Run traces and observability

Use this page when you need to prove what happened in a Guild Stack run. You can find the run, inspect the start manifest, follow the canonical trace, read the handoff and review receipts, check verification, open a local dashboard view, and diagnose a failure without treating the agent’s final message as the source of truth.

Try it: /guild:stats prints the usage and telemetry dashboard from your recorded runs. It is read-only over telemetry.

Run ledger

map / active

Trace, receipts, gates, close record

Start

run.yamlresolved-settings.json

Trace

v1.4-events.jsonlhandoffs/review/

Gate

review verdictverify.md

Close

provenance.jsonstats · dashboard · MCP

Traceable-run proof panel

Start with the directory, not the prose summary:

Run directory

.guild/runs/<run-id>/

1. run.yaml Start manifest: command, resolved host, model-tier policy, phase log.
2. provenance.json Close record: gate outcomes, retention class, touched facts.
3. logs/v1.4-events.jsonl The canonical trace stream, one JSON event per line.
4. logs/payloads/<span-id>.json Redacted payload sidecar, only when a redacted body is needed.
5. handoffs/ Per-specialist handoff receipts.
6. review/<gate>/ Review packets, results, and trail for each gate.
7. verify.md Verification result against the run summary.
8. quality/ Release-readiness verdict, when Quality runs.
9. ops/ Runbook class, rails, and outcome, when Operations runs.

Proof surface	Audit asks	What to look for
Start manifest	What was requested, where, and under which host policy?	run.yaml keys such as command, resolved arguments, working directory, resolved host, model-tier policy, initiative attachment, run class, and phase log.
Canonical trace	Which steps actually ran?	logs/v1.4-events.jsonl, one JSON event per line, including phase, dispatch, receipt, loop, tool, hook, gate, assumption, escalation, and review-round events.
Receipts	Which specialist produced which evidence?	handoffs/, review/gate/packet-*.md, review/gate/result-*.json, verify.md, quality/, and ops/.
Close record	What did the run touch, and can it be retained or benchmarked?	provenance.json, including gate outcomes, retention class, benchmark eligibility, and touched facts.
Read-only projection	How can a person or tool inspect the run later?	/guild:stats, /guild:dashboard, and the guild-telemetry MCP tools.

Even read-only commands record lightly: /guild:status runs as a lightweight run by default, writing only the run-lifecycle records and the terminal trace line. It does not write wiki pages, indexes, or reflections.

1. Trace

logs/v1.4-events.jsonl is the plugin-to-benchmark contract boundary. The plugin writes it, and the benchmark imports it by format. The frozen v1.4 event vocabulary records phase, dispatch, receipt, loop, tool, hook, gate, assumption, escalation, and review-round events.

guild.trace_event.v1 records run start and close markers. Additive .v2 fields add span IDs, parent spans, tier, model, payload pointers, and token/cost fields on LLM-call events without breaking v1 readers.

Guild Stack also emits six structured trace families into the same JSONL file:

Structured event	What it records
guild.trace.dispatch.v1	Specialist or lane dispatch plus backend.
guild.trace.recall.v1	A recall invocation result.
guild.trace.recall_decision.v1	Whether recall was good enough or a read-through/full-file path was needed.
guild.trace.config_resolution.v1	Completed settings resolution.
guild.trace.security_decision.v1	A capability-scope or recall-protection security decision.
guild.trace.degradation.v1	Host-capability degradation or fallback.

Trace writing is behavior-neutral: emitters validate and append, but trace I/O errors do not change the workflow result. New consumers should read logs/v1.4-events.jsonl; events.ndjson is a legacy compatibility mirror.

2. Receipts and gates

Receipts are the bridge between the run trace and the human audit trail. They keep the work inspectable when a run spans specialists, review rounds, quality checks, or operations.

Receipt	Path	Why it matters
Handoff receipt	.guild/runs/run-id/handoffs/	Shows the specialist’s scoped output and the evidence consumed by review and verification.
Review packet	.guild/runs/run-id/review/gate/packet-round.md	Freezes the artifact, scope, round, and hash that the reviewer must evaluate.
Review result	.guild/runs/run-id/review/gate/result-round.json	Carries the structured verdict and blocking findings.
Verification result	.guild/runs/run-id/verify.md	Records pass/fail against the run summary and expected evidence.
Quality record	.guild/runs/run-id/quality/run-id.md	Records the release-readiness verdict and selected harness evidence when Quality runs.
Operations record	.guild/runs/run-id/ops/run-id.md	Records the runbook class, dry-run, rails, and release/incident/rollback evidence when Operations runs.

The close record, provenance.json, bookends those receipts with guild.provenance.v1: gate outcomes, retention class, benchmark eligibility, and the touched fact block for tasks, agents, skills, decisions, features, files, and linked runs.

3. Dashboard and read-only queries

For a visual take on the same data, /guild:dashboard launches the benchmark repo’s local web UI against the live project. This is the telemetry split in practice: the plugin records and launches; the benchmark analyzes and renders. See Dashboard.

/guild:dashboard launches the benchmark web UI against the live project’s recorded runs. The former host-neutral guild.dashboard.v1 projector was retired because it was not wired to the command and exposed different semantics from the benchmark-backed surface.

The guild-telemetry MCP server gives agents and host MCP tooling structured, read-only query access over .guild/runs/:

Tool	What it answers
trace_list_runs	Which runs exist. Use this to discover run IDs first.
trace_summary	A compact summary of one run: phases, gates, outcome.
trace_query	Filtered event queries within a run’s trace.
trace_cost_rollup	Token usage and cost aggregated by tier, model, and specialist.

The intended flow is trace_list_runs, then trace_summary, then trace_query or trace_cost_rollup. The server is read-only by contract: it declares no write paths and no network access.

/guild:stats is the terminal counterpart: task counts, completion rate, flip counts, top skills, top-requested specialists, and the open reflection backlog. Two flags control its optional read-through cache:

Flag	Effect
--rebuild-index	Drops and rebuilds the optional cache.
--no-index	Forces a one-shot filesystem scan, bypassing the cache entirely.

The filesystem is always canonical. The cache is a rebuildable projection, and deleting it loses nothing.

4. Export and privacy

Raw traces and payload sidecars stay local by default. Sanitized export is a separate path, not something attached to issues or commits automatically. See Security & Permissions.

Payload sidecars live at logs/payloads/span-id.json only when a redacted body is needed. They preserve field names while masking secrets, keeping large or sensitive bodies out of the streamable JSONL log.

Replay-style tools that reconstruct a run’s timeline or a specialist’s exact context are specified but planned, not shipped. The trace contract is frozen so those tools can land later without a schema break.

5. Diagnosis

The trace is also the input to diagnosis. /guild:fix reads a failed run’s trace summary, inspects the context bundle and tool timeline, classifies the failure, and produces a fix plan.

The design taxonomy is bad context, bad plan, bad routing, bad skill, bad tool policy, or bad validation. The shipped diagnose skill reports concrete evidence-driven categories such as telemetry-scope, hook-registration, audit-log-gap, loop-telemetry-gap, agent-team-stall, codex-review-gap, verification-failure, or unknown.

Applying any fix requires your explicit approval. Diagnosis can point at a repair path; it does not auto-edit the project.

Multi-wave programs

Current resume behavior reads shipped on-disk lane state: runDir/run-state.json and runDir/lanes/lane/resume.json. The v2 contract also reserves a program-level manifest for long, multi-wave work:

Artifact	Scope	Status
.guild/runs/run-id/run-state.json	One run’s lane liveness.	Shipped.
.guild/runs/run-id/lanes/lane/resume.json	One lane’s resume checkpoint.	Shipped.
.guild/programs/slug/manifest.json	Program-level, across many runs.	Written as forward-prep; /guild:resume consumption is dormant.
.guild/runs/run-id/run.yaml	One wave/run.	Shipped.

The program manifest schema is guild.run_manifest.v1. It is present for future program-level resume, but today’s /guild:resume re-enters dead lanes from the run-local resume files.

Source-backed boundaries

Guild Stack observability is local-first and filesystem-canonical. The plugin records run.yaml, provenance.json, trace JSONL, payload sidecars, handoff receipts, verification, and summary files. The benchmark analyzes those run artifacts by format and never imports plugin code. SQLite and dashboard projections are rebuildable read-through views, not a second source of truth.

See also

• Dashboard - the local UI over the same run records.
• Security & Permissions - the sibling security-event log and redaction rules.
• Agent Communications - the handoff receipts that land under handoffs/.
• Cost & Tiering - how the tiers in trace_cost_rollup are assigned.
• Command Reference - /guild:stats, /guild:status, and /guild:fix syntax.