Skip to content

feat(session-control): session_history_list lists archived sessions a caller can revive - #15441

Closed
Pearcekieser wants to merge 2 commits into
kirodotdev:mainfrom
Pearcekieser:feat/mcp-session-history-list
Closed

Pearcekieser wants to merge 2 commits into
kirodotdev:mainfrom
Pearcekieser:feat/mcp-session-history-list

Conversation

@Pearcekieser

@Pearcekieser Pearcekieser commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: an agent can list the archived sessions it is allowed to revive, so it can find the right session_revive target without guessing a title.

session_revive (#13110) needs a slot key, transcript name, or exact title, and nothing on the kirocrew-dashboard MCP server lists archived sessions. chat_folder_tree shows live sessions only. An agent asked to "reopen last week's investigation in folder X" cannot see what is there.

Why it matters

Three live tool descriptions (chat_folder_move_session, chat_tag_assign, chat_session_pin) tell agents to bring an archived session back with session_revive first. Without a listing, that advice only works when the agent already knows the key.

Not a goal

  • Content search over transcripts (search_chat_history does that).
  • Delete, bulk revive, or any write.
  • Changing chat_folder_tree output.

What changed (motivation → approach → change)

The listing is the finding half of a revive, so it applies revive's own rules and lists only rows revive would accept for this caller.

  • session_control.list_archived_sessions runs revive's caller-side gate first (identity, live surface, ownership fence), then scans the history catalog newest first on a worker thread (_scan_revivable_history). It skips live slots, scheduled-run and member DM keys, non-persistent memory modes, app-scoped, channel-linked and mirrored sessions, and other workspaces. For a fenced caller it keeps only sessions whose created_by is the caller and whose crew-log lineage confirms it. When the lineage cannot answer, the rows are hidden and lineage_unknown is set. After the scan it re-checks the caller surface and drops rows that went live meanwhile.
  • The key-folding helper revive already used moves to module level (_fold_slot_key) so both paths fold keys the same way.
  • GET /api/session-control/history (folder_id, limit) is added to the strict internal-secret route set in server.py.
  • MCP tool session_history_list(folder?, limit?): the folder is resolved read-only, and an unknown folder is refused rather than created or answered with an empty list. limit is 1 to 100, default 20, clamped by the backend too. The reply says when more rows exist.
  • The channel-agent blocklist, tool title, docs/session-control.md (+ index count), the system spec, the MCP architecture doc and the feature map are updated.

Backwards compatibility

Compatible: one read-only tool and one GET route are added. Revive behaves the same; only its fold helper moved.

Tests

  • New test/test_session_control_history_list.py (23 tests): ordering and live-slot skip, every listed row accepted by revive_session, limit and clamp, folder filter and unknown folder, each revive refusal class hidden, fenced caller with confirmed, foreign and unreadable lineage, caller refused before history is read, a row revived mid-scan dropped, route forwarding, non-integer limit, strict route registration, and the MCP handler (rendering, read-only folder resolution, lineage note, missing strict key).
  • A mutation check confirmed the containment tests fail when the workspace, fence and link filters are removed.
  • Tool-set pins updated in test_mcp_dashboard_registration.py, test_mcp_dashboard_folders.py and test_session_control_doc.py.
  • Local backend gate subset (scoped tests, black, isort, flake8, mypy and the repo's static checks) run on this head.

Manual verification

Backend-only, no UI change. The route and handler are exercised end to end through aiohttp in the tests above.

Related Issues

Fixes #15439

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

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

dwu96 commented Sep 30, 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.

1 similar comment
@dwu96

dwu96 commented Sep 30, 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.

@Pearcekieser
Pearcekieser force-pushed the feat/mcp-session-history-list branch from a418a87 to 9d49ff8 Compare September 30, 2026 16:45
@Pearcekieser
Pearcekieser marked this pull request as ready for review September 30, 2026 16:45
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Full implementation is pushed on top of the skeleton, rebased on main bf53de7.

A pre-push local review found two issues, both fixed in 9d49ff8:

  • The post-scan caller re-check read the session store on the event loop. It now runs through asyncio.to_thread, like the pre-scan check.
  • The ownership fence could tighten while the scan ran on its worker thread, for example when a channel-DM link was bound to the caller. Rows filtered under the looser rule would then be returned. The fence is now re-read after the scan, and a tightened fence refuses the call with caller_changed_mid_read.

Two new tests cover these. Both fail on 81c7982 and pass on 9d49ff8.

@Pearcekieser
Pearcekieser requested a review from a team as a code owner September 30, 2026 16:45
@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
@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — 🟡 CONCERNS

Premise-level review of b649c4db3c612b0059fe910b4c0ff0819e14ec06 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: CONCERNS

session_history_list is a second spelling of kirocrew-core's list_sessions, which the description never mentions, and it ships its own bounded catalog walker next to the one revive already uses.

Not justified as shipped

  • Item 1 — duplicate of src/kiro_crew/mcp_tools/sessions.py:115 (list_sessions): the description says "nothing on the kirocrew-dashboard MCP server lists archived sessions". But list_sessions already lists history keys, titles and last-activity times, newest first. It is scoped to the workspace, skips incognito sessions, defaults to 20 rows and caps at 100. What is new is the revive filter, the fence and the folder filter.
    Subtraction: drop the new tool and keep only the revive-eligibility filter, applied inside the existing list_sessions path.
    Clears when: the description names list_sessions and says why its rows cannot be passed to session_revive.
  • Item 5 — oversized: the description gives no reported defect for "memory stays bounded however large the archive is". Revive's own _scan_archived_candidates (session_control.py:5429) and 13 other call sites read the full log.list_sessions().
    Subtraction: delete newest_session_stems, MAX_HISTORY_SCAN_ENTRIES, scan_truncated and the exact omitted count, and walk log.list_sessions() as revive does, keeping more.
    Clears when: the description points to a measured or reported cost of the unbounded walk on this path.

What this change ships

Inventory (6 items) — 4 justified

Intent: an agent can find which archived session to pass to session_revive without guessing a title. ADDITION.

  1. Agents get a new tool, session_history_list, that lists revivable archived sessions — duplicate of mcp_tools/sessions.py list_sessions
  2. The listing can be narrowed to one folder, and an unknown folder is refused — justified
  3. New internal GET /api/session-control/history route on the strict-secret set — justified
  4. Channel agents are blocked from the new tool — justified
  5. A bounded stems-only catalog read (newest_session_stems, 5000-entry cap, scan_truncated, omitted) — oversized, undeclared
  6. The fold helper is hoisted to _fold_slot_key for revive and the listing to share — justified

[FIRST-PRINCIPLES-REVIEWED] b649c4d

Description read

[DESCRIPTION-READ] c1e47d4e379fc7cd2e105f1bee83915f70ecdfa762e7dc249be1478607b1907a

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 added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 30, 2026
@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — 🟡 CONCERNS

Design-level review of b649c4db3c612b0059fe910b4c0ff0819e14ec06 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

The listing's promise that every row passes session_revive depends on a second, hand-copied set of revive's target checks, so it will drift.

Watch

  • Revive's refusals now exist twice. In _scan_revivable_history, the lines if meta.get("app") or meta.get("linked_session_key") or meta.get("channel_origin"): continue, the workspace check, the created_by check and the lineage check copy what revive_session does inline (around session_control.py:5718-5770). Nothing ties the two copies together. If someone later adds or tightens a refusal in revive_session, the listing keeps naming those sessions and showing their titles. That breaks both halves of the description's promise: the containment ("lists only rows revive would accept") and the title privacy. The only test that compares the two paths, test_every_listed_row_is_a_target_revive_accepts, round-trips one plain row. It would not catch a new refusal class.
    Clears when: both paths call one shared function that returns the refusal reason and code from the session's metadata, workspace, fence and lineage (for example _archived_target_refusal(...) -> (reason, code) | None); revive_session raises the result and the scan skips the row. Alternatively, a parametrized test checks for every revive refusal code that the matching archived session is missing from the listing.

[DESIGN-REVIEWED] b649c4d

Description read

[DESCRIPTION-READ] a081609568eb7ac0f3059f87ad05a05a1ba51db6d65591af4f590c64c369350f

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.

@Pearcekieser
Pearcekieser force-pushed the feat/mcp-session-history-list branch from 9d49ff8 to 74a69a4 Compare September 30, 2026 17:45
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased onto main acd219f. #15166 added session_end_wait to the same tool lists, so the conflicts in the four docs files are resolved by keeping both tools. The tool counts move to 25 on the docs pages and 15 in the session-control group pin in test_session_control_doc.py (74a69a4). The code is unchanged.

@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — 🔴 changes requested (blocking)

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

1 of 1 blocking finding(s) are security-class and were withheld from adjudication, so the blocking verdict stands.

BLOCKING -- src/kiro_crew/dashboard/session_control.py:6237 -- Final worker hop leaves mirror authorization stale
if await asyncio.to_thread(_caller_is_ownership_fenced, state, caller_key):
An outbound mirror binds through /mirror-link during this await -> the ordinary dashboard caller remains ownership-unfenced because this predicate ignores mirrors -> archived titles reach a now-forbidden caller whose reply delivery resolves the mirror live.
Anchor: residual/security
Fix: Track a caller-surface/mirror revision across the worker checks and validate it synchronously immediately before returning, without another suspension.
[BLOCK-MERGE] b649c4d
[GPT-REVIEWED] b649c4d

Adjudication (Opus 5.5) — is blocking on each finding proportionate?

F1 is fenced, so my verdict can't unblock the merge. I'm marking it FLAG, which leaves it blocking but gives a human reviewer a drafted reason to override it.

F1 — unbounded-harm class (security). I confirmed the conditions in the code:

  • The caller passes the surface and mirror re-check in a worker thread, which the diff adds at session_control.py:6232-6234. The fence check that comes after it (_caller_is_ownership_fenced, base session_control.py:352-399) never looks at mirrors.

  • For the race to happen, an operator has to bind a mirror through the dashboard HTTP route (routes/sessions.py:128 → chat_mirror.py:139) inside that one worker hop of a few milliseconds. The agent has no way of its own to open that window.

  • There is no recovery path. But a mirror bound one moment after the tool returns has the same effect: the titles are already in the agent's context, and its next reply goes out through the mirror anyway. The base design accepts that, because created_session_status (session_control.py:7302-7324) also checks only at a single point in time.

  • The proposed fix (a revision counter across the worker hops, then a synchronous final check) shrinks a window that is already no wider than the leak no check can prevent. The leaked data is only titles of the same user's archived sessions from the same workspace.

    [ADJUDICATION] b649c4d total=0 uphold=0 downgrade=0
    [GPT-ADJUDICATED] b649c4d

    [ADJUDICATION-FENCED] b649c4d fenced=1 flagged=1
    FLAG F1 src/kiro_crew/dashboard/session_control.py:6237 -- The race needs an operator to bind a mirror through the dashboard route within one worker hop of a few milliseconds, which leaks no more than a mirror bound just after the tool returns (accepted by the base created_session_status design at session_control.py:7302); the exposure is the same user's same-workspace archived titles, so the residual risk is plausibly acceptable.
    [GPT-ADJUDICATED-FENCED] b649c4d

🏷️ Fenced finding(s) machine-flagged as likely edge case

The security fence keeps these findings blocking regardless of adjudication; the only clearance path is a human override recorded by a repository writer, who must independently verify a rationale before recording it — it is machine-authored, and a wrong override on a security-class finding ships exactly the class the fence exists to stop. (This lane's comment deliberately carries no override command.)

  • F1 src/kiro_crew/dashboard/session_control.py:6237 — The race needs an operator to bind a mirror through the dashboard route within one worker hop of a few milliseconds, which leaks no more than a mirror bound just after the tool returns (accepted by the base created_session_status design at session_control.py:7302); the exposure is the same user's same-workspace archived titles, so the residual risk is plausibly acceptable.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 30, 2026
@github-actions

github-actions Bot commented Sep 30, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] b649c4d

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

issue (blocking): fixed in 60bf402. This is the unbounded folder_id finding that both the GPT 5.6 and the Opus 5 review raised on 9d49ff8.

A history row now keeps folder_id only when it is at most MAX_HISTORY_FOLDER_ID_CHARS (64) characters. Real folder ids are 12 hex characters. A longer value is reported as "", meaning unfiled, rather than cut short, because a truncated id would name a different folder or none. The other row fields were already bounded: title goes through _bounded_status_title, target is a transcript filename, and last_active has a fixed format. test_an_oversized_folder_id_is_reported_as_unfiled fails without the fix and passes with it.

@Pearcekieser
Pearcekieser force-pushed the feat/mcp-session-history-list branch from 60bf402 to 595f6c3 Compare September 30, 2026 20:00
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Squashed to one commit and rebased onto main 3ecea02, now at 595f6c3. PR Hygiene failed on 60bf402 because the branch had 4 commits. The tree is unchanged apart from main's new commits. The Windows installer failure on 60bf402 was an HTTP 500 during the electron-builder download, not a code failure.

@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Round on 595f6c3ff7, fixed in 1f9b94fdb0.

issue (blocking, GPT 5.6): the capped list drops the overflow count. Upheld and fixed. _scan_revivable_history no longer stops at limit. It keeps walking the catalog and applies the same eligibility checks, but for a row past the cap it keeps only the slot key, never the title. list_archived_sessions drops any of those keys that were revived during the scan, then returns the exact count as omitted. more is still returned and equals omitted > 0. The MCP tool now prints "N more not shown". Three new tests: the exact count on a capped list, a row revive would refuse is left out of the count, and an overflow row revived mid-scan is left out of the count.

thought (non-blocking, Design review): the scan restates revive's refusal clauses. Agreed that this is a real drift risk. This round doesn't change it. Factoring revive's per-row metadata refusals into one predicate that both verbs call would touch revive_session, which is already merged, and CONCERNS is advisory. test_every_listed_row_is_a_target_revive_accepts keeps today's rule sets in step. I can do the shared predicate as a follow-up if a maintainer wants it in this PR instead.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 30, 2026
@Pearcekieser
Pearcekieser force-pushed the feat/mcp-session-history-list branch from 1f9b94f to 304f8f6 Compare October 1, 2026 00:15
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased onto current main, now at 304f8f6. The diff is unchanged. This re-runs CI after Backend Tests (3.12, 3) failed on test_session_export.py::test_a_sent_export_streams_its_staged_file_and_removes_it, a staged-file cleanup check in a file this PR does not touch. It passed 3 of 3 runs locally. Coverage Gate failed only because that shard failed. The Windows installer red was another HTTP 500 during the build-tool download.

@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 readiness: checking Automated validation is still running labels Oct 1, 2026
@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Oct 1, 2026
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Holding 74b80c5fb4 instead of pushing a fourth retrigger. GPT 5.6 and Opus 5 both pass on this head. The only reds are two tests outside this PR and the Coverage Gate failure they cause. test_session_export.py::test_a_sent_export_streams_its_staged_file_and_removes_it failed on 3.12 shard 3, the same flake as on the previous head. test_runtime_cleanup_windows.py::test_native_admission_and_owner_shutdown_refund_after_verified_drain[False] failed on Windows shard 7 with OSError: [Errno 5] TerminateProcess failed.

todo: a maintainer "Re-run failed jobs" on CI run 36855809603 should turn this head green without re-running the review lanes.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 2, 2026
@Pearcekieser
Pearcekieser force-pushed the feat/mcp-session-history-list branch from 74b80c5 to 64f235a Compare October 2, 2026 05:30
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Rebased onto main d8d052f to clear the docs conflict with #15499 (session_reload). Both tools are kept in the tool lists; the docs tool count goes to 29 and the session-control group pin to 16. No code change. New head 64f235a.

@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 merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 2, 2026
@Pearcekieser
Pearcekieser force-pushed the feat/mcp-session-history-list branch from 64f235a to a69bc93 Compare October 2, 2026 14:00
@Pearcekieser

Copy link
Copy Markdown
Contributor Author

Round on 64f235a628, fixed in a69bc93d7b (rebased onto main 6916ba17f0, no other change).

issue (blocking, GPT 5.6): the scan cap followed an unbounded catalog read. Agreed. I had left this out on 8bacd090ba, but log.list_sessions() builds a full row, persisted title included, for every transcript before MAX_HISTORY_SCAN_ENTRIES applies. The scan now starts from a new newest_session_stems(max_entries) on the catalog projection, exposed on ConversationLog. It stats each transcript and keeps only the newest max_entries stems and mtimes in a heapq.nlargest heap, so what it holds is bounded by the cap however large the directory is. It reads no file content, and it still skips symlinked aliases. It also reports whether more transcripts existed, which now sets scan_truncated.

Because the scan no longer gets catalog rows, it drops the catalog pre-filters on memory_mode and folder_id, which the metadata line already re-checks, and a row's title now comes from the metadata line or the key, without the catalog's first-user-message fallback. Stacked dashboard_ duplicates are still folded by _fold_slot_key and seen, which keep the newest copy as list_sessions did.

Two new tests. One makes list_sessions raise and checks the listing still works, which fails on the previous head. The other checks that newest_session_stems returns only the newest entries and flags the rest. 38 tests in the file pass, plus 3,174 in the session-control, history and MCP suites. The one failure there, test_session_control_durable_sid_across_processes, fails the same way on main. The system spec names the new read.

@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 2, 2026
The capped listing now keeps walking the catalog past limit, keeping only the
key of each further eligible row, and returns that count as omitted (after
dropping any revived during the scan). The MCP tool renders it as 'N more not
shown'. Addresses the GPT 5.6 finding on 595f6c3.
@iamwhatever
iamwhatever force-pushed the feat/mcp-session-history-list branch from a69bc93 to b649c4d Compare October 4, 2026 07:10
@iamwhatever

Copy link
Copy Markdown
Contributor

Rebased onto main (6916ba1 -> efd0181) to clear the merge conflict in docs/architecture/mcp.md, docs/feature-map/README.md, src/kiro_crew/docs/index.md. CI re-running.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Oct 4, 2026
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 4, 2026

Copy link
Copy Markdown
Contributor

Triage: closing as a duplicate of #16530, which carries this change forward. Credit stays with @Pearcekieser.

Evidence (origin/main cc7e79894e7b):

The open review notes still apply to #16530: the post-scan mirror/fence re-check race, and revive's refusals being duplicated in _scan_revivable_history. Issue #15439 stays open and is tracked by #16530.

@bolichen97 bolichen97 closed this Oct 6, 2026
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Oct 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor) merge conflict Branch has merge conflicts with its base — author must resolve before merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(session-control): session_history_list lists archived sessions a caller can revive

4 participants