visionclaw 0.1.219-beta.0 → 0.1.219-dev.codex-issue-2805-worker-runtime.1

package/dist/threads/execution-store.js

@@ -0,0 +1,910 @@
+import { createHash, randomUUID } from "node:crypto";
+import fs from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import path from "node:path";
+import { z } from "zod";
+import { getSharedProfileDir } from "../config/index.js";
+import { logger } from "../logger.js";
+/**
+ * Host-side record of internal executions: task protocol v1 (#2805 step 1c).
+ *
+ * This is the execution host's authoritative ledger. The TUI request store
+ * separately correlates a localhost request with SSE output. Callers (General, the Lab adapter, Nightly)
+ * submit commands; the host owns state transitions; the worker only reports.
+ *
+ * Two local atomic boundaries, each one SQLite transaction:
+ *  1. A submit stores the command, the execution record and its schedulable
+ *     state together before `accepted` is returned.
+ *  2. A state change, its result or event, and the pending delivery to the
+ *     caller are stored together before the caller is notified.
+ *
+ * Delivery to the caller is at-least-once: an outbox row stays until the
+ * caller acknowledges that the event reached its own durable queue. Consumers
+ * deduplicate by `eventId`. The event `seq` is a transport cursor, distinct
+ * from the per-execution `revision` used for concurrency control.
+ */
+export const EXECUTION_PROTOCOL_VERSION = 1;
+export const EXECUTION_STATES = [
+    "queued", "running", "waiting_input", "cancel_requested",
+    "succeeded", "failed", "cancelled",
+];
+const TERMINAL_STATES = new Set(["succeeded", "failed", "cancelled"]);
+export function isTerminalExecutionState(state) {
+    return TERMINAL_STATES.has(state);
+}
+/** A caller's internal recipient; never an arbitrary callback URL. */
+export const ExecutionCallerSchema = z.object({
+    kind: z.enum(["general", "lab", "nightly", "tui"]),
+    /** Recipient reference inside that caller, e.g. a TUI requestId or thread id. */
+    ref: z.string().min(1).max(200),
+}).strict();
+export const CheckpointSchema = z.object({
+    done: z.array(z.string()).default([]),
+    remaining: z.array(z.string()).default([]),
+    decisions: z.array(z.string()).default([]),
+    blockers: z.array(z.string()).default([]),
+    artifactRefs: z.array(z.string()).default([]),
+    /** Operations whose outcome is unknown; verify before replaying any of them. */
+    uncertainOperations: z.array(z.string()).default([]),
+}).strict();
+export const SubmitPayloadSchema = z.object({
+    goal: z.string().min(1).max(20_000),
+    requirements: z.array(z.string().max(4_000)).max(64).default([]),
+    expectedOutput: z.string().max(4_000).optional(),
+    contextSummary: z.string().max(20_000).optional(),
+    inputRefs: z.array(z.string().max(512)).max(64).default([]),
+    checkpoint: CheckpointSchema.optional(),
+    /** Short owner-facing title, used only by the caller's delivery fallback. */
+    title: z.string().max(200).optional(),
+    /** Accounting carried over from a foreground attempt; never reset by a handoff. */
+    foregroundToolCallsUsed: z.number().int().nonnegative().default(0),
+    workspaceRef: z.string().max(1_024).optional(),
+    workspaceMode: z.enum(["read_only", "shared", "isolated"]).optional(),
+    /** Parent Task for shared scheduling; supplied by the trusted task service. */
+    parentTaskId: z.string().max(200).optional(),
+    preparedWorkspace: z.boolean().optional(),
+    /** Host-admitted workspace reads; has no authority for non-General callers. */
+    businessRead: z.boolean().optional(),
+    priorExecutionId: z.string().max(200).optional(),
+    /** Host-only retry identity: replaying the same chat message cannot retry twice. */
+    retryDispatchId: z.string().max(64).optional(),
+    retrySpecification: z.string().max(64).optional(),
+}).strict();
+export const EXECUTION_EVENT_TYPES = [
+    "accepted", "started", "progress", "question", "input_applied", "result", "stopped",
+];
+export class ExecutionCommandConflictError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ExecutionCommandConflictError";
+    }
+}
+export function executionStorePath() {
+    return path.join(getSharedProfileDir(), "executions.db");
+}
+function callerKey(caller, scope) {
+    return `${scope}\u0000${caller.kind}\u0000${caller.ref}`;
+}
+function stableStringify(value) {
+    if (Array.isArray(value))
+        return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+    if (value && typeof value === "object") {
+        return `{${Object.entries(value)
+            .filter(([, item]) => item !== undefined)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, item]) => `${JSON.stringify(key)}:${stableStringify(item)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+/** Digest of authenticated ownership, command type, target and normalized content. */
+function commandDigest(envelope, type, target, content) {
+    return createHash("sha256").update(stableStringify({
+        scope: envelope.scope, caller: envelope.caller, type, target, content,
+    })).digest("hex");
+}
+/**
+ * Results quote memory and conversation until they are redacted, so the
+ * database is owner-only. SQLite gives the WAL and shm files the database
+ * file's mode; files left by an older version are tightened here too.
+ */
+function restrictToOwner(dbPath) {
+    fs.closeSync(fs.openSync(dbPath, "a", 0o600));
+    for (const file of [dbPath, `${dbPath}-wal`, `${dbPath}-shm`]) {
+        try {
+            fs.chmodSync(file, 0o600);
+        }
+        catch (error) {
+            // Not fatal: the store still works, only less private.
+            if (error.code !== "ENOENT")
+                logger.warn(`[execution] Could not restrict ${path.basename(file)} to its owner`);
+        }
+    }
+}
+export class ExecutionStore {
+    now;
+    transactionDepth = 0;
+    db;
+    statements;
+    closed = false;
+    eventListeners = new Set();
+    /** Events appended inside the open transaction; published only after COMMIT. */
+    uncommittedEvents = [];
+    constructor(dbPath = executionStorePath(), now = () => new Date()) {
+        this.now = now;
+        // The supervisor can start before anything else has created the profile directory.
+        fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+        if (dbPath !== ":memory:")
+            restrictToOwner(dbPath);
+        this.db = new DatabaseSync(dbPath);
+        this.db.exec("PRAGMA journal_mode = WAL");
+        // Redacted results (see redactResultContent) must not linger in free pages.
+        this.db.exec("PRAGMA secure_delete = ON");
+        this.db.exec("PRAGMA busy_timeout = 5000");
+        this.db.exec("PRAGMA foreign_keys = ON");
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS executions (
+        execution_id TEXT PRIMARY KEY,
+        task_id TEXT NOT NULL,
+        scope TEXT NOT NULL,
+        caller TEXT NOT NULL,
+        state TEXT NOT NULL,
+        revision INTEGER NOT NULL,
+        input_seq INTEGER NOT NULL DEFAULT 0,
+        processed_input_seq INTEGER NOT NULL DEFAULT 0,
+        worker_instance_id INTEGER NOT NULL DEFAULT 0,
+        auto_resume_count INTEGER NOT NULL DEFAULT 0,
+        payload TEXT NOT NULL,
+        snapshot TEXT NOT NULL,
+        open_question_id TEXT,
+        result TEXT,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        queued_at TEXT NOT NULL,
+        started_at TEXT,
+        cancel_requested_at TEXT,
+        stopped_at TEXT
+      );
+      CREATE INDEX IF NOT EXISTS executions_task_idx ON executions(task_id, created_at);
+      CREATE INDEX IF NOT EXISTS executions_state_idx ON executions(state, queued_at);
+      CREATE TABLE IF NOT EXISTS execution_commands (
+        caller_key TEXT NOT NULL,
+        command_id TEXT NOT NULL,
+        digest TEXT NOT NULL,
+        response TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        PRIMARY KEY (caller_key, command_id)
+      );
+      CREATE TABLE IF NOT EXISTS execution_inputs (
+        execution_id TEXT NOT NULL REFERENCES executions(execution_id),
+        input_seq INTEGER NOT NULL,
+        command_id TEXT NOT NULL,
+        question_id TEXT,
+        text TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        PRIMARY KEY (execution_id, input_seq)
+      );
+      CREATE TABLE IF NOT EXISTS execution_events (
+        seq INTEGER PRIMARY KEY AUTOINCREMENT,
+        event_id TEXT NOT NULL UNIQUE,
+        task_id TEXT NOT NULL,
+        execution_id TEXT NOT NULL REFERENCES executions(execution_id),
+        type TEXT NOT NULL,
+        command_id TEXT,
+        created_at TEXT NOT NULL,
+        payload TEXT NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS execution_events_execution_idx ON execution_events(execution_id, seq);
+      CREATE TABLE IF NOT EXISTS execution_outbox (
+        event_id TEXT PRIMARY KEY REFERENCES execution_events(event_id),
+        caller TEXT NOT NULL,
+        attempts INTEGER NOT NULL DEFAULT 0,
+        next_attempt_at TEXT NOT NULL,
+        created_at TEXT NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS execution_tool_calls (
+        execution_id TEXT NOT NULL REFERENCES executions(execution_id),
+        call_id TEXT NOT NULL,
+        tool_name TEXT NOT NULL,
+        started_at TEXT NOT NULL,
+        finished_at TEXT,
+        PRIMARY KEY (execution_id, call_id)
+      );
+      CREATE TABLE IF NOT EXISTS execution_processes (
+        execution_id TEXT PRIMARY KEY REFERENCES executions(execution_id),
+        pid INTEGER NOT NULL,
+        process_start TEXT NOT NULL,
+        worker_instance_id INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS execution_usage (
+        execution_id TEXT PRIMARY KEY REFERENCES executions(execution_id),
+        usage TEXT NOT NULL
+      );
+    `);
+        const prepare = (sql) => this.db.prepare(sql);
+        this.statements = {
+            getExecution: prepare("SELECT * FROM executions WHERE execution_id = ?"),
+            activeForTask: prepare(`SELECT * FROM executions WHERE task_id = ? AND scope = ?
+        AND state IN ('queued','running','waiting_input','cancel_requested') ORDER BY created_at LIMIT 1`),
+            latestForTask: prepare("SELECT * FROM executions WHERE task_id = ? AND scope = ? ORDER BY created_at DESC, rowid DESC LIMIT 1"),
+            byState: prepare("SELECT * FROM executions WHERE state = ? ORDER BY queued_at, rowid"),
+            insertExecution: prepare(`INSERT INTO executions (
+        execution_id, task_id, scope, caller, state, revision, payload, snapshot,
+        created_at, updated_at, queued_at
+      ) VALUES (?, ?, ?, ?, 'queued', 1, ?, ?, ?, ?, ?)`),
+            getCommand: prepare("SELECT * FROM execution_commands WHERE caller_key = ? AND command_id = ?"),
+            insertCommand: prepare(`INSERT INTO execution_commands (caller_key, command_id, digest, response, created_at)
+        VALUES (?, ?, ?, ?, ?)`),
+            insertInput: prepare(`INSERT INTO execution_inputs (execution_id, input_seq, command_id, question_id, text, created_at)
+        VALUES (?, ?, ?, ?, ?, ?)`),
+            inputsAfter: prepare("SELECT * FROM execution_inputs WHERE execution_id = ? AND input_seq > ? ORDER BY input_seq"),
+            insertEvent: prepare(`INSERT INTO execution_events (event_id, task_id, execution_id, type, command_id, created_at, payload)
+        VALUES (?, ?, ?, ?, ?, ?, ?)`),
+            getEventBySeq: prepare("SELECT * FROM execution_events WHERE seq = ?"),
+            resultEvents: prepare("SELECT event_id, payload FROM execution_events WHERE execution_id = ? AND type = 'result'"),
+            setEventPayload: prepare("UPDATE execution_events SET payload = ? WHERE event_id = ?"),
+            eventsAfter: prepare("SELECT * FROM execution_events WHERE execution_id = ? AND seq > ? ORDER BY seq LIMIT 500"),
+            insertOutbox: prepare(`INSERT INTO execution_outbox (event_id, caller, next_attempt_at, created_at) VALUES (?, ?, ?, ?)`),
+            dueOutbox: prepare(`SELECT e.*, o.caller AS outbox_caller, o.attempts AS outbox_attempts FROM execution_outbox o
+        JOIN execution_events e ON e.event_id = o.event_id WHERE o.next_attempt_at <= ? ORDER BY e.seq LIMIT ?`),
+            ackOutbox: prepare("DELETE FROM execution_outbox WHERE event_id = ?"),
+            deferOutbox: prepare("UPDATE execution_outbox SET attempts = attempts + 1, next_attempt_at = ? WHERE event_id = ?"),
+            rescheduleOutbox: prepare("UPDATE execution_outbox SET next_attempt_at = ?"),
+            toolStarted: prepare(`INSERT OR IGNORE INTO execution_tool_calls (execution_id, call_id, tool_name, started_at) VALUES (?, ?, ?, ?)`),
+            toolFinished: prepare("UPDATE execution_tool_calls SET finished_at = ? WHERE execution_id = ? AND call_id = ? AND finished_at IS NULL"),
+            unfinishedTools: prepare("SELECT tool_name, call_id FROM execution_tool_calls WHERE execution_id = ? AND finished_at IS NULL ORDER BY started_at"),
+            upsertProcess: prepare(`INSERT INTO execution_processes (execution_id, pid, process_start, worker_instance_id) VALUES (?, ?, ?, ?)
+        ON CONFLICT(execution_id) DO UPDATE SET pid = excluded.pid, process_start = excluded.process_start, worker_instance_id = excluded.worker_instance_id`),
+            getProcess: prepare("SELECT * FROM execution_processes WHERE execution_id = ?"),
+            clearProcess: prepare("DELETE FROM execution_processes WHERE execution_id = ?"),
+            taskOwner: prepare("SELECT scope, caller FROM executions WHERE task_id = ? ORDER BY created_at, rowid LIMIT 1"),
+            liveWriter: prepare(`SELECT 1 AS found FROM executions e
+        WHERE json_extract(e.payload, '$.workspaceRef') = ? AND e.execution_id != ?
+          AND (? = 0 OR COALESCE(json_extract(e.payload, '$.workspaceMode'), 'shared') != 'read_only')
+          AND (e.state IN ('running','cancel_requested')
+            OR EXISTS (SELECT 1 FROM execution_processes p WHERE p.execution_id = e.execution_id))
+        LIMIT 1`),
+            getUsage: prepare("SELECT usage FROM execution_usage WHERE execution_id = ?"),
+            liveExecutions: prepare("SELECT e.* FROM executions e JOIN execution_processes p ON p.execution_id = e.execution_id"),
+            attemptsForTask: prepare("SELECT * FROM executions WHERE task_id = ? AND scope = ? ORDER BY created_at, rowid"),
+            putUsage: prepare(`INSERT INTO execution_usage (execution_id, usage) VALUES (?, ?)
+        ON CONFLICT(execution_id) DO UPDATE SET usage = excluded.usage`),
+        };
+    }
+    // ------------------------------------------------------------- commands
+    /**
+     * Accept a submit. A replay of the same commandId and content returns the
+     * original acceptance; the same key with other content is a conflict.
+     * A task that already has a live attempt is never given a second one.
+     */
+    submit(envelope, input) {
+        const payload = SubmitPayloadSchema.parse(input.payload);
+        return this.command(envelope, "submit", { taskId: input.taskId ?? null, retryOf: input.retryOf ?? null }, payload, () => {
+            const taskId = input.taskId ?? `task-${randomUUID()}`;
+            if (input.taskId && !this.ownsTask(input.taskId, envelope)) {
+                // A taskId belongs to the caller that first used it; nobody else may
+                // attach an attempt to it, even inside the same scope.
+                return { kind: "stale", reason: "task_not_owned", record: null };
+            }
+            const live = this.row(this.statements.activeForTask.get(taskId, envelope.scope));
+            if (live) {
+                return { kind: "stale", reason: "task_has_live_execution", record: this.toRecord(live) };
+            }
+            if (input.retryOf) {
+                const previous = this.row(this.statements.getExecution.get(input.retryOf));
+                if (previous?.task_id !== taskId || previous.scope !== envelope.scope) {
+                    return { kind: "stale", reason: "retry_target_not_found", record: null };
+                }
+                if (!isTerminalExecutionState(previous.state)) {
+                    return { kind: "stale", reason: "retry_target_not_terminal", record: this.toRecord(previous) };
+                }
+            }
+            const executionId = input.executionId ?? `exec-${randomUUID()}`;
+            const at = this.timestamp();
+            this.statements.insertExecution.run(executionId, taskId, envelope.scope, JSON.stringify(envelope.caller), JSON.stringify(payload), input.snapshot, at, at, at);
+            let revision = 1;
+            if (input.retryOf) {
+                const previousInputs = this.pendingInputs(input.retryOf, 0);
+                for (const accepted of previousInputs)
+                    this.statements.insertInput.run(executionId, accepted.inputSeq, accepted.commandId, accepted.questionId, accepted.text, accepted.createdAt);
+                const last = previousInputs.at(-1);
+                if (last)
+                    revision = this.update(this.mustGetRow(executionId), { input_seq: last.inputSeq });
+            }
+            this.appendEvent(executionId, "accepted", envelope.commandId, { state: "queued", revision });
+            const value = { accepted: true, taskId, executionId, state: "queued", revision };
+            return { kind: "ok", replay: false, value };
+        });
+    }
+    /**
+     * Record an execution the host admits and starts in one step (#2805 1d):
+     * a LabRun keeps its own Fin-App lease and capacity contract, so it never
+     * sits in this queue. Idempotent on `executionId`; a second admission of the
+     * same id returns the existing record instead of creating a new attempt.
+     */
+    admitAndStart(input) {
+        const payload = SubmitPayloadSchema.parse(input.payload);
+        ExecutionCallerSchema.parse(input.caller);
+        return this.transaction(() => {
+            const existing = this.row(this.statements.getExecution.get(input.executionId));
+            if (existing) {
+                if (existing.state === "queued") {
+                    const generation = existing.worker_instance_id + 1;
+                    this.update(existing, { state: "running", worker_instance_id: generation, started_at: existing.started_at ?? this.timestamp() });
+                    this.statements.upsertProcess.run(input.executionId, input.process.pid, input.process.processStart, generation);
+                    this.appendEvent(input.executionId, "started", null, { workerInstanceId: generation });
+                }
+                return this.mustGet(input.executionId);
+            }
+            const at = this.timestamp();
+            this.statements.insertExecution.run(input.executionId, input.taskId, input.scope, JSON.stringify(input.caller), JSON.stringify(payload), input.snapshot, at, at, at);
+            this.appendEvent(input.executionId, "accepted", null, { state: "queued", revision: 1 });
+            this.update(this.mustGetRow(input.executionId), { state: "running", worker_instance_id: 1, started_at: at });
+            this.statements.upsertProcess.run(input.executionId, input.process.pid, input.process.processStart, 1);
+            this.appendEvent(input.executionId, "started", null, { workerInstanceId: 1 });
+            return this.mustGet(input.executionId);
+        });
+    }
+    /**
+     * Host-initiated cancel for an execution whose caller is an external
+     * protocol (Fin-App cancel, lease loss). Same state rules as `cancel`.
+     */
+    requestHostCancel(executionId, reason) {
+        return this.transaction(() => {
+            const row = this.row(this.statements.getExecution.get(executionId));
+            if (!row || isTerminalExecutionState(row.state) || row.state === "cancel_requested") {
+                return row ? this.toRecord(row) : null;
+            }
+            this.update(row, { state: "cancel_requested", cancel_requested_at: this.timestamp() });
+            this.appendEvent(executionId, "progress", null, { cancelRequested: true, reason: reason.slice(0, 500) });
+            return this.mustGet(executionId);
+        });
+    }
+    /** Store supplementary input. The worker reads it at its next injection boundary. */
+    sendInput(envelope, input) {
+        return this.command(envelope, "send_input", { executionId: input.executionId }, {
+            text: input.text, questionId: input.questionId ?? null,
+        }, () => {
+            const row = this.owned(input.executionId, envelope);
+            if (!row)
+                return { kind: "stale", reason: "execution_not_found", record: null };
+            if (isTerminalExecutionState(row.state) || row.state === "cancel_requested") {
+                return { kind: "stale", reason: "execution_not_accepting_input", record: this.toRecord(row) };
+            }
+            if (row.result !== null) {
+                // The result is committed and waits only for its executor to stop.
+                // New input cannot be applied to it; the caller decides what follows.
+                return { kind: "stale", reason: "result_pending_stop", record: this.toRecord(row) };
+            }
+            if (input.questionId !== undefined && input.questionId !== row.open_question_id) {
+                return { kind: "stale", reason: "question_not_open", record: this.toRecord(row) };
+            }
+            const inputSeq = row.input_seq + 1;
+            const at = this.timestamp();
+            this.statements.insertInput.run(row.execution_id, inputSeq, envelope.commandId, input.questionId ?? null, input.text, at);
+            const answering = input.questionId !== undefined;
+            // The answered execution resumes in a new executor. While the one that
+            // asked is still stopping, it stays waiting_input with the question
+            // closed; confirmStopped() queues it once that executor is gone.
+            const next = answering && !this.processOf(row.execution_id) ? "queued" : row.state;
+            const revision = this.update(row, {
+                input_seq: inputSeq,
+                ...(answering ? { open_question_id: null } : {}),
+                ...(next === "queued" ? { state: next, queued_at: at } : {}),
+            });
+            return { kind: "ok", replay: false, value: { inputSeq, state: next, revision } };
+        });
+    }
+    /**
+     * Record a cancel request. A queued execution has no executor yet and is
+     * cancelled immediately; anything running enters `cancel_requested` and only
+     * becomes `cancelled` once the host confirms the executor stopped.
+     */
+    cancel(envelope, input) {
+        return this.command(envelope, "cancel", { executionId: input.executionId }, {
+            reason: input.reason ?? null, userInitiated: input.userInitiated === true,
+        }, () => {
+            const row = this.owned(input.executionId, envelope);
+            if (!row)
+                return { kind: "stale", reason: "execution_not_found", record: null };
+            if (isTerminalExecutionState(row.state) || row.state === "cancel_requested") {
+                return { kind: "ok", replay: false, value: { state: row.state, revision: row.revision } };
+            }
+            const at = this.timestamp();
+            if (row.state === "queued" || (row.state === "waiting_input" && !this.processOf(row.execution_id))) {
+                const result = {
+                    status: "cancelled", processedInputSeq: row.processed_input_seq,
+                    ...(input.reason ? { error: { code: "cancelled", message: input.reason } } : {}),
+                };
+                const revision = this.update(row, { state: "cancelled", cancel_requested_at: at, result: JSON.stringify(result) });
+                this.appendEvent(row.execution_id, "result", envelope.commandId, {
+                    ...result, userInitiated: input.userInitiated === true,
+                }, true);
+                return { kind: "ok", replay: false, value: { state: "cancelled", revision } };
+            }
+            const revision = this.update(row, { state: "cancel_requested", cancel_requested_at: at });
+            return { kind: "ok", replay: false, value: { state: "cancel_requested", revision } };
+        });
+    }
+    // ------------------------------------------------------ host transitions
+    get(executionId) {
+        const row = this.row(this.statements.getExecution.get(executionId));
+        return row ? this.toRecord(row) : null;
+    }
+    latestForTask(taskId, scope) {
+        const row = this.row(this.statements.latestForTask.get(taskId, scope));
+        return row ? this.toRecord(row) : null;
+    }
+    listByState(state) {
+        return this.statements.byState.all(state).map((row) => this.toRecord(row));
+    }
+    liveExecutions() {
+        return this.statements.liveExecutions.all().map((row) => this.toRecord(row));
+    }
+    attemptsForTask(taskId, scope) {
+        return this.statements.attemptsForTask.all(taskId, scope).map((row) => this.toRecord(row));
+    }
+    /** Atomic, synchronous admission of a set of Tasks. Events publish after commit. */
+    atomic(operation) {
+        return this.transaction(operation);
+    }
+    /**
+     * The host admitted the execution onto an executor. Never emits `started`
+     * from the queue; returns the new writer generation the worker must present.
+     */
+    markStarted(executionId, process) {
+        return this.transaction(() => {
+            const row = this.row(this.statements.getExecution.get(executionId));
+            if (row?.state !== "queued")
+                return null;
+            const generation = row.worker_instance_id + 1;
+            const at = this.timestamp();
+            this.update(row, { state: "running", worker_instance_id: generation, started_at: row.started_at ?? at });
+            this.statements.upsertProcess.run(executionId, process.pid, process.processStart, generation);
+            this.appendEvent(executionId, "started", null, { workerInstanceId: generation });
+            return this.get(executionId);
+        });
+    }
+    /** Record that the worker handed inputs up to `inputSeq` to its model context. */
+    markInputApplied(executionId, generation, inputSeq) {
+        return this.transaction(() => {
+            const row = this.current(executionId, generation);
+            if (!row || inputSeq <= row.processed_input_seq || inputSeq > row.input_seq)
+                return false;
+            this.update(row, { processed_input_seq: inputSeq });
+            this.appendEvent(executionId, "input_applied", null, { inputSeq });
+            return true;
+        });
+    }
+    pendingInputs(executionId, afterSeq) {
+        return this.statements.inputsAfter.all(executionId, afterSeq).map((row) => ({
+            executionId: row.execution_id, inputSeq: row.input_seq, commandId: row.command_id,
+            questionId: row.question_id, text: row.text, createdAt: row.created_at,
+        }));
+    }
+    recordProgress(executionId, generation, payload) {
+        return this.transaction(() => {
+            const row = this.current(executionId, generation);
+            if (row?.state !== "running")
+                return false;
+            this.appendEvent(executionId, "progress", null, payload, true);
+            return true;
+        });
+    }
+    /** The worker needs an answer. The question is durable; the executor may be released. */
+    askQuestion(executionId, generation, question) {
+        return this.transaction(() => {
+            const row = this.current(executionId, generation);
+            if (row?.state !== "running")
+                return null;
+            const questionId = `q-${randomUUID()}`;
+            this.update(row, { state: "waiting_input", open_question_id: questionId });
+            this.appendEvent(executionId, "question", null, { questionId, ...question }, true);
+            return questionId;
+        });
+    }
+    /**
+     * Commit a worker-reported terminal result. The result applies only if the
+     * reporter is the current generation and has processed every accepted
+     * input; a late report after a committed cancel request becomes `cancelled`
+     * while its artifacts are still recorded.
+     */
+    completeExecution(executionId, generation, report) {
+        return this.transaction(() => {
+            const row = this.row(this.statements.getExecution.get(executionId));
+            if (!row || isTerminalExecutionState(row.state))
+                return { rejected: "terminal" };
+            if (row.worker_instance_id !== generation)
+                return { rejected: "stale_writer" };
+            // A waiting (released) executor has nothing left to finish.
+            if (row.state !== "running" && row.state !== "cancel_requested")
+                return { rejected: "not_running" };
+            if (row.state !== "cancel_requested" && report.processedInputSeq < row.input_seq) {
+                return { rejected: "unprocessed_input", pendingInputSeq: row.input_seq };
+            }
+            const status = row.state === "cancel_requested" ? "cancelled" : report.status;
+            const result = { ...report, status };
+            // A terminal result needs a stopped executor before it is published; the
+            // host confirms that separately via confirmStopped().
+            this.update(row, { result: JSON.stringify(result) });
+            return { committed: row.state };
+        });
+    }
+    /**
+     * The host verified that the executor for this generation is stopped:
+     * its process exited or was killed and reaped. Only now may the record go
+     * terminal and the next writer be admitted.
+     */
+    confirmStopped(executionId, generation, fallback) {
+        return this.transaction(() => {
+            const row = this.row(this.statements.getExecution.get(executionId));
+            if (row?.worker_instance_id !== generation || isTerminalExecutionState(row.state))
+                return null;
+            // Already requeued for its next executor: a late confirmation changes nothing.
+            if (row.state === "queued")
+                return null;
+            const at = this.timestamp();
+            this.statements.clearProcess.run(executionId);
+            if (row.state === "waiting_input") {
+                // Released executor. An open question waits for its answer; an answer
+                // that arrived while this executor was stopping resumes it now.
+                const answered = row.open_question_id === null;
+                this.update(row, {
+                    stopped_at: at,
+                    ...(answered ? { state: "queued", queued_at: at } : {}),
+                });
+                this.appendEvent(executionId, "stopped", null, { workerInstanceId: generation, reason: "waiting_input" });
+                return this.get(executionId);
+            }
+            const reported = row.result ? JSON.parse(row.result) : null;
+            const result = this.withUsage(executionId, row.state === "cancel_requested"
+                ? { ...(reported ?? {}), status: "cancelled", processedInputSeq: reported?.processedInputSeq ?? row.processed_input_seq }
+                : reported ?? { status: fallback.status, error: fallback.error, processedInputSeq: row.processed_input_seq });
+            this.update(row, { state: result.status, result: JSON.stringify(result), stopped_at: at });
+            this.appendEvent(executionId, "stopped", null, { workerInstanceId: generation });
+            this.appendEvent(executionId, "result", null, { ...result }, true);
+            return this.get(executionId);
+        });
+    }
+    /**
+     * Drop a terminal execution's report content once its caller has applied
+     * it: `data`, `summary`, and error messages (codes stay). Used for
+     * maintenance executions, whose reports quote memory and conversation.
+     * Status, usage and every state transition are unchanged.
+     */
+    redactResultContent(executionId) {
+        const redact = (value) => {
+            const { data: _data, summary: _summary, error, ...rest } = value;
+            const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
+            return { ...rest, ...(typeof code === "string" ? { error: { code, message: "" } } : {}), redacted: true };
+        };
+        const redacted = this.transaction(() => {
+            const row = this.row(this.statements.getExecution.get(executionId));
+            if (!row || !isTerminalExecutionState(row.state) || !row.result)
+                return false;
+            this.update(row, { result: JSON.stringify(redact(JSON.parse(row.result))) });
+            for (const event of this.statements.resultEvents.all(executionId)) {
+                this.statements.setEventPayload.run(JSON.stringify(redact(JSON.parse(event.payload))), event.event_id);
+            }
+            return true;
+        });
+        // secure_delete does not reach the WAL: the frames that held the report
+        // stay in executions.db-wal until a checkpoint truncates it.
+        if (redacted)
+            this.truncateWal(executionId);
+        return redacted;
+    }
+    truncateWal(executionId) {
+        const outcome = this.db.prepare("PRAGMA wal_checkpoint(TRUNCATE)").get();
+        if (outcome?.busy) {
+            logger.warn(`[execution] WAL still holds redacted content of execution=${executionId}; a reader blocked the checkpoint`);
+        }
+    }
+    /**
+     * Put an interrupted running execution back in the queue under the same
+     * executionId. After `maxResumes` interruptions it fails instead, with the
+     * last interruption's cause in the error. A host restart is an
+     * interruption too (#2805: fail after 3 consecutive interruptions).
+     */
+    requeueForResume(executionId, generation, maxResumes, lastError) {
+        return this.transaction(() => {
+            const row = this.row(this.statements.getExecution.get(executionId));
+            if (row?.worker_instance_id !== generation || row.state !== "running")
+                return null;
+            this.statements.clearProcess.run(executionId);
+            if (row.auto_resume_count >= maxResumes) {
+                const detail = lastError ? `; last: ${lastError.slice(0, 300)}` : "";
+                const result = this.withUsage(executionId, {
+                    status: "failed", processedInputSeq: row.processed_input_seq,
+                    error: { code: "interrupted", message: `Execution was interrupted ${row.auto_resume_count + 1} times${detail}` },
+                    ...(row.result ? { checkpoint: JSON.parse(row.result).checkpoint } : {}),
+                });
+                this.update(row, { state: "failed", result: JSON.stringify(result), stopped_at: this.timestamp() });
+                this.appendEvent(executionId, "stopped", null, { workerInstanceId: generation });
+                this.appendEvent(executionId, "result", null, { ...result }, true);
+                return this.get(executionId);
+            }
+            this.update(row, { state: "queued", auto_resume_count: row.auto_resume_count + 1, queued_at: this.timestamp() });
+            this.appendEvent(executionId, "stopped", null, { workerInstanceId: generation, reason: "resume" });
+            return this.get(executionId);
+        });
+    }
+    /**
+     * Fail an execution whose executor can never succeed, e.g. it was refused
+     * at startup. Retrying would only fail the same way again.
+     */
+    failPermanently(executionId, generation, error) {
+        return this.transaction(() => {
+            const row = this.row(this.statements.getExecution.get(executionId));
+            if (row?.worker_instance_id !== generation || isTerminalExecutionState(row.state))
+                return null;
+            const hadExecutor = this.processOf(executionId) !== null;
+            this.statements.clearProcess.run(executionId);
+            const status = row.state === "cancel_requested" ? "cancelled" : "failed";
+            const result = this.withUsage(executionId, { status, error, processedInputSeq: row.processed_input_seq });
+            this.update(row, { state: status, result: JSON.stringify(result), stopped_at: this.timestamp() });
+            if (hadExecutor)
+                this.appendEvent(executionId, "stopped", null, { workerInstanceId: generation });
+            this.appendEvent(executionId, "result", null, { ...result }, true);
+            return this.get(executionId);
+        });
+    }
+    /** A waiting execution was answered and requeued; resume with the next generation. */
+    processOf(executionId) {
+        const row = this.statements.getProcess.get(executionId);
+        return row ? { pid: row.pid, processStart: row.process_start, workerInstanceId: row.worker_instance_id } : null;
+    }
+    // ----------------------------------------------------------- usage ledger
+    /**
+     * Accumulated task budget usage, held by the host (#2805 1b). The worker
+     * reports it over IPC; a task cannot reset it by editing local files.
+     */
+    usageOf(executionId) {
+        const row = this.statements.getUsage.get(executionId);
+        return row ? JSON.parse(row.usage) : null;
+    }
+    /**
+     * Merge a worker's usage report. Counters only grow: a report lower than
+     * what the host already holds (a reset local file, a replayed old report)
+     * cannot give the task its budget back.
+     */
+    recordUsage(executionId, generation, usage) {
+        return this.transaction(() => {
+            if (!this.current(executionId, generation))
+                return false;
+            const previous = this.usageOf(executionId) ?? {};
+            const merged = { ...previous };
+            for (const [key, value] of Object.entries(usage)) {
+                const before = previous[key];
+                if (typeof value === "number" && typeof before === "number")
+                    merged[key] = Math.max(before, value);
+                else if (before === undefined || before === null)
+                    merged[key] = value;
+            }
+            this.statements.putUsage.run(executionId, JSON.stringify(merged));
+            return true;
+        });
+    }
+    /** A host-side fact the caller must see, e.g. an executor that cannot be proven stopped. */
+    recordHostNotice(executionId, payload) {
+        return this.transaction(() => {
+            const row = this.row(this.statements.getExecution.get(executionId));
+            if (!row || isTerminalExecutionState(row.state))
+                return false;
+            this.appendEvent(executionId, "progress", null, { ...payload, host: true }, true);
+            return true;
+        });
+    }
+    /**
+     * Whether another execution may still write to `workspaceRef`: it is
+     * running or stopping, or its executor has not been confirmed stopped.
+     */
+    hasLiveWriter(workspaceRef, exceptExecutionId, reader = false) {
+        const row = this.statements.liveWriter.get(workspaceRef, exceptExecutionId ?? "", reader ? 1 : 0);
+        return row !== undefined;
+    }
+    // ------------------------------------------------------- tool-call ledger
+    toolCallStarted(executionId, callId, toolName) {
+        this.statements.toolStarted.run(executionId, callId, toolName, this.timestamp());
+    }
+    toolCallFinished(executionId, callId) {
+        this.statements.toolFinished.run(this.timestamp(), executionId, callId);
+    }
+    /** Calls that started but never finished: outcome unknown, verify before replay. */
+    unfinishedToolCalls(executionId) {
+        return this.statements.unfinishedTools.all(executionId)
+            .map((row) => ({ toolName: row.tool_name, callId: row.call_id }));
+    }
+    // -------------------------------------------------------- events/outbox
+    eventsAfter(executionId, afterSeq) {
+        return this.statements.eventsAfter.all(executionId, afterSeq).map((row) => this.toEvent(row));
+    }
+    /** Events still owed to their callers. */
+    dueDeliveries(limit = 50) {
+        const rows = this.statements.dueOutbox.all(this.timestamp(), limit);
+        return rows.map((row) => ({
+            event: this.toEvent(row),
+            caller: JSON.parse(row.outbox_caller),
+            attempts: row.outbox_attempts,
+        }));
+    }
+    /** The caller confirmed the event is in its own durable queue. */
+    acknowledgeDelivery(eventId) {
+        this.statements.ackOutbox.run(eventId);
+    }
+    deferDelivery(eventId, retryAt) {
+        this.statements.deferOutbox.run(retryAt.toISOString(), eventId);
+    }
+    /** After a host restart the callers are back too: retry every owed delivery now. */
+    rescheduleOwedDeliveries() {
+        this.statements.rescheduleOutbox.run(this.timestamp());
+    }
+    /**
+     * Observe every committed event (live streams). Durable delivery to a
+     * caller still goes through the outbox; this is a best-effort live feed.
+     */
+    onEvent(listener) {
+        this.eventListeners.add(listener);
+        return () => this.eventListeners.delete(listener);
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.db.close();
+    }
+    // -------------------------------------------------------------- helpers
+    command(envelope, type, target, content, apply) {
+        ExecutionCallerSchema.parse(envelope.caller);
+        if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/.test(envelope.commandId))
+            throw new Error("Invalid commandId");
+        const key = callerKey(envelope.caller, envelope.scope);
+        const digest = commandDigest(envelope, type, target, content);
+        return this.transaction(() => {
+            const previous = this.statements.getCommand.get(key, envelope.commandId);
+            if (previous) {
+                if (previous.digest !== digest) {
+                    throw new ExecutionCommandConflictError(`commandId ${envelope.commandId} was already used with different content`);
+                }
+                const replayed = JSON.parse(previous.response);
+                return replayed.kind === "ok" ? { ...replayed, replay: true } : replayed;
+            }
+            const outcome = apply();
+            this.statements.insertCommand.run(key, envelope.commandId, digest, JSON.stringify(outcome), this.timestamp());
+            return outcome;
+        });
+    }
+    /** A task id is owned by the scope and caller that first submitted it. */
+    ownsTask(taskId, envelope) {
+        const first = this.statements.taskOwner.get(taskId);
+        if (!first)
+            return true;
+        if (first.scope !== envelope.scope)
+            return false;
+        const owner = JSON.parse(first.caller);
+        return owner.kind === envelope.caller.kind && owner.ref === envelope.caller.ref;
+    }
+    owned(executionId, envelope) {
+        const row = this.row(this.statements.getExecution.get(executionId));
+        if (row?.scope !== envelope.scope)
+            return null;
+        const caller = JSON.parse(row.caller);
+        return caller.kind === envelope.caller.kind && caller.ref === envelope.caller.ref ? row : null;
+    }
+    current(executionId, generation) {
+        const row = this.row(this.statements.getExecution.get(executionId));
+        return row?.worker_instance_id === generation && !isTerminalExecutionState(row.state) ? row : null;
+    }
+    update(row, changes) {
+        const revision = row.revision + 1;
+        const entries = Object.entries({ ...changes, revision, updated_at: this.timestamp() });
+        const sql = `UPDATE executions SET ${entries.map(([key]) => `${key} = ?`).join(", ")}
+      WHERE execution_id = ? AND revision = ?`;
+        const result = this.db.prepare(sql).run(...entries.map(([, value]) => value), row.execution_id, row.revision);
+        if (result.changes !== 1)
+            throw new Error(`Execution ${row.execution_id} changed concurrently`);
+        return revision;
+    }
+    appendEvent(executionId, type, commandId, payload, deliver = type === "accepted") {
+        const row = this.row(this.statements.getExecution.get(executionId));
+        if (!row)
+            throw new Error(`Unknown execution ${executionId}`);
+        const eventId = `evt-${randomUUID()}`;
+        const at = this.timestamp();
+        const inserted = this.statements.insertEvent.run(eventId, row.task_id, executionId, type, commandId, at, JSON.stringify(payload));
+        if (deliver)
+            this.statements.insertOutbox.run(eventId, row.caller, at, at);
+        const event = this.toEvent(this.statements.getEventBySeq.get(Number(inserted.lastInsertRowid)));
+        this.uncommittedEvents.push({ event, caller: JSON.parse(row.caller) });
+        return event;
+    }
+    transaction(operation) {
+        if (this.transactionDepth > 0)
+            return operation();
+        this.db.exec("BEGIN IMMEDIATE");
+        this.transactionDepth += 1;
+        let value;
+        try {
+            value = operation();
+            this.db.exec("COMMIT");
+        }
+        catch (error) {
+            this.uncommittedEvents = [];
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+        finally {
+            this.transactionDepth -= 1;
+        }
+        const committed = this.uncommittedEvents;
+        this.uncommittedEvents = [];
+        for (const { event, caller } of committed) {
+            for (const listener of this.eventListeners) {
+                try {
+                    listener(event, caller);
+                }
+                catch { /* a live listener never fails the commit */ }
+            }
+        }
+        return value;
+    }
+    /** The host-held usage, attached to every terminal result; cost stays unknown. */
+    withUsage(executionId, result) {
+        const usage = this.usageOf(executionId);
+        return usage ? { ...result, usage: { ...usage, costUsd: null } } : result;
+    }
+    timestamp() {
+        return this.now().toISOString();
+    }
+    mustGetRow(executionId) {
+        const row = this.row(this.statements.getExecution.get(executionId));
+        if (!row)
+            throw new Error(`Execution ${executionId} disappeared inside its transaction`);
+        return row;
+    }
+    mustGet(executionId) {
+        return this.toRecord(this.mustGetRow(executionId));
+    }
+    row(value) {
+        return value ?? null;
+    }
+    toRecord(row) {
+        return {
+            taskId: row.task_id,
+            executionId: row.execution_id,
+            scope: row.scope,
+            caller: JSON.parse(row.caller),
+            state: row.state,
+            revision: row.revision,
+            inputSeq: row.input_seq,
+            processedInputSeq: row.processed_input_seq,
+            workerInstanceId: row.worker_instance_id,
+            autoResumeCount: row.auto_resume_count,
+            payload: JSON.parse(row.payload),
+            snapshot: row.snapshot,
+            openQuestionId: row.open_question_id,
+            result: row.result ? JSON.parse(row.result) : null,
+            usage: this.usageOf(row.execution_id),
+            createdAt: row.created_at,
+            updatedAt: row.updated_at,
+            queuedAt: row.queued_at,
+            startedAt: row.started_at,
+            cancelRequestedAt: row.cancel_requested_at,
+            stoppedAt: row.stopped_at,
+        };
+    }
+    toEvent(row) {
+        return {
+            protocolVersion: EXECUTION_PROTOCOL_VERSION,
+            eventId: row.event_id,
+            seq: row.seq,
+            taskId: row.task_id,
+            executionId: row.execution_id,
+            type: row.type,
+            ...(row.command_id ? { commandId: row.command_id } : {}),
+            createdAt: row.created_at,
+            payload: JSON.parse(row.payload),
+        };
+    }
+}
+//# sourceMappingURL=execution-store.js.map