# Trace Artifacts

Every run writes to `.seed-agent/runs/<run_id>/`. Reusable professor guidance is
stored across runs under `.seed-agent/memory/`.

- `.seed-agent/memory/MEMORY.md`: human-readable index of reusable professor
  memory.
- `.seed-agent/memory/items/<memory_id>.json`: source, kind, why, and
  how-to-apply fields for a durable professor memory item.

- `run.json`: versioned run metadata, state revision, status, model, goal, artifacts.
- `tasks.json`: versioned explicit task board owned by `lab-representative`.
- `events.jsonl`: append-only lifecycle timeline.
- `agent_calls.jsonl`: child-session calls and delegation records.
- `model_calls.jsonl`: append-only model attempt records derived from
  delegation/follow-up calls, including fallback status, resolved model,
  prompt artifact ref, and sanitized result/error summaries.
- `budget.json`: run safety budget state: elapsed-runtime limit, child session
  limit, model-call limit, warning threshold, stale-worker threshold, observed
  child sessions, model calls, token usage when OpenCode exposes it, and
  context injection counters.
- `background_tasks.json`: long-running background process/session status and checkpoints.
- `background_notifications.json`: durable parent-session notices for completed, failed, or cancelled background work.
- `team/runtime.json`: durable team member/status state, dynamic team id/name,
  launch status, member session ids, background ids, prompt refs, and cleanup
  instructions for partial launch failures.
- `team/specs/<team_id>.json`: accepted dynamic team spec contract before
  launch.
- `team/specs/<team_id>.md`: human-readable rendering of the accepted dynamic
  team spec.
- `team/tasks.json`: shared team task board with ownership, dependencies, revisions, and stale-update conflict records.
- `team/inbox/<member>/*.json`: durable per-member team messages and acknowledgement state.
- `threads/threads.json`: canonical agent-thread records. Each dynamic member
  is represented as a durable thread with session/background ids, prompt refs,
  tool/skill/MCP policy, helper budget, helper counts, and memory refs.
- `threads/<thread_id>/tool-manifest.json`: exact tool/skill/MCP/read/write
  manifest assigned to that thread.
- `threads/<thread_id>/helpers.jsonl`: append-only helper child-session ledger
  owned by that thread.
- `messages/envelopes.json`: durable agent-to-agent message envelopes with
  `from`, `to`, body/prompt refs, correlation ids, allowed tools/skills, target
  session ids, context refs/attachments, delivery status, retries, and errors.
- `messages/delivery.jsonl`: append-only delivery attempts for live
  `promptAsync`, mailbox-only, retry, and failure outcomes.
- `team/conversation.jsonl`: ordered team communication audit log with explicit
  `from`/`to`, launch/follow-up entries, prompt refs, child session ids,
  background ids, allowed/denied tools, and the OpenCode `session_tools` map
  sent to member sessions when available.
- `workspace/intents.json`: declared read/write/append intentions before lease
  acquisition.
- `workspace/leases.json`: active, blocked, and released workspace leases.
- `workspace/conflicts.json`: open/resolved lease overlaps and stale base-hash
  conflicts that can block final completion.
- `workspace/diffs.json`: recorded changed-path summaries used as write
  evidence for sub-plan verification and final completion gates.
- `workspace/merges.json`: worktree merge records that tie an isolated
  worktree diff to the accepted main-workspace diff under a main-workspace
  write lease.
- `context/bundles.json`: index of cache-aware context bundles with category,
  scope, owner, digest, body ref, byte length, and SHA-256.
- `context/bodies/<bundle_id>.md`: stored context body for stable contracts,
  warm summaries, hot deltas, heavy artifact refs, or memory checkpoints.
- `context/metrics.jsonl`: append-only context planning/render metrics used by
  `seed_context_metrics` and budget context counters.
- `continuation/context.json`: machine-readable continuation snapshot for
  resume, compaction, pending decisions, prioritized next actions, open
  sub-plans, budget warnings, stale background work, professor memory refs,
  terminal background work, and pending background notifications.
- `continuation/context.md`: compact continuation context injected into future
  turns when enabled.
- `meetings/state.json`: durable manual Lab Meeting state after
  `/seed-lab-meeting` is used.
- `meetings/<meeting_id>.json`: machine-readable Lab Meeting feedback-gate
  summary.
- `meetings/<meeting_id>.md`: professor-facing Lab Meeting summary and
  feedback options.
- `tool_calls.jsonl`: tool/MCP/command audit records.
- `evidence.md`: human-readable evidence ledger with stable anchors.
- `progress.md`: live professor-facing status.
- `final_report.md`: final professor-facing report.
- `activity/README.md`: index for the human-readable activity journal.
- `activity/latest.md`: latest Lab-Representative briefing for quick
  inspection.
- `activity/latest.json`: machine-readable latest RepresentativeBriefing.
- `activity/<10-minute-window>.md`: synthesized professor-facing briefing for
  the configurable time bucket. The default bucket size is 10 minutes.
- `activity/<10-minute-window>.json`: machine-readable RepresentativeBriefing
  for that bucket.
- `activity/raw/<10-minute-window>.md`: raw chronological sanitized event,
  agent-call, and tool-call summaries for audit/debugging.
- `artifacts/`: command output, prompts, exported material, and generated
  summaries such as `run-telemetry.json`, `report-gate.json`, and
  `policy-audit.json`.
- `artifacts/documents/<document_id>/metadata.json`: local PDF provenance,
  byte size, SHA-256, trust classification, and resolved source path.
- `artifacts/documents/<document_id>/extractor.json`: `pdftotext` binary path,
  flavor, version, OS details, normalization flags, page/chunk counts,
  warnings, and confidence.
- `artifacts/documents/<document_id>/text.txt`: normalized extracted PDF text.
- `artifacts/documents/<document_id>/pages.jsonl`: page-level untrusted text
  records.
- `artifacts/documents/<document_id>/chunks.jsonl`: chunk-level citation
  records for document/PDF analysis.

For tiny smoke tasks, the Lab-Representative can complete the work directly
after recording the reason with `seed_orchestrator_record_decision` and, for
native write/bash work in coordinator mode, `seed_coordinator_direct_work`.
That is why `agent_calls.jsonl` can be empty and `team/runtime.json` can list
only the lead member. A real dynamic team launch is visible in
`agent_calls.jsonl`, `team/runtime.json`, `team/launch-ledger.jsonl`, and
`team/conversation.jsonl`. Use `seed_team_conversation` for a readable timeline;
its timeline lines include `from -> to`, prompt refs, agent-call/session ids,
and `session_tools:<tool>=on/off` when the tool map was part of the launch or
follow-up.
- `artifacts/documents/<document_id>/extraction-report.md`: professor-facing
  extraction summary and trust-boundary warning.
- `artifacts/index.json`: versioned artifact index with relative paths, file
  metadata, and timestamps for generated run artifacts, including accepted
  team specs outside the `artifacts/` folder.

JSON and JSONL are the source of truth. Markdown is derived professor-facing material.
The activity journal is event-driven: it appends to a raw current time bucket
when SEED observes command, message, tool, delegation, evidence, team,
background, or continuation activity, then regenerates the current
Lab-Representative briefing from the trace, team state, workspace state,
artifacts, and blockers. It does not claim to expose hidden model reasoning.
Mailbox live-delivery attempts are recorded as events such as
`team_member_woken` or `team_member_wake_failed`; mailbox-only delivery remains
visible through the inbox files and unread counts in team status. Message
transform injection is derived from `team/runtime.json`, `team/tasks.json`, and
`team/inbox/` and does not create a second source of truth.
Lab Meetings are manual professor feedback gates. `/seed-lab-meeting` writes the
meeting state, asks active background workers to finish their already-assigned
background sessions, waits for those sessions to become terminal, and blocks new
delegation, team launch, and write/append workspace leases while the meeting is
wrapping up or awaiting feedback. Professor feedback is recorded through the
next normal Lab-Representative chat message, not a separate resume command.
`run.json`, `active-run.json`, task records, and `artifacts/index.json` include
schema versions. `run.json` and `active-run.json` also include
`state_revision`, which increments through the SEED mutation helper on
high-value state updates. JSONL trace appends are file-lock serialized. Legacy
v0 run/task state is migrated to the current schema when the harness reads it.
Older run artifact folders without an index are indexed on read so generated
outputs remain discoverable.

## Black-Box Fixture

`npm run e2e:blackbox` runs the fixture definitions in `evals/black-box/`
through SEED's public tool and command surfaces with an OpenCode-like host
client. The basic fixture verifies `final_report.md`, JSONL trace, the activity
journal, `artifacts/index.json`, and a captured host/tool transcript together.
The document/PDF fixture additionally drives `seed_team_create` with an
explicit inline spec, `seed_document_extract`, workspace leases,
representative briefings, `model_calls.jsonl`, and
`/seed-lab-meeting` plus normal professor feedback chat.
The Claude runtime UX fixture exercises the full professor-facing loop:
dynamic planner/implementer/verifier members, `team/launch-ledger.jsonl`,
`team/conversation.jsonl`, required sub-plan rework and acceptance, native
write-hook denial outside a member lease, duplicate-safe idempotency records,
stale team-task conflict handling, Lab Meeting feedback, budget state, and
untrusted document-evidence envelopes.
It is an example fixture for the generic dynamic-team path, not a built-in
paper-specific product mode.
Set `SEED_BLACK_BOX_E2E_KEEP=1` to preserve the temporary target repository and
transcript for manual inspection. Set `SEED_BLACK_BOX_E2E_OUT=<dir>` to write
partial JSONL progress and a final `black-box-results.json` collector report
that can be compared with the previous run in the same directory.
