Repository navigation
feat(session-control): broadcast to a fleet, and a roster that remembers a lost worker - #14185
Conversation
Design Review (Fable 5) — ✅ PASSDesign-level review of Design-Verdict: PASS Description table says [DESIGN-REVIEWED] 20adedc |
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Verify the one unattended widening: The grant's argument is the fence's own (default audience read from the same No existing mechanism duplicates either verb: every What this change shipsInventory (10 items) — 10 justifiedIntent: let a session that dispatched workers message all of them in one call and see which are still alive — an ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 20adedc |
GPT 5.6 Review — ✅ no blocking findingsGPT 5.6 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
|
Intent: Let one session address the fleet of workers it dispatched, and find out which of them are still alive -- a broadcast with an explicit queue-vs-steer mode, and a roster whose durable half reports a worker that was closed or lost as |
e667d02 to
3d66457
Compare
Opus 5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
|
self-added: yes
|
3d66457 to
3ded9ae
Compare
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
3ded9ae to
401f1d8
Compare
|
self-added: yes
|
401f1d8 to
eababb9
Compare
|
self-added: yes
|
Marker removed: this comment named a span id I wrote by hand rather than one from |
Marker removed: this comment named a span id I wrote by hand rather than one from |
|
PR Hygiene was failing on main's template, not on the diff: Rebased |
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
|
self-added: yes
|
|
Rebased |
|
disposition: fixed span=06afe54baead head=9f5fdd7d7549f631441b1c7802cb580e9795c966 Confirmed against the code, and the mechanism is worse than a lost row. Fixed as suggested: Pinned by
|
|
disposition: fixed span=2f6082500a24 head=9f5fdd7d7549f631441b1c7802cb580e9795c966 Correct, and verified independently: Rewritten to say both verbs refuse an app-scoped CALLER ( |
|
disposition: fixed span=4464213526e3 head=9f5fdd7d7549f631441b1c7802cb580e9795c966 Same row as the GPT lane's finding on Took the second remedy you offered — dropping the |
|
Rebased: onto main at Resolved as a union rather than a side: the tool-schema import list takes both names, the MCP tool count and the docs count come from Scoped re-run for the overlapping files: 401 passed ( |
…ers a lost worker session_broadcast sends one message to several sessions in a required queue or steer mode; session_status lists the sessions a caller stood up, taking the roster from the crew log's session tree so a worker that was closed or lost is reported gone rather than silently absent. Both route through the existing per-target gate, so neither reaches anything a session_send could not. The caller-side half of that gate is extracted into two shared helpers rather than copied, keeping one implementation for the verbs that have no target.
|
disposition: fixed span=36bec42fc986 head=dc8969c300c322a66c8fbb5f68a3acb8a00350c0 Confirmed, and it is the other side of the invariant the previous round fixed in Fixed as suggested: One deliberate difference from the status verb: the refusal is raised AFTER the allowed audit, not before. Each delivery was individually gated and has already happened, so the trail has to record them, and the refusal message says what is actually withheld — the per-target report — with an explicit "do NOT send the same text again". A caller that read this as a failed broadcast would deliver the same text twice, which is the harm the per-target rows exist to prevent. Pinned by New refusal code documented in the package-shipped |
|
disposition: fixed span=a294930262a0 head=dc8969c300c322a66c8fbb5f68a3acb8a00350c0 Correct, and it was a real CI red rather than only a table gap: Added to This one surfaced only after the rebase onto main, which is where the title table arrived; the lane had no such test on the previous head. |
|
disposition: fixed span=36bec42fc986 head=47c2764c48e4241b3990a44e51fecf6e261d9168 Confirmed, and it settles a call I got wrong two rounds ago. The Opus lane offered two remedies for the same row: filter the live rows through Fixed by membership in The row is dropped rather than reported title-less, on the grounds the loop's own workspace clause already states: Pinned by three cases in The feature-map sentence I wrote last round is now wrong in the other direction, so it is corrected too -- both verbs apply the same target containment; only the target-taking one can RAISE The three fix commits are squashed into one, so the PR is back to 2 commits for PR Hygiene. |
|
disposition: fixed span=36bec42fc986 head=1cee89f2876b91a35765cfac6346a625495c9c0a Confirmed, and it is a loss path the shield itself opened. Traced: Fixed as suggested: the retained delivery now carries its own post-outcome handling. Pinned by |
|
disposition: fixed span=2f6082500a24 head=1cee89f2876b91a35765cfac6346a625495c9c0a Correct -- my own sentence from the previous head, and it overstated in exactly the way described. The Rewritten to say what the containment actually buys: a contained session contributes no title and no live status, while a session the attested tree recorded still leaves its TITLELESS Worth naming why this row is not itself the leak: |
… both verbs Three review rounds, one invariant: a gate's verdict does not survive an await, and both verbs return payloads naming the caller's own private sessions. `session_broadcast` steer delivery. The per-target budget added for a wedged target cancels the awaiting frame, and `steer_into_running_turn` guards its own `client.steer` with `except Exception`, which does not catch `CancelledError`. A bare await therefore unwinds THROUGH the RPC and skips that coroutine's single reconciliation tail while the bytes may already have reached kiro-cli: the turn runs text no `slot.append` recorded, and the six per-text steer maps are never popped. Nothing else pops them -- `_settle_consumed_steers` clears only the attachment and decision-strip maps, and `_requeue_unconsumed_steers` returns early once settling emptied `_pending_steers` -- so the surviving `_steer_delivery_ids` entry refuses that exact text on the slot forever and `retained_steer_count` never falls back below `MAX_PENDING_STEERS`. Awaiting a shielded task splits the two halves: the frame still receives the cancellation, so the broadcast reports its timeout row on schedule, while the delivery runs to its own end and reconciles itself. The task is held in a module-level set so the loop cannot collect it mid-RPC. `session_broadcast` report. The entry gate runs once, before any audience is read, and this verb then suspends once per delivery. A channel mirror can be bound onto an already-open dashboard session in that window, so a payload built under the entry gate reaches that channel's audience carrying private session keys. Re-call `refuse_caller_surface` and compare the workspace captured at entry, immediately before the return -- raised AFTER the allowed audit, because each delivery was individually gated and has already happened, so the trail must record them and the refusal must say that what is withheld is the REPORT. `session_status` rows. The roster loop re-stated only the ownership fence and the workspace boundary, and the four clauses it did not re-state are exactly what leaked: a worker linked or mirrored to a channel AFTER birth kept appearing, and its `display_title` is derived from a conversation other people are in. Live rows now pass `_broadcast_resolution_slots`, the same predicate the sibling verb resolves names against, so one place enforces the containment instead of two drifting copies. Slot identity is deliberately not compared anywhere here: `get_or_create_slot` short-circuits an existing key and the single `put_slot` runs only where the key was absent, so no live key is rebound to a new object and such a check could never fire. Also declare `Tool.title` for both new tools in `data/mcp_tool_titles.json`, and correct the feature-map row: both verbs apply the same target containment, but only the target-taking one can RAISE `app_scoped_target`.
|
disposition: fixed span=2f6082500a24 head=c898937756f2a99a2eb20eaf612588168ea245a4 Correct, and checkable in this PR's own suite: Fixed as suggested, one phrase: the Not overridden. The statement was false about behaviour this PR's own test pins, and the correction costs one clause. |
|
Reviewed at head Nothing blocking. The gate extraction keeps the inline order (identity before resolution, surface after), the broadcast audience is read from the same [code-reviewer] 🟡 [Correctness]: In [code-reviewer] 🟢 [Consistency]: the timeout observation resolves the name unrestricted
[code-reviewer] 🟢 [Description]: PR body states the cap as 32; the code and both docs say 50 The "What changed" table lists Verified clean, for the record:
|
buluoray
left a comment
There was a problem hiding this comment.
Approving at this head. The three notes in my earlier comment are non-blocking: the silently dropped session_status row for a worker whose containment changed (🟡), the unrestricted timeout-observation lookup (🟢), and the stale cap of 32 in the PR body (🟢). They are fine as follow-ups.
Problem / Motivation
Goal: A session that dispatches workers can address all of them in one call, and can see which of them are still alive.
A session that dispatches workers can say one thing to one worker, and cannot find out which workers are still alive.
session_sendtakes one target. A conductor holding eight workers that must tell all of them "the base moved" writes eight calls and tracks by hand which ones landed. There is no way to say "interrupt all of them", so the urgent case costs the same eight round trips as the patient one.There is also no roster.
list_sessionsreads the durable catalog, so it does list a closed session -- but it reports neither who CREATED one nor whether it is still running, so a conductor cannot tell a worker still working from one that died with its process, and cannot pick its own workers out of every session in the workspace.Why it matters
Both gaps fail silently.
A hand-written loop of
session_sendcalls that dies partway leaves no record. The conductor's own reasoning is the only place that knows targets four through eight never got the message, and a compaction takes that with it. A worker that missed "the base moved" pushes against a base that moved.The missing roster is worse, because the absence reads as success. A patrol sees seven live workers, decides the eighth finished, and never re-dispatches it. The work item is dropped and nothing reports a failure.
Not a goal
gone, which conflates them; the roster's job here is that neither disappears. Deferred to issue session_status: a gone row cannot tell a finished worker from a lost one #14213.steer_into_running_turncancellation-safe. Its maps are left populated on cancel and the teardown requeue is what saves the message, so unwinding them would DISCARD text instead of delivering it late. That affects every steer caller, not just broadcast, and belongs in its own change.created_bythe ownership fence already trusts.queueandsteerare the two the backend already has; broadcast fans them out and adds none.What changed (motivation → approach → change)
session_broadcastqueueorsteersession_statusgonetreeMAX_BROADCAST_TARGETSBROADCAST_TARGET_ALLOWANCE_SECSdelivery_timeoutTwo new tools on the
kirocrew-dashboardsession-control server: schemas insrc/kiro_crew/validation.py, tools insrc/kiro_crew/mcp_dashboard.py, verbs insrc/kiro_crew/dashboard/session_control.py, routes insrc/kiro_crew/dashboard/handlers/session_control.pyandsrc/kiro_crew/dashboard/server.py, docs insrc/kiro_crew/docs/session-control.mdanddocs/system-specs/modules/session-control.md.session_broadcastcalls the existingsend_to_targetonce per target, so every bound already there holds per delivery and it reaches nothing asession_sendcould not. Its default audience reads the same_created_byfield the ownership fence reads, so it is a subset of what the fence admits; an explicit target is bound instead by that same fence running per delivery.modeis required with no default:queueandsteerare different instructions, and defaulting either way substitutes one for the other across a whole fleet.Deliveries run one at a time, each under its own bound, and a refusal is a ROW rather than an abort. The bound is what makes sequential delivery safe: one session that never answers would otherwise starve every session behind it, and the steer it suspends on has no ceiling -- so the urgent "stop, that is already fixed" would reach two of eight workers. On expiry the delivery is cancelled, reported as
delivery_timeout, and the loop moves on. That row does NOT claim the target missed the message, because the cancel can land after the target consumed it; the honest answer is that this side stopped waiting and the outcome is unknown, which is why it is a separate code from a crash.Partial delivery is normal: the caller is told which targets got the message. An explicitly empty
targetsis refused, never read as "everything". Duplicates go by RESOLVED session, not spelling, since a key and a title can name one worker. One name bounds the cap and one bounds the delivery allowance, each read by both the schema or client and the verb.session_statusneeds three sources because none answers alone. The live slots know what is running but forget a session the moment it is gone -- exactly the worker a patrol must not lose -- so the roster also comes from the crew log's durable session tree. That tree's edge is written at a session's first turn, so a worker that died earlier is in neither: transcript metadata supplies those, at thecreated_bythe fence already trusts. Every row names its source, and a history row isunknownrather thangone: metadata proves a birth, not whether it finished. Both durable reads can be partial, sotreeandhistoryeach carry their own quality and anincompletecount is a floor. The fence applies to the rows too, since a row carries another session's title.Supporting work. The caller-side half of
authorize_target's gate moves into two shared helpers -- two and not one, because the gate runs them on opposite sides of its target resolution. Both tools join the channel-agent block list insrc/kiro_crew/channel.py. Insrc/kiro_crew/agent.py,session_statusis granted to the conductors andsession_broadcastonly to a crew member. TheSession controlrow indocs/feature-map/README.mdgains both verbs, both endpoints and the app-caller refusal.Backwards compatibility
Compatible: two new tools, two new routes and two new grants. No existing argument, response field, refusal code or grant changes, and the gate's extracted helpers keep every check, code, message and call order they had inline.
Tests
97 new tests in three files.
test/test_session_broadcast.pycovers the audience (default set, the caller excluded, sessions it did not create excluded, stable order, dedup, a blank list refused, the cap refused rather than cut), both modes and the missing-mode refusal, partial delivery (a refusal collected while siblings still receive, an unexpected failure given its own code, sequential execution proved by an overlap counter), the caller gate, the route, and an end-to-end class that stubs no layer: the tool call through the real handler into two real slots.test/test_session_status.pycovers all four statuses including a plan's between-stages gap, thegonerow and its absent title, all threetreequalities including a raising projection, the fence on rows, the workspace boundary, and that the targets are unchanged afterwards.Four of those pin the repairs this PR's own review found, each proved failing before the fix: an empty
targetsreaching nobody, two spellings of one session delivering once, the request timeout derived from the cap, and one name bounding both caps.test/test_mcp_dashboard_session_broadcast.pycovers the prose the model reads: every row outcome including a steer that fell back to a queue, the missed-target warning present only when something was missed, and eachtreecaveat.Two source-shape pins are taught the new shape rather than loosened.
test/test_queue_drain_revalidation.pyparses the gate's refusals from source; the gate is now three functions, so it parses all three and names one refusal from each, which catches a whole function going missing instead of reporting eight refusals as deleted.test/test_pending_boundary_consumer_semantics.pyenumerates every reader of a slot's running state, so the roster verb is declared there as one.Ratchets updated where they pin the tool set by count or membership:
test/test_session_control_doc.py,test/test_mcp_dashboard_registration.py,test/test_mcp_dashboard_folders.py, and the grant pins intest/test_conductor_agent.py,test/test_pipeline_conductor_agent.py,test/test_security_conductor_agent.pyandtest/test_member_dispatch_mount.py.Manual verification
N/A -- the end-to-end class drives the real MCP tool through the real HTTP handler into real slots, which is what a manual run would do.
Four mutations were checked to prove the tests discriminate, each caught, with the file restored byte-identically (sha256 verified): dropping the broadcast provenance, forcing every delivery to the queue, aborting on the first refusal, and widening the default audience to every slot.
Related Issues
no linked issue: a new feature carries its context in the PR.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)