@autopilot-harness/core 0.1.0

package/dist/state-store.js

@@ -0,0 +1,1091 @@
+import fs from "node:fs";
+import path from "node:path";
+import { migrate, getLatestSchemaVersion, parseSchemaVersionValue } from "./migrate.js";
+import { isLexicallyInsideProject, isRealpathInsideProject, normalizeProjectRoot, } from "./project-path.js";
+import { openDatabase } from "./sqlite.js";
+import { isSafeTrackSlug } from "./track-slug.js";
+function nowIso() {
+    return new Date().toISOString();
+}
+/**
+ * Next `pending_followup_at` value. When `nowIso()` collides with `previousAt`,
+ * advance ≥1ms so claim/CAS ownership stamps stay unique (same-ms refresh must
+ * not look like the prior claim).
+ */
+function nextFollowupTimestamp(previousAt) {
+    let ts = nowIso();
+    const prev = previousAt ?? "";
+    if (prev && ts === prev) {
+        const t = Date.parse(prev);
+        ts = new Date((Number.isNaN(t) ? Date.now() : t) + 1).toISOString();
+    }
+    return ts;
+}
+/** Stable short id for CLI tables (first 8 chars of dehyphenated conversation_id). */
+export function shortConversationId(conversationId) {
+    return conversationId.replace(/-/g, "").slice(0, 8);
+}
+/** Max length for user/platform session titles (characters). */
+export const SESSION_TITLE_MAX_LENGTH = 200;
+const TITLE_CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
+/** Normalize and validate a session title; throws on empty/too long/controls. */
+export function normalizeSessionTitle(title) {
+    if (typeof title !== "string") {
+        throw new Error("Title must be a non-empty string");
+    }
+    const trimmed = title.trim();
+    if (!trimmed) {
+        throw new Error("Title must be a non-empty string");
+    }
+    if (TITLE_CONTROL_CHARS.test(trimmed)) {
+        throw new Error("Title must not contain control characters");
+    }
+    if (trimmed.length > SESSION_TITLE_MAX_LENGTH) {
+        throw new Error(`Title exceeds ${SESSION_TITLE_MAX_LENGTH} characters`);
+    }
+    return trimmed;
+}
+/** Collapse controls for single-line CLI table cells (platform titles may be dirty). */
+export function sanitizeSessionDisplayText(text) {
+    return text.replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/ +/g, " ").trim();
+}
+export class StateStore {
+    db;
+    projectRoot;
+    writeDepth = 0;
+    constructor(projectRoot, dbPath) {
+        // Trim before resolve — padded absolute roots become cwd-relative otherwise.
+        const root = normalizeProjectRoot(projectRoot);
+        if (!root) {
+            throw new Error("Invalid project root");
+        }
+        this.projectRoot = path.resolve(root);
+        const resolved = dbPath ?? path.join(this.projectRoot, ".autopilot", "state.db");
+        this.db = openDatabase(resolved);
+        try {
+            // Wait on locks so concurrent BEGIN IMMEDIATE (one_executor) can serialize
+            // instead of failing immediately with SQLITE_BUSY.
+            this.db.pragma("busy_timeout = 5000");
+        }
+        catch {
+            /* node:sqlite may ignore */
+        }
+        if (resolved !== ":memory:") {
+            try {
+                this.db.pragma("journal_mode = WAL");
+            }
+            catch {
+                /* node:sqlite may ignore */
+            }
+        }
+        migrate(this.db);
+    }
+    close() {
+        this.db.close();
+    }
+    getSchemaVersion() {
+        const row = this.db
+            .prepare("SELECT value FROM _schema_meta WHERE key = 'schema_version'")
+            .get();
+        return parseSchemaVersionValue(row?.value);
+    }
+    ensureReviewChain(conversationId) {
+        if (this.isInvalidConversationId(conversationId)) {
+            throw new Error("Invalid conversation id");
+        }
+        const ts = nowIso();
+        // INSERT OR IGNORE + EXISTS: refuse orphans without a session; concurrent
+        // creators are idempotent (plain INSERT would UNIQUE-fail on the PK).
+        this.insertReviewChainIfSession(conversationId, ts);
+        // Covers: no session, purge race after insert, and stale orphan chain rows.
+        if (!this.getSession(conversationId)) {
+            // Only delete while still session-less (avoids wiping a concurrent recreate).
+            this.db
+                .prepare(`DELETE FROM review_chains
+           WHERE conversation_id = ?
+             AND NOT EXISTS (SELECT 1 FROM sessions WHERE conversation_id = ?)`)
+                .run(conversationId, conversationId);
+            throw new Error("No session for conversation");
+        }
+        // Re-read after session check so a concurrent INSERT is not missed.
+        let ensured = this.getReviewChain(conversationId);
+        if (!ensured) {
+            // Session present but chain gone (e.g. purge deleted chain first) — retry once.
+            this.insertReviewChainIfSession(conversationId, ts);
+            ensured = this.getReviewChain(conversationId);
+        }
+        if (!ensured) {
+            throw new Error("No session for conversation");
+        }
+        return ensured;
+    }
+    /** Reject blank, padded, or control-bearing conversation ids (align resolveSessionId). */
+    isInvalidConversationId(conversationId) {
+        return (typeof conversationId !== "string" ||
+            !conversationId.trim() ||
+            conversationId !== conversationId.trim() ||
+            /[\u0000-\u001f\u007f]/.test(conversationId));
+    }
+    /** Public gate for hooks / stop handlers (fail-soft before any mutation). */
+    isConversationIdOk(conversationId) {
+        return !this.isInvalidConversationId(conversationId);
+    }
+    insertReviewChainIfSession(conversationId, ts) {
+        this.db
+            .prepare(`INSERT OR IGNORE INTO review_chains (conversation_id, fix_round, confirm_left, chain_pending, code_edited, item_confirm_complete, updated_at)
+         SELECT ?, 0, NULL, 0, 0, 0, ?
+         WHERE EXISTS (SELECT 1 FROM sessions WHERE conversation_id = ?)`)
+            .run(conversationId, ts, conversationId);
+    }
+    getReviewChain(conversationId) {
+        const row = this.db
+            .prepare("SELECT * FROM review_chains WHERE conversation_id = ?")
+            .get(conversationId);
+        if (!row)
+            return null;
+        return {
+            ...row,
+            reviewing_item_id: row.reviewing_item_id ?? null,
+            pending_followup: row.pending_followup ?? null,
+            pending_followup_at: row.pending_followup_at ?? null,
+            pending_redeliver_at: row.pending_redeliver_at ?? null,
+        };
+    }
+    getSession(conversationId) {
+        return (this.db
+            .prepare("SELECT * FROM sessions WHERE conversation_id = ?")
+            .get(conversationId) ?? null);
+    }
+    listSessions() {
+        return this.db
+            .prepare("SELECT * FROM sessions ORDER BY last_active_at DESC, conversation_id ASC")
+            .all();
+    }
+    /**
+     * Resolve a full conversation_id or a unique prefix / short id (first 8 hex-ish chars).
+     */
+    resolveSessionId(query) {
+        const q = query.trim();
+        if (!q) {
+            return { ok: false, error: "Session id required" };
+        }
+        if (/[\u0000-\u001f\u007f]/.test(q)) {
+            return {
+                ok: false,
+                error: "Session id must not contain control characters",
+            };
+        }
+        if (this.getSession(q)) {
+            return { ok: true, id: q };
+        }
+        const matches = this.listSessions().filter((s) => {
+            const id = s.conversation_id;
+            return id.startsWith(q) || shortConversationId(id) === q;
+        });
+        if (matches.length === 1) {
+            return { ok: true, id: matches[0].conversation_id };
+        }
+        if (matches.length === 0) {
+            return { ok: false, error: `No session matching "${q}"` };
+        }
+        return {
+            ok: false,
+            error: `Ambiguous id "${q}" matches ${matches.length} sessions; use a longer prefix`,
+        };
+    }
+    renameSession(conversationId, title) {
+        if (this.isInvalidConversationId(conversationId)) {
+            return null;
+        }
+        const trimmed = normalizeSessionTitle(title);
+        return this.exclusiveWrite(() => {
+            if (!this.getSession(conversationId)) {
+                return { commit: false, value: null };
+            }
+            const ts = nowIso();
+            this.db
+                .prepare(`UPDATE sessions SET
+            session_title = ?, session_title_source = 'user', title_updated_at = ?,
+            updated_at = ?
+           WHERE conversation_id = ?`)
+                .run(trimmed, ts, ts, conversationId);
+            return { commit: true, value: this.getSession(conversationId) };
+        });
+    }
+    /** Delete session row and its review_chains row (atomic). */
+    purgeSession(conversationId, 
+    /**
+     * Optional guard evaluated inside the write transaction (re-check after races).
+     * Return false to skip delete without error.
+     */
+    ifRow) {
+        return this.exclusiveWrite(() => {
+            const row = this.getSession(conversationId);
+            if (!row) {
+                return { commit: false, value: false };
+            }
+            if (ifRow && !ifRow(row)) {
+                return { commit: false, value: false };
+            }
+            this.db
+                .prepare("DELETE FROM review_chains WHERE conversation_id = ?")
+                .run(conversationId);
+            this.db
+                .prepare("DELETE FROM sessions WHERE conversation_id = ?")
+                .run(conversationId);
+            return { commit: true, value: true };
+        });
+    }
+    /**
+     * Reset review chain fields (same as REPLAN / fresh applyRun review reset).
+     * Clears pending_followup* so a later stop cannot redeliver a stale prompt and
+     * resurrect chain_pending after the caller believed the chain was wiped.
+     * Session row kept. Atomic: refuses orphan review_chains if session was purged.
+     */
+    resetReviewChain(conversationId) {
+        return this.exclusiveWrite(() => {
+            if (!this.getSession(conversationId)) {
+                return { commit: false, value: false };
+            }
+            this.updateReviewChain(conversationId, {
+                fix_round: 0,
+                confirm_left: null,
+                chain_pending: 0,
+                code_edited: 0,
+                item_confirm_complete: 0,
+                reviewing_item_id: null,
+                pending_followup: null,
+                pending_followup_at: null,
+                pending_redeliver_at: null,
+            });
+            return { commit: true, value: true };
+        });
+    }
+    /**
+     * Pin untrusted session roots to this store's projectRoot.
+     * Otherwise a caller could write project_root=/evil and later containment
+     * checks that trust session.project_root would pass for outside files.
+     * code_root may be a descendant (future worktree); project_root must match.
+     * Relative paths resolve against the store root (not process.cwd()).
+     */
+    sanitizeSessionRoot(raw, opts) {
+        const n = normalizeProjectRoot(raw);
+        if (!n)
+            return this.projectRoot;
+        const resolved = path.isAbsolute(n)
+            ? path.resolve(n)
+            : path.resolve(this.projectRoot, n);
+        if (resolved === this.projectRoot)
+            return this.projectRoot;
+        if (opts?.allowDescendant &&
+            isLexicallyInsideProject(this.projectRoot, resolved)) {
+            return resolved;
+        }
+        return this.projectRoot;
+    }
+    /**
+     * Refuse checklist_path that escapes the store project (absolute outside or
+     * relative that resolves outside). Missing paths kept only if lexically inside.
+     * Relative inputs stay relative when allowed (callers/tests rely on that form).
+     */
+    sanitizeChecklistPath(raw) {
+        if (typeof raw !== "string" || !raw || raw.includes("\0"))
+            return "";
+        if (path.isAbsolute(raw)) {
+            const abs = path.resolve(raw);
+            try {
+                fs.lstatSync(abs);
+                return isRealpathInsideProject(this.projectRoot, abs) ? abs : "";
+            }
+            catch {
+                return isLexicallyInsideProject(this.projectRoot, abs) ? abs : "";
+            }
+        }
+        const abs = path.resolve(this.projectRoot, raw);
+        try {
+            fs.lstatSync(abs);
+            return isRealpathInsideProject(this.projectRoot, abs) ? raw : "";
+        }
+        catch {
+            return isLexicallyInsideProject(this.projectRoot, abs) ? raw : "";
+        }
+    }
+    upsertSession(partial) {
+        if (this.isInvalidConversationId(partial.conversation_id)) {
+            throw new Error("Invalid conversation id");
+        }
+        const ts = nowIso();
+        // Heal padded/NUL + refuse roots that escape this store's project.
+        const projectRoot = this.sanitizeSessionRoot(partial.project_root);
+        const codeRoot = this.sanitizeSessionRoot(partial.code_root, {
+            allowDescendant: true,
+        });
+        const checklistPath = partial.checklist_path !== undefined
+            ? this.sanitizeChecklistPath(partial.checklist_path)
+            : undefined;
+        const existing = this.getSession(partial.conversation_id);
+        if (!existing) {
+            // Only renameSession may grant source=user (validated title). Upsert must not.
+            const insertSource = partial.session_title_source === "user"
+                ? "platform"
+                : (partial.session_title_source ?? null);
+            this.db
+                .prepare(`INSERT INTO sessions (
+            conversation_id, platform, session_title, session_title_source, title_updated_at,
+            track_id, track_title, checklist_path, phase, armed, paused,
+            paused_reason, pending_action, track_candidates_json,
+            project_root, code_root, last_active_at, updated_at
+          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                .run(partial.conversation_id, partial.platform ?? "cursor", partial.session_title ?? null, insertSource, partial.title_updated_at ?? null, partial.track_id ?? "_pending", partial.track_title ?? null, checklistPath ?? "", partial.phase ?? "idle", partial.armed ?? 0, partial.paused ?? 0, partial.paused_reason ?? null, partial.pending_action ?? null, partial.track_candidates_json ?? null, projectRoot, codeRoot, ts, ts);
+        }
+        else {
+            const merged = { ...existing, ...partial, updated_at: ts, last_active_at: ts };
+            // Preserve user titles at UPDATE time (not via a stale in-memory read):
+            // concurrent renameSession can flip source to 'user' between getSession and
+            // this write; CASE keeps the row's current user title fields atomically.
+            // Upsert must not elevate source to 'user' either (ELSE bind coerced).
+            const upsertSource = merged.session_title_source === "user"
+                ? "platform"
+                : merged.session_title_source;
+            const nextProjectRoot = this.sanitizeSessionRoot(merged.project_root);
+            const nextCodeRoot = this.sanitizeSessionRoot(merged.code_root, {
+                allowDescendant: true,
+            });
+            const nextChecklistPath = this.sanitizeChecklistPath(merged.checklist_path);
+            this.db
+                .prepare(`UPDATE sessions SET
+            platform = ?,
+            session_title = CASE WHEN session_title_source = 'user' THEN session_title ELSE ? END,
+            session_title_source = CASE WHEN session_title_source = 'user' THEN session_title_source ELSE ? END,
+            title_updated_at = CASE WHEN session_title_source = 'user' THEN title_updated_at ELSE ? END,
+            track_id = ?, track_title = ?, checklist_path = ?,
+            phase = ?, armed = ?, paused = ?, paused_reason = ?, pending_action = ?,
+            track_candidates_json = ?, project_root = ?, code_root = ?,
+            error_count = ?, idle_stop_count = ?, last_active_at = ?, updated_at = ?
+           WHERE conversation_id = ?`)
+                .run(merged.platform, merged.session_title, upsertSource, merged.title_updated_at, merged.track_id, merged.track_title, nextChecklistPath, merged.phase, merged.armed, merged.paused, merged.paused_reason, merged.pending_action, merged.track_candidates_json, nextProjectRoot, nextCodeRoot, merged.error_count, merged.idle_stop_count, merged.last_active_at, merged.updated_at, partial.conversation_id);
+        }
+        return this.getSession(partial.conversation_id);
+    }
+    updateReviewChain(conversationId, patch) {
+        // Use ensure's return — avoids a second read that can race to null mid-purge.
+        const current = this.ensureReviewChain(conversationId);
+        const merged = { ...current, ...patch, updated_at: nowIso() };
+        // Align with savePendingFollowup: blank/NUL must not stay redeliverable.
+        // Also drop chain_pending so a rejected pending cannot leave the review loop armed.
+        if (typeof merged.pending_followup === "string" &&
+            (!merged.pending_followup.trim() || merged.pending_followup.includes("\0"))) {
+            merged.pending_followup = null;
+            merged.pending_followup_at = null;
+            merged.pending_redeliver_at = null;
+            merged.chain_pending = 0;
+        }
+        if (typeof merged.reviewing_item_id === "string" &&
+            (!merged.reviewing_item_id.trim() || merged.reviewing_item_id.includes("\0"))) {
+            merged.reviewing_item_id = null;
+        }
+        const result = this.db
+            .prepare(`UPDATE review_chains SET
+          fix_round = ?, confirm_left = ?, chain_pending = ?, code_edited = ?,
+          item_confirm_complete = ?, reviewing_item_id = ?,
+          pending_followup = ?, pending_followup_at = ?, pending_redeliver_at = ?,
+          updated_at = ?
+         WHERE conversation_id = ?
+           AND EXISTS (SELECT 1 FROM sessions WHERE conversation_id = ?)`)
+            .run(merged.fix_round, merged.confirm_left, merged.chain_pending, merged.code_edited, merged.item_confirm_complete, merged.reviewing_item_id, merged.pending_followup, merged.pending_followup_at, merged.pending_redeliver_at, merged.updated_at, conversationId, conversationId);
+        // Purge race after ensure: do not leave a silently-updated orphan chain.
+        if (result.changes === 0) {
+            throw new Error("No session for conversation");
+        }
+        const updated = this.getReviewChain(conversationId);
+        if (!updated) {
+            throw new Error("No session for conversation");
+        }
+        return updated;
+    }
+    /**
+     * E1: product edit → code_edited=1.
+     * Sticky `reviewing_item_id`: set only when empty so a premature checklist `[x]`
+     * cannot retarget the item under review mid-chain.
+     *
+     * When `reviewingItemId` is a function, it runs **inside** the write lock against
+     * the live chain row so concurrent advance/neutralize cannot TOCTOU a stale
+     * pending/firstUnchecked snapshot from outside the lock.
+     */
+    markCodeEdited(conversationId, reviewingItemId) {
+        this.withSessionChainWrite(conversationId, () => {
+            this.ensureReviewChain(conversationId);
+            let raw = "";
+            if (typeof reviewingItemId === "function") {
+                try {
+                    const live = this.getReviewChain(conversationId);
+                    if (live) {
+                        const resolved = reviewingItemId(live);
+                        raw = typeof resolved === "string" ? resolved.trim() : "";
+                    }
+                }
+                catch {
+                    // Resolver must not skip arming code_edited (partial-failure safe).
+                    raw = "";
+                }
+            }
+            else if (typeof reviewingItemId === "string") {
+                raw = reviewingItemId.trim();
+            }
+            const itemId = raw && !raw.includes("\0") ? raw : "";
+            // Column-only update — avoid read-merge-write clobbering concurrent E4/pending.
+            this.db
+                .prepare(`UPDATE review_chains SET
+             code_edited = 1,
+             reviewing_item_id = CASE
+               WHEN (reviewing_item_id IS NULL OR trim(reviewing_item_id) = '')
+                    AND ? != ''
+               THEN ?
+               ELSE reviewing_item_id
+             END,
+             updated_at = ?
+           WHERE conversation_id = ?
+             AND EXISTS (SELECT 1 FROM sessions WHERE conversation_id = ?)`)
+                .run(itemId, itemId, nowIso(), conversationId, conversationId);
+        });
+    }
+    /**
+     * Drop sticky code_edited without touching pending/confirm (Stop/abort path).
+     * Column-only like clearChainPending — no ensure/merge; missing chain → no-op.
+     */
+    clearCodeEdited(conversationId) {
+        if (this.isInvalidConversationId(conversationId)) {
+            return;
+        }
+        this.db
+            .prepare(`UPDATE review_chains SET code_edited = 0, updated_at = ?
+         WHERE conversation_id = ?`)
+            .run(nowIso(), conversationId);
+    }
+    /**
+     * E8: user ordinary chat clears the in-chain flag only.
+     * Do NOT wipe pending_followup* — undelivered automation must still redeliver;
+     * clearing pending here would let the next stop advance confirm_left (skip a lens).
+     * Column-only UPDATE (no ensure/merge): missing chain → no-op; concurrent stop
+     * cannot lose confirm_left/pending via stale read-merge-write.
+     */
+    clearChainPending(conversationId) {
+        if (this.isInvalidConversationId(conversationId)) {
+            return;
+        }
+        this.db
+            .prepare(`UPDATE review_chains SET chain_pending = 0, updated_at = ? WHERE conversation_id = ?`)
+            .run(nowIso(), conversationId);
+    }
+    /**
+     * Column-only redeliver hold (recover claim sleep). Also clears chain_pending so
+     * armChain=false recover cannot leave a phantom E3 arm. Avoids updateReviewChain
+     * read-merge-write clobbering confirm_left / pending under concurrency.
+     */
+    setPendingRedeliverHold(conversationId, at) {
+        if (this.isInvalidConversationId(conversationId)) {
+            return;
+        }
+        const stamp = typeof at === "string" ? at.trim() : "";
+        if (!stamp || stamp.includes("\0")) {
+            return;
+        }
+        this.db
+            .prepare(`UPDATE review_chains SET
+          pending_redeliver_at = ?, chain_pending = 0, updated_at = ?
+         WHERE conversation_id = ?`)
+            .run(stamp, nowIso(), conversationId);
+    }
+    /**
+     * Column-only: drop claim redeliver hold without touching pending / confirm.
+     * Used when finish skips CAS (e.g. another followup in flight) but sleep was
+     * no-op — leaving the hold would block host-drop redelivery for debounceMs.
+     */
+    clearPendingRedeliverHold(conversationId) {
+        if (this.isInvalidConversationId(conversationId)) {
+            return;
+        }
+        this.db
+            .prepare(`UPDATE review_chains SET pending_redeliver_at = NULL, updated_at = ?
+         WHERE conversation_id = ?`)
+            .run(nowIso(), conversationId);
+    }
+    /**
+     * Drop redeliver hold only while `pending_followup_at` still equals this stop's
+     * claim stamp (and pending is recover). Prevents wiping a peer redeliver's
+     * newly armed hold after the debounce window.
+     */
+    clearPendingRedeliverHoldIfStamp(conversationId, expectedAt) {
+        if (this.isInvalidConversationId(conversationId)) {
+            return false;
+        }
+        if (!expectedAt || expectedAt.includes("\0")) {
+            return false;
+        }
+        const result = this.db
+            .prepare(`UPDATE review_chains SET pending_redeliver_at = NULL, updated_at = ?
+         WHERE conversation_id = ?
+           AND pending_followup_at = ?
+           AND pending_followup IS NOT NULL
+           AND trim(pending_followup) != ''
+           AND ${StateStore.SQL_PENDING_IS_RECOVER}`)
+            .run(nowIso(), conversationId, expectedAt);
+        return result.changes > 0;
+    }
+    setChainPending(conversationId) {
+        this.withSessionChainWrite(conversationId, () => {
+            this.ensureReviewChain(conversationId);
+            this.db
+                .prepare(`UPDATE review_chains SET chain_pending = 1, updated_at = ?
+           WHERE conversation_id = ?
+             AND EXISTS (SELECT 1 FROM sessions WHERE conversation_id = ?)`)
+                .run(nowIso(), conversationId, conversationId);
+        });
+    }
+    savePendingFollowup(conversationId, message, opts) {
+        const msg = typeof message === "string" ? message.trim() : "";
+        // Blank or NUL-poisoned text must not become a redeliverable pending.
+        if (!msg || msg.includes("\0"))
+            return;
+        const armChain = opts?.armChain !== false;
+        this.withSessionChainWrite(conversationId, () => {
+            this.ensureReviewChain(conversationId);
+            // Recover claim/CAS ownership keys off pending_followup_at — keep unique.
+            const ts = nextFollowupTimestamp(this.getReviewChain(conversationId)?.pending_followup_at);
+            const sql = armChain
+                ? `UPDATE review_chains SET
+          pending_followup = ?, pending_followup_at = ?, pending_redeliver_at = NULL,
+          chain_pending = 1, updated_at = ?
+         WHERE conversation_id = ?
+           AND EXISTS (SELECT 1 FROM sessions WHERE conversation_id = ?)`
+                : `UPDATE review_chains SET
+          pending_followup = ?, pending_followup_at = ?, pending_redeliver_at = NULL,
+          updated_at = ?
+         WHERE conversation_id = ?
+           AND EXISTS (SELECT 1 FROM sessions WHERE conversation_id = ?)`;
+            this.db.prepare(sql).run(msg, ts, ts, conversationId, conversationId);
+        });
+    }
+    /**
+     * SQL: pending looks like a recover automation prompt.
+     * Keep in sync with `isRecoverFollowupMessage` prefixes.
+     */
+    static SQL_PENDING_IS_RECOVER = `(
+    trim(pending_followup) GLOB 'Recover:*'
+    OR trim(pending_followup) GLOB '恢复：*'
+    OR trim(pending_followup) GLOB '恢复:*'
+  )`;
+    /**
+     * SQL: pending kinds that must stay chain_pending=0 on redeliver.
+     * Matches recover/stuck (armChain=false), terminal done/review_complete, and
+     * E5/E0 Advance (intentionally disarmed — next product edit arms via
+     * afterFileEdit → code_edited). Re-arming Advance on host-drop redelivery
+     * would force phantom E3 after the tip is answered. Keep prefixes in sync
+     * with emit/updateReviewChain sites and kindFromPendingMessage.
+     */
+    static SQL_PENDING_REDELIVER_KEEP_DISARMED = `(
+    trim(pending_followup) GLOB 'Recover:*'
+    OR trim(pending_followup) GLOB '恢复：*'
+    OR trim(pending_followup) GLOB '恢复:*'
+    OR trim(pending_followup) GLOB 'Stuck:*'
+    OR trim(pending_followup) GLOB '卡住：*'
+    OR trim(pending_followup) GLOB '卡住:*'
+    OR trim(pending_followup) GLOB 'All checklist*'
+    OR trim(pending_followup) GLOB '全部完成*'
+    OR trim(pending_followup) GLOB 'Review complete*'
+    OR trim(pending_followup) GLOB '自审完成*'
+    OR trim(pending_followup) GLOB 'Advance*'
+    OR trim(pending_followup) GLOB '推进*'
+  )`;
+    /**
+     * SQL predicate: pending is absent or not a recover automation prompt.
+     * Keep in sync with `isRecoverFollowupMessage` prefixes.
+     */
+    static SQL_PENDING_NOT_RECOVER = `(
+    pending_followup IS NULL
+    OR (
+      trim(pending_followup) NOT GLOB 'Recover:*'
+      AND trim(pending_followup) NOT GLOB '恢复：*'
+      AND trim(pending_followup) NOT GLOB '恢复:*'
+    )
+  )`;
+    /**
+     * Atomic emit-ownership bump: succeeds only when `pending_followup_at` still
+     * equals `expectedAt` and pending is a recover prompt. Returns the new stamp,
+     * or null if the race was lost / row missing. Advances by ≥1ms when `nowIso()`
+     * collides with `expectedAt`.
+     */
+    casBumpPendingFollowupAt(conversationId, expectedAt) {
+        if (this.isInvalidConversationId(conversationId))
+            return null;
+        if (!expectedAt || expectedAt.includes("\0"))
+            return null;
+        const ts = nextFollowupTimestamp(expectedAt);
+        const result = this.db
+            .prepare(`UPDATE review_chains SET
+          pending_followup_at = ?, pending_redeliver_at = NULL, updated_at = ?
+         WHERE conversation_id = ?
+           AND pending_followup_at = ?
+           AND pending_followup IS NOT NULL
+           AND trim(pending_followup) != ''
+           AND ${StateStore.SQL_PENDING_IS_RECOVER}`)
+            .run(ts, ts, conversationId, expectedAt);
+        return result.changes > 0 ? ts : null;
+    }
+    clearPendingFollowup(conversationId) {
+        if (this.isInvalidConversationId(conversationId)) {
+            return;
+        }
+        this.db
+            .prepare(`UPDATE review_chains SET
+          pending_followup = NULL, pending_followup_at = NULL, pending_redeliver_at = NULL,
+          updated_at = ?
+         WHERE conversation_id = ?`)
+            .run(nowIso(), conversationId);
+    }
+    /**
+     * Atomically clear pending only when the live row still matches `pred`.
+     * Avoids read-then-clear TOCTOU: a concurrent stop may replace recover with
+     * fix/confirm between getReviewChain and clearPendingFollowup.
+     * Safe inside an open exclusiveWrite (runs inline; no nest).
+     */
+    clearPendingFollowupIf(conversationId, pred) {
+        if (this.isInvalidConversationId(conversationId)) {
+            return false;
+        }
+        if (typeof pred !== "function") {
+            return false;
+        }
+        const run = () => {
+            const pending = this.getReviewChain(conversationId)?.pending_followup?.trim() ?? "";
+            if (!pending) {
+                return false;
+            }
+            let matched = false;
+            try {
+                const raw = pred(pending);
+                // Refuse thenables — async preds must not clear under a write lock.
+                if (raw !== null &&
+                    typeof raw === "object" &&
+                    typeof raw.then === "function") {
+                    return false;
+                }
+                matched = Boolean(raw);
+            }
+            catch {
+                return false;
+            }
+            if (!matched) {
+                return false;
+            }
+            this.db
+                .prepare(`UPDATE review_chains SET
+            pending_followup = NULL, pending_followup_at = NULL, pending_redeliver_at = NULL,
+            updated_at = ?
+           WHERE conversation_id = ?`)
+                .run(nowIso(), conversationId);
+            return true;
+        };
+        if (this.writeDepth > 0) {
+            return run();
+        }
+        return this.exclusiveWrite(() => {
+            const ok = run();
+            return { commit: ok, value: ok };
+        });
+    }
+    /**
+     * Column-only: neutralize fix/confirm/pending re-entry without ensure/session.
+     * Used when pause-threshold upsert failed but the session is still armed — a
+     * later completed stop must not resume the review loop via code_edited/pending
+     * or loopCount>0→E3 (fix_round cleared so bare loopCount cannot re-arm).
+     */
+    neutralizeReviewChain(conversationId) {
+        if (this.isInvalidConversationId(conversationId)) {
+            return;
+        }
+        this.db
+            .prepare(`UPDATE review_chains SET
+          code_edited = 0,
+          confirm_left = NULL,
+          chain_pending = 0,
+          item_confirm_complete = 0,
+          fix_round = 0,
+          reviewing_item_id = NULL,
+          pending_followup = NULL,
+          pending_followup_at = NULL,
+          pending_redeliver_at = NULL,
+          updated_at = ?
+         WHERE conversation_id = ?`)
+            .run(nowIso(), conversationId);
+    }
+    /**
+     * Like {@link neutralizeReviewChain}, but refuse to wipe an in-flight recover
+     * pending (error-storm claimer). Returns true when a row was updated.
+     */
+    neutralizeReviewChainUnlessRecover(conversationId) {
+        if (this.isInvalidConversationId(conversationId)) {
+            return false;
+        }
+        const result = this.db
+            .prepare(`UPDATE review_chains SET
+          code_edited = 0,
+          confirm_left = NULL,
+          chain_pending = 0,
+          item_confirm_complete = 0,
+          fix_round = 0,
+          reviewing_item_id = NULL,
+          pending_followup = NULL,
+          pending_followup_at = NULL,
+          pending_redeliver_at = NULL,
+          updated_at = ?
+         WHERE conversation_id = ?
+           AND ${StateStore.SQL_PENDING_NOT_RECOVER}`)
+            .run(nowIso(), conversationId);
+        return result.changes > 0;
+    }
+    /**
+     * Ambient error-recover soft-reset columns + clear pending, but refuse when
+     * pending is already recover (unlocked compensate TOCTOU defense).
+     * Preserves `reviewing_item_id` so a premature checklist `[x]` cannot retarget
+     * after recover (unlike neutralize/reset, which intentionally clear sticky).
+     * Returns true when a row was updated.
+     */
+    softResetAmbientChainUnlessRecover(conversationId, fields) {
+        if (this.isInvalidConversationId(conversationId)) {
+            return false;
+        }
+        const result = this.db
+            .prepare(`UPDATE review_chains SET
+          confirm_left = ?,
+          item_confirm_complete = ?,
+          chain_pending = ?,
+          code_edited = ?,
+          pending_followup = NULL,
+          pending_followup_at = NULL,
+          pending_redeliver_at = NULL,
+          updated_at = ?
+         WHERE conversation_id = ?
+           AND EXISTS (SELECT 1 FROM sessions WHERE conversation_id = ?)
+           AND ${StateStore.SQL_PENDING_NOT_RECOVER}`)
+            .run(fields.confirm_left, fields.item_confirm_complete, fields.chain_pending, fields.code_edited, nowIso(), conversationId, conversationId);
+        return result.changes > 0;
+    }
+    /**
+     * Column-only pause/disarm when the full upsertSession pause write failed.
+     * Without this, loopCount>0 completed stops can still hit E3 while armed.
+     */
+    pauseSessionForRepeatedErrors(conversationId, errorCount, lastError) {
+        if (this.isInvalidConversationId(conversationId)) {
+            return;
+        }
+        const count = typeof errorCount === "number" && Number.isFinite(errorCount)
+            ? Math.max(0, Math.floor(errorCount))
+            : 0;
+        const err = typeof lastError === "string" && !lastError.includes("\0")
+            ? lastError
+            : null;
+        const ts = nowIso();
+        this.db
+            .prepare(`UPDATE sessions SET
+          armed = 0,
+          paused = 1,
+          paused_reason = 'repeated_errors',
+          error_count = ?,
+          last_error = ?,
+          last_active_at = ?,
+          updated_at = ?
+         WHERE conversation_id = ?`)
+            .run(count, err, ts, ts, conversationId);
+    }
+    /**
+     * Fallback halt when richer pause UPDATE threw/no-op'd.
+     * Always drops armed; ensures paused=1. Preserves an existing paused_reason
+     * (e.g. concurrent stuck/human_gate, or richer pause already wrote) via
+     * COALESCE — only fills repeated_errors when reason was null.
+     * Leaves error_count/last_error to the richer pause path.
+     */
+    disarmSession(conversationId) {
+        if (this.isInvalidConversationId(conversationId)) {
+            return;
+        }
+        this.db
+            .prepare(`UPDATE sessions SET
+          armed = 0,
+          paused = 1,
+          paused_reason = COALESCE(paused_reason, 'repeated_errors'),
+          updated_at = ?
+         WHERE conversation_id = ?`)
+            .run(nowIso(), conversationId);
+    }
+    touchPendingRedeliver(conversationId) {
+        this.withSessionChainWrite(conversationId, () => {
+            this.ensureReviewChain(conversationId);
+            const ts = nowIso();
+            // Require live pending — after neutralize/clear, must not resurrect
+            // chain_pending=1 (would E3 on RESUME with no undelivered message).
+            // Recover/stuck, terminal done/review_complete, and Advance must stay
+            // disarmed; arming them here would open a phantom confirm after the tip
+            // is answered.
+            this.db
+                .prepare(`UPDATE review_chains SET
+          pending_redeliver_at = ?,
+          chain_pending = CASE
+            WHEN ${StateStore.SQL_PENDING_REDELIVER_KEEP_DISARMED} THEN 0
+            ELSE 1
+          END,
+          updated_at = ?
+         WHERE conversation_id = ?
+           AND pending_followup IS NOT NULL
+           AND trim(pending_followup) != ''
+           AND EXISTS (SELECT 1 FROM sessions WHERE conversation_id = ?)`)
+                .run(ts, ts, conversationId, conversationId);
+        });
+    }
+    /**
+     * Run fn only when session exists. Uses exclusiveWrite when not already in one
+     * (serialize vs purge); if already nested in a write txn, runs inline — nesting
+     * exclusiveWrite would throw.
+     */
+    withSessionChainWrite(conversationId, fn) {
+        if (this.isInvalidConversationId(conversationId)) {
+            return;
+        }
+        const run = () => {
+            if (!this.getSession(conversationId))
+                return false;
+            fn();
+            return true;
+        };
+        if (this.writeDepth > 0) {
+            run();
+            return;
+        }
+        this.exclusiveWrite(() => {
+            const ok = run();
+            return { commit: ok, value: undefined };
+        });
+    }
+    findExecutingSession(excludeConversationId) {
+        return (this.db
+            .prepare(`SELECT * FROM sessions
+           WHERE phase = 'executing' AND armed = 1 AND paused = 0
+             AND conversation_id != ?
+           LIMIT 1`)
+            .get(excludeConversationId) ?? null);
+    }
+    /**
+     * Move session + review_chain rows from `fromId` → `toId` (PK rebind).
+     * Replaces disposable destinations (idle — incl. stale track_id — or done).
+     * Refuses planning or executing destinations (paused or armed).
+     */
+    rebindConversation(fromId, toId) {
+        if (this.isInvalidConversationId(fromId) ||
+            this.isInvalidConversationId(toId)) {
+            return { ok: false, reason: "invalid_id" };
+        }
+        if (fromId === toId) {
+            const self = this.getSession(toId);
+            if (!self)
+                return { ok: false, reason: "missing_source" };
+            return { ok: true, session: self };
+        }
+        if (this.writeDepth > 0) {
+            return this.rebindConversationInTxn(fromId, toId);
+        }
+        return this.exclusiveWrite(() => {
+            const result = this.rebindConversationInTxn(fromId, toId);
+            return { commit: result.ok, value: result };
+        });
+    }
+    isDisposableResumeDest(dest) {
+        // All idle (incl. ambient revive that kept a stale track_id) and done may be
+        // replaced. Never replace planning / executing.
+        return dest.phase === "done" || dest.phase === "idle";
+    }
+    rebindConversationInTxn(fromId, toId) {
+        const source = this.getSession(fromId);
+        if (!source) {
+            return { ok: false, reason: "missing_source" };
+        }
+        const dest = this.getSession(toId);
+        if (dest) {
+            if (!this.isDisposableResumeDest(dest)) {
+                return { ok: false, reason: "dest_busy" };
+            }
+            this.db
+                .prepare("DELETE FROM review_chains WHERE conversation_id = ?")
+                .run(toId);
+            this.db
+                .prepare("DELETE FROM sessions WHERE conversation_id = ?")
+                .run(toId);
+        }
+        const ts = nowIso();
+        this.db
+            .prepare(`UPDATE sessions SET conversation_id = ?, updated_at = ?, last_active_at = ?
+           WHERE conversation_id = ?`)
+            .run(toId, ts, ts, fromId);
+        this.db
+            .prepare(`UPDATE review_chains SET conversation_id = ?, updated_at = ?
+           WHERE conversation_id = ?`)
+            .run(toId, ts, fromId);
+        const moved = this.getSession(toId);
+        if (!moved) {
+            return { ok: false, reason: "missing_source" };
+        }
+        return { ok: true, session: moved };
+    }
+    /**
+     * Atomically pick a foreign session (by slug or unique executing) and rebind
+     * it onto `toId`. No-op (ok + current dest) when nothing to claim.
+     */
+    claimSessionInto(toId, opts) {
+        if (this.isInvalidConversationId(toId)) {
+            return { ok: false, userMessage: "Invalid conversation id." };
+        }
+        const slug = opts?.slug?.trim() || undefined;
+        if (slug && !isSafeTrackSlug(slug)) {
+            return {
+                ok: false,
+                userMessage: `Invalid track slug "${sanitizeSessionDisplayText(slug).slice(0, 64)}".`,
+            };
+        }
+        return this.exclusiveWrite(() => {
+            const dest = this.getSession(toId);
+            if (dest && !this.isDisposableResumeDest(dest)) {
+                return {
+                    commit: false,
+                    value: {
+                        ok: false,
+                        userMessage: `This conversation already has track "${sanitizeSessionDisplayText(dest.track_id)}" (${sanitizeSessionDisplayText(String(dest.phase))}). Claim from a new chat with /autopilot-resume <slug> — planning/executing here cannot be replaced (OFF only pauses).`,
+                    },
+                };
+            }
+            const others = this.listSessions().filter((s) => s.conversation_id !== toId);
+            // OFF only pauses — phase stays "executing". Prefer unpaused workers so
+            // "OFF extras, then retry" actually reduces ambiguity; fall back to a
+            // single paused executing (dead-chat recovery).
+            const pickExecuting = (pool) => {
+                const active = pool.filter((s) => s.phase === "executing" && s.paused === 0);
+                if (active.length > 1) {
+                    const allSame = active.every((s) => s.track_id === active[0].track_id);
+                    return {
+                        ok: false,
+                        userMessage: allSame
+                            ? `Multiple executing sessions for "${sanitizeSessionDisplayText(active[0].track_id)}". Send Autopilot OFF on extras, then retry.`
+                            : `Multiple executing sessions (${active
+                                .map((s) => sanitizeSessionDisplayText(s.track_id))
+                                .join(", ")}). Send Autopilot OFF on extras, then retry — or use /autopilot-resume <slug>.`,
+                    };
+                }
+                if (active.length === 1) {
+                    return { ok: true, session: active[0] };
+                }
+                const paused = pool.filter((s) => s.phase === "executing" && s.paused === 1);
+                if (paused.length > 1) {
+                    const allSame = paused.every((s) => s.track_id === paused[0].track_id);
+                    return {
+                        ok: false,
+                        userMessage: allSame
+                            ? `Multiple paused executing sessions for "${sanitizeSessionDisplayText(paused[0].track_id)}". Leave only one source, then retry.`
+                            : `Multiple paused executing sessions (${paused
+                                .map((s) => sanitizeSessionDisplayText(s.track_id))
+                                .join(", ")}). Use /autopilot-resume <slug>.`,
+                    };
+                }
+                return { ok: true, session: paused[0] ?? null };
+            };
+            let source = null;
+            if (slug) {
+                const hits = others.filter((s) => s.track_id === slug);
+                const picked = pickExecuting(hits);
+                if (!picked.ok) {
+                    return { commit: false, value: picked };
+                }
+                const preferred = picked.session ?? hits.find((s) => s.phase === "planning") ?? null;
+                if (!preferred) {
+                    const onlyDone = hits.some((s) => s.phase === "done");
+                    return {
+                        commit: false,
+                        value: {
+                            ok: false,
+                            userMessage: onlyDone
+                                ? `Track "${slug}" is already done. Use /autopilot-run ${slug} to start again.`
+                                : `No session found for track "${slug}".`,
+                        },
+                    };
+                }
+                source = preferred;
+            }
+            else {
+                const picked = pickExecuting(others);
+                if (!picked.ok) {
+                    return { commit: false, value: picked };
+                }
+                source = picked.session;
+            }
+            if (!source) {
+                return {
+                    commit: true,
+                    value: { ok: true, session: dest ?? null },
+                };
+            }
+            const rebound = this.rebindConversationInTxn(source.conversation_id, toId);
+            if (!rebound.ok) {
+                if (rebound.reason === "dest_busy") {
+                    return {
+                        commit: false,
+                        value: {
+                            ok: false,
+                            userMessage: "This conversation already has an active session. Claim from a new chat with /autopilot-resume <slug> — planning/executing here cannot be replaced (OFF only pauses).",
+                        },
+                    };
+                }
+                return {
+                    commit: false,
+                    value: {
+                        ok: false,
+                        userMessage: `Failed to claim session for track "${sanitizeSessionDisplayText(source.track_id)}".`,
+                    },
+                };
+            }
+            return {
+                commit: true,
+                value: { ok: true, session: rebound.session },
+            };
+        });
+    }
+    /**
+     * Serialize writers with BEGIN IMMEDIATE so check-then-act (e.g. one_executor)
+     * and multi-statement enters stay atomic. Callback chooses commit vs rollback.
+     */
+    exclusiveWrite(fn) {
+        if (this.writeDepth > 0) {
+            throw new Error("exclusiveWrite does not support nesting");
+        }
+        this.writeDepth += 1;
+        this.db.exec("BEGIN IMMEDIATE");
+        try {
+            const { commit, value } = fn();
+            this.db.exec(commit ? "COMMIT" : "ROLLBACK");
+            return value;
+        }
+        catch (err) {
+            try {
+                this.db.exec("ROLLBACK");
+            }
+            catch {
+                /* ignore rollback errors after primary failure */
+            }
+            throw err;
+        }
+        finally {
+            this.writeDepth -= 1;
+        }
+    }
+    static openMemory(projectRoot) {
+        return new StateStore(projectRoot, ":memory:");
+    }
+}
+export { getLatestSchemaVersion };
+//# sourceMappingURL=state-store.js.map