Skip to content

feat(session-control): session_revive brings an archived session back to the sidebar - #13110

Merged
bolichen97 merged 2 commits into
kirodotdev:mainfrom
Pearcekieser:feat/session-revive-mcp-tool
Sep 30, 2026
Merged

bolichen97 merged 2 commits into
kirodotdev:mainfrom
Pearcekieser:feat/session-revive-mcp-tool

Conversation

@Pearcekieser

@Pearcekieser Pearcekieser commented Sep 23, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: An agent that can close a session with session_close can 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 way session_create files a new session).

An agent can close another session with session_close, but nothing on the kirocrew-dashboard MCP server can bring one back. chat_folder_move_session and chat_tag_assign both 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 only session_create an 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

  • Corroborating the app / workspace / memory_mode containment 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.
  • Closing the one-await window between the last session-store probe and the publish: that needs either the store's write lock held across the publish or a publish-then-retract shape; also listed under "Known trust boundary".
  • Cross-set title resolution (a live and an archived session sharing a title): the archived one stays addressable by key, and the live match is refused as already live, mirroring _resolve_slot's ambiguity doctrine.
  • Reviving into another workspace, deleting a transcript, or any change to the History tab's own UI.

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}/resume handler) 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 carry codes (no_conversation_log, slot_not_found), and the error-code baseline is tightened as that gate instructs.

Change: session_revive(target, folder?).

  • target is what a caller holds: slot key, dashboard:<slot> session key, the transcript name list_sessions reports, or an exact title (unique among archived sessions). Ambiguity is refused as ambiguous_target; a target that is already open is refused with its live key (target_already_live) instead of opened twice.
  • The revived slot is idle with its full transcript; folder files it after it is live, best-effort, through the same mkdir-p gate as session_create.folder (the result's filed says whether it happened). Reviving never transfers ownership: the session keeps the created_by it had.
  • Authorization is 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 _denier audit builder) so the verbs cannot drift, and in revive_session the 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 read workspace, app, linked_session_key/channel_origin, memory_mode and created_by off 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-publish containment hook (the core holds the built slot retracted and under construction while the hook awaits, with the row broadcast held back; the reopen write that clears closed is deferred until the hook has passed, so a hook refusal has nothing durable to undo and a clear that cannot land refuses reopen_failed 503 instead of publishing a tab that would not restore; a synchronous final_check re-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 answers reopen_rollback_failed 503 in place of the refusal when the marker cannot be confirmed back; a concurrent resume of the same key during the window is answered resume_in_progress 409; the existence and created_at identity 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 refused resume_session_deleted rather than published over the replacement, and the marker rollback compares created_at so 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 answers target_already_live with its key. Under a hook the built slot's _app, linked_session_key and channel_origin are 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 reads get_origin_link, the getter SessionManager actually 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 refuses resume_conflict rather 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 answering resume_in_progress, answering reopen_rollback_failed 503 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 because created_by is 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_minted witness): the lineage must be readable and name the caller as parent, else ownership_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 as session_create; because it preserves the target's creator, the per-caller cap is charged through a separate in-memory _revived_by field, and the registry's creator_slot_count now counts _created_by or _revived_by (never persisted, never read for ownership), so create_session and revive_session share the one accounting. Both caps are tested before the resume and re-tested in the pre-publish hook on the live table.
  • The history scan runs off the event loop; only live-slot table reads stay on it.
  • New route POST /api/session-control/revive (on the strict-internal list), schema, channel-agent containment entry, and tool descriptions on chat_folder_move_session, chat_tag_assign and session_close that 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 added session_adopt/session_release and feat(session-control): session_fork carries a transcript into a new session #13102 added session_fork on 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_session and the shared helpers in src/kiro_crew/dashboard/session_control.py; the route in src/kiro_crew/dashboard/handlers/session_control.py and src/kiro_crew/dashboard/server.py; the tool in src/kiro_crew/mcp_dashboard.py with its schema in src/kiro_crew/validation.py and the containment entry in src/kiro_crew/channel.py; docs in src/kiro_crew/docs/session-control.md, src/kiro_crew/docs/index.md, docs/system-specs/modules/session-control.md, docs/architecture/mcp.md and the Session control row of docs/feature-map/README.md.

The ! config/infra file changed signal is error-code-baseline.json, tightened per the gate, and src/kiro_crew/config/prompt.md, one sentence naming the new tool.

Backwards compatibility

Compatible: api_chat_slot_resume returns the same bodies and statuses as before, plus a code field on two refusals that had none; resume_slot_from_history gains an optional keyword-only containment hook that the wire wrapper does not pass. resume_conflict, resume_in_progress (both 409), reopen_failed and reopen_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_history also gains the keyword-only synchronous final_check; the wire wrapper passes neither. The revive reply no longer carries was_closed (no consumer; the audit detail keeps it). No existing tool changes shape; session_revive is additive. After #13102 merged, the MCP folder resolution reuses its _resolve_folder_for_new_session helper (the two PRs had extracted the same helper under different names; main's name is kept). No wording of session_create's or session_fork's refusals changes: the shared caller-side helpers (_check_caller_identity, _check_caller_slot, _denier) are used by authorize_target and revive_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_target keeps 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, which revive_session also 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_slot and _not_creator_reason, which authorize_target and revive_session both 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 real close_target and the real resume core (transcript restored, closed cleared, idle); every key spelling and a case-insensitive title; ownership not transferred (kept only when the lineage corroborates the line's created_by; an uncorroborated or lineage-denied claim leaves _created_by blank 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 without folder; 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 doubled dashboard:dashboard: prefix on a cron-/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 refused ownership_unverified when the lineage names another parent (a forged created_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 of authorize_target are pinned as a subset of revive_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 reports filed: false and 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-disk closed marker is intact; the core's hook contract: a refusing hook leaves the durable session exactly as found (the reopen write has not happened yet), a final_check refusal after the deferred clear restores closed and closed_at while the construction mark is still held, a clear that raises refuses reopen_failed with 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 one BaseException arm whose discard is shielded), a refusal whose marker restore keeps raising and cannot be confirmed by re-read answers reopen_rollback_failed 503 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 refused resume_session_deleted with 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 old closed marker, 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 getters SessionManager defines, a raising hook discards the built slot, a clean hook publishes once, a concurrent resume during the hook gets resume_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 answers target_already_live with its key, and the hook-less History path is unchanged; HTTP wrapper forwards folder_id and 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, app and workspace, 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 callers created_by against the crew-log lineage; memory_mode is defensive only, since incognito and temporary sessions are never written to history. For app and workspace no gateway-protected copy exists: _rehydrate_slot_from_history restores them from the same line onto live slots at every restart, authorize_target then 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_check and 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 by authorize_target's mirror check for the Slack and mirror forms, but not for an origin-link-only bind, which authorize_target never 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_target and 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

  • 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

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Intent: Give agents the mirror of session_close: session_revive reopens an archived session into the live sidebar, with its transcript, under the same containment and ownership rules as the other session-control verbs, by reusing the History tab's own resume path.
Not a goal: Changing what a resume does or how history is stored, transferring ownership to the reviver, reviving member DM threads or channel-backed sessions, or exposing a tail/partial revive.

@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Sep 23, 2026
@dwu96

dwu96 commented Sep 23, 2026

Copy link
Copy Markdown
Contributor

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

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 23, 2026
@Pearcekieser
Pearcekieser force-pushed the feat/session-revive-mcp-tool branch from 2f4a5de to 6dfdfbe Compare September 24, 2026 00:03
@Pearcekieser
Pearcekieser marked this pull request as ready for review September 24, 2026 00:05
@Pearcekieser
Pearcekieser requested review from a team and bolichen97 September 24, 2026 00:05
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 24, 2026
@github-actions

github-actions Bot commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — ✅ PASS

Design-level review of 8a1df2414f1d260e2b6f0995fb9c4deeb9521c74 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

Verify the dashboard's History-click resume tolerates the new coded 409/503 refusals (resume_in_progress, reopen_rollback_failed) the shared resume core can now return.

[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 .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 24, 2026 •

Copy link
Copy Markdown
Contributor

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

Premise-level review of 8a1df2414f1d260e2b6f0995fb9c4deeb9521c74 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

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 (src/kiro_crew/mcp_dashboard.py:288, :456, grep "revive one into the sidebar first") directing callers to a revive that does not exist. The change reuses the existing mechanisms at every seam I counted — the History resume path (split, not duplicated), _resolve_slot's recorded cross-form doctrine, _resolve_folder_for_new_session (now 3 consumers), and the pre-existing _slot_tree_parent / _caller_is_ownership_fenced fence helpers. The pre-publish re-assertion machinery guards the named channel-link/mirror/app boundaries, and the residual one-await window is declared out of scope with its cause stated. No pin is deleted; the doc counts a test pins (12→13) move with the code in the same commit.

Inventory (10 items, capped) — 10 justified

Intent: let an agent bring a closed session back into the sidebar with its transcript, as session_close's mirror — an ADDITION.

  1. New session_revive tool + /api/session-control/revive route revives an archived session with its transcript — justified
  2. Optional folder argument files the revived session in the same call, checked before anything is revived — justified
  3. Same containment and ownership fences applied from the archived metadata line, lineage-corroborated for fenced callers (ownership_unverified, fail-closed) — justified
  4. A revive spends the create budget and both slot caps; revived slot charged to the reviver via in-memory _revived_by — justified
  5. History resume endpoint split into a wire wrapper and a request-free core with pre-publish containment/final-check hooks — justified
  6. Two previously prose-only resume refusals now carry codes; error-code baseline tightened (48→45) — justified
  7. A History click losing a resume race now gets coded resume_in_progress 409 (was an uncoded failure) and restores the closed marker, else reopen_rollback_failed 503 — justified
  8. Channel agents are blocked from session_revive — justified
  9. Route added to strict-internal paths; 503s forwarded instead of degrading to 400 — justified
  10. Docs, prompt and tool-title updates, including syncing the stale mcp.md tool row — justified

[FIRST-PRINCIPLES-REVIEWED] 8a1df24

Description read

[DESCRIPTION-READ] 4f90894d8cd944fc41bacde8c9085638ba51ddc954a0cad301123da1a26c4769

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 24, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] 8a1df24

@Pearcekieser
Pearcekieser force-pushed the feat/session-revive-mcp-tool branch from 6dfdfbe to 2bd8004 Compare September 24, 2026 00:50
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Review round 1 on 6dfdfbec2 addressed in 2bd8004b7 (rebased onto main 4917d7247, two commits, same shape).

GPT 5.6 (blocking)

  • F1 session_control.py revive_session, archived ownership trusted from writable metadata. Fixed. For an ownership-fenced caller the created_by == caller claim is now corroborated against the crew-log session-tree lineage via _slot_tree_parent(slot_key) (the record create_session writes from the in-process _lineage_minted witness, never from disk). The tree must be readable and name the caller as parent, else the call is refused ownership_unverified; unreadable (crew log off, projection unseeded or incomplete) fails closed. Unfenced callers (the person's own tabs) were never ownership-gated and are unchanged. Tests: test_fenced_caller_is_refused_when_metadata_claims_ownership_the_lineage_denies (a forged created_by), test_fenced_caller_fails_closed_when_the_lineage_is_unreadable, test_unfenced_caller_does_not_consult_the_lineage. Noting the trade for maintainers: on a gateway with KIROCREW_CREW_LOG off, fenced callers cannot revive at all. That is the fail-closed answer the finding asks for; if a different trusted record is preferred (e.g. SEL create audit), say so.
  • F2 revive_session, concurrent revives bypass slot ceilings. Fixed along the adjudicator's remedy: the global and per-creator counts are re-tested on the published slot (strictly over, since it is now counted) inside the existing retract path (_retract, shared with the mirror re-check), which re-archives via close_slot and refuses 429. _created_by is restored before the re-test so the creator count includes the slot. Tests: test_a_slot_cap_crossed_during_the_resume_is_retracted, test_a_creator_cap_crossed_during_the_resume_is_retracted.
  • F3 docs/feature-map/README.md, Session control row. Fixed: the row now describes revive and lists POST .../revive.
  • Finding mcp_dashboard.py session_revive.folder "atomically". Fixed: the description now says filing is best-effort after the revive has landed and points at the filed result field; the PR body says the same.

Design Review (CONCERNS)

  • Target-side parity pin: added test_revive_raises_every_target_side_code_authorize_target_raises in test/test_session_control_revive.py. It parses the refusal codes out of authorize_target and asserts the target-side set is a subset of revive_session's, so a containment rule added to the live verb without an archived counterpart fails the test.
  • Live-gateway pass: still not run; the PR body states it and why (minting the per-session token is the product's credential mint, which the agent sandbox refuses by design). One maintainer revive through a live gateway is the remaining check.
  • Orphan mkdir-p segments on the already-live reply: not changed. The segments are created by _resolve_folder_for_session_verb before the core runs, exactly as session_create does when it later refuses; the already-live reply reports them (created_folders) so the caller can see them. Happy to move resolution after the outcome if preferred, at the cost of the "unknown folder refuses before touching history" property.

First Principles (CONCERNS)

  • Item 3, folder argument: kept. It exists for parity with session_create.folder and to avoid the revive-then-move pair racing a folder delete; the description no longer claims atomicity. If maintainers prefer the two-step composition, dropping it is a ~20-line deletion I will make on request.
  • Item 8, session_create refusal wording: now declared in the PR body's Backwards compatibility section. Code unchanged; the shared helper serves every verb so its text says "control".

CI: the only red lane on 6dfdfbec2 was Windows shard 4, test_diag_procs.py::test_gil_hint_fires_on_a_pinned_python_process_with_futex_waiters; this diff does not touch diag_procs and the test uses a fake proc table, so I read it as a flake; the new head reruns it.

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

github-actions Bot commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 399f443

@Pearcekieser
Pearcekieser force-pushed the feat/session-revive-mcp-tool branch from 2bd8004 to b5798de Compare September 24, 2026 01:40
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Review round 2 on 2bd8004b7, addressed in b5798de9f (same two commits, rebased onto current main).

GPT 5.6 (blocking)

  • F2 session_control.py revive_session, revived slots bypass the per-caller ceiling. Fixed. A revive preserves the target's own creator, so creator_slot_count never charged the reviver. Attribution for the cap is now tracked separately: the revived slot gets an in-memory _revived_by = caller_key (state.py _ChatSlot, never persisted, never read for ownership), and _caller_slot_charge(state, caller_key) counts slots whose _created_by OR _revived_by is the caller (a slot that is both counts once). It is tested before the resume and re-tested on the published slot. Tests: test_revived_sessions_the_caller_did_not_create_still_charge_its_cap, test_a_slot_both_created_and_revived_by_the_caller_is_charged_once.
  • F1 revive_session, containment fields read from agent-writable metadata. Not fixed in this PR, and I want to be explicit about why rather than stack another layer. app, workspace, memory_mode and linked_session_key are read from the archived metadata line, the same line _rehydrate_slot_from_history (chat_persistence.py) restores onto every live slot at gateway restart, after which authorize_target reads exactly those values off the slot for stop/send/read/adopt/release. The History tab's resume click hydrates from it too. There is no gateway-protected copy of these fields anywhere in the codebase; created_by is the only one with a gateway-authored counterpart (crew-log lineage), and round 1 corroborated that one. Closing this needs a trusted metadata store shared by restart, resume and revive, which is a design decision for maintainers, not a change I should make inside a tool PR. The PR body now carries a "Known trust boundary" section saying the same. If maintainers prefer, the smallest local mitigation I can see is refusing revive for FENCED callers unless the lineage record also exists (it already does that) and accepting the boundary for unfenced human callers, which is the current state.
  • F3 rollback failure reports a refusal after committing (downgraded by the adjudicator). Not changed; agreeing with the adjudication: close_slot raises only on nudge-retire or history-save failure and leaves the slot open, the failure is logged, and a retry answers target_already_live with the key, which is what a human History click would leave behind. A two-phase publish inside the shared resume core is out of proportion for this path.
  • Finding, _resolve_archived_target title resolution when a live session shares the title. Not changed. The live precheck exists so a caller naming an open session is told its live key rather than "not found"; resolving titles only among archived sessions would trade that answer for a wrong revive when the live and archived sessions share a title. A caller with an ambiguous title has the key spellings.
  • Finding, function-local imports. Not changed: session_control.py uses function-local imports throughout for chat_handlers, chat_persistence and chat_folders (create_session, close_target, adopt_target all do), because chat_handlers imports this module; revive_session follows the file's existing convention.

Design Review (CONCERNS): fixed. The ownership_unverified refusal text now names the prerequisite ("set KIROCREW_CREW_LOG=1 on the gateway"), and the session_revive tool description, the user doc (src/kiro_crew/docs/session-control.md) and the system spec say that fenced callers cannot revive on a default install with the crew log off, while the person's own sessions are unaffected.

First Principles (CONCERNS): folder kept, with the description and user doc now honest about best-effort filing after publication; the atomicity claim is gone everywhere. Dropping the field remains a small deletion if a maintainer asks for it.

Opus 5: no blocking findings on 2bd8004b7.

@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 24, 2026
@Pearcekieser
Pearcekieser force-pushed the feat/session-revive-mcp-tool branch from b5798de to 5fa615a Compare September 24, 2026 02:30
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Review round 3 on b5798de9f, addressed in 5fa615abc (same two commits, rebased onto current main).

Opus 5 (advisory, all three taken)

  • mcp_dashboard.py session_revive reply: the "folder could not be applied" note now fires only when the returned folder_id differs from the requested one, so a session already in that folder is not reported as a filing failure. Test: test_mcp_reply_does_not_warn_when_the_session_was_already_in_the_folder.
  • One per-caller accounting: create_session now gates on _caller_slot_charge too (moved beside _created_by_other), so a caller cannot fill the ceiling once by reviving and again by creating. Pinned by test_create_and_revive_share_one_per_caller_accounting (neither verb reads creator_slot_count). This also clears the First Principles Item 3.
  • error-code-baseline.json regenerated with test/test_error_code_contract.py --update: _compliant 2302 -> 2321 (the honest emitted value; the count rose rather than fell because the shared _denier sites are coded).

First Principles: Item 3 fixed as above. Item 2 (folder): unchanged, same answer as round 2; a small deletion on a maintainer's word.

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 (_rehydrate_slot_from_history) and on the History tab's own resume, and authorize_target reads those hydrated values for every existing verb. "Gateway-owned, agent-unwritable state" for these fields does not exist in the codebase today. The PR body's "Known trust boundary" section states this. This needs a maintainer decision: accept the boundary as equal to the existing restart/resume trust, or ask for a trusted metadata store as a prerequisite PR. I will not push further layers for it.

@Pearcekieser
Pearcekieser force-pushed the feat/session-revive-mcp-tool branch from 5fa615a to ec6bc80 Compare September 24, 2026 03:40
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Review round 4 on 5fa615abc, addressed in ec6bc8060 (same two commits on current main).

GPT 5.6

  • F1 (fenced) revive_session: caller containment could change while the revive awaited. Fixed. The caller-side slot refusals (_check_caller_slot: gone, app-scoped, ephemeral, channel-linked, mirrored) are now re-asserted on the live caller slot after the resume publishes, inside the same retract path as the target-side re-checks; a refusal re-archives the revived slot through close_slot and returns the caller-side code. Test: test_a_caller_that_loses_eligibility_during_the_resume_is_retracted.
  • F2 (fenced) containment from agent-writable metadata: narrowed as far as the codebase allows. The channel-link boundary is now also read from the gateway-owned session store (_archived_session_is_channel_linked: get_link for the inbound link, get_slack_link for the Slack thread binding), fail-closed on a store error, so a link scrubbed from the editable line is still refused linked_session_target. Tests: test_a_channel_link_recorded_by_the_gateway_refuses_even_when_metadata_is_clean, test_a_slack_thread_binding_in_the_store_refuses_the_revive, test_the_channel_link_probe_fails_closed_when_the_store_cannot_answer. Together with the mirror probe (store) and the created_by corroboration (lineage), the fields left on metadata alone are app and workspace; memory_mode is defensive only because incognito/temporary sessions are never written to history. For app and workspace no gateway-protected copy exists anywhere (restart rehydrate and the History resume trust the same line, and authorize_target reads the rehydrated values for every verb). The PR body's "Known trust boundary" section is updated to exactly that residue.

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 app/workspace containment on revive trusts the archived metadata line to the same degree the gateway's own restart and History resume already do, or (b) name a trusted-metadata-store follow-up as a prerequisite and I will hold or split accordingly. I am not adding further layers for this in the tool PR.

First Principles: PASS on 5fa615abc. Opus 5: no blocking findings.

CI on 5fa615abc: Await Fast Gate failed because the workflow approval landed at 02:31:44, five seconds after the await gave up at 02:31:39; Fast Gate itself was green and Coverage Gate failed closed only because the heavy jobs were skipped. Not a code finding; this head reruns it.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • span=0f7a335383d2 docs/system-specs/modules/session-control.md: the spec named _check_caller_identity / _check_caller_slot, which no longer exist

Outcome: fixed.
Rationale: stale from the 2026-09-29 rebase that consolidated this PR's helpers onto main's refuse_caller_identity / refuse_caller_surface (#14185, #14156). The paragraph now names those two and _check_caller_slot_fields, the store-free half refuse_caller_surface delegates to and the revive's synchronous last-word check reuses.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • span=56283a15b9fc docs/architecture/mcp.md: the kirocrew-dashboard row listed 19 tools, omitting session_set_model, session_broadcast, session_status

Outcome: fixed.
Rationale: the row now lists all 22 names the server advertises; checked by extracting the backticked names from the row and diffing against the "name" entries in src/kiro_crew/mcp_dashboard.py (22 == 22, no difference either way). The three missing tools were added on main after this row was last merged and this branch's rebases kept only its own addition.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

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 docs/system-specs/modules/session-control.md now names refuse_caller_identity / refuse_caller_surface / _check_caller_slot_fields instead of the two helpers the 09-29 rebase removed, and the kirocrew-dashboard row in docs/architecture/mcp.md lists all 22 advertised tools (session_set_model, session_status, session_broadcast were missing). The First Principles item on the folder argument is answered by correcting the SESSION_REVIVE_SCHEMA comment to the real reason (folder checked before anything is revived). Each Design, First Principles, GPT and Opus item has its own disposition record above. The Windows shard 5 (test_meetings_session) and shard 7 (test_auto_research) reds and the matrix-resolver rate-limit hit are outside this diff. 1477 targeted tests green.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Re-synced onto main 9ac3e7f (no code change, same two commits, baseline unchanged, merge clean; head 399f443). Every lane on 468bbd6 was green except Opus, which ended "review incomplete" at 02:18Z with no finding, so this re-sync is the retrigger for that lane. 1477 targeted tests green.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • span=36bec42fc986 revive_session containment hook: a channel mirror claim landing between the last store probe and the publish

Outcome: rebutted for this PR; it is maintainer decision 2 in the body's "Known trust boundary" (the probe-to-publish window), and the adjudicator flagged rather than upheld it.
Rationale: the store's guarded getters cannot run on the loop and its writer holds the store lock across a temp-file write and rename, so the only closures are a reservation shared with every channel-binding writer (a new cross-module ordering contract between the session map's _MAP_LOCK/batched_save transaction and the resume core's publish) or the publish-then-retract shape round 9 removed. The span after the last probe is synchronous through final_check and state._slots[slot.key] = slot (the resume core's own comment pins that), the claim must be a channel picker's worker-thread set_mirror_link on exactly this key inside that span, and authorize_target's fresh store read refuses mirrored_target on the caller's next verb, so the published slot carries no channel content and grants no reach. The same end state is reachable by an ordinary History-tab click today. Deferred to the follow-up the "Known trust boundary" section names.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • span=71f46a4050c1 Watch: resume_slot_from_history carries ~350 lines of compensation machinery on the human History-click path

Outcome: acknowledged; deferred to the follow-up the body's "Known trust boundary" section names, which is tracked as DELETING the ladder (a write lock held across the publish, or publish-then-retract), not extending it.
Rationale: the ladder exists only because the store's containment probes must be awaits while the publish must be synchronous; once the follow-up makes the publish atomic with the store read, the second hook pass, final_check, the deferred clear and the confirmed marker restore all collapse. Nothing was added to it in this round; rounds 28 to 31 changed docs, a lock-scope fix in the filing block and an audit-once arm. The item's own clearing condition is a maintainer's acceptance of the interim shape, which is the override the PR asks for.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • span=146e0c02d548 Suggestion: lift the hooked span out of resume_slot_from_history into one named helper

Outcome: deferred to the same follow-up, not done in this PR.
Rationale: the hooked span is the machinery the follow-up deletes; lifting it into a helper now and removing the helper later is the same lines moved twice, and moving ~350 lines inside the function every History click runs would restart the review rounds on a head whose two review lanes are otherwise clean. The revive protocol is already testable as a unit through the hook seam (containment/final_check parameters) and the 97 tests in test/test_session_control_revive.py.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author
  • span=81af697df006 Item 3: the Goal line never asked for filing, so the folder argument reads as oversized

Outcome: fixed by amending the Goal, the item's second clearing condition.
Rationale: filing in the same call is shipped intent, mirroring session_create.folder, so the body's **Goal:** line now says so ("and file it into a sidebar folder in the same call"). The mechanism is unchanged: the folder is resolved and checked before anything is revived (test_revive_refuses_an_unknown_folder_before_touching_history), the post-commit filing is best-effort with rollback, and the filed result key tells the caller which of the two happened.

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

Copy link
Copy Markdown
Contributor Author

Rebased onto main a2ae482 (head 8a1df24, no behaviour change). Main added session_summary, so the four conflicts were docs only: docs/architecture/mcp.md row regenerated from the server's advertised set (23 tools), docs/feature-map/README.md row carries both the summary clause and GET .../summary alongside revive, src/kiro_crew/docs/index.md and session-control.md list both tools and read 23 (13 session tools; the doc test pin follows). error-code-baseline.json regenerated on both commits. 1477 targeted tests plus the doc, registration, title and feature-map tests green; merge-tree clean.

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

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.

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) readiness: passed Eligible automated validation passed for the current revision

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants