@cadraos/sdk 0.3.14-p46.3 → 0.3.14

package/dist/kanban/engine/index.js

@@ -226,381 +226,6 @@ function parseHandoffVerdict(output) {
   }
 }
 
-// src/kanban/config-client.ts
-function isVersionRow(d) {
-  return !!d && typeof d === "object" && "definition" in d && !!d.definition;
-}
-function mapHandler(h) {
-  if (!h || !h.type || h.type === "none") {
-    return void 0;
-  }
-  return {
-    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,
-      headers: h.webhook.headers,
-      timeoutMs: h.webhook.timeout_ms,
-      retry: h.webhook.retry
-    } : void 0
-  };
-}
-function mapStage(s, index) {
-  const lane = {
-    // Carry the IMMUTABLE stage id through (p33 §10.2). It is what the
-    // webhook-secret fetch + the stage-run idemKey + the UI columns key off —
-    // a `key`/`label` rename never breaks dispatch or keying. `key` stays the
-    // editable display/slug.
-    id: s.id,
-    key: s.key,
-    label: s.name,
-    order: index,
-    handler: mapHandler(s.handler),
-    terminal: s.is_terminal ?? false,
-    initial: s.is_initial ?? false
-  };
-  if (s.trigger) lane.trigger = s.trigger;
-  if (s.due_rule != null) lane.dueRule = s.due_rule;
-  if (s.cap != null) lane.cap = s.cap;
-  if (s.dispatch) lane.dispatch = s.dispatch;
-  if (s.chunk_size != null) lane.chunkSize = s.chunk_size;
-  if (s.handoff === "off" || s.handoff === "verdict") lane.handoff = s.handoff;
-  return lane;
-}
-function mapTransition(t, idToKey) {
-  return {
-    id: t.id,
-    fromLane: idToKey.get(t.from_stage_id) ?? t.from_stage_id,
-    toLane: idToKey.get(t.to_stage_id) ?? t.to_stage_id,
-    manualAllowed: t.manual_allowed ?? false,
-    autoOnComplete: t.auto_on_complete ?? false,
-    kind: t.kind
-  };
-}
-function mapDefinitionToBoard(config, definition, version) {
-  const lanes = (definition.stages ?? []).map(mapStage);
-  const idToKey = new Map(
-    (definition.stages ?? []).map((s) => [s.id, s.key])
-  );
-  const transitions = (definition.transitions ?? []).map(
-    (t) => mapTransition(t, idToKey)
-  );
-  const board = {
-    id: config.uuid,
-    orgId: config.orgId ?? 0,
-    lifecycleId: config.uuid,
-    lifecycleVersion: version,
-    name: config.name,
-    lanes,
-    transitions
-  };
-  return {
-    uuid: config.uuid,
-    version,
-    name: config.name,
-    slug: config.slug,
-    board,
-    definition: { stages: lanes, transitions }
-  };
-}
-var DEFAULT_BASE_PATH = "/api/v1/board-configs";
-var BoardConfigClient = class {
-  http;
-  basePath;
-  /** Cache keyed by `${uuid}:${version}`. */
-  cache = /* @__PURE__ */ new Map();
-  /** Last-known active version per uuid (for degraded active fetch). */
-  activeVersions = /* @__PURE__ */ new Map();
-  constructor(options) {
-    this.http = options.http;
-    this.basePath = options.basePath ?? DEFAULT_BASE_PATH;
-  }
-  /**
-   * Fetch a config's ACTIVE version and map it. Re-validates against Cadra each
-   * call (a newly published version supersedes the old active one). On a fetch
-   * failure, serves the last cached copy for that config (graceful degradation,
-   * design.md §11 R-cache); if nothing is cached, the error propagates.
-   */
-  async getActive(uuid) {
-    try {
-      const res = await this.http.get(
-        `${this.basePath}/${uuid}`
-      );
-      const resolved = this.parse(res);
-      this.put(resolved);
-      this.activeVersions.set(uuid, resolved.version);
-      return resolved;
-    } catch (err) {
-      const cached = this.cachedActive(uuid);
-      if (cached) return cached;
-      throw err;
-    }
-  }
-  /**
-   * Fetch a SPECIFIC frozen version and map it. Published versions are
-   * immutable, so a cache hit skips the network. On a fetch miss + failure,
-   * serves the cached version if present.
-   */
-  async getPinned(uuid, version) {
-    const cached = this.cache.get(this.key(uuid, version));
-    if (cached) return cached;
-    try {
-      const res = await this.http.get(
-        `${this.basePath}/${uuid}`,
-        { version }
-      );
-      const resolved = this.parse(res, version);
-      this.put(resolved);
-      return resolved;
-    } catch (err) {
-      const fallback = this.cache.get(this.key(uuid, version));
-      if (fallback) return fallback;
-      throw err;
-    }
-  }
-  /** Drop all cached configs (e.g. after a known publish). */
-  clearCache() {
-    this.cache.clear();
-    this.activeVersions.clear();
-  }
-  // -------------------------------------------------------------------------
-  // internals
-  // -------------------------------------------------------------------------
-  key(uuid, version) {
-    return `${uuid}:${version}`;
-  }
-  put(resolved) {
-    this.cache.set(this.key(resolved.uuid, resolved.version), resolved);
-  }
-  cachedActive(uuid) {
-    const v = this.activeVersions.get(uuid);
-    if (v === void 0) return void 0;
-    return this.cache.get(this.key(uuid, v));
-  }
-  /**
-   * Normalize the wire envelope (active `{ config, definition, version }` OR
-   * pinned `{ config, version: { version, definition } }`) into a resolved
-   * config.
-   */
-  parse(res, requestedVersion) {
-    if (!res?.config?.uuid) {
-      throw new Error("Invalid board-config response: missing config.uuid");
-    }
-    let definition;
-    let version;
-    if (res.version && typeof res.version === "object") {
-      definition = res.version.definition;
-      version = res.version.version;
-    } else if (isVersionRow(res.definition)) {
-      definition = res.definition.definition;
-      version = res.definition.version ?? res.config.activeVersion ?? void 0;
-    } else {
-      definition = res.definition;
-      version = typeof res.version === "number" ? res.version : res.config.activeVersion ?? void 0;
-    }
-    if (!definition) {
-      throw new Error("Invalid board-config response: missing definition");
-    }
-    const resolvedVersion = version ?? requestedVersion ?? 1;
-    return mapDefinitionToBoard(res.config, definition, resolvedVersion);
-  }
-};
-function toResolvedLifecycle(cfg) {
-  return {
-    uuid: cfg.uuid,
-    version: cfg.version,
-    source: "cadra",
-    name: cfg.name,
-    slug: cfg.slug,
-    stages: cfg.board.lanes,
-    transitions: cfg.board.transitions ?? [],
-    board: cfg.board
-  };
-}
-var CadraLifecycleSource = class {
-  client;
-  constructor(arg) {
-    this.client = arg instanceof BoardConfigClient ? arg : new BoardConfigClient(arg);
-  }
-  /** The ACTIVE version, projected to a `ResolvedLifecycle` (`source: cadra`). */
-  async getActive(uuid) {
-    return toResolvedLifecycle(await this.client.getActive(uuid));
-  }
-  /** A PINNED version, projected to a `ResolvedLifecycle` (`source: cadra`). */
-  async getPinned(uuid, version) {
-    return toResolvedLifecycle(await this.client.getPinned(uuid, version));
-  }
-  /** Drop the underlying cache (e.g. after a known publish). */
-  clearCache() {
-    this.client.clearCache();
-  }
-};
-
-// src/kanban/engine/handlers.ts
-var WebhookDeliveryError = class extends Error {
-  constructor(message, status, retryable) {
-    super(message);
-    this.status = status;
-    this.retryable = retryable;
-    this.name = "WebhookDeliveryError";
-  }
-  status;
-  retryable;
-};
-async function hmacSign(secret, payload) {
-  const enc = new TextEncoder();
-  const key = await crypto.subtle.importKey(
-    "raw",
-    enc.encode(secret),
-    { name: "HMAC", hash: "SHA-256" },
-    false,
-    ["sign"]
-  );
-  const sig = await crypto.subtle.sign("HMAC", key, enc.encode(payload));
-  return [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, "0")).join("");
-}
-var sleepDefault = (ms) => new Promise((r) => setTimeout(r, ms));
-async function deliverWebhook(ctx, cadra, opts = {}) {
-  const binding = ctx.stage.handler?.webhook;
-  if (!binding) throw new Error(`Stage ${ctx.stage.key} has no webhook binding`);
-  const doFetch = opts.fetchImpl ?? fetch;
-  const maxAttempts = opts.maxAttempts ?? binding.retry ?? 3;
-  const baseBackoff = opts.baseBackoffMs ?? 200;
-  const sleep = opts.sleep ?? sleepDefault;
-  const now = opts.now ?? Date.now;
-  const stageId = ctx.stage.id ?? ctx.stage.key;
-  const secretMaterial = await cadra.getWebhookSecret({
-    boardConfigUuid: ctx.boardConfigUuid,
-    stageId
-  });
-  const timestamp = now();
-  const body = {
-    idemKey: ctx.idemKey,
-    cardId: ctx.cardId,
-    boardConfigUuid: ctx.boardConfigUuid,
-    configVersion: ctx.configVersion,
-    stageId,
-    input: ctx.input,
-    callbackUrl: ctx.callbackUrl,
-    callbackToken: secretMaterial?.callbackToken,
-    timestamp
-  };
-  const payload = JSON.stringify(body);
-  const signature = secretMaterial?.secret ? await hmacSign(secretMaterial.secret, `${timestamp}.${payload}`) : void 0;
-  const headers = {
-    "Content-Type": "application/json",
-    "Idempotency-Key": ctx.idemKey,
-    ...binding.headers ?? {}
-  };
-  if (signature) {
-    headers["X-Cadra-Signature"] = `t=${timestamp},v1=${signature}`;
-  }
-  let attempt = 0;
-  while (true) {
-    attempt += 1;
-    try {
-      const res = await doFetch(binding.url, {
-        method: "POST",
-        headers,
-        body: payload,
-        ...binding.timeoutMs ? { signal: AbortSignal.timeout(binding.timeoutMs) } : {}
-      });
-      if (res.ok) return;
-      if (res.status >= 400 && res.status < 500) {
-        throw new WebhookDeliveryError(
-          `Webhook ${binding.url} returned ${res.status}`,
-          res.status,
-          false
-        );
-      }
-      throw new WebhookDeliveryError(
-        `Webhook ${binding.url} returned ${res.status}`,
-        res.status,
-        true
-      );
-    } catch (err) {
-      const retryable = err instanceof WebhookDeliveryError ? err.retryable : true;
-      if (!retryable || attempt >= maxAttempts) {
-        if (err instanceof WebhookDeliveryError) throw err;
-        throw new WebhookDeliveryError(
-          err instanceof Error ? err.message : String(err),
-          void 0,
-          true
-        );
-      }
-      await sleep(baseBackoff * 2 ** (attempt - 1));
-    }
-  }
-}
-async function dispatchStageHandler(ctx, cadra, webhookOpts) {
-  const handler = ctx.stage.handler;
-  if (!handler || handler.type === "none" || handler.type === "human") {
-    return { dispatched: false };
-  }
-  const runIdemKey = ctx.batch?.batchKey ?? ctx.idemKey;
-  switch (handler.type) {
-    case "cadra_agent": {
-      if (!handler.agentUuid) {
-        throw new Error(`Stage ${ctx.stage.key} (cadra_agent) missing agentUuid`);
-      }
-      const { executionUuid } = await cadra.runAgent({
-        agentUuid: handler.agentUuid,
-        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 };
-    }
-    case "cadra_team": {
-      if (!handler.teamUuid) {
-        throw new Error(`Stage ${ctx.stage.key} (cadra_team) missing teamUuid`);
-      }
-      const { executionUuid } = await cadra.runTeam({
-        teamUuid: handler.teamUuid,
-        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 };
-    }
-    case "webhook": {
-      await deliverWebhook(ctx, cadra, webhookOpts);
-      return { dispatched: true };
-    }
-    case "remote_agent": {
-      const h = handler;
-      const remoteAgentUuid = h["remoteAgentUuid"] ?? h["remote_agent_uuid"];
-      if (!remoteAgentUuid) {
-        throw new Error(`Stage ${ctx.stage.key} (remote_agent) missing remoteAgentUuid`);
-      }
-      const { executionUuid } = await cadra.runRemoteAgent({
-        remoteAgentUuid,
-        orgId: ctx.orgId,
-        input: ctx.input,
-        idemKey: runIdemKey,
-        // Board/headless dispatch always disables ask_user (spec §6.5).
-        allowAskUser: false,
-        callbackRef: ctx.callbackUrl
-      });
-      return { dispatched: true, executionUuid };
-    }
-    default:
-      return { dispatched: false };
-  }
-}
-
 // src/kanban/adapters/in-memory-adapter.ts
 var TransitionConflictError = class extends Error {
   code = "transition_conflict";
@@ -609,6 +234,13 @@ var TransitionConflictError = class extends Error {
     this.name = "TransitionConflictError";
   }
 };
+var HostFenceError = class extends Error {
+  code = "host_fence";
+  constructor(message = "Card has a pending host op; host move skipped") {
+    super(message);
+    this.name = "HostFenceError";
+  }
+};
 var UnknownDueRuleError = class extends Error {
   code = "unknown_due_rule_kind";
   constructor(kind) {
@@ -626,6 +258,8 @@ var InMemoryStorageAdapter = class {
   cards = /* @__PURE__ */ new Map();
   logs = /* @__PURE__ */ new Map();
   runs = /* @__PURE__ */ new Map();
+  /** Lane KEY the card was in when each run was (re)claimed (idemKey → lane). */
+  runLanes = /* @__PURE__ */ new Map();
   // p46 Handoff ledger + op outbox (the full optional group).
   handoffs = [];
   ops = /* @__PURE__ */ new Map();
@@ -659,7 +293,19 @@ var InMemoryStorageAdapter = class {
     const c = this.cards.get(cardId);
     return c ? this.publicCard(c) : null;
   }
+  async getCardByExternalRef(boardConfigUuid, externalRef) {
+    for (const c of this.cards.values()) {
+      if (c.boardConfigUuid === boardConfigUuid && c.externalRef === externalRef) {
+        return this.publicCard(c);
+      }
+    }
+    return null;
+  }
   async createCard(input) {
+    if (input.externalRef !== void 0) {
+      const existing = await this.getCardByExternalRef(input.boardConfigUuid, input.externalRef);
+      if (existing) return existing;
+    }
     const id = nextId("card");
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const card = {
@@ -677,6 +323,7 @@ var InMemoryStorageAdapter = class {
       description: input.description,
       type: input.type,
       sharedContext: input.sharedContext,
+      ...input.externalRef !== void 0 ? { externalRef: input.externalRef } : {},
       createdAt: now,
       updatedAt: now
     };
@@ -701,6 +348,18 @@ var InMemoryStorageAdapter = class {
         `Expected lane ${move.fromLane}, card is in ${c.lane}`
       );
     }
+    if (move.hostObservation) {
+      const observedAt = move.hostObservation.observedAt;
+      for (const op of this.ops.values()) {
+        if (op.cardId !== cardId || !op.kind.startsWith("host.")) continue;
+        const settledAfter = observedAt !== void 0 && op.settledAt !== void 0 && Date.parse(op.settledAt) > Date.parse(observedAt);
+        if (op.status === "pending" || settledAfter) {
+          throw new HostFenceError(
+            `Card ${cardId} has ${op.status === "pending" ? "pending" : "freshly settled"} ${op.kind} ${op.opId}`
+          );
+        }
+      }
+    }
     c.lane = move.toLane;
     if (move.contextPatch) {
       c.sharedContext = { ...c.sharedContext ?? {}, ...move.contextPatch };
@@ -738,353 +397,740 @@ var InMemoryStorageAdapter = class {
       if (c.boardConfigUuid !== boardConfigUuid) continue;
       counts[c.lane] = (counts[c.lane] ?? 0) + 1;
     }
-    return counts;
+    return counts;
+  }
+  capabilities() {
+    return {
+      dueRuleFields: ["*"],
+      dueRulePredicates: ["*"],
+      membership: "adapter-resolved"
+    };
+  }
+  // ----- Stage runs -----
+  async beginStageRun(cardId, r) {
+    const existing = this.runs.get(r.idemKey);
+    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);
+        this.recordRunLane(cardId, r.idemKey);
+        return { created: true, run: { ...run2 } };
+      }
+      return { created: false, run: { ...existing } };
+    }
+    const run = {
+      idemKey: r.idemKey,
+      cardId,
+      stageId: r.stageId,
+      handlerType: r.handlerType,
+      status: "queued",
+      attempts: 1,
+      createdAt: new Date(this.now()).toISOString()
+    };
+    this.runs.set(r.idemKey, run);
+    this.recordRunLane(cardId, r.idemKey);
+    return { created: true, run: { ...run } };
+  }
+  recordRunLane(cardId, idemKey) {
+    const lane = this.cards.get(cardId)?.lane;
+    if (lane !== void 0) this.runLanes.set(idemKey, lane);
+  }
+  /**
+   * 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}`);
+    if (run.status === "completed") return { applied: false };
+    return this.transaction(async () => {
+      run.status = "completed";
+      if (c.executionUuid) run.executionUuid = c.executionUuid;
+      if (c.toLane) {
+        const card = this.requireCard(run.cardId);
+        const runLane = this.runLanes.get(idemKey);
+        const leftRunLane = runLane !== void 0 && card.lane !== runLane;
+        if (card.lane !== c.toLane && !leftRunLane) {
+          await this.applyTransition(run.cardId, {
+            fromLane: card.lane,
+            toLane: c.toLane,
+            actor: c.actor,
+            contextPatch: c.contextPatch,
+            executionUuid: c.executionUuid ?? run.executionUuid
+          });
+        }
+      }
+      this.writeLedger(run, c);
+      this.txFault?.("completeStageRun");
+      return { applied: true };
+    });
+  }
+  async failStageRun(idemKey, f) {
+    const run = this.runs.get(idemKey);
+    if (!run) throw new Error(`No stage run for idemKey ${idemKey}`);
+    if (run.status === "completed") return;
+    await this.transaction(async () => {
+      run.status = "failed";
+      run.error = f.error;
+      this.writeLedger(run, f);
+      this.txFault?.("failStageRun");
+    });
+  }
+  async getStageRun(idemKey) {
+    const r = this.runs.get(idemKey);
+    return r ? { ...r } : null;
+  }
+  async markStageRunDispatched(idemKey, d) {
+    const run = this.runs.get(idemKey);
+    if (!run) return;
+    if (run.status === "queued") run.status = "running";
+    if (d.executionUuid) {
+      run.executionUuid = d.executionUuid;
+      const card = this.cards.get(run.cardId);
+      if (card) card.executionId = d.executionUuid;
+    }
+  }
+  // ----- Handoff ledger + op outbox (p46 §4) -----
+  async appendHandoff(h) {
+    const existing = this.findConflict(h.card.id, h.stageId, h.configVersion, h.payload.kind, h.dedupeKey);
+    if (existing) return { created: false, handoff: this.toV1(existing.record) };
+    const row = this.insertHandoff({
+      payload: { ...h.payload, id: nextId("handoff") },
+      stageId: h.stageId,
+      configVersion: h.configVersion,
+      idemKey: h.idemKey,
+      attempt: h.attempt,
+      dedupeKey: h.dedupeKey
+    });
+    return { created: true, handoff: this.toV1(row.record) };
+  }
+  async listHandoffs(cardId, opts) {
+    const rows = this.handoffs.filter((r) => r.record.cardId === cardId).sort((a, b) => b.seq - a.seq).map((r) => structuredClone(r.record));
+    return opts?.limit !== void 0 ? rows.slice(0, opts.limit) : rows;
+  }
+  async answerHandoff(cardId, handoffId, answer, userId) {
+    const row = this.handoffs.find((r) => r.record.id === handoffId);
+    if (!row || row.record.cardId !== cardId || row.record.direction !== "ai_to_human" || !ANSWERABLE_HANDOFF_KINDS.includes(row.record.kind) || row.record.status !== "open") {
+      return { applied: false };
+    }
+    row.record.status = "answered";
+    row.record.answer = { ...answer };
+    row.answeredBy = userId;
+    return { applied: true };
+  }
+  async resolveHandoff(handoffId) {
+    const row = this.handoffs.find((r) => r.record.id === handoffId);
+    if (!row || row.record.status !== "open") return { applied: false };
+    row.record.status = "resolved";
+    return { applied: true };
+  }
+  async consumeHandoffs(ids, idemKey) {
+    const at = new Date(this.now()).toISOString();
+    for (const row of this.handoffs) {
+      if (ids.includes(row.record.id) && row.record.direction === "human_to_ai" && row.record.status === "open") {
+        row.record.status = "consumed";
+        row.record.consumedAt = at;
+        row.consumedByIdemKey = idemKey;
+      }
+    }
+  }
+  async claimOp(op) {
+    const existing = this.ops.get(op.opId);
+    if (existing) {
+      if (existing.status === "done") return { run: false };
+      existing.attempts += 1;
+      return { run: true };
+    }
+    this.ops.set(op.opId, { ...op, status: "pending", attempts: 1 });
+    return { run: true };
+  }
+  async completeOp(opId) {
+    const op = this.ops.get(opId);
+    if (op) {
+      op.status = "done";
+      op.settledAt = new Date(this.now()).toISOString();
+    }
+  }
+  async failOp(opId, error) {
+    const op = this.ops.get(opId);
+    if (op) {
+      op.status = "failed";
+      op.lastError = error;
+      op.settledAt = new Date(this.now()).toISOString();
+    }
+  }
+  /** Test/inspection helper: read one outbox op. */
+  getOp(opId) {
+    const op = this.ops.get(opId);
+    return op ? structuredClone(op) : void 0;
+  }
+  // ----- internals -----
+  /**
+   * Run `fn` as one all-or-nothing "transaction": snapshot every table, and
+   * restore the snapshot if `fn` throws (models the host's SQL tx rollback).
+   */
+  async transaction(fn) {
+    const snap = {
+      cards: structuredClone(this.cards),
+      logs: structuredClone(this.logs),
+      runs: structuredClone(this.runs),
+      handoffs: structuredClone(this.handoffs),
+      ops: structuredClone(this.ops),
+      handoffSeq: this.handoffSeq
+    };
+    try {
+      return await fn();
+    } catch (err) {
+      this.cards = snap.cards;
+      this.logs = snap.logs;
+      this.runs = snap.runs;
+      this.handoffs = snap.handoffs;
+      this.ops = snap.ops;
+      this.handoffSeq = snap.handoffSeq;
+      throw err;
+    }
+  }
+  /** The F3 in-tx ledger write for completeStageRun / failStageRun. */
+  writeLedger(run, w) {
+    if (!w.handoff) return;
+    const p = w.handoff.payload;
+    const conflict = this.findConflict(p.cardId, run.stageId, this.versionOf(run.idemKey), p.kind, w.handoff.dedupeKey);
+    if (conflict) return;
+    const row = this.insertHandoff({
+      payload: p,
+      stageId: run.stageId,
+      configVersion: this.versionOf(run.idemKey),
+      idemKey: run.idemKey,
+      attempt: run.attempts ?? 1,
+      dedupeKey: w.handoff.dedupeKey
+    });
+    if (w.notifyOpId && !this.ops.has(w.notifyOpId)) {
+      this.ops.set(w.notifyOpId, {
+        opId: w.notifyOpId,
+        kind: "notify.in_app",
+        cardId: p.cardId,
+        handoffId: row.record.id,
+        payload: { handoffId: row.record.id },
+        status: "pending",
+        attempts: 0
+      });
+    }
+  }
+  findConflict(cardId, stageId, configVersion, kind, dedupeKey) {
+    if (dedupeKey) {
+      const d = this.handoffs.find((r) => r.dedupeKey === dedupeKey);
+      if (d) return d;
+    }
+    if (kind === "BLOCKED") {
+      return this.handoffs.find(
+        (r) => r.record.kind === "BLOCKED" && r.record.status === "open" && r.record.cardId === cardId && r.stageId === stageId && r.configVersion === configVersion
+      );
+    }
+    return void 0;
   }
-  capabilities() {
-    return {
-      dueRuleFields: ["*"],
-      dueRulePredicates: ["*"],
-      membership: "adapter-resolved"
+  insertHandoff(r) {
+    this.handoffSeq += 1;
+    const row = {
+      record: { ...structuredClone(r.payload), status: "open", consumedAt: null },
+      stageId: r.stageId,
+      configVersion: r.configVersion,
+      idemKey: r.idemKey,
+      attempt: r.attempt,
+      dedupeKey: r.dedupeKey,
+      seq: this.handoffSeq
     };
+    this.handoffs.push(row);
+    return row;
   }
-  // ----- Stage runs -----
-  async beginStageRun(cardId, r) {
-    const existing = this.runs.get(r.idemKey);
-    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 } };
+  toV1(rec) {
+    const { status: _s, consumedAt: _c, ...v1 } = structuredClone(rec);
+    return v1;
+  }
+  /** The trailing config version of an idemKey (`cardId:stageId:version`). */
+  versionOf(idemKey) {
+    return Number(idemKey.slice(idemKey.lastIndexOf(":") + 1));
+  }
+  /**
+   * Reject (throw) if any node in the rule tree is not a known `kind` — checked
+   * up front so a bad rule fails closed before we ever inspect a card.
+   */
+  assertKnownKind(rule) {
+    switch (rule.kind) {
+      case "always":
+      case "backlog":
+      case "field_due":
+      case "predicate":
+        return;
+      case "and":
+        for (const r of rule.rules) this.assertKnownKind(r);
+        return;
+      default:
+        throw new UnknownDueRuleError(
+          rule.kind ?? "<missing>"
+        );
+    }
+  }
+  /**
+   * Evaluate a (validated) `DueRule` against an in-memory card. `field_due` /
+   * `predicate` read the card's `sharedContext` (the reference adapter's only
+   * "host data"); a real host pushes these down to SQL over its own columns.
+   */
+  isDue(card, rule, now) {
+    switch (rule.kind) {
+      case "always":
+        return true;
+      case "backlog":
+        return true;
+      case "field_due": {
+        const v = card.sharedContext?.[rule.field];
+        if (v == null) return false;
+        const left = this.toComparable(v);
+        const right = rule.value === "now" ? now : this.toComparable(rule.value);
+        if (left == null || right == null) return false;
+        return left <= right;
       }
-      return { created: false, run: { ...existing } };
+      case "predicate": {
+        const v = card.sharedContext?.[rule.ref];
+        if (v == null) return false;
+        return String(v) === String(rule.value);
+      }
+      case "and":
+        return rule.rules.every((r) => this.isDue(card, r, now));
+      default:
+        throw new UnknownDueRuleError(
+          rule.kind ?? "<missing>"
+        );
     }
-    const run = {
-      idemKey: r.idemKey,
-      cardId,
-      stageId: r.stageId,
-      handlerType: r.handlerType,
-      status: "queued",
-      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.
+   * Coerce a value to a comparable primitive for `field_due` (`<=`): dates →
+   * epoch ms, numeric strings → numbers, else the raw number/string.
    */
-  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;
+  toComparable(v) {
+    if (typeof v === "number") return v;
+    if (v instanceof Date) return v.getTime();
+    if (typeof v === "string") {
+      const t = Date.parse(v);
+      if (!Number.isNaN(t)) return t;
+      const n = Number(v);
+      if (!Number.isNaN(n) && v.trim() !== "") return n;
+      return v;
     }
-    return false;
+    return null;
   }
-  async completeStageRun(idemKey, c) {
-    const run = this.runs.get(idemKey);
-    if (!run) throw new Error(`No stage run for idemKey ${idemKey}`);
-    if (run.status === "completed") return { applied: false };
-    return this.transaction(async () => {
-      run.status = "completed";
-      if (c.executionUuid) run.executionUuid = c.executionUuid;
-      if (c.toLane) {
-        const card = this.requireCard(run.cardId);
-        if (card.lane !== c.toLane) {
-          await this.applyTransition(run.cardId, {
-            fromLane: card.lane,
-            toLane: c.toLane,
-            actor: c.actor,
-            contextPatch: c.contextPatch,
-            executionUuid: c.executionUuid ?? run.executionUuid
-          });
-        }
-      }
-      this.writeLedger(run, c);
-      this.txFault?.("completeStageRun");
-      return { applied: true };
-    });
+  requireCard(cardId) {
+    const c = this.cards.get(cardId);
+    if (!c) throw new Error(`Card not found: ${cardId}`);
+    return c;
   }
-  async failStageRun(idemKey, f) {
-    const run = this.runs.get(idemKey);
-    if (!run) throw new Error(`No stage run for idemKey ${idemKey}`);
-    if (run.status === "completed") return;
-    await this.transaction(async () => {
-      run.status = "failed";
-      run.error = f.error;
-      this.writeLedger(run, f);
-      this.txFault?.("failStageRun");
+  appendLog(cardId, entry) {
+    const list = this.logs.get(cardId) ?? [];
+    list.push({
+      id: nextId("log"),
+      cardId,
+      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+      ...entry
     });
+    this.logs.set(cardId, list);
   }
-  async getStageRun(idemKey) {
-    const r = this.runs.get(idemKey);
-    return r ? { ...r } : null;
-  }
-  async markStageRunDispatched(idemKey, d) {
-    const run = this.runs.get(idemKey);
-    if (!run) return;
-    if (run.status === "queued") run.status = "running";
-    if (d.executionUuid) {
-      run.executionUuid = d.executionUuid;
-      const card = this.cards.get(run.cardId);
-      if (card) card.executionId = d.executionUuid;
-    }
+  publicCard(c) {
+    const { boardConfigUuid: _b, ...pub } = c;
+    return { ...pub };
   }
-  // ----- Handoff ledger + op outbox (p46 §4) -----
-  async appendHandoff(h) {
-    const existing = this.findConflict(h.card.id, h.stageId, h.configVersion, h.payload.kind, h.dedupeKey);
-    if (existing) return { created: false, handoff: this.toV1(existing.record) };
-    const row = this.insertHandoff({
-      payload: { ...h.payload, id: nextId("handoff") },
-      stageId: h.stageId,
-      configVersion: h.configVersion,
-      idemKey: h.idemKey,
-      attempt: h.attempt,
-      dedupeKey: h.dedupeKey
-    });
-    return { created: true, handoff: this.toV1(row.record) };
+};
+
+// src/kanban/config-client.ts
+function isVersionRow(d) {
+  return !!d && typeof d === "object" && "definition" in d && !!d.definition;
+}
+function mapHandler(h) {
+  if (!h || !h.type || h.type === "none") {
+    return void 0;
   }
-  async listHandoffs(cardId, opts) {
-    const rows = this.handoffs.filter((r) => r.record.cardId === cardId).sort((a, b) => b.seq - a.seq).map((r) => structuredClone(r.record));
-    return opts?.limit !== void 0 ? rows.slice(0, opts.limit) : rows;
+  return {
+    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,
+      headers: h.webhook.headers,
+      timeoutMs: h.webhook.timeout_ms,
+      retry: h.webhook.retry
+    } : void 0
+  };
+}
+function mapStage(s, index) {
+  const lane = {
+    // Carry the IMMUTABLE stage id through (p33 §10.2). It is what the
+    // webhook-secret fetch + the stage-run idemKey + the UI columns key off —
+    // a `key`/`label` rename never breaks dispatch or keying. `key` stays the
+    // editable display/slug.
+    id: s.id,
+    key: s.key,
+    label: s.name,
+    order: index,
+    handler: mapHandler(s.handler),
+    terminal: s.is_terminal ?? false,
+    initial: s.is_initial ?? false
+  };
+  if (s.trigger) lane.trigger = s.trigger;
+  if (s.due_rule != null) lane.dueRule = s.due_rule;
+  if (s.cap != null) lane.cap = s.cap;
+  if (s.dispatch) lane.dispatch = s.dispatch;
+  if (s.chunk_size != null) lane.chunkSize = s.chunk_size;
+  if (s.handoff === "off" || s.handoff === "verdict") lane.handoff = s.handoff;
+  return lane;
+}
+function mapTransition(t, idToKey) {
+  return {
+    id: t.id,
+    fromLane: idToKey.get(t.from_stage_id) ?? t.from_stage_id,
+    toLane: idToKey.get(t.to_stage_id) ?? t.to_stage_id,
+    manualAllowed: t.manual_allowed ?? false,
+    autoOnComplete: t.auto_on_complete ?? false,
+    kind: t.kind
+  };
+}
+function mapDefinitionToBoard(config, definition, version) {
+  const lanes = (definition.stages ?? []).map(mapStage);
+  const idToKey = new Map(
+    (definition.stages ?? []).map((s) => [s.id, s.key])
+  );
+  const transitions = (definition.transitions ?? []).map(
+    (t) => mapTransition(t, idToKey)
+  );
+  const board = {
+    id: config.uuid,
+    orgId: config.orgId ?? 0,
+    lifecycleId: config.uuid,
+    lifecycleVersion: version,
+    name: config.name,
+    lanes,
+    transitions
+  };
+  return {
+    uuid: config.uuid,
+    version,
+    name: config.name,
+    slug: config.slug,
+    board,
+    definition: { stages: lanes, transitions }
+  };
+}
+var DEFAULT_BASE_PATH = "/api/v1/board-configs";
+var BoardConfigClient = class {
+  http;
+  basePath;
+  /** Cache keyed by `${uuid}:${version}`. */
+  cache = /* @__PURE__ */ new Map();
+  /** Last-known active version per uuid (for degraded active fetch). */
+  activeVersions = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.http = options.http;
+    this.basePath = options.basePath ?? DEFAULT_BASE_PATH;
   }
-  async answerHandoff(cardId, handoffId, answer, userId) {
-    const row = this.handoffs.find((r) => r.record.id === handoffId);
-    if (!row || row.record.cardId !== cardId || row.record.direction !== "ai_to_human" || !ANSWERABLE_HANDOFF_KINDS.includes(row.record.kind) || row.record.status !== "open") {
-      return { applied: false };
+  /**
+   * Fetch a config's ACTIVE version and map it. Re-validates against Cadra each
+   * call (a newly published version supersedes the old active one). On a fetch
+   * failure, serves the last cached copy for that config (graceful degradation,
+   * design.md §11 R-cache); if nothing is cached, the error propagates.
+   */
+  async getActive(uuid) {
+    try {
+      const res = await this.http.get(
+        `${this.basePath}/${uuid}`
+      );
+      const resolved = this.parse(res);
+      this.put(resolved);
+      this.activeVersions.set(uuid, resolved.version);
+      return resolved;
+    } catch (err) {
+      const cached = this.cachedActive(uuid);
+      if (cached) return cached;
+      throw err;
     }
-    row.record.status = "answered";
-    row.record.answer = { ...answer };
-    row.answeredBy = userId;
-    return { applied: true };
-  }
-  async resolveHandoff(handoffId) {
-    const row = this.handoffs.find((r) => r.record.id === handoffId);
-    if (!row || row.record.status !== "open") return { applied: false };
-    row.record.status = "resolved";
-    return { applied: true };
   }
-  async consumeHandoffs(ids, idemKey) {
-    const at = new Date(this.now()).toISOString();
-    for (const row of this.handoffs) {
-      if (ids.includes(row.record.id) && row.record.direction === "human_to_ai" && row.record.status === "open") {
-        row.record.status = "consumed";
-        row.record.consumedAt = at;
-        row.consumedByIdemKey = idemKey;
-      }
+  /**
+   * Fetch a SPECIFIC frozen version and map it. Published versions are
+   * immutable, so a cache hit skips the network. On a fetch miss + failure,
+   * serves the cached version if present.
+   */
+  async getPinned(uuid, version) {
+    const cached = this.cache.get(this.key(uuid, version));
+    if (cached) return cached;
+    try {
+      const res = await this.http.get(
+        `${this.basePath}/${uuid}`,
+        { version }
+      );
+      const resolved = this.parse(res, version);
+      this.put(resolved);
+      return resolved;
+    } catch (err) {
+      const fallback = this.cache.get(this.key(uuid, version));
+      if (fallback) return fallback;
+      throw err;
     }
   }
-  async claimOp(op) {
-    const existing = this.ops.get(op.opId);
-    if (existing) {
-      if (existing.status === "done") return { run: false };
-      existing.attempts += 1;
-      return { run: true };
-    }
-    this.ops.set(op.opId, { ...op, status: "pending", attempts: 1 });
-    return { run: true };
+  /** Drop all cached configs (e.g. after a known publish). */
+  clearCache() {
+    this.cache.clear();
+    this.activeVersions.clear();
   }
-  async completeOp(opId) {
-    const op = this.ops.get(opId);
-    if (op) op.status = "done";
+  // -------------------------------------------------------------------------
+  // internals
+  // -------------------------------------------------------------------------
+  key(uuid, version) {
+    return `${uuid}:${version}`;
   }
-  async failOp(opId, error) {
-    const op = this.ops.get(opId);
-    if (op) {
-      op.status = "failed";
-      op.lastError = error;
-    }
+  put(resolved) {
+    this.cache.set(this.key(resolved.uuid, resolved.version), resolved);
   }
-  /** Test/inspection helper: read one outbox op. */
-  getOp(opId) {
-    const op = this.ops.get(opId);
-    return op ? structuredClone(op) : void 0;
+  cachedActive(uuid) {
+    const v = this.activeVersions.get(uuid);
+    if (v === void 0) return void 0;
+    return this.cache.get(this.key(uuid, v));
   }
-  // ----- internals -----
   /**
-   * Run `fn` as one all-or-nothing "transaction": snapshot every table, and
-   * restore the snapshot if `fn` throws (models the host's SQL tx rollback).
+   * Normalize the wire envelope (active `{ config, definition, version }` OR
+   * pinned `{ config, version: { version, definition } }`) into a resolved
+   * config.
    */
-  async transaction(fn) {
-    const snap = {
-      cards: structuredClone(this.cards),
-      logs: structuredClone(this.logs),
-      runs: structuredClone(this.runs),
-      handoffs: structuredClone(this.handoffs),
-      ops: structuredClone(this.ops),
-      handoffSeq: this.handoffSeq
-    };
-    try {
-      return await fn();
-    } catch (err) {
-      this.cards = snap.cards;
-      this.logs = snap.logs;
-      this.runs = snap.runs;
-      this.handoffs = snap.handoffs;
-      this.ops = snap.ops;
-      this.handoffSeq = snap.handoffSeq;
-      throw err;
-    }
-  }
-  /** The F3 in-tx ledger write for completeStageRun / failStageRun. */
-  writeLedger(run, w) {
-    if (!w.handoff) return;
-    const p = w.handoff.payload;
-    const conflict = this.findConflict(p.cardId, run.stageId, this.versionOf(run.idemKey), p.kind, w.handoff.dedupeKey);
-    if (conflict) return;
-    const row = this.insertHandoff({
-      payload: p,
-      stageId: run.stageId,
-      configVersion: this.versionOf(run.idemKey),
-      idemKey: run.idemKey,
-      attempt: run.attempts ?? 1,
-      dedupeKey: w.handoff.dedupeKey
-    });
-    if (w.notifyOpId && !this.ops.has(w.notifyOpId)) {
-      this.ops.set(w.notifyOpId, {
-        opId: w.notifyOpId,
-        kind: "notify.in_app",
-        cardId: p.cardId,
-        handoffId: row.record.id,
-        payload: { handoffId: row.record.id },
-        status: "pending",
-        attempts: 0
-      });
+  parse(res, requestedVersion) {
+    if (!res?.config?.uuid) {
+      throw new Error("Invalid board-config response: missing config.uuid");
     }
-  }
-  findConflict(cardId, stageId, configVersion, kind, dedupeKey) {
-    if (dedupeKey) {
-      const d = this.handoffs.find((r) => r.dedupeKey === dedupeKey);
-      if (d) return d;
+    let definition;
+    let version;
+    if (res.version && typeof res.version === "object") {
+      definition = res.version.definition;
+      version = res.version.version;
+    } else if (isVersionRow(res.definition)) {
+      definition = res.definition.definition;
+      version = res.definition.version ?? res.config.activeVersion ?? void 0;
+    } else {
+      definition = res.definition;
+      version = typeof res.version === "number" ? res.version : res.config.activeVersion ?? void 0;
     }
-    if (kind === "BLOCKED") {
-      return this.handoffs.find(
-        (r) => r.record.kind === "BLOCKED" && r.record.status === "open" && r.record.cardId === cardId && r.stageId === stageId && r.configVersion === configVersion
-      );
+    if (!definition) {
+      throw new Error("Invalid board-config response: missing definition");
     }
-    return void 0;
+    const resolvedVersion = version ?? requestedVersion ?? 1;
+    return mapDefinitionToBoard(res.config, definition, resolvedVersion);
   }
-  insertHandoff(r) {
-    this.handoffSeq += 1;
-    const row = {
-      record: { ...structuredClone(r.payload), status: "open", consumedAt: null },
-      stageId: r.stageId,
-      configVersion: r.configVersion,
-      idemKey: r.idemKey,
-      attempt: r.attempt,
-      dedupeKey: r.dedupeKey,
-      seq: this.handoffSeq
-    };
-    this.handoffs.push(row);
-    return row;
+};
+function toResolvedLifecycle(cfg) {
+  return {
+    uuid: cfg.uuid,
+    version: cfg.version,
+    source: "cadra",
+    name: cfg.name,
+    slug: cfg.slug,
+    stages: cfg.board.lanes,
+    transitions: cfg.board.transitions ?? [],
+    board: cfg.board
+  };
+}
+var CadraLifecycleSource = class {
+  client;
+  constructor(arg) {
+    this.client = arg instanceof BoardConfigClient ? arg : new BoardConfigClient(arg);
+  }
+  /** The ACTIVE version, projected to a `ResolvedLifecycle` (`source: cadra`). */
+  async getActive(uuid) {
+    return toResolvedLifecycle(await this.client.getActive(uuid));
+  }
+  /** A PINNED version, projected to a `ResolvedLifecycle` (`source: cadra`). */
+  async getPinned(uuid, version) {
+    return toResolvedLifecycle(await this.client.getPinned(uuid, version));
+  }
+  /** Drop the underlying cache (e.g. after a known publish). */
+  clearCache() {
+    this.client.clearCache();
   }
-  toV1(rec) {
-    const { status: _s, consumedAt: _c, ...v1 } = structuredClone(rec);
-    return v1;
+};
+
+// src/kanban/engine/handlers.ts
+var WebhookDeliveryError = class extends Error {
+  constructor(message, status, retryable) {
+    super(message);
+    this.status = status;
+    this.retryable = retryable;
+    this.name = "WebhookDeliveryError";
   }
-  /** The trailing config version of an idemKey (`cardId:stageId:version`). */
-  versionOf(idemKey) {
-    return Number(idemKey.slice(idemKey.lastIndexOf(":") + 1));
+  status;
+  retryable;
+};
+async function hmacSign(secret, payload) {
+  const enc = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    enc.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, enc.encode(payload));
+  return [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+var sleepDefault = (ms) => new Promise((r) => setTimeout(r, ms));
+async function deliverWebhook(ctx, cadra, opts = {}) {
+  const binding = ctx.stage.handler?.webhook;
+  if (!binding) throw new Error(`Stage ${ctx.stage.key} has no webhook binding`);
+  const doFetch = opts.fetchImpl ?? fetch;
+  const maxAttempts = opts.maxAttempts ?? binding.retry ?? 3;
+  const baseBackoff = opts.baseBackoffMs ?? 200;
+  const sleep = opts.sleep ?? sleepDefault;
+  const now = opts.now ?? Date.now;
+  const stageId = ctx.stage.id ?? ctx.stage.key;
+  const secretMaterial = await cadra.getWebhookSecret({
+    boardConfigUuid: ctx.boardConfigUuid,
+    stageId
+  });
+  const timestamp = now();
+  const body = {
+    idemKey: ctx.idemKey,
+    cardId: ctx.cardId,
+    boardConfigUuid: ctx.boardConfigUuid,
+    configVersion: ctx.configVersion,
+    stageId,
+    input: ctx.input,
+    callbackUrl: ctx.callbackUrl,
+    callbackToken: secretMaterial?.callbackToken,
+    timestamp
+  };
+  const payload = JSON.stringify(body);
+  const signature = secretMaterial?.secret ? await hmacSign(secretMaterial.secret, `${timestamp}.${payload}`) : void 0;
+  const headers = {
+    "Content-Type": "application/json",
+    "Idempotency-Key": ctx.idemKey,
+    ...binding.headers ?? {}
+  };
+  if (signature) {
+    headers["X-Cadra-Signature"] = `t=${timestamp},v1=${signature}`;
   }
-  /**
-   * Reject (throw) if any node in the rule tree is not a known `kind` — checked
-   * up front so a bad rule fails closed before we ever inspect a card.
-   */
-  assertKnownKind(rule) {
-    switch (rule.kind) {
-      case "always":
-      case "backlog":
-      case "field_due":
-      case "predicate":
-        return;
-      case "and":
-        for (const r of rule.rules) this.assertKnownKind(r);
-        return;
-      default:
-        throw new UnknownDueRuleError(
-          rule.kind ?? "<missing>"
+  let attempt = 0;
+  while (true) {
+    attempt += 1;
+    try {
+      const res = await doFetch(binding.url, {
+        method: "POST",
+        headers,
+        body: payload,
+        ...binding.timeoutMs ? { signal: AbortSignal.timeout(binding.timeoutMs) } : {}
+      });
+      if (res.ok) return;
+      if (res.status >= 400 && res.status < 500) {
+        throw new WebhookDeliveryError(
+          `Webhook ${binding.url} returned ${res.status}`,
+          res.status,
+          false
+        );
+      }
+      throw new WebhookDeliveryError(
+        `Webhook ${binding.url} returned ${res.status}`,
+        res.status,
+        true
+      );
+    } catch (err) {
+      const retryable = err instanceof WebhookDeliveryError ? err.retryable : true;
+      if (!retryable || attempt >= maxAttempts) {
+        if (err instanceof WebhookDeliveryError) throw err;
+        throw new WebhookDeliveryError(
+          err instanceof Error ? err.message : String(err),
+          void 0,
+          true
         );
+      }
+      await sleep(baseBackoff * 2 ** (attempt - 1));
     }
   }
-  /**
-   * Evaluate a (validated) `DueRule` against an in-memory card. `field_due` /
-   * `predicate` read the card's `sharedContext` (the reference adapter's only
-   * "host data"); a real host pushes these down to SQL over its own columns.
-   */
-  isDue(card, rule, now) {
-    switch (rule.kind) {
-      case "always":
-        return true;
-      case "backlog":
-        return true;
-      case "field_due": {
-        const v = card.sharedContext?.[rule.field];
-        if (v == null) return false;
-        const left = this.toComparable(v);
-        const right = rule.value === "now" ? now : this.toComparable(rule.value);
-        if (left == null || right == null) return false;
-        return left <= right;
+}
+async function dispatchStageHandler(ctx, cadra, webhookOpts) {
+  const handler = ctx.stage.handler;
+  if (!handler || handler.type === "none" || handler.type === "human") {
+    return { dispatched: false };
+  }
+  const runIdemKey = ctx.batch?.batchKey ?? ctx.idemKey;
+  switch (handler.type) {
+    case "cadra_agent": {
+      if (!handler.agentUuid) {
+        throw new Error(`Stage ${ctx.stage.key} (cadra_agent) missing agentUuid`);
       }
-      case "predicate": {
-        const v = card.sharedContext?.[rule.ref];
-        if (v == null) return false;
-        return String(v) === String(rule.value);
+      const { executionUuid } = await cadra.runAgent({
+        agentUuid: handler.agentUuid,
+        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 };
+    }
+    case "cadra_team": {
+      if (!handler.teamUuid) {
+        throw new Error(`Stage ${ctx.stage.key} (cadra_team) missing teamUuid`);
       }
-      case "and":
-        return rule.rules.every((r) => this.isDue(card, r, now));
-      default:
-        throw new UnknownDueRuleError(
-          rule.kind ?? "<missing>"
-        );
+      const { executionUuid } = await cadra.runTeam({
+        teamUuid: handler.teamUuid,
+        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 };
     }
-  }
-  /**
-   * Coerce a value to a comparable primitive for `field_due` (`<=`): dates →
-   * epoch ms, numeric strings → numbers, else the raw number/string.
-   */
-  toComparable(v) {
-    if (typeof v === "number") return v;
-    if (v instanceof Date) return v.getTime();
-    if (typeof v === "string") {
-      const t = Date.parse(v);
-      if (!Number.isNaN(t)) return t;
-      const n = Number(v);
-      if (!Number.isNaN(n) && v.trim() !== "") return n;
-      return v;
+    case "webhook": {
+      await deliverWebhook(ctx, cadra, webhookOpts);
+      return { dispatched: true };
     }
-    return null;
-  }
-  requireCard(cardId) {
-    const c = this.cards.get(cardId);
-    if (!c) throw new Error(`Card not found: ${cardId}`);
-    return c;
-  }
-  appendLog(cardId, entry) {
-    const list = this.logs.get(cardId) ?? [];
-    list.push({
-      id: nextId("log"),
-      cardId,
-      createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-      ...entry
-    });
-    this.logs.set(cardId, list);
-  }
-  publicCard(c) {
-    const { boardConfigUuid: _b, ...pub } = c;
-    return { ...pub };
+    case "remote_agent": {
+      const h = handler;
+      const remoteAgentUuid = h["remoteAgentUuid"] ?? h["remote_agent_uuid"];
+      if (!remoteAgentUuid) {
+        throw new Error(`Stage ${ctx.stage.key} (remote_agent) missing remoteAgentUuid`);
+      }
+      const { executionUuid } = await cadra.runRemoteAgent({
+        remoteAgentUuid,
+        orgId: ctx.orgId,
+        input: ctx.input,
+        idemKey: runIdemKey,
+        // Board/headless dispatch always disables ask_user (spec §6.5).
+        allowAskUser: false,
+        callbackRef: ctx.callbackUrl
+      });
+      return { dispatched: true, executionUuid };
+    }
+    default:
+      return { dispatched: false };
   }
-};
+}
 
 // src/kanban/adapters/http-adapter.ts
 var HttpAdapterError = class extends Error {
@@ -2307,6 +2353,7 @@ function createEngine(options) {
   async function runStage(cardId, laneKey, internal = {}) {
     const card = await adapter.getCard(cardId);
     if (!card) throw new Error(`Card not found: ${cardId}`);
+    if (internal.requireLane && card.lane !== laneKey) return { dispatched: false };
     const cfg = await pinnedConfigFor(card);
     const stage = laneByKey(cfg, laneKey);
     if (!stage) throw new Error(`Stage "${laneKey}" not in config ${cfg.uuid}`);
@@ -2491,7 +2538,7 @@ ${renderHandoffForPrompt(items)}`;
   async function dispatchOnEntry(cardId, laneKey, cfg) {
     const stage = laneByKey(cfg, laneKey);
     if (hasAutomatedHandler(stage) && dispatchesOnEntry(stage)) {
-      return runStage(cardId, laneKey);
+      return runStage(cardId, laneKey, { requireLane: true });
     }
     return { dispatched: false };
   }
@@ -2516,6 +2563,41 @@ ${renderHandoffForPrompt(items)}`;
     await dispatchOnEntry(cardId, moved.lane, cfg);
     return moved;
   }
+  async function hostMove(cardId, toLane, actor, opts) {
+    const card = await adapter.getCard(cardId);
+    if (!card) throw new Error(`Card not found: ${cardId}`);
+    const cfg = await pinnedConfigFor(card);
+    const toStage = laneByKey(cfg, toLane);
+    if (!toStage) {
+      throw new Error(`Lane "${toLane}" not in config ${cfg.uuid} v${cfg.version}`);
+    }
+    if (card.lane === toLane) return card;
+    const fromLane = opts.expectedFromLane;
+    if (card.lane !== fromLane) {
+      throw new TransitionConflictError(`Expected lane ${fromLane}, card is in ${card.lane}`);
+    }
+    const edge = (cfg.board.transitions ?? []).find(
+      (t) => t.fromLane === fromLane && t.toLane === toLane
+    );
+    const moved = await adapter.applyTransition(cardId, {
+      fromLane,
+      toLane,
+      transitionId: edge?.id ?? `host:${fromLane}->${toLane}`,
+      actor,
+      hostObservation: {
+        ...opts.externalMeta !== void 0 ? { externalMeta: opts.externalMeta } : {},
+        ...opts.observedAt !== void 0 ? { observedAt: opts.observedAt } : {}
+      }
+    });
+    if (ledger) {
+      const fromStage = laneByKey(cfg, fromLane);
+      if (!hasAutomatedHandler(fromStage) && hasAutomatedHandler(toStage)) {
+        await writeHumanToAi(card, moved, toStage, cfg, actor);
+      }
+    }
+    await dispatchOnEntry(cardId, moved.lane, cfg);
+    return moved;
+  }
   async function writeHumanToAi(before, moved, toStage, cfg, actor) {
     if (!ledger) return;
     const recent = await ledger.listHandoffs(before.id, { limit: 50 });
@@ -2554,13 +2636,20 @@ ${renderHandoffForPrompt(items)}`;
     if (!initialLane) {
       throw new Error(`Config ${boardConfigUuid} has no lanes`);
     }
+    if (input.externalRef !== void 0 && adapter.getCardByExternalRef) {
+      const existing = await adapter.getCardByExternalRef(boardConfigUuid, input.externalRef);
+      if (existing) return existing;
+    }
     const card = await adapter.createCard({
       ...input,
       boardConfigUuid,
       configVersion: cfg.version,
       initialLane
     });
-    pinnedVersions.set(card.id, cfg.version);
+    if (input.externalRef !== void 0 && card.lane !== initialLane) {
+      return card;
+    }
+    pinnedVersions.set(card.id, card.configVersion ?? cfg.version);
     await dispatchOnEntry(card.id, initialLane, cfg);
     return await adapter.getCard(card.id) ?? card;
   }
@@ -2849,6 +2938,7 @@ ${renderHandoffForPrompt(items)}`;
   return {
     createCard,
     transition,
+    hostMove,
     runStage: async (cardId, laneKey) => {
       const { runStatus: _rs, ...pub } = await runStage(cardId, laneKey);
       return pub;
@@ -2869,6 +2959,6 @@ function chunk(items, size) {
   return out;
 }
 
-export { ANSWERABLE_HANDOFF_KINDS, BoardConfigClient, CadraLifecycleSource, CapabilitiesNotLoadedError, ConductorUnsupportedError, DEFAULT_BOARD_CEILING, HANDOFF_ANSWER_MAX_TEXT, HANDOFF_OUTPUT_MAX_BYTES, HANDOFF_PROMPT_PREAMBLE, HANDOFF_VERDICT_JSON_SCHEMA, HANDOFF_VERDICT_TASK_SUFFIX, HandoffAnswerError, HttpAdapterError, HttpStorageAdapter, InMemoryStorageAdapter, NotScheduledLaneError, TransitionConflictError, UnknownDueRuleError, WebhookDeliveryError, createEngine, deliverWebhook, dispatchStageHandler, exampleHostHandler, hasHandoffLedger, hmacSign, isSafeHandoffUrl, mapDefinitionToBoard, parseHandoffVerdict, renderHandoffForPrompt, resolveAutoEdge, resolveManualEdge, runAdapterConformance, startExampleHost, toResolvedLifecycle };
+export { ANSWERABLE_HANDOFF_KINDS, BoardConfigClient, CadraLifecycleSource, CapabilitiesNotLoadedError, ConductorUnsupportedError, DEFAULT_BOARD_CEILING, HANDOFF_ANSWER_MAX_TEXT, HANDOFF_OUTPUT_MAX_BYTES, HANDOFF_PROMPT_PREAMBLE, HANDOFF_VERDICT_JSON_SCHEMA, HANDOFF_VERDICT_TASK_SUFFIX, HandoffAnswerError, HostFenceError, HttpAdapterError, HttpStorageAdapter, InMemoryStorageAdapter, NotScheduledLaneError, TransitionConflictError, UnknownDueRuleError, WebhookDeliveryError, createEngine, deliverWebhook, dispatchStageHandler, exampleHostHandler, hasHandoffLedger, hmacSign, isSafeHandoffUrl, mapDefinitionToBoard, parseHandoffVerdict, renderHandoffForPrompt, resolveAutoEdge, resolveManualEdge, runAdapterConformance, startExampleHost, toResolvedLifecycle };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map