coding_cli_turn_signals

Coding CLI turn signals: where each fact comes from

Status: current as of 2026-09-27 (five original CLIs certified; AGY onboarding tested at the provider boundary). Detailed history: PLAT-354. Submit receipts: durable_ack_p0.md.

Rule

tmux remains the critical interactive transport. It launches the CLI, types input (so a user can steer a running turn), carries live stderr to the terminal panel, and gives the CLI its full interactive harness.

Every correctness fact comes from the CLI's own structured record: was the message taken in, is the turn finished, what is the final answer. That record is JSONL or SQLite. This is P0. Reading the pane is P1: a fast early hint, overridden by the record. The only exceptions are screens that have no record at all (trust/login prompts, a draft stuck in the input box).

Do not fix a delivery or completion bug by parsing more pane text. Find the structured signal instead.

Per CLI

CLI	Record	Taken in	Finished	Final answer
Claude Code	transcript JSONL (~/.claude/projects/…)	user row for this prompt	end_turn, and the turn_duration row's pendingBackgroundAgentCount is 0	last assistant text of the turn
Codex	rollout JSONL	user message in the rollout	turn.completed / task complete	last agent message
Muse	session.jsonl	runtime.user_intent.accepted	run terminal; with subagents, follow the chain below	assistant message of the final run
Cursor	store.db (SQLite)	user row for this query	the turn's rows end in assistant prose (a trailing tool call = still running; a trailing tool result = reply pending)	that prose
Pi	markers.jsonl + session	intake marker	agent_settled (fallback: agent_end + 15 s quiet)	last assistant message
AGY	conversation SQLite (~/.gemini/antigravity-cli/conversations/<id>.db)	matching type-14 user step after the pre-submit index	a status-3 type-15 assistant step with text at the end of the turn's trail, stable for 2 s, with the composer ready	type-15 field 20.1 text after that user step

AGY 1.2.12 has no distinct run-terminal row in the observed conversation record. Its SQLite trail is the primary intake and answer proof for normal and retained turns; tmux composer readiness remains a secondary completion guard so narration before a tool does not end the turn. A trailing tool step keeps the turn open. Retained progress also reads new assistant SQLite steps with a cursor, without replaying old text. This contract is covered by the persistent MCP bridge live test with a 25-second tool. For live input, the server's second receipt comes from a new exact-match user step after the pre-send SQLite index; repeated identical sends need distinct rows. TestAgyCLIRealDurableAckContract passed on two retained turns.

Messages sent during a running turn (steering)

The user can type while a turn runs. Each CLI records it differently:

• Claude Code: queue-operation enqueue/remove rows, plus a queued_command attachment.
• Cursor: a later user row inside the same turn. The reader keeps it in the same turn, so the answer is the turn's last prose, not a reply to the steer alone.
• Muse, Codex, Pi: a new intake record for that message.

Background subagents

With Native agent tools on, a CLI may start background subagents and write an interim reply ("waiting for the subagents"). That reply is not the answer:

• Claude Code: the turn is not done until pendingBackgroundAgentCount is 0.
• Muse: spawn_accepted → inbox_item_queued (matched by source_run_record_id) → the run that drains it → that run's terminal. The answer comes from the last run. If the log stops growing for 5 minutes, the adapter stops waiting.

Environment gotcha (Claude Code)

A Claude CLI started from inside another Claude session inherits variables that turn its transcript saving off. With no transcript, no delivery can be proven. The adapter clears them for both the tmux launch and the structured command: CLAUDECODE, CLAUDE_CODE_CHILD_SESSION, CLAUDE_CODE_SESSION_ID, CLAUDE_CODE_MESSAGING_SOCKET, CLAUDE_CODE_MESSAGING_TOKEN, CLAUDE_CODE_SESSION_ATTENDED.

Certification

Certified versions are in scripts/p0-certified-cli-versions.json; the gate script is scripts/run-coding-cli-p0.sh, which needs MCP_API_TOKEN and WORKSPACE_API_TOKEN. Run it for one provider at a time (--providers <name>), not all providers, unless asked. Opt-in stress tests (-coding-cli-stress, count set by CODING_CLI_STRESS_ITERATIONS) run parallel subagents, a slow MCP tool and a mid-turn steer. Results on 2026-09-24: Claude 3/3, Codex 3/3, Muse 3/3, Cursor 5/5.

Known, accepted issues (reopen only if they recur or get worse): an intermittent Claude StructuredCompletionP0 failure, an occasional Muse IC-11 retained-shell-start timeout, and one unreproduced Pi empty retry after cancel.