@evoclock/pi-agentic-driver 0.9.0 → 0.9.2

package/scripts/enforcement/task_board_core_pi.js

@@ -1,5 +1,5 @@
 // SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
-// SPDX-License-Identifier: AGPL-3.0-or-later
+// SPDX-License-Identifier: AGPL-3.0-only
 
 // BOARD-1 semantic model, closed validator, hash canonicalization, both
 // surface parsers/serializers, the trusted board writer, and the pure
@@ -15,6 +15,11 @@ import { createHash, createHmac, randomBytes } from "node:crypto";
 import { existsSync, readFileSync, writeFileSync, renameSync, mkdirSync, openSync, closeSync, unlinkSync, chmodSync, statSync as fsStatSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { dirname, join } from "node:path";
+// R1/R2 (router design §7.2): the replacement writer derives route trust from
+// the router config and the dead-route rule from observations. These imports
+// are the pure router libraries; the board writer never mutates them.
+import { isDeadRoute } from "./router_replacement_pi.js";
+import { getRouteDecisionIdByDigest } from "./router_store_pi.js";
 
 // ---------------------------------------------------------------------------
 // Closed vocabularies (§1)
@@ -1288,8 +1293,8 @@ export function isDispatchable(card, boardIndex) {
 // Markdown stays canonical for task semantics.
 // ---------------------------------------------------------------------------
 
-export const CLAIMS_SCHEMA = "agentic-driver.board-claims.v2";
-export const ENVELOPE_SCHEMA = "agentic-driver.assignment-envelope.v1";
+export const CLAIMS_SCHEMA = "agentic-driver.board-claims.v3";
+export const ENVELOPE_SCHEMA = "agentic-driver.assignment-envelope.v2";
 export const AUTOMATION_POLICY_SCHEMA = "agentic-driver.automation-policy.v1";
 export const PLACEMENTS = Object.freeze(["container", "host"]);
 export const RISK_LEVELS = Object.freeze(["low", "medium", "high"]);
@@ -1324,17 +1329,21 @@ function writeJsonFileAtomic(path, value) {
 }
 
 // HMAC over the canonical JSON form of the claims content, keyed by the
-// writer-state secret (F1). Covers claims, consumed-claim records, and the
-// transaction record — every authority-bearing field of the file.
-function claimsFileHmac(value, secret) {
+// writer-state secret (F1). Covers claims, consumed-claim records, the
+// transaction record, and the verdict-evidence map — every authority-bearing
+// field of the file. v2→v3 (router design §5.3): `evidence` joins the HMAC
+// input; v2 files are grandfathered (absent evidence reads as {}).
+function claimsFileHmac(value, secret, { includeEvidence = true } = {}) {
+  const payload = {
+    schema: value.schema,
+    generation: value.generation,
+    transaction: value.transaction ?? null,
+    claims: value.claims ?? [],
+    consumedClaims: value.consumedClaims ?? [],
+  };
+  if (includeEvidence) payload.evidence = value.evidence ?? {};
   return createHmac("sha256", secret)
-    .update(canonicalJsonString({
-      schema: value.schema,
-      generation: value.generation,
-      transaction: value.transaction ?? null,
-      claims: value.claims ?? [],
-      consumedClaims: value.consumedClaims ?? [],
-    }), "utf8")
+    .update(canonicalJsonString(payload), "utf8")
     .digest("hex");
 }
 
@@ -1349,16 +1358,35 @@ function exactKeys(value, keys) {
   return actual.length === expected.length && actual.every((key, i) => key === expected[i]);
 }
 
+// v1→v2 (router design §5.1): exactly these keys gained — seatId, accountId,
+// provider, model, role, effort, containmentTier, phase, routeDecisionDigest,
+// reservationId. v1 claims remain valid and dispatchable under the old
+// predicate; new claims require the v2 schema.
 const ENVELOPE_FIELDS = Object.freeze([
   "schema", "envelopeId", "cardId", "cardHash", "repository", "startingRevision",
   "baseRevision", "branch", "allowedPaths", "unchangedPaths", "capabilities",
   "stoppingPoint", "acceptance", "placement", "interactionProfile", "risk",
   "riskCeiling", "mode", "createdAt", "expiry",
+  "seatId", "accountId", "provider", "model", "role", "effort",
+  "containmentTier", "phase", "routeDecisionDigest", "reservationId",
 ]);
+const V1_ENVELOPE_FIELDS = Object.freeze([
+  "schema", "envelopeId", "cardId", "cardHash", "repository", "startingRevision",
+  "baseRevision", "branch", "allowedPaths", "unchangedPaths", "capabilities",
+  "stoppingPoint", "acceptance", "placement", "interactionProfile", "risk",
+  "riskCeiling", "mode", "createdAt", "expiry",
+]);
+const EFFORT_LEVELS = Object.freeze(["low", "default", "high"]);
+const ENVELOPE_PHASES = Object.freeze(["plan", "implement", "review", "escalate"]);
+const CONTAINMENT_TIERS = Object.freeze(["testudo", "docker-policy", "none"]);
 
-export function wellFormedEnvelope(env) {
-  if (env === null || typeof env !== "object" || Array.isArray(env) || !exactKeys(env, ENVELOPE_FIELDS)) return false;
-  if (env.schema !== ENVELOPE_SCHEMA) return false;
+function wellFormedV1Envelope(env) {
+  if (env === null || typeof env !== "object" || Array.isArray(env) || !exactKeys(env, V1_ENVELOPE_FIELDS)) return false;
+  if (env.schema !== "agentic-driver.assignment-envelope.v1") return false;
+  return v1EnvelopeCoreValid(env);
+}
+
+function v1EnvelopeCoreValid(env) {
   if (typeof env.envelopeId !== "string" || !/^[0-9a-f]{32}$/.test(env.envelopeId)) return false;
   if (typeof env.cardId !== "string" || !CARD_ID_RE.test(env.cardId)) return false;
   if (env.cardHash !== null && !/^[0-9a-f]{64}$/.test(env.cardHash)) return false;
@@ -1382,24 +1410,61 @@ export function wellFormedEnvelope(env) {
   return true;
 }
 
-const CLAIM_FIELDS = Object.freeze(["cardId", "claimedAt", "role", "envelopeId", "envelope"]);
+export function wellFormedEnvelope(env) {
+  // Migration (§5.1): v1 claims remain valid and dispatchable under the old
+  // predicate; new claims require the v2 schema.
+  if (env !== null && typeof env === "object" && !Array.isArray(env) && env.schema === "agentic-driver.assignment-envelope.v1") {
+    return wellFormedV1Envelope(env);
+  }
+  if (env === null || typeof env !== "object" || Array.isArray(env) || !exactKeys(env, ENVELOPE_FIELDS)) return false;
+  if (env.schema !== ENVELOPE_SCHEMA) return false;
+  if (!v1EnvelopeCoreValid(env)) return false;
+  // Route fields (§5.1): seatId/provider/model/role non-empty strings;
+  // accountId string or null; effort/containmentTier/phase closed enums;
+  // routeDecisionDigest 64-hex; reservationId string or null.
+  for (const field of ["seatId", "provider", "model", "role"]) {
+    if (typeof env[field] !== "string" || env[field] === "") return false;
+  }
+  if (env.accountId !== null && (typeof env.accountId !== "string" || env.accountId === "")) return false;
+  if (!EFFORT_LEVELS.includes(env.effort)) return false;
+  if (!CONTAINMENT_TIERS.includes(env.containmentTier)) return false;
+  if (!ENVELOPE_PHASES.includes(env.phase)) return false;
+  if (!/^[0-9a-f]{64}$/.test(env.routeDecisionDigest ?? "")) return false;
+  if (env.reservationId !== null && (typeof env.reservationId !== "string" || env.reservationId === "")) return false;
+  return true;
+}
+
+const CLAIM_FIELDS = Object.freeze(["cardId", "claimedAt", "role", "envelopeId", "envelope", "parentClaimId", "attemptIndex"]);
+// v2 grandfathering: claims in v2 files carry exactly the five legacy fields.
+const V2_CLAIM_FIELDS = Object.freeze(["cardId", "claimedAt", "role", "envelopeId", "envelope"]);
 const CONSUMED_FIELDS = Object.freeze(["cardId", "envelopeId", "consumedAt", "reason"]);
 const CONSUMED_REASONS = Object.freeze([
   "expired", "reclaimed", "completed", "exhausted", "cancelled", "failed",
   "waiting-approval", "role-blocked", "worker-unresponsive",
 ]);
 const TRANSACTION_FIELDS = Object.freeze(["op", "cardId", "envelopeId", "at", "phase"]);
-const CLAIMS_STATE_FIELDS = Object.freeze(["schema", "generation", "transaction", "claims", "consumedClaims", "hmac"]);
-
-function wellFormedClaim(claim) {
-  return claim !== null && typeof claim === "object" && !Array.isArray(claim) && exactKeys(claim, CLAIM_FIELDS)
-    && CARD_ID_RE.test(claim.cardId)
-    && ISO_TS_RE.test(claim.claimedAt)
-    && ROLE_NAME_RE.test(claim.role)
-    && /^[0-9a-f]{32}$/.test(claim.envelopeId)
-    && wellFormedEnvelope(claim.envelope)
-    && claim.envelope.envelopeId === claim.envelopeId
-    && claim.envelope.cardId === claim.cardId;
+const REPLACE_TRANSACTION_FIELDS = Object.freeze(["op", "cardId", "envelopeId", "at", "phase", "oldEnvelopeId", "oldReason"]);
+// v2→v3: verdict evidence is closed and HMAC-authenticated; claims also gain lineage.
+const CLAIMS_STATE_FIELDS = Object.freeze(["schema", "generation", "transaction", "claims", "consumedClaims", "evidence", "hmac"]);
+const V2_CLAIMS_STATE_FIELDS = Object.freeze(["schema", "generation", "transaction", "claims", "consumedClaims", "hmac"]);
+const EVIDENCE_KEY_RE = /^[0-9a-f]{64}$/;
+
+function wellFormedClaim(claim, { legacy = false } = {}) {
+  if (claim === null || typeof claim !== "object" || Array.isArray(claim)) return false;
+  if (!exactKeys(claim, legacy ? V2_CLAIM_FIELDS : CLAIM_FIELDS)) return false;
+  if (!CARD_ID_RE.test(claim.cardId)) return false;
+  if (!ISO_TS_RE.test(claim.claimedAt)) return false;
+  if (!ROLE_NAME_RE.test(claim.role)) return false;
+  if (!/^[0-9a-f]{32}$/.test(claim.envelopeId)) return false;
+  if (!wellFormedEnvelope(claim.envelope)) return false;
+  if (claim.envelope.envelopeId !== claim.envelopeId) return false;
+  if (claim.envelope.cardId !== claim.cardId) return false;
+  if (legacy) return true;
+  // Lineage (§7.3): parentClaimId is a claim identity string or null
+  // (initial dispatch); attemptIndex is a non-negative integer starting
+  // at 0 for the initial attempt.
+  return (claim.parentClaimId === null || (typeof claim.parentClaimId === "string" && claim.parentClaimId !== ""))
+    && Number.isInteger(claim.attemptIndex) && claim.attemptIndex >= 0;
 }
 
 function wellFormedConsumedClaim(claim) {
@@ -1411,11 +1476,25 @@ function wellFormedConsumedClaim(claim) {
 }
 
 function wellFormedTransaction(tx) {
-  return tx === null
-    || (typeof tx === "object" && !Array.isArray(tx) && exactKeys(tx, TRANSACTION_FIELDS)
-      && tx.op === "claim" && CARD_ID_RE.test(tx.cardId)
+  if (tx === null) return true;
+  if (typeof tx !== "object" || Array.isArray(tx)) return false;
+  if (tx.op === "claim") {
+    return exactKeys(tx, TRANSACTION_FIELDS)
+      && CARD_ID_RE.test(tx.cardId)
       && /^[0-9a-f]{32}$/.test(tx.envelopeId) && ISO_TS_RE.test(tx.at)
-      && tx.phase === "claims-written");
+      && tx.phase === "claims-written";
+  }
+  // §10.4 replace-attempt transaction: the pre-recorded replacement identity
+  // plus the old envelope ID and terminal reason it replaces.
+  if (tx.op === "replace-attempt") {
+    return exactKeys(tx, REPLACE_TRANSACTION_FIELDS)
+      && CARD_ID_RE.test(tx.cardId)
+      && /^[0-9a-f]{32}$/.test(tx.envelopeId) && /^[0-9a-f]{32}$/.test(tx.oldEnvelopeId)
+      && ISO_TS_RE.test(tx.at)
+      && tx.phase === "claims-written"
+      && CONSUMED_REASONS.includes(tx.oldReason);
+  }
+  return false;
 }
 
 // Read and VERIFY the claims file. Missing file → fresh ONLY while the
@@ -1435,16 +1514,33 @@ export function readClaimsState(boardPath) {
     if (writerState.claimsDigest !== null || writerState.claimsGeneration > 0) {
       return { ok: false, reason: "the claims file is missing but the writer state anchors issued claims state — deletion is rejected (fails closed)" };
     }
-    return { ok: true, missing: true, state: { generation: 0, transaction: null, claims: [], consumedClaims: [] } };
+    return { ok: true, missing: true, state: { generation: 0, transaction: null, claims: [], consumedClaims: [], evidence: {} } };
   }
   const value = readJsonFile(path);
-  if (value === null || typeof value !== "object" || Array.isArray(value) || !exactKeys(value, CLAIMS_STATE_FIELDS)) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return { ok: false, reason: "the claims file is malformed or has an unknown shape (fails closed)" };
+  }
+  // Schema migration (§5.3): v2 files are grandfathered — an absent evidence
+  // map reads as {}, claims keep the legacy five-field shape, and the HMAC is
+  // verified over the legacy input. v3 requires the evidence key, the lineage
+  // fields, and the extended HMAC.
+  const legacy = value.schema === "agentic-driver.board-claims.v2";
+  let evidence = value.evidence;
+  if (legacy) {
+    if (!exactKeys(value, V2_CLAIMS_STATE_FIELDS)) {
+      return { ok: false, reason: "the claims file is malformed or has an unknown shape (fails closed)" };
+    }
+    evidence = {};
+  } else if (!exactKeys(value, CLAIMS_STATE_FIELDS)) {
     return { ok: false, reason: "the claims file is malformed or has an unknown shape (fails closed)" };
   }
+  if (!isPlainEvidenceMap(evidence)) {
+    return { ok: false, reason: "the claims evidence map is malformed (fails closed)" };
+  }
   if (!Array.isArray(value.claims) || !Array.isArray(value.consumedClaims)
     || !Number.isInteger(value.generation) || value.generation < 0
     || !wellFormedTransaction(value.transaction)
-    || !value.claims.every(wellFormedClaim)
+    || !value.claims.every((claim) => wellFormedClaim(claim, { legacy }))
     || !value.consumedClaims.every(wellFormedConsumedClaim)) {
     return { ok: false, reason: "the claims file contains a malformed record (fails closed)" };
   }
@@ -1457,7 +1553,8 @@ export function readClaimsState(boardPath) {
   if (writerState.secret === null) {
     return { ok: false, reason: "writer state file has no secret to verify the claims file (fails closed)" };
   }
-  if (typeof value.hmac !== "string" || value.hmac !== claimsFileHmac(value, writerState.secret)) {
+  if (typeof value.hmac !== "string"
+    || value.hmac !== claimsFileHmac({ ...value, evidence }, writerState.secret, { includeEvidence: !legacy })) {
     return { ok: false, reason: "the claims file HMAC does not verify — tampered or forged (fails closed)" };
   }
   // Deletion/rollback guard: the generation must be exactly the anchored
@@ -1475,6 +1572,7 @@ export function readClaimsState(boardPath) {
       transaction: value.transaction,
       claims: value.claims,
       consumedClaims: value.consumedClaims,
+      evidence,
     },
   };
 }
@@ -1495,6 +1593,24 @@ function claimsAnchorDigest(value, secret) {
     .digest("hex");
 }
 
+const EVIDENCE_FIELDS = Object.freeze(["evalInputDigest", "answers", "probabilities", "thresholdPolicy", "versions", "requestId", "timestamp"]);
+function isPlainEvidenceMap(evidence) {
+  if (evidence === null || typeof evidence !== "object" || Array.isArray(evidence)) return false;
+  const keys = Object.keys(evidence);
+  if (keys.length > 64) return false;
+  for (const key of keys) {
+    const r = evidence[key];
+    if (!EVIDENCE_KEY_RE.test(key) || r === null || typeof r !== "object" || Array.isArray(r) || !exactKeys(r, EVIDENCE_FIELDS)) return false;
+    if (r.evalInputDigest !== key || !EVIDENCE_KEY_RE.test(r.evalInputDigest)) return false;
+    if (r.answers === null || typeof r.answers !== "object" || Array.isArray(r.answers)
+      || r.probabilities === null || typeof r.probabilities !== "object" || Array.isArray(r.probabilities)
+      || r.thresholdPolicy === null || typeof r.thresholdPolicy !== "object" || Array.isArray(r.thresholdPolicy)
+      || r.versions === null || typeof r.versions !== "object" || Array.isArray(r.versions)) return false;
+    if (typeof r.requestId !== "string" || r.requestId === "" || !ISO_TS_RE.test(r.timestamp) || JSON.stringify(r).length > 8192) return false;
+  }
+  return true;
+}
+
 // Recover the two-file claims/anchor commit. The complete authenticated next
 // claims state is staged in writer state first, so either crash window rolls
 // forward deterministically rather than accepting an older file.
@@ -1503,9 +1619,15 @@ function recoverClaimsAnchorLocked(boardPath) {
   const writerState = readWriterState(statePath);
   const pending = writerState.pendingClaimsState;
   if (pending === null) return { ok: true, recovered: false };
-  if (writerState.secret === null || !pending || typeof pending !== "object"
-    || !exactKeys(pending, CLAIMS_STATE_FIELDS)
-    || pending.hmac !== claimsFileHmac(pending, writerState.secret)) {
+  if (writerState.secret === null || !pending || typeof pending !== "object") {
+    return { ok: false, reason: "the staged claims-anchor transaction is malformed or unauthenticated (fails closed)" };
+  }
+  const pendingLegacy = pending.schema === "agentic-driver.board-claims.v2";
+  if (pendingLegacy ? !exactKeys(pending, V2_CLAIMS_STATE_FIELDS) : !exactKeys(pending, CLAIMS_STATE_FIELDS)
+    || !Array.isArray(pending.claims) || !pending.claims.every((claim) => wellFormedClaim(claim, { legacy: pendingLegacy }))) {
+    return { ok: false, reason: "the staged claims-anchor transaction is malformed or unauthenticated (fails closed)" };
+  }
+  if (pending.hmac !== claimsFileHmac(pending, writerState.secret, { includeEvidence: !pendingLegacy })) {
     return { ok: false, reason: "the staged claims-anchor transaction is malformed or unauthenticated (fails closed)" };
   }
   writeJsonFileAtomic(claimsPath(boardPath), pending);
@@ -1529,12 +1651,18 @@ function writeClaims(boardPath, claims, { consumedClaims = null, transaction = n
   writerState = readWriterState(statePath);
   const previous = readClaimsState(boardPath);
   if (!previous.ok) throw Object.assign(new Error(previous.reason), { code: "claims-corrupt" });
+  // v2→v3 migration: legacy claims are upgraded in place on the next write —
+  // absent lineage fields take their initial-dispatch defaults (§7.3).
+  const upgradedClaims = claims.map((claim) => claim.parentClaimId === undefined && claim.attemptIndex === undefined
+    ? { ...claim, parentClaimId: null, attemptIndex: 0 }
+    : claim);
   const value = {
     schema: CLAIMS_SCHEMA,
     generation: previous.state.generation + 1,
     transaction,
-    claims,
+    claims: upgradedClaims,
     consumedClaims: consumedClaims ?? previous.state.consumedClaims,
+    evidence: previous.state.evidence ?? {},
   };
   value.hmac = claimsFileHmac(value, writerState.secret);
   // Prepare → claims → commit. Because prepare contains the complete signed
@@ -1567,7 +1695,103 @@ export function readAutomationPolicy(boardPath, { configPath = null } = {}) {
 const POLICY_FIELDS = Object.freeze([
   "roles", "placement", "maxConcurrent", "expiry", "envelopeExpiryHours",
   "board", "riskCeiling", "allowPerCardRiskOverride", "acceptedRepositories",
+  "pulse",
+]);
+
+// Pulse policy v1 (PULSE_DESIGN_v3 §3): one optional closed `pulse` object
+// inside the existing board-bound automation policy. No second policy store:
+// the pulse record is validated here, beside the shipped policy fields, and
+// a policy without `pulse` behaves exactly as before (Pulse disabled).
+const PULSE_FIELDS = Object.freeze([
+  "enabled", "mode", "intervalSeconds", "fillOnStart", "routing",
+  "stallTimeoutSeconds", "unattendedHostRiskAccepted",
 ]);
+const PULSE_ROUTE_FIELDS = Object.freeze(["model", "maxConcurrent"]);
+const PULSE_MODES = Object.freeze(["interactive", "automated"]);
+const PULSE_MODEL_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+function pulseCapacityOk(value) {
+  return Number.isInteger(value) && value >= 1 && value <= 32;
+}
+
+function checkPulseRouteEntry(entry, { seen }) {
+  if (entry === null || typeof entry !== "object" || Array.isArray(entry)
+    || !exactKeys(entry, PULSE_ROUTE_FIELDS)) {
+    return "each routing entry must have exactly {model, maxConcurrent}";
+  }
+  if (typeof entry.model !== "string" || !PULSE_MODEL_RE.test(entry.model)) {
+    return `route model "${entry.model}" is not an exact provider/model identifier`;
+  }
+  if (seen.has(entry.model)) {
+    return `model "${entry.model}" appears more than once for this role`;
+  }
+  seen.add(entry.model);
+  if (!pulseCapacityOk(entry.maxConcurrent)) {
+    return `route maxConcurrent for "${entry.model}" must be an integer from 1 through 32`;
+  }
+  return null;
+}
+
+// Validate the optional `pulse` object. Returns {ok, pulse, reason}. Fails
+// closed on unknown fields, duplicate models, routing roles absent from the
+// policy's declared roles, and invalid capacities.
+export function checkPulsePolicy(pulse, { roles = null } = {}) {
+  if (pulse === null || pulse === undefined) return { ok: true, pulse: null, reason: null };
+  if (typeof pulse !== "object" || Array.isArray(pulse) || !exactKeys(pulse, PULSE_FIELDS)) {
+    return { ok: false, pulse: null, reason: "the automation policy pulse object has unknown or missing fields — the pulse shape is closed (fails closed)" };
+  }
+  if (typeof pulse.enabled !== "boolean") {
+    return { ok: false, pulse: null, reason: "pulse.enabled is required and must be a boolean (fails closed)" };
+  }
+  if (!PULSE_MODES.includes(pulse.mode)) {
+    return { ok: false, pulse: null, reason: `pulse.mode must be one of ${PULSE_MODES.join(", ")} (fails closed)` };
+  }
+  if (!Number.isInteger(pulse.intervalSeconds) || pulse.intervalSeconds < 10 || pulse.intervalSeconds > 86400) {
+    return { ok: false, pulse: null, reason: "pulse.intervalSeconds must be an integer from 10 through 86400 (fails closed)" };
+  }
+  if (typeof pulse.fillOnStart !== "boolean") {
+    return { ok: false, pulse: null, reason: "pulse.fillOnStart must be a boolean (fails closed)" };
+  }
+  if (pulse.routing === null || typeof pulse.routing !== "object" || Array.isArray(pulse.routing)) {
+    return { ok: false, pulse: null, reason: "pulse.routing must be an object keyed by declared policy role (fails closed)" };
+  }
+  const declared = Array.isArray(roles) ? roles : [];
+  for (const role of Object.keys(pulse.routing)) {
+    if (!declared.includes(role)) {
+      return { ok: false, pulse: null, reason: `pulse.routing declares role "${role}", which is absent from the policy roles (fails closed)` };
+    }
+    const entry = pulse.routing[role];
+    if (entry === null || typeof entry !== "object" || Array.isArray(entry)
+      || !exactKeys(entry, ["preferred", "fallback", "maxConcurrent"])) {
+      return { ok: false, pulse: null, reason: `pulse.routing["${role}"] must have exactly {preferred, fallback, maxConcurrent} (fails closed)` };
+    }
+    if (!Array.isArray(entry.preferred) || entry.preferred.length === 0) {
+      return { ok: false, pulse: null, reason: `pulse.routing["${role}"].preferred must list at least one route (fails closed)` };
+    }
+    if (!Array.isArray(entry.fallback)) {
+      return { ok: false, pulse: null, reason: `pulse.routing["${role}"].fallback must be a list (fails closed)` };
+    }
+    const seen = new Set();
+    for (const route of entry.preferred) {
+      const reason = checkPulseRouteEntry(route, { seen });
+      if (reason) return { ok: false, pulse: null, reason: `pulse.routing["${role}"].preferred: ${reason} (fails closed)` };
+    }
+    for (const route of entry.fallback) {
+      const reason = checkPulseRouteEntry(route, { seen });
+      if (reason) return { ok: false, pulse: null, reason: `pulse.routing["${role}"].fallback: ${reason} (fails closed)` };
+    }
+    if (!pulseCapacityOk(entry.maxConcurrent)) {
+      return { ok: false, pulse: null, reason: `pulse.routing["${role}"].maxConcurrent must be an integer from 1 through 32 (fails closed)` };
+    }
+  }
+  if (!Number.isInteger(pulse.stallTimeoutSeconds) || pulse.stallTimeoutSeconds < 30 || pulse.stallTimeoutSeconds > 86400) {
+    return { ok: false, pulse: null, reason: "pulse.stallTimeoutSeconds must be an integer from 30 through 86400 (fails closed)" };
+  }
+  if (typeof pulse.unattendedHostRiskAccepted !== "boolean") {
+    return { ok: false, pulse: null, reason: "pulse.unattendedHostRiskAccepted must be a boolean (fails closed)" };
+  }
+  return { ok: true, pulse, reason: null };
+}
 
 export function checkAutomationPolicy(policy, { now = null, boardPath = null } = {}) {
   const at = now ?? new Date().toISOString();
@@ -1623,6 +1847,14 @@ export function checkAutomationPolicy(policy, { now = null, boardPath = null } =
     || !policy.acceptedRepositories.every((repo) => typeof repo === "string" && repo !== "" && !repo.includes(".."))) {
     return { ok: false, reason: "the automation policy acceptedRepositories must be a non-empty closed list of repository paths (fails closed)" };
   }
+
+  // Pulse (§3): the optional closed pulse object is validated in place. A
+  // policy without `pulse` is unchanged and means Pulse is disabled.
+  if (policy.pulse !== undefined) {
+    const pulse = checkPulsePolicy(policy.pulse, { roles: policy.roles });
+    if (!pulse.ok) return { ok: false, reason: pulse.reason };
+  }
+
   return { ok: true, policy, reason: null };
 }
 
@@ -1639,7 +1871,7 @@ export function repositoryAccepted(policy, repository) {
 // in), the card's base revision is bound in when present (branch chaining),
 // and the risk classification comes from the policy (per-card override only
 // when the policy allows).
-export function createEnvelope({ card, policy, now = null, repository = null, startingRevision = null }) {
+export function createEnvelope({ card, policy, now = null, repository = null, startingRevision = null, route = null }) {
   const at = now ?? new Date().toISOString();
   const envelopeId = randomBytes(16).toString("hex");
   const expiryHours = Number.isFinite(policy?.envelopeExpiryHours) && policy.envelopeExpiryHours > 0
@@ -1656,6 +1888,22 @@ export function createEnvelope({ card, policy, now = null, repository = null, st
   // envelope's starting revision IS the base (branch chaining), not merely a
   // copied field; execution validation enforces HEAD === startingRevision.
   const startRev = startingRevision ?? card.base ?? gitHead(repo);
+  const r = route;
+  if (r === null || typeof r !== "object"
+    || typeof r.seatId !== "string" || r.seatId === ""
+    || typeof r.provider !== "string" || r.provider === ""
+    || typeof r.model !== "string" || r.model === ""
+    || typeof r.role !== "string" || r.role === ""
+    || !EFFORT_LEVELS.includes(r.effort) || !CONTAINMENT_TIERS.includes(r.containmentTier)
+    || !ENVELOPE_PHASES.includes(r.phase) || !/^[0-9a-f]{64}$/.test(r.routeDecisionDigest ?? "")) {
+    throw Object.assign(new Error("new claims require a complete authenticated route decision"), { code: "route-required" });
+  }
+  const routeFields = {
+    seatId: r.seatId, accountId: r.accountId ?? null, provider: r.provider,
+    model: r.model, role: r.role, effort: r.effort, containmentTier: r.containmentTier,
+    phase: r.phase, routeDecisionDigest: r.routeDecisionDigest,
+    reservationId: typeof r.reservationId === "string" && r.reservationId !== "" ? r.reservationId : null,
+  };
   return deepFreeze({
     schema: ENVELOPE_SCHEMA,
     envelopeId,
@@ -1677,6 +1925,7 @@ export function createEnvelope({ card, policy, now = null, repository = null, st
     mode: "automated",
     createdAt: at,
     expiry,
+    ...routeFields,
   });
 }
 
@@ -1746,7 +1995,62 @@ export function selectDispatchableCard({ cards, boardPath, activeClaims, cardId
 // the new complete state (both writes are atomic renames); two concurrent
 // claims can never both win because the entire read-decide-write sequence
 // holds the lock. Expired claims are released first, inside the same lock.
-export function claimCard({ boardPath, cardId = null, role, policy = null, configPath = null, now = null, repository = null, startingRevision = null }) {
+export function claimCard({ boardPath, cardId = null, role, policy = null, configPath = null, now = null, repository = null, startingRevision, route = null }) {
+  return claimCardInternal({ boardPath, cardId, role, policy, configPath, now, repository, startingRevision, confirmedBatch: null, route });
+}
+
+// ---------------------------------------------------------------------------
+// Trusted Pulse-internal confirmed-batch claim path. Host placement is
+// claimable ONLY here, and only for a batch context object this module has
+// registered after one native confirmation (registerConfirmedBatchForClaims),
+// matched by object identity — never by batchId string, user/model field, or
+// durable state. Each confirmed entry is single-use: one claim consumes it,
+// and a claim for a card outside the confirmed set is refused.
+// ---------------------------------------------------------------------------
+
+// batch context object (WeakMap key) -> Set of cardIds still claimable from it.
+const confirmedBatchClaims = new WeakMap();
+
+export function registerConfirmedBatchForClaims(batch) {
+  if (batch?.schema !== "agentic-driver.pulse-batch.v1" || typeof batch.batchId !== "string" || !Array.isArray(batch.entries)) {
+    throw new Error("registerConfirmedBatchForClaims requires a minted pulse batch context");
+  }
+  confirmedBatchClaims.set(batch, new Set(batch.entries.map((entry) => entry.cardId)));
+  return batch.batchId;
+}
+
+export function claimCardForConfirmedBatch({ boardPath, cardId = null, role, policy = null, configPath = null, now = null, repository = null, startingRevision = null, confirmedBatch = null }) {
+  if (confirmedBatch === null || !confirmedBatchClaims.has(confirmedBatch)) {
+    return { ok: false, code: "confirmed-batch-required", reason: "host placement is claimable only through the Pulse confirmed-batch path with a batch registered after native confirmation (fails closed)" };
+  }
+  if (typeof cardId !== "string" || cardId === "") {
+    return { ok: false, code: "confirmed-batch-card-required", reason: "a confirmed-batch claim requires an explicit cardId from the confirmed batch (fails closed)" };
+  }
+  const expiresMs = Date.parse(confirmedBatch.expiresAt);
+  const nowMs = Date.parse(now ?? new Date().toISOString());
+  if (!Number.isFinite(expiresMs) || !Number.isFinite(nowMs)) {
+    return { ok: false, code: "confirmed-batch-time-invalid", reason: "the confirmed batch expiry or current time is invalid (fails closed)" };
+  }
+  if (nowMs >= expiresMs) {
+    return { ok: false, code: "confirmed-batch-expired", reason: "the confirmed batch context has expired; a fresh preview and confirmation is required" };
+  }
+  const entry = confirmedBatch.entries.find((e) => e.cardId === cardId);
+  if (!entry || entry.placement !== "host") {
+    return { ok: false, code: "confirmed-batch-card-mismatch", reason: "the requested card is not a host entry in the confirmed batch; confirmations cannot be crossed between batch entries" };
+  }
+  if (entry.state !== "reserved") {
+    return { ok: false, code: "confirmed-batch-entry-not-reserved", reason: `confirmed batch entry is ${entry.state}, not reserved; it cannot be claimed again (single-use)` };
+  }
+  const claimable = confirmedBatchClaims.get(confirmedBatch);
+  if (!claimable.has(cardId)) {
+    return { ok: false, code: "confirmed-batch-entry-consumed", reason: "the confirmed batch entry was already claimed; confirmation is single-use" };
+  }
+  const result = claimCardInternal({ boardPath, cardId, role, policy, configPath, now, repository, startingRevision, confirmedBatch });
+  if (result.ok) claimable.delete(cardId); // consume the single-use confirmation
+  return result;
+}
+
+function claimCardInternal({ boardPath, cardId = null, role, policy = null, configPath = null, now = null, repository = null, startingRevision = null, confirmedBatch = null, route = null }) {
   if (typeof boardPath !== "string" || boardPath === "") {
     throw Object.assign(new Error("boardPath is required"), { code: "board-path-required" });
   }
@@ -1760,7 +2064,7 @@ export function claimCard({ boardPath, cardId = null, role, policy = null, confi
   for (let attempt = 0; ; attempt += 1) {
     try {
       return withWriterLock(boardPath, () =>
-        claimCardLocked({ boardPath, cardId, role, policy, configPath, now, repository, startingRevision }));
+        claimCardLocked({ boardPath, cardId, role, policy, configPath, now, repository, startingRevision, confirmedBatch, route }));
     } catch (error) {
       if (error?.code === "writer-lock-held" && attempt < 20) {
         sleepSync(25);
@@ -1774,7 +2078,27 @@ export function claimCard({ boardPath, cardId = null, role, policy = null, confi
   }
 }
 
-function claimCardLocked({ boardPath, cardId, role, policy, configPath, now, repository, startingRevision }) {
+// Route fields for confirmed-batch claims: the batch entry carries the
+// route decision's identity (seatId/provider/model/digest/reservationId)
+// minted by the scheduler from the route decision — never recomputed here.
+function confirmedBatchRouteFor(cardId, confirmedBatch) {
+  const entry = (confirmedBatch?.entries ?? []).find((e) => e.cardId === cardId);
+  if (!entry) return null;
+  return {
+    seatId: entry.seatId,
+    accountId: entry.accountId,
+    provider: entry.provider,
+    model: entry.model,
+    role: entry.role,
+    effort: entry.effort,
+    containmentTier: entry.containmentTier,
+    phase: entry.phase,
+    routeDecisionDigest: entry.routeDecisionDigest,
+    reservationId: entry.reservationId,
+  };
+}
+
+function claimCardLocked({ boardPath, cardId, role, policy, configPath, now, repository, startingRevision, confirmedBatch = null, route = null }) {
   const at = now ?? new Date().toISOString();
   if (!existsSync(boardPath)) {
     return { ok: false, code: "board-unavailable", reason: "board file is no longer present (board-unavailable)" };
@@ -1813,9 +2137,17 @@ function claimCardLocked({ boardPath, cardId, role, policy, configPath, now, rep
   if (!policyCheck.policy.roles.includes(role)) {
     return { ok: false, code: "policy-role-refused", reason: `role "${role}" is not declared in the automation policy (fails closed)` };
   }
-  // §3.4 mode table: automated placement is container/microVM, always.
-  if (policyCheck.policy.placement !== "container") {
-    return { ok: false, code: "policy-placement-refused", reason: "automated board dispatch requires container placement per the automation policy (§3.4)" };
+  // §3.4 mode table: ordinary claims are contained-only (container/microVM),
+  // always. Host placement is claimable ONLY through the trusted Pulse-internal
+  // confirmed-batch path (claimCardForConfirmedBatch), which requires a batch
+  // context registered after one native confirmation. Static pulse.mode=
+  // "interactive" plus host placement is never enough on its own; automated
+  // dispatch may never use host placement.
+  if (confirmedBatch === null && policyCheck.policy.placement !== "container") {
+    return { ok: false, code: "policy-placement-refused", reason: "ordinary board dispatch requires container placement per the automation policy (§3.4); host placement is claimable only through the Pulse confirmed-batch path" };
+  }
+  if (confirmedBatch !== null && policyCheck.policy.placement !== "host") {
+    return { ok: false, code: "policy-placement-refused", reason: "the Pulse confirmed-batch claim path requires host placement (fails closed)" };
   }
   // F4: the starting revision comes from the card's repository — the
   // workspace the board lives in, not process.cwd(). A caller-supplied
@@ -1856,13 +2188,16 @@ function claimCardLocked({ boardPath, cardId, role, policy, configPath, now, rep
       : "no dispatchable unclaimed card is available" };
   }
   const card = selected.card;
-  const envelope = createEnvelope({ card, policy: policyCheck.policy, now: at, repository: repo, startingRevision });
+  const selectedRoute = confirmedBatch !== null ? confirmedBatchRouteFor(card.cardId, confirmedBatch) : route;
+  const envelope = createEnvelope({ card, policy: policyCheck.policy, now: at, repository: repo, startingRevision, route: selectedRoute });
   const claim = {
     cardId: card.cardId,
     claimedAt: at,
     role,
     envelopeId: envelope.envelopeId,
     envelope,
+    parentClaimId: null,
+    attemptIndex: 0,
   };
   const nextClaims = [...activeClaims, claim];
   // F3: the transaction record goes into the claims file BEFORE the
@@ -2186,6 +2521,220 @@ export function reclaimClaim({ boardPath, cardId = null, envelopeId = null } = {
   });
 }
 
+// §10.4 dispatcher-owned recoverable replaceAttempt: one transition under the
+// writer lock that replaces a failed/unresponsive attempt with a new attempt
+// (new envelope, new claim) for the same card. Trusted input: the expected
+// active card ID, old envelope ID, terminal reason, and replacement route
+// (role/repository/starting revision). Not a public model action.
+//
+// Transaction shape: a prepared transaction is durably staged (HMAC-covered
+// via the claims file's own authentication) containing the old terminal
+// evidence and the pre-recorded new attempt identity. Only then is the old
+// envelope consumed and the new claim published; the transaction record
+// clears once the projection is republished. Recovery is idempotent and runs
+// first: if only the old consumption landed, the replacement rolls forward
+// only while all bound identities still match; otherwise it returns
+// REVIEW_REQUIRED. Recovery never creates another envelope.
+const REPLACE_TRANSACTION_OPS = Object.freeze(["replace-attempt"]);
+const REPLACE_TRANSACTION_PHASES = Object.freeze(["prepared", "committed"]);
+
+export function replaceAttempt({ boardPath, cardId, envelopeId, reason, replacement = {}, now = null } = {}) {
+  if (typeof boardPath !== "string" || boardPath === "") {
+    throw Object.assign(new Error("boardPath is required"), { code: "board-path-required" });
+  }
+  if (typeof cardId !== "string" || !CARD_ID_RE.test(cardId)) {
+    throw Object.assign(new Error("cardId must be a well-formed card ID"), { code: "invalid-input" });
+  }
+  if (typeof envelopeId !== "string" || !/^[0-9a-f]{32}$/.test(envelopeId)) {
+    throw Object.assign(new Error("envelopeId must be a 32-hex envelope ID"), { code: "invalid-input" });
+  }
+  if (!CONSUMED_REASONS.includes(reason)) {
+    throw Object.assign(new Error(`reason must be one of ${CONSUMED_REASONS.join(", ")}`), { code: "invalid-input" });
+  }
+  const at = now ?? new Date().toISOString();
+  return withWriterLock(boardPath, () => replaceAttemptLocked({ boardPath, cardId, envelopeId, reason, replacement, at }));
+}
+
+function replaceAttemptLocked({ boardPath, cardId, envelopeId, reason, replacement, at }) {
+  // Recovery first (idempotent): roll any interrupted prior transaction
+  // forward before observing state, never creating another envelope.
+  const anchorRecovery = recoverClaimsAnchorLocked(boardPath);
+  if (!anchorRecovery.ok) {
+    return { ok: false, code: "claims-anchor-recovery-failed", recoverable: true, reason: anchorRecovery.reason };
+  }
+  const read = readClaimsState(boardPath);
+  if (!read.ok) return { ok: false, code: "claims-corrupt", reason: read.reason };
+  const reconciliation = reconcileTransactionLocked({ boardPath, state: read.state });
+  if (reconciliation?.failed) {
+    return { ok: false, code: "recovery-failed", recoverable: true, reason: reconciliation.reason };
+  }
+
+  // The old attempt must be the exact active authenticated claim for this
+  // card. Drift, reuse, or a consumed old envelope fails closed.
+  const oldClaim = read.state.claims.find((claim) => claim.envelopeId === envelopeId);
+  if (!oldClaim) {
+    return { ok: false, code: "envelope-not-active",
+      reason: read.state.consumedClaims.some((entry) => entry.envelopeId === envelopeId)
+        ? "the old envelope attempt was already consumed — a replacement requires a fresh dispatch (single-attempt lifecycle)"
+        : `no active claim for envelope ${envelopeId} (fails closed)` };
+  }
+  if (oldClaim.cardId !== cardId) {
+    return { ok: false, code: "card-drift", reason: `envelope ${envelopeId} is bound to card ${oldClaim.cardId}, not ${cardId} (fails closed)` };
+  }
+
+  // Re-evaluate current observations under the lock: card identity/hash,
+  // policy validity, and capacity for the replacement route.
+  if (!existsSync(boardPath)) {
+    return { ok: false, code: "board-unavailable", reason: "board file is no longer present (board-unavailable)" };
+  }
+  const validatedBoard = validateBoard(readFileSync(boardPath, "utf8"), {});
+  if (!validatedBoard.ok) return { ok: false, code: "board-invalid", errors: validatedBoard.errors };
+  const card = validatedBoard.cards.find((entry) => entry.cardId === cardId);
+  if (!card) return { ok: false, code: "card-not-found", reason: `card ${cardId} no longer exists on the board (drift — REVIEW_REQUIRED)` };
+  const currentHash = card.hash ?? computeCardHash(card);
+  if (currentHash !== oldClaim.envelope.cardHash) {
+    return { ok: false, code: "card-hash-drift", reason: "the card hash drifted from the old envelope binding — semantic edits require human review (REVIEW_REQUIRED)" };
+  }
+
+  const resolvedPolicy = readAutomationPolicy(boardPath);
+  const policyCheck = checkAutomationPolicy(resolvedPolicy, { now: at, boardPath });
+  if (!policyCheck.ok) {
+    return { ok: false, code: "policy-refused", reason: policyCheck.reason };
+  }
+  const replacementRole = typeof replacement.role === "string" && replacement.role !== "" ? replacement.role : oldClaim.role;
+  if (!policyCheck.policy.roles.includes(replacementRole)) {
+    return { ok: false, code: "policy-role-refused", reason: `replacement role "${replacementRole}" is not declared in the automation policy (fails closed)` };
+  }
+  if (policyCheck.policy.placement !== "container") {
+    return { ok: false, code: "policy-placement-refused", reason: "automated board dispatch requires container placement per the automation policy (§3.4)" };
+  }
+  const replacementRepository = typeof replacement.repository === "string" && replacement.repository !== ""
+    ? replacement.repository
+    : dirname(boardPath);
+  if (!repositoryAccepted(policyCheck.policy, replacementRepository)) {
+    return { ok: false, code: "policy-repository-refused", reason: `repository "${replacementRepository}" is not on the automation policy's acceptedRepositories list (fails closed)` };
+  }
+  const activeClaims = releaseExpiredClaimsLocked({ boardPath, at, state: read.state });
+  const concurrency = Number(policyCheck.policy.maxConcurrent);
+  // Capacity: the old claim is being replaced, so it frees exactly one slot.
+  if (activeClaims.filter((claim) => claim.envelopeId !== envelopeId).length >= concurrency) {
+    return { ok: false, code: "policy-concurrency-refused", reason: `the automation policy allows at most ${concurrency} concurrent claim(s); no free slot for the replacement` };
+  }
+
+  // Pre-record the replacement identity, then durably stage the prepared
+  // transaction BEFORE consuming the old envelope. The staged claims state
+  // carries the complete signed next value, so either crash window rolls
+  // forward deterministically (the same prepare→claims→commit scheme as
+  // claimCard, extended with the replace op and phase).
+  const oldRoute = {
+    seatId: oldClaim.envelope.seatId, accountId: oldClaim.envelope.accountId,
+    provider: oldClaim.envelope.provider, model: oldClaim.envelope.model, role: replacementRole,
+    effort: oldClaim.envelope.effort, containmentTier: oldClaim.envelope.containmentTier,
+    phase: oldClaim.envelope.phase, routeDecisionDigest: oldClaim.envelope.routeDecisionDigest,
+    reservationId: oldClaim.envelope.reservationId,
+  };
+  const requestedRoute = replacement.route ?? oldRoute;
+  if (requestedRoute.seatId === oldRoute.seatId
+    && canonicalJsonString(requestedRoute) !== canonicalJsonString(oldRoute)) {
+    return { ok: false, code: "replacement-route-invalid", reason: "same-seat replacement is pinned to every field of the prior authenticated envelope (fails closed)" };
+  }
+  if (requestedRoute.seatId !== oldRoute.seatId) {
+    // R1: different-seat replacement route fidelity. The caller-supplied
+    // requestedRoute is NEVER the route authority. The seat is resolved from
+    // the trusted router config for decision.selectedSeatId; the route fields
+    // must then equal that seat's fields (effort follows the card), and the
+    // decision's parentDecisionId must equal the prior decision id retrieved
+    // from the store — never a merely non-null value.
+    const decision = replacement.routeDecision;
+    const routerConfig = replacement.routerConfig ?? null;
+    const seat = decision !== null && typeof decision === "object" && Array.isArray(routerConfig?.seats)
+      ? routerConfig.seats.find((candidate) => candidate?.seatId === decision.selectedSeatId) ?? null
+      : null;
+    const digest = decision !== null && typeof decision === "object" ? sha256Hex(canonicalJsonString(decision)) : null;
+    // R2: deadness is computed from supplied observations (reusing the pure
+    // §7.2 rule), never accepted as a caller-supplied boolean.
+    const dead = isDeadRoute({ seat, healthObservations: replacement.healthObservations ?? {},
+      quotaObservations: replacement.quotaObservations ?? [], now: at });
+    const priorDecisionId = replacement.routerStore !== null && replacement.routerStore !== undefined
+      ? getRouteDecisionIdByDigest(replacement.routerStore, oldClaim.envelope.routeDecisionDigest)
+      : typeof replacement.priorDecisionId === "string" && replacement.priorDecisionId !== ""
+        ? replacement.priorDecisionId
+        : null;
+    const cardEffort = EFFORT_LEVELS.includes(card?.effort) ? card.effort : "default";
+    const seatRoute = seat === null ? null : {
+      seatId: seat.seatId, accountId: seat.accountId ?? null, provider: seat.provider,
+      model: seat.model, containmentTier: seat.containmentTier, effort: cardEffort,
+    };
+    const routeMatchesSeat = seatRoute !== null
+      && requestedRoute.seatId === seatRoute.seatId
+      && requestedRoute.accountId === seatRoute.accountId
+      && requestedRoute.provider === seatRoute.provider
+      && requestedRoute.model === seatRoute.model
+      && requestedRoute.containmentTier === seatRoute.containmentTier
+      && requestedRoute.effort === seatRoute.effort
+      && requestedRoute.role === replacementRole;
+    if (!decision || decision.schema !== "agentic-driver.route-decision.v1"
+      || seat === null || !routeMatchesSeat
+      || typeof priorDecisionId !== "string" || priorDecisionId === "" || decision.parentDecisionId !== priorDecisionId
+      || digest !== requestedRoute.routeDecisionDigest
+      || dead.dead
+      || (requestedRoute.reservationId !== null && replacement.reservationCreated !== true)) {
+      return { ok: false, code: "replacement-route-invalid", reason: "different-seat replacement requires the config seat for the decision's selectedSeatId, an exact seat-derived route, the prior store decision id as parentDecisionId, a live (non-dead) route, a matching digest, and a reservation (fails closed)" };
+    }
+  }
+  const newEnvelope = createEnvelope({ card, policy: policyCheck.policy, now: at, repository: replacementRepository, startingRevision: replacement.startingRevision ?? undefined, route: requestedRoute });
+  const newClaim = {
+    cardId,
+    claimedAt: at,
+    role: replacementRole,
+    envelopeId: newEnvelope.envelopeId,
+    envelope: newEnvelope,
+    parentClaimId: envelopeId,
+    attemptIndex: (oldClaim.attemptIndex ?? 0) + 1,
+  };
+  const keptClaims = activeClaims.filter((claim) => claim.envelopeId !== envelopeId);
+  const nextClaims = [...keptClaims, newClaim];
+  const consumedClaims = [...read.state.consumedClaims, {
+    cardId, envelopeId, consumedAt: at, reason,
+  }];
+  const transaction = {
+    op: "replace-attempt",
+    cardId,
+    envelopeId: newEnvelope.envelopeId,
+    at,
+    phase: "claims-written",
+    oldEnvelopeId: envelopeId,
+    oldReason: reason,
+  };
+  writeClaims(boardPath, nextClaims, { consumedClaims, transaction });
+  const projection = writeProjection(boardPath, validatedBoard.cards, nextClaims);
+  if (!projection.written) {
+    return {
+      ok: false,
+      replaced: true,
+      code: "replace-recoverable",
+      recoverable: true,
+      reason: `projection publication failed: ${projection.error ?? "unknown"} (replacement committed; transaction retained for roll-forward)`,
+      cardId,
+      oldEnvelopeId: envelopeId,
+      claim: newClaim,
+      envelope: newEnvelope,
+      projection,
+    };
+  }
+  finalizeTransactionLocked({ boardPath, claims: nextClaims, projection });
+  return {
+    ok: true,
+    replaced: true,
+    cardId,
+    oldEnvelopeId: envelopeId,
+    oldReason: reason,
+    claim: newClaim,
+    envelope: newEnvelope,
+    projection,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Provider observation (§5 reversibility): everything registers behind the
 // observation that a board file exists. No board file, no behavior change and