Skip to content

feat(session-control): let session_send steer a busy target's running turn - #11920

Closed
chenmingwei23 wants to merge 1 commit into
kirodotdev:mainfrom
chenmingwei23:feat/session-send-steer-11919
Closed

chenmingwei23 wants to merge 1 commit into
kirodotdev:mainfrom
chenmingwei23:feat/session-send-steer-11919

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Sep 19, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

A session that sends to a busy peer has to wait for it. session_send could only
start a turn on an idle target or put the message in the queue, so a conductor
watching a worker head the wrong way could not say so until the worker finished
the work it wanted stopped. The tool's own description offered to "steer it
mid-run", which it could not do.

The same fleet pattern already behaves differently by worker type: a subagent can
be corrected mid-flight with spawn_steer, a peer session cannot.

Why it matters

Long turns are where the wait hurts. The worker spends minutes on work that is
already ruled out, and the correction is read after that work has landed, often
after it was pushed. The mid-turn path existed and only the composer could reach
it, so the cost was a missing wire, not a missing capability.

What changed (motivation, approach, change)

session_send takes an optional steer. On a busy target it cuts the message
into the turn already running instead of queueing it, so the target reads the
correction while the work is still in flight.

Target state steer omitted steer: true
idle starts a turn starts a turn
busy queues for the next turn cuts into the running turn
busy, injection unavailable queues queues, and the caller is told the steer did not land

The injection is the composer's own path, steer_into_running_turn, not a second
mechanism. Both delivery arms hand over one text: redacted through
sanitize_outbound and prefixed with [sent by session <caller> via session_send]. So an injected message cannot read as something the person typed,
which is the property that keeps app-authenticated composer sends off the steer
path.

Two things guard the new arm. The queue arm records the containment that held
when the message was admitted, and the drain re-asserts it, because a queued
message runs later than it was authorized. A steer runs inside the window
authorize_target just cleared, so there is nothing to re-check. The one
suspension the arm adds is the steer RPC itself, so a steer that cannot be
injected re-runs the gate before falling back to the queue. Without that, a
target that gained a channel link during the RPC would have that link stamped as
"held at admission" and the drain would read a widened audience as the authorized
one. A target whose key resolves to a different session during the RPC is refused
with target_moved.

steer is a delivery mode, not a permission. authorize_target still decides who
may send, and a crew-bound (executor == "remote") target is still refused before
either arm. The flag is type-checked at both entry points, because the string
"false" is truthy and coercing it would interrupt a turn for a caller that asked
for the queue: the tool schema in src/kiro_crew/validation.py types it strictly
and defaults it false, and the route in
src/kiro_crew/dashboard/handlers/session_control.py refuses a non-boolean with
invalid_steer. The delivery arms live in
src/kiro_crew/dashboard/session_control.py, and
src/kiro_crew/mcp_dashboard.py declares the parameter, forwards it, and reports
which of the three outcomes happened.

The result now carries steered beside started, so a coordinator can tell an
injection from a started turn from a queued message.

The owning spec, docs/system-specs/modules/session-control.md, gains the steer
arm. Two sentences in the same section said the queued arm's second authorization
moment was unenforced and tracked as #5911; the drain re-check has since shipped
(newly_held_constraints, called from chat_runner), so they are corrected
rather than left contradicting the paragraph above them.

Backwards compatibility

Compatible: steer defaults to false at both entry points, so a caller that omits
it keeps today's queue-or-run behaviour, and steered is an added response field
rather than a changed one.

Tests

test/test_session_control.py covers the delivery matrix against the real
steer_into_running_turn and a steer-capable client, not a stub: a steer lands in
the running turn and leaves exactly one transcript row with the provenance
envelope on both the injected text and the row; a client that cannot take it falls
back to the queue; a steer the turn's teardown requeued is not queued a second
time; an idle target never enters the steer path; and a busy target with a live
client still queues when steer is not asked for.

test_the_queue_fallback_re_runs_the_gate_after_the_steer_rpc links the target
during the RPC and asserts the send is refused with linked_session_target and
nothing is queued. Removing the re-gate queues the message, which is the defect
the test exists for.

test/test_mcp_dashboard_session_send.py covers the tool layer: what it forwards,
the three outcome reports, and the schema refusing a non-boolean. The route's own
invalid_steer refusal is tested beside the existing send route tests.

Manual verification

Run in an isolated pod built from this branch, against a real kiro-cli backend.
No fixtures, no mocked event stream. Two sends, identical in every way except the
flag, both issued while the target was confirmed mid-turn.

Without steer, the send queues: {"started": false, "steered": false}. The
target's transcript then holds TWO assistant turns -- it finished writing all 120
numbers first, and only answered the injected message afterwards, in a second
turn.

With steer: true, the send is injected: {"started": false, "steered": true}.
The transcript holds ONE assistant turn, and the injected row sits ahead of the
reply rather than after it.

The still frame below is the whole claim in one image: the peer's message rendered
with a Steering... badge and its [sent by session <key> via session_send]
envelope, the assistant's output still streaming underneath it (caught mid-word at
ninety-fi), the sidebar row reading Streaming, and the composer's stop button
live. The turn was running when the message landed.

steer-mid-turn.mp4

steering badge while the assistant is still streaming

One thing this does not show, stated plainly: the model read the steer and chose
to finish counting anyway, closing with an offer to stop if asked directly. The
feature's contract is delivery into the running turn, which is what is proven
here. Whether the model obeys mid-stream is the model's business, not this
change's.

Also checked by hand: {"steer": "false"} is rejected with HTTP 400
invalid_steer rather than coerced true, and a steer: true send to an IDLE
target falls through to the normal start arm and reports steered: false.

recorded from 31dcb97 - worktree pod on an
isolated port and data dir - real server + real model, no fixtures

Related Issues

Fixes #11919

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|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

@chenmingwei23
chenmingwei23 requested review from a team and CrysisDeu September 19, 2026 00:17
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Intent: Let one session correct a peer session while its turn is still running, by wiring session_send to the mid-turn injection path the dashboard composer already uses, behind an opt-in steer flag that falls back to the queue rather than dropping the message.
Not a goal: widening who may send (authorization stays authorize_target's), steering crew-bound targets, changing the composer's own steer path, or changing behaviour for callers that do not pass the flag.

@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 19, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/session-send-steer-11919 branch from 5333050 to 31dcb97 Compare September 19, 2026 00:33
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

All four red lanes on the previous head had a single cause, and it was mine.

scripts/check_comment_history.py flagged one added comment line in
src/kiro_crew/dashboard/session_control.py (the STEER_UNAVAILABLE fallback
block, around line 2395): it read "the state it would record is no longer the
state this send was authorized against", and "no longer" is history narration
the gate correctly rejects. Everything else followed from it:

  • Comment History Gate failed, so Fast Gate failed.
  • CI's "Await Fast Gate" job waits on the Fast Gate verdict for the commit, so
    it failed too, which skipped every downstream test lane.
  • Coverage Gate fails closed when its upstream coverage jobs are skipped, so it
    failed on frontend-test=skipped.
  • PR Readiness aggregated the above.
  • The fork AI review lanes are stage 2 of workflow_run on Fast Gate and are
    gated on conclusion == 'success', so none of them triggered. That is why the
    GPT and Opus markers named an older head rather than this one.

The comment now states the condition in the present tense ("the RPC above
suspends, so the state it would record can differ from the state this send was
authorized against"), which keeps the reason the re-gate exists without
narrating history. Comment-only change, no behaviour touched.

Verified before pushing: check_comment_history.py against base a170442 passes
with an exact merge-base (CI measured against the base tip and warned its verdict
could be inexact; the local run is the precise one, and it agrees the line was a
real violation). black, isort and flake8 clean on the file.
test/test_session_control.py and test/test_mcp_dashboard_session_send.py:
204 passed.

New head: 31dcb97

@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 19, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Opus 4.8 Review (fork) — ⚠️ review incomplete

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

No completed Opus verdict for this commit; see the Fork Opus 4.8 Review job logs.

@github-actions

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — ⚠️ could not complete

The first-principles review did not produce a verdict for 31dcb972bc7ad84436376bc4c95ae109f2c664d3 (the review step failed). See the Fork First Principles Review job logs. Advisory — does not block merge.

@github-actions

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ⚠️ could not complete

The design review did not produce a verdict for 31dcb972bc7ad84436376bc4c95ae109f2c664d3 (the review step failed). See the Fork Design Review job logs. Advisory — does not block merge.

@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 19, 2026
@github-actions

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ⚠️ review incomplete

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

No completed GPT verdict for this commit; see the Fork GPT 5.6 Review job logs.

Captured review output -- no verdict stamp for this commit, so this is NOT a verdict

Incomplete review: pass(es) 1 2 did not complete.

The pass-2 verdict was not published because both calls are required. Re-run the workflow for a complete review.

… turn

session_send could only start a turn or queue for the next one, so a caller watching a peer session go the wrong way had to wait out the work it wanted stopped. An optional steer flag now injects the message into the turn already running, through the same steer_into_running_turn path the dashboard composer uses.

Both arms hand over the same redacted, provenance-prefixed text, so an injected message cannot read as human typing. A steer that cannot be injected falls back to the queue, and that fallback re-runs authorize_target because the steer RPC suspends: without it the queue would stamp a containment snapshot the authorization never saw.

Closes kirodotdev#11919
@chenmingwei23
chenmingwei23 force-pushed the feat/session-send-steer-11919 branch from 31dcb97 to 77764a8 Compare September 19, 2026 16:16
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Sep 19, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Superseded by #12048, which carries this exact commit from a same-repository branch.

Verified before closing: both heads are the same commit 77764a8f383a8c3f6832e1f399ee4fdf5c53281e and both resolve to the same tree 987ec95677167dc0c8310f8f6402118ea9f21e30. No code was edited for the move.

Why the move was needed rather than a wait or an override. The two required review lanes never produced a verdict on this fork branch. Both check-runs read review incomplete, and the fork Opus run created for this head at 16:17:06Z (run 35454458337, event=workflow_run) failed with connect ECONNREFUSED 54.185.253.63:443 three times, then bun: command not found, then exit 127 at 16:18:57Z, before a single model call. That is #11911: the six fork-* review workflows set harden-runner egress-policy: block with objects.githubusercontent.com allowed but not release-assets.githubusercontent.com, which is where setup-bun now fetches bun. Fork lanes execute the default branch's copy of their workflow, so no push to this branch could change the allowlist they run under, and the fix (#11976) is still open.

The same-repository review workflows carry no egress block at all, so #12048 can actually be reviewed. Everything else on this head was already accounted for: 89 lanes deduplicated to the newest run per workflow gave 75 success, 10 skipped, 2 neutral and zero pending, with mergeable=MERGEABLE; the only failures were the two lanes above and the PR Readiness status that aggregates them. No override was requested and no review was dismissed.

@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Sep 19, 2026
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.

session_send cannot steer a busy target: every message waits for the next turn

1 participant