@cadraos/sdk 0.3.8 → 0.3.9

package/dist/board-host/index.d.cts

@@ -318,6 +318,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). */
@@ -414,6 +421,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. */
@@ -430,6 +444,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;
 }
@@ -483,7 +510,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 }`
@@ -597,11 +629,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).
+     *
+     * ⚠ 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.
      *
-     * @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).
+     * 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;
@@ -628,7 +691,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;

package/dist/board-host/index.d.ts

@@ -318,6 +318,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). */
@@ -414,6 +421,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. */
@@ -430,6 +444,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;
 }
@@ -483,7 +510,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 }`
@@ -597,11 +629,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).
+     *
+     * ⚠ 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.
      *
-     * @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).
+     * 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;
@@ -628,7 +691,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;

package/dist/board-host/server/index.d.cts

@@ -548,6 +548,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). */
@@ -644,6 +651,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. */
@@ -660,6 +674,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;
 }
@@ -713,7 +740,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 }`
@@ -827,11 +859,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 }` 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).
+     * @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).
+     *
+     * ⚠ 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;
@@ -858,7 +921,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;
@@ -1310,6 +1378,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?: {

package/dist/board-host/server/index.d.ts

@@ -548,6 +548,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). */
@@ -644,6 +651,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. */
@@ -660,6 +674,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;
 }
@@ -713,7 +740,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 }`
@@ -827,11 +859,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 }` 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).
+     * @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).
+     *
+     * ⚠ 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;
@@ -858,7 +921,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;
@@ -1310,6 +1378,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?: {

package/dist/chat/index.cjs

@@ -689,15 +689,6 @@ var ExecutionStreamControllerImpl = class {
   sseClient = null;
   status = "connecting";
   reconnectAttempts = 0;
-  // CAD-39 / webchat dual-plane create-connect race. `hasConnected` flips true on
-  // the first successful SSE open; `notFoundRetries` bounds retries of a 404
-  // encountered BEFORE we ever connect (the run row is persisted slightly AFTER
-  // the client opens the stream — the norm on the webchat path where msg-api owns
-  // the executionId and cadra persists the agent_executions row via an async
-  // worker callback). See handleConnectionError.
-  hasConnected = false;
-  notFoundRetries = 0;
-  maxConnectRaceRetries = 3;
   seenEventIds = /* @__PURE__ */ new Set();
   _lastEventId = null;
   activityTimeoutId = null;
@@ -837,8 +828,6 @@ var ExecutionStreamControllerImpl = class {
         if (connected) {
           this.status = "connected";
           this.reconnectAttempts = 0;
-          this.hasConnected = true;
-          this.notFoundRetries = 0;
           this.resetActivityTimeout();
         }
         this.emit("connectionChange", { connected, usingFallback: false });
@@ -1128,38 +1117,6 @@ var ExecutionStreamControllerImpl = class {
       return;
     }
     const msg = error instanceof Error ? error.message : String(error);
-    const isNotFound = /\b404\b/.test(msg);
-    const isAuthFailure = /\b40[13]\b/.test(msg) || /INVALID_API_KEY|INVALID_REQUEST/.test(msg);
-    if (isNotFound && !isAuthFailure && !this.hasConnected) {
-      if (this.notFoundRetries < this.maxConnectRaceRetries) {
-        this.notFoundRetries++;
-        this.status = "reconnecting";
-        const delay = Math.min(
-          this.config.reconnectBaseDelayMs * this.notFoundRetries,
-          this.config.reconnectMaxDelayMs
-        );
-        await new Promise((resolve) => setTimeout(resolve, delay));
-        if (this.status === "closed") {
-          return;
-        }
-        try {
-          await this.connectSSE();
-        } catch (retryError) {
-          await this.handleConnectionError(retryError);
-        }
-        return;
-      }
-      if (this.pollingEnabled) {
-        if (this.sseClient) {
-          this.sseClient.disconnect();
-          this.sseClient = null;
-        }
-        this.status = "fallback_polling";
-        this.emit("connectionChange", { connected: false, usingFallback: true });
-        this.startPolling();
-        return;
-      }
-    }
     if (/\b4\d\d\b/.test(msg) || /INVALID_API_KEY|INVALID_REQUEST/.test(msg)) {
       if (this.sseClient) {
         this.sseClient.disconnect();
@@ -1409,6 +1366,7 @@ var AgentsAPI = class extends BaseResourceAPI {
     super(http, "/api/v1/agents");
     this.getStreamConfig = getStreamConfig;
   }
+  getStreamConfig;
   // ===== LIST Operations =====
   /**
    * List all agents in the organization
@@ -2314,6 +2272,7 @@ var SessionsAPI = class extends BaseResourceAPI {
     super(http, "/api/v1/sessions");
     this.getStreamConfig = getStreamConfig;
   }
+  getStreamConfig;
   // ===== LIST Operations =====
   /**
    * List all sessions in the organization
@@ -2633,6 +2592,7 @@ var KanbanAPI = class extends BaseResourceAPI {
     super(http, "/api/v1/kanban");
     this.getStreamConfig = getStreamConfig;
   }
+  getStreamConfig;
   // ===== BOARD =====
   /**
    * Get the current org's board (lanes in declared order). Auto-provisions
@@ -2834,6 +2794,7 @@ var RemoteAgentsAPI = class extends BaseResourceAPI {
     super(http, "/api/v1/remote-agents");
     this.getStreamConfig = getStreamConfig;
   }
+  getStreamConfig;
   /**
    * List all remote agents in the organization
    *
@@ -8637,8 +8598,7 @@ function AgentChat({
   hideHeaderWhileEmpty = false,
   hideTypingIndicator = false,
   onInputChange,
-  onInputControlReady,
-  injectedMessages
+  onInputControlReady
 }) {
   const {
     messages,
@@ -8702,9 +8662,8 @@ function AgentChat({
     },
     [enableAttachments, attachments, sendMessage]
   );
-  const renderedMessages = injectedMessages && injectedMessages.length > 0 ? [...messages, ...injectedMessages].filter((m, i, arr) => arr.findIndex((x) => x.id === m.id) === i).sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime()) : messages;
   const messageListProps = {
-    messages: renderedMessages,
+    messages,
     welcomeMessage: hideHeader ? void 0 : welcomeMessage,
     renderWelcome: hideHeader ? void 0 : renderWelcome,
     isLoading,