@cadraos/sdk 0.3.8 → 0.3.10

package/dist/kanban/index.d.cts

@@ -1,4 +1,5 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
 
 /**
  * Shared kanban types for the @cadraos/sdk/kanban module.
@@ -317,6 +318,13 @@ interface KanbanCard$1 {
     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). */
@@ -455,6 +463,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. */
@@ -471,6 +486,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;
 }
@@ -664,6 +692,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?: {
@@ -1605,6 +1640,11 @@ interface KanbanAdapter {
      * @returns The updated card.
      */
     transitionCard(input: TransitionCardInput): Promise<KanbanCard$1>;
+    /**
+     * Delete a card permanently. OPTIONAL — when absent, the board offers no
+     * delete affordance (back-compat). Server-authorized + org-scoped.
+     */
+    deleteCard?(cardId: string): Promise<void>;
     /**
      * Create an `ExecutionStreamController` for a card's run, keyed on the
      * card's `executionId`.
@@ -1623,6 +1663,77 @@ interface KanbanAdapter {
     createRunStream?(executionId: string): ExecutionStreamController;
 }
 
+interface ScheduleStatusProps {
+    /** Next scheduled sweep (ISO string) → the "next run in {t}" countdown. */
+    nextTickAt?: string;
+    /** Per-lane due counts (lane key → # of due cards) — powers "· {n} due". */
+    dueByLane?: Record<string, number>;
+    /**
+     * Override the leading status label. Defaults to "On schedule" (`on-schedule`
+     * tone), "Paused" (`paused`), or "Running now" (`due`).
+     */
+    label?: string;
+    /** Status tone → drives the dot colour + default label. Default `on-schedule`. */
+    tone?: "on-schedule" | "due" | "paused";
+    /** Additional CSS class. */
+    className?: string;
+}
+/**
+ * Render the calm schedule-status line.
+ */
+declare function ScheduleStatus({ nextTickAt, dueByLane, label, tone, className, }: ScheduleStatusProps): react_jsx_runtime.JSX.Element;
+
+/** The kind of agent bound to a lane — drives the picker's leading icon. */
+type LaneAgentKind = "cadra" | "remote" | "human";
+/** A selectable agent option for a lane. */
+interface LaneAgentOption {
+    /** Stable agent id (Cadra agent/team uuid, remote runner id, or "human"). */
+    id: string;
+    /** Display name, e.g. "Cadra · Lead Sourcer" or "My desktop agent". */
+    label: string;
+    /** Agent kind — icon + semantics. Default `cadra`. */
+    kind?: LaneAgentKind;
+    /**
+     * Connection state for a `remote` agent (desktop/ACP). `true` → online dot,
+     * `false` → offline dot + the lane will pause. Omit for always-on agents.
+     */
+    online?: boolean;
+}
+interface LaneAgentPickerProps {
+    /** The currently-assigned agent (display). */
+    selected?: LaneAgentOption;
+    /** The agents the owner may pick from. */
+    options?: LaneAgentOption[];
+    /** Fired when the owner assigns an agent to this lane. */
+    onSelect?: (agentId: string) => void;
+    /**
+     * Owner gate (M10 / §14). When `false`, the picker is LOCKED (read-only + a
+     * visible reason). Defaults to `true`; an editable picker still needs
+     * `onSelect` + `options` to actually open.
+     */
+    canEdit?: boolean;
+    /**
+     * The visible reason shown under a locked picker (IS-6), e.g.
+     * "Only Ava (owner) can change agents". Rendered as text, never a tooltip.
+     */
+    lockedReason?: string;
+    /**
+     * MV3 (optional, additive). When provided AND an agent is `selected`, the
+     * open menu shows an "Edit this agent" footer action; clicking it calls
+     * `onEditAgent(selected.id)` and closes the menu. The HOST owns the edit
+     * surface (e.g. an in-shell sheet) — the picker only fires the intent.
+     * Omit → today's render, unchanged.
+     */
+    onEditAgent?: (agentId: string) => void;
+    /** Additional CSS class. */
+    className?: string;
+}
+/**
+ * Render the lane agent picker — interactive for owners, locked-with-reason for
+ * members.
+ */
+declare function LaneAgentPicker({ selected, options, onSelect, canEdit, lockedReason, onEditAgent, className, }: LaneAgentPickerProps): react_jsx_runtime.JSX.Element;
+
 interface KanbanBoardProps {
     /** The adapter driving the board (default HTTP or a custom direct adapter). */
     adapter: KanbanAdapter;
@@ -1663,13 +1774,108 @@ interface KanbanBoardProps {
      * Default off (undefined).
      */
     pollIntervalMs?: number;
+    /**
+     * Server-aggregate card counts per lane KEY (spec §3a, `countsByLane`). Drives
+     * each lane header's count pill + cap meter (the rendered array may be a
+     * page). Absent → headers show the rendered `cards.length`.
+     */
+    laneCounts?: Record<string, number>;
+    /**
+     * Owner gate for per-lane agent pickers (M10 / §14). When `false`, every
+     * lane's picker renders LOCKED (read-only + a visible reason). Passed to each
+     * column as the default `canEdit`. Default `true`.
+     */
+    canEditHandlers?: boolean;
+    /**
+     * Resolve the agent-picker slot for a lane — "Cadra agent | My desktop agent"
+     * (§12 wireframe). Return `undefined` for lanes with no picker. Owner-gated by
+     * `canEditHandlers` unless the slot sets its own `canEdit`. Absent → no picker.
+     */
+    laneAgentPicker?: (lane: KanbanLane) => LaneAgentPickerProps | undefined;
+    /**
+     * The calm schedule-status strip rendered ABOVE the board — "On schedule ·
+     * next run in 10m" (spec §6 ScheduleStatus; carries `nextTickAt` + `dueByLane`).
+     * NEVER the word "Conductor" (M2). Absent → no strip.
+     */
+    scheduleStatus?: ScheduleStatusProps;
+    /**
+     * Host-driven card focus (p45 STORY-011): when set (or changed), the board
+     * OPENS this card's drawer — powering a deep-link (the cockpit `Review`
+     * ?card= target) and the activity-rail `Review` primary. `openCard` fetches
+     * the card via `adapter.getCard`, so the target need NOT be in the loaded
+     * page. Absent → no auto-open (today's behavior, M10). Re-set the SAME id (or
+     * change it) to re-open after the user closes the drawer.
+     */
+    focusCardId?: string;
+    /**
+     * Replace the built-in `CardDrawer` with a HOST-owned drawer (work-shell v2,
+     * Screen C). When provided, the board renders `renderCardDrawer(ctx)` instead
+     * of its internal drawer whenever a card is selected — the host owns the
+     * tabbed Run/Context/Activity/Steer presentation while the board still owns
+     * selection state (`focusCardId`, click-to-open, close). Absent → today's
+     * internal drawer (M10 back-compat; yobo + the test harness are unchanged).
+     *
+     * The context carries everything the internal drawer receives, so the host
+     * drawer can advance/transition/retry/edit the card and react to run-terminal
+     * exactly as the built-in one does.
+     */
+    renderCardDrawer?: (ctx: CardDrawerRenderContext) => ReactNode;
+    /**
+     * Enable HTML5 drag-to-move cards between lanes (work-shell v2 / MV4). A card
+     * can only be dropped on a lane reachable by a `manualAllowed` transition from
+     * its current lane — allowed lanes highlight, others refuse the drop. The move
+     * commits through the same `transitionCard` path as the drawer (server
+     * re-validates). OPTIONAL — absent → no drag (today's render, M10). Requires
+     * `enableAdvance` (the transitions that gate drops come from the same source).
+     */
+    enableDrag?: boolean;
     /** Additional CSS class for the board container. */
     className?: string;
 }
+/**
+ * Everything a HOST-owned card drawer needs — mirrors the props the built-in
+ * `CardDrawer` receives (work-shell v2 Screen C seam). The board owns selection;
+ * the host owns rendering.
+ */
+interface CardDrawerRenderContext {
+    /** The currently open card. */
+    card: KanbanCard$1;
+    /** The adapter (provides `getCard`, the run-stream factory, etc.). */
+    adapter: KanbanAdapter;
+    /** All lanes (for resolving transition target labels + human-gate detection). */
+    lanes: KanbanLane[];
+    /**
+     * The lifecycle's declared edges — filter to `fromLane === card.lane &&
+     * manualAllowed` for the "Move to a step" targets. Undefined when advance is
+     * disabled.
+     */
+    transitions?: KanbanTransition[];
+    /** Whether the card can be advanced (false in a terminal lane). */
+    canAdvance: boolean;
+    /** Close the drawer (clears the board's selection). */
+    onClose: () => void;
+    /** Re-dispatch a failed card. Absent when the host supplied no `onRetryCard`. */
+    onRetry?: (card: KanbanCard$1) => void;
+    /** Persist an inline title/description edit. Absent when `enableEdit` is false. */
+    onUpdate?: (cardId: string, patch: {
+        title?: string;
+        description?: string;
+    }) => void | Promise<void | unknown>;
+    /** Auto-advance a single-edge lane. Absent when `enableAdvance` is false. */
+    onAdvance?: (cardId: string) => void | Promise<void | unknown>;
+    /** Take a specific manual transition. Absent when `enableAdvance` is false. */
+    onTransition?: (cardId: string, toLane: string) => void | Promise<void | unknown>;
+    /** Delete this card permanently. Absent when the adapter has no `deleteCard`. */
+    onDelete?: (cardId: string) => Promise<boolean>;
+    /** Fired when the card's run reaches a terminal state (host should refetch). */
+    onRunTerminal?: (status: "completed" | "failed") => void;
+    /** Fired on a non-throwing run/board error. */
+    onError?: (message: string) => void;
+}
 /**
  * Drop-in agent-first kanban board.
  */
-declare function KanbanBoard({ adapter, onCreateCard, onRetryCard, onError, onCardCreated, enableCreate, enableEdit, enableAdvance, pollIntervalMs, className, }: KanbanBoardProps): react_jsx_runtime.JSX.Element;
+declare function KanbanBoard({ adapter, onCreateCard, onRetryCard, onError, onCardCreated, enableCreate, enableEdit, enableAdvance, pollIntervalMs, laneCounts, canEditHandlers, laneAgentPicker, scheduleStatus, focusCardId, renderCardDrawer, enableDrag, className, }: KanbanBoardProps): react_jsx_runtime.JSX.Element;
 
 /**
  * The host's BROWSER-SIDE card source. The host implements these against its
@@ -1691,6 +1897,8 @@ interface AgentBoardCardSource {
     }): Promise<KanbanCard$1>;
     /** Request a manual transition → host engine validates + advances. */
     transitionCard(input: TransitionCardInput): Promise<KanbanCard$1>;
+    /** Delete a card permanently. OPTIONAL — absent → no delete affordance. */
+    deleteCard?(cardId: string): Promise<void>;
     /**
      * Create an `ExecutionStreamController` for a card's run (the SAME controller
      * the chat module uses). Optional — when absent, the drawer falls back to the
@@ -1748,14 +1956,54 @@ interface KanbanColumnProps {
     onCreateCard?: (lane: KanbanLane) => void;
     /** Whether to show the "+ New card" affordance on this column. */
     showCreate?: boolean;
+    /**
+     * SERVER-aggregate card count for the header pill + cap meter (spec §3a,
+     * `countsByLane`). The rendered array may be a page; this is the true total.
+     * OPTIONAL — absent → the header shows `cards.length` (today's render).
+     */
+    count?: number;
+    /**
+     * The per-lane agent-picker slot (spec §6). Rendered in the lane header when
+     * supplied; owner-gating comes from the slot's own `canEdit` or the
+     * board-level `canEditHandlers`. OPTIONAL — absent → no picker.
+     */
+    agentPicker?: LaneAgentPickerProps;
+    /**
+     * Board-level owner gate for lane pickers (M10). Used as the default
+     * `canEdit` for `agentPicker` when the slot doesn't set its own.
+     */
+    canEditHandlers?: boolean;
+    /** Make this column's cards draggable sources. */
+    draggableCards?: boolean;
+    /** A drag is in progress somewhere on the board (drives the dimming of
+     * non-target lanes). */
+    dragActive?: boolean;
+    /** This lane is a VALID drop target for the card currently being dragged
+     * (`manualAllowed` from its lane) — highlight + accept the drop. */
+    dropAllowed?: boolean;
+    /** Fired when a card in this column starts being dragged. */
+    onCardDragStart?: (card: KanbanCard$1) => void;
+    /** Fired when a drag ends (drop or cancel). */
+    onCardDragEnd?: () => void;
+    /** Fired when a card is dropped onto this lane (only when `dropAllowed`). */
+    onLaneDrop?: (lane: KanbanLane) => void;
     /** Additional CSS class. */
     className?: string;
 }
 /**
  * Render a single lane column with its cards.
  */
-declare function KanbanColumn({ lane, cards, onCardClick, selectedCardId, onCreateCard, showCreate, className, }: KanbanColumnProps): react_jsx_runtime.JSX.Element;
+declare function KanbanColumn({ lane, cards, onCardClick, selectedCardId, onCreateCard, showCreate, count, agentPicker, canEditHandlers, draggableCards, dragActive, dropAllowed, onCardDragStart, onCardDragEnd, onLaneDrop, className, }: KanbanColumnProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * A card's lane-relative schedule state (spec §3a), computed by the column from
+ * the card + its lane and passed down. OPTIONAL — absent → today's render.
+ *
+ * - `ready`   — run completed and awaiting the next lane (success chip).
+ * - `due`     — `next_due_at ≤ now`; the next sweep will pick it up (neutral).
+ * - `waiting` — sitting in a scheduled lane, not yet due (neutral).
+ */
+type DueState = "due" | "ready" | "waiting";
 interface KanbanCardProps {
     /** The card to render. */
     card: KanbanCard$1;
@@ -1763,13 +2011,30 @@ interface KanbanCardProps {
     onClick?: (card: KanbanCard$1) => void;
     /** Whether this card is currently selected/open. */
     selected?: boolean;
+    /**
+     * The card's lane-relative schedule state (spec §3a), supplied by the column.
+     * Drives the due/ready/waiting chips. OPTIONAL — absent → run-status chip only
+     * (today's render).
+     */
+    dueState?: DueState;
+    /**
+     * Make this card an HTML5 drag SOURCE (work-shell v2 / MV4). OPTIONAL —
+     * absent → not draggable (today's render, M10). The board decides where a
+     * drop is allowed (only `manualAllowed` targets); the card just reports the
+     * drag start/end.
+     */
+    draggable?: boolean;
+    /** Fired on drag start (draggable cards only). */
+    onDragStart?: (card: KanbanCard$1) => void;
+    /** Fired on drag end (draggable cards only). */
+    onDragEnd?: () => void;
     /** Additional CSS class. */
     className?: string;
 }
 /**
  * Render a single kanban card tile.
  */
-declare function KanbanCard({ card, onClick, selected, className }: KanbanCardProps): react_jsx_runtime.JSX.Element;
+declare function KanbanCard({ card, onClick, selected, dueState, draggable, onDragStart, onDragEnd, className, }: KanbanCardProps): react_jsx_runtime.JSX.Element;
 
 interface CardDrawerProps {
     /** The card to display, or null when the drawer is closed. */
@@ -1833,6 +2098,69 @@ interface CardDrawerProps {
  */
 declare function CardDrawer({ card, adapter, onClose, onRetry, onUpdate, onAdvance, canAdvance, transitions, lanes, onTransition, onRunTerminal, onError, className, }: CardDrawerProps): react_jsx_runtime.JSX.Element | null;
 
+interface CapMeterProps {
+    /** Current card count in the lane (server aggregate). */
+    count: number;
+    /** The lane's per-sweep cap. */
+    cap: number;
+    /** Additional CSS class. */
+    className?: string;
+}
+/**
+ * Render a lane capacity meter (`count/cap` + a filling track).
+ */
+declare function CapMeter({ count, cap, className }: CapMeterProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Internal styling helpers (inline — no clsx dependency).
+ *
+ * All board surfaces speak in SEMANTIC design tokens (p45 STORY-010): the
+ * board is a shared SDK component, so it must adopt the CONSUMER's active
+ * theme, never bake in a fixed palette. Tokens resolve per-theme via CSS
+ * variables (light/dark flip without `dark:` variants), and the status
+ * vocabulary is one-color-one-meaning (spec §3 crit F3):
+ *
+ * - `info`        → running / working
+ * - `success`     → ready / done / sent / on-schedule
+ * - `warning`     → needs-you / human gate (RESERVED — never for "due")
+ * - `destructive` → failed
+ * - `neutral`     → scheduled / due / waiting (machine will handle it)
+ *
+ * @module @cadraos/sdk/kanban
+ */
+/**
+ * Join truthy class names with a space.
+ */
+declare function cn(...classes: (string | undefined | false | null)[]): string;
+/**
+ * The badge/chip variants the board renders. Mirrors the shadcn `Badge` enum
+ * every consumer ships (`default | secondary | destructive | outline | success
+ * | warning`) PLUS the one new variant this story adds — `info` — for the
+ * load-bearing "running/working" chip (spec §6). `neutral` is NOT a new Badge
+ * variant: it composes the REAL `secondary` + `muted-foreground` tokens so the
+ * calm scheduled/due/waiting chips stay distinct from amber without inventing a
+ * `badge-muted` class (judge polish note 1).
+ */
+type BadgeVariant = "default" | "secondary" | "outline" | "destructive" | "success" | "warning" | "info" | "neutral";
+/**
+ * Token classes for a badge/chip variant. Colour only — the caller supplies the
+ * chip layout (rounded-full, padding, text size). Soft-tinted for the status
+ * variants (matching the mock's `hsl(var(--token)/.15)` fills) so they read as
+ * calm siblings, solid for `default`.
+ */
+declare function badgeVariantClass(variant: BadgeVariant): string;
+/**
+ * Visual tone for a run status badge (reworked to semantic tokens — STORY-010).
+ * Labels are unchanged; only the classes move from hardcoded palette to tokens.
+ * `pending`/`cancelled` map to the CALM `neutral` tone — amber is reserved for
+ * needs-you (F3), so a queued run never borrows the human-action colour.
+ */
+declare function runStatusTone(status: string | undefined): {
+    label: string;
+    variant: BadgeVariant;
+    className: string;
+};
+
 interface UseKanbanBoardOptions {
     /** The adapter driving all board/card operations. */
     adapter: KanbanAdapter;
@@ -1893,6 +2221,8 @@ interface UseKanbanBoardResult {
     }) => Promise<KanbanCard$1 | null>;
     /** Manually transition a card; refetches the board afterwards. */
     transitionCard: (input: TransitionCardInput) => Promise<KanbanCard$1 | null>;
+    /** Delete a card permanently (optimistic + rollback). Returns success. */
+    deleteCard: (cardId: string) => Promise<boolean>;
     /**
      * Called by the drawer when the open card's run reaches a terminal state.
      * Refetches the board (Spec-1 propagation contract).
@@ -4331,7 +4661,12 @@ declare function createDefaultKanbanAdapter(config: DefaultKanbanAdapterConfig):
  *
  * 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 }`
@@ -4445,11 +4780,42 @@ interface KanbanStorageAdapter {
      */
     capabilities?(): AdapterCapabilities;
     /**
-     * CAS-insert a stage-run intent keyed on `idemKey` (UNIQUE).
-     *
-     * @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).
+     * 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.
+     *
+     * 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;
@@ -4476,7 +4842,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;
@@ -4496,4 +4867,4 @@ interface KanbanStorageAdapter {
     getStageRun(idemKey: string): Promise<StageRun | null>;
 }
 
-export { type Actor, type AdapterCapabilities, AgentBoard, type AgentBoardCardSource, type AgentBoardProps, type ApplyTransitionInput, BoardConfigClient, type BoardConfigClientOptions, type BoardConfigHttp, CadraLifecycleSource, CardDrawer, type CardDrawerProps, type CardList, type CreateCardInput, type CreateCardServerInput, type DefaultKanbanAdapterConfig, type DueRule, type KanbanActorType, type KanbanAdapter, KanbanBoard, type KanbanBoard$1 as KanbanBoardData, type KanbanBoardProps, type KanbanCard$1 as KanbanCard, type KanbanCardProps, KanbanCard as KanbanCardTile, KanbanColumn, type KanbanColumnProps, type KanbanHandlerType, type KanbanLane, type KanbanLaneDispatch, type KanbanLaneHandler, type KanbanLaneTrigger, type KanbanRunStatus, type KanbanRunSummary, type KanbanStorageAdapter, type KanbanTransition, type KanbanWebhookBinding, type LifecycleRef, type LifecycleSource, type LifecycleSourceKind, type ListCardsInput, type ResolveLifecycleRef, type ResolvedBoardConfig, type ResolvedLifecycle, type Stage, type StageRun, type StageRunStatus, type Transition, type TransitionCardInput, type TransitionLogEntry, type UseCardRunOptions, type UseCardRunResult, type UseKanbanBoardOptions, type UseKanbanBoardResult, createDefaultKanbanAdapter, mapDefinitionToBoard, toResolvedLifecycle, useCardRun, useKanbanBoard };
+export { type Actor, type AdapterCapabilities, AgentBoard, type AgentBoardCardSource, type AgentBoardProps, type ApplyTransitionInput, type BadgeVariant, BoardConfigClient, type BoardConfigClientOptions, type BoardConfigHttp, CadraLifecycleSource, CapMeter, type CapMeterProps, CardDrawer, type CardDrawerProps, type CardDrawerRenderContext, type CardList, type CreateCardInput, type CreateCardServerInput, type DefaultKanbanAdapterConfig, type DueRule, type DueState, type KanbanActorType, type KanbanAdapter, KanbanBoard, type KanbanBoard$1 as KanbanBoardData, type KanbanBoardProps, type KanbanCard$1 as KanbanCard, type KanbanCardProps, KanbanCard as KanbanCardTile, KanbanColumn, type KanbanColumnProps, type KanbanHandlerType, type KanbanLane, type KanbanLaneDispatch, type KanbanLaneHandler, type KanbanLaneTrigger, type KanbanRunStatus, type KanbanRunSummary, type KanbanStorageAdapter, type KanbanTransition, type KanbanWebhookBinding, type LaneAgentKind, type LaneAgentOption, LaneAgentPicker, type LaneAgentPickerProps, type LifecycleRef, type LifecycleSource, type LifecycleSourceKind, type ListCardsInput, type ResolveLifecycleRef, type ResolvedBoardConfig, type ResolvedLifecycle, ScheduleStatus, type ScheduleStatusProps, type Stage, type StageRun, type StageRunStatus, type Transition, type TransitionCardInput, type TransitionLogEntry, type UseCardRunOptions, type UseCardRunResult, type UseKanbanBoardOptions, type UseKanbanBoardResult, badgeVariantClass, cn, createDefaultKanbanAdapter, mapDefinitionToBoard, runStatusTone, toResolvedLifecycle, useCardRun, useKanbanBoard };