@fitchmultz/pi-subagents 0.44.6 → 0.45.0

package/dist/history/source-file.js

@@ -0,0 +1,45 @@
+import * as fs from "node:fs";
+import { HistoryIndexError } from "./types.js";
+export function identity(stat) {
+    return `${stat.dev}:${stat.ino}`;
+}
+export function stamp(stat) {
+    return `${identity(stat)}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
+}
+export function requireSource(store, id) {
+    const source = store.source(id);
+    if (!source) {
+        throw new HistoryIndexError("SOURCE_CHANGED", "Source was removed before ingestion.");
+    }
+    return source;
+}
+/** Acquires the writer lock before reading any cursor or clearing shared staging. */
+export function openSource(store, id) {
+    store.beginIngest();
+    let fd;
+    try {
+        let source = requireSource(store, id);
+        store.count("sourceChecks");
+        store.count("sourceOpens");
+        fd = fs.openSync(source.path, "r");
+        const initial = fs.fstatSync(fd, { bigint: true });
+        if (!initial.isFile() || initial.size > BigInt(Number.MAX_SAFE_INTEGER)) {
+            throw new Error("Journal is not a supported regular file.");
+        }
+        if (source.identity !== null &&
+            (source.identity !== identity(initial) || Number(initial.size) < source.cursor)) {
+            store.resetSource(id);
+            source = requireSource(store, id);
+        }
+        store.clearUnpublished(id);
+        store.run("DELETE FROM pending_text");
+        return { fd, initial, source };
+    }
+    catch (error) {
+        if (fd !== undefined) {
+            fs.closeSync(fd);
+        }
+        store.endIngest();
+        throw error;
+    }
+}

package/dist/history/source-watches.js

@@ -0,0 +1,141 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { identity } from "./source-file.js";
+/** Owns native handles, physical-directory identity and co-located run/source subscriptions. */
+export class SourceWatches {
+    runs = new Set();
+    watchers = new Map();
+    sourceWatchers = new Map();
+    identities = new WeakMap();
+    sources = new Map();
+    root;
+    events;
+    constructor(agentDir, events) {
+        this.root = path.join(agentDir, "sessions", "subagent-runs");
+        this.events = events;
+    }
+    handle(directory, recursive, listener, source = false) {
+        const handles = source ? this.sourceWatchers : this.watchers;
+        const existing = handles.get(directory);
+        try {
+            const physical = identity(fs.statSync(directory, { bigint: true }));
+            if (existing && this.identities.get(existing) === physical) {
+                return;
+            }
+            const watcher = fs.watch(directory, { recursive }, (event, name) => {
+                const filename = name?.toString() ?? null;
+                const selfRename = event === "rename" && filename === path.basename(directory);
+                if (selfRename && handles.get(directory) === watcher) {
+                    this.identities.delete(watcher);
+                    this.handle(directory, recursive, listener, source);
+                    listener(null);
+                }
+                else {
+                    listener(filename);
+                }
+                if (!source) {
+                    this.notifySources(directory, selfRename ? null : filename);
+                }
+                this.events.schedule();
+            });
+            this.identities.set(watcher, physical);
+            this.retireOnClose(directory, watcher, source);
+            handles.set(directory, watcher);
+            // Native close fences macOS re-registration; admit the replacement first.
+            existing?.close();
+        }
+        catch {
+            if (existing && handles.get(directory) === existing) {
+                this.identities.delete(existing);
+            }
+            // Known-handle census recovers absent directories and dropped native watches.
+        }
+    }
+    retireOnClose(directory, watcher, source) {
+        const handles = source ? this.sourceWatchers : this.watchers;
+        const retire = () => {
+            if (handles.get(directory) === watcher) {
+                handles.delete(directory);
+            }
+        };
+        watcher.on("error", () => {
+            watcher.close();
+            retire();
+        });
+        watcher.on("close", retire);
+    }
+    reset(directory) {
+        for (const handles of [this.watchers, this.sourceWatchers]) {
+            const watcher = handles.get(directory);
+            if (watcher) {
+                this.identities.delete(watcher);
+            }
+        }
+        for (const id of this.sources.get(directory)?.keys() ?? []) {
+            this.events.source(id);
+        }
+    }
+    notifySources(directory, name) {
+        for (const [id, filename] of this.sources.get(directory) ?? []) {
+            if (name === null || name.length === 0 || filename === name) {
+                this.events.source(id);
+            }
+        }
+    }
+    sourceDirectory(directory) {
+        if (!this.sources.has(directory) || this.watchers.has(directory)) {
+            return;
+        }
+        this.handle(directory, false, (name) => {
+            this.notifySources(directory, name);
+        }, true);
+    }
+    install(runIds, sources) {
+        for (const id of runIds) {
+            this.runs.add(id);
+        }
+        // Observe only admitted trees. Foreign run directory churn never causes a global scan.
+        this.handle(this.root, false, (name) => {
+            let ids = this.runs;
+            if (name !== null && name.length > 0) {
+                ids = this.runs.has(name) ? [name] : [];
+            }
+            for (const id of ids) {
+                this.reset(path.join(this.root, id));
+                this.events.run(id);
+            }
+        });
+        for (const id of runIds) {
+            const directory = path.join(this.root, id);
+            this.handle(directory, true, (name) => {
+                if (name === null || name.length === 0) {
+                    this.reset(directory);
+                }
+                this.events.run(id);
+            });
+            this.sourceDirectory(directory);
+        }
+        for (const source of sources) {
+            const directory = path.dirname(source.path);
+            let linked = this.sources.get(directory);
+            if (!linked) {
+                linked = new Map();
+                this.sources.set(directory, linked);
+            }
+            linked.set(source.id, path.basename(source.path));
+            this.sourceDirectory(directory);
+        }
+    }
+    forget(source) {
+        this.sources.get(path.dirname(source.path))?.delete(source.id);
+    }
+    close() {
+        for (const watcher of [...this.watchers.values(), ...this.sourceWatchers.values()]) {
+            watcher.close();
+        }
+        this.watchers.clear();
+        this.sourceWatchers.clear();
+        this.sources.clear();
+        this.runs.clear();
+    }
+}

package/dist/history/store.js

@@ -1,124 +1,82 @@
-import * as fs from "node:fs";
 import * as path from "node:path";
-import { createHash, randomUUID } from "node:crypto";
-import { historyDirectory, historyTransaction, openHistoryDatabase } from "./database.js";
-import { stripTerminalSequences } from "../shared/native-tui.js";
-import { HistoryIndexError } from "./types.js";
-import { readSavedOutput } from "./canonical-result.js";
-export const hash = (text) => createHash("sha256").update(text).digest("hex");
-export const exactTextDigest = (text) => hash(stripTerminalSequences(text).trim());
-export const safeText = (value, limit = 1024) => typeof value === "string" ? value.replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)|\x1b\[[0-?]*[ -/]*[@-~]|[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "").slice(0, limit) : "";
-export function integer(value, fallback, maximum = Number.MAX_SAFE_INTEGER) {
-    const result = value === undefined ? fallback : value;
-    if (!Number.isSafeInteger(result) || Number(result) < 0 || Number(result) > maximum)
-        throw new HistoryIndexError("INVALID", "Expected a bounded non-negative integer.");
-    return Number(result);
-}
-export function pageLimit(value, fallback = 100) {
-    const limit = integer(value, fallback, 100);
-    if (!limit)
-        throw new HistoryIndexError("INVALID", "Page limit must be from 1 to 100.");
-    return limit;
-}
+import { openGeneration } from "./database-generation.js";
+import { OutputDigests } from "./output-digests.js";
+import { historyTransaction, openHistoryDatabase } from "./database.js";
+import { hash, safeText, hasText } from "./text.js";
+export { hash, exactTextDigest, safeText, integer, pageLimit } from "./text.js";
+import { HistoryIndexError, } from "./types.js";
+import { sourceRow, indexRow, number, text, } from "./rows.js";
+import { parseObject, errorMessage } from "./values.js";
 export class HistoryStore {
     db;
     generation;
     file;
     owner;
-    operations = { sourceChecks: 0, sourceOpens: 0, sourceBytesRead: 0, runProjections: 0, queries: 0 };
+    counters = {
+        sourceChecks: 0,
+        sourceOpens: 0,
+        sourceBytesRead: 0,
+        runProjections: 0,
+        queries: 0,
+    };
+    get operations() {
+        return { ...this.counters };
+    }
+    count(operation, amount = 1) {
+        this.counters[operation] += amount;
+    }
     ingestLock;
-    outputDigests = new Map();
+    outputDigests = new OutputDigests();
     constructor(agentDir, owner) {
         this.owner = owner;
-        const directory = historyDirectory(agentDir);
-        const manifest = path.join(directory, `${hash(owner)}.json`);
-        let name;
+        const { db, file } = openGeneration(agentDir, owner);
+        this.db = db;
+        this.file = file;
         try {
-            const saved = JSON.parse(fs.readFileSync(manifest, "utf8"));
-            if (typeof saved.file === "string" && /^[a-f0-9-]+\.sqlite$/.test(saved.file))
-                name = saved.file;
+            this.generation = text(this.require("SELECT value FROM meta WHERE key='generation'"), "value");
+            this.db.exec("CREATE TEMP TABLE pending_text(field TEXT, position INTEGER, end_position INTEGER, text TEXT)");
         }
         catch (error) {
-            if (error.code !== "ENOENT" && !(error instanceof SyntaxError))
-                throw error;
-        }
-        let db;
-        if (name) {
-            try {
-                const file = path.join(directory, name);
-                if (!fs.existsSync(file) || fs.lstatSync(file).isSymbolicLink())
-                    throw new HistoryIndexError("CORRUPT", "Invalid index generation.");
-                db = openHistoryDatabase(file);
-                if (db.prepare("PRAGMA user_version").get()?.user_version !== 5)
-                    throw new HistoryIndexError("CORRUPT", "Invalid index schema.");
-                db.prepare("SELECT value FROM meta WHERE key='generation'").get();
-            }
-            catch (error) {
-                db?.close();
-                db = undefined;
-                if (!isCorruption(error))
-                    throw error;
-                name = undefined;
-            }
+            this.db.close();
+            throw error;
         }
-        if (!name) {
-            name = `${randomUUID()}.sqlite`;
-            db = openHistoryDatabase(path.join(directory, name));
-            this.schema(db);
-            const temporary = `${manifest}.${process.pid}.${randomUUID()}`;
-            fs.writeFileSync(temporary, JSON.stringify({ file: name }), { mode: 0o600 });
-            fs.renameSync(temporary, manifest);
-            // Never rename/unlink an open SQLite generation or separate its WAL. Old corrupt
-            // generations remain private for diagnosis; the manifest selects the new projection.
+    }
+    require(sql, ...params) {
+        const row = this.get(sql, ...params);
+        if (!row) {
+            throw new HistoryIndexError("CORRUPT", "Missing required index row.");
         }
-        this.db = db;
-        this.file = path.join(directory, name);
-        fs.chmodSync(this.file, 0o600);
-        for (const suffix of ["-wal", "-shm"])
-            if (fs.existsSync(this.file + suffix))
-                fs.chmodSync(this.file + suffix, 0o600);
-        this.generation = String(this.get("SELECT value FROM meta WHERE key='generation'").value);
-        this.db.exec("CREATE TEMP TABLE pending_text(field TEXT, position INTEGER, end_position INTEGER, text TEXT)");
-    }
-    schema(db) {
-        db.exec(`
-			CREATE TABLE meta(key TEXT PRIMARY KEY,value TEXT NOT NULL);
-			INSERT INTO meta VALUES ('generation','${randomUUID()}'),('version','0'),('indexedAt','0');
-			CREATE TABLE runs(id TEXT PRIMARY KEY,attention INTEGER NOT NULL,updated INTEGER NOT NULL,negative_updated INTEGER NOT NULL,state TEXT NOT NULL,filter_text TEXT NOT NULL,view TEXT NOT NULL,predecessor_id TEXT,predecessor_index INTEGER);
-			CREATE INDEX runs_predecessor ON runs(predecessor_id,predecessor_index);
-			CREATE INDEX runs_attention ON runs(attention,negative_updated,id);
-			CREATE INDEX runs_newest ON runs(negative_updated,id);
-			CREATE INDEX runs_oldest ON runs(updated,id);
-			CREATE INDEX runs_state ON runs(state,attention,negative_updated,id);
-			CREATE TABLE sources(id TEXT PRIMARY KEY,path TEXT NOT NULL UNIQUE,generation INTEGER NOT NULL DEFAULT 1,identity TEXT,stamp TEXT,session_id TEXT,header_digest TEXT,cursor INTEGER NOT NULL DEFAULT 0,prefix_digest TEXT,state TEXT NOT NULL DEFAULT 'pending',error TEXT,malformed INTEGER NOT NULL DEFAULT 0,complexity INTEGER NOT NULL DEFAULT 0,checked_at INTEGER,format_version INTEGER);
-			CREATE TABLE children(run_id TEXT NOT NULL REFERENCES runs(id) ON DELETE CASCADE,child_index INTEGER NOT NULL,agent TEXT NOT NULL,source_id TEXT REFERENCES sources(id),filter_text TEXT NOT NULL,output_digest TEXT,terminal_entry_id TEXT,ended_at INTEGER,PRIMARY KEY(run_id,child_index));
-			CREATE INDEX children_source ON children(source_id);
-			CREATE INDEX children_agent ON children(agent,run_id);
-			CREATE TABLE entries(rowid INTEGER PRIMARY KEY,source_id TEXT NOT NULL REFERENCES sources(id),generation INTEGER NOT NULL,id TEXT NOT NULL,native_id TEXT,parent_id TEXT,start INTEGER NOT NULL,end INTEGER NOT NULL,digest TEXT NOT NULL,timestamp INTEGER,type TEXT NOT NULL,preview TEXT NOT NULL,published INTEGER NOT NULL DEFAULT 0,role TEXT,assistant_text INTEGER NOT NULL DEFAULT 0,visible_id TEXT,human_id TEXT,configuration_model TEXT,configuration_thinking TEXT,UNIQUE(source_id,generation,id),UNIQUE(source_id,generation,start));
-			CREATE INDEX entries_page ON entries(source_id,generation,published,start);
-			CREATE INDEX entries_time ON entries(source_id,generation,published,timestamp,start);
-			CREATE INDEX entries_human ON entries(source_id,generation,human_id,start);
-			CREATE TABLE answers(entry_rowid INTEGER NOT NULL REFERENCES entries(rowid) ON DELETE CASCADE,digest TEXT NOT NULL,item_id TEXT NOT NULL,PRIMARY KEY(entry_rowid,digest));
-			CREATE INDEX answers_digest ON answers(digest,entry_rowid);
-			CREATE TABLE tools(entry_rowid INTEGER NOT NULL REFERENCES entries(rowid) ON DELETE CASCADE,source_id TEXT NOT NULL,generation INTEGER NOT NULL,call_id TEXT NOT NULL,kind TEXT NOT NULL);
-			CREATE INDEX tools_lookup ON tools(source_id,generation,call_id,kind);
-			CREATE TABLE documents(id INTEGER PRIMARY KEY,entry_rowid INTEGER NOT NULL REFERENCES entries(rowid) ON DELETE CASCADE,field TEXT NOT NULL,text_start INTEGER NOT NULL,text_end INTEGER NOT NULL,preview TEXT NOT NULL);
-			CREATE INDEX documents_entry ON documents(entry_rowid);
-			CREATE VIRTUAL TABLE corpus USING fts5(text,content='',contentless_delete=1,tokenize='unicode61');
-			PRAGMA user_version=5;
-		`);
-    }
-    get(sql, ...params) { return this.db.prepare(sql).get(...params); }
-    all(sql, ...params) { return this.db.prepare(sql).all(...params); }
-    run(sql, ...params) { return this.db.prepare(sql).run(...params); }
+        return row;
+    }
+    get(sql, ...params) {
+        const row = this.db.prepare(sql).get(...params);
+        return row === undefined ? undefined : indexRow(row);
+    }
+    all(sql, ...params) {
+        return this.db
+            .prepare(sql)
+            .all(...params)
+            .map(indexRow);
+    }
+    run(sql, ...params) {
+        return this.db.prepare(sql).run(...params);
+    }
     deleteDocuments(sourceId, unpublishedOnly = false) {
         const where = `entry_rowid IN (SELECT rowid FROM entries WHERE source_id=?${unpublishedOnly ? " AND published=0" : ""})`;
         this.run(`DELETE FROM corpus WHERE rowid IN (SELECT id FROM documents WHERE ${where})`, sourceId);
         this.run(`DELETE FROM documents WHERE ${where}`, sourceId);
     }
-    transaction(work) { return historyTransaction(this.db, work); }
-    bump() { this.run("UPDATE meta SET value=CAST(value AS INTEGER)+1 WHERE key='version'"); this.run("UPDATE meta SET value=? WHERE key='indexedAt'", String(Date.now())); }
-    source(id) { return this.get("SELECT * FROM sources WHERE id=?", id); }
+    transaction(work) {
+        return historyTransaction(this.db, work);
+    }
+    bump() {
+        this.run("UPDATE meta SET value=CAST(value AS INTEGER)+1 WHERE key='version'");
+        this.run("UPDATE meta SET value=? WHERE key='indexedAt'", String(Date.now()));
+    }
+    source(id) {
+        const row = this.get("SELECT * FROM sources WHERE id=?", id);
+        return row ? sourceRow(row) : undefined;
+    }
     resetSource(id, state = "pending", error = null) {
         this.transaction(() => {
             this.deleteDocuments(id);
@@ -133,63 +91,85 @@ export class HistoryStore {
             this.run("DELETE FROM entries WHERE source_id=? AND published=0", id);
         });
     }
-    outputDigest(result) {
-        if (!result)
-            return null;
-        if (!result.fullOutputPath)
-            return typeof result.finalOutput === "string" && result.finalOutput.length !== 8192 && !result.truncation?.truncated ? exactTextDigest(result.finalOutput) : null;
-        try {
-            const stat = fs.statSync(result.fullOutputPath, { bigint: true });
-            if (!stat.isFile() || stat.size > 16n * 1024n * 1024n)
-                return null;
-            const stamp = `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
-            const cached = this.outputDigests.get(result.fullOutputPath);
-            if (cached?.stamp === stamp)
-                return cached.digest;
-            const text = readSavedOutput(result.fullOutputPath);
-            const digest = exactTextDigest(text);
-            this.outputDigests.set(result.fullOutputPath, { stamp, digest });
-            return digest;
-        }
-        catch {
-            return null;
-        }
-    }
     putView(view, full = view) {
-        const attention = view.attention.includes("awaiting_input") ? 0 : view.attention.some((reason) => reason !== "unreviewed") ? 1 : view.state === "live" ? 2 : view.attention.length ? 3 : 4;
-        const json = JSON.stringify(view), filters = new Map(full.children.map((child) => [child.index, safeText(`${child.agent} ${child.label ?? ""} ${child.task ?? full.task}`, Infinity).toLowerCase()]));
+        const attention = attentionRank(view);
+        const json = JSON.stringify(view), filters = new Map(full.children.map((child) => [
+            child.index,
+            safeText(`${child.agent} ${child.label ?? ""} ${child.task ?? full.task}`, Infinity).toLowerCase(),
+        ]));
         const filterText = safeText(`${full.task} ${[...filters.values()].join(" ")}`, Infinity).toLowerCase();
-        const digests = new Map(full.children.map((child) => [child.index, this.outputDigest(child.result)]));
+        const digests = new Map(full.children.map((child) => [child.index, this.outputDigests.read(child.result)]));
         const saved = this.get("SELECT view,filter_text FROM runs WHERE id=?", view.runId);
-        if (saved?.view === json && saved.filter_text === filterText && this.all("SELECT child_index,output_digest FROM children WHERE run_id=?", view.runId).every((child) => child.output_digest === digests.get(child.child_index)))
+        if (saved?.view === json &&
+            saved.filter_text === filterText &&
+            this.all("SELECT child_index,output_digest FROM children WHERE run_id=?", view.runId).every((child) => child.output_digest === digests.get(number(child, "child_index")))) {
             return;
+        }
         this.transaction(() => {
             this.run("INSERT INTO runs VALUES (?,?,?,?,?,?,?,?,?) ON CONFLICT(id) DO UPDATE SET attention=excluded.attention,updated=excluded.updated,negative_updated=excluded.negative_updated,state=excluded.state,filter_text=excluded.filter_text,view=excluded.view,predecessor_id=excluded.predecessor_id,predecessor_index=excluded.predecessor_index", view.runId, attention, view.updatedAt, -view.updatedAt, view.state, filterText, json, view.predecessorRunId ?? null, view.predecessorIndex ?? 0);
-            this.run("DELETE FROM children WHERE run_id=?", view.runId);
-            for (const child of view.children) {
-                let source = null;
-                if (child.sessionFile) {
-                    const file = path.resolve(child.sessionFile);
-                    source = hash(file);
-                    this.run("INSERT INTO sources(id,path) VALUES (?,?) ON CONFLICT(id) DO NOTHING", source, file);
-                }
-                const terminal = child.state !== "live" && child.state !== "unknown";
-                this.run("INSERT INTO children VALUES (?,?,?,?,?,?,?,?)", view.runId, child.index, child.agent, source, filters.get(child.index) ?? "", digests.get(child.index) ?? null, terminal ? child.result?.terminalEntryId ?? null : null, terminal && !child.result?.terminalEntryId ? view.updatedAt : null);
-            }
+            this.putChildren(view, filters, digests);
             this.bump();
         });
     }
-    info(pending) {
-        const sources = this.get("SELECT COUNT(*) AS total,SUM(state IN ('pending','indexing')) AS pending,SUM(state IN ('degraded','missing','error')) AS errors FROM sources WHERE id IN (SELECT source_id FROM children)");
-        const indexedAt = Number(this.get("SELECT value FROM meta WHERE key='indexedAt'").value) || null;
-        const errors = Number(sources.errors ?? 0);
+    putChildren(view, filters, digests) {
+        this.run("DELETE FROM children WHERE run_id=?", view.runId);
+        for (const child of view.children) {
+            let source = null;
+            if (hasText(child.sessionFile)) {
+                const file = path.resolve(child.sessionFile);
+                source = hash(file);
+                this.run("INSERT INTO sources(id,path) VALUES (?,?) ON CONFLICT(id) DO NOTHING", source, file);
+            }
+            const terminal = child.state !== "live" && child.state !== "unknown";
+            const boundary = terminalBoundary(child, view.updatedAt, terminal);
+            this.run("INSERT INTO children VALUES (?,?,?,?,?,?,?,?)", view.runId, child.index, child.agent, source, filters.get(child.index) ?? "", digests.get(child.index) ?? null, boundary.entry, boundary.endedAt);
+        }
+    }
+    info(pending, projectionErrors = 0) {
+        const sources = this.require("SELECT COUNT(*) AS total,SUM(state IN ('pending','indexing')) AS pending,SUM(state IN ('degraded','missing','error')) AS errors FROM sources WHERE id IN (SELECT source_id FROM children)");
+        const indexedAtValue = Number(text(this.require("SELECT value FROM meta WHERE key='indexedAt'"), "value"));
+        const indexedAt = indexedAtValue === 0 ? null : indexedAtValue;
+        const errors = Number(sources.errors ?? 0) + projectionErrors;
         const remaining = pending + Number(sources.pending ?? 0);
-        const freshness = { authoritative: false, state: remaining ? "catching-up" : errors ? "degraded" : "current", pending: remaining, errors, indexedAt };
-        return { version: Number(this.get("SELECT value FROM meta WHERE key='version'").value), indexedAt, freshness };
+        const freshness = {
+            authoritative: false,
+            state: freshnessState(remaining, errors),
+            pending: remaining,
+            errors,
+            indexedAt,
+        };
+        return {
+            version: Number(text(this.require("SELECT value FROM meta WHERE key='version'"), "value")),
+            indexedAt,
+            freshness,
+        };
+    }
+    status(pending) {
+        return {
+            ...this.info(pending),
+            databaseFile: this.file,
+            physicalSources: number(this.require("SELECT COUNT(*) AS count FROM sources"), "count"),
+            publishedEntries: number(this.require("SELECT COUNT(*) AS count FROM entries WHERE published=1"), "count"),
+            operations: this.operations,
+        };
     }
     entry(row) {
-        return { id: row.id, nativeId: row.native_id, parentId: row.parent_id, sequence: row.start, timestamp: row.timestamp, type: row.type,
-            ref: { sourceId: row.source_id, generation: row.generation, start: row.start, end: row.end, digest: row.digest }, entry: JSON.parse(row.preview) };
+        return {
+            id: row.id,
+            nativeId: row.native_id,
+            parentId: row.parent_id,
+            sequence: row.start,
+            timestamp: row.timestamp,
+            type: row.type,
+            ref: {
+                sourceId: row.source_id,
+                generation: row.generation,
+                start: row.start,
+                end: row.end,
+                digest: row.digest,
+            },
+            entry: parseObject(row.preview),
+        };
     }
     /** A separate SQLite transaction serializes incremental staging without blocking browse queries.
      * SQLite releases it on process death; no PID lease, expiry, or stale-file deletion is needed. */
@@ -202,15 +182,46 @@ export class HistoryStore {
             this.ingestLock.exec("BEGIN IMMEDIATE");
         }
         catch (error) {
-            if (/locked|busy/i.test(String(error.message)))
+            if (/locked|busy/i.test(errorMessage(error))) {
                 throw new HistoryIndexError("INDEX_BUSY", "Another worker is indexing this generation.");
+            }
             throw error;
         }
     }
-    endIngest() { if (this.ingestLock?.isTransaction)
-        this.ingestLock.exec("ROLLBACK"); }
-    close() { this.ingestLock?.close(); this.db.close(); }
+    endIngest() {
+        if (this.ingestLock?.isTransaction === true) {
+            this.ingestLock.exec("ROLLBACK");
+        }
+    }
+    close() {
+        this.ingestLock?.close();
+        this.db.close();
+    }
 }
-function isCorruption(error) {
-    return error instanceof HistoryIndexError && error.code === "CORRUPT" || /malformed|not a database|no such table|corrupt/i.test(String(error.message));
+function terminalBoundary(child, updatedAt, terminal) {
+    if (!terminal) {
+        return { entry: null, endedAt: null };
+    }
+    return {
+        entry: child.result?.terminalEntryId ?? null,
+        endedAt: hasText(child.result?.terminalEntryId) ? null : updatedAt,
+    };
+}
+function attentionRank(view) {
+    if (view.attention.includes("awaiting_input")) {
+        return 0;
+    }
+    if (view.attention.some((reason) => reason !== "unreviewed")) {
+        return 1;
+    }
+    if (view.state === "live") {
+        return 2;
+    }
+    return view.attention.length > 0 ? 3 : 4;
+}
+function freshnessState(pending, errors) {
+    if (pending > 0) {
+        return "catching-up";
+    }
+    return errors > 0 ? "degraded" : "current";
 }