Skip to content

fix(codex): steer a running turn over codex-acp's _session/steering - #14115

Merged
bolichen97 merged 1 commit into
kirodotdev:mainfrom
Pearcekieser:fix/codex-steer-queue
Sep 29, 2026
Merged

bolichen97 merged 1 commit into
kirodotdev:mainfrom
Pearcekieser:fix/codex-steer-queue

Conversation

@Pearcekieser

@Pearcekieser Pearcekieser commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: On a codex session, a steer sent from the dashboard composer reaches the running turn, and a steer that turn does not keep is queued instead of lost.

On a codex session the busy composer offers Steer and Queue, but Steer never steers. Every steer the user sends lands as a queued message and runs only after the current turn ends. The same holds for a steer from Side Chat, the messaging channels and spawn_steer; this PR fixes the dashboard composer, and those three keep queueing on codex (see below).

Why it matters

A user correcting a codex turn mid-flight ("stop, use the other file") waits for the wrong work to finish before the correction reaches the model. The UI gives no sign the steer was downgraded.

Not a goal

  • Steering codex from messaging channels, Side Chat, spawn_steer or a peer session_send: those keep queueing on codex.
  • Exactly-once delivery: a codex steer is at-least-once, and a steer codex acted on before a later denial or cancel runs again as its own turn.
  • Changing kiro-cli steering: its _session/steer path and steering_consumed echo are unchanged.
  • Changing how the dashboard keeps a steer's admission and origin records after a True return; that is main's existing behaviour for every backend.

What changed (motivation → approach → change)

Steer depends on supports_steer, which read ACP_BACKENDS_STEER, and that set names only the kiro-cli family because the handle speaks only kiro-cli's _session/steer. codex-acp 1.11.0 has its own verb, _session/steering. Driven live, it answers injected when a turn is running and startedNewTurn when none is (then running a turn of its own), and it sends no steering_consumed echo. session/cancel stops that adapter-owned turn and the next prompt runs normally.

A new set, ACP_BACKENDS_STEERING_REQUEST = {codex}, turns on supports_steer for the shared-runtime session handle. The handle sends _session/steering through a new AcpRuntime.send_request_for_answer, off the session queue, and waits for the answer or for the aimed-at turn to end, with no timer. The answer is registered with that prompt before the write can suspend, and the turn's dispatch loop checks it ahead of every frame: injected yields EVENT_STEER_CONSUMED, so the existing settle path marks the steer delivered, but only at a frame that is not the turn's terminal while nothing is buffered behind it on the session queue. The reader resolves answers and routes the terminal one line at a time, so only there is it certain the answer was read first; near the end of a turn nothing settles. steer() returns True only after that settlement. startedNewTurn sends session/cancel and reports undelivered. Because the cancel names no turn, a new prompt first waits up to 5 s for answers still owed from the last turn and for the cancels they schedule; an answer still missing is forgotten and replaced by one session/cancel, so an adapter-owned turn is stopped before our prompt is written. failed, an error, a malformed answer, or the turn ending first report undelivered, and the caller queues the text. At most 16 steers are held unsettled, counting answers still awaited after their turn ended (kept so a late startedNewTurn can be cancelled), each at most 64,000 characters; past that the steer takes the queue path. destroy drops the runtime's registration of any answer the session still holds (AcpRuntime.forget_request). The mid-turn steer line on the backend card reads either set.

Delivery is at-least-once. codex-acp orders the steering answer against the prompt's terminal in no way and sends no consumption echo, so an injected answer read after the terminal, or in the same read as it, leaves the steer queued too, and it runs a second time as its own turn. That is the requeue path's existing trade (a visible duplicate over a silent loss); the late answer is logged so the window can be measured.

No codex steer is sent while the turn waits on an approval: codex answers it injected, but its only reject option cancels the turn and drops the steer, so the steer is queued for the next turn instead. A codex steer that was accepted is still dropped if a later approval is denied or the turn is cancelled, because codex's reject and session/cancel discard injected text with the turn. So steer() returns True once codex answers injected (accepted, not consumed), and the turn reports the steer as EVENT_STEER_CONSUMED only when it ends cleanly, with no denied approval, no cancel and no refusal (_release_proven_steers), and only once that steer's steer() call has returned True. The composer writes the steer's transcript row synchronously on that return, so a consumption report never clears a pending entry whose row does not exist yet; a steer still suspended in its write at the terminal is left pending and queued by the teardown. On any other ending nothing is reported, and the composer's pending entry is queued by the turn's teardown, so the steer runs again as its own turn instead of being lost. The wait for codex's answer is bounded at 8 s (_STEERING_ANSWER_WAIT_SECS), below the browser's 10 s send abort, and a slower answer takes the queue path. Because only the composer keeps such a pending entry, codex steer is limited to the dashboard composer: the new steer_needs_loss_recovery (declared on LLMProvider, overridden by AcpProvider, AcpSessionProvider and AcpClient) makes AcpProvider.supports_steer False and AcpProvider.steer refuse, which keeps the messaging channels and Side Chat on their queue paths for codex, and spawn_steer (subagent_manager/continuation.py) refuses with steer_unsupported in favour of mode='follow_up'. A peer's session_send into a codex session is refused the same way in chat_delivery.steer_into_running_turn (user_origin=False), so it falls back to the queue and only the session's own composer steers codex. An earlier revision of this PR requeued already-settled steers from the dashboard; review found five successive races in that recovery path, so it was removed. Deferring the consumed report to a clean turn end lets the existing teardown requeue cover the denial and cancel cases instead.

Where it lives: the set in agent_sdk/backends.py (re-exported by acp_backends.py and acp/types.py) and the card line in agent_sdk/backend_cards.py; the verb in acp/session_handle.py with its transport in acp/runtime.py; supports_refusal_steer on acp/client.py, acp/session_provider.py, providers/acp.py and providers/base.py; its two readers in deny_notice.py and dashboard/chat_runner.py. The harness-parity spec's H6 row (docs/system-specs/modules/harness-parity.md) and harness-onboarding.md name both steer tables and the user/refusal split, and messaging.md and common/injected-messages.md name the deny-notice gate as supports_refusal_steer.

Backwards compatibility

Compatible: kiro-cli and KAS steers take the same path as before, and every other backend still reports no steer. The one new provider property defaults to False.

Tests

  • test/test_codex_steering_request.py (new): each answer outcome (injected settles through the echo, startedNewTurn cancels and is undelivered, failed and error answers are undelivered), no request without a running turn, an unanswered steer undelivered once its turn ends (a late startedNewTurn still cancelled), malformed answers undelivered without raising, the count and size bounds, a cancelled caller releasing its slot, answers awaited past their turn sharing the bound and dropped on destroy, the terminal-before-injected order reporting undelivered, a late startedNewTurn cancelled before the next prompt is written, an answer that never arrives forgotten and cancelled before the next prompt, an answer for an earlier prompt never settling a newer one, an injected answer read in one buffer with the terminal, in either order, queued rather than settled, an injected answer never settled at the terminal or with frames buffered, an answer read while the steering write is still draining settling at the next non-terminal frame before the turn completes, through the real reader and dispatch loop, no late cancel once our next prompt runs, a steer against real turn state, no request while the turn waits on an approval, a failed cancel logged rather than raised, nothing reported consumed after a denied approval on codex (and a kiro denial leaving settling on), a steer proven mid-turn not reported consumed when the turn is then denied or cancelled (through the real reader and dispatch loop), an answer slower than the send-request bound queued, a steer cancelled after it was proven never reported consumed, proven steers counted toward the retention cap, ACP_BACKENDS_STEERING_REQUEST pinned to codex, the kiro verb unchanged, and send_request_for_answer resolving off the session queue.
  • test/test_steer_requeue.py: TestPeerSteerOnCodex, a peer steer into codex refused before any RPC while the composer still steers.
  • test/test_subagent_continuable.py: spawn_steer refuses a codex run with steer_unsupported.
  • test/test_codex_steering_request.py also covers the provider wrapper refusing a codex steer while still steering kiro.
  • test_acp_codex_harness.py, test_harness_parity.py: codex advertises user steer but not refusal steer, and the tables stay the source of both answers.
  • test_refusal_inband_notice.py, test_messaging_driver.py, test_slack_handler_coverage.py: the doubles gain supports_refusal_steer, since the deny paths now read it.

Manual verification

Drove codex-acp 1.11.0 over stdio: _session/steering during a prompt returned {"outcome":"injected"} in 10 ms; with no prompt running it returned {"outcome":"startedNewTurn"} and started a turn; session/cancel then stopped it and a following session/prompt ran to end_turn. A dashboard run was not possible on the test host: codex sessions refuse to start there without a sandbox backend, and the model call is denied by an account policy.

Related Issues

Fixes #14114

Pattern harvest

Not generalizable: the defect is a missing per-harness verb, and the harness-parity checks already gate steer by table membership rather than harness identity.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@Pearcekieser
Pearcekieser requested review from a team and iamwhatever September 26, 2026 04:32
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Intent: make Steer on a codex session reach the running turn, using codex-acp's own _session/steering request, with each steer delivered exactly once.
Not a goal: steering deny notices into codex turns (codex drops them with the cancelled turn), changing the busy composer UI, or changing kiro-cli/KAS steer behavior.

@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 26, 2026
@github-actions

github-actions Bot commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of eb59e97244d6379548f53afe9f79c9fe0b250faa via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify a live composer steer on a real codex session (the PR's own dashboard run was blocked by the test host) before relying on delivery.

Suggestions

  • Record the measured codex-acp version floor (1.11.0) next to ACP_BACKENDS_STEERING_REQUEST as a comparable constant, not only prose, so a future adapter that reorders answers or adds a consumption echo has one place to hang a floor check — the pattern mcp_hot_reload already uses.

[DESIGN-REVIEWED] eb59e97

@github-actions

github-actions Bot commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — ✅ PASS

Premise-level review of eb59e97244d6379548f53afe9f79c9fe0b250faa via the fork AI-review pipeline — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: PASS

Verify on live codex-acp 1.11.0 the two measured claims the design rests on: reject cancels the turn dropping injected text; session/cancel stops an adapter-owned turn.

What this change ships

Inventory (10 items) — 10 justified

Intent: a dashboard-composer steer on a codex session reaches the running turn, and one the turn drops is requeued, not lost — a FIX.

  1. Composer steer on codex now reaches the running turn instead of silently queueing — justified
  2. A steer codex drops (denied approval, cancel, refusal, late answer) is requeued and may run twice, visibly — justified
  3. No steer is sent while a codex turn waits on an approval; it queues — justified
  4. Channels, Side Chat, spawn_steer, peer session_send keep queueing on codex, now by explicit refusal (steer_needs_loss_recovery) — justified
  5. Deny notices gate on new supports_refusal_steer; unchanged for kiro/KAS, off for codex — justified
  6. New set ACP_BACKENDS_STEERING_REQUEST={codex} and runtime send_request_for_answer/forget_request — justified
  7. Codex backend card now shows the mid-turn steer line — justified
  8. Bounds: 16 unsettled steers, 64k chars each; past either, queue — justified
  9. A codex prompt may wait up to 5s (with one cancel) for owed answers; a steer waits up to 8s — justified
  10. The pin "codex must not advertise steer" rewritten to its opposite, its own stated reason (-32601) discharged by codex's own verb — justified

[FIRST-PRINCIPLES-REVIEWED] eb59e97

@github-actions

github-actions Bot commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

Reviewed eb59e97244d6379548f53afe9f79c9fe0b250faa via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] eb59e97

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: codex steer answer bound in AcpSessionHandle._steer_via_steering_request

  • Timed-out steers are falsely reported as delivered

rebutted, not a defect: steer() returning True means "accepted, delivery open", the contract kiro-cli's fire-and-forget _session/steer already ships (session_handle.py steer, chat_delivery.py steered comment). No caller reads True as proof of delivery that this path changes.
The timeout branch returns True only after codex accepted the write and did not answer inside 10 s; a live adapter answers injected in ~10 ms. A late injected settles through the echo frame; a late startedNewTurn is cancelled and the steer stays pending for the teardown requeue.
Returning False there, the proposed fix, was this PR's first shape and is its own blocking defect (local GPT review, fixed before publish): the caller queues the text while codex may still inject it, so it runs twice.
The residual, a late failed after a >10 s answer on a non-dashboard caller, is the same loss the kiro-cli verb has for any steer it never consumes. Override reason: "True on an unanswered steer is the existing kiro-cli steer contract; False double-executes on a late injected answer."

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

self-added: no

  • H6 row still describes one steer table

fixed in f022a3c: the H6 row in docs/system-specs/modules/harness-parity.md now names ACP_BACKENDS_STEER and ACP_BACKENDS_STEERING_REQUEST, says supports_steer on the handle is their union and supports_refusal_steer reads the first alone and why, and lists test_codex_steering_request.py and the new handle members.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

self-added: no

  • state the discharged -32601 reason in the rewritten pin's docstring

fixed in f022a3c: test_codex_advertises_user_steer_over_its_own_steering_request now says it replaces the "codex must not advertise steer" pin, that the pin's reason was -32601 at the mid-turn correction, and that speaking codex's own verb discharges it.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 26, 2026
@github-actions

github-actions Bot commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review (fork) — ✅ no blocking findings

Reviewed eb59e97244d6379548f53afe9f79c9fe0b250faa via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] eb59e97

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 26, 2026
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: codex injected-answer settlement in AcpSessionHandle (_steering_answers / _take_injected_steers)

  • Synthetic acknowledgement can trail turn completion

fixed in 02454b3: no synthetic frame is queued any more. The answer future is registered with its prompt generation from send_request_for_answer(on_registered=...), before the write's drain() can suspend, and the prompt dispatch loop calls _take_injected_steers() ahead of every frame, so an injected answer the reader resolved before the terminal line yields EVENT_STEER_CONSUMED inside that turn.
A late injected settles the same way while its turn runs; one aimed at an earlier prompt is dropped, because that turn's teardown already requeued the steer.
Tests drive the real reader and dispatch: answer and terminal fed back to back, and fed while the steering write's drain is held; both fail without the fix.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 26, 2026
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: codex steer answer bound in AcpSessionHandle._steer_via_steering_request

  • timed-out Codex steers are acknowledged before delivery

needs-a-decision: this is the round-1 finding again (same span, same return True on an answer slower than 10 s), and the code is correct as-is.
True means "accepted, delivery open", the contract the default kiro-cli _session/steer ships with no answer awaited at all. The dashboard and session_send keep the steer in slot._pending_steers because True was returned, and the turn's teardown requeues it; False would drop that entry and queue text codex may still inject, which runs it twice.
The residual is spawn_steer only, which already reports success on less evidence on kiro-cli, and it needs the codex backend, a >10 s answer on a request measured in milliseconds, and a late non-injected outcome. The lane's adjudicator flagged it as a likely edge case.
Override reason: "True on an unanswered codex steer is the existing kiro-cli steer contract; the dashboard and session_send requeue it, and False would double-execute a late injected answer."

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

@iamwhatever @chenmingwei23 could one of you rule on the fenced GPT finding here? It blocks the PR and only a repository writer's override can clear it.

The lane has raised the same thing twice, on the round-1 head and on this head: when codex has not answered a steer within 10 s, the handle returns True ("accepted, delivery open"), which is how the default kiro-cli steer already behaves. The alternative the lane proposes, returning False, was this PR's first shape. It caused a double run on a late injected answer, and a local review caught it before publishing. The lane's own adjudicator rated the residual MEDIUM-to-LOW, confined to spawn_steer, and flagged it as a likely edge case. The disposition above has the full reasoning and an override reason.

If you would rather have the bound removed or handled differently, say how and I'll change it.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 26, 2026
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Removed the dashboard lost-steer recovery in 19f7490 and documented the limit it tried to cover. Asking maintainers to accept that limit.

Why: across five review rounds, GPT found an upheld race in that recovery path each time: the metadata restore, the row state, redaction collisions, the text-keyed maps, and on 5925996 both an interrupted loss report and a hard kill requeuing discarded steers. Each fix added state that the next finding lived in. So this push takes the recovery out rather than patching it a sixth time.

The limit: if a codex turn settles a user's steer and a tool approval later in the same turn is denied, codex cancels the turn and drops the injected text, and Kiro Crew does not recover it. After a denial, nothing later in that turn settles, so a steer still in flight is queued rather than lost. The limit is stated in the ACP_BACKENDS_STEERING_REQUEST comment, the H6 row of harness-parity.md, and the PR description.

What stays is the part the reviews did not dispute: codex steer over _session/steering from the dashboard composer, at-least-once delivery, no steer sent while an approval is pending, and the pre-prompt cancel of any adapter-started turn. To keep the limit where the user is watching and can resend, the messaging channels and Side Chat still queue on codex, and spawn_steer still refuses with steer_unsupported. kiro-cli is unchanged everywhere.

Removed: EVENT_STEER_LOST, take_lost_steers, remember_settled_steer, the settled and restored slot logs, _restore_lost_steers / _collect_lost_steers / _requeue_restored_steers, and from_states on find_written_steer_row. chat_delivery.py, chat_handlers.py, state.py and test_steer_requeue.py are back to main, and chat_runner.py differs from main only by the supports_refusal_steer gate. That also removes both findings on 5925996 (session_handle.py:4281, chat_handlers.py:5015) and the flagged one on 6f2914a (chat_runner.py:7720), since their code is gone.

Checked locally: the 269 steering, requeue and subagent tests pass, 13,139 backend tests across the affected files pass, and mypy, the agent-SDK boundary, comment-history and docs lint are clean.

@iamwhatever @chenmingwei23, does the documented limit work for you? The alternative is a stronger delivery guarantee from codex-acp itself, for example a steering-consumed notice, which I can file upstream.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: codex steering answers (AcpSessionHandle._steer_via_steering_request)

  • settled steer is lost after a later denial

not changed, by design. This is the limit this head documents on purpose, in the ACP_BACKENDS_STEERING_REQUEST comment, the H6 row of harness-parity.md and the PR description. The earlier revisions carried exactly the fix you propose (retain settled codex steers and requeue on denial). Across five review rounds each version raised a new upheld race in that recovery path, so it was removed in 19f7490. To keep the limit where the user is watching and can resend, only the dashboard composer steers codex. Maintainer acceptance of the limit is requested in #14115 (comment); this finding stands or falls with that decision.

  • cancellation leaves an adapter-owned turn running

fixed in the next push with the change you named. When _abandon finds the answer already resolved, which happens when a cancelled caller unwinds in the same loop iteration the answer arrived in, it now runs _late_answer on it before returning. A startedNewTurn there therefore gets its session/cancel like any late one.
Test: test_a_caller_cancelled_after_started_new_turn_still_cancels_that_turn. It fails without the change (no cancel is sent) and passes with it.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: codex steering settle wait and bound (AcpSessionHandle._steer_via_steering_request)

  • the steering docstring still describes settled steers held for a denial

fixed in the next push. The parenthetical now says the cap counts unanswered and abandoned answers only, and that a settled steer holds nothing.

  • the settle wait holds the dashboard send across a frame-quiet stretch

not changed, as on earlier heads. A bound here brings back the timer earlier rounds removed. A slow injected would return False, the caller would queue the text, and the late answer would still inject it, so the steer would run twice on every long tool call rather than only at a turn's edge. The cost of leaving it is a composer send that can wait through a silent tool call. After this PR the dashboard composer is the only caller left, because channels, Side Chat and spawn_steer do not steer codex.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: codex steering gates and bounds (AcpSessionHandle._steer_via_steering_request)

  • A later denial permanently loses an accepted steer

not changed, by design. This is the documented limit of codex steering on this head: see the ACP_BACKENDS_STEERING_REQUEST comment, the H6 row of harness-parity.md and the PR description. The requeue-on-denial you propose was carried by earlier revisions and removed in 19f7490 after five rounds of upheld races in it. Maintainer acceptance of the limit is requested in #14115 (comment).

  • A pre-prompt steer can cancel the prompt about to start

fixed in the next push. The handle now sets _prompt_written right after this turn's session/prompt write returns, and resets it at turn start. _steer_via_steering_request sends nothing until it is set. A steer during prompt construction therefore takes the caller's queue path instead of reaching an adapter with no turn of ours, and no startedNewTurn cancel can follow our prompt. Tests: test_no_request_goes_out_before_the_prompt_is_written, plus the real-turn-state test, which now also checks that an active turn whose prompt is unwritten refuses. Both hang on the previous head, where the steer is sent and waits for an answer.

  • Settled writes bypass the steering retention bound

not changed; the adjudicator downgraded this as a disproportionate remedy. A settled entry holds only a resolved future, and the parked steer pops it in the next loop iteration, so the excess is transient, self-clearing and bounded by the cap.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: codex steering log lines (AcpSessionHandle._steer_via_steering_request, _settle_abandoned_steering)

  • adapter error text leaks into gateway logs

fixed in the next push, even though the adjudicator flagged it as an acceptable edge case: the fix costs less than an override. Every log line this PR adds on the steering path now records only the exception's class, never its text: the refused-answer line, the write-failure line (which also drops exc_info), the adapter-owned-turn cancel failure and the pre-prompt cancel failure.
Test: test_an_error_answer_logs_its_class_not_the_adapter_text. It fails on aeff45d (the text appears in the log) and passes with the change.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: codex steering spec and settle wait

  • the messaging.md bullet promises channel steer for codex

fixed in the next push. The _handle_busy bullet now states the wrapper's actual rule. AcpProvider.supports_steer is False for a steer_needs_loss_recovery backend (codex) and its steer refuses, so a mid-turn channel message on a codex session always queues. _session/steering is spoken only for the dashboard composer, which steers the inner handle.

  • the codex settle wait is unbounded under an inline HTTP handler

not changed, as on earlier heads. A bound brings back the timer that earlier rounds removed. A slow injected would return False, the caller would queue the text, and the late answer would still inject it, so the steer would run twice on every long tool call. The dashboard composer is the only remaining caller.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Re-triggered: the GPT, Opus, Security Scope and Internal Content Scan lanes on d15c1a9 ended with no verdict at 00:32 UTC, right after the CI app's API rate limit (403 at 00:31). Every other check on that head passed. 37fd7ea is the same change rebased onto current main (8ab7636), with no code change.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: codex steering denial limit (AcpSessionHandle._note_steering_denial)

  • A later denial silently drops an already-settled steer

not changed, by design, as on 19f7490, 65d17ad and aeff45d. This is the documented limit of codex steering on this PR: see the ACP_BACKENDS_STEERING_REQUEST comment, the H6 row of harness-parity.md, the PR description, and the _note_steering_denial docstring the adjudicator quotes. The retain-and-requeue fix was carried by earlier revisions and removed after five rounds of upheld races in it. This finding therefore needs a maintainer decision, not more code: either accept the limit (#14115 (comment)) or say so and I'll take a different design.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: runtime stdin write lock (AcpRuntime.send_request_for_answer)

  • the new stdin writer bypasses the write lock

fixed in the next push. send_request_for_answer now writes and drains inside _stdin_write_lock() and calls _refuse_write_if_dead() first, the same as send_request. A dead runtime there pops the registration and retrieves or cancels its future, so asyncio logs nothing unhandled. A concurrent response write measuring the buffer level for its no-progress bound therefore never sees a steering frame land mid-measurement.
Test: test_every_runtime_stdin_writer_takes_the_lock now includes send_request_for_answer. It fails on 37fd7ea and passes with the change.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: codex steering denial limit (AcpSessionHandle._note_steering_denial)

  • A settled Codex steer is lost after a later approval denial

not changed, by design. This is the documented limit, the same finding as on 37fd7ea (#14115 (comment)), and it needs a maintainer decision rather than more code. The adjudicator adds one point worth weighing in that decision: the later denial can come from a host or policy auto-reject that the user did not choose, not only from a human click. In that case the steer's row reads consumed for text codex dropped.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: peer steer refusal on codex (chat_delivery.steer_into_running_turn)

  • a peer session_send still steers codex through the inner provider

fixed in the next push. steer_into_running_turn now returns STEER_UNAVAILABLE before any RPC when the caller is not the session's own human (user_origin=False) and the client has steer_needs_loss_recovery. session_control already sends that outcome down its queue arm, so a peer's text on a codex session queues, and only the composer the user watches steers codex. Tests: TestPeerSteerOnCodex in test_steer_requeue.py (the peer steer is refused with no RPC and nothing registered; the composer still steers). The peer test fails on d81a728 and passes with the change.

  • the phase-2 settle wait has no ceiling

not changed, as on earlier heads. A ceiling brings back the timer earlier rounds removed. The steer would be queued while the late injected still lands, so it would run twice. After this push the composer is the only caller left.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Replies to the GPT review of 626cf6017. Both are addressed in bd982fa7e.

issue (blocking): steer settlement reverses transcript ordering (session_handle.py:4285). Fixed. The settle check was at the top of each frame's handling, so a frame the reader had queued before the steering answer could be dequeued with an empty queue behind it and have the steer row persisted ahead of it. Settlement now runs between frames: after the previous frame is fully handled and before the next is dequeued, and only while nothing is buffered. The reader queues frames and resolves answers inline in stdout order, so with the queue empty every frame read before the answer has already been handled, and a terminal read before it would already have ended the turn. test_a_frame_read_before_the_answer_is_handled_before_the_steer_settles feeds a chunk and the injected answer in one read; it produces steer_consumed, text_chunk, complete on 626cf6017 and text_chunk, steer_consumed, complete now. 13,331 scoped backend tests pass.

issue (blocking): a later denial drops a steer already reported consumed (session_handle.py:2735). No code change. This is the documented limit of codex steering: codex's reject cancels the turn and discards what was injected, and codex-acp gives no signal that would let the host recover it. Two earlier recovery designs in this PR drew repeated upheld findings and were removed. The limit is written up in the ACP_BACKENDS_STEERING_REQUEST comment, the harness-parity spec and the PR description, and steering is confined to the dashboard composer the user is watching. The acceptance request to maintainers is in 5850430530 and 5851736151.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Reply to the GPT review of bd982fa7e.

issue (blocking): a later approval denial loses an already-settled steer (session_handle.py:2736). No code change. This is the documented limit of codex steering, the same finding as on the previous heads. codex's reject cancels the turn and discards what was injected, and two recovery designs in this PR drew repeated upheld findings and were removed. The limit is written up in the ACP_BACKENDS_STEERING_REQUEST comment, the harness-parity spec and the PR description, and steering is limited to the dashboard composer. It needs a maintainer decision: accept the limit or ask for a different design. The request is in 5850430530 and 5851736151.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

@Pearcekieser has accepted the documented limit of codex steering for this PR. When an approval in a codex turn is denied, including an automatic host or policy denial, a steer the turn already settled is lost with the cancelled turn and its transcript row still shows "consumed". The limit is recorded in the ACP_BACKENDS_STEERING_REQUEST comment, the harness-parity spec and the PR description, and codex steering is limited to the dashboard composer.

Dispositions for the reviews of bd982fa7e, addressed in 8a8863580:

GPT, issue (blocking): a later approval denial loses an already-settled steer (session_handle.py:2736). This is the accepted limit above; no code change.

Opus, issue (blocking): a codex steer settles as consumed after a plain cancel() (session_handle.py:2718). Fixed as proposed. _take_injected_steers now also returns nothing once _cancelled is set, the same as after a denial, so a soft Stop leaves the steer unsettled and the turn-exit requeue shows it as a queue card. test_a_cancelled_turn_settles_no_steer fails on bd982fa7e and passes now.

Opus, suggestion (non-blocking): the steer() docstring contradicts the codex branch (session_handle.py:2332). Fixed. The docstring now describes both transports and points at _steer_via_steering_request.

Opus, suggestion (non-blocking): bound client.steer() in chat_delivery.py:415 with asyncio.wait_for. Declined, as on earlier heads. A timer that falls through to the queue while the adapter may still inject the text can run the steer twice. The wait ends when the turn ends, and a steer that has not settled by then is queued.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

9e4d90e80 removes the defect behind GPT's recurring finding ("a later approval denial loses an already-settled steer") instead of leaving it as a documented limit.

A codex steer now counts as consumed only when its turn ends cleanly. steer() returns True once codex answers injected, which means accepted, and the composer keeps its pending entry. The turn reports EVENT_STEER_CONSUMED only at a clean terminal, with no denied approval, no cancel and no refusal (_release_proven_steers). After a denial or a cancel nothing is reported, so the turn's teardown queues the pending entry and the steer runs as its own turn. The wait for codex's answer is bounded at 8 s, below the browser's 10 s send abort, and a slower answer goes to the queue.

test_a_steer_proven_mid_turn_is_not_reported_consumed_if_the_turn_is_cut[denied|cancelled] runs through the real reader and dispatch loop, and test_an_answer_slower_than_the_send_request_bound_is_queued covers the bound. All three fail on 8a8863580 and pass now. The limit text is gone from the PR description, the ACP_BACKENDS_STEERING_REQUEST comment and the harness-parity spec.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Replies to the GPT review of 9e4d90e80, all addressed in f5e258cc2. The branch is now squashed to one commit for PR Hygiene.

issue (blocking): settled steer text bypasses the retention cap (session_handle.py:2511). Fixed as proposed: held now also counts _steers_proven, so proven steers waiting for the clean-terminal report share the _MAX_STEERING_ANSWERS cap. test_proven_steers_awaiting_the_terminal_count_toward_the_cap fails on 9e4d90e80 and passes now.

suggestion (non-blocking): pin ACP_BACKENDS_STEERING_REQUEST membership (backends.py:1093). Added test_only_codex_takes_the_steering_request, which asserts equality with frozenset({ACP_BACKEND_CODEX}).

suggestion (non-blocking): the steer() docstring says it awaits settlement (session_handle.py:2430). Fixed. It now says the codex path awaits only the adapter's answer, that True means accepted, and that consumption is reported separately at the clean terminal.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Reply to the GPT review of f5e258cc2, addressed in b4daf7705: one commit, rebased onto current main.

issue (blocking): cancellation can erase a consumed steer from the transcript (session_handle.py:2543). Fixed as the adjudicator proposed. Every non-True exit of the codex steer now revokes the steer wherever the dispatch loop has put it, including _steers_proven, matched by identity so an identical second steer is kept. A caller cancelled after its steer was proven is therefore never reported consumed at the clean terminal, and the caller's own bookkeeping queues it. test_a_steer_cancelled_after_it_was_proven_is_never_reported_consumed fails on f5e258cc2 and passes now.

PR Hygiene and Fork PR Description: the description now has the template's ## Not a goal section.

Backend Tests shard 3 on f5e258cc2 (test_review_repair_routing_skill.py::test_slim_skills_do_not_regrow_duplicate_guidance_or_wire_model_ids[prepare-pr-68000], 68,015 > 68,000 bytes) is inherited from main. This PR does not touch that skill; the fix is PR #14397.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

7f1894938 is b4daf7705 rebased onto current main with no code change. The Opus 5 Review of b4daf7705 ended "review incomplete" without posting, and a body edit does not rerun it, so this push is only to get that review. GPT 5.6 found no blocking findings on b4daf7705.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased onto current main (c1f69f518) to clear the merge conflict. No code change.

The only conflict was one row in docs/system-specs/modules/messaging.md: main added the TOOLLESS_TURN_AGENT row and extended the deny_all_tools row, and this PR renames supports_steer to supports_refusal_steer in the deny-cause row. The resolution keeps main's text plus that rename. git range-diff against 7f1894938 shows no change outside that docs context.

The 112 codex steering and requeue tests pass on c002279b7.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

ee1e65504 fixes GPT 5.6's blocking finding on c002279b7 (session_handle.py:2785, non-clean terminals consuming pending steers).

_release_proven_steers now reports a proven steer only when the stop reason is exactly end_turn, and still only with no cancel, no denied approval and no RefusalInfo. The old guard excluded only cancelled and stale_recover, so a bare wire refusal (which carries no RefusalInfo), max_tokens, and error reasons such as error: tool stall all let the steer be reported consumed. Its pending entry was then settled and skipped by the requeue. On every ending other than end_turn the proven steers are now dropped unreported, and the turn's teardown queues each pending entry.

A new parametrized test, test_only_a_clean_end_turn_reports_a_proven_steer, covers refusal, cancelled, stale_recover, max_tokens and error: tool stall. On c002279b7 the refusal, max_tokens and error: tool stall cases fail, and all five pass now. The cancelled and stale_recover cases already passed, because the old guard listed them, so they stay as regression pins. The targeted steer and ACP runtime tests pass (117 + 818), as do black, mypy and the comment-history gate.

Four other red checks on c002279b7 don't come from this PR:

  • Frontend Tests (2), Electron Shell Tests and Coverage Gate also fail on main's own CI run for 20ed6a1dc (run 36337451146), so they're inherited.
  • Pod Boot Canary (Windows) passed on that main run. Here it failed with pod up failed: no internal-API credential for pod 'KiroCrew' ... is it running?, which is a boot-timing failure in pod code this PR doesn't touch. I'm treating it as flaky.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Parking this PR at ee1e65504. GPT 5.6's latest blocking finding is the seventh edge case in how a codex steer is settled, so I'm stopping the patch rounds and putting the design question to the maintainers instead.

Settlement edge cases found so far

Each line gives the head that exposed the case and what happened to it.

  1. bd830c073: two credential-bearing steers redacted to the same text, so the lost-steer restore could not tell them apart. Fixed by matching on the raw text, then made moot when the restore was removed.
  2. 5017f0eaa: the restore wrote back into the text-keyed maps the steer request owns. Identical-text steers lost their attachments and admission, and the request's tail could pop a restored record. Fixed with a per-occurrence record, then made moot when the restore was removed.
  3. 5925996f0: two more upheld findings in that restore. The restore was dropped and "a denied approval loses an already-consumed steer" was documented as a limit.
  4. 19f74906b: if the steer caller was cancelled just as codex answered startedNewTurn, codex's new turn kept running. Fixed.
  5. 65d17ada3: a steer sent while the prompt was still being written could cancel the prompt. Fixed: steers wait for the prompt write.
  6. 626cf6017: frames queued before the steer answer were written after the steer row, so the transcript order was wrong. Fixed: settle only once the reader queue is drained.
  7. bd982fa7e: after a soft Stop, a steer codex had taken was still settled consumed and never requeued. Fixed.
  8. 8a8863580: the documented denial limit (case 3) was replaced with settle-at-clean-end. A steer counts as consumed only when the turn ends cleanly, otherwise it is queued.
  9. 9e4d90e80: steers waiting for the end-of-turn report were not counted toward the 16-steer cap. Fixed.
  10. f5e258cc2: a caller cancelled after its steer was proven left the steer in _steers_proven, so it was reported consumed with no row. Fixed.
  11. c002279b7: the clean-end check excluded only two stop reasons, so a bare refusal, max_tokens and error endings all consumed the steer. Fixed: only end_turn counts.
  12. ee1e65504 (open): consumption is emitted before the caller has returned acceptance. If the gateway shuts down between the dashboard clearing the pending entry and the step that persists the steer's row, the steer is neither persisted nor requeued.

Why the class keeps recurring

Every case above comes from the same shape. The steer's only durable trace, its transcript row, is written at the end of a hand-off between three in-memory owners: the steer RPC caller, the ACP reader loop, and the chat runner's pending list. Each pair of owners has its own ordering and cancellation windows. Each fix closed one window and moved the risk to the next one.

A simpler model

Persist the steer's transcript row, in a new "sent" state, before the steer is injected into codex. After that, every later event only changes the state of a row that already exists:

  • A clean end_turn marks it consumed.
  • Any other ending marks it requeued, and the turn's teardown queues it.
  • Gateway startup reconciles rows still in "sent" by requeuing them.

No in-memory hand-off holds the only copy of the steer, so no cancellation or teardown window can lose it. Cases 1, 2, 3, 7, 10 and 12 disappear as a class rather than one at a time. Cases 4, 5, 6 and 9 are about ordering and bounds on the codex wire, and they stay as they are.

What the simpler model costs

  • A new row state on the transcript, with rendering for the sent to consumed and sent to requeued transitions, and a migration-safe default for older readers.
  • A durable write on the steer hot path, before the RPC. The composer's 8 s send budget has to absorb it.
  • A startup reconciliation pass over "sent" rows, with care that one steer isn't requeued twice when a live turn and a restart both see it.
  • Delivery stays at-least-once. A steer codex acted on before a denial or crash can still run a second time from the queue. The difference is that the row now shows the requeue.
  • This is a redesign of the steer persistence path, so it belongs in its own PR, reviewed as a design change, not as round 38 of this one.

Where that leaves this PR

This PR stays open at ee1e65504 with the watch loop stopped. Maintainers can take it as is, with case 12 as a known shutdown-only transcript gap, or ask for the persist-first redesign as a follow-up. The adjudicator rated case 12 as medium harm: the steer's text did run, and only the transcript row is lost, under a timing coincidence during process teardown.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Un-parking with a fix for the last open GPT finding on ee1e65504 (session_handle.py:4426, consumption can precede the sender's acceptance).

GPT's fix, emitting consumption only after the steering caller has returned acceptance, is taken, without making the terminal wait on the caller (the stall the adjudicator warned about):

  • _steer_via_steering_request records the steer in _steers_accepted at the point it returns True.
  • _release_proven_steers reports a proven steer consumed only if it is also in _steers_accepted (matched by identity). The dashboard's persisting tail in chat_delivery.steer_into_running_turn runs synchronously on that True return, so by the time EVENT_STEER_CONSUMED reaches _settle_consumed_steers, the steer's row already exists.
  • A steer still suspended in its write when the clean terminal arrives is not reported. Its caller resumes after _turn_done is set, returns False, and the pending entry is queued by the teardown. That is the requeue path's visible at-least-once cost; nothing on the terminal path waits.

Tests: test_a_clean_terminal_never_reports_a_steer_its_caller_has_not_accepted fails on ee1e65504 (the release returned the steer) and passes now; test_a_clean_terminal_reports_a_steer_its_caller_accepted covers the positive case. Targeted steering, requeue and steer-related runs pass; black, mypy and the comment-history gate are clean. Rebased onto current main in the same push, still one commit.

The skill-size and Frontend (2) / Electron Shell / Coverage Gate reds noted on the previous round are inherited from main, as before.

codex sessions offered the steer/queue split but every steer fell back to
the queue: the handle only spoke kiro-cli's _session/steer. Speak codex's
own request on the shared runtime, read its outcome as the delivery
evidence, and keep deny notices on the recovery continuation.
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased onto current main with no code change (git range-diff shows a4049c4 = eb59e97).

GPT 5.6 and Opus 5 both passed on a4049c4. The only reds were inherited: test_pid_reader_ratchet.py failed because the old base recorded 158 pid-reader sites while the tree held 160. Main fixed that in #14778, and this PR adds no pid reads. Coverage Gate failed as a consequence. test_channel_connect_row.py (Linux shard 7) passes locally on the old and new base. The ratchet, the channel-connect test and the 112 steering/requeue tests all pass on eb59e97.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

@iamwhatever @chenmingwei23 eb59e9724 has readiness: passed: GPT 5.6 and Opus 5 have no blocking findings, all checks are green, and it merges cleanly with main. Could one of you merge it? A fork contributor can't turn on auto-merge. Thanks.

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed on behalf of the maintainers (sweep 2026-09-28): readiness passed, required checks green on eb59e97, no blocking review threads, security posture unchanged. Approving and merging.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Steer on a codex session always falls back to the queue

2 participants