[dreveman]

Summary

This stack makes it possible to get an AgentProf trace in the three situations
users actually hit, without changing how existing manual recording works:

1. No trace yet — a new capture_an_agent_run AI workflow walks an agent
   (or user) through installing the right recording plugin, capturing one
   task, and verifying the artifact before analysis.
2. Just one prompt — /trace <prompt> in Pi and Claude Code records a
   single turn and prints the saved trace path.
3. Nobody at the keyboard — AGENTPROF_AUTO_TRACE=1 +
   AGENTPROF_TRACING_DIR=<folder> makes every harness session a script
   launches record start-to-finish into one attributable folder.

Changes

AI workflow: capture a run

• New capture_an_agent_run.md in the Perfetto skill overlay: consent and
  content-policy gates first, per-harness install + record + verify steps
  (Pi, Claude Code, Codex, Muse), then handoff to investigate_agent_run
  via inventory.sql. Routed in the skill router (patch 0009;
  0001–0008 only renumber).
• investigate_agent_run now points here when there is no recording yet.
• Fix: .gitignore's *.agentprof silently ignored new files under
  ai/skills/dev.agentprof/; added an exemption so future workflows show up
  in git status.

/trace <prompt> (Pi, Claude Code)

• Pi: starts the capture, submits the prompt with sendUserMessage, and
  publishes from agent_settled so child sessions are included, then prints
  the trace path. Refuses while already recording or busy.
• Claude: the mod intercepts the marker at turn.start (starting before the
  prompt is recorded, so the turn isn't marked partial), stores the prompt
  without the marker, and stops at turn.complete; the pending turn ID is
  checkpointed so a mod reload mid-turn still stops the recording. If a
  recording is already active the turn joins it.
• Codex and Muse have no host mechanism to run a submitted prompt under
  plugin control, so they keep tracing start/tracing stop (documented).

Always-on scripted capture (all four harnesses)

• AGENTPROF_AUTO_TRACE=1 records every top-level session that inherits the
  environment; =0 suppresses automatic capture for one launch and wins over
  the legacy switches (PI_TRACING, AGENTPROF_CODEX_AUTO_START,
  AGENTPROF_MUSE_AUTO_START, Claude auto_start).
• AGENTPROF_TRACING_DIR sets the default output folder for all recordings
  without an explicit path. Automatic files are named
  <harness>-<full-session-id>-<timestamp>-<unique>.pftrace; child sessions
  keep joining their parent's trace.
• Codex and Muse runtime bundles are regenerated.

Docs

• All four harness READMEs, the root README, and the capture workflow
  (including a "scripted or always-on capture" section recommending pairing
  with AGENTPROF_CAPTURE_CONTENTS=0 for scripted fleets).

Behavior notes

• Claude: the model receives the /trace prompt text as typed (the mod
  cannot rewrite a submitted prompt); only the stored prompt omits the marker.
• Pi trace filenames from startup recording now contain the full session ID;
  an order-dependent test assertion was fixed to pair capture/flow events
  within a single trace file.

Tests

• New tests per harness: Pi /trace driver test (one submission, published
  at settle, refusal while recording), Pi AGENTPROF_AUTO_TRACE config +
  end-to-end tests, two Claude /trace hook tests, Claude/Codex/Muse
  auto-trace tests including =0 suppression and tracing-dir relocation.
• Full Pi, Claude, Codex, and Muse suites pass with a locally built Trace
  Processor; plugin bundle --check (Codex, Muse, Claude) passes; skills
  overlay and SQL tests pass; license check and git diff --check clean
  (except two pre-existing trailing-whitespace lines inside the generated
  patch context).