Skip to content

feat(session-control): session_reload relaunches a created session - #15499

Merged
bolichen97 merged 1 commit into
kirodotdev:mainfrom
Pearcekieser:feat/mcp-session-reload
Oct 2, 2026
Merged

bolichen97 merged 1 commit into
kirodotdev:mainfrom
Pearcekieser:feat/mcp-session-reload

Conversation

@Pearcekieser

@Pearcekieser Pearcekieser commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: an agent can reload a session it created, so a config change it just made reaches that session without the person clicking Reload in the tab.

A live session mounts its MCP servers and builds its tool table once, when its agent process starts. A server granted later, a Settings MCP toggle, or an agent-spec fix never reaches it. The tab menu's Reload session item (POST /api/chat/slots/{slot}/reload) relaunches the process and keeps the transcript. No MCP tool does the same, so a conductor that changed a worker's MCP grant has to ask a human to click Reload, or close the worker and lose its conversation.

Why it matters

Conductors that dispatch workers now also change their configuration (MCP grants, agent specs). Without a reload verb, each change needs a human in the loop or throws away the worker's context. This PR gives the verb to sessions acting on workers they created; it is withheld from conductor and crew-member grants for now, as session_set_model was, so a conductor still gets an approval prompt until a later PR names the conductor step that needs it.

Not a goal

What changed (motivation → approach → change)

The tab menu already has a correct teardown with two locks, three identity re-checks, a rebind check, a busy probe, a sub-agent probe and a skip_if_busy reset with one retry. Copying it would let the two drift, so the locked body of api_chat_slot_reload moves into chat_handlers.reload_slot_session. The route and the new verb both call it and pass their own authorization as three callbacks (still_ours, denied, busy). The teardown passes still_ours an after_reset flag, so a caller knows whether the process is already gone without inferring it from call order. It also adds one re-check after the in-lock sub-agent probe, the last await before the reset. If the old process's shutdown raises after the session was popped, the teardown now finishes the reload (notice, respawn) and answers 200 with the switch handlers' existing old session teardown incomplete warning, using the same provider-identity probe as _reset_slot_session_or_warn; a raise before the pop still propagates. That is the one change to the route's responses: it used to answer 500 there.

session_control.reload_target is the verb:

  • authorize_target supplies the usual containment (same workspace, persistent, not app-scoped, not channel-linked or mirrored, not a scheduled run) and refuses self-reload. A caller is mid-turn, so a self-reload could never succeed.
  • Only sessions the caller created (not_creator otherwise), for every caller class. A reload relaunches a process a person may be using, so this verb is narrower than session_stop.
  • Remote-crew targets are refused (remote_target_unsupported), as session_set_model does.
  • A turn running or starting, queued messages, or attached sub-agents refuse with target_busy before any lock is taken. The same probe runs again inside the locks.
  • The whole gate re-runs after every await inside the teardown, including the sub-agent probe. If the target leaves the caller's reach or its slot is replaced during the reset itself, the process is already gone, so the call answers target_changed_during_reload instead of an ordinary refusal and is audited.
  • The reload notice text names the calling session's key; the notice meta carries only kind, as the route's does. Allowed and denied calls are written to the SEL.

Where each piece lives:

  • src/kiro_crew/dashboard/chat_handlers.py: the shared reload_slot_session teardown, called by api_chat_slot_reload.
  • src/kiro_crew/dashboard/session_control.py: reload_target, the gate and busy checks above.
  • src/kiro_crew/dashboard/handlers/session_control.py and src/kiro_crew/dashboard/server.py: POST /api/session-control/reload, registered in the strict internal-secret route set.
  • src/kiro_crew/mcp_dashboard.py, src/kiro_crew/validation.py and src/kiro_crew/data/mcp_tool_titles.json: the session_reload(target) tool, its schema and its title.
  • src/kiro_crew/channel.py: the tool joins CHANNEL_AGENT_BLOCKED_TOOLS. src/kiro_crew/agent.py records it as withheld from conductors, and no crew-member grant includes it.
  • src/kiro_crew/docs/session-control.md, src/kiro_crew/docs/index.md, and the architecture, feature-map and system-spec docs: the tool's documentation and its refusal codes.

Backwards compatibility

Compatible: the tab menu route runs the same checks in the same order and returns the same responses. It gains one identity re-check after the sub-agent probe, so a slot replaced during that probe answers the existing slot_not_found 404 instead of being reset. The rest is a new tool and a new route.

Tests

test/test_session_control_reload.py has 28 tests:

  • Happy path: reset and eager respawn, transcript unchanged apart from one notice naming the caller, agent, model and workspace kept, SEL allowed.
  • Refusals: not created, created by someone else, self, channel-linked, incognito, remote crew, turn running, turn the provider reports, queued messages, sub-agents attached.
  • Races: a turn starting inside the locks, a declined reset under a racing turn, a target linked or replaced while the call waits on its lock, a target linked during the in-lock sub-agent probe (refused, nothing reset), and a target linked or replaced during the reset (target_changed_during_reload, audited).
  • Teardown failures: a shutdown raise after the pop completes the reload with a warning and an allowed audit; a raise before the pop answers reload_failed (500), audited, with nothing torn down.
  • Route: 403 without the internal secret, success, busy as 409, and presence in the strict internal set.
  • MCP tool: passes the verified caller key, renders a busy refusal as an error, renders target_changed_during_reload as "reset, no notice" rather than "could not reload", renders a degraded-teardown warning as a completed reload, and takes no agent, model or workspace argument.

test/test_pending_boundary_consumer_semantics.py gains reload_target in its list of busy-predicate readers, beside set_model_target.

The in-lock gate, the re-check after the sub-agent probe, the in-lock busy probe and both post-reset branches were each checked by mutation: removing them makes a test fail. The registration, doc and refactor-contract tests were updated for the new tool.

Manual verification

N/A. No UI change. The route and verb are covered end to end through the aiohttp handler and the MCP tool dispatcher in the tests above.

Related Issues

Fixes #15449

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

Contribution License Agreement

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Intent: let an agent reload a session it created, the same relaunch the tab menu's Reload session performs, so a config change it made (MCP grant, agent spec) reaches that session without a human click and without losing the conversation.
Not a goal: changing agent, model, workspace or effort on reload; automatic reload at a turn boundary (#14810, RFC #15409); reloading sessions the caller did not create, busy sessions, or every session at once.

@Pearcekieser
Pearcekieser marked this pull request as ready for review September 30, 2026 17:01
@Pearcekieser
Pearcekieser requested a review from a team as a code owner September 30, 2026 17:01
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: checking Automated validation is still running merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Sep 30, 2026
@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of 0449f50f9d975d2554d37d3c7fb175b88c096273 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

The route's post-pop teardown failure now answers 200 + warning where it answered 500 — confirm the tab UI surfaces or safely ignores that warning.

[DESIGN-REVIEWED] 0449f50

Description read

[DESCRIPTION-READ] 76e53b4e3aa6c47d8ede9d3e25deebce803953c671fb31d86a1e16905a013c34

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

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

Premise-level review of 0449f50f9d975d2554d37d3c7fb175b88c096273 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 the tab-menu route's 500→200-with-warning change: chatSlotSettings.ts:61 types the body {ok, error}, so the new warning is silently dropped in the UI.

What this change ships

Inventory (9 items) — 9 justified

Intent: an agent can relaunch a session it created so a config change it made reaches that session without a human clicking Reload — ADDITION (linked issue #15449; auto-reload explicitly excluded as covered by RFC #15409, draft-equivalent and not relied on here).

  1. Agents get a session_reload tool and route relaunching a session they created — justified
  2. Targets must be idle, local, caller-created; self-reload refused — justified
  3. Channel agents, conductors and crew-member grants never get the verb — justified
  4. Tab-menu Reload: a post-pop teardown failure now answers success-with-warning instead of 500 — justified
  5. Tab-menu Reload: a slot replaced during the sub-agent probe now 404s instead of resetting — justified
  6. One shared teardown (reload_slot_session) behind both the tab menu and the verb — justified
  7. New refusal codes for reload callers (target_busy, target_changed_during_reload, reload_failed, target_replaced) — justified
  8. The target's transcript gains one notice naming the reloading session — justified
  9. Docs, feature map and tool catalog list the 28th session-control tool — justified

Checks run: session_reload|reload_target|reload_slot_session over base src/ finds no existing agent-facing reload (only the tab route this verb reuses, so no second spelling); _TEARDOWN_INCOMPLETE_WARNING has 5 existing base consumers, so item 4 reuses an existing mechanism rather than inventing one; the creator fence reuses _created_by_other (13 base uses in session_control.py). Not product shape: a new verb beside the existing route, blocked by default for every unattended caller class.

[FIRST-PRINCIPLES-REVIEWED] 0449f50

Description read

[DESCRIPTION-READ] 0365b65655ce1c38aa94dcc25d56b7e0c5a79c8b69f6a33266dad6798c452400

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] 0449f50

@Pearcekieser
Pearcekieser force-pushed the feat/mcp-session-reload branch from 6fdc30c to f4ca8fd Compare September 30, 2026 18:00
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased onto main after session_end_wait landed. The conflicts were only in the tool lists (architecture MCP table, feature map, docs index, session-control page, withheld-verb comments in agent.py), resolved by keeping both tools. The documented tool count went from 24 to 25 and the session-control group count in test_session_control_doc.py from 14 to 15. No behaviour change. The targeted tests (1258) pass.

@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 0449f50

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Sep 30, 2026
@Pearcekieser
Pearcekieser force-pushed the feat/mcp-session-reload branch from f4ca8fd to 939f861 Compare September 30, 2026 20:30
@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • span=36bec42fc986 issue (blocking, security): Authorization can become stale before teardown

Outcome: fixed in 939f861.
The finding holds. The in-lock _subagents_attached_response probe is an await that ran after the last still_ours() and before _reset_slot_session, so a channel link or mirror landing during it reached the teardown on authorization read before that await. The adjudicator's note covered the two lock-acquisition re-checks but not this later await.
reload_slot_session now calls still_ours(False) after the probe (and after the test seam), immediately before the reset, so a refusal there still means nothing was torn down. test_a_target_linked_during_the_children_probe_is_refused links the target during the in-lock probe and asserts linked_session_target with the reset never awaited; it fails with the new re-check removed.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • span=9e349aab0a7d Watch: post-reset detection rested on an implicit call-order contract

Outcome: fixed in 939f861.
The phase is now explicit in the shared contract: reload_slot_session passes still_ours(after_reset), True only for the re-check after _reset_slot_session. reload_target dropped past_probe and _busy_in_lock and reads the flag. The new pre-reset re-check after the sub-agent probe (the GPT fix) is exactly the edit this item predicted would misreport under the old scheme; with the flag it refuses as an ordinary pre-reset refusal, pinned by test_a_target_linked_during_the_children_probe_is_refused.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • span=a355ff668dd4 Suggestion: return a structured result from reload_slot_session

Outcome: addressed by the smaller change in 939f861, not the full restructure.
The part of this suggestion that removes a hazard, dropping the past_probe state machine, is done by passing after_reset into still_ours. Returning a structured result would also remove the json.loads(response.text) mapping in reload_target, but that means changing the route's return path, which this PR keeps byte-identical. The body parse is one mapping table (_reload_route_refusal) covered by the busy and replaced-slot tests, so I left it.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • span=8b9de25a113e Not justified as shipped: reloaded_by notice meta key with zero consumers

Outcome: fixed in 939f861, deletion made.
The notice_meta parameter of reload_slot_session and the reloaded_by meta key are gone; the notice meta is {"kind": "session_reload"} for both callers, as on base. The caller key stays in the notice text and in the SEL audit detail. The transcript test now asserts reloaded_by is absent from the meta.

@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 30, 2026
@Pearcekieser
Pearcekieser force-pushed the feat/mcp-session-reload branch from 939f861 to 5901ad7 Compare September 30, 2026 22:45
@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • span=61f08a343bfd Watch: the motivating caller (a conductor) is withheld the verb

Outcome: deliberate deferral, now stated in the PR body.
Withholding is intentional and follows the session_set_model precedent: the conductor withheld-list convention in agent.py grants a verb only once a conductor step is named that needs it, and this PR names none. The body's motivation paragraph now says so, so it no longer claims more than ships: the verb serves sessions reloading workers they created, and a conductor still gets an approval prompt until a later PR adds the grant with its step.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • span=a294930262a0 issue: the MCP tool renders target_changed_during_reload as "could not reload"

Outcome: fixed in the next push (single commit, rebased on main).
The finding holds: the tool's generic error branch told the agent the reload did not happen for a process that was already torn down. session_reload now checks code == "target_changed_during_reload" (the code survives _http_error_body) before the generic branch and says the process was reset and no notice was added. test_tool_reports_a_changed_target_as_reset_not_refused covers it and fails with the branch removed.

@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 30, 2026
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased the same commit onto main 4224aa2 with no behaviour change (head 91b7918), to pick up main's fix for the inherited fold-catalogue / lesson-turn-injection reds. 310 targeted tests pass.

@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 Oct 1, 2026
@Pearcekieser
Pearcekieser force-pushed the feat/mcp-session-reload branch from 91b7918 to ebce660 Compare October 2, 2026 00:00
@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • span=36bec42fc986 issue (blocking): handle post-pop reset failures

Outcome: fixed in ebce660.
SessionManager.reset pops the session before a deferred shutdown error is re-raised, so the old process is already gone when the raise reaches the reload. reload_slot_session now captures the registered provider before each reset and, on a raise, uses the same identity probe as _reset_slot_session_or_warn. If a different provider (or none) is registered, the teardown happened: the reload logs it, writes the notice, schedules the respawn and answers 200 with old session teardown incomplete. If the same provider is still registered, the raise came before the pop and still propagates; reload_target then audits it as denied and answers reload_failed (500), nothing torn down. The fix sits in the shared teardown, so the tab menu's route gets the same handling. Tests: test_a_shutdown_raise_after_the_pop_still_completes_the_reload and test_a_raise_before_the_pop_is_reported_and_audited, each red with its half of the fix removed. The docs list reload_failed and the warning.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • span=0f7a335383d2 issue (non-blocking): spec names session_end_wait as the only all-caller creator fence

Outcome: fixed in ebce660.
reload_target's creator check has no ownership_fenced guard, so it binds owner and Global V1 callers the same way end_wait_target's does. docs/system-specs/modules/session-control.md now names both session_end_wait and session_reload as the exceptions.

@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 Oct 2, 2026
…agent process

Adds a kirocrew-dashboard MCP tool and POST /api/session-control/reload. It reloads an idle session the caller created the way the tab menu's Reload session does: the agent process is torn down and the resume spawn re-armed, so the new process re-reads its agent spec, environment and MCP servers while the conversation is kept. The target's transcript gets the reload notice naming the calling session.

The teardown moves out of api_chat_slot_reload into chat_handlers.reload_slot_session, which both the route and the verb call with their own authorization callbacks, so the lock order and re-checks are shared. The verb refuses self, not-created, remote-crew and busy targets (turn running or starting, queued messages, sub-agents) and re-runs its gate after every lock await. Blocked for channel agents and withheld from conductors and crew members.
@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 Oct 2, 2026
@Pearcekieser
Pearcekieser force-pushed the feat/mcp-session-reload branch from ebce660 to 0449f50 Compare October 2, 2026 01:45
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

chore (non-blocking): rebased onto main fa37aa54fd with no code change (same single commit, now 0449f50f9d). This picks up #16032, which fixes the inherited flake8 F811 in autonudge.py that failed Backend Lint on ebce6605ed. The other two reds on that head (test_session_export shard 3, Windows test_usage shard 6) are in files this PR doesn't touch; they rerun here. All review lanes passed on the previous head with no findings.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 2, 2026

@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.

Approved: PR Readiness green on this head, merges cleanly into current main, no outstanding blocking review.

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-control: session_reload relaunches a created session's agent process from another session

3 participants