@osolmaz/pi-workflows 0.11.1 → 0.12.0

package/dist/controllers/sqlite.js

@@ -9,6 +9,7 @@ const MAX_KEY_LENGTH = 512;
 const MAX_ERROR_LENGTH = 8_192;
 const MAX_EVENT_BYTES = 64 * 1024;
 const MAX_RESOURCE_VALUE_BYTES = 1024 * 1024;
+const TURN_INTENT_FACTS_SCHEMA = "pi-workflows.deferred-turn-facts.v1";
 export class SqliteControllerStore {
     filePath;
     database;
@@ -467,19 +468,93 @@ export class SqliteControllerStore {
             if (row === undefined) {
                 throw new Error("Controller store has no schema identifier");
             }
-            return;
         }
-        this.transaction(() => {
-            this.database
-                .prepare("INSERT OR IGNORE INTO schema_info (singleton, schema_id) VALUES (1, ?)")
-                .run(CONTROLLER_STORE_SCHEMA);
-            this.database.exec(SCHEMA_SQL);
-            const queueColumns = this.database.pragma("table_info(workflow_run_queue)");
-            if (!queueColumns.some((column) => column.name === "origin_session_id")) {
-                this.database.exec("ALTER TABLE workflow_run_queue ADD COLUMN origin_session_id TEXT");
+        else {
+            const existingQueue = this.database
+                .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'workflow_run_queue'")
+                .get();
+            if (existingQueue !== undefined) {
+                this.assertAlphaSchemaLayout(false);
+                this.assertNoLegacyPendingLaunchNotifications();
             }
-            this.database.exec("DROP TABLE IF EXISTS session_watermarks");
-        });
+            this.transaction(() => {
+                this.database
+                    .prepare("INSERT OR IGNORE INTO schema_info (singleton, schema_id) VALUES (1, ?)")
+                    .run(CONTROLLER_STORE_SCHEMA);
+                this.database.exec(SCHEMA_SQL);
+            });
+        }
+        this.assertAlphaSchemaLayout(true);
+        this.assertNoLegacyPendingLaunchNotifications();
+    }
+    assertAlphaSchemaLayout(requireTurnIntents) {
+        const requiredQueueColumns = new Set([
+            "run_id",
+            "workflow_ref",
+            "workflow_path",
+            "workflow_source_json",
+            "definition_digest",
+            "input_json",
+            "launch_options_json",
+            "status",
+            "runner_id",
+            "claim_token",
+            "claim_expires_at",
+            "affinity_runner_id",
+            "origin_session_id",
+            "parent_run_id",
+            "error_code",
+            "error_message",
+            "created_at",
+            "updated_at",
+            "started_at",
+            "finished_at",
+        ]);
+        const actual = new Set(this.database.pragma("table_info(workflow_run_queue)").map((column) => column.name));
+        const missing = [...requiredQueueColumns].filter((column) => !actual.has(column));
+        if (missing.length > 0) {
+            throw new Error("Controller store uses an incompatible alpha layout. Preserve needed run bundles, then reset the project controller store.");
+        }
+        if (!requireTurnIntents)
+            return;
+        const requiredIntentColumns = new Set([
+            "intent_id",
+            "source_event_id",
+            "run_id",
+            "workflow_ref",
+            "target_session_id",
+            "cause",
+            "node_id",
+            "attempt_id",
+            "fallback_facts_json",
+            "requested_at",
+            "eligible_at",
+            "resolved_at",
+            "resolution",
+            "resolution_message_id",
+            "delivery_claim_token",
+            "delivery_claim_expires_at",
+        ]);
+        const intentColumns = new Set(this.database.pragma("table_info(workflow_turn_intents)").map((column) => column.name));
+        const missingIntentColumns = [...requiredIntentColumns].filter((column) => !intentColumns.has(column));
+        if (missingIntentColumns.length > 0) {
+            throw new Error("Controller store uses an incompatible alpha turn-intent layout. Preserve needed run bundles, then reset the project controller store.");
+        }
+    }
+    assertNoLegacyPendingLaunchNotifications() {
+        const notificationTable = this.database
+            .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'workflow_notifications'")
+            .get();
+        if (notificationTable === undefined) {
+            throw new Error("Controller store uses an incompatible alpha notification layout. Preserve needed run bundles, then reset the project controller store.");
+        }
+        const legacy = this.database
+            .prepare(`SELECT 1 FROM workflow_notifications
+         WHERE kind = 'launch_failure' AND delivered_at IS NULL LIMIT 1`)
+            .get();
+        if (legacy !== undefined) {
+            throw new Error("Controller store contains pending alpha launch-failure notifications. Preserve needed run bundles, then reset the project controller store.");
+        }
     }
     transaction(task) {
         this.database.exec("BEGIN IMMEDIATE");
@@ -551,10 +626,32 @@ export class SqliteControllerStore {
         }
         return workflow;
     }
-    /**
-     * Insert a user-started run and claim it in one statement, so the
-     * originating runner owns the run from birth (origin affinity).
-     */
+    /** Reserve a user-started run before the initiating agent turn settles. */
+    reserveWorkflowRun(options) {
+        validateRunId(options.runId);
+        validateKey(options.workflowName, "workflow name");
+        validateKey(options.workflowSourceRef, "workflow source ref");
+        validateKey(options.definitionDigest, "workflow definition digest");
+        validateKey(options.runnerId, "runner id");
+        validateKey(options.originSessionId, "origin session id");
+        const inputJson = canonicalJson(options.input ?? null, "workflow run input");
+        const sourceJson = canonicalJson(options.workflowSource, "workflow run source");
+        const launchJson = canonicalJson(options.launchOptions ?? {}, "workflow launch options");
+        validateJsonSize(inputJson, "Workflow run input", MAX_RESOURCE_VALUE_BYTES);
+        validateJsonSize(sourceJson, "Workflow run source", MAX_EVENT_BYTES);
+        validateJsonSize(launchJson, "Workflow launch options", MAX_EVENT_BYTES);
+        const now = validTimestamp(options.now);
+        this.database
+            .prepare(`INSERT INTO workflow_run_queue (
+          run_id, workflow_ref, workflow_path, workflow_source_json, definition_digest,
+          input_json, launch_options_json, status, runner_id, claim_token, claim_expires_at,
+          affinity_runner_id, origin_session_id, parent_run_id, error_code, error_message,
+          created_at, updated_at, started_at, finished_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, 'queued', NULL, NULL, NULL, ?, ?, ?, NULL, NULL, ?, ?, NULL, NULL)`)
+            .run(options.runId, options.workflowName, options.workflowSourceRef, sourceJson, options.definitionDigest, inputJson, launchJson, options.runnerId, options.originSessionId, options.parentRunId ?? null, now, now);
+        return this.requireWorkflowRun(options.runId);
+    }
+    /** Insert a run that will start immediately outside a live model turn. */
     enqueueWorkflowRun(options) {
         validateRunId(options.runId);
         validateKey(options.workflowName, "workflow name");
@@ -566,16 +663,19 @@ export class SqliteControllerStore {
             validateKey(options.originSessionId, "origin session id");
         }
         const inputJson = canonicalJson(options.input ?? null, "workflow run input");
+        const sourceJson = canonicalJson(options.workflowSource ?? { ref: options.workflowSourceRef }, "workflow run source");
+        const launchJson = canonicalJson(options.launchOptions ?? {}, "workflow launch options");
         validateJsonSize(inputJson, "Workflow run input", MAX_RESOURCE_VALUE_BYTES);
         const now = validTimestamp(options.now);
         const expiresAt = epoch(now) + options.leaseMs;
         this.database
             .prepare(`INSERT INTO workflow_run_queue (
-          run_id, workflow_ref, workflow_path, input_json, status,
-          runner_id, claim_token, claim_expires_at, affinity_runner_id,
-          origin_session_id, parent_run_id, created_at, updated_at
-        ) VALUES (?, ?, ?, ?, 'claimed', ?, ?, ?, ?, ?, ?, ?, ?)`)
-            .run(options.runId, options.workflowName, options.workflowSourceRef, inputJson, options.runnerId, options.claimToken, expiresAt, options.affinityRunnerId ?? options.runnerId, options.originSessionId ?? null, options.parentRunId ?? null, now, now);
+          run_id, workflow_ref, workflow_path, workflow_source_json, definition_digest,
+          input_json, launch_options_json, status, runner_id, claim_token, claim_expires_at,
+          affinity_runner_id, origin_session_id, parent_run_id, error_code, error_message,
+          created_at, updated_at, started_at, finished_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, 'starting', ?, ?, ?, ?, ?, ?, NULL, NULL, ?, ?, ?, NULL)`)
+            .run(options.runId, options.workflowName, options.workflowSourceRef, sourceJson, options.definitionDigest ?? "unavailable", inputJson, launchJson, options.runnerId, options.claimToken, expiresAt, options.affinityRunnerId ?? options.runnerId, options.originSessionId ?? null, options.parentRunId ?? null, now, now, now);
         return this.requireWorkflowRun(options.runId);
     }
     getWorkflowRun(runId) {
@@ -595,6 +695,43 @@ export class SqliteControllerStore {
                 .all(options.status);
         return rows.map(workflowRunFromRow);
     }
+    findSessionReservation(sessionId) {
+        validateKey(sessionId, "session id");
+        const row = this.database
+            .prepare(`SELECT * FROM workflow_run_queue
+         WHERE origin_session_id = ? AND status IN ('queued', 'starting', 'running')
+         ORDER BY created_at LIMIT 1`)
+            .get(sessionId);
+        return row === undefined ? undefined : workflowRunFromRow(row);
+    }
+    claimWorkflowRun(options) {
+        validateRunId(options.runId);
+        validateKey(options.runnerId, "runner id");
+        validateKey(options.claimToken, "claim token");
+        validateDuration(options.leaseMs, "leaseMs");
+        const now = validTimestamp(options.now);
+        const nowMs = epoch(now);
+        const expiresAt = nowMs + options.leaseMs;
+        const result = this.database
+            .prepare(`UPDATE workflow_run_queue
+         SET status = 'starting', runner_id = ?, claim_token = ?, claim_expires_at = ?,
+             started_at = COALESCE(started_at, ?), updated_at = ?
+         WHERE run_id = ? AND (
+           status IN ('queued', 'parked')
+           OR (status = 'starting' AND claim_expires_at IS NOT NULL AND claim_expires_at <= ?)
+         )`)
+            .run(options.runnerId, options.claimToken, expiresAt, now, now, options.runId, nowMs);
+        return result.changes === 1 ? this.requireWorkflowRun(options.runId) : undefined;
+    }
+    markWorkflowRunRunning(options) {
+        validateRunId(options.runId);
+        const now = validTimestamp(options.now);
+        const result = this.database
+            .prepare(`UPDATE workflow_run_queue SET status = 'running', updated_at = ?
+         WHERE run_id = ? AND claim_token = ? AND status = 'starting'`)
+            .run(now, options.runId, options.claimToken);
+        return result.changes === 1;
+    }
     /**
      * Claim the oldest claimable run, preferring runs with affinity to this
      * runner. Parked rows are claimable immediately; claimed rows become
@@ -616,11 +753,11 @@ export class SqliteControllerStore {
         }
         const exclusion = excluded.length === 0 ? "" : `AND run_id NOT IN (${excluded.map(() => "?").join(", ")})`;
         const sessionFilter = options.sessionId === undefined
-            ? ""
+            ? "AND status != 'queued' AND (status != 'starting' OR origin_session_id IS NULL)"
             : "AND (origin_session_id IS NULL OR origin_session_id = ?)";
         const claimable = `(
-      status = 'parked'
-      OR (status = 'claimed' AND claim_expires_at IS NOT NULL AND claim_expires_at <= ?)
+      status IN ('queued', 'parked')
+      OR (status IN ('starting', 'running') AND claim_expires_at IS NOT NULL AND claim_expires_at <= ?)
     )`;
         return this.transaction(() => {
             const candidate = this.database
@@ -636,13 +773,13 @@ export class SqliteControllerStore {
             }
             const result = this.database
                 .prepare(`UPDATE workflow_run_queue
-           SET status = 'claimed', runner_id = ?, claim_token = ?,
-               claim_expires_at = ?, updated_at = ?
+           SET status = 'starting', runner_id = ?, claim_token = ?,
+               claim_expires_at = ?, started_at = COALESCE(started_at, ?), updated_at = ?
            WHERE run_id = ? AND (
-             status = 'parked'
-             OR (status = 'claimed' AND claim_expires_at IS NOT NULL AND claim_expires_at <= ?)
+             status IN ('queued', 'parked')
+             OR (status IN ('starting', 'running') AND claim_expires_at IS NOT NULL AND claim_expires_at <= ?)
            )`)
-                .run(options.runnerId, options.claimToken, expiresAt, now, candidate.run_id, nowMs);
+                .run(options.runnerId, options.claimToken, expiresAt, now, now, candidate.run_id, nowMs);
             return result.changes === 1 ? this.requireWorkflowRun(candidate.run_id) : undefined;
         });
     }
@@ -654,7 +791,7 @@ export class SqliteControllerStore {
         const expiresAt = nowMs + options.leaseMs;
         const result = this.database
             .prepare(`UPDATE workflow_run_queue SET claim_expires_at = ?
-         WHERE run_id = ? AND claim_token = ? AND status = 'claimed'
+         WHERE run_id = ? AND claim_token = ? AND status IN ('starting', 'running')
            AND claim_expires_at > ?`)
             .run(expiresAt, options.runId, options.claimToken, nowMs);
         return result.changes === 1;
@@ -665,7 +802,7 @@ export class SqliteControllerStore {
         const nowMs = epoch(validTimestamp(options.now));
         const row = this.database
             .prepare(`SELECT 1 AS live FROM workflow_run_queue
-         WHERE run_id = ? AND claim_token = ? AND status = 'claimed'
+         WHERE run_id = ? AND claim_token = ? AND status IN ('starting', 'running')
            AND claim_expires_at > ?`)
             .get(options.runId, options.claimToken, nowMs);
         return row !== undefined;
@@ -678,10 +815,42 @@ export class SqliteControllerStore {
             .prepare(`UPDATE workflow_run_queue
          SET status = 'parked', runner_id = NULL, claim_token = NULL,
              claim_expires_at = NULL, updated_at = ?
-         WHERE run_id = ? AND claim_token = ? AND status = 'claimed'`)
+         WHERE run_id = ? AND claim_token = ? AND status IN ('starting', 'running')`)
             .run(now, options.runId, options.claimToken);
         return result.changes === 1;
     }
+    failWorkflowRun(options) {
+        validateRunId(options.runId);
+        validateKey(options.errorCode, "workflow launch error code");
+        const message = options.errorMessage.trim();
+        if (message.length === 0 || Buffer.byteLength(message) > 2_048) {
+            throw new Error("Workflow launch error message must be between 1 and 2048 bytes");
+        }
+        const now = validTimestamp(options.now);
+        const claimFilter = options.claimToken === undefined ? "" : "AND claim_token = ?";
+        const result = this.database
+            .prepare(`UPDATE workflow_run_queue
+         SET status = 'failed', runner_id = NULL, claim_token = NULL,
+             claim_expires_at = NULL, parent_run_id = NULL, input_json = 'null',
+             launch_options_json = '{}', error_code = ?, error_message = ?,
+             finished_at = ?, updated_at = ?
+         WHERE run_id = ? AND status IN ('queued', 'starting', 'running') ${claimFilter}`)
+            .run(options.errorCode, message, now, now, options.runId, ...(options.claimToken === undefined ? [] : [options.claimToken]));
+        return result.changes === 1;
+    }
+    cancelWorkflowRun(options) {
+        validateRunId(options.runId);
+        const now = validTimestamp(options.now);
+        const claimFilter = options.claimToken === undefined ? "" : "AND claim_token = ?";
+        const result = this.database
+            .prepare(`UPDATE workflow_run_queue
+         SET status = 'cancelled', runner_id = NULL, claim_token = NULL,
+             claim_expires_at = NULL, input_json = 'null', launch_options_json = '{}',
+             finished_at = ?, updated_at = ?
+         WHERE run_id = ? AND status IN ('queued', 'starting') ${claimFilter}`)
+            .run(now, now, options.runId, ...(options.claimToken === undefined ? [] : [options.claimToken]));
+        return result.changes === 1;
+    }
     /**
      * Delete a claimed row. Used when a continuation fails before its bundle
      * exists, so the parent's one-continuation slot is not consumed by a run
@@ -701,9 +870,10 @@ export class SqliteControllerStore {
         const result = this.database
             .prepare(`UPDATE workflow_run_queue
          SET status = 'done', runner_id = NULL, claim_token = NULL,
-             claim_expires_at = NULL, updated_at = ?
-         WHERE run_id = ? AND claim_token = ? AND status = 'claimed'`)
-            .run(now, options.runId, options.claimToken);
+             claim_expires_at = NULL, input_json = 'null', launch_options_json = '{}',
+             finished_at = ?, updated_at = ?
+         WHERE run_id = ? AND claim_token = ? AND status IN ('starting', 'running')`)
+            .run(now, now, options.runId, options.claimToken);
         return result.changes === 1;
     }
     /** Repair a canonical bundle's queue source and claim it only when needed. */
@@ -721,26 +891,27 @@ export class SqliteControllerStore {
             const row = this.database
                 .prepare("SELECT * FROM workflow_run_queue WHERE run_id = ?")
                 .get(options.runId);
-            if (row === undefined || row.status === "done")
+            if (row === undefined || ["done", "failed", "cancelled"].includes(row.status)) {
                 return false;
+            }
             if (row.workflow_path === options.workflowSourceRef && row.status === "parked") {
                 return "unchanged";
             }
             const claimable = row.status === "parked" ||
-                (row.status === "claimed" &&
+                (row.status === "starting" &&
                     row.claim_token === options.claimToken &&
                     row.claim_expires_at !== null &&
                     row.claim_expires_at > nowMs) ||
-                (row.status === "claimed" &&
+                (row.status === "starting" &&
                     row.claim_expires_at !== null &&
                     row.claim_expires_at <= nowMs);
             if (!claimable)
                 return false;
             const result = this.database
                 .prepare(`UPDATE workflow_run_queue
-           SET workflow_ref = ?, workflow_path = ?, status = 'claimed', runner_id = ?,
+           SET workflow_ref = ?, workflow_path = ?, status = 'starting', runner_id = ?,
                claim_token = ?, claim_expires_at = ?, updated_at = ?
-           WHERE run_id = ? AND status != 'done'`)
+           WHERE run_id = ? AND status NOT IN ('done', 'failed', 'cancelled')`)
                 .run(options.workflowName, options.workflowSourceRef, options.runnerId, options.claimToken, expiresAt, now, options.runId);
             return result.changes === 1 ? "claimed" : false;
         });
@@ -761,25 +932,26 @@ export class SqliteControllerStore {
             const row = this.database
                 .prepare("SELECT * FROM workflow_run_queue WHERE run_id = ?")
                 .get(options.runId);
-            if (row === undefined || row.status === "done")
+            if (row === undefined || ["done", "failed", "cancelled"].includes(row.status)) {
                 return false;
+            }
             const sourceMatches = row.workflow_path === options.oldWorkflowPath ||
                 row.workflow_path === options.workflowSourceRef;
             const claimable = row.status === "parked" ||
-                (row.status === "claimed" &&
+                (row.status === "starting" &&
                     row.claim_token === options.claimToken &&
                     row.claim_expires_at !== null &&
                     row.claim_expires_at > nowMs) ||
-                (row.status === "claimed" &&
+                (row.status === "starting" &&
                     row.claim_expires_at !== null &&
                     row.claim_expires_at <= nowMs);
             if (!sourceMatches || !claimable)
                 return false;
             const result = this.database
                 .prepare(`UPDATE workflow_run_queue
-           SET workflow_ref = ?, workflow_path = ?, status = 'claimed', runner_id = ?,
+           SET workflow_ref = ?, workflow_path = ?, status = 'starting', runner_id = ?,
                claim_token = ?, claim_expires_at = ?, updated_at = ?
-           WHERE run_id = ? AND status != 'done'`)
+           WHERE run_id = ? AND status NOT IN ('done', 'failed', 'cancelled')`)
                 .run(options.workflowName, options.workflowSourceRef, options.runnerId, options.claimToken, expiresAt, now, options.runId);
             return result.changes === 1;
         });
@@ -815,6 +987,179 @@ export class SqliteControllerStore {
             payload: parseStoredJson(row.payload_json, "run event payload"),
         }));
     }
+    ensureWorkflowTurnIntent(options) {
+        validateKey(options.intentId, "workflow turn intent id");
+        validateKey(options.sourceEventId, "workflow turn source event id");
+        validateRunId(options.runId);
+        validateKey(options.workflowRef, "workflow turn workflow ref");
+        validateKey(options.targetSessionId, "workflow turn target session id");
+        validateWorkflowTurnIntentCause(options.cause);
+        const nodeId = options.nodeId ?? null;
+        const attemptId = options.attemptId ?? null;
+        if (nodeId !== null)
+            validateKey(nodeId, "workflow turn node id");
+        if (attemptId !== null)
+            validateKey(attemptId, "workflow turn attempt id");
+        const factsJson = workflowTurnIntentFactsJson(options.fallbackFacts);
+        const now = validTimestamp(options.now);
+        const eligibleAt = options.eligible === true ? now : null;
+        this.database
+            .prepare(`INSERT INTO workflow_turn_intents (
+          intent_id, source_event_id, run_id, workflow_ref, target_session_id,
+          cause, node_id, attempt_id, fallback_facts_json, requested_at, eligible_at,
+          resolved_at, resolution, resolution_message_id,
+          delivery_claim_token, delivery_claim_expires_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, NULL, NULL, NULL, NULL)
+        ON CONFLICT(intent_id) DO NOTHING`)
+            .run(options.intentId, options.sourceEventId, options.runId, options.workflowRef, options.targetSessionId, options.cause, nodeId, attemptId, factsJson, now, eligibleAt);
+        const existing = this.getWorkflowTurnIntent(options.intentId);
+        if (existing === undefined) {
+            throw new Error(`Workflow turn intent was not stored: ${options.intentId}`);
+        }
+        if (existing.sourceEventId !== options.sourceEventId ||
+            existing.runId !== options.runId ||
+            existing.workflowRef !== options.workflowRef ||
+            existing.targetSessionId !== options.targetSessionId ||
+            existing.cause !== options.cause ||
+            existing.nodeId !== nodeId ||
+            existing.attemptId !== attemptId) {
+            throw new Error(`Workflow turn intent identity conflict: ${options.intentId}`);
+        }
+        return existing;
+    }
+    getWorkflowTurnIntent(intentId) {
+        validateKey(intentId, "workflow turn intent id");
+        const row = this.database
+            .prepare("SELECT * FROM workflow_turn_intents WHERE intent_id = ?")
+            .get(intentId);
+        return row === undefined ? undefined : workflowTurnIntentFromRow(row);
+    }
+    findPendingWorkflowTurnIntent(options) {
+        validateRunId(options.runId);
+        validateKey(options.targetSessionId, "workflow turn target session id");
+        const row = this.database
+            .prepare(`SELECT * FROM workflow_turn_intents
+         WHERE run_id = ? AND target_session_id = ? AND resolved_at IS NULL
+         ORDER BY requested_at DESC, intent_id DESC LIMIT 1`)
+            .get(options.runId, options.targetSessionId);
+        return row === undefined ? undefined : workflowTurnIntentFromRow(row);
+    }
+    claimWorkflowTurnIntent(options) {
+        validateKey(options.intentId, "workflow turn intent id");
+        validateKey(options.targetSessionId, "workflow turn target session id");
+        validateKey(options.claimToken, "workflow turn claim token");
+        validateDuration(options.leaseMs, "leaseMs");
+        const nowMs = epoch(validTimestamp(options.now));
+        const result = this.database
+            .prepare(`UPDATE workflow_turn_intents
+         SET delivery_claim_token = ?, delivery_claim_expires_at = ?
+         WHERE intent_id = ? AND target_session_id = ? AND resolved_at IS NULL
+           AND (delivery_claim_expires_at IS NULL OR delivery_claim_expires_at <= ?)`)
+            .run(options.claimToken, nowMs + options.leaseMs, options.intentId, options.targetSessionId, nowMs);
+        if (result.changes !== 1)
+            return undefined;
+        const row = this.database
+            .prepare("SELECT * FROM workflow_turn_intents WHERE intent_id = ?")
+            .get(options.intentId);
+        return workflowTurnIntentFromRow(row);
+    }
+    claimEligibleWorkflowTurnIntents(options) {
+        validateKey(options.targetSessionId, "workflow turn target session id");
+        validateKey(options.claimToken, "workflow turn claim token");
+        validateDuration(options.leaseMs, "leaseMs");
+        const limit = options.limit ?? 20;
+        if (!Number.isSafeInteger(limit) || limit <= 0 || limit > 100) {
+            throw new Error("Workflow turn intent limit must be an integer from 1 through 100");
+        }
+        const now = validTimestamp(options.now);
+        const nowMs = epoch(now);
+        return this.transaction(() => {
+            const ids = this.database
+                .prepare(`SELECT intent_id FROM workflow_turn_intents
+           WHERE target_session_id = ? AND resolved_at IS NULL AND eligible_at IS NOT NULL
+             AND eligible_at <= ?
+             AND (delivery_claim_expires_at IS NULL OR delivery_claim_expires_at <= ?)
+           ORDER BY eligible_at, intent_id LIMIT ?`)
+                .all(options.targetSessionId, now, nowMs, limit);
+            if (ids.length === 0)
+                return [];
+            const placeholders = ids.map(() => "?").join(", ");
+            this.database
+                .prepare(`UPDATE workflow_turn_intents
+           SET delivery_claim_token = ?, delivery_claim_expires_at = ?
+           WHERE intent_id IN (${placeholders}) AND resolved_at IS NULL
+             AND (delivery_claim_expires_at IS NULL OR delivery_claim_expires_at <= ?)`)
+                .run(options.claimToken, nowMs + options.leaseMs, ...ids.map((row) => row.intent_id), nowMs);
+            const rows = this.database
+                .prepare(`SELECT * FROM workflow_turn_intents WHERE delivery_claim_token = ?
+           ORDER BY eligible_at, intent_id`)
+                .all(options.claimToken);
+            return rows.map(workflowTurnIntentFromRow);
+        });
+    }
+    makeWorkflowTurnIntentEligible(options) {
+        validateKey(options.intentId, "workflow turn intent id");
+        const result = this.database
+            .prepare(`UPDATE workflow_turn_intents
+         SET fallback_facts_json = ?, eligible_at = COALESCE(eligible_at, ?)
+         WHERE intent_id = ? AND resolved_at IS NULL`)
+            .run(workflowTurnIntentFactsJson(options.fallbackFacts), validTimestamp(options.now), options.intentId);
+        return result.changes === 1;
+    }
+    resolveWorkflowTurnIntent(options) {
+        validateKey(options.intentId, "workflow turn intent id");
+        validateKey(options.targetSessionId, "workflow turn target session id");
+        validateKey(options.claimToken, "workflow turn claim token");
+        validateWorkflowTurnIntentResolution(options.resolution);
+        validateKey(options.messageId, "workflow turn resolution message id");
+        const result = this.database
+            .prepare(`UPDATE workflow_turn_intents
+         SET resolved_at = ?, resolution = ?, resolution_message_id = ?,
+             delivery_claim_token = NULL, delivery_claim_expires_at = NULL
+         WHERE intent_id = ? AND target_session_id = ? AND resolved_at IS NULL
+           AND delivery_claim_token = ?`)
+            .run(validTimestamp(options.now), options.resolution, options.messageId, options.intentId, options.targetSessionId, options.claimToken);
+        return result.changes === 1;
+    }
+    releaseWorkflowTurnIntentClaim(options) {
+        validateKey(options.intentId, "workflow turn intent id");
+        validateKey(options.targetSessionId, "workflow turn target session id");
+        validateKey(options.claimToken, "workflow turn claim token");
+        const result = this.database
+            .prepare(`UPDATE workflow_turn_intents
+         SET delivery_claim_token = NULL, delivery_claim_expires_at = NULL
+         WHERE intent_id = ? AND target_session_id = ? AND resolved_at IS NULL
+           AND delivery_claim_token = ?`)
+            .run(options.intentId, options.targetSessionId, options.claimToken);
+        return result.changes === 1;
+    }
+    listWorkflowTurnIntents(options = {}) {
+        if (options.targetSessionId !== undefined) {
+            validateKey(options.targetSessionId, "workflow turn target session id");
+        }
+        if (options.runId !== undefined)
+            validateRunId(options.runId);
+        const limit = options.limit ?? 20;
+        if (!Number.isSafeInteger(limit) || limit <= 0 || limit > 100) {
+            throw new Error("Workflow turn intent limit must be an integer from 1 through 100");
+        }
+        const clauses = [];
+        const values = [];
+        if (options.targetSessionId !== undefined) {
+            clauses.push("target_session_id = ?");
+            values.push(options.targetSessionId);
+        }
+        if (options.runId !== undefined) {
+            clauses.push("run_id = ?");
+            values.push(options.runId);
+        }
+        const where = clauses.length === 0 ? "" : `WHERE ${clauses.join(" AND ")}`;
+        const rows = this.database
+            .prepare(`SELECT * FROM workflow_turn_intents ${where}
+         ORDER BY requested_at DESC, intent_id DESC LIMIT ?`)
+            .all(...values, limit);
+        return rows.map(workflowTurnIntentFromRow);
+    }
     enqueueWorkflowNotification(options) {
         validateRunId(options.runId);
         validateKey(options.nodeId, "workflow node id");
@@ -945,19 +1290,31 @@ const SCHEMA_SQL = `
     run_id TEXT PRIMARY KEY,
     workflow_ref TEXT NOT NULL,
     workflow_path TEXT NOT NULL,
+    workflow_source_json TEXT NOT NULL,
+    definition_digest TEXT NOT NULL,
     input_json TEXT NOT NULL,
-    status TEXT NOT NULL CHECK (status IN ('claimed', 'parked', 'done')),
+    launch_options_json TEXT NOT NULL,
+    status TEXT NOT NULL CHECK (
+      status IN ('queued', 'starting', 'running', 'parked', 'done', 'failed', 'cancelled')
+    ),
     runner_id TEXT,
     claim_token TEXT,
     claim_expires_at INTEGER,
     affinity_runner_id TEXT,
     origin_session_id TEXT,
     parent_run_id TEXT,
+    error_code TEXT,
+    error_message TEXT,
     created_at TEXT NOT NULL,
-    updated_at TEXT NOT NULL
+    updated_at TEXT NOT NULL,
+    started_at TEXT,
+    finished_at TEXT
   );
   CREATE INDEX IF NOT EXISTS workflow_run_queue_claimable
     ON workflow_run_queue(status, claim_expires_at);
+  CREATE UNIQUE INDEX IF NOT EXISTS workflow_run_queue_session_reservation
+    ON workflow_run_queue(origin_session_id)
+    WHERE origin_session_id IS NOT NULL AND status IN ('queued', 'starting', 'running');
   -- A checkpointed parent admits exactly one continuation run, across
   -- sessions and processes.
   CREATE UNIQUE INDEX IF NOT EXISTS workflow_run_queue_parent
@@ -993,6 +1350,40 @@ const SCHEMA_SQL = `
     ON workflow_notifications(target_session_id, delivery_claim_expires_at, created_at)
     WHERE delivered_at IS NULL;
 
+  CREATE TABLE IF NOT EXISTS workflow_turn_intents (
+    intent_id TEXT PRIMARY KEY,
+    source_event_id TEXT NOT NULL,
+    run_id TEXT NOT NULL,
+    workflow_ref TEXT NOT NULL,
+    target_session_id TEXT NOT NULL,
+    cause TEXT NOT NULL CHECK (
+      cause IN ('agentCancelled', 'timedOut', 'failed', 'launchFailed',
+                'controllerInterrupted', 'claimLost')
+    ),
+    node_id TEXT,
+    attempt_id TEXT,
+    fallback_facts_json TEXT NOT NULL,
+    requested_at TEXT NOT NULL,
+    eligible_at TEXT,
+    resolved_at TEXT,
+    resolution TEXT CHECK (resolution IN ('workflowPrompt', 'presentation', 'fallback')),
+    resolution_message_id TEXT,
+    delivery_claim_token TEXT,
+    delivery_claim_expires_at INTEGER,
+    CHECK (
+      (resolved_at IS NULL AND resolution IS NULL AND resolution_message_id IS NULL) OR
+      (resolved_at IS NOT NULL AND resolution IS NOT NULL AND resolution_message_id IS NOT NULL)
+    )
+  );
+  CREATE UNIQUE INDEX IF NOT EXISTS workflow_turn_intents_one_pending_run
+    ON workflow_turn_intents(run_id, target_session_id) WHERE resolved_at IS NULL;
+  CREATE INDEX IF NOT EXISTS workflow_turn_intents_pending_run
+    ON workflow_turn_intents(run_id, target_session_id, requested_at)
+    WHERE resolved_at IS NULL;
+  CREATE INDEX IF NOT EXISTS workflow_turn_intents_eligible_session
+    ON workflow_turn_intents(target_session_id, eligible_at, intent_id)
+    WHERE resolved_at IS NULL AND eligible_at IS NOT NULL;
+
   CREATE TABLE IF NOT EXISTS effects (
     effect_key TEXT NOT NULL,
     resource_uid TEXT NOT NULL,
@@ -1079,7 +1470,48 @@ function workflowFromRow(row) {
         ...(row.error === null ? {} : { error: row.error }),
     };
 }
+function workflowTurnIntentFromRow(row) {
+    const cause = validateWorkflowTurnIntentCause(row.cause);
+    const resolution = row.resolution === null ? null : validateWorkflowTurnIntentResolution(row.resolution);
+    const fallbackFacts = parseStoredJson(row.fallback_facts_json, "workflow turn intent facts");
+    validateWorkflowTurnIntentFacts(fallbackFacts);
+    validateKey(row.intent_id, "workflow turn intent id");
+    validateKey(row.source_event_id, "workflow turn source event id");
+    validateRunId(row.run_id);
+    validateKey(row.workflow_ref, "workflow turn workflow ref");
+    validateKey(row.target_session_id, "workflow turn target session id");
+    validTimestamp(row.requested_at);
+    if (row.eligible_at !== null)
+        validTimestamp(row.eligible_at);
+    if (row.resolved_at !== null)
+        validTimestamp(row.resolved_at);
+    const allResolutionFieldsNull = row.resolved_at === null && row.resolution === null && row.resolution_message_id === null;
+    const allResolutionFieldsSet = row.resolved_at !== null && row.resolution !== null && row.resolution_message_id !== null;
+    if (!allResolutionFieldsNull && !allResolutionFieldsSet) {
+        throw new Error(`Workflow turn intent ${row.intent_id} has inconsistent resolution fields`);
+    }
+    return {
+        intentId: row.intent_id,
+        sourceEventId: row.source_event_id,
+        runId: row.run_id,
+        workflowRef: row.workflow_ref,
+        targetSessionId: row.target_session_id,
+        cause,
+        nodeId: row.node_id,
+        attemptId: row.attempt_id,
+        fallbackFacts,
+        requestedAt: row.requested_at,
+        eligibleAt: row.eligible_at,
+        resolvedAt: row.resolved_at,
+        resolution,
+        resolutionMessageId: row.resolution_message_id,
+        deliveryClaimExpiresAt: row.delivery_claim_expires_at === null ? null : iso(row.delivery_claim_expires_at),
+    };
+}
 function workflowNotificationFromRow(row) {
+    if (row.kind !== "progress" && row.kind !== "final") {
+        throw new Error("Controller store contains an incompatible pending alpha workflow notification. Preserve needed run bundles, then reset the project controller store.");
+    }
     return {
         notificationId: row.notification_id,
         runId: row.run_id,
@@ -1094,12 +1526,98 @@ function workflowNotificationFromRow(row) {
         deliveredAt: row.delivered_at,
     };
 }
+function workflowTurnIntentFactsJson(facts) {
+    validateWorkflowTurnIntentFacts(facts);
+    const json = canonicalJson(facts, "workflow turn intent facts");
+    validateJsonSize(json, "Workflow turn intent facts", MAX_EVENT_BYTES);
+    return json;
+}
+function validateWorkflowTurnIntentFacts(facts) {
+    if (facts === null || typeof facts !== "object" || Array.isArray(facts)) {
+        throw new Error("Workflow turn intent facts must be an object");
+    }
+    const candidate = facts;
+    if (candidate.schema !== TURN_INTENT_FACTS_SCHEMA) {
+        throw new Error(`Workflow turn intent facts schema must be ${TURN_INTENT_FACTS_SCHEMA}`);
+    }
+    const allowedKeys = new Set([
+        "schema",
+        "workflowName",
+        "runId",
+        "observedState",
+        "cause",
+        "nodeId",
+        "attemptId",
+        "reason",
+        "handoff",
+    ]);
+    for (const key of Object.keys(candidate)) {
+        if (!allowedKeys.has(key))
+            throw new Error(`Unknown workflow turn intent facts field: ${key}`);
+    }
+    if (typeof candidate.workflowName !== "string") {
+        throw new Error("Workflow turn intent workflowName must be a string");
+    }
+    if (typeof candidate.runId !== "string") {
+        throw new Error("Workflow turn intent runId must be a string");
+    }
+    if (typeof candidate.observedState !== "string") {
+        throw new Error("Workflow turn intent observedState must be a string");
+    }
+    if (typeof candidate.cause !== "string") {
+        throw new Error("Workflow turn intent cause must be a string");
+    }
+    validateKey(candidate.workflowName, "workflow turn facts workflow name");
+    validateRunId(candidate.runId);
+    validateKey(candidate.observedState, "workflow turn facts observed state");
+    validateWorkflowTurnIntentCause(candidate.cause);
+    if (candidate.nodeId !== null && typeof candidate.nodeId !== "string") {
+        throw new Error("Workflow turn intent nodeId must be a string or null");
+    }
+    if (candidate.attemptId !== null && typeof candidate.attemptId !== "string") {
+        throw new Error("Workflow turn intent attemptId must be a string or null");
+    }
+    if (candidate.reason !== null && typeof candidate.reason !== "string") {
+        throw new Error("Workflow turn intent reason must be a string or null");
+    }
+    if (candidate.nodeId !== null)
+        validateKey(candidate.nodeId, "workflow turn facts node id");
+    if (candidate.attemptId !== null) {
+        validateKey(candidate.attemptId, "workflow turn facts attempt id");
+    }
+    if (candidate.reason !== null && candidate.reason.length > MAX_ERROR_LENGTH) {
+        throw new Error(`Workflow turn intent reason must be at most ${MAX_ERROR_LENGTH} characters`);
+    }
+    if (typeof candidate.handoff !== "boolean") {
+        throw new Error("Workflow turn intent handoff must be a boolean");
+    }
+}
+function validateWorkflowTurnIntentCause(value) {
+    if (value !== "agentCancelled" &&
+        value !== "timedOut" &&
+        value !== "failed" &&
+        value !== "launchFailed" &&
+        value !== "controllerInterrupted" &&
+        value !== "claimLost") {
+        throw new Error(`Invalid workflow turn intent cause: ${value}`);
+    }
+    return value;
+}
+function validateWorkflowTurnIntentResolution(value) {
+    if (value !== "workflowPrompt" && value !== "presentation" && value !== "fallback") {
+        throw new Error(`Invalid workflow turn intent resolution: ${value}`);
+    }
+    return value;
+}
 function workflowRunFromRow(row) {
     return {
         runId: row.run_id,
         workflowName: row.workflow_ref,
         workflowSourceRef: row.workflow_path,
+        workflowSource: parseStoredJson(row.workflow_source_json, "workflow run source"),
+        definitionDigest: row.definition_digest,
         input: parseStoredJson(row.input_json, "workflow run input"),
+        launchOptions: parseStoredJson(row.launch_options_json, "workflow launch options"),
         status: row.status,
         runnerId: row.runner_id,
         claimToken: row.claim_token,
@@ -1107,8 +1625,12 @@ function workflowRunFromRow(row) {
         affinityRunnerId: row.affinity_runner_id,
         originSessionId: row.origin_session_id,
         parentRunId: row.parent_run_id,
+        errorCode: row.error_code,
+        errorMessage: row.error_message,
         createdAt: row.created_at,
         updatedAt: row.updated_at,
+        startedAt: row.started_at,
+        finishedAt: row.finished_at,
     };
 }
 function validateRunId(runId) {