Skip to content

perf(history): list channel backfill, resume and Webex sessions from the listing index - #36240

Merged
bolichen97 merged 1 commit into
mainfrom
perf/36138-indexed-listings
Nov 13, 2026
Merged

bolichen97 merged 1 commit into
mainfrom
perf/36138-indexed-listings

Conversation

@rnoack1

@rnoack1 rnoack1 commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: The channel folder backfill, the channel resume picker and the Webex /sessions command list sessions in milliseconds on a busy gateway, instead of re-reading every transcript after each write.

These gateway callers still list sessions with the full scan, ConversationLog.list_sessions(). On a gateway that is writing transcripts, the scan's memo misses after every write, so each call re-reads one row per transcript on a worker thread, holding the GIL. At 9,338 transcripts that is about 1 s per call, against about 15 ms from the listing index (#35938's measurement). #33874 and #35938 moved the dashboard listings and the Shared Crew reads; these are the remaining full-scan callers outside the ones kept on purpose.

Why it matters

When several of these scans run at once they fill the shared default executor, and unrelated dashboard requests wait behind them until the tunnel times out with a 524.

Not a goal

  • Moving list_sessions(keys=...) calls, list_sessions_status() (the channel reconcile), or the callers kept on the scan on purpose: session_revive._consider, the boot restore and the one-shot crew-mode migration.
  • Changing the listing index itself or the default executor.

What changed (motivation → approach → change)

The channel folder backfill, the resume picker and the Webex /sessions command now re-read only the transcript that changed, so its cost stays flat as history grows. Each call moves from list_sessions() to list_sessions_indexed(), which returns the same rows in the same order:

Caller Reads Why the index's lag is fine
dashboard/channel_slots.py backfill_channel_folder keys and modified, for one channel a one-shot click; each candidate's metadata is still read fresh with get_metadata
messaging/session_resume.py resolve_session_choices (listing and title fallback) keys, titles, memory_mode a list a person picks from; a pick re-checks the log exists
webex/transport_dispatch_commands.py _handle_sessions this bucket's keys and titles a list printed for a person

The one difference is the one #33874 accepted: another process's append to an existing transcript shows within RECONCILE_SECS (5 s) instead of 2 s. Writes in this process, and files created or removed by anyone, show at once. memory_mode, which the resume picker filters incognito sessions on, comes from the same metadata line in both paths; a metadata rewrite by another process already lagged up to 2 s on the scan. The search index pass (SessionCatalogProjection.backfill_index) stays on the scan. It runs only in the index worker's own spawned process, so it never holds the gateway's GIL or its default executor. That process writes no transcript, so every gateway append would reach its index only after a reconcile, up to two worker passes (60 s each when idle) later, and the process would also hold its own copy of the index.

The history spec lists the three moved callers among the index's callers and the search index pass among those kept on the scan, with its reason.

Backwards compatibility

Compatible: same rows, same order; another process's append to an existing transcript shows in these three listings within 5 s instead of 2 s.

Removes nothing: no route, row, key, command or function is taken away.

Tests

  • test/test_session_listing_callers_index.py: after one in-process append, each caller re-reads 1 row at 600, 1200, 2400 and 4704 transcripts (backfill, resume listing, resume title fallback, Webex /sessions). With the change reverted all 16 fail, reading n rows (assert 600 == 1 up to assert 4704 == 1).
  • test/channel_folders_helpers.py, test/discord_sessions_helpers.py, test/test_teams_sessions.py, test/test_webex_dispatch_commands.py: the fake logs serve list_sessions_indexed.
  • test/test_telegram_sessions.py: the two owner-gate tests patch list_sessions_indexed, the read the picker makes. With the owner gate forced open, test_owner_gate_runs_before_history_read[private-chat-not-user] fails (assert 1 == 0); patching list_sessions instead passes either way.
  • Determinism: the new file passed 20 repeats at -n0 (16/16 each) and 10 at -n 4 --dist loadgroup beside test_channel_folders_backfill.py and test_webex_dispatch_commands.py (105/105 each); a shuffled order (seed 36138) of the new file, test_channel_folders_backfill.py and test_teams_sessions.py passed 125/125.

Manual verification

N/A: unit coverage of each caller's read path; the index's parity with the scan is covered by test_history_listing_index.py.

Related Issues

Closes #36138
Part of #33842

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

@rnoack1
rnoack1 requested review from a team and KiroCrewCaptain as code owners November 13, 2026 00:05
@rnoack1
rnoack1 requested a review from mbriones98 November 13, 2026 00:05
@KiroCrewCaptain

KiroCrewCaptain commented Nov 13, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: the decider raised 1 possible problem and estimates a 45% chance that this change introduces a defect; a person should check it.

The three production call-site swaps to list_sessions_indexed() are correct, and the new test shows each caller re-reads one row after an in-process write. But switching the shared resume picker leaves Telegram's owner-gate tests patching log.list_sessions on a real log, which the picker no longer calls. test_owner_gate_runs_before_history_read now passes even with the owner gate removed. This is the same fake-update class the PR handled for Discord, Teams and Webex but missed for Telegram, on a trust-boundary check. Request patching list_sessions_indexed in those two tests.

Things to check (possible problems the decider raised; at this confidence many turn out to be fine):

  • Moving the shared resume picker to the index turns Telegram's owner-gate-before-history-read test into a test that passes no matter what: if the owner gate were removed or moved after the read, reads would still be 0. The PR updated the Discord, Teams and Webex fakes for exactly this kind of chang (test/test_telegram_sessions.py, medium)

An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit 5505d7515a · 158 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@github-actions github-actions Bot added the readiness: action required A blocking check or review needs attention label Nov 13, 2026
@rnoack1
rnoack1 force-pushed the perf/36138-indexed-listings branch from 001c2a4 to 5505d75 Compare November 13, 2026 01:13
@rnoack1

rnoack1 commented Nov 13, 2026

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in docs/system-specs/modules/history.md, src/kiro_crew/messaging/session_resume.py and docs/system-specs/modules/security.md since this head went green (8e22544 -> ee7d56e); CI re-running.

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

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 288ac17563abdb43635d49470de3131f3f0f5eb1 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 288ac17563abdb43635d49470de3131f3f0f5eb1 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks. This moves three more callers onto the existing listing index. The rows and their order stay the same, the 2 s → 5 s lag on another process's appends is a documented trade-off, and a revert undoes it cleanly.

[DESIGN-REVIEWED] 288ac17

Description read

[DESCRIPTION-READ] 1f16b421c990c574bacb1e1b6e8e069a0aa58bc157caf92db13bc8ea76a74372

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 Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 288ac17563abdb43635d49470de3131f3f0f5eb1 — 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 does not.

First-Principles-Verdict: PASS

Nothing blocks. This is a perf fix that points three callers at the existing listing index, and every remaining full-scan caller is either kept on purpose with a reason or listed under Not a goal.

What this change ships

Inventory (5 items) — 5 justified

Intent: the channel backfill, the resume picker and Webex /sessions stop re-reading every transcript after a write, so they stop filling the default executor (that wait ends in a 524). This is a FIX.

  1. The channel folder backfill lists sessions from the listing index instead of a full scan — justified
  2. The channel resume picker and its title fallback list from the index — justified
  3. The Webex /sessions command lists from the index — justified
  4. Another process's append now shows in these three listings within 5 s instead of 2 s — justified
  5. The history spec now lists the three moved callers and says why backfill_index stays on the scan — justified

Siblings counted: I grepped list_sessions() and .list_sessions) in src/kiro_crew and found 5 non-app full-scan callers left. Four are crew_mode_migration, session_revive, restore_drivers (2 sites) and history_search backfill_index; each is kept on the scan with a reason in the spec. The fifth is the history_listing_index.py:322 fallback, which is the index itself. That leaves 0 unfixed siblings.

[FIRST-PRINCIPLES-REVIEWED] 288ac17

Description read

[DESCRIPTION-READ] dbb651c4013102480903eb42e872ed5cb41ac1ddcf3ecc5a812901eeda2342cf

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 Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 288ac17563abdb43635d49470de3131f3f0f5eb1 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 288ac17

Verdict parsed from the review's SHA-scoped output markers for commit 288ac17563abdb43635d49470de3131f3f0f5eb1.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 288ac17563abdb43635d49470de3131f3f0f5eb1 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 288ac17563abdb43635d49470de3131f3f0f5eb1 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 288ac17

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 288ac17563abdb43635d49470de3131f3f0f5eb1 false-positive: <reason, 20 to 500 characters>

@rnoack1

rnoack1 commented Nov 13, 2026

Copy link
Copy Markdown
Contributor Author

Backend Tests (3.12, 8) is red on test_reply_format_once.py::...::test_the_table_names_every_selectable_harness (no table row for mimocode). That is main's red from #24732, tracked in #36279 with the fix in #36290; this PR touches neither file. Waiting for #36290 to merge, then rebasing.

@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 Nov 13, 2026
@rnoack1
rnoack1 force-pushed the perf/36138-indexed-listings branch from 5505d75 to 6b2c212 Compare November 13, 2026 03:25
@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 Nov 13, 2026
@rnoack1

rnoack1 commented Nov 13, 2026

Copy link
Copy Markdown
Contributor Author

Rebased: main moved in test/test_reply_format_once.py (the red-main fix #36290) and docs/system-specs/modules/security.md since this head ran (ee7d56e -> 27e9359); CI re-running.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 13, 2026
@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 labels Nov 13, 2026
@rnoack1
rnoack1 force-pushed the perf/36138-indexed-listings branch from 6b2c212 to 288ac17 Compare November 13, 2026 05:35
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 13, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Read the full diff. Part of #36138 / #33842, the same pattern as #35938. Three callers switch from list_sessions to list_sessions_indexed: the channel folder backfill, the channel resume picker with its title fallback, and the Webex /sessions command. list_sessions_indexed returns the same rows in the same order as fresh copies.

On access: every filter these callers apply happens after the listing and is unchanged. The Webex bucket/generation route match stays as is, and so do the resume picker's eligibility pass and needles_match_text title fallback, and the backfill's per-namespace checks. No app-scoped listing is touched; it keeps the direct scan as before. So no channel user sees a session they could not see on main. The only difference is freshness: another process's append to an existing transcript shows after the next reconcile, up to RECONCILE_SECS. Files created or removed still show on the next call. The spec now lists these callers, and it also documents why backfill_index keeps the scan. The new test pins one row read after an in-process write at every size for all four paths. No regex, no new refusal. LGTM.

@bolichen97
bolichen97 merged commit a8f5fa5 into main Nov 13, 2026
99 of 100 checks passed
@bolichen97
bolichen97 deleted the perf/36138-indexed-listings branch November 13, 2026 08:05
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 13, 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.

perf(history): move the remaining full-scan session listings to the listing index

3 participants