docs(sessions): state that legacy roots are imported once

README.md

@@ -76,7 +76,7 @@ Then run `codegraph init` in each project, as in [Get Started](#get-started). In
 
 T3-hosted provider transcripts can appear in session search; CodeGraph does not read the T3 database. A [pure offline Codex metadata prototype](docs/design/t3-session-metadata.md) associates caller-supplied app titles and thread links with existing hits. It has no CLI or MCP caller and adds no searchable prose.
 
-Session search uses `.codegraph/sessions-v2.db`. The first session search imports remembered roots from `sessions.db` and reindexes available transcripts. It leaves the older file untouched for older executables. Session mentions in code answers resume after the new store is populated. Cached passages from unavailable transcripts remain only in the older store. Retaining both files uses extra disk space. The graph index and project-local scope stay unchanged.
+Session search uses `.codegraph/sessions-v2.db`. The first session search imports remembered roots from `sessions.db` once and reindexes available transcripts. It leaves the older file untouched for older executables; roots an older executable records after that stay in the older file. Session mentions in code answers resume after the new store is populated. Cached passages from transcripts that were unavailable when the new store was first built remain only in the older store. Retaining both files uses extra disk space. The graph index and project-local scope stay unchanged.
 
 ### What the fork adds
 

__tests__/sessions-storage.test.ts

@@ -73,6 +73,22 @@ describe('session storage generations', () => {
     expect(fs.readFileSync(legacy)).toEqual(before);
   });
 
+  it('imports remembered roots once; roots an older writer records later stay in the older store', () => {
+    const { legacy, current } = fixture();
+    const old = legacyStore(legacy);
+    try {
+      expect(open(current).rememberRoots([])).toEqual(['removed-worktree']);
+      // An older executable keeps writing its own store after the upgrade.
+      old.exec("INSERT INTO roots VALUES ('later-worktree')");
+      const before = fs.readFileSync(legacy);
+      const reopened = open(current);
+      expect(reopened.rememberRoots([])).toEqual(['removed-worktree']);
+      expect(fs.readFileSync(legacy)).toEqual(before);
+      // A root the new store sees for itself is remembered there.
+      expect(reopened.rememberRoots(['later-worktree']).sort()).toEqual(['later-worktree', 'removed-worktree']);
+    } finally { old.close(); }
+  });
+
   it('keeps legacy writes, replacement, deletion and reopen independent in every three-event ordering', () => {
     const events = ['legacy', 'replace', 'delete', 'reopen'] as const;
     const sequences: Array<Array<typeof events[number]>> = [];

site/src/content/docs/reference/mcp-server.md

@@ -21,7 +21,7 @@ By default the server exposes `codegraph_explore` for code and `codegraph_sessio
 
 T3-hosted provider transcripts can appear in session search; CodeGraph does not read the T3 database. The source includes a disabled-by-default offline Codex metadata prototype that associates caller-supplied T3 titles and thread links with existing hits. It has no CLI or MCP caller, adds no searchable prose and leaves provider titles, keys and ranking unchanged.
 
-Session history lives in `.codegraph/sessions-v2.db`, separate from the code graph. The first session search imports remembered roots from `sessions.db` and reindexes available transcripts. The older file remains untouched for older executables. Session mentions in code answers resume after the new store is populated. Cached passages from unavailable transcripts remain only in the older store. Retaining both files uses extra disk space. Indexes that predate remembered roots start with none. A damaged newer roots table stops initialization.
+Session history lives in `.codegraph/sessions-v2.db`, separate from the code graph. The first session search imports remembered roots from `sessions.db` once and reindexes available transcripts. The older file remains untouched for older executables, and roots an older executable records after that stay in the older file. Session mentions in code answers resume after the new store is populated. Cached passages from transcripts that were unavailable when the new store was first built remain only in the older store. Retaining both files uses extra disk space. Indexes that predate remembered roots start with none. A damaged newer roots table stops initialization.
 
 Exposing one strong code tool is deliberate. Measured agent behavior showed that one well-aimed tool steers agents to a direct answer better than a menu of narrower ones — fewer mis-picks — and agents reach for it both when answering questions and while editing code.
 

src/sessions/index.ts

@@ -219,6 +219,8 @@ export class SessionsIndex {
               INSERT INTO doc_sources SELECT rowid, file FROM docs;`);
           }
           db.exec('CREATE INDEX IF NOT EXISTS doc_sources_file ON doc_sources(file)');
+          // Roots come over once, when this store is created; roots an older
+          // executable records in sessions.db afterwards stay there.
           if (!hadRoots && legacyPath && fs.existsSync(legacyPath)) {
             const legacy = createDatabase(legacyPath, { readOnly: true }).db;
             try {