AgentTUI: separate pane reachability from Codex turn activity and expose actionable delivery outcomes

[Yangtze-Seventh]

Context

Follow-up to #12.

The queue-vs-submit rule adopted there is directionally correct, but downstream dogfood exposed a second state-model bug: recent transcript activity is a reachability/liveness signal, not proof that a Codex turn is currently running.

A target can have a completed turn while its transcript is still inside the freshness window. If the adapter treats that effective active value as current turn activity, it sends Tab to an idle Codex composer. The envelope is written into the input box but is not submitted to the transcript.

The inverse failure also occurs: for a genuinely busy turn, a successful Tab queue may remain absent from the transcript until the turn finishes. An early grep miss is therefore not non-delivery evidence. Retrying at that point can produce duplicate decisions when the original queue later lands.

Root cause

Two independent axes were collapsed into one state:

1. Reachability/liveness — registry declaration plus transcript freshness; answers whether to use a live pane or stopped-session resume.
2. Current submit activity — whether the Codex TUI is currently executing a turn; answers whether to send Tab or Enter.

A second collapse happened in the result model: one queued-unverified value covered actions with opposite caller behavior (wait, inspect, recover an existing composer, or safely retry).

Proposed contract

1. Separate reachability from submit activity

For a reachable Codex pane, derive submit activity from the latest complete Codex turn-boundary event:

• latest task_started → active → send Tab once;
• latest task_complete → idle → send Enter;
• no trustworthy boundary → do not guess.

A non-empty, unterminated JSONL tail must be treated as a concurrent-write/unknown state. Do not skip it and reuse an older boundary.

Refresh submit activity after any pane settle delay, immediately before the key. If an unverified Enter would be retried, refresh again and retry only while still idle.

2. Report outcomes by observed action

Do not use names such as will-land or stranded, which predict a future result without evidence. Return an explicit caller action instead:

delivery	Meaning	Caller action
pre-injection-rejected	turn state unknown; zero pane commands	retry after state becomes readable (retry_safe=true)
delivered	this envelope nonce appears after the pre-send transcript boundary	await semantic peer ACK
queued-for-next-turn	active Codex Tab command executed; nonce not yet present	wait for turn boundary; do not resend
submit-unverified	Enter executed; nonce not observed	inspect target or await ACK; do not blindly resend
composer-unsubmitted	pane text written; refreshed state unknown; no key sent	recover the existing composer; do not rewrite envelope
write-unverified	pane write command returned non-zero or timed out	inspect target; do not resend
submit-command-unverified	submit-key command returned non-zero or timed out	inspect target or await ACK; do not blindly resend

Every structured pane result should include:

• submit_action
• recommended_action
• retry_safe
• verification_guidance
• the unique envelope nonce
• message-specific evidence (envelope-nonce-found or none)
• semantic acknowledged=false until a peer reply

Only a mechanically proven zero-pane-command path may set retry_safe=true.

For queued-for-next-turn, explicitly state that an early transcript miss is not non-delivery evidence. A caller must not use one early grep miss to justify reinjection.

3. Define fail-closed behavior by phase

fail closed is ambiguous unless the transport side effect is stated:

• unknown before pane write → zero pane commands, structured pre-injection-rejected, non-zero exit;
• unknown after pane write → no submit key, structured composer-unsubmitted, non-zero exit;
• target becomes active/unknown after an Enter attempt → no second Enter, submit-unverified;
• pane command non-zero/timeout → preserve nonce and attempted stage, structured uncertain result, non-zero exit, explicit do-not-resend action.

Dogfood evidence

The downstream adopter reproduced both directions:

1. A recently completed target was still derived as reachable/active by freshness. Tab left the envelope in the idle composer. One Enter submitted the existing envelope and immediately unblocked the waiting workflow.
2. A truly busy target had no nonce in an early transcript check, but the original Tab queue appeared after the turn ended. A premature reinjection produced duplicate content.

The adopter implementation now has 34 focused AgentTUI tests and passed an independent challenge review covering:

• effective active + latest task_complete → Enter;
• latest task_started → Tab;
• active→idle transition during settle;
• partial JSONL tail → unknown;
• no second Enter after active/unknown transition;
• nonce-only delivery evidence;
• every outcome and caller action above;
• pane write/submit non-zero and timeout paths.

Acceptance criteria

• Core schema/guidance distinguishes reachability from current submit activity.
• Reference adapter derives Codex activity from complete turn-boundary events, not transcript freshness.
• Submit activity is refreshed immediately before the key and before any Enter retry.
• Unknown pre-write and post-write phases have distinct structured behavior.
• Delivery outcomes expose explicit caller actions and retry safety.
• Early transcript miss is documented and tested as insufficient non-delivery evidence.
• Non-zero/timeout pane commands still return nonce-bearing structured outcomes and prohibit blind resend.
• Tests cover the full routing and outcome matrix for Codex and preserve Claude Code's Enter/receiver-native queue behavior.
• Downstream templates/generators propagate the corrected contract without product-specific paths or assumptions.

[JasonJarvan]

Residual failure found and reproduced in the KHS adopter after the original fix:

• Sender result for nonce 00b06d03-5605-46e8-9b41-b45ddaa954d5: target_submit_activity=idle, submit_action=enter-submit, delivery=submit-unverified.
• The target was not running a turn. Text was present in the Codex composer, but two successful Zellij Enter commands did not submit it.
• Root cause is now confirmed against Codex CLI 0.145.0 source: raw zellij action write-chars arrives as a rapid non-bracketed key stream and enters Codex PasteBurst; while the burst is active, handle_submission_with_time consumes Enter as a newline inside the paste rather than submitting. A zero Zellij exit code therefore only proves the byte was written, not that it had submit semantics.

Adopter fix (TDD): wrap Codex pane payloads in standard bracketed-paste framing (ESC[200~ ... ESC[201~) before the existing Enter-for-idle / Tab-for-active action. Claude Code remains unchanged.

Evidence after fix:

• 34/34 AgentTUI unit tests pass.
• Live idle-Codex probe to khs-upload-imp, nonce 0ef2248f-6f42-47e6-8af9-648cff4909c1, returned delivery=delivered, submit_action=enter-submit, evidence=envelope-nonce-found in 1.15s and immediately started a turn without human Enter.

Please include bracketed-paste framing in the upstream adapter contract/implementation; state separation and nonce verification alone do not prevent this idle-composer stranding mode.

[JasonJarvan]

A second transport-lifecycle defect is now reproduced and fixed in the KHS adopter. It affects both Codex and Claude Code resume routes.

Failure evidence

The previous adapter ran codex exec resume / claude -p --resume using blocking subprocess.run(..., timeout=args.timeout). Those processes own the resumed target turn; they are not bounded message-write commands. When AgentTUI’s internal default 120-second timeout fired, Python terminated the resume runner and the target rollout later recorded turn_aborted.

EverMe evidence (Codex reviewer): three envelopes entered the target transcript, then their turns recorded aborts. Two repeated deep-review attempts lost roughly 2.5 hours. The sender’s outer shell timeout was 900 seconds, but AgentTUI’s internal 120-second timeout fired first. This also explains reports where the same surface error covered both a completed turn and an aborted turn.

Important caller-action correction: turn_aborted does not prove zero side effects or safe replay. A turn may have read/written state or called external systems before aborting; in one specimen the reviewer had already performed review work and was interrupted during write-back. Therefore aborted/unacknowledged resume remains retry_safe=false.

Adopted fix

Resume routes now:

1. record the target transcript byte boundary;
2. launch the brand-native resume command with subprocess.Popen, start_new_session=True, and stdin/stdout/stderr connected to DEVNULL;
3. observe the envelope nonce for at most min(--timeout, 10s);
4. return without ever calling terminate/kill/wait-with-timeout on the runner.

Structured outcomes:

• delivered: nonce found, but task_completion=unverified; await peer ACK.
• resume-started-unverified: observation ended while detached runner remains alive; do not resend.
• resume-exited-unverified: runner exited before nonce evidence; exit does not prove zero side effects, do not blindly resend.

Verification

• 39/39 AgentTUI tests pass, including pre-send boundary, detached launch, observation timeout, and early runner exit.
• Live disposable Codex resume: send returned in 3 seconds with runner still active; target continued for ~19 seconds and reached task_complete with ACK DETACHED LONG TURN SURVIVED, no abort.
• Exact timeout branch: --timeout 0.01 returned resume-started-unverified; the detached target continued and later reached task_complete with ACK OBSERVATION TIMEOUT SURVIVED.

Please make sender/runner lifecycle separation normative upstream. Delivery evidence and target-task completion must remain separate dimensions.

[JasonJarvan]

Second axis: the outcome taxonomy is cut by observed action, not by cause — and three distinct causes collapse into one reading

The seven-value contract above is cut along what the adapter observed itself doing (text written or not, submit key sent or not, non-zero/timeout). That axis is correct and still wanted.

But dogfood measurement surfaced a second, orthogonal collapse, and it is the one that explains a complaint we kept hearing — "this has been fixed several times and it still happens." Three unrelated causes travel the same action path (pane resolves, pane write returns 0, submit key returns 0, nonce never appears in the target transcript) and therefore produce the same single reading:

#	Cause	What is actually true	Where the bytes stop	Would a different terminal multiplexer change it?
1	Sender half-deaf (sandboxed sender)	The sending process runs inside a sandbox that isolates the multiplexer's unix socket. It can be injected into; it cannot inject out.	The multiplexer command never reaches the server, or reaches it inertly.	No. Socket isolation is a property of the sandbox, not of the multiplexer.
2	Target auth expired	Bytes arrive, the submit key works, the composer submits — but the target CLI cannot process the turn (it needs re-authentication). The transcript is therefore never written.	Inside the target CLI, after submit.	No. Unrelated to transport.
3	Long text truncated in composer + never submitted	Text reaches the composer but is mangled by composer parsing (measured: a filename arriving with an interior character dropped) and never gets queued.	In the target composer, before submit.	Partially — this is the one a bracketed-paste write (or a wrapper that changes paste semantics) can address.

Consequence: with one reading covering all three, every fix lands on one cause while the other two keep firing. From the outside that is indistinguishable from a single recurring bug being fixed badly. The root cause is not the transport; it is indistinguishability.

Why this changes the order of work

1. First make the three causes distinguishable at delivery time — classify immediately after the pane write, and give each cause its own terminal value and exit code instead of folding all three into one unverified value. Until this exists, any fix's effectiveness is unmeasurable: you cannot tell "fixed" from "the other two causes still firing."
2. Then fix them one at a time, each with its own acceptance evidence.
3. Only then evaluate a transport wrapper — and scope it honestly to cause 3. Doing the wrapper first is very likely to be followed by "still happens intermittently," because causes 1 and 2 are untouched by any choice of multiplexer.

On the post-write screen-dump as a classifier — and its boundary

Dumping the target pane's visible screen immediately after the pane write is what separates cause 3 from causes 1–2: it distinguishes "the text never arrived" from "the text arrived and was not submitted" (and, when the target renders a re-authentication prompt, points at cause 2). That is a real and cheap discriminator.

Its boundary must be stated in the same breath, because it is easy to over-apply:

• Valid: post-hoc classification, as above.
• Invalid as an existence preflight — for a pane that does not exist, the dump can return rc=0 with empty output, i.e. a false positive for "exists".
• Not delivery evidence — screen content is not the transcript. Delivery evidence remains message-specific: the envelope nonce appearing in the target transcript after the pre-send boundary.

Provenance

Claim	Class	Source	Unverified gap
Causes 1–3 each occur and each yields the same unverified reading	measured	three separate reproductions during broadcast delivery; cause 3's truncation observed as a character dropped from a filename mid-composer	not established which cause dominates by frequency
A screen dump run without re-injecting separates "never arrived" from "arrived, not submitted"	measured	isolation diagnostic performed on a target whose earlier attempt traces were still on screen	not yet run as an automatic step inside the send path
Multiplexer choice is causally irrelevant to causes 1 and 2	inferred	cause 1 is sandbox socket isolation; cause 2 is inside the target CLI post-submit	no negative control has been run under a second multiplexer
A screen dump returns rc=0 with empty output for a nonexistent pane	measured	probe against a non-existent pane id while designing the existence preflight	single multiplexer only

Additional acceptance criteria proposed for this issue

• The three causes above are separable at delivery time, each with a distinct terminal value and exit code; none of them shares a value with the others.
• Classification runs after the pane write and before returning, and its inputs are recorded in the structured result.
• The screen-dump boundary is documented where the diagnostic is defined: diagnosis only; not an existence preflight; not delivery evidence.
• Any transport-wrapper change is scoped in its own acceptance criteria to cause 3, and does not claim to address causes 1–2.