nlm-memory 0.20.1 → 0.21.12

package/dist/core/storage/sqlite-session-store.js

@@ -10,6 +10,16 @@
  * markers + session_embedding_chunks (vec0). Idle-status overlay (computed
  * from transcript mtime) is deferred to a later phase; A.2 returns the
  * persisted status verbatim.
+ *
+ * Tenancy (program spec §4, M2 plan Wave B): every method takes `tenantId`
+ * as its non-optional first parameter. `sessions`, `entities`,
+ * `entity_variants`, and `session_entities` are STAMP tables and every
+ * SELECT/UPDATE/DELETE against them routes its WHERE fragment through
+ * `tenantClause`; INSERTs stamp `tenant_id` explicitly. `markers` and
+ * `session_edges` carry no `tenant_id` column (DERIVE-VIA-FK) — they are
+ * reached only through an already tenant-filtered session id set, or (for
+ * `recentMarkers`/`markSuperseded`'s fact cascade) via an explicit join back
+ * to a tenant-filtered `sessions` row.
  */
 import { existsSync, mkdirSync } from "node:fs";
 import { dirname, resolve } from "node:path";
@@ -21,6 +31,9 @@ import { runMigrations } from "./migrate.js";
 import { tokenize } from "../recall/tokenize.js";
 import { chunkSessionText } from "../embedding/chunk-body.js";
 import { batchWinners } from "./fact-batch.js";
+import { tenantClause } from "../tenancy/tenant-clause.js";
+import { DEFAULT_TEAM_ID } from "../tenancy/default-team.js";
+import { recordEmbedFailure } from "../health/embed-failure-state.js";
 /**
  * Find the most recent prior session whose entity-set is identical to the new
  * session's, so a `continues` edge can link the two. "Identical" means same set
@@ -28,18 +41,28 @@ import { batchWinners } from "./fact-batch.js";
  * session is not superseding/replacing anything — a continuation extends a prior
  * topic rather than overturning it. Returns null when there is no such prior
  * (no entities, or no exact-set match), which leaves the pair unlinked and thus
- * eligible to surface in the re_derivation_rate metric.
+ * eligible to surface in the re_derivation_rate metric. Scoped to the same
+ * tenant as the new session — a continuation can never cross tenants.
  */
-function findContinuesPredecessor(db, newId, rawEntities) {
+function findContinuesPredecessor(db, tenantId, newId, rawEntities) {
     const entities = [...new Set(rawEntities.map((e) => e.trim()).filter(Boolean))];
     if (entities.length === 0)
         return null;
     const placeholders = entities.map(() => "?").join(",");
+    // session_entities rows are always written with the same tenant_id as their
+    // owning session (every write site stamps both together), so scoping the
+    // outer `sessions` row by tenant is already sufficient. The `se.tenant_id =
+    // s.tenant_id` join condition below is defense in depth (guard test C4
+    // explicitly permits column-to-column tenant equality as a join form) — it
+    // costs nothing and survives a future write path that stamps the two rows
+    // inconsistently.
+    const tc = tenantClause(tenantId, "s.tenant_id");
     const row = db
         .prepare(`SELECT s.id AS id
          FROM sessions s
-         JOIN session_entities se ON se.session_id = s.id
+         JOIN session_entities se ON se.session_id = s.id AND se.tenant_id = s.tenant_id
         WHERE s.id != ?
+          AND ${tc.sql}
           AND se.entity_canonical IN (${placeholders})
         GROUP BY s.id
        HAVING COUNT(DISTINCT se.entity_canonical) = ?
@@ -47,13 +70,16 @@ function findContinuesPredecessor(db, newId, rawEntities) {
             = (SELECT COUNT(*) FROM session_entities x WHERE x.session_id = s.id)
         ORDER BY s.started_at DESC, s.id DESC
         LIMIT 1`)
-        .get(newId, ...entities, entities.length);
+        .get(newId, tc.param, ...entities, entities.length);
     return row?.id ?? null;
 }
 export class SqliteSessionStore {
     db;
-    overlayCache = null;
-    overlayCacheAt = 0;
+    // Keyed by tenantId — a single-tenant Map entry today (DEFAULT_TEAM_ID),
+    // but the overlay's content is tenant-scoped (program spec §4.6 hardening
+    // 1) and must never bleed across tenants once M3 adds real multi-tenant
+    // traffic to one daemon instance.
+    overlayCache = new Map();
     /**
      * @internal. Construct via SqliteStorage.create(...) instead. Direct
      * construction is preserved for the SqliteStorage adapter only; all
@@ -90,38 +116,42 @@ export class SqliteSessionStore {
         return this.db;
     }
     invalidateOverlayCache() {
-        this.overlayCache = null;
+        this.overlayCache.clear();
     }
-    overlay() {
+    overlay(tenantId) {
         // TTL backstop: explicit invalidation covers the daemon's own writers; the
         // 30s expiry bounds staleness if another process ever writes actions to
         // this database file.
-        if (this.overlayCache !== null && Date.now() - this.overlayCacheAt < 30_000) {
-            return this.overlayCache;
+        const cached = this.overlayCache.get(tenantId);
+        if (cached !== undefined && Date.now() - cached.at < 30_000) {
+            return cached.overlay;
         }
-        this.overlayCache = loadActionOverlay(this.db);
-        this.overlayCacheAt = Date.now();
-        return this.overlayCache;
+        const overlay = loadActionOverlay(this.db, tenantId);
+        this.overlayCache.set(tenantId, { overlay, at: Date.now() });
+        return overlay;
     }
     /** Recently-written sessions ordered by created_at desc. Powers /live Writes column. */
-    recentWrites(limit) {
+    recentWrites(tenantId, limit) {
+        const tc = tenantClause(tenantId);
         const rows = this.db
             .prepare(`SELECT id, runtime, label, summary, created_at AS createdAt
          FROM sessions
+         WHERE ${tc.sql}
          ORDER BY created_at DESC
          LIMIT ?`)
-            .all(limit);
+            .all(tc.param, limit);
         if (rows.length === 0)
             return [];
         // Pull associated entities in one shot keyed by session id; cheap because
         // limit is small (<=50). Renders as topic chips on the /live row.
         const placeholders = rows.map(() => "?").join(",");
+        const entTc = tenantClause(tenantId);
         const entityRows = this.db
             .prepare(`SELECT session_id, entity_canonical
          FROM session_entities
-         WHERE session_id IN (${placeholders})
+         WHERE ${entTc.sql} AND session_id IN (${placeholders})
          ORDER BY entity_canonical`)
-            .all(...rows.map((r) => r.id));
+            .all(entTc.param, ...rows.map((r) => r.id));
         const byId = new Map();
         for (const e of entityRows) {
             const list = byId.get(e.session_id);
@@ -133,14 +163,16 @@ export class SqliteSessionStore {
         return rows.map((r) => ({ ...r, entities: byId.get(r.id) ?? [] }));
     }
     /** Recently-extracted markers ordered by session created_at desc. Powers /live Decisions column. */
-    recentMarkers(limit) {
+    recentMarkers(tenantId, limit) {
+        const tc = tenantClause(tenantId, "s.tenant_id");
         return this.db
             .prepare(`SELECT m.session_id AS sessionId, m.kind, m.text, s.label, s.created_at AS createdAt
          FROM markers m
          JOIN sessions s ON s.id = m.session_id
+         WHERE ${tc.sql}
          ORDER BY s.created_at DESC, m.position ASC
          LIMIT ?`)
-            .all(limit);
+            .all(tc.param, limit);
     }
     /**
      * Atomic ingest: writes the session row, markers, entity rows + links,
@@ -153,7 +185,7 @@ export class SqliteSessionStore {
      * Mirrors Python's SQLiteStore.insert_session. Markdown projection is not
      * yet ported and skipped here.
      */
-    async insertSession(record, embedder = null, supersedes = null, factSink = null) {
+    async insertSession(tenantId, record, embedder = null, supersedes = null, factSink = null) {
         const db = this.db;
         const txn = db.transaction(() => {
             db.prepare(`
@@ -161,11 +193,15 @@ export class SqliteSessionStore {
           id, runtime, runtime_session_id, started_at, ended_at, duration_min,
           label, summary, body, status,
           transcript_kind, transcript_path, transcript_offset, transcript_length,
-          classifier_provider, classifier_model, classifier_confidence
+          classifier_provider, classifier_model, classifier_confidence,
+          scope, agent_persona, parent_session_id,
+          primary_model, total_tokens, skill, tenant_id
         ) VALUES (@id, @runtime, @runtimeSessionId, @startedAt, @endedAt, @durationMin,
           @label, @summary, @body, @status,
           @transcriptKind, @transcriptPath, @transcriptOffset, @transcriptLength,
-          @classifierProvider, @classifierModel, @classifierConfidence)
+          @classifierProvider, @classifierModel, @classifierConfidence,
+          @scope, @agentPersona, @parentSessionId,
+          @primaryModel, @totalTokens, @skill, @tenantId)
         ON CONFLICT(id) DO UPDATE SET
           ended_at = excluded.ended_at,
           duration_min = excluded.duration_min,
@@ -176,6 +212,12 @@ export class SqliteSessionStore {
           classifier_provider = excluded.classifier_provider,
           classifier_model = excluded.classifier_model,
           classifier_confidence = excluded.classifier_confidence,
+          scope = COALESCE(excluded.scope, scope),
+          agent_persona = COALESCE(excluded.agent_persona, agent_persona),
+          parent_session_id = COALESCE(excluded.parent_session_id, parent_session_id),
+          primary_model = COALESCE(excluded.primary_model, primary_model),
+          total_tokens = COALESCE(excluded.total_tokens, total_tokens),
+          skill = COALESCE(excluded.skill, skill),
           updated_at = datetime('now')
       `).run({
                 id: record.id,
@@ -195,6 +237,13 @@ export class SqliteSessionStore {
                 classifierProvider: record.classifier?.provider ?? null,
                 classifierModel: record.classifier?.model ?? null,
                 classifierConfidence: record.classifier?.confidence ?? null,
+                scope: record.scope,
+                agentPersona: record.agentPersona ?? null,
+                parentSessionId: record.parentSessionId ?? null,
+                primaryModel: record.primaryModel ?? null,
+                totalTokens: record.totalTokens ?? null,
+                skill: record.skill ?? null,
+                tenantId,
             });
             db.prepare("DELETE FROM markers WHERE session_id = ?").run(record.id);
             const markerStmt = db.prepare("INSERT INTO markers (session_id, kind, text, position) VALUES (?, ?, ?, ?)");
@@ -207,42 +256,49 @@ export class SqliteSessionStore {
             const rawNewEntities = [...new Set(record.entities.map((e) => e.trim()).filter(Boolean))];
             // Resolve each extracted entity through entity_variants so merged surface
             // forms bind to the canonical instead of resurrecting the retired source.
-            const resolveVariant = db.prepare("SELECT canonical FROM entity_variants WHERE variant = ?");
-            const newEntities = rawNewEntities.map((name) => resolveVariant.get(name)?.canonical ?? name);
+            const variantTc = tenantClause(tenantId);
+            const resolveVariant = db.prepare(`SELECT canonical FROM entity_variants WHERE ${variantTc.sql} AND variant = ?`);
+            const newEntities = rawNewEntities.map((name) => resolveVariant.get(variantTc.param, name)?.canonical ?? name);
+            const oldEntityTc = tenantClause(tenantId);
             const oldEntityRows = db
-                .prepare("SELECT entity_canonical FROM session_entities WHERE session_id = ?")
-                .all(record.id);
+                .prepare(`SELECT entity_canonical FROM session_entities WHERE ${oldEntityTc.sql} AND session_id = ?`)
+                .all(oldEntityTc.param, record.id);
             const oldEntities = new Set(oldEntityRows.map((r) => r.entity_canonical));
-            db.prepare("DELETE FROM session_entities WHERE session_id = ?").run(record.id);
+            const deleteEntTc = tenantClause(tenantId);
+            db.prepare(`DELETE FROM session_entities WHERE ${deleteEntTc.sql} AND session_id = ?`).run(deleteEntTc.param, record.id);
             const insertEnt = db.prepare(`
         INSERT OR IGNORE INTO entities
-          (canonical, type, status, source, first_seen_session, last_seen_session, session_count)
-        VALUES (?, 'candidate', 'candidate', 'auto-detected', ?, ?, 0)
+          (tenant_id, canonical, type, status, source, first_seen_session, last_seen_session, session_count)
+        VALUES (?, ?, 'candidate', 'candidate', 'auto-detected', ?, ?, 0)
       `);
-            const touchLastSeen = db.prepare("UPDATE entities SET last_seen_session = ?, updated_at = datetime('now') WHERE canonical = ?");
-            const linkEnt = db.prepare("INSERT INTO session_entities (session_id, entity_canonical) VALUES (?, ?)");
+            const touchLastSeenTc = tenantClause(tenantId);
+            const touchLastSeen = db.prepare(`UPDATE entities SET last_seen_session = ?, updated_at = datetime('now') WHERE ${touchLastSeenTc.sql} AND canonical = ?`);
+            const linkEnt = db.prepare("INSERT INTO session_entities (tenant_id, session_id, entity_canonical) VALUES (?, ?, ?)");
             for (const name of newEntities) {
-                insertEnt.run(name, record.id, record.id);
+                insertEnt.run(tenantId, name, record.id, record.id);
                 // Update last_seen for entities newly added to this session; matches prior touch semantics.
                 if (!oldEntities.has(name)) {
-                    touchLastSeen.run(record.id, name);
+                    touchLastSeen.run(record.id, tenantId, name);
                 }
-                linkEnt.run(record.id, name);
+                linkEnt.run(tenantId, record.id, name);
             }
             // Recompute session_count exactly for every entity in (old union new) so
             // counts reflect reality regardless of prior drift.
-            const recomputeCount = db.prepare("UPDATE entities SET session_count = (SELECT COUNT(*) FROM session_entities WHERE entity_canonical = ?), updated_at = datetime('now') WHERE canonical = ?");
+            const recomputeInnerTc = tenantClause(tenantId);
+            const recomputeOuterTc = tenantClause(tenantId);
+            const recomputeCount = db.prepare(`UPDATE entities SET session_count = (SELECT COUNT(*) FROM session_entities WHERE ${recomputeInnerTc.sql} AND entity_canonical = ?), updated_at = datetime('now') WHERE ${recomputeOuterTc.sql} AND canonical = ?`);
             for (const name of new Set([...oldEntities, ...newEntities])) {
-                recomputeCount.run(name, name);
+                recomputeCount.run(tenantId, name, tenantId, name);
             }
             if (supersedes && supersedes.priorSessionId !== record.id) {
                 const predecessorStatus = supersedes.kind === "replaces" ? "replaced" : "superseded";
                 db.prepare(`INSERT OR IGNORE INTO session_edges (from_session, to_session, kind)
            VALUES (?, ?, ?)`).run(record.id, supersedes.priorSessionId, supersedes.kind);
-                db.prepare("UPDATE sessions SET status = ?, updated_at = datetime('now') WHERE id = ?").run(predecessorStatus, supersedes.priorSessionId);
+                const predStatusTc = tenantClause(tenantId);
+                db.prepare(`UPDATE sessions SET status = ?, updated_at = datetime('now') WHERE id = ? AND ${predStatusTc.sql}`).run(predecessorStatus, supersedes.priorSessionId, predStatusTc.param);
             }
             else {
-                const priorId = findContinuesPredecessor(db, record.id, record.entities);
+                const priorId = findContinuesPredecessor(db, tenantId, record.id, record.entities);
                 if (priorId !== null) {
                     db.prepare(`INSERT OR IGNORE INTO session_edges (from_session, to_session, kind)
              VALUES (?, ?, 'continues')`).run(record.id, priorId);
@@ -276,7 +332,7 @@ export class SqliteSessionStore {
                 // copy drifted from the port method and missed NLM #351 bug 1 (orphan
                 // embeddings on replace) and bug 2 (per-fact collapse -> supersedence
                 // cycles). Runs inside this session txn.
-                factSink.factStore.ingestSessionFactsInTxn(record.id, factSink.facts);
+                factSink.factStore.ingestSessionFactsInTxn(tenantId, record.id, factSink.facts, record.scope);
             }
         });
         txn();
@@ -300,13 +356,15 @@ export class SqliteSessionStore {
                     const { vector } = await embedder.embed(text, "document");
                     this.insertChunkEmbedding(record.id, chunkIdx, vector);
                 }
-                catch {
+                catch (err) {
                     // Per-chunk embedder failure must not roll the ingest back or
                     // abort subsequent chunks.
+                    recordEmbedFailure("chunk");
+                    process.stderr.write(`[nlm] embedding chunk failed session=${record.id} chunk=${chunkIdx}: ${String(err)}\n`);
                 }
             }
             if (factSink !== null) {
-                await this.embedFacts(factSink.factStore, factSink.facts, embedder);
+                await this.embedFacts(tenantId, factSink.factStore, factSink.facts, embedder);
             }
         }
     }
@@ -339,22 +397,27 @@ export class SqliteSessionStore {
      * Non-empty body required (the classifier needs transcript text). When
      * `reprocess` is false, sessions that already have facts are excluded.
      */
-    async listBackfillCandidates(filter) {
+    async listBackfillCandidates(tenantId, filter) {
+        const tc = tenantClause(tenantId, "s.tenant_id");
         const sql = filter.reprocess
-            ? `SELECT id, started_at, body FROM sessions
-         WHERE started_at < ? AND body IS NOT NULL AND length(body) > 0
-           ${filter.from ? "AND id > ?" : ""}
-         ORDER BY started_at ASC, id ASC`
+            ? `SELECT s.id, s.started_at, s.body FROM sessions s
+         WHERE ${tc.sql} AND s.started_at < ? AND s.body IS NOT NULL AND length(s.body) > 0
+           ${filter.from ? "AND s.id > ?" : ""}
+         ORDER BY s.started_at ASC, s.id ASC`
+            // facts.tenant_id is always stamped to match its source_session_id's
+            // session tenant, so this is defense in depth on top of the already
+            // tenant-filtered outer sessions row (guard test C4 permits
+            // column-to-column tenant equality as a join form).
             : `SELECT s.id, s.started_at, s.body FROM sessions s
-         WHERE s.started_at < ? AND s.body IS NOT NULL AND length(s.body) > 0
-           AND NOT EXISTS (SELECT 1 FROM facts f WHERE f.source_session_id = s.id)
+         WHERE ${tc.sql} AND s.started_at < ? AND s.body IS NOT NULL AND length(s.body) > 0
+           AND NOT EXISTS (SELECT 1 FROM facts f WHERE f.source_session_id = s.id AND f.tenant_id = s.tenant_id)
            ${filter.from ? "AND s.id > ?" : ""}
          ORDER BY s.started_at ASC, s.id ASC`;
         const rows = filter.from
             ? this.db.prepare(sql)
-                .all(filter.cutoff, filter.from)
+                .all(tc.param, filter.cutoff, filter.from)
             : this.db.prepare(sql)
-                .all(filter.cutoff);
+                .all(tc.param, filter.cutoff);
         return rows.map((r) => ({ id: r.id, startedAt: r.started_at, body: r.body }));
     }
     /**
@@ -369,16 +432,17 @@ export class SqliteSessionStore {
      * write path. The live ingest path (`insertSession`) keeps using the
      * internal helpers directly so session+facts commit together.
      */
-    async insertFactsForSession(sessionId, factStore, facts, embedder = null) {
+    async insertFactsForSession(tenantId, sessionId, factStore, facts, embedder = null) {
         // Delegate to the canonical sync ingest (single source of truth for
         // replace + collapse + embedding cleanup). Sync because better-sqlite3 txn
         // callbacks must be sync; ingestSessionFactsInTxn is the sync core.
+        const sessionScope = await this.getSessionScopeById(tenantId, sessionId);
         const txn = this.db.transaction(() => {
-            factStore.ingestSessionFactsInTxn(sessionId, facts);
+            factStore.ingestSessionFactsInTxn(tenantId, sessionId, facts, sessionScope);
         });
         txn();
         if (embedder) {
-            await this.embedFacts(factStore, facts, embedder);
+            await this.embedFacts(tenantId, factStore, facts, embedder);
         }
     }
     /**
@@ -386,68 +450,43 @@ export class SqliteSessionStore {
      * embeddings to fact_embeddings via FactStore.upsertEmbedding. Per-fact
      * failures don't abort the batch, and never affect committed fact rows.
      */
-    async embedFacts(factStore, facts, embedder) {
+    async embedFacts(tenantId, factStore, facts, embedder) {
         for (const fact of batchWinners(facts)) {
             const factText = `${fact.subject} ${fact.predicate} ${fact.value}`.trim();
             if (!factText)
                 continue;
             try {
                 const { vector } = await embedder.embed(factText, "document");
-                await factStore.upsertEmbedding(fact.id, vector);
+                await factStore.upsertEmbedding(tenantId, fact.id, vector);
             }
-            catch {
+            catch (err) {
                 // Per-fact embedding failure must not abort embedding of subsequent
                 // facts. The fact row stays current; semantic recall just misses it
                 // until a future re-ingest.
+                recordEmbedFailure("fact");
+                process.stderr.write(`[nlm] embedding fact failed fact=${fact.id}: ${String(err)}\n`);
             }
         }
     }
-    async list(filter) {
-        const rows = this.db
-            .prepare(`
-        SELECT id, runtime, runtime_session_id, started_at, ended_at, duration_min,
-               label, summary, status, transcript_kind, transcript_path, body,
-               classifier_provider, classifier_model, classifier_confidence
-        FROM sessions
-        ORDER BY started_at ASC
-      `)
-            .all();
-        if (rows.length === 0)
-            return [];
-        const ids = rows.map((r) => r.id);
-        const entitiesByIdMap = this.loadEntities(ids);
-        const markersByIdMap = this.loadMarkers(ids);
-        const overlay = this.overlay();
-        const sessions = rows.map((r) => this.rowToSession(r, entitiesByIdMap, markersByIdMap, overlay));
-        if (!filter)
-            return sessions;
-        return sessions.filter((s) => {
-            if (filter.entity !== undefined && !s.entities.includes(filter.entity)) {
-                return false;
-            }
-            if (filter.hasDecisions === true && s.decisions.length === 0)
-                return false;
-            if (filter.hasOpenQuestions === true && s.open.length === 0)
-                return false;
-            return true;
-        });
-    }
-    async getById(sessionId) {
+    async getById(tenantId, sessionId) {
+        const tc = tenantClause(tenantId);
         const row = this.db
             .prepare(`
         SELECT id, runtime, runtime_session_id, started_at, ended_at, duration_min,
                label, summary, status, transcript_kind, transcript_path, body,
-               classifier_provider, classifier_model, classifier_confidence
+               classifier_provider, classifier_model, classifier_confidence,
+               agent_persona, parent_session_id,
+               primary_model, total_tokens, skill
         FROM sessions
-        WHERE id = ?
+        WHERE id = ? AND ${tc.sql}
       `)
-            .get(sessionId);
+            .get(sessionId, tc.param);
         if (!row)
             return null;
-        const entities = this.loadEntities([sessionId]);
+        const entities = this.loadEntities(tenantId, [sessionId]);
         const markers = this.loadMarkers([sessionId]);
         const edges = this.loadSessionEdges([sessionId]);
-        const overlay = this.overlay();
+        const overlay = this.overlay(tenantId);
         return this.rowToSession(row, entities, markers, overlay, edges);
     }
     /**
@@ -456,45 +495,47 @@ export class SqliteSessionStore {
      * never reads, and SELECTing it for the corpus is what wedged the
      * daemon. Resolved sessions carry `body: ""`.
      */
-    async getByIds(ids) {
+    async getByIds(tenantId, ids) {
         if (ids.length === 0)
             return [];
         const placeholders = ids.map(() => "?").join(",");
+        const tc = tenantClause(tenantId);
         const rows = this.db
             .prepare(`
         SELECT id, runtime, runtime_session_id, started_at, ended_at, duration_min,
                label, summary, status, transcript_kind, transcript_path
         FROM sessions
-        WHERE id IN (${placeholders})
+        WHERE id IN (${placeholders}) AND ${tc.sql}
       `)
-            .all(...ids);
+            .all(...ids, tc.param);
         if (rows.length === 0)
             return [];
         const foundIds = rows.map((r) => r.id);
-        const entitiesByIdMap = this.loadEntities(foundIds);
+        const entitiesByIdMap = this.loadEntities(tenantId, foundIds);
         const markersByIdMap = this.loadMarkers(foundIds);
-        const overlay = this.overlay();
+        const overlay = this.overlay(tenantId);
         return rows.map((r) => this.rowToSession({ ...r, body: null }, entitiesByIdMap, markersByIdMap, overlay));
     }
-    async listByDateRange(fromIso, toIso) {
+    async listByDateRange(tenantId, fromIso, toIso) {
+        const tc = tenantClause(tenantId);
         const rows = this.db
             .prepare(`
         SELECT id, runtime, runtime_session_id, started_at, ended_at, duration_min,
                label, summary, status, transcript_kind, transcript_path, workstream_id
         FROM sessions
-        WHERE started_at < ? AND (ended_at IS NULL OR ended_at >= ?)
+        WHERE started_at < ? AND (ended_at IS NULL OR ended_at >= ?) AND ${tc.sql}
         ORDER BY started_at ASC
       `)
-            .all(toIso, fromIso);
+            .all(toIso, fromIso, tc.param);
         if (rows.length === 0)
             return [];
         const ids = rows.map((r) => r.id);
-        const entitiesByIdMap = this.loadEntities(ids);
+        const entitiesByIdMap = this.loadEntities(tenantId, ids);
         const markersByIdMap = this.loadMarkers(ids);
-        const overlay = this.overlay();
+        const overlay = this.overlay(tenantId);
         return rows.map((r) => this.rowToSession({ ...r, body: null }, entitiesByIdMap, markersByIdMap, overlay));
     }
-    async semanticSearch(queryVector, limit, opts) {
+    async semanticSearch(tenantId, queryVector, limit, opts) {
         const k = Math.max(1, Math.trunc(limit));
         const blob = Buffer.from(queryVector.buffer, queryVector.byteOffset, queryVector.byteLength);
         // Overfetch chunks so the max-pool grouping has enough unique sessions
@@ -505,6 +546,12 @@ export class SqliteSessionStore {
         const envOverfetch = Number.parseInt(process.env["NLM_CHUNK_OVERFETCH"] ?? "", 10);
         const CHUNK_OVERFETCH = Number.isFinite(envOverfetch) && envOverfetch > 0 ? envOverfetch : 4;
         const chunkK = k * CHUNK_OVERFETCH;
+        // The vec0 KNN scan has no tenant awareness (session_embedding_chunks
+        // carries no tenant_id — DERIVE-VIA-FK), so it returns neighbors from the
+        // whole corpus. The tenant filter is re-applied below, in the
+        // id-resolution join against `sessions` (program spec §4.3, vector-path
+        // rule) — any candidate session id that doesn't resolve within the
+        // caller's tenant is excluded, not merely "not down-ranked".
         const rows = this.db
             .prepare(`
         SELECT session_id, distance
@@ -515,19 +562,29 @@ export class SqliteSessionStore {
       `)
             .all(blob, chunkK);
         // Max-pool: keep the smallest distance (highest cosine) per session,
-        // filtering out superseded, replaced, and out-of-workstream sessions.
+        // filtering out superseded, replaced, out-of-workstream, and (via the
+        // tenant-filtered id-resolution join) out-of-tenant sessions.
         const best = new Map();
         const excludedSessionIds = new Set();
         const wsIds = opts?.workstreamIds;
         if (wsIds !== undefined && wsIds.length === 0)
             return [];
-        // First pass: collect all unique session IDs to check their status + workstream
+        // First pass: resolve each unique candidate session id against the
+        // tenant-filtered sessions table to get its status + workstream. A
+        // candidate id that fails to resolve (wrong tenant or gone) is excluded
+        // outright, not merely left un-excluded.
         const uniqueSessionIds = [...new Set(rows.map((r) => r.session_id))];
         if (uniqueSessionIds.length > 0) {
             const placeholders = uniqueSessionIds.map(() => "?").join(",");
+            const tc = tenantClause(tenantId);
             const statusRows = this.db
-                .prepare(`SELECT id, status, workstream_id FROM sessions WHERE id IN (${placeholders})`)
-                .all(...uniqueSessionIds);
+                .prepare(`SELECT id, status, workstream_id FROM sessions WHERE id IN (${placeholders}) AND ${tc.sql}`)
+                .all(...uniqueSessionIds, tc.param);
+            const resolvedIds = new Set(statusRows.map((r) => r.id));
+            for (const id of uniqueSessionIds) {
+                if (!resolvedIds.has(id))
+                    excludedSessionIds.add(id);
+            }
             const excludeSuperseded = opts?.includeSuperseded !== true;
             for (const sr of statusRows) {
                 const statusExcluded = sr.status === "replaced" || (excludeSuperseded && sr.status === "superseded");
@@ -537,7 +594,7 @@ export class SqliteSessionStore {
                 }
             }
         }
-        // Second pass: max-pool, excluding superseded/replaced sessions
+        // Second pass: max-pool, excluding superseded/replaced/out-of-tenant sessions
         for (const r of rows) {
             if (excludedSessionIds.has(r.session_id))
                 continue;
@@ -558,7 +615,7 @@ export class SqliteSessionStore {
      * for better matches). User input is tokenized and rebuilt into a quoted
      * OR query so FTS5 metacharacters cannot reach the MATCH parser.
      */
-    async keywordSearch(query, limit, opts) {
+    async keywordSearch(tenantId, query, limit, opts) {
         const wsIds = opts?.workstreamIds;
         if (wsIds !== undefined && wsIds.length === 0)
             return [];
@@ -569,6 +626,7 @@ export class SqliteSessionStore {
         const statusFilter = opts?.includeSuperseded === true
             ? "AND s.status != 'replaced'"
             : "AND s.status NOT IN ('superseded', 'replaced')";
+        const tc = tenantClause(tenantId, "s.tenant_id");
         let wsFilter = "";
         const params = [matchExpr];
         if (wsIds?.length) {
@@ -576,6 +634,7 @@ export class SqliteSessionStore {
             wsFilter = `AND s.workstream_id IN (${ph})`;
             params.push(...wsIds);
         }
+        params.push(tc.param);
         params.push(k);
         const rows = this.db
             .prepare(`
@@ -586,48 +645,54 @@ export class SqliteSessionStore {
         WHERE sessions_fts MATCH ?
           ${statusFilter}
           ${wsFilter}
+          AND ${tc.sql}
         ORDER BY score DESC
         LIMIT ?
       `)
             .all(...params);
         return rows.map((r) => ({ sessionId: r.session_id, score: r.score }));
     }
-    async resolveSuccessors(ids) {
+    async resolveSuccessors(tenantId, ids) {
         if (ids.length === 0)
             return new Map();
         const placeholders = ids.map(() => "?").join(",");
+        const tc = tenantClause(tenantId, "s.tenant_id");
         const rows = this.db
             .prepare(`
-        SELECT from_session, to_session
-        FROM session_edges
-        WHERE kind = 'supersedes'
-          AND to_session IN (${placeholders})
+        SELECT se.from_session, se.to_session
+        FROM session_edges se
+        JOIN sessions s ON s.id = se.to_session
+        WHERE se.kind = 'supersedes'
+          AND se.to_session IN (${placeholders})
+          AND ${tc.sql}
       `)
-            .all(...ids);
+            .all(...ids, tc.param);
         const out = new Map();
         for (const r of rows)
             out.set(r.to_session, r.from_session);
         return out;
     }
-    async updateStatus(sessionId, status) {
+    async updateStatus(tenantId, sessionId, status) {
         if (status === "idle") {
             throw new Error("Cannot persist derived status 'idle' — only active/closed/superseded");
         }
+        const tc = tenantClause(tenantId);
         this.db
-            .prepare("UPDATE sessions SET status = ?, updated_at = datetime('now') WHERE id = ?")
-            .run(status, sessionId);
+            .prepare(`UPDATE sessions SET status = ?, updated_at = datetime('now') WHERE id = ? AND ${tc.sql}`)
+            .run(status, sessionId, tc.param);
     }
-    async markSuperseded(predecessorId, successorId) {
+    async markSuperseded(tenantId, predecessorId, successorId) {
         if (predecessorId === successorId) {
             throw new Error("A session cannot supersede itself");
         }
-        const existsStmt = this.db.prepare("SELECT COUNT(*) AS c FROM sessions WHERE id = ?");
+        const existsTc = tenantClause(tenantId);
+        const existsStmt = this.db.prepare(`SELECT COUNT(*) AS c FROM sessions WHERE id = ? AND ${existsTc.sql}`);
         const txn = this.db.transaction(() => {
-            const predExists = (existsStmt.get(predecessorId)?.c ?? 0) > 0;
+            const predExists = (existsStmt.get(predecessorId, tenantId)?.c ?? 0) > 0;
             if (!predExists) {
                 throw new Error(`predecessor session ${predecessorId} not found`);
             }
-            const succExists = (existsStmt.get(successorId)?.c ?? 0) > 0;
+            const succExists = (existsStmt.get(successorId, tenantId)?.c ?? 0) > 0;
             if (!succExists) {
                 throw new Error(`successor session ${successorId} not found`);
             }
@@ -672,56 +737,68 @@ export class SqliteSessionStore {
                 .prepare(`INSERT OR IGNORE INTO session_edges (from_session, to_session, kind)
            VALUES (?, ?, 'supersedes')`)
                 .run(successorId, predecessorId);
+            const statusTc = tenantClause(tenantId);
             this.db
-                .prepare("UPDATE sessions SET status = 'superseded', updated_at = datetime('now') WHERE id = ?")
-                .run(predecessorId);
+                .prepare(`UPDATE sessions SET status = 'superseded', updated_at = datetime('now') WHERE id = ? AND ${statusTc.sql}`)
+                .run(predecessorId, statusTc.param);
             // Cascade supersedence to facts: link predecessor facts to their successors
-            const selectPredFacts = this.db.prepare("SELECT id, subject, predicate FROM facts WHERE source_session_id = ?");
-            const selectSuccFact = this.db.prepare("SELECT id FROM facts WHERE source_session_id = ? AND subject = ? AND predicate = ? AND superseded_by IS NULL LIMIT 1");
-            const updateFactSuperseded = this.db.prepare("UPDATE facts SET superseded_by = ? WHERE id = ?");
+            const predFactsTc = tenantClause(tenantId);
+            const selectPredFacts = this.db.prepare(`SELECT id, subject, predicate FROM facts WHERE source_session_id = ? AND ${predFactsTc.sql}`);
+            const succFactTc = tenantClause(tenantId);
+            const selectSuccFact = this.db.prepare(`SELECT id FROM facts WHERE source_session_id = ? AND subject = ? AND predicate = ? AND superseded_by IS NULL AND ${succFactTc.sql} LIMIT 1`);
+            const updateFactTc = tenantClause(tenantId);
+            const updateFactSuperseded = this.db.prepare(`UPDATE facts SET superseded_by = ? WHERE id = ? AND ${updateFactTc.sql}`);
             const delFactEmbedding = this.db.prepare("DELETE FROM fact_embeddings WHERE fact_id = ?");
-            const predecessorFacts = selectPredFacts.all(predecessorId);
+            const predecessorFacts = selectPredFacts.all(predecessorId, predFactsTc.param);
             for (const pFact of predecessorFacts) {
-                const successor = selectSuccFact.get(successorId, pFact.subject, pFact.predicate);
+                const successor = selectSuccFact.get(successorId, pFact.subject, pFact.predicate, succFactTc.param);
                 if (successor) {
-                    updateFactSuperseded.run(successor.id, pFact.id);
+                    updateFactSuperseded.run(successor.id, pFact.id, updateFactTc.param);
                     delFactEmbedding.run(pFact.id);
                 }
             }
         });
         txn();
     }
-    async setWorkstreamBinding(sessionId, workstreamId, source, confidence) {
-        this.db.prepare("UPDATE sessions SET workstream_id = ?, binding_source = ?, binding_confidence = ?, updated_at = datetime('now') WHERE id = ?").run(workstreamId, source, confidence, sessionId);
+    async getSessionScopeById(tenantId, id) {
+        const tc = tenantClause(tenantId);
+        const row = this.db.prepare(`SELECT scope FROM sessions WHERE id = ? AND ${tc.sql}`).get(id, tc.param);
+        return row?.scope ?? null;
     }
-    async listSessionIdsByWorkstreams(workstreamIds) {
+    async setWorkstreamBinding(tenantId, sessionId, workstreamId, source, confidence) {
+        const tc = tenantClause(tenantId);
+        this.db.prepare(`UPDATE sessions SET workstream_id = ?, binding_source = ?, binding_confidence = ?, updated_at = datetime('now') WHERE id = ? AND ${tc.sql}`).run(workstreamId, source, confidence, sessionId, tc.param);
+    }
+    async listSessionIdsByWorkstreams(tenantId, workstreamIds) {
         if (workstreamIds.length === 0)
             return [];
         const ph = workstreamIds.map(() => "?").join(",");
-        return this.db.prepare(`SELECT id FROM sessions WHERE workstream_id IN (${ph}) ORDER BY started_at ASC`).all(...workstreamIds).map((r) => r.id);
+        const tc = tenantClause(tenantId);
+        return this.db.prepare(`SELECT id FROM sessions WHERE workstream_id IN (${ph}) AND ${tc.sql} ORDER BY started_at ASC`).all(...workstreamIds, tc.param).map((r) => r.id);
     }
-    async getEntities(sessionId) {
-        return this.loadEntities([sessionId]).get(sessionId) ?? [];
+    async getEntities(tenantId, sessionId) {
+        return this.loadEntities(tenantId, [sessionId]).get(sessionId) ?? [];
     }
-    async getWorkstreamIds(sessionIds) {
+    async getWorkstreamIds(tenantId, sessionIds) {
         const out = new Map();
         if (sessionIds.length === 0)
             return out;
         const ph = sessionIds.map(() => "?").join(",");
-        for (const r of this.db.prepare(`SELECT id, workstream_id FROM sessions WHERE id IN (${ph})`).all(...sessionIds))
+        const tc = tenantClause(tenantId);
+        for (const r of this.db.prepare(`SELECT id, workstream_id FROM sessions WHERE id IN (${ph}) AND ${tc.sql}`).all(...sessionIds, tc.param))
             out.set(r.id, r.workstream_id);
         return out;
     }
     // ── insert helpers used by tests / future ingest path ─────────────────
     /** @internal test-only helper; production callers use insertSession(). */
-    insertSessionForTest(session) {
+    insertSessionForTest(session, tenantId = DEFAULT_TEAM_ID) {
         const stmt = this.db.prepare(`
       INSERT INTO sessions (
         id, runtime, runtime_session_id, started_at, ended_at, duration_min,
-        label, summary, body, status, transcript_kind, transcript_path
+        label, summary, body, status, transcript_kind, transcript_path, tenant_id
       ) VALUES (
         @id, @runtime, @runtimeSessionId, @startedAt, @endedAt, @durationMin,
-        @label, @summary, @body, @status, @transcriptKind, @transcriptPath
+        @label, @summary, @body, @status, @transcriptKind, @transcriptPath, @tenantId
       )
     `);
         const status = session.status === "idle" ? "active" : session.status;
@@ -738,15 +815,16 @@ export class SqliteSessionStore {
             status,
             transcriptKind: session.transcriptKind,
             transcriptPath: session.transcriptPath,
+            tenantId,
         });
         const entStmt = this.db.prepare(`
-      INSERT OR IGNORE INTO entities (canonical, type, status)
-      VALUES (?, 'candidate', 'active')
+      INSERT OR IGNORE INTO entities (tenant_id, canonical, type, status)
+      VALUES (?, ?, 'candidate', 'active')
     `);
-        const linkStmt = this.db.prepare("INSERT OR IGNORE INTO session_entities (session_id, entity_canonical) VALUES (?, ?)");
+        const linkStmt = this.db.prepare("INSERT OR IGNORE INTO session_entities (tenant_id, session_id, entity_canonical) VALUES (?, ?, ?)");
         for (const e of session.entities) {
-            entStmt.run(e);
-            linkStmt.run(session.id, e);
+            entStmt.run(tenantId, e);
+            linkStmt.run(tenantId, session.id, e);
         }
         const markerStmt = this.db.prepare("INSERT INTO markers (session_id, kind, text, position) VALUES (?, ?, ?, ?)");
         session.decisions.forEach((d, i) => markerStmt.run(session.id, "decision", d, i));
@@ -764,18 +842,19 @@ export class SqliteSessionStore {
         this.insertChunkEmbedding(sessionId, chunkIdx, vector);
     }
     // ── internal ──────────────────────────────────────────────────────────
-    loadEntities(ids) {
+    loadEntities(tenantId, ids) {
         if (ids.length === 0)
             return new Map();
         const placeholders = ids.map(() => "?").join(",");
+        const tc = tenantClause(tenantId);
         const rows = this.db
             .prepare(`
         SELECT session_id, entity_canonical
         FROM session_entities
-        WHERE session_id IN (${placeholders})
+        WHERE session_id IN (${placeholders}) AND ${tc.sql}
         ORDER BY session_id
       `)
-            .all(...ids);
+            .all(...ids, tc.param);
         const out = new Map();
         for (const r of rows) {
             const list = out.get(r.session_id);
@@ -879,6 +958,11 @@ export class SqliteSessionStore {
             classifierProvider: row.classifier_provider ?? null,
             classifierModel: row.classifier_model ?? null,
             classifierConfidence: row.classifier_confidence ?? null,
+            agentPersona: row.agent_persona ?? null,
+            parentSessionId: row.parent_session_id ?? null,
+            primaryModel: row.primary_model ?? null,
+            totalTokens: row.total_tokens ?? null,
+            skill: row.skill ?? null,
         };
     }
 }