@zq-silk/yui 0.5.2 → 0.6.0

package/dist/storage/upgrade/sqliteStateMigration.js

@@ -0,0 +1,457 @@
+/**
+ * state.json -> SQLite staged migration (task-21 §8, work-item-4).
+ *
+ * This module is the document-to-database population and verification seam for
+ * the layout 6 -> 7 offline migration. It is deliberately side-effect-light:
+ *
+ *  - `populateSqliteFromState` opens a {@link SqliteTaskStore} on the sidecar
+ *    `yui.db.staged` and bulk-loads every record family from the parsed
+ *    `state.json` document, preserving the Home identity, revision, and ID
+ *    high-water marks. The source document is never written.
+ *  - `computeStateFamilyChecksums` / `computeDbFamilyChecksums` compute a
+ *    per-family `{ count, hash }` over the canonical JSON of every record, so
+ *    the staged database can be verified against an independent re-read of
+ *    `state.json` (the Verify phase of §8.2).
+ *  - `verifySqliteMigration` compares the two checksum maps and throws on any
+ *    count or content mismatch, leaving the source untouched.
+ *
+ * The checksum is content-based: each record is canonicalised (sorted keys,
+ * stable array ordering) and hashed individually; the per-family hash is the
+ * sha256 of the sorted record hashes. This is order-independent (a map
+ * serialised in any key order produces the same checksum) and catches any
+ * dropped, duplicated, or mutated record.
+ */
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import Database from "better-sqlite3";
+import { SqliteTaskStore } from "../sqliteStore.js";
+/** The sidecar database filename used during staging. */
+export const STAGED_DATABASE_FILENAME = "yui.db.staged";
+/** The committed database filename. */
+export const COMMITTED_DATABASE_FILENAME = "yui.db";
+// ---------------------------------------------------------------------------
+// Canonical JSON and hashing
+// ---------------------------------------------------------------------------
+/**
+ * Deterministic JSON serialisation: object keys are sorted recursively so that
+ * two semantically-equal objects serialise identically regardless of key
+ * insertion order. Arrays preserve their order.
+ */
+function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalJson).join(",")}]`;
+    }
+    const record = value;
+    const keys = Object.keys(record).sort();
+    return `{${keys
+        .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+        .join(",")}}`;
+}
+/**
+ * Compute a per-family checksum over a set of records. Each record is hashed
+ * individually (over its canonical JSON); the family hash is the sha256 of
+ * the sorted per-record hashes, making the result independent of record
+ * ordering.
+ */
+function hashRecords(records) {
+    const hashes = records
+        .map((record) => createHash("sha256").update(canonicalJson(record)).digest("hex"))
+        .sort();
+    const hash = createHash("sha256").update(hashes.join("\n")).digest("hex");
+    return { count: records.length, hash };
+}
+// ---------------------------------------------------------------------------
+// Document shape helpers
+// ---------------------------------------------------------------------------
+function asObject(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return {};
+    return value;
+}
+function asObjectMap(value) {
+    const record = asObject(value);
+    const result = {};
+    for (const [key, entry] of Object.entries(record)) {
+        if (entry !== null && typeof entry === "object" && !Array.isArray(entry)) {
+            result[key] = entry;
+        }
+    }
+    return result;
+}
+function asNullableObject(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value !== "object" || Array.isArray(value))
+        return null;
+    return value;
+}
+function asStoredTask(value) {
+    const record = asObject(value);
+    return {
+        task: asObject(record.task),
+        brief: asNullableObject(record.brief),
+        roles: asObjectMap(record.roles),
+        managedWorkspaces: asObjectMap(record.managedWorkspaces),
+        roleSessionSets: asObjectMap(record.roleSessionSets),
+        workItems: asObjectMap(record.workItems),
+        agentRuns: asObjectMap(record.agentRuns),
+        reviewRounds: asObjectMap(record.reviewRounds),
+        changeSets: asObjectMap(record.changeSets),
+        integrationAttempts: asObjectMap(record.integrationAttempts),
+        activeRuns: asObjectMap(record.activeRuns),
+        messages: asObjectMap(record.messages),
+        inputRequests: asObjectMap(record.inputRequests),
+        decisions: asObjectMap(record.decisions),
+        milestones: asObjectMap(record.milestones),
+        events: asObjectMap(record.events),
+        leaderFailure: asNullableObject(record.leaderFailure),
+        operatorNotification: asNullableObject(record.operatorNotification),
+        idHighWaterMarks: asObject(record.idHighWaterMarks)
+    };
+}
+function tasksOf(state) {
+    const result = {};
+    for (const [taskId, raw] of Object.entries(asObject(state.tasks))) {
+        result[taskId] = asStoredTask(raw);
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Population (Snapshot -> Stage)
+// ---------------------------------------------------------------------------
+/**
+ * Populate a fresh SQLite database from the parsed `state.json` document.
+ *
+ * The database is opened with the `migration` option (fence bypass) because
+ * the staged load runs while the upgrade fence is active. Every record family
+ * is saved through the canonical {@link SqliteTaskStore} methods so the
+ * typed-column projections and payload contents match what a live store would
+ * produce. The Home identity, revision, and ID high-water marks are preserved
+ * so the opened store continues from the same counters.
+ *
+ * This function NEVER writes `state.json`; it only creates/populates the
+ * sidecar database file.
+ */
+export function populateSqliteFromState(home, state, databaseFilename) {
+    const store = new SqliteTaskStore(home, { databaseFilename, migration: true });
+    try {
+        store.transaction(() => {
+            // Home identity + revision continuity.
+            const identity = asNullableObject(state.homeIdentity);
+            const revision = typeof state.revision === "number" ? state.revision : 0;
+            if (identity !== null) {
+                store.migrationSetHomeMeta(identity, revision);
+            }
+            // Config singleton.
+            const config = asNullableObject(state.config);
+            if (config !== null)
+                store.saveConfig(config);
+            // Global record families.
+            for (const agent of Object.values(asObjectMap(state.configuredAgents))) {
+                store.saveConfiguredAgent(agent);
+            }
+            for (const project of Object.values(asObjectMap(state.projects))) {
+                store.saveProject(project);
+            }
+            for (const profile of Object.values(asObjectMap(state.agentProfiles))) {
+                store.saveAgentProfile(profile);
+            }
+            for (const role of Object.values(asObjectMap(state.globalRoles))) {
+                store.saveGlobalRole(role);
+            }
+            for (const sessions of Object.values(asObjectMap(state.globalRoleSessionSets))) {
+                store.saveGlobalRoleSessionSet(sessions);
+            }
+            // Tasks and their per-task families.
+            const tasks = tasksOf(state);
+            for (const [taskId, stored] of Object.entries(tasks)) {
+                store.saveTask(stored.task);
+                if (stored.brief !== null) {
+                    store.saveTaskBrief(taskId, stored.brief);
+                }
+                for (const role of Object.values(stored.roles)) {
+                    store.saveRole(taskId, role);
+                }
+                for (const workspace of Object.values(stored.managedWorkspaces)) {
+                    store.saveManagedWorkspace(workspace);
+                }
+                for (const sessions of Object.values(stored.roleSessionSets)) {
+                    store.saveRoleSessionSet(sessions);
+                }
+                for (const item of Object.values(stored.workItems)) {
+                    store.saveWorkItem(taskId, item);
+                }
+                for (const run of Object.values(stored.agentRuns)) {
+                    store.saveAgentRun(run);
+                }
+                for (const round of Object.values(stored.reviewRounds)) {
+                    store.saveReviewRound(taskId, round);
+                }
+                for (const changeSet of Object.values(stored.changeSets)) {
+                    store.saveChangeSet(taskId, changeSet);
+                }
+                for (const attempt of Object.values(stored.integrationAttempts)) {
+                    store.saveIntegrationAttempt(taskId, attempt);
+                }
+                // Active-run pointers: the document stores { schemaVersion, runId }
+                // keyed by pointer; the store derives the pointer from the Run.
+                for (const [pointer, value] of Object.entries(stored.activeRuns)) {
+                    const run = stored.agentRuns[value.runId];
+                    if (run === undefined) {
+                        throw new Error(`Active run pointer ${taskId}/${pointer} references missing agent run ${value.runId}.`);
+                    }
+                    if (pointer.startsWith("/execution-lane/")) {
+                        store.saveActiveExecutionLaneRun(run);
+                    }
+                    else {
+                        store.saveActiveAgentRun(run);
+                    }
+                }
+                for (const message of Object.values(stored.messages)) {
+                    store.saveMessage(taskId, message);
+                }
+                for (const request of Object.values(stored.inputRequests)) {
+                    store.saveInputRequest(taskId, request);
+                }
+                for (const decision of Object.values(stored.decisions)) {
+                    store.saveDecision(taskId, decision);
+                }
+                for (const milestone of Object.values(stored.milestones)) {
+                    store.saveMilestone(taskId, milestone);
+                }
+                for (const event of Object.values(stored.events)) {
+                    store.saveEvent(taskId, event);
+                }
+                if (stored.leaderFailure !== null) {
+                    store.saveLeaderFailure(stored.leaderFailure);
+                }
+                if (stored.operatorNotification !== null) {
+                    store.saveOperatorNotification(stored.operatorNotification);
+                }
+                // Per-task ID high-water marks.
+                for (const [kind, highWater] of Object.entries(stored.idHighWaterMarks)) {
+                    if (typeof highWater === "number" && Number.isFinite(highWater)) {
+                        store.migrationSeedIdSequence(taskId, kind, highWater);
+                    }
+                }
+            }
+            // Work mailboxes.
+            for (const mailbox of Object.values(asObjectMap(state.mailboxes))) {
+                store.saveWorkMailbox(mailbox);
+            }
+            // Global ID high-water marks, derived from existing task/project ids.
+            seedGlobalSequences(store, state);
+        });
+    }
+    finally {
+        store.close();
+    }
+}
+/**
+ * Seed `global_sequences` from the numeric suffixes of existing task and
+ * project ids so the next allocated id never collides with a historical one.
+ * Ids that do not match `<kind>-<n>` are ignored (legacy formats).
+ */
+function seedGlobalSequences(store, state) {
+    const taskMax = maxIdSuffix(Object.keys(asObject(state.tasks)), "task");
+    const projectMax = maxIdSuffix(Object.keys(asObject(state.projects)), "project");
+    if (taskMax > 0)
+        store.migrationSeedGlobalSequence("task", taskMax);
+    if (projectMax > 0)
+        store.migrationSeedGlobalSequence("project", projectMax);
+}
+function maxIdSuffix(ids, prefix) {
+    let max = 0;
+    const pattern = new RegExp(`^${prefix}-(\\d+)$`, "u");
+    for (const id of ids) {
+        const match = pattern.exec(id);
+        if (match !== null) {
+            const value = Number.parseInt(match[1], 10);
+            if (Number.isSafeInteger(value))
+                max = Math.max(max, value);
+        }
+    }
+    return max;
+}
+// ---------------------------------------------------------------------------
+// State-side checksums (the source of truth)
+// ---------------------------------------------------------------------------
+/**
+ * Compute per-family checksums from the parsed `state.json` document. This is
+ * the expected checksum set; the staged database is verified against it.
+ */
+export function computeStateFamilyChecksums(state) {
+    const checksums = {};
+    checksums.config = hashRecords(asNullableObject(state.config) === null ? [] : [asObject(state.config)]);
+    checksums.configuredAgent = hashRecords(Object.values(asObjectMap(state.configuredAgents)));
+    checksums.project = hashRecords(Object.values(asObjectMap(state.projects)));
+    checksums.agentProfile = hashRecords(Object.values(asObjectMap(state.agentProfiles)));
+    checksums.globalRole = hashRecords(Object.values(asObjectMap(state.globalRoles)));
+    checksums.globalRoleSessionSet = hashRecords(Object.values(asObjectMap(state.globalRoleSessionSets)));
+    // Flatten the per-task families across all tasks.
+    const tasks = tasksOf(state);
+    const taskRecords = [];
+    const briefs = [];
+    const roles = [];
+    const workspaces = [];
+    const roleSessionSets = [];
+    const workItems = [];
+    const agentRuns = [];
+    const reviewRounds = [];
+    const changeSets = [];
+    const integrationAttempts = [];
+    const activeRunPointers = [];
+    const messages = [];
+    const inputRequests = [];
+    const decisions = [];
+    const milestones = [];
+    const events = [];
+    const leaderFailures = [];
+    const operatorNotifications = [];
+    for (const stored of Object.values(tasks)) {
+        taskRecords.push(stored.task);
+        if (stored.brief !== null)
+            briefs.push(stored.brief);
+        roles.push(...Object.values(stored.roles));
+        workspaces.push(...Object.values(stored.managedWorkspaces));
+        roleSessionSets.push(...Object.values(stored.roleSessionSets));
+        workItems.push(...Object.values(stored.workItems));
+        agentRuns.push(...Object.values(stored.agentRuns));
+        reviewRounds.push(...Object.values(stored.reviewRounds));
+        changeSets.push(...Object.values(stored.changeSets));
+        integrationAttempts.push(...Object.values(stored.integrationAttempts));
+        activeRunPointers.push(...Object.values(stored.activeRuns));
+        messages.push(...Object.values(stored.messages));
+        inputRequests.push(...Object.values(stored.inputRequests));
+        decisions.push(...Object.values(stored.decisions));
+        milestones.push(...Object.values(stored.milestones));
+        events.push(...Object.values(stored.events));
+        if (stored.leaderFailure !== null)
+            leaderFailures.push(stored.leaderFailure);
+        if (stored.operatorNotification !== null)
+            operatorNotifications.push(stored.operatorNotification);
+    }
+    checksums.task = hashRecords(taskRecords);
+    checksums.taskBrief = hashRecords(briefs);
+    checksums.taskRole = hashRecords(roles);
+    checksums.managedWorkspace = hashRecords(workspaces);
+    checksums.taskRoleSessionSet = hashRecords(roleSessionSets);
+    checksums.workItem = hashRecords(workItems);
+    checksums.agentRun = hashRecords(agentRuns);
+    checksums.reviewRound = hashRecords(reviewRounds);
+    checksums.changeSet = hashRecords(changeSets);
+    checksums.integrationAttempt = hashRecords(integrationAttempts);
+    checksums.activeRunPointer = hashRecords(activeRunPointers);
+    checksums.message = hashRecords(messages);
+    checksums.inputRequest = hashRecords(inputRequests);
+    checksums.decision = hashRecords(decisions);
+    checksums.milestone = hashRecords(milestones);
+    checksums.event = hashRecords(events);
+    checksums.leaderFailure = hashRecords(leaderFailures);
+    checksums.operatorNotification = hashRecords(operatorNotifications);
+    checksums.workMailbox = hashRecords(Object.values(asObjectMap(state.mailboxes)));
+    return checksums;
+}
+function hashPayloadTable(db, sql) {
+    const rows = db.prepare(sql).all();
+    return hashRecords(rows.map((row) => JSON.parse(row.payload)));
+}
+/** Reconstruct a WorkMailbox from the normalised mailboxes table columns. */
+function rowToMailbox(row) {
+    let target;
+    switch (row.target_kind) {
+        case "operator":
+            target = { kind: "operator" };
+            break;
+        case "task":
+            target = { kind: "task", taskId: row.task_id };
+            break;
+        case "role":
+            target = { kind: "role", taskId: row.task_id, roleName: row.role_name };
+            break;
+        case "role-runtime":
+            target = { kind: "role-runtime", taskId: row.task_id, roleName: row.role_name };
+            break;
+        case "global-role-runtime":
+            target = { kind: "global-role-runtime", roleName: row.role_name };
+            break;
+        default:
+            target = { kind: row.target_kind };
+    }
+    return {
+        schemaVersion: 1,
+        target,
+        nextSequence: row.next_sequence,
+        processing: row.processing === null ? null : JSON.parse(row.processing),
+        pending: row.pending === null ? null : JSON.parse(row.pending)
+    };
+}
+/**
+ * Compute per-family checksums from the SQLite database. The database is
+ * opened read-only; this is the independent verification read.
+ */
+export function computeDbFamilyChecksums(home, databaseFilename) {
+    const dbPath = join(home, databaseFilename);
+    const db = new Database(dbPath, { readonly: true });
+    try {
+        const checksums = {};
+        checksums.config = hashPayloadTable(db, "SELECT payload FROM config");
+        checksums.configuredAgent = hashPayloadTable(db, "SELECT payload FROM configured_agents");
+        checksums.project = hashPayloadTable(db, "SELECT payload FROM projects");
+        checksums.agentProfile = hashPayloadTable(db, "SELECT payload FROM agent_profiles");
+        checksums.globalRole = hashPayloadTable(db, "SELECT payload FROM global_roles");
+        checksums.globalRoleSessionSet = hashPayloadTable(db, "SELECT payload FROM global_role_session_sets");
+        checksums.task = hashPayloadTable(db, "SELECT payload FROM task_records");
+        checksums.taskBrief = hashPayloadTable(db, "SELECT brief AS payload FROM task_records WHERE brief IS NOT NULL");
+        checksums.taskRole = hashPayloadTable(db, "SELECT payload FROM task_roles");
+        checksums.managedWorkspace = hashPayloadTable(db, "SELECT payload FROM managed_workspaces");
+        checksums.taskRoleSessionSet = hashPayloadTable(db, "SELECT payload FROM role_session_sets");
+        checksums.workItem = hashPayloadTable(db, "SELECT payload FROM work_items");
+        checksums.agentRun = hashPayloadTable(db, "SELECT payload FROM agent_runs");
+        checksums.reviewRound = hashPayloadTable(db, "SELECT payload FROM review_rounds");
+        checksums.changeSet = hashPayloadTable(db, "SELECT payload FROM change_sets");
+        checksums.integrationAttempt = hashPayloadTable(db, "SELECT payload FROM integration_attempts");
+        checksums.activeRunPointer = hashPayloadTable(db, "SELECT payload FROM active_runs");
+        checksums.message = hashPayloadTable(db, "SELECT payload FROM messages");
+        checksums.inputRequest = hashPayloadTable(db, "SELECT payload FROM input_requests");
+        checksums.decision = hashPayloadTable(db, "SELECT payload FROM decisions");
+        checksums.milestone = hashPayloadTable(db, "SELECT payload FROM milestones");
+        checksums.event = hashPayloadTable(db, "SELECT payload FROM events");
+        checksums.leaderFailure = hashPayloadTable(db, "SELECT payload FROM task_projections WHERE kind = 'leader-failure' AND payload IS NOT NULL");
+        checksums.operatorNotification = hashPayloadTable(db, "SELECT payload FROM task_projections WHERE kind = 'operator-notification' AND payload IS NOT NULL");
+        // Mailboxes are reconstructed from typed columns (no payload column).
+        const mailboxRows = db.prepare("SELECT target_kind, task_id, role_name, next_sequence, processing, pending FROM mailboxes ORDER BY target_key").all();
+        checksums.workMailbox = hashRecords(mailboxRows.map(rowToMailbox));
+        return checksums;
+    }
+    finally {
+        db.close();
+    }
+}
+// ---------------------------------------------------------------------------
+// Verification (Verify phase of §8.2)
+// ---------------------------------------------------------------------------
+/**
+ * Compare the per-family checksums of the source document against those of the
+ * staged database. Throws on any count or content mismatch, naming every
+ * divergent family. The source document is never modified.
+ */
+export function verifySqliteChecksums(state, home, databaseFilename) {
+    const expected = computeStateFamilyChecksums(state);
+    const actual = computeDbFamilyChecksums(home, databaseFilename);
+    const families = new Set([...Object.keys(expected), ...Object.keys(actual)]);
+    const mismatches = [];
+    for (const family of families) {
+        const e = expected[family];
+        const a = actual[family];
+        if (e === undefined || a === undefined || e.count !== a.count || e.hash !== a.hash) {
+            mismatches.push(`${family} (expected ${e === undefined ? "absent" : `${e.count}/${e.hash.slice(0, 12)}`}, ` +
+                `found ${a === undefined ? "absent" : `${a.count}/${a.hash.slice(0, 12)}`})`);
+        }
+    }
+    if (mismatches.length > 0) {
+        throw new Error(`SQLite migration checksum mismatch for ${mismatches.length} family/families: ${mismatches.join("; ")}`);
+    }
+}

package/dist/storage/upgrade/upgradeOrchestrator.js

@@ -34,19 +34,21 @@
  * authoritative input byte-for-byte unchanged.
  */
 import { spawn } from "node:child_process";
-import { readFileSync, readdirSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { describeReport, runMigration } from "../migration/index.js";
 import { validateCompatibleFileTaskStore } from "../compatibleTaskStore.js";
 import { stopFileTaskController, ensureFileTaskController, ensureFileTaskControllerIdentity } from "../../controller/clientRuntime.js";
 import { callController } from "../../core/controllerClient.js";
 import { FileTaskStore, STORAGE_STATE_FILE, withStorageWriteLock } from "../taskStore.js";
+import { SqliteTaskStore } from "../sqliteStore.js";
 import { clearUpgradeFence, placeUpgradeFence, readUpgradeFence, UpgradeFenceError } from "../upgradeFence.js";
 import { withUpgradeCoordinationLock } from "../upgradeCoordination.js";
 import { clearUpgradeReceipt, writeUpgradeReceipt, upgradeReceiptPath } from "./upgradeReceipt.js";
 import { switchProgressPath } from "./switchProgress.js";
 import { classifyHome } from "./homeClassification.js";
 import { createHomeMigrationTarget, describeActiveRuntime, homeRuntimeIsActive, inspectHomeRuntime } from "./homeMigrationTarget.js";
+import { createSqliteMigrationTarget } from "./sqliteMigrationTarget.js";
 import { inspectOfflineUpgradeInventory } from "./offlineUpgradeInventory.js";
 /**
  * Run the storage upgrade for one Home. Never throws for an expected blocker;
@@ -160,14 +162,20 @@ export async function runStorageUpgrade(options) {
             return withClassification(offlineInventoryBlocker(inventory, true), classification);
         }
     }
-    const target = createHomeMigrationTarget({
-        home,
-        latest,
-        now,
-        callerPid,
-        ...(options.renameImpl === undefined ? {} : { renameImpl: options.renameImpl }),
-        ...(options.switchFaultHook === undefined ? {} : { switchFaultHook: options.switchFaultHook })
-    });
+    // Select the migration target. A layout-6 Home migrates to the SQLite
+    // control-plane layout (7) via the staged state.json→SQLite target; all
+    // other plans (record-only on layout 7) use the file-document target.
+    const usesSqliteTarget = classification.layoutVersion === 6 && latest.layout === 7;
+    const target = usesSqliteTarget
+        ? createSqliteMigrationTarget({ home, latest, registry, now, callerPid })
+        : createHomeMigrationTarget({
+            home,
+            latest,
+            now,
+            callerPid,
+            ...(options.renameImpl === undefined ? {} : { renameImpl: options.renameImpl }),
+            ...(options.switchFaultHook === undefined ? {} : { switchFaultHook: options.switchFaultHook })
+        });
     // 2) A USABLE (already-current) Home has nothing to migrate; the engine
     // confirms with a no-op and we never fence, drain, or switch.
     if (verdict === "USABLE") {
@@ -726,12 +734,30 @@ function readCommittedRevision(home) {
 /** Post-switch health check: a fresh loader must parse the promoted Home. */
 function postSwitchHealthCheck(home) {
     try {
-        const store = new FileTaskStore(home);
-        store.getConfig();
-        store.listTasks();
-        store.listProjects();
-        store.listConfiguredAgents();
-        store.listWorkMailboxes();
+        // A layout-7 Home that went through the SQLite staged migration has
+        // yui.db; verify it through the SQLite store. Otherwise fall back to the
+        // file-document store (record-only migrations on an existing layout-7 Home).
+        if (existsSync(join(home, "yui.db"))) {
+            const store = new SqliteTaskStore(home);
+            try {
+                store.getConfig();
+                store.listTasks();
+                store.listProjects();
+                store.listConfiguredAgents();
+                store.listWorkMailboxes();
+            }
+            finally {
+                store.close();
+            }
+        }
+        else {
+            const store = new FileTaskStore(home);
+            store.getConfig();
+            store.listTasks();
+            store.listProjects();
+            store.listConfiguredAgents();
+            store.listWorkMailboxes();
+        }
         return null;
     }
     catch (error) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zq-silk/yui",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Local control plane for long-running native agent CLI sessions backed by tmux.",
   "license": "MIT",
   "private": false,
@@ -48,6 +48,7 @@
   "dependencies": {
     "@xterm/addon-fit": "^0.11.0",
     "@xterm/xterm": "^6.0.0",
+    "better-sqlite3": "^12.11.1",
     "node-pty": "^1.1.0",
     "smol-toml": "1.7.0",
     "ws": "^8.21.1"