debug-agent-session

name	debug-agent-session
description	Use when an Eve agent is behaving wrong (stuck, gaming the score, bad reasoning) and you need to read its own rollout to find out why

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.