@cadraos/sdk 0.3.8 → 0.3.10

package/dist/kanban/engine/index.d.cts

@@ -315,6 +315,13 @@ interface KanbanCard {
     executionId?: string;
     /** Summary of the card's current/last run, if any. */
     run?: KanbanRunSummary;
+    /**
+     * When this card next becomes DUE on a scheduled lane (ISO string) — maps to
+     * `agentic_card.next_due_at` (spec §3a / STORY-003/004). Drives the board's
+     * ⧗ "due" chip: `next_due_at ≤ now` → due (the next sweep will pick it up).
+     * OPTIONAL — absent → no due chip (today's render).
+     */
+    nextDueAt?: string;
     /** Who created the card. */
     createdBy?: string;
     /** When the card was created (ISO string). */
@@ -411,6 +418,13 @@ type StageRunStatus = "queued" | "running" | "completed" | "failed";
  * dispatch or a duplicate completion can't double-fire / double-advance
  * (design §5/§11 R2), and a `key` rename never collides with a prior run.
  * Backed by a host `stage_run` table with a UNIQUE constraint on `idemKey`.
+ *
+ * Stranded-run recovery (design §10): a run left `failed` (a dispatch threw) or
+ * stale `queued` (a process died before dispatch) is RE-CLAIMED by the next
+ * `beginStageRun` — reset to a fresh `queued` intent (with `attempts` bumped) —
+ * so a transient dispatch failure self-heals on the following sweep. v1 is
+ * acyclic-only: the idemKey pins `(cardId, stageId, version)`, so a re-claim
+ * only ever re-runs a FAILED attempt of the current stage, never a completed one.
  */
 interface StageRun {
     /** Idempotency key (`cardId:stageId:configVersion`; stageId = immutable id). UNIQUE. */
@@ -427,6 +441,19 @@ interface StageRun {
     executionUuid?: string;
     /** Error message (when failed). */
     error?: string;
+    /**
+     * Dispatch attempt count (design §10 — stranded-run recovery). `1` on first
+     * claim; incremented each time `beginStageRun` RE-CLAIMS a stranded
+     * (failed/stale-queued) run. Optional/back-compat — a host that doesn't track
+     * re-claims leaves it undefined; surfaced for the sweep digest + observability.
+     *
+     * v1 RECORDS attempts but does NOT cap them: self-heal is bounded by the
+     * CADENCE (one re-dispatch per sweep tick), not a max-attempts ceiling, so a
+     * transient outage recovers while a genuinely poison card simply re-fails once
+     * per tick (visible via this counter). A retry ceiling / backoff is a
+     * deliberate follow-on, not v1.
+     */
+    attempts?: number;
     /** When the run intent was created (ISO string). */
     createdAt: string;
 }
@@ -480,7 +507,12 @@ interface ApplyTransitionInput {
  *
  * 2. `beginStageRun` is a CAS insert keyed on `idemKey` (UNIQUE). It returns
  *    `{ created: true, run }` on first insert and `{ created: false, run }`
- *    when the key already exists — so a retried dispatch is a no-op.
+ *    when a NON-reclaimable run already exists — so a retried dispatch is a
+ *    no-op. A `failed` or STALE `queued` run is RE-CLAIMED (reset to `queued`
+ *    → `{ created: true }`) so a transient dispatch failure self-heals on the
+ *    next sweep (design §10 — stranded-run recovery); a `running`/`completed`
+ *    run is never re-claimed. v1 is acyclic-only: the idemKey pins
+ *    `(cardId, stageId, version)`, so a re-claim only re-runs a FAILED attempt.
  *
  * 3. `completeStageRun` runs in ONE transaction: mark the stage run completed
  *    AND `applyTransition` to `toLane` together; it returns `{ applied: false }`
@@ -594,11 +626,42 @@ interface KanbanStorageAdapter {
      */
     capabilities?(): AdapterCapabilities;
     /**
-     * CAS-insert a stage-run intent keyed on `idemKey` (UNIQUE).
+     * CAS-insert a stage-run intent keyed on `idemKey` (UNIQUE), with
+     * FAILED/STALE-QUEUED RE-CLAIM (design §10 — stranded-run recovery).
+     *
+     * @returns `{ created: true, run }` when this call OWNS the dispatch — either
+     * a first insert, OR a RE-CLAIM of an existing run left `failed` (a prior
+     * dispatch threw → `failStageRun`) or stale `queued` (a process died between
+     * begin and dispatch): the adapter resets that run to a fresh `queued` intent
+     * (clearing the stale error/executionUuid, bumping `attempts`) and the engine
+     * dispatches again. `{ created: false, run }` when a NON-reclaimable run
+     * already exists (`running` — mid-flight; or `completed`) — the engine treats
+     * this as "already dispatched"/terminal and does NOT re-invoke the handler.
+     *
+     * A host implements the re-claim as a single conditional write (e.g. an
+     * `UPDATE stage_run SET status='queued', attempts=attempts+1, created_at=now(),
+     * error=NULL, execution_uuid=NULL WHERE idem_key=$1 AND (status='failed' OR
+     * (status='queued' AND created_at < $stale)) RETURNING …`, alongside the plain
+     * CAS insert).
      *
-     * @returns `{ created: true, run }` on first insert; `{ created: false, run }`
-     * when the key already exists (the engine treats this as "already
-     * dispatched" and does NOT re-invoke the handler).
+     * ⚠ CRITICAL for the "two overlapping ticks never both win" guarantee: the SET
+     * MUST move the row OUT of its own WHERE range — reset the `created_at`
+     * discriminator (as shown). Under READ COMMITTED, a concurrent tick's UPDATE
+     * blocks on the row lock, then RE-CHECKS its WHERE against the just-committed
+     * row: with `created_at=now()` the stale-queued predicate no longer matches, so
+     * it updates 0 rows (RETURNING empty → `created:false`). A naive
+     * `SET status='queued'` that leaves `created_at` UNCHANGED is the trap — both
+     * ticks still match the same stale `queued` row and BOTH re-dispatch. (The
+     * in-memory reference adapter resets `createdAt` for exactly this reason.)
+     * Equivalently, claim via a `SELECT … FOR UPDATE SKIP LOCKED` subselect. The
+     * staleness horizon MUST comfortably exceed the host's dispatch timeout so a
+     * genuinely in-flight `queued` row (mid dispatch call) is never re-claimed out
+     * from under it.
+     *
+     * v1 scope is ACYCLIC flows only: because the idemKey embeds
+     * `(cardId, stageId, version)`, a card can never legitimately re-enter the same
+     * stage at the same version, so a re-claim only ever re-runs a FAILED attempt
+     * of the current stage — it never re-executes a completed one.
      */
     beginStageRun(cardId: string, r: {
         stageId: string;
@@ -625,7 +688,12 @@ interface KanbanStorageAdapter {
         applied: boolean;
     }>;
     /**
-     * Mark a stage run failed (surfaced + retryable). Does NOT advance the card.
+     * Mark a stage run failed (surfaced). Does NOT advance the card — it stays in
+     * its lane. The engine calls this when a stage DISPATCH throws (design §10 —
+     * stranded-run recovery), so the run is left `failed` (NOT a stranded `queued`
+     * row the CAS would skip forever) and is RE-CLAIMED by the next
+     * `beginStageRun` on the following sweep. A `completed` run is never clobbered
+     * (a late failure after a success is a no-op — idempotent).
      */
     failStageRun(idemKey: string, f: {
         error: string;
@@ -805,6 +873,13 @@ interface WireHandler {
     type?: string;
     agent_uuid?: string;
     team_uuid?: string;
+    /**
+     * remote_agent → the `remote_agents.uuid` for a `remote_agent` lane (§5.3).
+     * Snake-cased on the wire (published JSONB); mapped to `remoteAgentUuid`.
+     * WITHOUT this the binding is silently dropped at parse and every published
+     * remote_agent lane fails dispatch with "missing remoteAgentUuid" (FINDING-6).
+     */
+    remote_agent_uuid?: string;
     /** Legacy p28 slug ref. */
     agent_ref?: string;
     webhook?: {
@@ -994,6 +1069,14 @@ interface RunAgentInput {
     input: Record<string, unknown>;
     /** Idempotency key (= cardId:stageId:version). */
     idemKey: string;
+    /**
+     * Board/headless dispatch forces allowAskUser=false (spec §6.5 / FINDING-5).
+     * The engine only ever dispatches cadra_agent stages from board surfaces,
+     * which have NO ask_user UI — an ask attempt must FAIL the execution (→ failed
+     * callback → completion bridge → §10 reclaim), never pause it. Pinned `false`
+     * at the type boundary, matching RunRemoteAgentInput.
+     */
+    allowAskUser: false;
     /** A host callback reference the run can advance through (optional). */
     callbackRef?: string;
 }
@@ -1003,6 +1086,8 @@ interface RunTeamInput {
     orgId?: number;
     input: Record<string, unknown>;
     idemKey: string;
+    /** Board/headless dispatch forces allowAskUser=false (spec §6.5 / FINDING-5). */
+    allowAskUser: false;
     callbackRef?: string;
 }
 interface RunRemoteAgentInput {
@@ -1196,6 +1281,20 @@ declare class InMemoryStorageAdapter implements KanbanStorageAdapter {
     private cards;
     private logs;
     private runs;
+    /**
+     * A `queued` stage-run older than this (ms) is STALE and re-claimable by
+     * `beginStageRun` (design §10) — it models a run whose process died between
+     * `beginStageRun` and dispatch, so `failStageRun` never ran. A `failed` run is
+     * re-claimable regardless of age. Must comfortably exceed the dispatch time so
+     * a genuinely in-flight `queued` run is never re-claimed out from under it.
+     */
+    private readonly staleQueuedMs;
+    /** Injectable clock (ms) — real hosts use `Date.now`; tests pin it. */
+    private readonly now;
+    constructor(opts?: {
+        staleQueuedMs?: number;
+        now?: () => number;
+    });
     listCards(boardConfigUuid: string): Promise<KanbanCard[]>;
     getCard(cardId: string): Promise<KanbanCard | null>;
     createCard(input: CreateCardServerInput): Promise<KanbanCard>;
@@ -1219,6 +1318,13 @@ declare class InMemoryStorageAdapter implements KanbanStorageAdapter {
         created: boolean;
         run: StageRun;
     }>;
+    /**
+     * A stranded stage-run the next `beginStageRun` may re-claim (design §10): a
+     * `failed` run (dispatch threw), or a `queued` run older than `staleQueuedMs`
+     * (a process died before dispatch flipped it). `running`/`completed` runs are
+     * never re-claimed.
+     */
+    private isReclaimable;
     completeStageRun(idemKey: string, c: {
         executionUuid?: string;
         toLane?: string;

package/dist/kanban/engine/index.d.ts

@@ -315,6 +315,13 @@ interface KanbanCard {
     executionId?: string;
     /** Summary of the card's current/last run, if any. */
     run?: KanbanRunSummary;
+    /**
+     * When this card next becomes DUE on a scheduled lane (ISO string) — maps to
+     * `agentic_card.next_due_at` (spec §3a / STORY-003/004). Drives the board's
+     * ⧗ "due" chip: `next_due_at ≤ now` → due (the next sweep will pick it up).
+     * OPTIONAL — absent → no due chip (today's render).
+     */
+    nextDueAt?: string;
     /** Who created the card. */
     createdBy?: string;
     /** When the card was created (ISO string). */
@@ -411,6 +418,13 @@ type StageRunStatus = "queued" | "running" | "completed" | "failed";
  * dispatch or a duplicate completion can't double-fire / double-advance
  * (design §5/§11 R2), and a `key` rename never collides with a prior run.
  * Backed by a host `stage_run` table with a UNIQUE constraint on `idemKey`.
+ *
+ * Stranded-run recovery (design §10): a run left `failed` (a dispatch threw) or
+ * stale `queued` (a process died before dispatch) is RE-CLAIMED by the next
+ * `beginStageRun` — reset to a fresh `queued` intent (with `attempts` bumped) —
+ * so a transient dispatch failure self-heals on the following sweep. v1 is
+ * acyclic-only: the idemKey pins `(cardId, stageId, version)`, so a re-claim
+ * only ever re-runs a FAILED attempt of the current stage, never a completed one.
  */
 interface StageRun {
     /** Idempotency key (`cardId:stageId:configVersion`; stageId = immutable id). UNIQUE. */
@@ -427,6 +441,19 @@ interface StageRun {
     executionUuid?: string;
     /** Error message (when failed). */
     error?: string;
+    /**
+     * Dispatch attempt count (design §10 — stranded-run recovery). `1` on first
+     * claim; incremented each time `beginStageRun` RE-CLAIMS a stranded
+     * (failed/stale-queued) run. Optional/back-compat — a host that doesn't track
+     * re-claims leaves it undefined; surfaced for the sweep digest + observability.
+     *
+     * v1 RECORDS attempts but does NOT cap them: self-heal is bounded by the
+     * CADENCE (one re-dispatch per sweep tick), not a max-attempts ceiling, so a
+     * transient outage recovers while a genuinely poison card simply re-fails once
+     * per tick (visible via this counter). A retry ceiling / backoff is a
+     * deliberate follow-on, not v1.
+     */
+    attempts?: number;
     /** When the run intent was created (ISO string). */
     createdAt: string;
 }
@@ -480,7 +507,12 @@ interface ApplyTransitionInput {
  *
  * 2. `beginStageRun` is a CAS insert keyed on `idemKey` (UNIQUE). It returns
  *    `{ created: true, run }` on first insert and `{ created: false, run }`
- *    when the key already exists — so a retried dispatch is a no-op.
+ *    when a NON-reclaimable run already exists — so a retried dispatch is a
+ *    no-op. A `failed` or STALE `queued` run is RE-CLAIMED (reset to `queued`
+ *    → `{ created: true }`) so a transient dispatch failure self-heals on the
+ *    next sweep (design §10 — stranded-run recovery); a `running`/`completed`
+ *    run is never re-claimed. v1 is acyclic-only: the idemKey pins
+ *    `(cardId, stageId, version)`, so a re-claim only re-runs a FAILED attempt.
  *
  * 3. `completeStageRun` runs in ONE transaction: mark the stage run completed
  *    AND `applyTransition` to `toLane` together; it returns `{ applied: false }`
@@ -594,11 +626,42 @@ interface KanbanStorageAdapter {
      */
     capabilities?(): AdapterCapabilities;
     /**
-     * CAS-insert a stage-run intent keyed on `idemKey` (UNIQUE).
+     * CAS-insert a stage-run intent keyed on `idemKey` (UNIQUE), with
+     * FAILED/STALE-QUEUED RE-CLAIM (design §10 — stranded-run recovery).
+     *
+     * @returns `{ created: true, run }` when this call OWNS the dispatch — either
+     * a first insert, OR a RE-CLAIM of an existing run left `failed` (a prior
+     * dispatch threw → `failStageRun`) or stale `queued` (a process died between
+     * begin and dispatch): the adapter resets that run to a fresh `queued` intent
+     * (clearing the stale error/executionUuid, bumping `attempts`) and the engine
+     * dispatches again. `{ created: false, run }` when a NON-reclaimable run
+     * already exists (`running` — mid-flight; or `completed`) — the engine treats
+     * this as "already dispatched"/terminal and does NOT re-invoke the handler.
+     *
+     * A host implements the re-claim as a single conditional write (e.g. an
+     * `UPDATE stage_run SET status='queued', attempts=attempts+1, created_at=now(),
+     * error=NULL, execution_uuid=NULL WHERE idem_key=$1 AND (status='failed' OR
+     * (status='queued' AND created_at < $stale)) RETURNING …`, alongside the plain
+     * CAS insert).
      *
-     * @returns `{ created: true, run }` on first insert; `{ created: false, run }`
-     * when the key already exists (the engine treats this as "already
-     * dispatched" and does NOT re-invoke the handler).
+     * ⚠ CRITICAL for the "two overlapping ticks never both win" guarantee: the SET
+     * MUST move the row OUT of its own WHERE range — reset the `created_at`
+     * discriminator (as shown). Under READ COMMITTED, a concurrent tick's UPDATE
+     * blocks on the row lock, then RE-CHECKS its WHERE against the just-committed
+     * row: with `created_at=now()` the stale-queued predicate no longer matches, so
+     * it updates 0 rows (RETURNING empty → `created:false`). A naive
+     * `SET status='queued'` that leaves `created_at` UNCHANGED is the trap — both
+     * ticks still match the same stale `queued` row and BOTH re-dispatch. (The
+     * in-memory reference adapter resets `createdAt` for exactly this reason.)
+     * Equivalently, claim via a `SELECT … FOR UPDATE SKIP LOCKED` subselect. The
+     * staleness horizon MUST comfortably exceed the host's dispatch timeout so a
+     * genuinely in-flight `queued` row (mid dispatch call) is never re-claimed out
+     * from under it.
+     *
+     * v1 scope is ACYCLIC flows only: because the idemKey embeds
+     * `(cardId, stageId, version)`, a card can never legitimately re-enter the same
+     * stage at the same version, so a re-claim only ever re-runs a FAILED attempt
+     * of the current stage — it never re-executes a completed one.
      */
     beginStageRun(cardId: string, r: {
         stageId: string;
@@ -625,7 +688,12 @@ interface KanbanStorageAdapter {
         applied: boolean;
     }>;
     /**
-     * Mark a stage run failed (surfaced + retryable). Does NOT advance the card.
+     * Mark a stage run failed (surfaced). Does NOT advance the card — it stays in
+     * its lane. The engine calls this when a stage DISPATCH throws (design §10 —
+     * stranded-run recovery), so the run is left `failed` (NOT a stranded `queued`
+     * row the CAS would skip forever) and is RE-CLAIMED by the next
+     * `beginStageRun` on the following sweep. A `completed` run is never clobbered
+     * (a late failure after a success is a no-op — idempotent).
      */
     failStageRun(idemKey: string, f: {
         error: string;
@@ -805,6 +873,13 @@ interface WireHandler {
     type?: string;
     agent_uuid?: string;
     team_uuid?: string;
+    /**
+     * remote_agent → the `remote_agents.uuid` for a `remote_agent` lane (§5.3).
+     * Snake-cased on the wire (published JSONB); mapped to `remoteAgentUuid`.
+     * WITHOUT this the binding is silently dropped at parse and every published
+     * remote_agent lane fails dispatch with "missing remoteAgentUuid" (FINDING-6).
+     */
+    remote_agent_uuid?: string;
     /** Legacy p28 slug ref. */
     agent_ref?: string;
     webhook?: {
@@ -994,6 +1069,14 @@ interface RunAgentInput {
     input: Record<string, unknown>;
     /** Idempotency key (= cardId:stageId:version). */
     idemKey: string;
+    /**
+     * Board/headless dispatch forces allowAskUser=false (spec §6.5 / FINDING-5).
+     * The engine only ever dispatches cadra_agent stages from board surfaces,
+     * which have NO ask_user UI — an ask attempt must FAIL the execution (→ failed
+     * callback → completion bridge → §10 reclaim), never pause it. Pinned `false`
+     * at the type boundary, matching RunRemoteAgentInput.
+     */
+    allowAskUser: false;
     /** A host callback reference the run can advance through (optional). */
     callbackRef?: string;
 }
@@ -1003,6 +1086,8 @@ interface RunTeamInput {
     orgId?: number;
     input: Record<string, unknown>;
     idemKey: string;
+    /** Board/headless dispatch forces allowAskUser=false (spec §6.5 / FINDING-5). */
+    allowAskUser: false;
     callbackRef?: string;
 }
 interface RunRemoteAgentInput {
@@ -1196,6 +1281,20 @@ declare class InMemoryStorageAdapter implements KanbanStorageAdapter {
     private cards;
     private logs;
     private runs;
+    /**
+     * A `queued` stage-run older than this (ms) is STALE and re-claimable by
+     * `beginStageRun` (design §10) — it models a run whose process died between
+     * `beginStageRun` and dispatch, so `failStageRun` never ran. A `failed` run is
+     * re-claimable regardless of age. Must comfortably exceed the dispatch time so
+     * a genuinely in-flight `queued` run is never re-claimed out from under it.
+     */
+    private readonly staleQueuedMs;
+    /** Injectable clock (ms) — real hosts use `Date.now`; tests pin it. */
+    private readonly now;
+    constructor(opts?: {
+        staleQueuedMs?: number;
+        now?: () => number;
+    });
     listCards(boardConfigUuid: string): Promise<KanbanCard[]>;
     getCard(cardId: string): Promise<KanbanCard | null>;
     createCard(input: CreateCardServerInput): Promise<KanbanCard>;
@@ -1219,6 +1318,13 @@ declare class InMemoryStorageAdapter implements KanbanStorageAdapter {
         created: boolean;
         run: StageRun;
     }>;
+    /**
+     * A stranded stage-run the next `beginStageRun` may re-claim (design §10): a
+     * `failed` run (dispatch threw), or a `queued` run older than `staleQueuedMs`
+     * (a process died before dispatch flipped it). `running`/`completed` runs are
+     * never re-claimed.
+     */
+    private isReclaimable;
     completeStageRun(idemKey: string, c: {
         executionUuid?: string;
         toLane?: string;

package/dist/kanban/engine/index.js

@@ -10,6 +10,10 @@ function mapHandler(h) {
     type: h.type,
     agentUuid: h.agent_uuid,
     teamUuid: h.team_uuid,
+    // FINDING-6: carry the remote_agent binding through the wire parse. The
+    // engine's remote_agent dispatch reads `remoteAgentUuid`; dropping it here
+    // made every published remote_agent lane dispatch-dead.
+    remoteAgentUuid: h.remote_agent_uuid,
     agentRef: h.agent_ref,
     webhook: h.webhook ? {
       url: h.webhook.url,
@@ -319,6 +323,8 @@ async function dispatchStageHandler(ctx, cadra, webhookOpts) {
         orgId: ctx.orgId,
         input: ctx.input,
         idemKey: runIdemKey,
+        // Board/headless dispatch always disables ask_user (spec §6.5 / FINDING-5).
+        allowAskUser: false,
         callbackRef: ctx.callbackUrl
       });
       return { dispatched: true, executionUuid };
@@ -332,6 +338,8 @@ async function dispatchStageHandler(ctx, cadra, webhookOpts) {
         orgId: ctx.orgId,
         input: ctx.input,
         idemKey: runIdemKey,
+        // Board/headless dispatch always disables ask_user (spec §6.5 / FINDING-5).
+        allowAskUser: false,
         callbackRef: ctx.callbackUrl
       });
       return { dispatched: true, executionUuid };
@@ -382,10 +390,25 @@ function nextId(prefix) {
   idSeq += 1;
   return `${prefix}-${idSeq}`;
 }
+var DEFAULT_STALE_QUEUED_MS = 15 * 6e4;
 var InMemoryStorageAdapter = class {
   cards = /* @__PURE__ */ new Map();
   logs = /* @__PURE__ */ new Map();
   runs = /* @__PURE__ */ new Map();
+  /**
+   * A `queued` stage-run older than this (ms) is STALE and re-claimable by
+   * `beginStageRun` (design §10) — it models a run whose process died between
+   * `beginStageRun` and dispatch, so `failStageRun` never ran. A `failed` run is
+   * re-claimable regardless of age. Must comfortably exceed the dispatch time so
+   * a genuinely in-flight `queued` run is never re-claimed out from under it.
+   */
+  staleQueuedMs;
+  /** Injectable clock (ms) — real hosts use `Date.now`; tests pin it. */
+  now;
+  constructor(opts) {
+    this.staleQueuedMs = opts?.staleQueuedMs ?? DEFAULT_STALE_QUEUED_MS;
+    this.now = opts?.now ?? (() => Date.now());
+  }
   // ----- Cards -----
   async listCards(boardConfigUuid) {
     return [...this.cards.values()].filter((c) => c.boardConfigUuid === boardConfigUuid).map((c) => this.publicCard(c));
@@ -485,18 +508,48 @@ var InMemoryStorageAdapter = class {
   // ----- Stage runs -----
   async beginStageRun(cardId, r) {
     const existing = this.runs.get(r.idemKey);
-    if (existing) return { created: false, run: { ...existing } };
+    if (existing) {
+      if (this.isReclaimable(existing)) {
+        const run2 = {
+          idemKey: r.idemKey,
+          cardId,
+          stageId: r.stageId,
+          handlerType: r.handlerType,
+          status: "queued",
+          attempts: (existing.attempts ?? 1) + 1,
+          createdAt: new Date(this.now()).toISOString()
+        };
+        this.runs.set(r.idemKey, run2);
+        return { created: true, run: { ...run2 } };
+      }
+      return { created: false, run: { ...existing } };
+    }
     const run = {
       idemKey: r.idemKey,
       cardId,
       stageId: r.stageId,
       handlerType: r.handlerType,
       status: "queued",
-      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+      attempts: 1,
+      createdAt: new Date(this.now()).toISOString()
     };
     this.runs.set(r.idemKey, run);
     return { created: true, run: { ...run } };
   }
+  /**
+   * A stranded stage-run the next `beginStageRun` may re-claim (design §10): a
+   * `failed` run (dispatch threw), or a `queued` run older than `staleQueuedMs`
+   * (a process died before dispatch flipped it). `running`/`completed` runs are
+   * never re-claimed.
+   */
+  isReclaimable(run) {
+    if (run.status === "failed") return true;
+    if (run.status === "queued") {
+      const age = this.now() - Date.parse(run.createdAt);
+      return Number.isFinite(age) && age >= this.staleQueuedMs;
+    }
+    return false;
+  }
   async completeStageRun(idemKey, c) {
     const run = this.runs.get(idemKey);
     if (!run) throw new Error(`No stage run for idemKey ${idemKey}`);
@@ -1191,6 +1244,14 @@ function runAdapterConformance(makeAdapter, runner) {
       expect(still.lane).toBe("generate");
     });
     const asConductor = (adapter) => adapter.listDueCards && adapter.countsByLane && adapter.capabilities ? adapter : null;
+    const supportsField = (adapter, field) => {
+      const fields = adapter.capabilities().dueRuleFields;
+      return fields.includes("*") || fields.includes(field);
+    };
+    const supportsPredicate = (adapter, ref) => {
+      const preds = adapter.capabilities().dueRulePredicates;
+      return preds.includes("*") || preds.includes(ref);
+    };
     it("listDueCards {kind:'always'} returns every card in the lane", async () => {
       const base = await makeAdapter();
       const adapter = asConductor(base);
@@ -1222,6 +1283,7 @@ function runAdapterConformance(makeAdapter, runner) {
       const base = await makeAdapter();
       const adapter = asConductor(base);
       if (!adapter) return;
+      if (!supportsField(adapter, "next_touch_at")) return;
       const past = new Date(Date.now() - 6e4).toISOString();
       const future = new Date(Date.now() + 6e4).toISOString();
       await seedCard(adapter, "scheduled", "due", { next_touch_at: past });
@@ -1243,6 +1305,7 @@ function runAdapterConformance(makeAdapter, runner) {
       const base = await makeAdapter();
       const adapter = asConductor(base);
       if (!adapter) return;
+      if (!supportsPredicate(adapter, "status")) return;
       await seedCard(adapter, "queued", "approved", { status: "approved" });
       await seedCard(adapter, "queued", "draft", { status: "draft" });
       const rule = {
@@ -1259,6 +1322,8 @@ function runAdapterConformance(makeAdapter, runner) {
       const base = await makeAdapter();
       const adapter = asConductor(base);
       if (!adapter) return;
+      if (!supportsField(adapter, "next_touch_at") || !supportsPredicate(adapter, "status"))
+        return;
       const past = new Date(Date.now() - 6e4).toISOString();
       const future = new Date(Date.now() + 6e4).toISOString();
       await seedCard(adapter, "queued", "send-me", {
@@ -1521,20 +1586,28 @@ function createEngine(options) {
     if (!begin.created) {
       return { dispatched: false, executionUuid: begin.run.executionUuid };
     }
-    const result = await dispatchStageHandler(
-      {
-        cardId,
-        boardConfigUuid: card.boardId,
-        configVersion: cfg.version,
-        stage,
-        idemKey,
-        input: cardContext(card, stage),
-        orgId: options.orgId,
-        callbackUrl
-      },
-      cadraClient,
-      webhookOptions
-    );
+    let result;
+    try {
+      result = await dispatchStageHandler(
+        {
+          cardId,
+          boardConfigUuid: card.boardId,
+          configVersion: cfg.version,
+          stage,
+          idemKey,
+          input: cardContext(card, stage),
+          orgId: options.orgId,
+          callbackUrl
+        },
+        cadraClient,
+        webhookOptions
+      );
+    } catch (err) {
+      await adapter.failStageRun(idemKey, {
+        error: err instanceof Error ? err.message : String(err)
+      });
+      throw err;
+    }
     if (result.executionUuid && adapter.markStageRunDispatched) {
       await adapter.markStageRunDispatched(idemKey, {
         executionUuid: result.executionUuid
@@ -1603,21 +1676,30 @@ function createEngine(options) {
     }));
     batchMembers.set(batchKey, batchCards.map((c) => c.idemKey));
     const lead = eligible[0].card;
-    const result = await dispatchStageHandler(
-      {
-        cardId: lead.id,
-        boardConfigUuid: lead.boardId,
-        configVersion: cfg.version,
-        stage,
-        idemKey: eligible[0].idemKey,
-        input: batchContext(lead, stage, batchCards),
-        orgId: options.orgId,
-        callbackUrl,
-        batch: { batchKey, cards: batchCards }
-      },
-      cadraClient,
-      webhookOptions
-    );
+    let result;
+    try {
+      result = await dispatchStageHandler(
+        {
+          cardId: lead.id,
+          boardConfigUuid: lead.boardId,
+          configVersion: cfg.version,
+          stage,
+          idemKey: eligible[0].idemKey,
+          input: batchContext(lead, stage, batchCards),
+          orgId: options.orgId,
+          callbackUrl,
+          batch: { batchKey, cards: batchCards }
+        },
+        cadraClient,
+        webhookOptions
+      );
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      for (const { idemKey } of eligible) {
+        await adapter.failStageRun(idemKey, { error: msg });
+      }
+      throw err;
+    }
     if (result.executionUuid && adapter.markStageRunDispatched) {
       for (const { idemKey } of eligible) {
         await adapter.markStageRunDispatched(idemKey, {