@maudecode/talaria-web 1.17.2 → 1.19.0

package/dist/sessions/state-db.js

@@ -7,12 +7,19 @@
  */
 import { existsSync, openSync, readSync, closeSync, statSync } from 'node:fs';
 import { DatabaseSync } from 'node:sqlite';
+import { createHash } from 'node:crypto';
+import { Worker } from 'node:worker_threads';
 import { str } from '../util.js';
+import { stateDbMessageFingerprint, stateDbMessageKey } from './state-db-identity.js';
 import { MESSAGING_SOURCES } from './source-kind.js';
 import { looksLikeDefaultCliTitle, normalizeSourceName } from './titles.js';
 export const CLI_MIN_UNTITLED_USER_MESSAGE_COUNT = 2;
-const STATE_DB_BUSY_TIMEOUT_MS = 500;
+/** The Agent's `_READ_BUSY_TIMEOUT_S` (TAL-890): a DELETE-journal commit by another process blocks readers across its fsyncs. */
+const STATE_DB_BUSY_TIMEOUT_MS = 5000;
+/** The gateway watcher's change check stays cheap; a lock there fails over to a full projection. */
+const STATE_DB_FINGERPRINT_BUSY_TIMEOUT_MS = 500;
 const SOURCE_LABELS = {
+    bluebubbles: 'BlueBubbles', dingtalk: 'DingTalk', feishu: 'Feishu', qqbot: 'QQBot', yuanbao: 'Yuanbao', whatsapp_cloud: 'WhatsApp Cloud',
     acp: 'ACP', api_server: 'API', cli: 'CLI', cron: 'Cron', discord: 'Discord', email: 'Email', kanban: 'Kanban', wecom: 'WeCom', wecom_callback: 'WeCom Callback',
     slack: 'Slack', telegram: 'Telegram', tool: 'Tool', tui: 'TUI', webhook: 'Webhook', webui: 'WebUI', weixin: 'Weixin', matrix: 'Matrix', signal: 'Signal',
 };
@@ -89,6 +96,8 @@ export function isCliSessionRow(row) {
 export function isCliSessionRowVisible(row) {
     if (!isCliSessionRow(row))
         return true;
+    if (row._lineage_root_id && row._lineage_tip_id)
+        return true;
     const actual = positiveInt(row.actual_message_count);
     const messageCount = actual || positiveInt(row.message_count);
     if (messageCount <= 0)
@@ -107,9 +116,13 @@ export function isCliSessionRowVisible(row) {
     return countUserTurns(row) >= CLI_MIN_UNTITLED_USER_MESSAGE_COUNT;
 }
 // ── compression-chain projection ─────────────────────────────────────────
+/** The Agent's `_CHAIN_CAP`: the most hops a walk along a compression lineage takes. Its visited check stops a cycle sooner. */
+const COMPRESSION_CHAIN_CAP = 1000;
 function isContinuationSession(parent, child) {
     if (!parent || !child)
         return false;
+    if (lower(child.source) === 'tool' || explicitForkMarkers(child, true).length > 0)
+        return false;
     if (lower(child.session_source) === 'fork')
         return false;
     const parentSource = lower(parent.source);
@@ -202,6 +215,10 @@ export function projectAgentSessionRows(rows) {
     };
     const projected = [];
     for (const row of rows) {
+        if (row._lineage_root_id && row._lineage_tip_id) {
+            projected.push({ ...row });
+            continue;
+        }
         if (continuationChildIds.has(str(row.id)))
             continue;
         let segments = 1;
@@ -246,15 +263,175 @@ export function openStateDbReadonly(dbPath, busyTimeoutMs = STATE_DB_BUSY_TIMEOU
     const db = new DatabaseSync(dbPath, { readOnly: true, timeout: busyTimeoutMs });
     return db;
 }
+/** The table's columns; a failed read throws, so an unreadable database is never mistaken for an older schema (TAL-785). */
 function tableColumns(db, table) {
+    return new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((r) => r.name));
+}
+const LOCAL_POLICY_PREFIX = 'gateway.local_policy.v1:';
+/** Read-only equivalent of Agent validate_local_lineage. A receipt, never a reset edge alone, proves ownership. */
+function localLineages(db, sid) {
+    const result = new Map();
+    if (!tableColumns(db, 'state_meta').has('value'))
+        return result;
+    const cols = tableColumns(db, 'sessions');
+    if (!['chat_id', 'user_id', 'session_key', 'model_config', 'parent_session_id', 'end_reason'].every((c) => cols.has(c)))
+        return result;
+    const meta = db.prepare('SELECT value FROM state_meta WHERE key = ?');
+    const fetch = db.prepare('SELECT * FROM sessions WHERE id IN (SELECT value FROM json_each(?))');
+    const messageCols = tableColumns(db, 'messages');
+    const lastMessage = ['session_id', 'timestamp'].every((c) => messageCols.has(c)) ? '(SELECT MAX(m.timestamp) FROM messages m WHERE m.session_id = s.id)' : 'NULL';
+    const activity = `MAX(COALESCE(${cols.has('last_activity_at') ? 's.last_activity_at' : 'NULL'}, 0), COALESCE(${lastMessage}, 0), COALESCE(s.started_at, 0))`;
+    // Agent _CHAIN_STEP_SQL prefers a compression child, then a live child, then recency and id.
+    const children = db.prepare(`SELECT s.* FROM sessions s WHERE s.parent_session_id = ? ORDER BY CASE WHEN s.end_reason = 'compression' THEN 0 WHEN s.ended_at IS NULL THEN 1 ELSE 2 END, ${activity} DESC, s.started_at DESC, s.id DESC`);
+    const explicitChild = (child, includeReset) => {
+        return lower(child.source) === 'tool' || lower(child.session_source) === 'fork'
+            || explicitForkMarkers(child, includeReset).length > 0;
+    };
+    const compressionChildren = (parent) => str(parent.end_reason) === 'compression'
+        ? children.all(str(parent.id)).filter((child) => !explicitChild(child, true)) : [];
+    const owner = sid ? db.prepare('SELECT chat_id FROM sessions WHERE id = ?').get(sid)?.chat_id || sid : null;
+    const receipts = owner
+        ? db.prepare('SELECT key, value FROM state_meta WHERE key = ?').all(`${LOCAL_POLICY_PREFIX}${str(owner)}`)
+        : db.prepare('SELECT key, value FROM state_meta WHERE key GLOB ?').iterate(`${LOCAL_POLICY_PREFIX}*`);
+    for (const saved of receipts) {
+        try {
+            if (saved.value.length > 1_000_000)
+                continue;
+            const receipt = JSON.parse(saved.value);
+            const owner = saved.key.slice(LOCAL_POLICY_PREFIX.length);
+            const ids = receipt.lineage;
+            const entry = receipt.entry;
+            if (receipt.session_id !== owner || !Array.isArray(ids) || ids.length < 2 || ids.length > COMPRESSION_CHAIN_CAP
+                || !ids.every((id) => typeof id === 'string' && Boolean(id)) || new Set(ids).size !== ids.length
+                || ids[0] !== owner || ids.at(-1) !== entry?.session_id)
+                continue;
+            if (!['profile_id', 'principal_id', 'request_id', 'route'].every((key) => typeof receipt[key] === 'string' && receipt[key]))
+                continue;
+            if ('legacy_session_id' in receipt) {
+                const legacy = meta.get(`gateway.local_legacy.v1:${owner}`);
+                if (receipt.legacy_session_id !== owner || !legacy)
+                    continue;
+                const binding = JSON.parse(legacy.value);
+                if (!['session_id', 'profile_id', 'principal_id', 'legacy_session_id'].every((key) => binding[key] === receipt[key]))
+                    continue;
+            }
+            else {
+                // Python json.dumps uses ensure_ascii=True, including UTF-16 surrogate pairs.
+                const identity = JSON.stringify([receipt.profile_id, receipt.principal_id, receipt.request_id]).replace(/[\u007f-\uffff]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+                if (owner !== `local-${createHash('sha256').update(identity).digest('hex')}`)
+                    continue;
+            }
+            const byId = new Map(fetch.all(JSON.stringify(ids)).map((row) => [str(row.id), row]));
+            const rows = ids.map((id) => byId.get(id));
+            if (!rows.every((row) => Boolean(row) && row.chat_id === owner && row.user_id === receipt.principal_id && row.session_key === receipt.route))
+                continue;
+            let contextStart = 0;
+            let valid = true;
+            for (let i = 1; i < rows.length; i += 1) {
+                const parent = rows[i - 1], child = rows[i];
+                if (child.parent_session_id !== parent.id || explicitChild(child, false)) {
+                    valid = false;
+                    break;
+                }
+                if (parent.end_reason === 'session_reset') {
+                    const config = jsonLoadsIfString(child.model_config);
+                    if (!config || config._reset_from !== parent.id) {
+                        valid = false;
+                        break;
+                    }
+                    contextStart = i;
+                }
+                else {
+                    const next = compressionChildren(parent);
+                    if (next[0]?.id !== child.id) {
+                        valid = false;
+                        break;
+                    }
+                }
+            }
+            if (!valid || compressionChildren(rows.at(-1)).length)
+                continue;
+            const lineage = { owner, ids, context: ids.slice(contextStart), rows, title: [...rows].reverse().find((row) => row.title)?.title ?? null };
+            for (const id of ids)
+                result.set(id, lineage);
+        }
+        catch { /* Malformed receipts cannot attach history to another conversation. */ }
+    }
+    return result;
+}
+/** The validated receipt's current physical target, or the original id on old Agents / unproven metadata. */
+export function stateDbLocalTarget(dbPath, sid, opts = {}) {
+    if (!existsSync(dbPath)) {
+        opts.onRead?.(sid);
+        return sid;
+    }
+    let db;
     try {
-        return new Set(db.prepare(`PRAGMA table_info(${table})`).all().map((r) => r.name));
+        db = openStateDbReadonly(dbPath);
+    }
+    catch {
+        return sid;
+    }
+    try {
+        db.exec('BEGIN');
+        const target = localLineages(db, sid).get(sid)?.ids.at(-1) ?? sid;
+        opts.onRead?.(target);
+        return target;
     }
     catch {
-        return new Set();
+        return sid;
+    }
+    finally {
+        db.close();
     }
 }
+export const AGENT_STORAGE_OK = Object.freeze({ state: 'ok', reason: null });
+/**
+ * The corrupt-storage reason when `error` is SQLite's `SQLITE_CORRUPT` or `SQLITE_NOTADB` (the Agent's
+ * `hermes_state_health`), else null. The message is matched too, since a listing worker failure crosses the thread
+ * boundary as its message alone.
+ */
+export function stateDbCorruptReason(error) {
+    const code = error?.errcode;
+    const message = error instanceof Error ? error.message : String(error);
+    const corrupt = (typeof code === 'number' && [11, 26].includes(code & 0xff)) || /malformed|not a database/i.test(message);
+    return corrupt ? `Agent session storage (state.db) is damaged: ${message}. Agent sessions are unavailable until it is repaired or restored from a backup.` : null;
+}
+/** The storage state a failed `state.db` read reports: `corrupt` when SQLite says the file is damaged, else `unavailable`. */
+export function stateDbReadFailure(error) {
+    const corrupt = stateDbCorruptReason(error);
+    if (corrupt)
+        return { state: 'corrupt', reason: corrupt };
+    return { state: 'unavailable', reason: `Agent session storage (state.db) could not be read: ${error instanceof Error ? error.message : String(error)}.` };
+}
+/**
+ * TAL-785: whether `state.db` can serve the session list: `corrupt` when SQLite reports the file damaged, `unavailable`
+ * when it cannot be read for another reason (permissions, a lock, an I/O error), `outdated` when a readable database
+ * has no `sessions.source` column. A missing file is `ok`. Full-text index damage is never probed, so it stays `ok`, as
+ * the Agent treats it.
+ */
+export function stateDbStorage(dbPath) {
+    if (!existsSync(dbPath))
+        return AGENT_STORAGE_OK;
+    try {
+        const db = openStateDbReadonly(dbPath);
+        try {
+            if (!tableColumns(db, 'sessions').has('source'))
+                return { state: 'outdated', reason: `state.db has no 'source' column (older hermes-agent?). Agent sessions unavailable. Upgrade hermes-agent to fix this.` };
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch (error) {
+        return stateDbReadFailure(error);
+    }
+    return AGENT_STORAGE_OK;
+}
 const warnedNoSourceColumn = new Set();
+let readDelayMs = 0;
+/** Test hook: each listing read (and each listing worker request) blocks its thread this long first, standing in for a slow `state.db` (TAL-920). */
+export function setStateDbReadDelayForTests(ms) { readDelayMs = ms; }
 /**
  * Python `read_importable_agent_session_rows`. The recency slice is bounded to
  * `limit * 8` candidates before the messages aggregate runs; subagent parents
@@ -269,8 +446,12 @@ export function readImportableAgentSessionRows(dbPath, opts = {}) {
     const limit = opts.limit === undefined ? 200 : opts.limit;
     const exclude = opts.excludeSources === undefined ? ['cron', 'webui'] : opts.excludeSources;
     const include = opts.includeSources ?? null;
+    if (readDelayMs > 0)
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, readDelayMs);
     const db = openStateDbReadonly(dbPath);
     try {
+        db.exec('BEGIN'); // Receipt and physical rows must belong to the same committed generation.
+        const local = localLineages(db, opts.sessionIds?.length === 1 ? opts.sessionIds[0] : undefined);
         const sessionCols = tableColumns(db, 'sessions');
         const messageCols = tableColumns(db, 'messages');
         if (!sessionCols.has('source')) {
@@ -331,14 +512,26 @@ export function readImportableAgentSessionRows(dbPath, opts = {}) {
         let candidateOrder = 'ORDER BY s.started_at DESC';
         const where = ['s.source IS NOT NULL'];
         const params = [];
+        if (opts.sessionIds !== undefined) {
+            where.push('s.id IN (SELECT value FROM json_each(?))');
+            params.push(JSON.stringify(opts.sessionIds.map((id) => local.get(id)?.ids.at(-1) ?? id)));
+        }
+        const superseded = [...local].filter(([id, lineage]) => id !== lineage.ids.at(-1)).map(([id]) => id);
+        if (superseded.length) {
+            where.push('s.id NOT IN (SELECT value FROM json_each(?))');
+            params.push(JSON.stringify(superseded));
+        }
+        const hasPolicies = Boolean(db.prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'state_meta'").get());
+        const policySource = (id) => `(SELECT CASE WHEN json_valid(value) THEN json_extract(value, '$.policy.source') END FROM state_meta WHERE key = '${LOCAL_POLICY_PREFIX}' || ${id})`;
+        const sourceSql = hasPolicies ? `COALESCE(${policySource('s.id')}, ${sessionCols.has('chat_id') ? policySource('s.chat_id') : 'NULL'}, s.source)` : 's.source';
         const included = (include ?? []).map(String).filter(Boolean);
         if (included.length) {
-            where.push(`s.source IN (${included.map(() => '?').join(', ')})`);
+            where.push(`${sourceSql} IN (${included.map(() => '?').join(', ')})`);
             params.push(...included);
         }
         const excluded = (exclude ?? []).map(String).filter(Boolean);
         if (excluded.length) {
-            where.push(`s.source NOT IN (${excluded.map(() => '?').join(', ')})`);
+            where.push(`${sourceSql} NOT IN (${excluded.map(() => '?').join(', ')})`);
             params.push(...excluded);
         }
         const preaggregated = messagesHasSessionId && messagesHasTimestamp && included.length === 1 && included[0] === 'cron' && !messagesIndexPresent;
@@ -351,7 +544,7 @@ export function readImportableAgentSessionRows(dbPath, opts = {}) {
             orderBy = messagesIndexPresent ? 'ORDER BY COALESCE(last_activity, s.started_at) DESC' : 'ORDER BY COALESCE(MAX(m.timestamp), s.started_at) DESC';
             candidateOrder = 'ORDER BY COALESCE((SELECT MAX(mx.timestamp) FROM messages mx WHERE mx.session_id = s.id), s.started_at) DESC, s.started_at DESC';
         }
-        const selectSql = `SELECT s.id, s.title, s.model, s.message_count, s.started_at, s.source, ${['session_source', 'user_id', 'chat_id', 'chat_type', 'thread_id', 'session_key', 'origin_chat_id', 'origin_user_id', 'platform', 'parent_session_id', 'ended_at', 'end_reason'].map(col).join(', ')}, ${actualCountExpr} AS actual_message_count, ${userCountExpr} AS actual_user_message_count, ${lastActivityExpr} AS last_activity`;
+        const selectSql = `SELECT s.id, s.title, s.model, s.message_count, s.started_at, s.source, ${['model_config', 'session_source', 'user_id', 'chat_id', 'chat_type', 'thread_id', 'session_key', 'origin_chat_id', 'origin_user_id', 'platform', 'parent_session_id', 'ended_at', 'end_reason'].map(col).join(', ')}, ${actualCountExpr} AS actual_message_count, ${userCountExpr} AS actual_user_message_count, ${lastActivityExpr} AS last_activity`;
         let raw;
         if (limit !== null) {
             const resultLimit = Math.max(0, Math.trunc(limit));
@@ -366,8 +559,21 @@ export function readImportableAgentSessionRows(dbPath, opts = {}) {
         else {
             raw = db.prepare(`${selectSql} FROM sessions s ${joinClause} WHERE ${where.join(' AND ')} ${groupByClause} ${orderBy}`).all(...params);
         }
-        let projected = projectAgentSessionRows(raw.map((r) => ({ ...r })));
-        projected = projected.map((r) => ({ ...r, ...normalizeAgentSessionSource(r.source) }));
+        const owners = sessionSources(db, sessionCols, raw.map((r) => str(r.id)));
+        raw = raw.map((r) => { const owner = owners.get(str(r.id)); return { ...r, source: typeof owner === 'object' ? owner.source : owner || r.source }; });
+        let projected = projectAgentSessionRows(raw.map((r) => {
+            const lineage = local.get(str(r.id));
+            if (!lineage)
+                return { ...r };
+            const root = lineage.rows[0];
+            const title = lineage.title || r.title;
+            return { ...r, title, started_at: root.started_at, last_activity: r.last_activity ?? r.started_at, parent_session_id: root.parent_session_id,
+                _lineage_root_id: lineage.owner, _lineage_tip_id: r.id, _lineage_ids: [...lineage.ids], _compression_segment_count: lineage.ids.length };
+        }));
+        projected = projected.map((r) => {
+            const parent = local.get(str(r.parent_session_id));
+            return { ...r, ...normalizeAgentSessionSource(r.source), ...(parent ? { _parent_lineage_root_id: parent.owner, parent_title: parent.title, parent_source: parent.rows.at(-1)?.source ?? null } : {}) };
+        });
         projected = projected.filter(isCliSessionRowVisible);
         if (limit === null)
             return projected;
@@ -469,15 +675,138 @@ export function latestCronSessionInfo(dbPath, jobIds, completedIds) {
         db.close();
     }
 }
-/**
- * TAL-358: the `sessions.source` owner of each present id, in one chunked read. A missing state.db (or one without a
- * `source` column) owns nothing; an unreadable one answers null, so callers fail closed on an unknown owner.
- */
-export function stateDbSessionSources(dbPath, sessionIds) {
+/** A source label remains display metadata; canonical receipts and ledgers independently retain write ownership. */
+export const CANONICAL_READ_ONLY_REASON = 'This session is owned by the Agent gateway and is display-only in Talaria.';
+export const OWNERSHIP_UNAVAILABLE_REASON = 'Agent session ownership could not be verified. The session is read-only until storage is readable.';
+export const RETIRED_READ_ONLY_REASON = 'The Agent has retired this session identity. Open or import a new conversation to continue.';
+/** Ownership fences outlive the fully validated localLineages history: even a pruned or broken receipt cannot release a writer. */
+function sessionSources(db, cols, ids) {
     const sources = new Map();
+    const canReadRows = cols.has('id') && cols.has('source');
+    const tables = new Set(db.prepare("SELECT name FROM sqlite_master WHERE type = 'table'").all().map((r) => r.name));
+    const walk = canReadRows ? resumeLineageWalker(db, cols) : (sid) => [sid];
+    const lineages = new Map(ids.map((id) => [id, walk(id)]));
+    const segments = [...new Set([...lineages.values()].flat())];
+    const rows = new Map();
+    for (let i = 0; canReadRows && i < segments.length; i += 400) {
+        const chunk = segments.slice(i, i + 400);
+        for (const row of db.prepare(`SELECT id, source, ${cols.has('chat_id') ? 'chat_id' : 'NULL AS chat_id'} FROM sessions WHERE id IN (${chunk.map(() => '?').join(',')})`).all(...chunk))
+            rows.set(str(row.id), row);
+    }
+    const candidates = [...new Set([...segments, ...[...rows.values()].map((r) => str(r.chat_id)).filter(Boolean)])];
+    const candidateSet = new Set(candidates);
+    const policies = new Map();
+    const receiptOwners = new Map();
+    const retired = new Set();
+    const bindings = new Set();
+    const wanted = new Set(segments);
+    const policyValue = (value) => {
+        try {
+            const parsed = JSON.parse(str(value));
+            return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const rememberPolicy = (owner, policy) => {
+        const entry = policy?.entry;
+        const target = entry && typeof entry === 'object' && !Array.isArray(entry) ? entry.session_id : null;
+        const lineage = Array.isArray(policy?.lineage) ? policy.lineage : [];
+        const aliases = [owner, policy?.session_id, policy?.legacy_session_id, target, ...lineage];
+        if (!candidateSet.has(owner) && !aliases.some((id) => typeof id === 'string' && wanted.has(id)))
+            return;
+        policies.set(owner, policy);
+        for (const id of aliases)
+            if (typeof id === 'string' && wanted.has(id) && !receiptOwners.has(id))
+                receiptOwners.set(id, owner);
+    };
+    if (tables.has('state_meta')) {
+        const read = db.prepare('SELECT value FROM state_meta WHERE key = ?');
+        for (const owner of candidates) {
+            const raw = read.get(`${LOCAL_POLICY_PREFIX}${owner}`);
+            if (raw)
+                rememberPolicy(owner, policyValue(raw.value));
+            if (read.get(`gateway.retired_session.v1.${owner}`))
+                retired.add(owner);
+            if (read.get(`gateway.api.binding.v1.${owner}`))
+                bindings.add(owner);
+        }
+    }
+    const ledgerIds = new Set();
+    for (const [table, column] of [['session_admissions', 'target_session_id'], ['worker_executions', 'session_id']]) {
+        if (!tables.has(table))
+            continue;
+        const hasLineage = tableColumns(db, table).has('lineage_json');
+        for (let i = 0; i < candidates.length; i += 400) {
+            const chunk = candidates.slice(i, i + 400);
+            const marks = chunk.map(() => '?').join(',');
+            const linked = hasLineage ? ` OR EXISTS (SELECT 1 FROM json_each(lineage_json) WHERE value IN (${marks}))` : '';
+            const found = db.prepare(`SELECT ${column} AS id, ${hasLineage ? 'lineage_json' : 'NULL AS lineage_json'} FROM ${table} WHERE ${column} IN (${marks})${linked}`).all(...chunk, ...(hasLineage ? chunk : []));
+            for (const row of found) {
+                ledgerIds.add(row.id);
+                if (row.lineage_json !== null) {
+                    const lineage = JSON.parse(row.lineage_json);
+                    if (!Array.isArray(lineage) || !lineage.every((v) => typeof v === 'string'))
+                        throw new Error('Unreadable Agent admission lineage');
+                    for (const sid of lineage)
+                        ledgerIds.add(sid);
+                }
+            }
+        }
+    }
+    // Pruned/reset segments can survive only in a receipt, without a row or chat_id to follow.
+    if (tables.has('state_meta') && segments.some((id) => !receiptOwners.has(id) && !ledgerIds.has(id) && !retired.has(id) && !bindings.has(id))) {
+        for (const raw of db.prepare('SELECT key, value FROM state_meta WHERE key GLOB ?').iterate(`${LOCAL_POLICY_PREFIX}*`)) {
+            const policy = policyValue(raw.value);
+            const entry = policy?.entry;
+            const target = entry && typeof entry === 'object' && !Array.isArray(entry) ? entry.session_id : null;
+            if (!policy || typeof policy.session_id !== 'string' || typeof target !== 'string' || (policy.lineage !== undefined && (!Array.isArray(policy.lineage) || !policy.lineage.length || !policy.lineage.every((id) => typeof id === 'string'))))
+                throw new Error('Unreadable Agent ownership receipt');
+            const owner = raw.key.slice(LOCAL_POLICY_PREFIX.length);
+            if (!owner)
+                throw new Error('Unreadable Agent ownership receipt');
+            rememberPolicy(owner, policy);
+        }
+    }
+    const kanban = new Set(kanbanOwnedIds(db, cols, ids.filter((id) => rows.has(id))));
+    for (const id of ids) {
+        const row = rows.get(id);
+        let source = kanban.has(id) ? 'kanban' : str(row?.source);
+        let canonical = false;
+        let retiredId = false;
+        for (const segment of lineages.get(id) ?? [id]) {
+            const chatId = str(rows.get(segment)?.chat_id);
+            for (const owner of new Set([segment, chatId, receiptOwners.get(segment)].filter((v) => Boolean(v)))) {
+                if (retired.has(owner))
+                    retiredId = true;
+                if (ledgerIds.has(owner) || bindings.has(owner))
+                    canonical = true;
+                if (!policies.has(owner))
+                    continue;
+                const policy = policies.get(owner);
+                // A broken receipt never releases its owner or a physical row naming that owner.
+                canonical = true;
+                const origin = policy?.policy;
+                if (origin && typeof origin === 'object' && !Array.isArray(origin) && str(origin.source))
+                    source = str(origin.source);
+            }
+        }
+        const authority = canonical;
+        // LOCAL is the canonical transport. Missing receipts cannot prove it safe to claim.
+        if (lower(source) === 'local')
+            canonical = true;
+        if (!row && !canonical && !retiredId)
+            continue;
+        sources.set(id, retiredId && !authority ? { source, canonical: true, reason: RETIRED_READ_ONLY_REASON } : canonical ? { source, canonical: true } : source);
+    }
+    return sources;
+}
+/** Batched source/ownership probe. An unreadable authority answers null so callers fail closed. */
+export function stateDbSessionSources(dbPath, sessionIds) {
     const ids = [...new Set([...sessionIds].map((s) => s.trim()).filter(Boolean))];
     if (!ids.length || !existsSync(dbPath))
-        return sources;
+        return new Map();
     let db;
     try {
         db = openStateDbReadonly(dbPath);
@@ -486,15 +815,8 @@ export function stateDbSessionSources(dbPath, sessionIds) {
         return null;
     }
     try {
-        const cols = tableColumns(db, 'sessions');
-        if (!cols.has('id') || !cols.has('source'))
-            return sources;
-        for (let i = 0; i < ids.length; i += 500) {
-            const chunk = ids.slice(i, i + 500);
-            for (const row of db.prepare(`SELECT id, source FROM sessions WHERE id IN (${chunk.map(() => '?').join(',')})`).all(...chunk))
-                sources.set(row.id, str(row.source));
-        }
-        return sources;
+        db.exec('BEGIN');
+        return sessionSources(db, tableColumns(db, 'sessions'), ids);
     }
     catch {
         return null;
@@ -503,6 +825,76 @@ export function stateDbSessionSources(dbPath, sessionIds) {
         db.close();
     }
 }
+/** The same marker parser serves conservative history boundaries and exact-parent ownership walks. */
+function explicitForkMarkers(row, includeReset) {
+    let cfg = row.model_config;
+    if (typeof cfg === 'string') {
+        try {
+            cfg = JSON.parse(cfg);
+        }
+        catch {
+            return [];
+        }
+    }
+    if (!cfg || typeof cfg !== 'object' || Array.isArray(cfg))
+        return [];
+    const c = cfg;
+    return [c._branched_from, c._delegate_from, ...(includeReset ? [c._reset_from] : [])].filter((m) => m !== undefined && m !== null);
+}
+/** Python `_is_explicit_fork_child_row`: a tool child, or a branch/delegate (`includeReset`: also reset) fork of its parent. */
+function isExplicitForkChild(row, includeReset) {
+    if (str(row.source) === 'tool')
+        return true;
+    const markers = explicitForkMarkers(row, includeReset);
+    const parentId = row.parent_session_id;
+    return parentId ? markers.includes(parentId) : markers.length > 0;
+}
+/**
+ * Python `_resume_lineage_ids`: `sid` and the compression ancestors a resume loads, root first. Each hop's parent ended
+ * `compression` and the child is no branch, reset, delegate or tool fork. The walk stops at a cycle or the Agent's
+ * 1000-hop `_CHAIN_CAP`; without the lineage columns it is `[sid]`.
+ */
+function resumeLineageWalker(db, cols) {
+    if (!['parent_session_id', 'end_reason'].every((c) => cols.has(c)))
+        return (sid) => [sid];
+    const select = db.prepare(`SELECT id, source, parent_session_id, end_reason, ${cols.has('model_config') ? 'model_config' : 'NULL AS model_config'} FROM sessions WHERE id = ?`);
+    return (sid) => {
+        const chain = [sid];
+        let current = select.get(sid);
+        if (!current || isExplicitForkChild(current, false))
+            return chain;
+        while (chain.length < 1000) {
+            const parentId = str(current.parent_session_id);
+            if (!parentId || chain.includes(parentId) || isExplicitForkChild(current, true))
+                break;
+            const parent = select.get(parentId);
+            if (str(parent?.end_reason) !== 'compression')
+                break;
+            chain.push(parentId);
+            current = parent;
+        }
+        return chain.reverse();
+    };
+}
+/**
+ * TAL-793 (Agent `is_kanban_owned_session`): the `ids` whose compression lineage has a `kanban` `source` or
+ * `created_source` (schema v31; `source` alone decides before it), a Kanban worker's transcript only its dispatcher continues.
+ */
+function kanbanOwnedIds(db, cols, ids) {
+    if (!ids.length)
+        return [];
+    const walk = resumeLineageWalker(db, cols);
+    const lineages = ids.map(walk);
+    const segments = [...new Set(lineages.flat())];
+    const match = cols.has('created_source') ? "(source = 'kanban' OR created_source = 'kanban')" : "source = 'kanban'";
+    const kanban = new Set();
+    for (let i = 0; i < segments.length; i += 500) {
+        const chunk = segments.slice(i, i + 500);
+        for (const row of db.prepare(`SELECT id FROM sessions WHERE id IN (${chunk.map(() => '?').join(',')}) AND ${match}`).all(...chunk))
+            kanban.add(row.id);
+    }
+    return ids.filter((_, i) => lineages[i].some((sid) => kanban.has(sid)));
+}
 /** Python `state_db_has_session`: true only when `sid` is a row of the sessions table; a missing or unreadable db is false. */
 export function stateDbHasSession(dbPath, sid) {
     const id = sid.trim();
@@ -535,7 +927,7 @@ export function stateDbHasSession(dbPath, sid) {
 export function cheapChangeFingerprint(dbPath, onError) {
     try {
         const parts = [];
-        const db = openStateDbReadonly(dbPath);
+        const db = openStateDbReadonly(dbPath, STATE_DB_FINGERPRINT_BUSY_TIMEOUT_MS);
         try {
             for (const table of ['sessions', 'messages']) {
                 try {
@@ -579,19 +971,143 @@ export function cheapChangeFingerprint(dbPath, onError) {
         return null;
     }
 }
+let listingWorker = null;
+let nextCallId = 0;
+/** Set while `stopStateDbWorker` waits for the worker to exit; calls then reject instead of starting another worker. */
+let stoppingWorker = false;
+/** Reject every call still waiting on `current` and forget it, so the next call starts a fresh worker. */
+function retireListingWorker(current, error) {
+    if (listingWorker === current)
+        listingWorker = null;
+    for (const call of current.pending.values())
+        call.reject(error);
+    current.pending.clear();
+}
+/** The lazily started, long-lived listing worker; requests run one at a time in arrival order. */
+function startedListingWorker() {
+    if (listingWorker)
+        return listingWorker;
+    // Source runs (vitest) load the TypeScript worker; the build runs the compiled one beside this module.
+    const ext = import.meta.url.endsWith('.ts') ? 'ts' : 'js';
+    const current = { worker: new Worker(new URL(`./state-db-worker.${ext}`, import.meta.url)), pending: new Map() };
+    current.worker.unref();
+    current.worker.on('message', (reply) => {
+        const call = current.pending.get(reply.id);
+        if (!call)
+            return;
+        current.pending.delete(reply.id);
+        if (!current.pending.size)
+            current.worker.unref();
+        call.resolve(reply);
+    });
+    current.worker.on('error', (error) => { retireListingWorker(current, error); });
+    current.worker.on('exit', (code) => { retireListingWorker(current, new Error(`state.db worker exited with code ${String(code)}`)); });
+    listingWorker = current;
+    return current;
+}
+function callListingWorker(call) {
+    // A multi-read caller the stop interrupted goes on to its next read; that read must not restart the worker.
+    if (stoppingWorker)
+        return Promise.reject(new Error('state.db worker stopped'));
+    const current = startedListingWorker();
+    const id = ++nextCallId;
+    return new Promise((resolve, reject) => {
+        current.pending.set(id, { resolve, reject });
+        // A call in flight keeps the process alive until it settles; an idle worker never does.
+        current.worker.ref();
+        current.worker.postMessage({ ...call, id, delayMs: readDelayMs });
+    });
+}
+/** `readImportableAgentSessionRows` on the listing worker, so a slow `state.db` never blocks the event loop. Rejects when the worker fails. */
+export async function readImportableAgentSessionRowsAsync(dbPath, opts = {}) {
+    const { log, ...query } = opts;
+    const reply = await callListingWorker({ op: 'rows', dbPath, opts: query });
+    for (const line of reply.logs)
+        log?.(line);
+    if (reply.error !== undefined)
+        throw new Error(reply.error);
+    return reply.value;
+}
+/** `cheapChangeFingerprint` on the listing worker; a worker failure reports as a failed change check. */
+export async function cheapChangeFingerprintAsync(dbPath, onError) {
+    let reply;
+    try {
+        reply = await callListingWorker({ op: 'fingerprint', dbPath });
+    }
+    catch (error) {
+        onError?.('change check failed', error);
+        return null;
+    }
+    for (const [reason, message] of reply.failures)
+        onError?.(reason, new Error(message));
+    return reply.value;
+}
+/** `stateDbStorage` on the listing worker; a worker failure is `unavailable`. */
+export async function stateDbStorageAsync(dbPath) {
+    try {
+        return (await callListingWorker({ op: 'storage', dbPath })).value;
+    }
+    catch (error) {
+        return stateDbReadFailure(error);
+    }
+}
+/** `stateDbSessionSources` on the listing worker; a worker failure is an unreadable state.db (null), so owners stay locked. */
+export async function stateDbSessionSourcesAsync(dbPath, sessionIds) {
+    try {
+        return (await callListingWorker({ op: 'sources', dbPath, ids: [...sessionIds] })).value;
+    }
+    catch {
+        return null;
+    }
+}
+/** `agentSessionRowsExisting` on the listing worker; a worker failure assumes every row present, so nothing is pruned. */
+export async function agentSessionRowsExistingAsync(dbPath, sessionIds) {
+    const ids = [...sessionIds];
+    try {
+        return (await callListingWorker({ op: 'existing', dbPath, ids })).value;
+    }
+    catch {
+        return new Set(ids.map((s) => s.trim()).filter(Boolean));
+    }
+}
+/** Test hook: the listing worker exits abruptly while this call is in flight. */
+export function crashStateDbWorkerForTests() {
+    return callListingWorker({ op: 'crash' });
+}
+/** Stop the listing worker (server shutdown). Calls in flight reject; a later call starts a new worker. */
+export async function stopStateDbWorker() {
+    const current = listingWorker;
+    if (!current)
+        return;
+    stoppingWorker = true;
+    try {
+        retireListingWorker(current, new Error('state.db worker stopped'));
+        await current.worker.terminate();
+    }
+    finally {
+        stoppingWorker = false;
+    }
+}
 // ── message reader ────────────────────────────────────────────────────────
 const STATE_DB_CONTENT_JSON_PREFIX = '\0json:';
 // `display_kind` / `display_metadata`: the Agent's own tag for rows it writes itself (steers, delivered notifications; TAL-371).
-const OPTIONAL_MESSAGE_COLUMNS = ['tool_call_id', 'tool_calls', 'tool_name', 'reasoning', 'reasoning_details', 'codex_reasoning_items', 'reasoning_content', 'codex_message_items', 'api_content', 'display_kind', 'display_metadata'];
-const JSON_MESSAGE_COLUMNS = new Set(['tool_calls', 'reasoning_details', 'codex_reasoning_items', 'codex_message_items', 'display_metadata']);
+const OPTIONAL_MESSAGE_COLUMNS = ['tool_call_id', 'tool_calls', 'tool_name', 'reasoning', 'reasoning_details', 'codex_reasoning_items', 'reasoning_content', 'codex_message_items', 'api_content', 'display_kind', 'display_metadata', 'absorbed_message_uids'];
+const JSON_MESSAGE_COLUMNS = new Set(['tool_calls', 'reasoning_details', 'codex_reasoning_items', 'codex_message_items', 'display_metadata', 'absorbed_message_uids']);
 /** Python `_decode_state_db_content`: the Agent's sentinel-prefixed structured content, left untouched otherwise. */
 function decodeStateDbContent(value) {
     const text = Buffer.isBuffer(value) ? value.toString('utf8') : value;
     if (typeof text !== 'string' || !text.startsWith(STATE_DB_CONTENT_JSON_PREFIX))
         return text;
     try {
-        const decoded = JSON.parse(text.slice(STATE_DB_CONTENT_JSON_PREFIX.length));
-        return Array.isArray(decoded) ? decoded : text;
+        const payload = text.slice(STATE_DB_CONTENT_JSON_PREFIX.length);
+        let unsafeInteger = false;
+        const decoded = JSON.parse(payload, (_key, value, context) => {
+            if (typeof value === 'number' && !Number.isSafeInteger(value) && /^-?\d+$/.test(context?.source ?? ''))
+                unsafeInteger = true;
+            return value;
+        });
+        // Python keeps arbitrary-precision integers. Retain the JSON text rather than silently rounding any of them.
+        return unsafeInteger ? payload : decoded;
     }
     catch {
         return text;
@@ -616,11 +1132,13 @@ function projectStateDbMessage(row, hasId) {
         const value = row[col];
         if (value === null || value === undefined || value === '')
             continue;
-        msg[col] = JSON_MESSAGE_COLUMNS.has(col) ? jsonLoadsIfString(value) : value;
+        msg[col === 'absorbed_message_uids' ? '_absorbed_message_uids' : col] = JSON_MESSAGE_COLUMNS.has(col) ? jsonLoadsIfString(value) : value;
     }
     // TAL-493: the merge tells rows committed after the session's last read by this id.
     if (hasId && row.id !== null && row.id !== undefined)
         msg._state_db_row_id = row.id;
+    if (typeof row.message_uid === 'string' && row.message_uid.length)
+        msg._state_db_message_uid = row.message_uid;
     if (msg.role === 'tool' && msg.tool_name && !msg.name)
         msg.name = msg.tool_name;
     return msg;
@@ -639,6 +1157,74 @@ function stateDbGeneration(dbPath) {
         return null;
     }
 }
+// Agent v0.21.6's exact in-flight request wrapper. Unknown rewrites are not copy evidence.
+const INFLIGHT_REPLAY_HEADER = '[STILL IN PROGRESS — this is the active request, restated after the compaction boundary because it was not finished yet. Continue it; do not start over.]';
+/** The payload comparison ignores only the Agent's documented replay wrapper and dropped api_content. */
+function replayPayload(row) {
+    const message = projectStateDbMessage(row, false);
+    delete message.timestamp;
+    const copyKey = JSON.stringify(message);
+    let content = message.content;
+    let replay = false;
+    if (row.role === 'user') {
+        if (typeof content === 'string') {
+            replay = content.startsWith(`${INFLIGHT_REPLAY_HEADER}\n`);
+            content = (replay ? content.slice(INFLIGHT_REPLAY_HEADER.length + 1) : content).trim();
+        }
+        else if (Array.isArray(content)) {
+            // Multimodal replays prepend a text block and retain all original parts, including media.
+            const parts = content;
+            let start = 0;
+            while (start < parts.length) {
+                const first = parts[start];
+                if (!first || typeof first !== 'object' || Array.isArray(first))
+                    break;
+                const part = first;
+                if (part.type !== 'text' || part.text !== `${INFLIGHT_REPLAY_HEADER}\n` || Object.keys(part).some((k) => k !== 'type' && k !== 'text'))
+                    break;
+                start += 1;
+            }
+            replay = start > 0;
+            content = parts.slice(start);
+        }
+    }
+    message.content = content;
+    delete message.api_content; // _reappend_inflight_user_task drops this stale model-facing sidecar.
+    return { copyKey, replayKey: JSON.stringify(message), replay };
+}
+/**
+ * Compare adjacent generations, never all rows of one UID with its oldest archive. The archive retains
+ * authored payload changes even after active/compacted flags change. Only unchanged timestamp copies or
+ * exact request restatements inherit identity; edits (including A -> B -> A) start at their own row ID.
+ */
+function replayIdentities(db, chain, rows, available) {
+    const identities = new Map();
+    // Tool-result text can be pruned without changing its tool-call identity; retain the existing rule.
+    const uids = [...new Set(rows.filter((row) => row.role !== 'tool').map((row) => row.message_uid).filter((uid) => typeof uid === 'string' && uid.length > 0))];
+    if (!uids.length)
+        return identities;
+    const liveIds = new Set(rows.map((row) => row.id));
+    const previous = new Map();
+    const columns = ['id', 'message_uid', 'active', 'compacted', 'role', 'content', 'timestamp', ...OPTIONAL_MESSAGE_COLUMNS.filter((c) => available.has(c))];
+    // One ordered scan of the selected sessions, filtering against a materialized UID set. Stream the rows;
+    // memory holds only the preceding payload per live UID, not the accumulated archive. NULL/nonstandard
+    // active flags take exactly the same path and do not depend on the Agent's partial active=1 UID index.
+    const history = db.prepare(`SELECT ${columns.join(', ')} FROM messages WHERE session_id IN (${chain.map(() => '?').join(', ')}) AND message_uid IN (SELECT value FROM json_each(?)) ORDER BY id`);
+    for (const row of history.iterate(...chain, JSON.stringify(uids))) {
+        const uid = row.message_uid;
+        const payload = replayPayload(row);
+        const prior = previous.get(uid);
+        const copy = payload.copyKey === prior?.copyKey && row.timestamp === prior.timestamp;
+        const restatement = prior && payload.replay && payload.replayKey === prior.replayKey && (prior.active !== 0 || prior.compacted === 1);
+        const identity = prior && (copy || restatement) ? prior.identity : Number(row.id);
+        const changed = prior ? (copy || restatement ? prior.changed : true) : false;
+        const sourceKey = prior && (copy || restatement) ? prior.sourceKey : stateDbMessageFingerprint(projectStateDbMessage(row, false));
+        if (prior && row.role !== 'tool' && liveIds.has(row.id))
+            identities.set(Number(row.id), { id: identity, changed, sourceKey });
+        previous.set(uid, { ...payload, identity, changed, sourceKey, timestamp: row.timestamp, active: row.active, compacted: row.compacted });
+    }
+    return identities;
+}
 export function stateDbSessionMessages(dbPath, sid, opts = {}) {
     return stateDbSessionRead(dbPath, sid, opts).rows;
 }
@@ -647,7 +1233,14 @@ export function stateDbSessionMessages(dbPath, sid, opts = {}) {
  * (TAL-493: an empty id-capable read is a baseline of 0; a missing database or a failed read says nothing).
  */
 export function stateDbSessionRead(dbPath, sid, opts = {}) {
-    const none = { rows: [], idCapable: false, ok: false };
+    return readStateDbSession(dbPath, sid, opts);
+}
+/** The same snapshot and provenance projection, restricted to physical rows past the seen marker. */
+export function stateDbSessionTailRead(dbPath, sid, afterId, opts = {}) {
+    return readStateDbSession(dbPath, sid, { ...opts, stitch: false, afterId });
+}
+function readStateDbSession(dbPath, sid, opts) {
+    const none = { rows: [], idCapable: false, ok: false, reason: null, generation: null };
     const id = sid.trim();
     if (!id || !existsSync(dbPath))
         return none;
@@ -659,20 +1252,23 @@ export function stateDbSessionRead(dbPath, sid, opts = {}) {
         return none;
     }
     try {
+        db.exec('BEGIN'); // The live rows and their archived predecessors must describe one snapshot.
         const available = tableColumns(db, 'messages');
         if (!['role', 'content', 'timestamp'].every((c) => available.has(c)))
             return { ...none, ok: available.size > 0 };
         const hasId = available.has('id');
-        const selected = [...(hasId ? ['id'] : []), 'role', 'content', 'timestamp', ...OPTIONAL_MESSAGE_COLUMNS.filter((c) => available.has(c))];
+        const selected = [...(hasId ? ['id'] : []), ...(available.has('message_uid') ? ['message_uid'] : []), 'role', 'content', 'timestamp', ...OPTIONAL_MESSAGE_COLUMNS.filter((c) => available.has(c))];
         // TAL-529: an explicit lineage (the session and its compression continuations) replaces the parent walk.
-        const chain = opts.lineage?.length ? [...opts.lineage] : [id];
-        if (!opts.lineage?.length && (opts.stitch ?? true)) {
+        const local = localLineages(db, id).get(id);
+        const chain = local ? (opts.stitch === false ? [local.ids.at(-1) ?? id] : [...local.context]) : opts.lineage?.length ? [...opts.lineage] : [id];
+        if (!local && !opts.lineage?.length && (opts.stitch ?? true)) {
             const sessionCols = tableColumns(db, 'sessions');
             if (['parent_session_id', 'end_reason', 'started_at', 'source'].every((c) => sessionCols.has(c))) {
-                const select = db.prepare('SELECT id, source, started_at, parent_session_id, ended_at, end_reason FROM sessions WHERE id = ?');
+                const extra = ['model_config', 'session_source'].map((c) => sessionCols.has(c) ? c : `NULL AS ${c}`).join(', ');
+                const select = db.prepare(`SELECT id, source, started_at, parent_session_id, ended_at, end_reason, ${extra} FROM sessions WHERE id = ?`);
                 let current = select.get(id);
                 const seen = new Set([id]);
-                for (let hop = 0; hop < 20 && current; hop += 1) {
+                for (let hop = 0; hop < COMPRESSION_CHAIN_CAP && current; hop += 1) {
                     const parentId = str(current.parent_session_id);
                     if (!parentId || seen.has(parentId))
                         break;
@@ -686,19 +1282,74 @@ export function stateDbSessionRead(dbPath, sid, opts = {}) {
             }
         }
         const activeClause = available.has('active') ? ' AND (active IS NULL OR active != 0)' : '';
+        if (opts.afterId !== undefined && !hasId)
+            return { ...none, ok: true };
+        const range = opts.afterId === undefined ? '' : ' AND id > ?';
+        const rangeArgs = opts.afterId === undefined ? [] : [opts.afterId];
         const order = hasId ? 'id' : 'timestamp';
-        const rows = db.prepare(`SELECT ${selected.join(', ')}, session_id FROM messages WHERE session_id IN (${chain.map(() => '?').join(', ')})${activeClause} ORDER BY ${order} ASC`).all(...chain);
+        const rows = db.prepare(`SELECT ${selected.join(', ')}, session_id FROM messages WHERE session_id IN (${chain.map(() => '?').join(', ')})${activeClause}${range} ORDER BY ${order} ASC`).all(...chain, ...rangeArgs);
         const projected = rows.map((row) => projectStateDbMessage(row, hasId));
+        // TAL-709: an in-place compaction archives the live rows and re-inserts each as a copy that keeps its role and timestamp
+        // (content may be pruned). A copy takes the id of the oldest archived row it copies, so the merge sees a row it has
+        // already read instead of a new one. Only a compaction archive (`compacted = 1`) vouches for a changed copy: a rewound
+        // row (`compacted = 0`, also the compaction's carried tail) counts only for the same tool call or the same content, so
+        // an edit that kept its timestamp stays new.
+        if (hasId && available.has('active')) {
+            // One indexed lookup per live row ((session_id, active, timestamp)): the archive is never loaded, however many
+            // compactions it holds.
+            const sameCall = available.has('tool_call_id') ? " AND COALESCE(a.tool_call_id, '') = COALESCE(m.tool_call_id, '')" : '';
+            const vouched = [available.has('compacted') ? 'a.compacted = 1' : '', available.has('tool_call_id') ? 'm.tool_call_id IS NOT NULL' : '', 'a.content = m.content'].filter(Boolean).join(' OR ');
+            const twins = db.prepare(`SELECT m.id AS id, MIN(a.id) AS twin FROM messages m JOIN messages a ON a.session_id = m.session_id AND a.active = 0 AND a.role = m.role AND a.timestamp = m.timestamp AND a.id < m.id${sameCall} WHERE m.session_id IN (${chain.map(() => '?').join(', ')}) AND (m.active IS NULL OR m.active != 0) AND (${vouched})${opts.afterId === undefined ? '' : ' AND m.id > ?'} GROUP BY m.id`).all(...chain, ...rangeArgs);
+            const twinOf = new Map(twins.map((row) => [row.id, row.twin]));
+            for (const [i, row] of rows.entries()) {
+                const twin = twinOf.get(row.id);
+                if (typeof twin === 'number')
+                    projected[i]._state_db_row_id = twin;
+            }
+        }
+        if (hasId && ['message_uid', 'active', 'compacted'].every((c) => available.has(c))) {
+            const identities = replayIdentities(db, local?.context ?? chain, rows, available);
+            for (const [i, row] of rows.entries()) {
+                const identity = identities.get(Number(row.id));
+                // A known changed generation overrides even a coincidental legacy timestamp twin.
+                if (identity !== undefined) {
+                    projected[i]._state_db_row_id = identity.id;
+                    if (identity.id !== row.id)
+                        projected[i]._state_db_source_key = identity.sourceKey;
+                    if (identity.changed)
+                        projected[i]._state_db_authored_change = true;
+                }
+            }
+        }
         // TAL-493: the database file's identity, so a marker taken in a replaced state.db is never applied to its successor.
+        const generation = stateDbGeneration(dbPath);
         if (hasId) {
-            const generation = stateDbGeneration(dbPath);
             for (const m of projected)
                 m._state_db_generation = generation;
         }
-        return { rows: projected, idCapable: hasId, ok: true };
+        let anchor;
+        if (opts.afterId !== undefined) {
+            anchor = projected.find((m) => m._state_db_row_id === opts.afterId);
+            if (!anchor) {
+                const row = db.prepare(`SELECT ${selected.join(', ')}, session_id FROM messages WHERE session_id IN (${chain.map(() => '?').join(', ')}) AND id = ?${activeClause} LIMIT 1`).get(...chain, opts.afterId);
+                if (row)
+                    anchor = { ...projectStateDbMessage(row, true), _state_db_generation: generation };
+            }
+        }
+        let requiresFullRead = false;
+        if (opts.afterId !== undefined && opts.unidentified) {
+            const matches = projected.filter((m) => opts.unidentified.some((keys) => keys.has(stateDbMessageKey(m))));
+            if (matches.length) {
+                // Projection can normalize content/timestamps. A bounded role-key superset is conservative copy detection.
+                const roles = [...new Set(matches.map((m) => m.role))];
+                const covered = db.prepare(`SELECT 1 FROM messages WHERE session_id IN (${chain.map(() => '?').join(', ')}) AND id <= ? AND role IN (SELECT value FROM json_each(?))${activeClause} LIMIT 1`).get(...chain, opts.afterId, JSON.stringify(roles));
+                requiresFullRead = Boolean(covered) || available.has('message_uid');
+            }
+        }
+        return { rows: projected, idCapable: hasId, ok: true, reason: null, generation, requiresFullRead, ...(anchor ? { anchor } : {}) };
     }
-    catch {
-        return none;
+    catch (error) {
+        return { ...none, reason: stateDbReadFailure(error).reason };
     }
     finally {
         db.close();
@@ -706,8 +1357,8 @@ export function stateDbSessionRead(dbPath, sid, opts = {}) {
 }
 /**
  * TAL-529: `sid` and each compression continuation the Agent rotated it to, down to the live tip (Python
- * `resolve_live_compression_tip`). The walk stops at the last unambiguous row: no continuation, several, a cycle, or 20
- * hops. A missing or unreadable database is `[sid]`.
+ * `resolve_live_compression_tip`). The walk stops at the last unambiguous row: no continuation, several, a cycle, or
+ * `COMPRESSION_CHAIN_CAP` hops. A missing or unreadable database is `[sid]`.
  */
 export function stateDbCompressionLineage(dbPath, sid) {
     const lineage = [sid.trim()];
@@ -721,14 +1372,19 @@ export function stateDbCompressionLineage(dbPath, sid) {
         return lineage;
     }
     try {
+        db.exec('BEGIN');
+        const local = localLineages(db, lineage[0]).get(lineage[0]);
+        if (local)
+            return [...local.ids];
         const sessionCols = tableColumns(db, 'sessions');
         if (!['id', 'parent_session_id', 'end_reason', 'ended_at', 'started_at', 'source'].every((c) => sessionCols.has(c)))
             return lineage;
         const sessionSource = sessionCols.has('session_source') ? 'session_source' : 'NULL AS session_source';
-        const cols = `id, source, ${sessionSource}, started_at, parent_session_id, ended_at, end_reason`;
+        const modelConfig = sessionCols.has('model_config') ? 'model_config' : 'NULL AS model_config';
+        const cols = `id, source, ${sessionSource}, started_at, parent_session_id, ended_at, end_reason, ${modelConfig}`;
         let current = db.prepare(`SELECT ${cols} FROM sessions WHERE id = ?`).get(lineage[0]);
         const children = db.prepare(`SELECT ${cols} FROM sessions WHERE parent_session_id = ?`);
-        for (let hop = 0; hop < 20 && current; hop += 1) {
+        for (let hop = 0; hop < COMPRESSION_CHAIN_CAP && current; hop += 1) {
             const parent = current;
             const next = children.all(str(parent.id)).filter((child) => isContinuationSession(parent, child));
             if (next.length !== 1 || lineage.includes(str(next[0].id)))
@@ -745,6 +1401,93 @@ export function stateDbCompressionLineage(dbPath, sid) {
         db.close();
     }
 }
+function lineageReportRow(row, role) {
+    const ended = row.ended_at ?? null;
+    return {
+        session_id: row.id, role, title: row.title ?? null, source: row.source ?? null, started_at: row.started_at ?? null, updated_at: ended ?? row.started_at ?? null,
+        end_reason: row.end_reason ?? null, active: ended === null, archived: false,
+    };
+}
+const emptyLineageReport = (sid) => ({
+    mutation: false, found: false, session_id: sid, lineage_key: sid, tip_session_id: sid, total_segments: 0, materialized_segments: 0, segments: [], children: [], manual_review: false,
+});
+/**
+ * Python `read_session_lineage_report`: a read-only report of `sid`'s compression lineage. The walk follows up to
+ * `maxHops` continuation parents (the tip first, the root last), then lists each segment's non-continuation children,
+ * newest first. A cycle, a hop limit hit, or a continuation off the walked path marks `manual_review`. A missing,
+ * unreadable, or too-old database, or an unknown id, answers `found: false`.
+ */
+export function stateDbLineageReport(dbPath, rawSid, maxHops = COMPRESSION_CHAIN_CAP) {
+    const sid = rawSid.trim();
+    if (!sid || !existsSync(dbPath))
+        return emptyLineageReport(sid);
+    let db;
+    try {
+        db = openStateDbReadonly(dbPath);
+    }
+    catch {
+        return emptyLineageReport(sid);
+    }
+    try {
+        db.exec('BEGIN');
+        const local = localLineages(db, sid).get(sid);
+        const cols = tableColumns(db, 'sessions');
+        if (!['id', 'parent_session_id', 'end_reason'].every((c) => cols.has(c)))
+            return emptyLineageReport(sid);
+        const col = (name, fallback = 'NULL') => (cols.has(name) ? `s.${name}` : `${fallback} AS ${name}`);
+        const select = `SELECT s.id, ${col('source')}, ${col('session_source')}, ${col('title')}, ${col('started_at', '0')}, s.parent_session_id, ${col('ended_at')}, s.end_reason FROM sessions s`;
+        const byId = db.prepare(`${select} WHERE s.id = ?`);
+        const fetch = (id) => (id ? byId.get(str(id)) ?? null : null);
+        const target = fetch(sid);
+        if (!target)
+            return emptyLineageReport(sid);
+        const segments = local ? [...local.rows].reverse().slice(0, Math.max(1, maxHops)) : [target];
+        const seen = new Set(segments.map((row) => str(row.id)));
+        let manualReview = local ? local.ids.length > maxHops : true;
+        for (let hop = 0; !local && hop < maxHops; hop += 1) {
+            const current = segments[segments.length - 1];
+            const parentId = str(current.parent_session_id);
+            const parent = fetch(parentId);
+            if (!parent || seen.has(parentId)) {
+                manualReview = Boolean(parentId && seen.has(parentId));
+                break;
+            }
+            if (!isContinuationSession(parent, current)) {
+                manualReview = false;
+                break;
+            }
+            segments.push(parent);
+            seen.add(parentId);
+        }
+        const segmentIds = segments.map((row) => str(row.id));
+        const children = db.prepare(`${select} WHERE s.parent_session_id IN (${segmentIds.map(() => '?').join(', ')})`).all(...segmentIds);
+        const childRows = [];
+        for (const parent of segments) {
+            const own = children.filter((child) => str(child.parent_session_id) === str(parent.id) && !seen.has(str(child.id)));
+            own.sort((a, b) => (Number(b.started_at) || 0) - (Number(a.started_at) || 0));
+            for (const child of own) {
+                // A continuation off the walked path means a branched lineage or an older selected segment: flag it, list nothing.
+                if (isContinuationSession(parent, child))
+                    manualReview = true;
+                else
+                    childRows.push(child);
+            }
+        }
+        return {
+            mutation: false, found: true, session_id: sid, lineage_key: segments[segments.length - 1].id, tip_session_id: segments[0].id,
+            total_segments: segments.length, materialized_segments: segments.length,
+            segments: segments.map((row, idx) => lineageReportRow(row, idx === 0 ? 'tip' : 'hidden_segment')),
+            children: childRows.map((row) => lineageReportRow(row, 'child_session')),
+            manual_review: manualReview,
+        };
+    }
+    catch {
+        return emptyLineageReport(sid);
+    }
+    finally {
+        db.close();
+    }
+}
 /** The `sessions` row for `sid` (source and lifecycle columns), or null. */
 export function stateDbSessionRow(dbPath, sid) {
     const id = sid.trim();
@@ -821,4 +1564,78 @@ export function insightsSessionRows(dbPath, cutoff) {
         db.close();
     }
 }
+/** A state.db `timestamp` in unix seconds: a number, or an ISO-8601 string (Python `fromisoformat`); null when unreadable. */
+export function stateDbTimestampSeconds(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : null;
+    if (typeof value !== 'string' || !value.trim())
+        return null;
+    const ms = Date.parse(value.trim());
+    return Number.isFinite(ms) ? ms / 1000 : null;
+}
+/** Python `CONVERSATION_ROUND_THRESHOLD`: the handoff dock is offered from this many rounds. */
+export const CONVERSATION_ROUND_THRESHOLD = 10;
+/**
+ * Python `count_conversation_rounds` (TAL-258): a round is a user message answered by the assistant; consecutive user
+ * messages merge into one. With `since`, only rows stamped after it count (an unreadable stamp still counts). A missing
+ * or unreadable database is 0.
+ */
+export function countConversationRounds(dbPath, sid, since = null) {
+    if (!existsSync(dbPath))
+        return 0;
+    let rows;
+    try {
+        const db = openStateDbReadonly(dbPath);
+        try {
+            rows = db.prepare('SELECT role, timestamp FROM messages WHERE session_id = ? ORDER BY timestamp ASC').all(sid);
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch {
+        return 0;
+    }
+    let rounds = 0;
+    let seenUser = false;
+    let answered = false;
+    for (const row of rows) {
+        if (since !== null) {
+            const ts = stateDbTimestampSeconds(row.timestamp);
+            if (ts !== null && ts <= since)
+                continue;
+        }
+        const role = lower(row.role);
+        if (role === 'user') {
+            if (seenUser && answered) {
+                rounds += 1;
+                answered = false;
+            }
+            seenUser = true;
+        }
+        else if (role === 'assistant' && seenUser) {
+            answered = true;
+        }
+    }
+    return seenUser && answered ? rounds + 1 : rounds;
+}
+/** The content of the session's newest row when that row is a `tool` row (the handoff marker's tail dedupe, TAL-258); else null. */
+export function stateDbTailToolContent(dbPath, sid) {
+    if (!existsSync(dbPath))
+        return null;
+    try {
+        const db = openStateDbReadonly(dbPath);
+        try {
+            const row = db.prepare('SELECT role, content FROM messages WHERE session_id = ? ORDER BY rowid DESC LIMIT 1').get(sid);
+            const content = row?.role === 'tool' ? decodeStateDbContent(row.content) : null;
+            return typeof content === 'string' ? content : null;
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch {
+        return null;
+    }
+}
 //# sourceMappingURL=state-db.js.map