fix(sessions): move session search to a separate store so older writers can't corrupt it

[bompus]

Session search now keeps its index in .codegraph/sessions-v2.db instead of sessions.db.

Why

When a transcript changes, session search replaces that file's rows in the FTS table. Doing that by scanning prose is slow, so this change keeps a file-to-row mapping and replaces through it. An older CodeGraph executable that still writes sessions.db would not update that mapping, and the new code would then replace the wrong rows. Moving to a new file keeps older writers and the new lookup apart.

Behavior

• The first session search creates sessions-v2.db, imports the remembered project roots from sessions.db (read-only) and reindexes the transcripts that are still available.
• sessions.db is never written, so older executables keep working against their own index. Passages from transcripts that no longer exist stay only in the old file.
• Schema setup and the root import run in one transaction. Opening an already-initialized store does no schema writes.
• Older index versions (1 to 4) that predate remembered roots import no roots. A damaged roots table in a newer store stops initialization and rolls back instead of dropping remembered worktrees.
• Project-local scope, the CODEGRAPH_SESSIONS_DIR override and SQLite durability settings are unchanged.

Cost

Keeping both files uses extra disk space, and the first search after upgrading pays for a full transcript reindex.

The speed, disk and read-volume effects of this change were not measured. Attempts to run a before/after comparison on the shared development host kept being rejected by I/O stalls from other activity before they produced usable results, so this lands on correctness evidence only.

Checks

• Full Vitest suite on the rebased branch (Node 24): 671 files, 8,583 passed, 39 skipped.
• New __tests__/sessions-storage.test.ts covers upgrading a version-4 index without changing it, importing roots without copying prose, legacy writes interleaved with replacement and deletion in every three-event order, rollback of a failed mapping insert or root import, and opening an initialized store while the other writer holds its lock.

README rows checked: the session-search paragraph under "About this fork" and the codegraph_sessions row in the MCP tools table now name sessions-v2.db. The docs site page reference/mcp-server.md is updated to match. No numbers quoted in the README change.

Summary by CodeRabbit

• New Features

  • The first session search transfers remembered roots and reindexes available transcripts into the updated session store. The existing session database remains unchanged.
  • Session mentions in code answers can resume once the updated store is populated.

• Documentation

  • Updated guidance explains the session-history migration, including storage considerations and cases where remembered roots may be empty.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository YAML (base), Organization UI (inherited)
• Review profile: CHILL
• Plan: Advanced
• Run ID: 9b3f8585-58db-411b-9f42-cfc8e6897cae

---

📥 Commits

Reviewing files that changed from the base of the PR and between 830f8dd and ded858b.

---

📒 Files selected for processing (7)

• CHANGELOG.md
• README.md
• __tests__/sessions-index.test.ts
• __tests__/sessions-storage.test.ts
• site/src/content/docs/reference/mcp-server.md
• src/mcp/tools.ts
• src/sessions/index.ts

---

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 0 remain after this review.

---

---

📝 Walkthrough

Walkthrough

The session index now uses sessions-v2.db. On initialization, it can import remembered roots from the legacy database. Transcript indexing now maintains source mappings for FTS rows, and tests and documentation cover these changes.

Changes

Session storage

Layer / File(s)	Summary
Versioned store initialization src/sessions/index.ts, __tests__/sessions-storage.test.ts, __tests__/sessions-index.test.ts, README.md, site/src/content/docs/reference/mcp-server.md, src/mcp/tools.ts, CHANGELOG.md	The index uses sessions-v2.db and initializes or repairs its schema transactionally. It imports remembered roots from the legacy store when applicable. Tests and documentation cover legacy-store handling, initialization, and database naming.
Transcript source mapping lifecycle src/sessions/index.ts, __tests__/sessions-storage.test.ts, __tests__/sessions-index.test.ts	Transcript replacement and removal update source mappings alongside FTS rows. Tests check mapping consistency and verify that failed mapping insertion preserves prior search results.

---

Priority: ⬇️ Low

Merge Risk

Merge Risk: ⚪ Minimal · up to ded85

The new session-search store appears ready to merge after normal checks. The first search rebuilds available transcript content, and the older database remains intact.

Security Architecture Review

Security architecture risk: 🔵 Low · up to ded85

The separate database prevents older executables from corrupting the new index’s row mappings. Initialization and transcript replacement have transactional failure containment, and the inspected search path retains its existing project-scope controls. Remaining uncertainty concerns mixed-version root synchronization and migration recovery under conditions not directly exercised by the inspected tests.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The inspected change affects the selected project’s session database and transcripts reachable through remembered worktree roots, provider matching, or the existing explicit directory override. Modifying trusted root data already required influence over the legacy store consumed by the base.

Trust Boundaries and Controls

• observed — The legacy database is opened read-only and contributes paths only, not indexed prose. Filename separation and rejection of direct legacy-path opens prevent normal older writers from modifying the FTS rows whose identities are maintained by the new mapping.

Resilience and Maintainability Implications

• observed — Inspected tests assert that a rejected mapping insert preserves prior search results and that a failed legacy-root import rolls back initialization and permits retry after repair. These checks support containment of partial state changes, but do not exercise abrupt process termination or concurrent legacy-root commits during import.

Hardening Proposals

• proposed — Document the one-time root snapshot semantics and add a coordinated legacy-writer migration test to make mixed-version scope divergence explicit. This is a compatibility-hardening proposal, not an observed security finding.

---

---

---

🚥 Pre-merge checks | ✅ 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: moving session search to a separate store to prevent corruption by older writers.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Suppressions Explained		The pull request adds no lint, type-check, or compiler suppression directive. The changed-file inventory contains no lint or type-check configuration files, and added-line scans found no markers such …
User-Visible Changes Documented		The pull request does not add, remove, or rename a CLI command or flag, MCP tool, MCP argument, supported language/framework, agent target, or config key. The only src/mcp/tools.ts change updates a …

---

---

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

---

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}