Skip to content

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

Merged
chenmingwei23 merged 2 commits into
mainfrom
rebase/15441-session-history-list
Oct 14, 2026
Merged

chenmingwei23 merged 2 commits into
mainfrom
rebase/15441-session-history-list

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

Replaces #15441 (by @Pearcekieser), rebased onto current main. Fork PRs cannot consume /ai-review overrides, so this is an in-repo replacement carrying @Pearcekieser's original commits unchanged in intent; only conflict resolution and main's moved code were adjusted (the kirocrew-dashboard tool count is now 36 because main added sibling tools, the tool is registered as a Tool(...) row in main's ToolTable with its handler as _run_session_history_list, the GET route is registered in server_runtime/mcp_routes.py, and the session-control/feature-map/mcp docs were re-merged onto main's newer wording). Credit for the change is @Pearcekieser's.

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.

list_sessions (mcp_tools/sessions.py) is the nearest existing listing, and it does not close the gap. It mixes live and archived sessions, has no folder filter, lists rows revive refuses (app-scoped, channel-linked, member DM threads, scheduled runs), and applies no ownership fence, so a fenced crew member or agent-created session sees titles of sessions it may not revive. This tool lists exactly the rows session_revive would accept for this caller.

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.
  • ConversationLog.newest_session_stems(max_entries) (history.py, backed by history_search.py) is a bounded catalog read: it stats transcripts and keeps only the newest N in a heap, reading no file content, so the scan's memory is capped by its own limit however large the archive is.
  • 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?) (mcp_dashboard.py, schema in validation.py): 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 (channel.py), tool title (data/mcp_tool_titles.json), docs/session-control.md (+ index count), the system spec, the MCP architecture doc and the feature map are updated. On rebase the count moved to 36 (21 session-control tools) and the feature-map/mcp rows were re-merged onto main's current text (keeping main's session_continue, session_generate_title, session_move_to_column, chat_folder_delete, chat_folder_file_self and include_session_link additions).

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: 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).
  • Tool-set pins updated in test_mcp_dashboard_registration.py, test_mcp_dashboard_folders.py, test_session_control_doc.py and the refusal-audit table in test_session_control.py; the MCP route-table and boot-trace pins in test_dashboard_server_composition_contract.py count the new GET route. The MCP handler tests drive the tool through TABLE.call with InMemoryDashboardClient, as main's other session tools do.
  • Local on this rebased head: 17 scoped files (the session-control, MCP dashboard registration/folders, composition-contract, channel block list, tool title/registry, internal-path and feature-map tests; 1056 passed) and the flake-pattern ratchet, plus black --check, isort and flake8 on the changed files, scripts/docs_lint.py --test and scripts/docs-lint.sh. CI runs the full suite and mypy.

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

Pattern harvest

Rule candidate: when rebasing a fork PR that documents a count/list (tool counts, index rows), re-derive the count from the live source (_tool_definitions()), not from the PR's frozen number — main may have added a sibling tool, so the correct post-rebase count is base+delta, not the PR's value.

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

Screenshots / video

Backend-only; no UI surface changes, so no screenshots apply.

@iamwhatever
iamwhatever requested a review from a team as a code owner October 3, 2026 14:33
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 3, 2026
@github-actions

github-actions Bot commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 7baa709648802b459c53e219f14470ac3648b3a8 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Check what an agent can do after more: true: there is no cursor, offset or date filter, so revivable sessions older than the newest 100 can never be listed.

[DESIGN-REVIEWED] 7baa709

Description read

[DESCRIPTION-READ] 31c5510c587c34d0df71fa4f7b0aa70ecb9801e0823b4f50648899f5fa9ea6a8

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 Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🟡 CONCERNS

Premise-level review of 7baa709648802b459c53e219f14470ac3648b3a8 — 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

newest_session_stems is a second spelling of the catalog walk that revive already does through log.list_sessions(), and no measured cost backs it.

Not justified as shipped

  • Item 4 — inherited: the only support is "so the scan's memory is capped by its own limit however large the archive is". No measurement says list_sessions() costs too much, and revive's own _scan_archived_candidates (session_control.py:7015) walks that same catalog with it. Grep newest_session_stems: 1 consumer. Grep log.list_sessions() in session_control.py: 2 existing consumers.
    Subtraction: delete newest_session_stems (history.py, history_search.py), MAX_HISTORY_SCAN_ENTRIES and the scan_truncated reply field, and walk log.list_sessions() the way revive does.
    Clears when: a measured cost of list_sessions() on a real archive is cited, or the deletion is made.

What this change ships

Inventory (6 items) — 5 justified

Intent: let an agent find an archived session it may revive without guessing its key or title. ADDITION.

  1. Agents get a new session_history_list tool listing archived sessions they could revive — justified
  2. New strict-internal GET /api/session-control/history route — justified
  3. Revive's target refusals become one shared predicate that both revive and the listing use — justified
  4. A new bounded catalog read that stats files, plus the scan_truncated reply flag — one consumer, generalized
  5. Channel agents cannot call the new tool — justified
  6. The listing re-checks the caller's surface, workspace and fence before it replies, and drops rows that went live during the scan — justified

[FIRST-PRINCIPLES-REVIEWED] 7baa709

Description read

[DESCRIPTION-READ] aa4d1c4149f2c7e564171c202720f535fa48f82b996b5a13f98fbabbeec4e48a

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 Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 7baa709648802b459c53e219f14470ac3648b3a8 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 7baa709

Verdict parsed from the review's SHA-scoped output markers for commit 7baa709648802b459c53e219f14470ac3648b3a8.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 7baa709648802b459c53e219f14470ac3648b3a8: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 3, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 7baa709648802b459c53e219f14470ac3648b3a8 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 7baa709

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 7baa709648802b459c53e219f14470ac3648b3a8: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 3, 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
@iamwhatever
iamwhatever force-pushed the rebase/15441-session-history-list branch from c64c438 to eec542e Compare October 12, 2026 11:46
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 12, 2026
@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 7baa709648802b459c53e219f14470ac3648b3a8 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 12, 2026
@iamwhatever
iamwhatever force-pushed the rebase/15441-session-history-list branch from eec542e to 25c211f Compare October 12, 2026 12:10
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Disposition for the First Principles CONCERNS on eec542eaf0 (advisory; no code change for either item):

  • Item 1 (overlap with list_sessions) — addressed in the description. list_sessions mixes live and archived rows, has no folder filter, lists sessions session_revive refuses (app-scoped, channel-linked, member DM threads, scheduled runs) and applies no ownership fence, so a fenced crew member or agent-created session sees titles it may not revive. The Problem section now says this.
  • Item 4 (exact omitted count) — kept as shipped. The exact count is the original author's second commit ("report the exact number of rows past the limit"); the walk is bounded by the scan cap and newest_session_stems keeps memory at that cap, and scan_truncated says when the count is a lower bound. Whether to trim it to limit + 1 is a product call for the maintainers; this rebase does not change it.
  • Item 7 (undeclared newest_session_stems) — now declared in "What changed".

Also on 25c211f5e6: the GPT/Semgrep finding (autouse fixture on shared monkeypatch) is fixed by moving _enabled to _floor_monkeypatch, as the sibling session-control suites do, and the composition-contract pins are updated for the one added GET route.

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

Copy link
Copy Markdown
Contributor Author

Self-review (crew-pr-reviewer, read-only): CHANGES NEEDED

This adds a read-only session_history_list MCP tool and GET /api/session-control/history so an agent can find a session_revive target. The gap is real, and the caller gate (identity, surface, ownership fence with crew-log lineage, re-check after the scan) is sound. I checked the diff of src/kiro_crew/dashboard/session_control.py against revive_session's target-side refusals. Today every refusal revive raises on archived metadata (unattended, ephemeral, app, linked/mirrored, workspace, not_creator, ownership_unverified) has a matching skip, so nothing leaks now. Two current-head CONCERNS on 25c211f are real and have no target=design/target=first-principles disposition for that head. The only reply is a free-form comment about eec542e that never mentions Design's two Watch items. (1) Cost: _scan_revivable_history (session_control.py ~L7390-7460) keeps walking up to MAX_HISTORY_SCAN_ENTRIES=5000 entries past limit only to produce an exact omitted count. For every eligible row past the limit it does a get_metadata_status disk read and an _archived_link_and_mirror session-store lock probe, so each agent call can contend with store writers. The goal only needs "more exist". Fix: stop at limit + 1 eligible rows, drop omitted, omitted_keys, the post-scan recount and the "at least N" wording, and keep more/scan_truncated. (2) Drift: the scan restates revive's refusals inline. A future revive refusal for a private session kind would leave titles listed to a fenced caller. Fix: extract one archived-target predicate (meta → refusal code or None) that both revive_session and the scan call, or add a test that walks every revive refusal code and asserts the scan skips it. — crew-pr-reviewer

@iamwhatever
iamwhatever marked this pull request as draft October 12, 2026 15:47
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Converted to draft by crew-pr-reviewer: the self-review above is CHANGES NEEDED. Mark ready again (gh pr ready 16530) once the points are addressed.

@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 12, 2026
@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 12, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Dispositions for d3f74d9 (advisory notes; no code change pushed for them).

target=design: Checked in code. The refusals revive_session raises before it reaches _archived_target_refusal all come from _resolve_archived_target (src/kiro_crew/dashboard/session_control.py, ~L6777-6846), and the scan already covers each one. target_already_live: the scan skips live_keys and then drops rows that went live after the scan. member_thread_target: the scan skips the members_mod.DM_SLOT_KEY_PREFIX keys (~L7463-7467). target_not_found / ambiguous_target: these only arise from resolving the caller's input string; the scan lists one row per folded slot key (seen), and only dashboard_ stems whose metadata reads. Every refusal after the predicate is either caller-side (folder_not_found, create_rate_limited, the slot caps) or comes from the resume core's re-check of a live slot. None of those describes the target's own kind, so none belongs in the listing filter.

target=first-principles (item 7, scan_truncated has no consumer): Correct that no non-test caller reads it today. It stays as a separate fact because more cannot say which case produced it: "another eligible row exists" versus "the walk ran out of its 5000-entry budget and older sessions were never examined". Only the second one means a bigger limit will not help, and that is the case the field names. The cost is one bool. Removing it would also mean another push, which reruns every lane, for an advisory note. If a maintainer prefers the smaller reply, deleting the key and its spec line is a separate one-line change.

@iamwhatever
iamwhatever force-pushed the rebase/15441-session-history-list branch from d3f74d9 to 17e74be Compare October 13, 2026 19:03
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Rebased onto main cf3c385 (the PR was DIRTY). New head 17e74be, still two commits, no logic change.

Conflicts, resolved keeping both sides:

  • Tool lists in docs/architecture/mcp.md, docs/feature-map/README.md, docs/session-control.md and docs/index.md now hold main's session_continue, session_generate_title and session_move_to_column beside session_history_list: 36 tools, 21 session-control (test_session_control_doc pin is 21).
  • history_search.py keeps main's _scan_head_title and this PR's newest_session_stems.
  • test_dashboard_server_composition_contract.py counts the new GET route: route table 285 rows with its new digest, one more _deferred in both boot traces.

Local on this head: 17 scoped test files (1056 passed), the flake-pattern ratchet, black/isort/flake8 on changed files, and both docs lints.

@github-actions github-actions Bot added readiness: checking Automated validation is still running 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 13, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • scan_truncated has no non-test reader: rebutted, kept span=20d09397ad0f

True today: _run_session_history_list reads sessions, more and lineage_unknown, not scan_truncated.
more merges two cases: another eligible row exists past limit, or the walk spent its MAX_HISTORY_SCAN_ENTRIES (5000) budget and older sessions were never examined.
Only the second means a bigger limit cannot help, and scan_truncated is the one bit that names it; docs/system-specs/modules/session-control.md documents it.
Cost is one bool on a strict-internal route. Removing it needs a new head that reruns every lane for an advisory item.
Same ruling as on the prior head (comment 6132846001). Dropping the key and its spec line stays a one-line follow-up if a maintainer wants the smaller reply.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • more: true has no cursor: answered, no change

The reply tells the agent what to do with more: "(more exist; raise limit or narrow by folder)" in _run_session_history_list.
No cursor or offset on purpose: the catalog is newest-first by mtime and shifts whenever a session closes or revives, so an offset would skip or repeat rows between pages.
The tool exists to find a revive target. The newest 100 rows plus the folder filter cover that; an older session stays reachable through session_revive's own key or exact-title resolution, which reads the whole catalog (log.list_sessions() in _scan_archived_candidates), or through search_chat_history.

@github-actions github-actions Bot added 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: checking Automated validation is still running labels Oct 13, 2026
Pearcekieser and others added 2 commits October 14, 2026 00:25
…get predicate

The walk ends at the first eligible row past the page, so no metadata read
or session-store probe is spent beyond it; the reply says more and
scan_truncated, with no row count.

revive_session and the history scan both ask _archived_target_refusal, so
a refusal added to revive hides that kind from the listing by the same
edit. The scan asks it on metadata first and probes the store only for a
row that passes.

The listing tests read the catalog through newest_session_stems, a bounded
stems-and-mtimes read, and backdate closed_at before any revive so a close
and a resume never tie on a coarse clock.
@iamwhatever
iamwhatever force-pushed the rebase/15441-session-history-list branch from 17e74be to 7baa709 Compare October 14, 2026 00:33
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Oct 14, 2026
@chenmingwei23
chenmingwei23 merged commit 71823b9 into main Oct 14, 2026
104 checks passed
@chenmingwei23
chenmingwei23 deleted the rebase/15441-session-history-list branch October 14, 2026 01:40
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 14, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

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

3 participants