Skip to content
Luotsi Luotsi

Replay And Artifacts

Artifacts are part of the Luotsi contract. Commands, scenario runs, inspect sessions, and live view all write into an artifact root so the result can be explained after the fact.

Use artifacts list when you need to rediscover a recent run id or temp-root artifact directory before you choose between the generic artifact browser and the replay-specific front door.

What typically lands in an artifact root

Section titled “What typically lands in an artifact root”
  • Screenshots and recordings
  • UI hierarchy and screen-state captures
  • Telemetry and log snapshots
  • session-timeline.jsonl and session-replay.json
  • Report outputs such as JSON, JSONL, JUnit, or replay summaries

Core replay commands

Section titled “Core replay commands”
Terminal window
luotsi artifacts list --artifacts ./artifacts
luotsi artifacts info ./artifacts/my-run
luotsi replay packet --artifacts ./artifacts/my-run
luotsi replay packet --artifacts ./artifacts/my-run --check
luotsi replay packet --last --artifacts ./artifacts
luotsi replay packet --last --artifacts ./artifacts --check
luotsi replay open --artifacts ./artifacts/my-run --dry-run
luotsi replay open --last --artifacts ./artifacts --dry-run
luotsi artifacts open ./artifacts/my-run
luotsi artifacts open --last --artifacts ./artifacts
luotsi artifacts pack ./artifacts/my-run --output my-run.zip --dry-run
luotsi artifacts pack ./artifacts/my-run --output my-run.zip
luotsi artifacts pack ./artifacts/my-run --output my-run-lab-safe.zip --redact lab-safe
luotsi artifacts verify my-run-lab-safe.zip --require-lab-safe --sha256 <digest>
luotsi artifacts info my-run-lab-safe.zip
luotsi artifacts intake my-run-lab-safe.zip --output ./artifacts/my-run --require-lab-safe --write-json --write-readme --sha256 <digest>
luotsi artifacts unpack my-run-lab-safe.zip --output ./artifacts/my-run --require-lab-safe --sha256 <digest>
luotsi replay summarize --artifacts ./artifacts/my-run
luotsi replay open --artifacts ./artifacts/my-run --dry-run --write-json --write-markdown
luotsi replay capsule --artifacts ./artifacts/my-run --write-readme --write-json
luotsi replay timeline --artifacts ./artifacts/my-run --failures
luotsi replay timeline --artifacts ./artifacts/my-run --source-path session-timeline.jsonl --sequence 1
luotsi replay scrub --artifacts ./artifacts/my-run --failures --context 3 --write-markdown
luotsi replay search --artifacts ./artifacts/my-run --contains "timeout"

What each command is for

Section titled “What each command is for”
  • artifacts list: recent artifact-root discovery when you only have a temp root or run id
  • artifacts info: non-mutating summary of one artifact root or package zip before you open, pack, share, or unpack it
  • artifacts open: generic artifact browser and index refresh when you do not need replay-specific recommendations yet
  • artifacts pack: zip an artifact root for sharing, upload, or CI handoff
  • artifacts verify: validate a received package manifest, SHA-256, redaction status, and exact unpack/replay/capsule commands without writing files; add --sha256 <digest> to require expected package bytes and --require-lab-safe when CI or support must reject unredacted packages before unpacking
  • artifacts intake: validate, restore, optionally persist intake JSON/Markdown, refresh the index, and return info/open/replay/capsule commands for a received package in one step
  • replay summarize: condensed session-level overview with commands into capsule, open, scrub, graph, and clustering
  • replay timeline: ordered timeline events with type, timestamps, detail text, filters, and follow-up commands when failures are selected
  • replay scrub: local previous/focused/next event view with exact commands to move through replay evidence, open the capsule, search, or graph the focused failure
  • replay search: text search across timelines and text-like artifacts with follow-up commands when matches are replay-relevant
  • replay packet: write run-summary.json and run-summary.md, return the luotsi-run-summary.v1 packet with status, failure snapshot, focused evidence files, recommended next action, 60-second checklist, and follow-up commands, and stay non-interactive for CI and agents; use --human when a terminal reader needs the same first-minute triage path inline, use --check to validate an existing packet without rewriting artifacts and return the same next action/evidence/checklist handoff for continuation, and use --last when the agent only has a search root
  • replay open: browser-free replay front door for one artifact root when a human wants session counts, primary failure, recommended next action, and follow-up commands before raw artifact browsing; it opens the browser only when --dry-run is not supplied. Use replay packet to persist and validate run-summary.json and run-summary.md as the stable production investigation packet.
  • replay capsule: replay capsule is the shareable CI-triage summary after the replay front door, with primary failure reopen command, failure timeline with exact reopen commands, restored package intake audit when present, existing scenario draft artifacts and summary counts, ready draft run handoff, artifact manifest, and suggested next commands
  • replay scenario-draft: turn inspect or replay actions into a conservative starter scenario

artifacts pack writes luotsi-artifact-package.json into the zip with the run id, created timestamp, category counts, and recommended reopen commands. By default, the package is an exact copy. --redact lab-safe redacts obvious secrets from text-like zip entries, leaves source artifacts and binary media unchanged, and records redaction counts in the manifest. Successful pack results recommend unpacking with --sha256. Lab-safe packages also carry --require-lab-safe into handoff commands.

artifacts verify validates the manifest and archive entries without extracting the package. It reports SHA-256 plus share_safety and returns exact unpack/replay/capsule commands. With --sha256 <digest>, checksum mismatches fail before restore; with --require-lab-safe, unredacted packages return status: blocked, blockers, repair commands, and exit code 1 before unpacking.

artifacts info <package.zip> offers the same non-mutating package intake through the existing info workflow.

artifacts unpack requires that manifest and rejects --require-lab-safe failures and --sha256 mismatches before writing files. It reports the manifest back in the result. Both pack and unpack support --dry-run when you want to validate the handoff without writing files yet.

artifacts intake wraps that safe restore for received packages, returning status, share_safety, checksum verification, and exact info/open/replay/capsule commands. Add --write-json --write-readme to leave schema-backed artifact-intake-summary.json and artifact-intake.md in the restored root, or --open to launch the refreshed index after a successful restore. replay capsule surfaces those intake files plus compact status/share-safety/SHA verification fields when reopening a restored bundle.

Newer semantic triage helpers

Section titled “Newer semantic triage helpers”
Terminal window
luotsi replay graph --artifacts ./artifacts/my-run
luotsi replay cluster --artifacts ./artifacts/my-run

Use replay graph when you want a stable node or edge model across sessions, failures, artifacts, actions, telemetry signals, and generated scenario draft provenance. Use replay cluster when you need repeated failure shapes grouped into triage buckets.

The public distinction that matters is:

  • replay packet is the canonical first stop for failed CI, reviews, and agent loops because it writes and returns the durable investigation packet without launching a browser
  • run-summary.json and run-summary.md are the stable packet files to attach after replay packet; the Markdown starts with an At a Glance summary, failure snapshot, focused evidence files, packet gate, copy-paste triage commands, and the 60-second checklist, and the source contract is documented in docs/schemas/luotsi-run-summary-v1.md
  • replay packet --human and replay packet --check --human include a copy_paste block that starts with the packet validation gate command before the first-minute triage commands
  • replay open is the browser-free replay front door when a human also wants one artifact root summarized before opening the local index
  • replay capsule is the deeper operator and CI handoff after the packet/front door
  • replay graph is the agent- and debugger-facing node/edge model for that same root
  • replay cluster is the cross-run grouping view when the same failure shape keeps returning in CI

replay graph returns a queryable graph for one artifact root with query, agent_summary, taxonomy, total_node_count, matched_node_count, node_kinds, edge_kinds, insights, actions, evidence, facts, causal_chains, hypotheses, optional artifact paths, and the returned nodes and edges arrays. The promoted node kinds that matter most in practice are failure, action, selector, screen_state, telemetry_signal, scenario_draft, and generated_step. Use --failed, --node-kind, --edge-kind, --action, --selector, --contains, --insight, --severity, --evidence, --fact, or --node <id> --depth <n> to narrow the view. Graph actions start with replay packet and replay packet --check, then include replay open so semantic context can route back to the browser-free replay front door after the packet/check loop.

replay cluster works one level up. Point it at a directory of replayable artifact roots when you need Luotsi to group failed sessions by normalized failure shape and return triage hints plus the next replay/search commands for the best representative bundle.

Explore to scenario

Section titled “Explore to scenario”

replay scenario-draft is intentionally conservative. It promotes replay evidence into a starter scenario and keeps review data next to the generated steps:

  • review_items is the short human checklist for selectors, telemetry, visual assertions, low-confidence provenance, and normalizations.
  • next_actions is the ordered authoring handoff for reviewing, validating, auditing persisted provenance, and reopening the first source event.
  • validation appears when --validate is used with --output or --file; it records static validation status without running a device scenario.
  • package_provenance appears when trusted timeline evidence names the app package; the draft scenario metadata and ready handoff commands use that package.
  • device_provenance appears when replay metadata has one trusted adb target; the draft scenario metadata and ready handoff commands use that serial.
  • run_handoff records whether the draft is ready for a non-device run plan. Validated drafts include run --path <draft> --dry-run, app preflight, direct run, and, when trusted package plus concrete device serial are available, a claimed run with --claim-device --claim-wait-sec 60. Blocked drafts explain what must be fixed first.
  • source_summaries shows how many steps came from inspect commands, screen deltas, view events, telemetry, or existing scenario events.
  • step_origins maps every generated step back to its source event, timeline file, sequence, timestamp, confidence, and an exact replay timeline command.
  • normalizations records stabilization and cleanup decisions such as inserting waits before generated taps or dropping adjacent duplicate inferred waits.
Terminal window
luotsi replay scenario-draft --artifacts ./artifacts/my-inspect --output ./scenarios/draft.json --validate --write-json --write-markdown

Use the generated markdown review before committing a draft. Coordinate taps and visual assertions are especially device-specific and should be tightened before CI use.

When you persist draft review artifacts, Luotsi currently writes:

  • scenario-draft-summary.json for machine-readable counts, warnings, package provenance when available, validation status when requested, review items, and provenance summary
  • scenario-draft.md for the human review checklist, optional package provenance, validation status, run handoff, origins, normalizations, and emitted draft steps

Practical workflow

Section titled “Practical workflow”
  1. Run the command or scenario with an explicit artifact root if you want a stable location.
  2. Use artifacts list if you need to rediscover the run id or exact artifact root, then use replay packet --last to write the durable first-minute packet, replay packet --last --check to validate a received packet, replay open --last when a human wants the replay-specific front door response, artifacts info for a non-mutating root or package summary, and artifacts open --last only when you specifically need the latest generic browser.
  3. Use replay summarize to confirm what happened at the session level.
  4. Move to replay timeline or replay search to narrow the failure window.
  5. Use replay graph when you need promoted selectors/actions/telemetry, facts, causal chains, or hypotheses; use replay cluster when the question is whether the same failure shape is repeating across runs.

MVP contract

Section titled “MVP contract”

This workflow is the first stable slice of Luotsi’s replay plan. It is intentionally narrower than a full semantic debugger, but it should be enough for a developer or CI job to preserve a failure, reopen it, and turn useful exploration evidence into a reviewed scenario draft.

Unified session timeline

Section titled “Unified session timeline”

Every replayable session should preserve ordered timeline evidence in session-timeline.jsonl. Consumers can depend on:

  • replay timeline returning stable path, sequence, timestamp, type, is_failure, detail, and scalar properties fields.
  • --source-path plus --sequence reopening the exact event referenced by another replay artifact.
  • --context expanding a filtered result with neighboring events so a triage note can show what happened immediately before and after the failure.
  • --format json|jsonl providing raw replay output when a script does not want the normal command envelope.

Timeline events are still evidence, not assertions. They preserve what Luotsi observed so replay, draft generation, and future semantic graph work can build on the same substrate.

Failure replay capsule

Section titled “Failure replay capsule”

replay capsule is the shareable CI-triage summary after the replay front door. A credible capsule includes:

  • primary_failure with an exact source_command that reopens the failing event.
  • failure_timeline entries with their own exact replay timeline commands.
  • artifact_manifest and artifact_counts for screenshots, videos, logs, reports, timelines, and generated replay files.
  • scenario_draft_artifacts and scenario_draft_summary when a draft has already been generated, including package/device provenance, validation status, run handoff, and bounded previews of warnings, next actions, and review items.
  • suggested_commands that lead the operator from summary to timeline, scrub, search, open, graph, or scenario draft without guessing paths.
  • recommended_next_steps that rank ready draft dry-run, preflight, claimed-run, and direct-run handoff commands first when available, then other persisted draft actions, scrub, graph, search, cluster, open, and draft-generation actions for the current bundle.

Use --write-readme --write-json for shareable artifacts. That writes replay-capsule.md for humans and replay-capsule-summary.json for automation, then refreshes the artifact index.

Explore to scenario

Section titled “Explore to scenario”

replay scenario-draft is the first Explore-to-Scenario slice. It only promotes evidence that can be traced back to timeline events, and it keeps uncertainty visible:

  • The generated scenario JSON is meant to be validated and edited, not blindly committed.
  • scenario-draft-summary.json gives confidence, warnings, package/device provenance when available, validation status when requested, run handoff status including claimed-run command when concrete, review items, next actions, normalization notes, and generated step context.
  • scenario-draft.md lists package/device provenance, validation, and run handoff status including claimed-run command when concrete, plus recommended next actions, review items, source summaries, normalizations, step origins, and the draft steps.
  • step_origins and normalizations include source_path, sequence, timestamp, and source_command so every generated step and inserted pre-tap wait can be audited with replay timeline.

This is enough for the near-term authoring loop: explore a flow, generate a draft, review selectors and coordinates, validate it, plan it with run --path <draft> --dry-run, then harden it into a scenario.

CI triage recipe

Section titled “CI triage recipe”
Terminal window
luotsi replay packet --artifacts ./artifacts/failing-run
luotsi replay packet --artifacts ./artifacts/failing-run --check
luotsi replay open --artifacts ./artifacts/failing-run --dry-run
luotsi replay capsule --artifacts ./artifacts/failing-run --write-readme --write-json
luotsi replay timeline --artifacts ./artifacts/failing-run --failures --context 3 --write-markdown
luotsi replay scrub --artifacts ./artifacts/failing-run --failures --context 3 --write-markdown
luotsi replay scenario-draft --artifacts ./artifacts/failing-run --output ./scenarios/recovered-draft.json --validate --write-json --write-markdown
Section titled “Related pages”