2.0 KiB

Raw Blame History

Codex-Specific Monitoring (v2.4.0)

Purpose: Special handling for Codex CLI sessions in story-automator monitor-session

Agent Detection

Codex sessions are detected by:

AI_AGENT environment variable (most reliable)
Explicit Codex CLI identifiers: OpenAI Codex, codex exec, codex-cli, gpt-*-codex, tokens used

Session States for Codex

State	Meaning	Detection
`in_progress`	Codex actively working	Heartbeat alive OR output changed recently
`idle`	Session alive but no prompt yet	Heartbeat idle + output stale (pre-stuck window)
`completed`	CLI has exited	Prompt returned, pane exited, or `tokens used`
`stuck`	No recent output for too long	Output stale beyond threshold

Key Difference: For Codex, "idle" is NOT the same as "completed". The CLI may have stopped but the workflow might not have finished.

Output Freshness vs Completed Detection

output_fresh():   Output hash changed within CODEX_OUTPUT_STALE_SECONDS
codex_completed(): Prompt returned, pane exited, or "tokens used"

Priority: completed > active > idle > stuck

Output Staleness Window

CODEX_OUTPUT_STALE_SECONDS (default: 300) defines how long Codex can be silent before the session is considered stuck. Any output change refreshes the timer.

Code-Review Workflow Verification

For code-review with Codex, story-automator monitor-session verifies completion:

# Must pass --workflow and --story-key for verification
result=$("$scripts" monitor-session "$session" --json \
  --workflow review --story-key {story_id})

Verification checks:

Sprint-status.yaml shows "done" for story
OR story file Status field shows "done"
If neither → final_state: "incomplete"

Fake Todo Progress

Codex doesn't use TodoWrite, so story-automator tmux-status-check fakes progress:

Start: todos_total=1, todos_done=0
While running: Keep 0/1
On idle after activity: Set 1/1 (signals "done, needs verification")

2.0 KiB Raw Blame History