Skip to content
Orcho Docs

Artifact Reference for Orcho Runs

Every run, regardless of outcome, lands in one directory:

<workspace>/runspace/runs/<run_id>/

run_id is the timestamp-shaped directory name (for example 20260629_1427). That filesystem layout is a contract: post-mortem tooling, the evidence slices, and the MCP surface all read the same files. Prefer the typed projections (orcho status, orcho evidence, MCP tools) first; read files directly for debugging and forensics.

The run directory

Section titled “The run directory”
<run_dir>/
├── meta.json                        # run state snapshot: status, profile,
│                                    # delivery gate, handoff state
├── events.jsonl                     # append-only event spine (source of truth)
├── metrics.json                     # token / duration / attempt rollups
├── evidence.json                    # composed v1 evidence bundle
├── evidence.md                      # readable rendering of evidence.json
├── checkpoints.db                   # phase log + agent sessions (SQLite)
├── parsed_plan.json                 # typed plan contract (when plan ran)
├── plan_<run_id>_r<N>.{md,json}     # per-round plan artifacts
├── diff.patch                       # captured run diff (the review subject)
├── output.log                       # raw stdout/stderr capture
├── runner.log                       # decolorized banner / phase log
├── progress.log                     # live-card snapshots
├── phase_handoff_decisions/         # one JSON per resolved handoff
├── verification_receipts/           # per-phase-round receipts: <phase>_round<N>.json
├── verification_env_receipts/       # env-assertion receipts: verify_env_<env>.json
├── verification_command_receipts/   # declared-command receipts: <command>.json
└── mcp_supervisor.json              # supervisor handle (only when spawned via MCP)

The physical git checkout is deliberately not inside the run directory. With worktree isolation enabled it lives at <workspace>/runspace/worktrees/<worktree_id>/checkout/, and meta.json records that path under worktree.path.

Cross-project runs add cross-level files: cross_plan.json / cross_plan.md at the run root, and per-alias <alias>/implementation_handoff.{json,md} (JSON canonical, .md a derived audit view).

Who writes what, when

Section titled “Who writes what, when”
FileWriter / timingContract
events.jsonlAppended live during the run.Never rewritten; the authority every other surface is projected from.
meta.jsonMutated in place by the pipeline; one out-of-band writer on halt.Cached snapshot of the stream; drift is detectable and repairable.
metrics.jsonUpdated at phase boundaries.Tokens in/out, cache fields, durations, per-phase and per-attempt splits.
evidence.jsonComposed near the end of the run.Schema-validated v1 bundle; evidence.md is its human rendering.
parsed_plan.jsonWritten when planning approves.The typed plan --from-run-plan reuses.
diff.patchCaptured from the run checkout.The retained delivery subject; validated before apply/commit.
phase_handoff_decisions/One file per operator decision.Durable, idempotent decision artifacts.
verification_* receiptsWritten when declared checks execute.Proof consumed by gates and final acceptance.
output.log / runner.log / progress.logStreamed during the run.Human-readable; not a parsing surface.

evidence.json top-level keys

Section titled “evidence.json top-level keys”

The v1 bundle always carries:

schema_version, run_id, run_dir, status, created_at, task, profile,
plan, phases, gates, commands, artifacts, metrics, errors,
prompt_render, raw_events_path

prompt_render is the durable prompt-render trace summary (empty list when a run produced no covered records); raw_events_path points back at events.jsonl so a bundle can always be re-derived from the spine.

Artifact kinds

Section titled “Artifact kinds”

Generated artifacts are classified on two axes — audience × persistence:

artifact_kindMeaning
internal_ephemeralEngine-facing, disposable (working logs, previews).
internal_durableEngine-facing, kept (parsed_plan.json, receipts).
external_ephemeralOperator-facing, disposable (preview renders).
external_durableOperator-facing, kept (evidence.json, diff.patch).

Each artifact.created event carries the file path and its artifact_kind, so an event consumer can locate files without guessing the directory layout.

What is conditional

Section titled “What is conditional”
  • parsed_plan.json and plan_* exist only when the profile ran a planning block; review-only shapes skip them.
  • diff.patch exists when the run produced changes to retain; a mock run rehearses the lifecycle without editing code.
  • verification_* receipt directories appear when declared checks actually executed; a missing receipt is itself meaningful (see Verification receipts).
  • mcp_supervisor.json exists only for MCP-spawned runs — its absence is what classifies a run inspect_only for MCP control.
  • Cross-level files exist only for run_kind = cross_project runs.

Deep reference

Section titled “Deep reference”

The canonical engineering doc lives with the code:

Section titled “Related”