@osolmaz/pi-workflows 0.11.1 → 0.12.0

package/src/controllers/sqlite.ts

@@ -34,6 +34,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";
 
 type ResourceRow = {
   controller: string;
@@ -83,20 +84,36 @@ type WorkflowRow = {
   error: string | null;
 };
 
+export type WorkflowRunLaunchStatus =
+  | "queued"
+  | "starting"
+  | "running"
+  | "parked"
+  | "done"
+  | "failed"
+  | "cancelled";
+
 type WorkflowRunQueueRow = {
   run_id: string;
   workflow_ref: string;
   workflow_path: string;
+  workflow_source_json: string;
+  definition_digest: string;
   input_json: string;
-  status: "claimed" | "parked" | "done";
+  launch_options_json: string;
+  status: WorkflowRunLaunchStatus;
   runner_id: string | null;
   claim_token: string | null;
   claim_expires_at: number | null;
   affinity_runner_id: string | null;
   origin_session_id: string | null;
   parent_run_id: string | null;
+  error_code: string | null;
+  error_message: string | null;
   created_at: string;
   updated_at: string;
+  started_at: string | null;
+  finished_at: string | null;
 };
 
 /** A user-started workflow run tracked by the durable run queue. */
@@ -106,8 +123,11 @@ export type WorkflowRunQueueRecord = {
   workflowName: string;
   /** Canonical source reference used to reopen the run. */
   workflowSourceRef: string;
+  workflowSource: unknown;
+  definitionDigest: string;
   input: unknown;
-  status: "claimed" | "parked" | "done";
+  launchOptions: unknown;
+  status: WorkflowRunLaunchStatus;
   runnerId: string | null;
   claimToken: string | null;
   claimExpiresAt: string | null;
@@ -115,8 +135,12 @@ export type WorkflowRunQueueRecord = {
   /** Pi session that owns delivery and interactive execution, or null for detached runs. */
   originSessionId: string | null;
   parentRunId: string | null;
+  errorCode: string | null;
+  errorMessage: string | null;
   createdAt: string;
   updatedAt: string;
+  startedAt: string | null;
+  finishedAt: string | null;
 };
 
 type WorkflowNotificationRow = {
@@ -126,7 +150,7 @@ type WorkflowNotificationRow = {
   attempt_id: string;
   notification_index: number;
   target_session_id: string;
-  kind: "progress" | "final";
+  kind: string;
   content: string;
   created_at: string;
   delivery_claim_token: string | null;
@@ -148,6 +172,65 @@ export type WorkflowNotificationRecord = {
   deliveredAt: string | null;
 };
 
+export type WorkflowTurnIntentCause =
+  | "agentCancelled"
+  | "timedOut"
+  | "failed"
+  | "launchFailed"
+  | "controllerInterrupted"
+  | "claimLost";
+
+export type WorkflowTurnIntentResolution = "workflowPrompt" | "presentation" | "fallback";
+
+export type WorkflowTurnIntentFacts = JsonObject & {
+  schema: typeof TURN_INTENT_FACTS_SCHEMA;
+  workflowName: string;
+  runId: string;
+  observedState: string;
+  cause: WorkflowTurnIntentCause;
+  nodeId: string | null;
+  attemptId: string | null;
+  reason: string | null;
+  handoff: boolean;
+};
+
+type WorkflowTurnIntentRow = {
+  intent_id: string;
+  source_event_id: string;
+  run_id: string;
+  workflow_ref: string;
+  target_session_id: string;
+  cause: string;
+  node_id: string | null;
+  attempt_id: string | null;
+  fallback_facts_json: string;
+  requested_at: string;
+  eligible_at: string | null;
+  resolved_at: string | null;
+  resolution: string | null;
+  resolution_message_id: string | null;
+  delivery_claim_token: string | null;
+  delivery_claim_expires_at: number | null;
+};
+
+export type WorkflowTurnIntentRecord = {
+  intentId: string;
+  sourceEventId: string;
+  runId: string;
+  workflowRef: string;
+  targetSessionId: string;
+  cause: WorkflowTurnIntentCause;
+  nodeId: string | null;
+  attemptId: string | null;
+  fallbackFacts: WorkflowTurnIntentFacts;
+  requestedAt: string;
+  eligibleAt: string | null;
+  resolvedAt: string | null;
+  resolution: WorkflowTurnIntentResolution | null;
+  resolutionMessageId: string | null;
+  deliveryClaimExpiresAt: string | null;
+};
+
 type RunEventRow = {
   seq: number;
   recorded_at: string;
@@ -799,21 +882,119 @@ export class SqliteControllerStore implements ControllerStore {
       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)") as {
-        name: string;
-      }[];
-      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();
+  }
+
+  private assertAlphaSchemaLayout(requireTurnIntents: boolean): void {
+    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)") as {
+          name: string;
+        }[]
+      ).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)") as {
+          name: string;
+        }[]
+      ).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.",
+      );
+    }
+  }
+
+  private assertNoLegacyPendingLaunchNotifications(): void {
+    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.",
+      );
+    }
   }
 
   private transaction<T>(task: () => T): T {
@@ -901,15 +1082,68 @@ export class SqliteControllerStore implements ControllerStore {
     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: {
+    runId: string;
+    workflowName: string;
+    workflowSourceRef: string;
+    workflowSource: unknown;
+    definitionDigest: string;
+    input: unknown;
+    launchOptions?: unknown;
+    runnerId: string;
+    originSessionId: string;
+    parentRunId?: string;
+    now?: string;
+  }): WorkflowRunQueueRecord {
+    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: {
     runId: string;
     workflowName: string;
     workflowSourceRef: string;
+    workflowSource?: unknown;
+    definitionDigest?: string;
     input: unknown;
+    launchOptions?: unknown;
     runnerId: string;
     claimToken: string;
     leaseMs: number;
@@ -928,22 +1162,31 @@ export class SqliteControllerStore implements ControllerStore {
       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_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,
@@ -952,6 +1195,7 @@ export class SqliteControllerStore implements ControllerStore {
         options.parentRunId ?? null,
         now,
         now,
+        now,
       );
     return this.requireWorkflowRun(options.runId);
   }
@@ -978,6 +1222,58 @@ export class SqliteControllerStore implements ControllerStore {
     return rows.map(workflowRunFromRow);
   }
 
+  findSessionReservation(sessionId: string): WorkflowRunQueueRecord | undefined {
+    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) as WorkflowRunQueueRow | undefined;
+    return row === undefined ? undefined : workflowRunFromRow(row);
+  }
+
+  claimWorkflowRun(options: {
+    runId: string;
+    runnerId: string;
+    claimToken: string;
+    leaseMs: number;
+    now?: string;
+  }): WorkflowRunQueueRecord | undefined {
+    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: { runId: string; claimToken: string; now?: string }): boolean {
+    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
@@ -1008,11 +1304,11 @@ export class SqliteControllerStore implements ControllerStore {
       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
@@ -1036,14 +1332,14 @@ export class SqliteControllerStore implements ControllerStore {
       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;
     });
   }
@@ -1062,7 +1358,7 @@ export class SqliteControllerStore implements ControllerStore {
     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);
@@ -1076,7 +1372,7 @@ export class SqliteControllerStore implements ControllerStore {
     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);
@@ -1092,12 +1388,68 @@ export class SqliteControllerStore implements ControllerStore {
         `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: {
+    runId: string;
+    claimToken?: string;
+    errorCode: string;
+    errorMessage: string;
+    now?: string;
+  }): boolean {
+    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: { runId: string; claimToken?: string; now?: string }): boolean {
+    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
@@ -1119,10 +1471,11 @@ export class SqliteControllerStore implements ControllerStore {
       .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'`,
+             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, options.runId, options.claimToken);
+      .run(now, now, options.runId, options.claimToken);
     return result.changes === 1;
   }
 
@@ -1149,26 +1502,28 @@ export class SqliteControllerStore implements ControllerStore {
       const row = this.database
         .prepare("SELECT * FROM workflow_run_queue WHERE run_id = ?")
         .get(options.runId) as WorkflowRunQueueRow | undefined;
-      if (row === undefined || row.status === "done") return false;
+      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,
@@ -1208,26 +1563,28 @@ export class SqliteControllerStore implements ControllerStore {
       const row = this.database
         .prepare("SELECT * FROM workflow_run_queue WHERE run_id = ?")
         .get(options.runId) as WorkflowRunQueueRow | undefined;
-      if (row === undefined || row.status === "done") return false;
+      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,
@@ -1291,6 +1648,287 @@ export class SqliteControllerStore implements ControllerStore {
     }));
   }
 
+  ensureWorkflowTurnIntent(options: {
+    intentId: string;
+    sourceEventId: string;
+    runId: string;
+    workflowRef: string;
+    targetSessionId: string;
+    cause: WorkflowTurnIntentCause;
+    nodeId?: string | null;
+    attemptId?: string | null;
+    fallbackFacts: WorkflowTurnIntentFacts;
+    eligible?: boolean;
+    now?: string;
+  }): WorkflowTurnIntentRecord {
+    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: string): WorkflowTurnIntentRecord | undefined {
+    validateKey(intentId, "workflow turn intent id");
+    const row = this.database
+      .prepare("SELECT * FROM workflow_turn_intents WHERE intent_id = ?")
+      .get(intentId) as WorkflowTurnIntentRow | undefined;
+    return row === undefined ? undefined : workflowTurnIntentFromRow(row);
+  }
+
+  findPendingWorkflowTurnIntent(options: {
+    runId: string;
+    targetSessionId: string;
+  }): WorkflowTurnIntentRecord | undefined {
+    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) as WorkflowTurnIntentRow | undefined;
+    return row === undefined ? undefined : workflowTurnIntentFromRow(row);
+  }
+
+  claimWorkflowTurnIntent(options: {
+    intentId: string;
+    targetSessionId: string;
+    claimToken: string;
+    leaseMs: number;
+    now?: string;
+  }): WorkflowTurnIntentRecord | undefined {
+    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) as WorkflowTurnIntentRow;
+    return workflowTurnIntentFromRow(row);
+  }
+
+  claimEligibleWorkflowTurnIntents(options: {
+    targetSessionId: string;
+    claimToken: string;
+    leaseMs: number;
+    limit?: number;
+    now?: string;
+  }): WorkflowTurnIntentRecord[] {
+    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) as { intent_id: string }[];
+      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) as WorkflowTurnIntentRow[];
+      return rows.map(workflowTurnIntentFromRow);
+    });
+  }
+
+  makeWorkflowTurnIntentEligible(options: {
+    intentId: string;
+    fallbackFacts: WorkflowTurnIntentFacts;
+    now?: string;
+  }): boolean {
+    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: {
+    intentId: string;
+    targetSessionId: string;
+    claimToken: string;
+    resolution: WorkflowTurnIntentResolution;
+    messageId: string;
+    now?: string;
+  }): boolean {
+    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: {
+    intentId: string;
+    targetSessionId: string;
+    claimToken: string;
+  }): boolean {
+    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: {
+      targetSessionId?: string;
+      runId?: string;
+      limit?: number;
+    } = {},
+  ): WorkflowTurnIntentRecord[] {
+    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: string[] = [];
+    const values: unknown[] = [];
+    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) as WorkflowTurnIntentRow[];
+    return rows.map(workflowTurnIntentFromRow);
+  }
+
   enqueueWorkflowNotification(options: {
     runId: string;
     nodeId: string;
@@ -1483,19 +2121,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
@@ -1531,6 +2181,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,
@@ -1621,7 +2305,56 @@ function workflowFromRow(row: WorkflowRow): ChildWorkflowRecord {
   };
 }
 
+function workflowTurnIntentFromRow(row: WorkflowTurnIntentRow): WorkflowTurnIntentRecord {
+  const cause = validateWorkflowTurnIntentCause(row.cause);
+  const resolution =
+    row.resolution === null ? null : validateWorkflowTurnIntentResolution(row.resolution);
+  const fallbackFacts = parseStoredJson<unknown>(
+    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: WorkflowNotificationRow): WorkflowNotificationRecord {
+  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,
@@ -1638,12 +2371,102 @@ function workflowNotificationFromRow(row: WorkflowNotificationRow): WorkflowNoti
   };
 }
 
+function workflowTurnIntentFactsJson(facts: WorkflowTurnIntentFacts): string {
+  validateWorkflowTurnIntentFacts(facts);
+  const json = canonicalJson(facts, "workflow turn intent facts");
+  validateJsonSize(json, "Workflow turn intent facts", MAX_EVENT_BYTES);
+  return json;
+}
+
+function validateWorkflowTurnIntentFacts(facts: unknown): asserts facts is WorkflowTurnIntentFacts {
+  if (facts === null || typeof facts !== "object" || Array.isArray(facts)) {
+    throw new Error("Workflow turn intent facts must be an object");
+  }
+  const candidate = facts as Record<string, unknown>;
+  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: string): WorkflowTurnIntentCause {
+  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: string): WorkflowTurnIntentResolution {
+  if (value !== "workflowPrompt" && value !== "presentation" && value !== "fallback") {
+    throw new Error(`Invalid workflow turn intent resolution: ${value}`);
+  }
+  return value;
+}
+
 function workflowRunFromRow(row: WorkflowRunQueueRow): WorkflowRunQueueRecord {
   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,
@@ -1651,8 +2474,12 @@ function workflowRunFromRow(row: WorkflowRunQueueRow): WorkflowRunQueueRecord {
     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,
   };
 }