debug-agent-session

Debug an agent's session

When a run looks wrong (stalled, gaming, no progress) and the score/population don't explain it, read the agent's own rollout, its full conversation and tool calls, to see why it did what it did. Local files only. run_root layout is in docs/using-eve.md.

Where the rollout session is

Each active solver worker runs in <run_root>/solver_workspaces/<workspace_id>/. The agent's own session record (JSONL, one event per line) lives there:

• Codex: <workspace_id>/.codex-driver-transcripts/<session>.jsonl (full rollout also under <workspace_id>/.codex-driver-home/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl)

A *-live.jsonl is an in-progress session; the non-live file is the completed snapshot. (Note: <run_root>/artifacts/<run-id>_solver/transcripts/ holds the optimization log trees, not the agent conversation, use the workspace JSONL for behavior.) To find the workspace for a suspect candidate, locate its ..._step_<n>_... directory under <run_root>/solver_workspaces/ (see ../inspect-population/SKILL.md); there is no DB column mapping an entry to its workspace path.

If the run has been resumed, failed post-checkpoint workspaces may have been moved to <run_root>/.resume_archive/resume_*/solver_workspaces/<workspace_id>/. Check active solver_workspaces/ first for the current logical run, then .resume_archive/ only when debugging the interrupted attempt itself.

What to look for

Read the JSONL for the agent's reasoning + tool calls. Common failure signatures, with the runner.log markers that flag them:

• Optimizer no-op (the guidance tree was not modified; no optimizer candidate will be produced): the optimizer agent isn't editing its guidance. Read its session to see whether it understood the task.
• Synced 0 optimizers (Phase 3: updated Elo for N optimizers and synced 0 Phase 2 optimizers): the optimizer side produces nothing; two in a row is a stop-and-flag signal (see ../supervise-run/SKILL.md).
• Family lock-in: optimizer_lineage.db shows only one optimizer entry_id reused across iterations (selection keeps picking the same one), exploration collapsed.
• Gaming the eval: the candidate scores high but its solver/ (via ../inspect-population/SKILL.md) games the metric instead of solving the task; the session often shows the agent reverse-engineering the evaluator.

Note

A mechanical halt (crash, killed process) is not an agent-behavior problem, recover it with ../resume-run/SKILL.md.