v0.9.14: runtime API steer receipts claim delivery the engine never made — item.completed emitted unconditionally, dropped steers reported as sent

[Hmbown]

Why this matters

Steering is the user's only way to redirect a running turn. Today the runtime API reports a steer as delivered before the engine decides, and the engine can silently drop it — so a client tells the user "Guidance sent", clears their composer, and their words never reach the model. Input silently lost.

Current behavior

• crates/tui/src/runtime_threads.rs:9575 steer_turn: reserves channel capacity, persists the steer item as already Completed, then spawn_steer_receipts (runtime_threads.rs:8890) emits turn.steered + item.completed unconditionally — the code comment says "after engine acceptance" but no acceptance check exists.
• Engine side: crates/tui/src/core/engine.rs:1285 next_turn_steer drains the channel and discards any steer whose turn has moved on; turn-loop interrupt/failure paths drop pending_steers (turn_loop.rs:48, :809, :2074).
• The Ratatui TUI presentation path was made honest in 9efb4ba (Steered input is not inserted as the newest history entry: it lands above in-flight work and reads as out of order #6190); the runtime API layer serving GPUI/ACP/SDK clients never got the equivalent.

Repro (live)

GPUI client steering a running turn (Enter while active turn): the app showed its sent-confirmation and cleared the composer; the model never received the text mid-turn, and the durable record still shows the steer item completed. Session: 6453856f-10b5-4a9b-947c-dcac902071d3.

Desired behavior

1. The engine reports each steer's real outcome (committed into the turn's record vs dropped).
2. steer_turn settles the item truthfully: Completed only on commit; dropped steers settle as canceled/not-delivered with an event, and the API returns a typed error (e.g. 409 turn-moved-on) so clients can requeue instead of trusting a lie.
3. Invariant (grokbuild's interjection tests in refs/grokbuild PTY suites): user guidance either reaches the model or is visibly returned — never silently dropped.

Acceptance criteria

• Regression test: steer accepted into the channel, turn ends before the engine commits it → API returns the typed drop error (or truthful not-delivered receipt); no turn.steered/item.completed success events for it
• Steer committed at a step boundary still produces item.completed (existing happy path preserved, test green)
• Focused cargo test -p codewhale-tui --lib --locked green for runtime_threads steer tests

Related

• Steered input is not inserted as the newest history entry: it lands above in-flight work and reads as out of order #6190 (the TUI-side honesty fix this mirrors)
• v0.9.14: unanswered user-input prompts stick in pending_user_inputs forever when their turn dies without the terminal settle #6275 (same turn-death settlement surface)

[Hmbown]

Engine + runtime API side is implemented; here is exactly what it does and does not fix

Landed locally (not yet pushed) as fix(runtime): report the steer the engine actually took, not the one it was sent.

Mechanism. SteerInput now carries an optional verdict channel, and
SteerInput::into_pending is the only way to claim a steer off it. The
resulting PendingSteer reports Accepted from commit() and Dropped from
Drop — so every exit path settles exactly once without anyone auditing exit
paths: wrong turn, empty text, interrupt, stream failure, early return, and the
engine itself going away. steer_turn persists the item queued and hands the
verdict channel to a detached settler, never to the caller, so a cancelled
or timed-out request cannot orphan the verdict and strand the item.

Verdicts: Accepted → item completed, steer_count rises, turn.steered +
item.completed. Dropped → item canceled, turn.steer_dropped carrying
the text, a reason and the settled item, and the API answers 409.

Also closed a trap this created: reconstruct_messages_from_turns had no
status filter, so a canceled steer item would have been replayed into the
model's context on restore — putting words into the context that the record
says were never delivered. queued/canceled user messages are now skipped.

What this fixes for the GPUI repro

codehwhale-gpui/src/workspace/mod.rs:2650 branches on exactly two outcomes:

Ok(())  => { clear the composer; notice = "Guidance sent." }
Err(e)  => { keep the composer; error = "... Check the conversation before resending guidance." }

So with no GPUI change at all:

• turn moved on / interrupted / failed → now 409 → Err → the composer
  keeps the user's text and they are told. This is the reported repro, fixed.
• delivered → Ok → "Guidance sent." Correct, and now actually true.

What it does not fix, and why

There is a third case the API cannot avoid. A steer sent while the engine is
inside a long tool call cannot settle until that call returns — minutes,
sometimes. An HTTP request must not hang that long, so after a bounded wait the
API returns 200 with the item still queued and the settler finishes
asynchronously.

GPUI reads that as Ok(()), clears the composer, and says "Guidance sent."
In that one case it is still claiming delivery it does not have. It cannot
do better today because runtime.rs:1097 discards the response body
(let _: Value = self.request(...)).

The GPUI-side follow-up is small and belongs in the client, not here:

• deserialise the returned TurnRecord, find the steer item, and branch on its
  status: completed → "Guidance sent."; queued → "Guidance queued — it
  reaches the model after the current step." and do not clear the composer
  until turn.steered arrives;
• treat turn.steer_dropped on the event stream as "resend this", restoring
  the text.

Filing that separately rather than widening this issue. Worth saying plainly:
until that lands, the honest claim is "the runtime no longer lies, and the
client no longer lies in the common case."

[Hmbown]

Landed in 27df0c6836, on main.

Acceptance, against the criteria in the body:

• Regression test for the drop path — steer_dropped_by_the_engine_is_reported_as_undelivered (runtime_threads/tests.rs). Shown failing without the fix: it returns Ok with steer_count: 1 instead of the 409.
• No turn.steered/item.completed for a dropped steer — asserted in that test; the item settles canceled and turn.steer_dropped carries the text so a client can requeue.
• Happy path preserved — steer_turn_on_active_turn_records_item_and_event still green.
• Focused suite — cargo nextest run -p codewhale-tui --lib -E 'test(steer) or test(runtime_threads) or test(runtime_api) or test(restart_rebuild)': 492 run, 492 passed.

Mechanism: SteerInput carries a verdict channel, PendingSteer reports Accepted from commit() and Dropped from Drop, so every exit path settles exactly once without anyone auditing exit paths. steer_turn hands the verdict to a detached settler rather than the caller, so a cancelled request cannot strand the item.

Also closed a trap this created: reconstruct_messages_from_turns had no status filter, so a canceled steer would have been replayed into model context on restore. queued/canceled user messages are now skipped.

One residual, filed separately rather than left implied: a steer sent behind a long tool call returns 200 with the item still queued, and the GPUI client reads that as delivered because it discards the response body. That is Hmbown/codehwhale-gpui#65.