Repository navigation
feat(session-control): session_revive brings an archived session back to the sidebar - #13110
Conversation
|
Intent: Give agents the mirror of |
|
👋 Hi! This PR is currently in draft status. Workflow runs won't be auto-approved until it's marked as ready for review. When you're ready, click "Ready for review" and the workflows will be approved on the next cycle automatically. |
2f4a5de to
6dfdfbe
Compare
Design Review (Fable 5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS Verify the dashboard's History-click resume tolerates the new coded 409/503 refusals ( [DESIGN-REVIEWED] 8a1df24 Description read[DESCRIPTION-READ] 461c4801e91c4c3fc55be1d05ca7bb9b9fbb824f41a540960084defcdd324cb4 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 |
First Principles Review (Fable 5, fork) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Every dashboard History click now flows through the rewritten resume core — verify wire parity of that endpoint by hand, not just by the new tests. The capability is derived, not inherited: base ships at least 2 tool descriptions ( Inventory (10 items, capped) — 10 justifiedIntent: let an agent bring a closed session back into the sidebar with its transcript, as
[FIRST-PRINCIPLES-REVIEWED] 8a1df24 Description read[DESCRIPTION-READ] 4f90894d8cd944fc41bacde8c9085638ba51ddc954a0cad301123da1a26c4769 That sha256 names the PR description this verdict read. Recompute it with |
GPT 5.6 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
6dfdfbe to
2bd8004
Compare
|
Review round 1 on GPT 5.6 (blocking)
Design Review (CONCERNS)
First Principles (CONCERNS)
CI: the only red lane on |
Opus 5 Review (fork) — ✅ no blocking findingsReviewed |
2bd8004 to
b5798de
Compare
|
Review round 2 on GPT 5.6 (blocking)
Design Review (CONCERNS): fixed. The First Principles (CONCERNS): Opus 5: no blocking findings on |
b5798de to
5fa615a
Compare
|
Review round 3 on Opus 5 (advisory, all three taken)
First Principles: Item 3 fixed as above. Item 2 ( Design Review: PASS; the "verify fenced callers dead-by-default is intended" note is for maintainers. It is the fail-closed answer to GPT F1 of round 1 and is documented in the user doc, the tool description and the refusal text. GPT 5.6 F1 (fenced, blocking, third statement of the same boundary): unchanged and, I believe, not fixable inside this PR. Containment fields are read from the archived metadata line; the same line hydrates every live slot at restart ( |
5fa615a to
ec6bc80
Compare
|
Review round 4 on GPT 5.6
Design Review (CONCERNS): agreed, someone must decide it. the ask to a maintainer (@dwu96, as the one who has been approving this PR's workflows) is one of (a) accept on this PR that First Principles: PASS on CI on |
|
|
|
Round 30 on 9b56dca: GPT and Opus both passed with no blocking findings. Head 468bbd6 (same two commits, main unmoved by anything that touches this PR, merge clean) fixes the two Opus doc advisories: the spec paragraph in |
|
|
|
|
…request-free core `api_chat_slot_resume` was one 430-line handler that both decided whether an archived session may be pulled back into a live slot and shaped that decision into aiohttp responses. Nothing but the History tab could reach the decision. Extract `resume_slot_from_history(state, *, name, history_key, request_app, caller_label, request_title) -> ResumeOutcome`: the same guards, the same member-pin and delete/recreate barriers, the same materialisation, but every refusal comes back as a `ResumeRefusal(error, code, status)` and the dedup arm returns the existing slot. `api_chat_slot_resume` is now the thin wrapper that reads the request and reproduces each historical body and status unchanged; the live-slot probe becomes `_live_slot_for_resume` plus a payload helper. Behavior otherwise unchanged: the 28 test modules that exercise the resume endpoint pass untouched (3128 tests). This is the seam the session-control `revive` verb plugs into next. The two refusals on that path that carried prose alone -- "no conversation log" (400) and the app-isolation "not found" on a live slot (404) -- gain `no_conversation_log` and `slot_not_found`, so every refusal is a transparent coded body (the error-code contract for a dynamic-status site); error text and statuses are unchanged and the per-file baseline is tightened as the gate instructs.
… to the sidebar `session_close` archives a tab to history, and until now nothing on the `kirocrew-dashboard` MCP server could bring one back: `chat_folder_move_session` and `chat_tag_assign` told the caller to "revive one into the sidebar first" with no tool that did so, and an agent asked to reopen a closed investigation could only re-create an empty session and lose the transcript. `session_revive(target, folder?)` is the mirror of `session_close`. It takes an archived session by slot key, `dashboard:<slot>` session key, transcript stem or exact unique title, reopens it as an idle live tab with its full transcript -- the same thing as clicking it in the History tab, through the same `resume_slot_from_history` core -- optionally files it into a sidebar folder (same mkdir-p gate as `session_create.folder`), and returns the live key so the other session tools can address it. A target that is already open is refused with its live key (`target_already_live`). Authorization is `authorize_target`'s, applied to the persisted metadata line since there is no live slot yet: the caller-side refusals are now shared helpers (`_check_caller_identity`, `_check_caller_slot`, `_not_creator_reason`, one `_denier` audit builder) so the two verbs cannot drift, and the target-side ones read `workspace`, `app`, `linked_session_key`/`channel_origin`, `memory_mode` and `created_by` off the metadata with the same codes. An ownership-fenced caller (crew member, scheduled run, agent-created session) may revive only a session it created; reviving never transfers ownership. New route `POST /api/session-control/revive` (strict-internal list included), schema, channel-agent containment entry, tool descriptions that now name the tool, user doc (15 tools), system spec section, and 28 tests covering the round trip through the real close, every key spelling, filing, and each refusal. Ratchets that pin the advertised set and the doc's counts are updated.
|
Rebased onto main a2ae482 (head 8a1df24, no behaviour change). Main added |
bolichen97
left a comment
There was a problem hiding this comment.
Reviewed on behalf of the maintainers (sweep 2026-09-30): readiness passed, required checks green on 8a1df24, no blocking review threads, security posture unchanged. Approving and merging.
Problem / Motivation
Goal: An agent that can close a session with
session_closecan also bring an archived one back into the sidebar, with its transcript and under the same containment and ownership rules as the other session verbs, and file it into a sidebar folder in the same call (the waysession_createfiles a new session).An agent can close another session with
session_close, but nothing on thekirocrew-dashboardMCP server can bring one back.chat_folder_move_sessionandchat_tag_assignboth tell the caller "ARCHIVED (history) sessions cannot be moved/tagged; revive one into the sidebar first", and no tool revives. Today an agent asked to reopen a closed investigation from chat can onlysession_createan empty session and lose the transcript. The case that surfaced this: a closed session named "Prod Test Account Lookup" was wanted back in the sidebar from a chat, and no tool could do it.Why it matters
Closing is presented as recoverable ("it can be reopened later"), but only a human clicking the History tab can recover it. Every agent workflow that files, tags, seeds or continues a session hits a wall the moment that session was closed, and the recovery it is pointed at does not exist.
Not a goal
app/workspace/memory_modecontainment fields against gateway-owned state: those fields exist only on the transcript metadata line today, exactly as the restart path and the History click already trust them; a gateway-owned record for them is a separate PR and is listed under "Known trust boundary" below._resolve_slot's ambiguity doctrine.What changed (motivation → approach → change)
Goal: the mirror of
session_close, with the same reach and the same containment.Approach: reuse the History tab's own resume path rather than build a second one.
api_chat_slot_resume(the/api/chat/slots/{slot}/resumehandler) is split into a thin wire wrapper and a request-free core,resume_slot_from_history, so a controlled revive and a human click share one materialisation, one set of member-pin and delete/recreate barriers and one set of refusal codes. The wrapper reproduces every historical body and status; the two refusals on that path that shipped prose alone now carrycodes (no_conversation_log,slot_not_found), and the error-code baseline is tightened as that gate instructs.Change:
session_revive(target, folder?).targetis what a caller holds: slot key,dashboard:<slot>session key, the transcript namelist_sessionsreports, or an exact title (unique among archived sessions). Ambiguity is refused asambiguous_target; a target that is already open is refused with its live key (target_already_live) instead of opened twice.folderfiles it after it is live, best-effort, through the same mkdir-p gate assession_create.folder(the result'sfiledsays whether it happened). Reviving never transfers ownership: the session keeps thecreated_byit had.authorize_target's, applied to the persisted metadata line because there is no live slot yet. The caller-side checks are now shared helpers (_check_caller_identity,_check_caller_slot,_not_creator_reason, one_denieraudit builder) so the verbs cannot drift, and inrevive_sessionthe whole caller side runs before the archived target is resolved, so an ineligible caller gets one answer whether or not the session exists; the target-side checks readworkspace,app,linked_session_key/channel_origin,memory_modeandcreated_byoff the metadata with the same codes, and the channel-link and outbound-mirror boundaries are also read from the gateway-owned session store by history key (get_origin_link,get_slack_link,get_mirror_link; fail-closed), and every boundary tested before the resume, caller-side included, is re-asserted on the built slot in the resume core's new pre-publishcontainmenthook (the core holds the built slot retracted and under construction while the hook awaits, with the row broadcast held back; the reopen write that clearsclosedis deferred until the hook has passed, so a hook refusal has nothing durable to undo and a clear that cannot land refusesreopen_failed503 instead of publishing a tab that would not restore; a synchronousfinal_checkre-asserts the store-free answers after the core's last await and immediately before the publish, and a refusal there restores the marker while the construction mark still reserves the key, confirming the restore by a re-read with one retry on a raise, and answersreopen_rollback_failed503 in place of the refusal when the marker cannot be confirmed back; a concurrent resume of the same key during the window is answeredresume_in_progress409; the existence andcreated_atidentity barrier that guards the hook-less resume is re-run after the hook's last await and again on the verification read after the deferred clear, and a final time synchronously after the last await, so a session deleted or delete-and-recreated inside the hook window is refusedresume_session_deletedrather than published over the replacement, and the marker rollback comparescreated_atso it never archives a replacement; because the deferred clear and its verification read are awaits after the hook's store-backed probes, the hook runs a second time after them as the last awaiting act, so a channel binding recorded in the store during those awaits is still refused), so a refused revive publishes nothing. A revive that finds the session already live (before the history scan, during it, or by the time the resume ran) answers through one builder that authorizes that live slot as any live target before naming it (the slot-field checks on the loop, the two store probes in a worker, and the slot-field checks once more on the loop after them, so a protection landing during the store hop is answered before the key is named): a protected slot answers with that refusal and reveals neither its existence nor its key, an unprotected one answerstarget_already_livewith its key. Under a hook the built slot's_app,linked_session_keyandchannel_originare restored from the fresh metadata re-read (the resume core hydrates neither link field), so the hook's app and link checks read the line as it is. The inbound-link corroboration readsget_origin_link, the getterSessionManageractually defines (an earlier spelling read a name it lacks and was inert), pinned by a test against the real class; an unreadable answer on the final synchronous identity read refusesresume_conflictrather than falling through; and the hook-less History path asks the construction-conflict question before its eager clear so a click that lost the race leaves the line as it found it, and a click that passed that guard, cleared, and then lost at the post-read guard restores the marker before answeringresume_in_progress, answeringreopen_rollback_failed503 instead when the restore cannot be confirmed. An ownership-fenced caller (crew member, scheduled run, agent-created session) may revive only a session it created, and becausecreated_byis read from an agent-editable transcript file, that claim is corroborated against the crew-log session-tree lineage (gateway-authored, written from the in-process_lineage_mintedwitness): the lineage must be readable and name the caller as parent, elseownership_unverified. Unfenced callers (the person's own tabs) are not ownership-gated, so the human recovery case works with the crew log off. Revive spends the same create budget, global slot cap and per-caller cap assession_create; because it preserves the target's creator, the per-caller cap is charged through a separate in-memory_revived_byfield, and the registry'screator_slot_countnow counts_created_byor_revived_by(never persisted, never read for ownership), socreate_sessionandrevive_sessionshare the one accounting. Both caps are tested before the resume and re-tested in the pre-publish hook on the live table.POST /api/session-control/revive(on the strict-internal list), schema, channel-agent containment entry, and tool descriptions onchat_folder_move_session,chat_tag_assignandsession_closethat now name the tool. Docs: the user page (18 tools, after feat(session-tree): adopt and release records so one conductor can take over another #12962 addedsession_adopt/session_releaseand feat(session-control): session_fork carries a transcript into a new session #13102 addedsession_forkon main), the session-control system spec, the MCP server table, and the agent prompt line.Where it lives: the resume split in
src/kiro_crew/dashboard/chat_handlers.py;revive_sessionand the shared helpers insrc/kiro_crew/dashboard/session_control.py; the route insrc/kiro_crew/dashboard/handlers/session_control.pyandsrc/kiro_crew/dashboard/server.py; the tool insrc/kiro_crew/mcp_dashboard.pywith its schema insrc/kiro_crew/validation.pyand the containment entry insrc/kiro_crew/channel.py; docs insrc/kiro_crew/docs/session-control.md,src/kiro_crew/docs/index.md,docs/system-specs/modules/session-control.md,docs/architecture/mcp.mdand the Session control row ofdocs/feature-map/README.md.The
! config/infra file changedsignal iserror-code-baseline.json, tightened per the gate, andsrc/kiro_crew/config/prompt.md, one sentence naming the new tool.Backwards compatibility
Compatible:
api_chat_slot_resumereturns the same bodies and statuses as before, plus acodefield on two refusals that had none;resume_slot_from_historygains an optional keyword-onlycontainmenthook that the wire wrapper does not pass.resume_conflict,resume_in_progress(both 409),reopen_failedandreopen_rollback_failed(both 503) are new core refusals reachable only with a hook; the session-control route maps 503 explicitly rather than degrading it to 400.resume_slot_from_historyalso gains the keyword-only synchronousfinal_check; the wire wrapper passes neither. The revive reply no longer carrieswas_closed(no consumer; the audit detail keeps it). No existing tool changes shape;session_reviveis additive. After #13102 merged, the MCPfolderresolution reuses its_resolve_folder_for_new_sessionhelper (the two PRs had extracted the same helper under different names; main's name is kept). No wording ofsession_create's orsession_fork's refusals changes: the shared caller-side helpers (_check_caller_identity,_check_caller_slot,_denier) are used byauthorize_targetandrevive_session;_refuse_ineligible_creator(create and fork) keeps its own spelling of the overlapping four checks, with the refusal-parity tests pinning the two sets against each other. Folding it onto the shared helpers is a follow-up, not part of this PR.authorize_targetkeeps every check, order and code (the factoring is pinned by the refusal-parity tests); its four live-target containment reads (unattended prefix, memory mode, app scope, channel link) now come from the shared_live_target_refusal, whichrevive_sessionalso applies to the hydrated slot, so the two cannot drift. The unattended prefix test casefolds in both. After #13522 merged, the owner-DM exemption (owner_dm_refusal) and the owner-DM fence wording live in the shared helpers_check_caller_slotand_not_creator_reason, whichauthorize_targetandrevive_sessionboth call; the two channel refusals therefore sit in the store-reading half (_check_caller_slot) rather than the store-free_check_caller_slot_fields, since their exemption reads the session store. #13522's own tests pass unchanged through the helpers.Tests
test/test_session_control_revive.py(97 tests): the round trip through the realclose_targetand the real resume core (transcript restored,closedcleared, idle); every key spelling and a case-insensitive title; ownership not transferred (kept only when the lineage corroborates the line'screated_by; an uncorroborated or lineage-denied claim leaves_created_byblank on the revived slot, so a forged key is handed reach over nothing); filing applied, refused before anything is revived when the folder is unknown, previous placement kept withoutfolder; live target refused with its key (including one that goes live during the scan); unknown and ambiguous targets; member threads; each metadata-read containment (workspace_mismatch,app_scoped_target,linked_session_target,ephemeral_target,unattended_target); the outbound-mirror guard from the session store, fail-closed when the store errors, and refused before publish when a mirror lands mid-resume; a channel link or Slack thread binding recorded in the store refuses even when the metadata line is clean, fail-closed on store error; a caller that loses eligibility, or a channel link that lands, during the resume is refused before publish; a doubleddashboard:dashboard:prefix on acron-/member-key is folded to its fixed point so the prefix guards see the key the resume would publish; fenced caller may revive only what it created, is refusedownership_unverifiedwhen the lineage names another parent (a forgedcreated_by) or cannot be read (crew log off), unfenced callers never consult the lineage; a global or per-caller cap crossed during the resume is refused before publish; revived sessions the caller did not create still charge its per-caller cap (a created-and-revived slot once), and create and revive are pinned to the one charge function; the MCP reply does not warn when the session was already in the requested folder; the target-side refusal codes ofauthorize_targetare pinned as a subset ofrevive_session's; shared caller-side refusals, applied before the target is resolved (an app-scoped caller gets the same 403 for an existing and an absent archived session); slot cap, create budget and per-creator cap; a filing failure after publish does not fail the revive, and the filing save is strict so a raised write reportsfiled: falseand rolls the placement back rather than a dirty-flush True, the filing runs under the slot-metadata txn lock the folder endpoint uses, and its rollback compares the live value so a placement another writer committed inside the awaits is left alone, and a cancellation inside the filing rolls the placement back and writes the allowed audit for the already-committed revive before propagating, and a cancellation delivered while the filing waits for a contended slot-metadata lock writes that audit exactly once; the history scan, every session-store probe on the target (link, Slack binding, mirror, both sides of the resume) and the store probes behind the already-live answer run off the loop thread while a protection landing during that hop is caught on the loop before the key is named; a key candidate is resolved through the catalog's spelling of the filename stem, so a case variant of a live key on a case-insensitive filesystem is reported live instead of publishing a second slot over one transcript; metadata that drifts during the resume (app,memory_mode,linked_session_key,workspace) is re-read off the built slot and refused before publish; every in-window refusal asserts the built slot was neither resolvable nor in the live table while the hook ran and that the on-diskclosedmarker is intact; the core's hook contract: a refusing hook leaves the durable session exactly as found (the reopen write has not happened yet), afinal_checkrefusal after the deferred clear restoresclosedandclosed_atwhile the construction mark is still held, a clear that raises refusesreopen_failedwith the marker intact, a task cancelled during the deferred clear still releases the construction mark and restores the marker (every await between the retraction and the publish sits under oneBaseExceptionarm whose discard is shielded), a refusal whose marker restore keeps raising and cannot be confirmed by re-read answersreopen_rollback_failed503 after one retry while a restore that fails once recovers on the retry and the original refusal stands, the route forwards both 503s, a session deleted or delete-and-recreated inside the hook window is refusedresume_session_deletedwith no slot published and the replacement untouched, a channel link recorded in the store during the deferred clear is refused by the second hook pass with the marker rolled back, a delete-and-recreate inside the clear leaves the replacement without the oldclosedmarker, a protected live target is refused without its key or title on both pre-resume live branches, a link written to the metadata line during the transcript read is refused by the hook, an unreadable final identity read refuses with the marker rolled back, the store probes read gettersSessionManagerdefines, a raising hook discards the built slot, a clean hook publishes once, a concurrent resume during the hook getsresume_in_progress, the folder un-hide keeps the History path's place before construction (a refused hooked resume can leave a folder visible, as a click refused at the member barrier can), a folder deleted meanwhile still unfiles the session as the click does, the global cap in the hook is exclusive like every other allocation path, an already-live protected slot is refused without its key or title while an unprotected one answerstarget_already_livewith its key, and the hook-less History path is unchanged; HTTP wrapper forwardsfolder_idand the fence; route on the strict list; MCP tool posts with the caller's key, refuses without a strict key, names the live key, reports created folder segments on the already-live reply. A fence keeps the slot-form mirror probe answering "not mirrored" without reading the slot when no session store is present (the spec-builder queue path stamps containment on a duck-typed slot; the first history-key split of the probe broke two of its route tests). Ratchets updated: advertised set, channel containment, doc counts, refusal-code parse now walks the shared helpers. The 28 resume-endpoint test modules pass untouched.Known trust boundary (for maintainers)
Two of the target-side containment fields,
appandworkspace, are read only from the archived metadata line, which an agent with file access to the crew home can edit. The channel-link boundary is corroborated against the gateway-owned session store (get_link,get_slack_link), the outbound-mirror boundary against the same store, and for fenced callerscreated_byagainst the crew-log lineage;memory_modeis defensive only, since incognito and temporary sessions are never written to history. Forappandworkspaceno gateway-protected copy exists:_rehydrate_slot_from_historyrestores them from the same line onto live slots at every restart,authorize_targetthen reads them off the slot for stop/send/read/adopt/release, and the History tab's own resume click hydrates from it too. Closing that needs a trusted metadata store shared by restart, resume and revive, which is out of scope here. A maintainer should either accept this boundary on the PR as equal to the existing restart/resume trust, or name the trusted-metadata-store follow-up as a prerequisite.Second boundary, a window rather than a field: the session-store probes for an inbound channel link, a Slack thread binding and an outbound mirror run in a worker thread (the store's guarded getters share the lock its writer holds across a temp-file write and rename, and the AutoSDE rule forbids them on the loop), and the last of them runs one await before the synchronous
final_checkand the publish. A channel bind landing inside that one await, from a writer that needs no live slot, publishes a slot whose later verbs are re-refused byauthorize_target's mirror check for the Slack and mirror forms, but not for an origin-link-only bind, whichauthorize_targetnever reads. Closing it means either holding the store's write lock across the publish (a disk write in front of every channel bind) or a post-publish re-check that reopens the publish-then-retract shape removed in round 9. The fork GPT lane's adjudicator flagged this as an edge case a human may accept; it is left as a maintainer decision alongside the field boundary above.Manual verification
Not run against a live gateway. Unit coverage drives the real
close_targetand the real resume core end to end (transcript restored, slot published, filing applied), and the HTTP wrapper and MCP tool are covered at their seams. A scripted isolated-gateway pass was attempted; driving/api/session-control/*requires minting a signed per-session token, which the agent sandbox refuses by policy, so that pass is left for a maintainer or for the live gateway once this lands.Related Issues
N/A — no tracking issue; the gap was found while splitting an investigation into per-thread sessions.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)