@evoclock/pi-agentic-driver 0.9.0 → 0.9.1

package/README.md

@@ -232,9 +232,14 @@ Claims and envelopes are kept in authenticated state beside `TASKS.md`. The
 derived `board.md` view shows active claims but never becomes an authority
 source.
 
+`agentic_kanban_pulse` checks the board for ready work and available capacity.
+A check only reports which work is ready to run. It does not claim cards. Interactive host
+work needs explicit policy and one native confirmation for the batch. Automated
+work requires containment and never falls back to the host.
+
 Coming next:
 
-- an optional watcher that checks for dispatchable work;
+- contained Pulse execution through Testudo;
 - Vogelkop support for the shared card fields; and
 - our own Obsidian plugin for canonical `TASKS.md`.
 

package/extensions/herdr-communication.ts

@@ -1,7 +1,14 @@
 // SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
+import { statSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
 export default async function herdrCommunicationPi(pi) {
-  const module = await import(new URL("../scripts/enforcement/herdr_communication_pi.js", import.meta.url).href);
+  const moduleUrl = new URL("../scripts/enforcement/herdr_communication_pi.js", import.meta.url);
+  // Native ESM retains transitive modules across Pi's Jiti extension reload.
+  // Bind this import to the current file revision so /reload cannot reuse it.
+  moduleUrl.searchParams.set("mtime", String(statSync(fileURLToPath(moduleUrl)).mtimeMs));
+  const module = await import(moduleUrl.href);
   return module.registerHerdrCommunicationInterface(pi);
 }

package/extensions/herdr-lifecycle.ts

@@ -1,7 +1,8 @@
 // SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
-export default async function herdrLifecyclePi(pi) {
-  const module = await import(new URL("../scripts/enforcement/herdr_lifecycle_pi.js", import.meta.url).href);
-  return module.registerHerdrLifecycleInterface(pi);
+import { registerHerdrLifecycleInterface } from "../scripts/enforcement/herdr_lifecycle_pi.js";
+
+export default function herdrLifecyclePi(pi) {
+  return registerHerdrLifecycleInterface(pi);
 }

package/extensions/pulse.ts

@@ -0,0 +1,74 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+// Board Pulse provider extension. Registers the deterministic
+// agentic_kanban_pulse tool and owns the optional fixed-interval timer. The
+// board is resolved per tool call from the calling session's working
+// directory; a workspace with no board file gets a structured
+// board-unavailable result. Board Pulse is capacity scheduling; it is
+// distinct from Herdr worker liveness pulse.
+//
+// No resources start in the extension factory: the timer is created and
+// started only on session_start and cleared idempotently on session_shutdown
+// (PULSE_DESIGN_v3 §8). The worker spawn seam is the existing guarded
+// herdr-lifecycle boundary — native confirmation, trusted repository,
+// installed model roll, fixed argv, shell:false — never raw pane management.
+
+import { executeHerdrSpawnWorker } from "../scripts/enforcement/herdr_lifecycle_pi.js";
+import { resolveBoardPath, registerPulseTools, createPulseTimer, pulseTick, pulseWorkerSpawnSeam } from "../scripts/enforcement/pulse_scheduler_pi.js";
+
+export default function pulsePi(pi) {
+
+  // Guarded worker-creation seam (§2.5): every Pulse spawn goes through
+  // pulseWorkerSpawnSeam, which is placement-aware and fails closed — host
+  // placements route to executeHerdrSpawnWorker (native confirmation,
+  // verification); container/microvm placements are denied before any host
+  // worker is ever started. No other creation path exists.
+  const spawnWorker = pulseWorkerSpawnSeam({ executeHerdrSpawnWorker });
+
+  const result = registerPulseTools(pi, {
+    resolveBoardPath: (ctx) => resolveBoardPath(typeof ctx === "string" ? ctx : ctx?.cwd || process.cwd()),
+    spawnWorker,
+  });
+
+  // Optional timer (§8): created only after session_start, only when the
+  // resolved workspace policy enables Pulse in automated mode with a valid
+  // interval. fillOnStart queues one tick after startup; it is not catch-up.
+  // Ticks never overlap and missed ticks are never replayed. Reload/new/
+  // resume/fork emit session_shutdown first, so exactly one fresh runtime
+  // exists at a time and no in-memory single-flight state is inherited.
+  let timer = null;
+  const clearTimer = () => {
+    if (timer) {
+      timer.clear();
+      timer = null;
+    }
+  };
+  const setupTimer = async (_event, ctx) => {
+    clearTimer();
+    try {
+      const boardPath = resolveBoardPath(ctx?.cwd || process.cwd());
+      if (!boardPath) return;
+      const { readAutomationPolicy, checkAutomationPolicy } = await import(new URL("../scripts/enforcement/task_board_core_pi.js", import.meta.url).href);
+      const policy = readAutomationPolicy(boardPath);
+      const check = checkAutomationPolicy(policy, { boardPath });
+      const pulse = check.ok ? check.policy.pulse : null;
+      if (!pulse || pulse.enabled !== true || pulse.mode !== "automated") return;
+      timer = createPulseTimer({
+        intervalSeconds: pulse.intervalSeconds,
+        fillOnStart: pulse.fillOnStart === true,
+        tick: () => pulseTick({ boardPath, spawnWorker, context: ctx }),
+      });
+      timer.start();
+    } catch {
+      // No-board/no-policy/disabled policy produce zero scheduling effects.
+      clearTimer();
+    }
+  };
+  if (typeof pi?.on === "function") {
+    pi.on("session_start", setupTimer);
+    pi.on("session_shutdown", clearTimer);
+  }
+
+  return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evoclock/pi-agentic-driver",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Guardrail extensions for Agentic Driver: advisory review, bounded Herdr communication, and guarded worker lifecycle.",
   "type": "module",
   "license": "AGPL-3.0-or-later",
@@ -40,6 +40,7 @@
     "extensions/herdr-communication.ts",
     "extensions/herdr-dispatch.ts",
     "extensions/task-board.ts",
+    "extensions/pulse.ts",
     "lib/adapters/diff-scope.mjs",
     "lib/adapters/evidence.mjs",
     "lib/adapters/narrative.mjs",
@@ -66,7 +67,10 @@
     "extensions/aidr.ts",
     "scripts/aidr_writing_review.js",
     "templates/AGENTS.md",
-    "scripts/enforcement/task_board_core_pi.js"
+    "scripts/enforcement/task_board_core_pi.js",
+    "scripts/enforcement/pulse_core_pi.js",
+    "scripts/enforcement/pulse_scheduler_pi.js",
+    "skills/pulse/SKILL.md"
   ],
   "pi": {
     "extensions": [

package/scripts/enforcement/herdr_async_dispatch_pi.js

@@ -16,7 +16,9 @@ import {
   HERDR_COMMUNICATION_ACTIONS,
 } from "./herdr_communication_pi.js";
 import { isNativeTuiContext } from "./native_tui_context.js";
-import { prepareEnvelopeForExecution, validateEnvelopeForExecution, consumeEnvelope } from "./task_board_core_pi.js";
+import { prepareEnvelopeForExecution, validateEnvelopeForExecution, consumeEnvelope, gitHead } from "./task_board_core_pi.js";
+import { sha256Hex } from "./task_board_core_pi.js";
+import { execFileSync } from "node:child_process";
 
 export const WORKER_DISPATCH_TOOL = "agentic_worker_dispatch";
 export const WORKER_DISPATCH_SCHEMA = "agentic-driver.worker-dispatch.v1";
@@ -29,10 +31,17 @@ const MAX_JOURNEY_STEPS = 200;
 const MAX_REPORT_BYTES = 32 * 1024;
 const REGISTRATIONS = new WeakSet();
 
+// The worker-side review-request marker. An implementation journey whose last
+// complete report carries this marker terminates as review_requested (§6.3):
+// it projects review readiness without approval. The board lane transition
+// remains a human/writer decision; Pulse never infers it.
+export const REVIEW_REQUEST_MARKER = "[REVIEW_REQUESTED]";
+
 // Terminal journey states. Only `cancelled` and `failed` are failures; every
 // other terminal state is an observed outcome, and no state is retried.
 export const WORKER_DISPATCH_TERMINAL_STATES = Object.freeze([
   "completed", "exhausted", "role-blocked", "cancelled", "failed", "waiting-approval", "worker-unresponsive",
+  "review_requested",
 ]);
 
 export const WORKER_DISPATCH_PARAMETERS = Object.freeze({
@@ -225,6 +234,46 @@ function journeyReceipt(journey) {
   return body;
 }
 
+// §10.2 progress snapshot: a compact observation attached to the journey
+// step/terminal evidence it belongs to. Not authority, not persisted
+// separately, and not written on every timer tick — only at assignment start
+// and meaningful checkpoints. Repository observations are read-only.
+function progressSnapshot({ taskId = null, envelope = null, repository = null, workerStatus = null, lastReportAt = null }) {
+  const snapshot = {
+    schema: "agentic-driver.progress-snapshot.v1",
+    taskId,
+    at: new Date().toISOString(),
+  };
+  if (envelope) {
+    snapshot.envelopeId = envelope.envelopeId ?? null;
+    snapshot.cardId = envelope.cardId ?? null;
+    snapshot.branch = envelope.branch ?? null;
+  }
+  if (repository) {
+    snapshot.repository = repository;
+    snapshot.head = gitHead(repository);
+    const diff = scopedDiffHash(repository);
+    snapshot.scopedDiffHash = diff.hash;
+    snapshot.changedPaths = diff.paths;
+  }
+  if (workerStatus !== null) snapshot.workerStatus = workerStatus;
+  if (lastReportAt !== null) snapshot.lastCompleteReportAt = lastReportAt;
+  return snapshot;
+}
+
+// Hash of the repository's uncommitted diff (scoped work-in-progress signal).
+// Returns {hash, paths}; a repository where git is unavailable yields nulls.
+function scopedDiffHash(repository) {
+  try {
+    const paths = execFileSync("git", ["status", "--porcelain"], { cwd: repository, encoding: "utf8" })
+      .split("\n").map((line) => line.slice(3).trim()).filter(Boolean);
+    const diff = execFileSync("git", ["diff", "HEAD"], { cwd: repository, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+    return { hash: sha256Hex(diff), paths: paths.slice(0, 64) };
+  } catch {
+    return { hash: null, paths: [] };
+  }
+}
+
 // One continuous journey. Each step: pulse (liveness + eligibility), observe
 // the next dispatchable item, one prompt exchange (no retry on any failure),
 // read the marked report, collate. Bounded by maxSteps, never wall-clock.
@@ -256,7 +305,7 @@ export async function runWorkerJourney(params, context, options = {}, signal) {
   const finish = async (requestedStatus) => {
     let status = requestedStatus;
     if (board && boardAttemptStarted && !envelopeConsumed) {
-      const reason = ["completed", "exhausted", "cancelled", "failed", "waiting-approval", "role-blocked", "worker-unresponsive"].includes(status)
+      const reason = ["completed", "exhausted", "cancelled", "failed", "waiting-approval", "role-blocked", "worker-unresponsive", "review_requested"].includes(status)
         ? status
         : status.startsWith("worker-unresponsive") ? "worker-unresponsive" : "failed";
       let consumed;
@@ -277,7 +326,7 @@ export async function runWorkerJourney(params, context, options = {}, signal) {
     journey.status = status;
     return {
       schema: WORKER_DISPATCH_SCHEMA,
-      ok: status === "completed" || status === "exhausted" || status === "waiting-approval",
+      ok: status === "completed" || status === "exhausted" || status === "waiting-approval" || status === "review_requested",
       action: "dispatch",
       mode,
       autonomy,
@@ -590,8 +639,21 @@ export async function runWorkerJourney(params, context, options = {}, signal) {
       status: "done",
       workerStatus: exchange.agentStatus,
       report: exchange.report,
+      // §10.2 progress snapshot at the meaningful checkpoint (step completion).
+      progress: progressSnapshot({
+        taskId: task.id,
+        envelope: board?.envelope ?? null,
+        repository: options.repository ?? null,
+        workerStatus: exchange.agentStatus ?? null,
+        lastReportAt: new Date().toISOString(),
+      }),
     });
     dispatched.add(task.id);
+    // §6.3 review routing: the last complete report requests review.
+    if (typeof exchange.report === "string" && exchange.report.includes(REVIEW_REQUEST_MARKER)) {
+      journey.status = "review_requested";
+      return finish("review_requested");
+    }
   }
 
   journey.status = "completed";

package/scripts/enforcement/herdr_communication_pi.js

@@ -42,6 +42,10 @@ const MAX_IDENTITY_FIELD_BYTES = 4 * 1024;
 const MAX_MARKER_HORIZONTAL_WHITESPACE = 128;
 const MAX_PROMPT_CONTRACT_ECHO_BYTES = 4 * 1024;
 const MAX_READ_LINES = 400;
+// A valid 32 KiB report can contain more than 400 short lines. A second,
+// finite read may cover one line per byte plus framing without relaxing the
+// existing 128 KiB process-output ceiling.
+const MAX_REPORT_READ_LINES = MAX_REPORT_BYTES + 16;
 const MAX_WAIT_TIMEOUT_MS = 300_000;
 const MAX_IMPLEMENTER_PROMPT_TIMEOUT_MS = 120_000;
 const COMMAND_TIMEOUT_MS = 15_000;
@@ -397,6 +401,14 @@ function validateParams(params) {
     if (!isReviewerRole(params.role) && params.timeoutMs > MAX_IMPLEMENTER_PROMPT_TIMEOUT_MS) {
       throw communicationError("implementer_prompt_timeout_exceeded", "worker prompts are limited to one two-minute atomic step", "denied");
     }
+    // Prompt freshness: each explicit prompt carries its own task scope and
+    // contract framing built from THAT call's prompt text. A stale or reused
+    // prompt text never binds a later exchange — provenance requires the
+    // echoed contract to match the current prompt exactly (provenancedReport
+    // Segment), so a prior exchange's scope cannot silently cover this one.
+    if (params.prompt.includes(REPORT_CONTRACT_LINE)) {
+      throw communicationError("prompt_preformatted", "the prompt must carry task scope only; the report contract is added by the transport (fails closed)", "denied");
+    }
   }
   if (action === "wait") {
     if (!Number.isInteger(params.timeoutMs) || params.timeoutMs < 1 || params.timeoutMs > MAX_WAIT_TIMEOUT_MS) {
@@ -458,7 +470,7 @@ function fixedArgv(action, params) {
     case "read":
       return [
         "agent", "read", params.role,
-        "--source", "recent-unwrapped", "--lines", String(MAX_READ_LINES),
+        "--source", "recent-unwrapped", "--lines", String(params.readLines ?? MAX_READ_LINES),
         "--format", "text",
       ];
     default:
@@ -468,11 +480,11 @@ function fixedArgv(action, params) {
 
 function promptWithReportRequirement(role, prompt) {
   const marker = reportMarkersForRole(role);
+  // Communication adds transport framing only. Task scope and role behaviour
+  // belong to the caller's current prompt; injecting either here would make a
+  // task-scoped instruction silently bind every later exchange for that role.
   const requirement = [
     "",
-    ...(isReviewerRole(role) ? ["Remain strictly read-only; do not modify files, state, or Git."] : [
-      "MANDATORY ATOMIC EXECUTION CONTRACT: execute one acceptance-checked step only; do not continue to a second file, test group, or follow-up; stop and report incomplete work as CHANGES_REQUIRED before the two-minute boundary.",
-    ]),
     REPORT_CONTRACT_LINE,
     marker.open,
     marker.close,
@@ -1223,11 +1235,23 @@ export async function executeHerdrCommunication(params, context, options = {}, s
       if (waitedStatus === "blocked") {
         return errorResult(operation, communicationError("role_blocked", "the prompted role reached blocked state", "blocked"));
       }
-      const rawReport = await invokeHerdr("read", { action: "read", role }, context, options, signal);
-      const post = readText(rawReport);
+      let post = readText(await invokeHerdr("read", { action: "read", role }, context, options, signal));
       const sentPrompt = promptWithReportRequirement(role, request.prompt);
-      const boundary = provenancedReportSegment(pre, post, sentPrompt, role);
-      const report = extractReportFromSegment(post, role, boundary.end);
+      let report;
+      let reportReadCount = 1;
+      try {
+        const boundary = provenancedReportSegment(pre, post, sentPrompt, role);
+        report = extractReportFromSegment(post, role, boundary.end);
+      } catch (error) {
+        if (!(error instanceof HerdrCommunicationError)
+            || !["report_scope_unavailable", "report_reversed"].includes(error.code)) throw error;
+        // The ordinary terminal tail can begin inside a valid current report.
+        // Expand once; never resend the prompt and never retry indefinitely.
+        post = readText(await invokeHerdr("read", { action: "read", role, readLines: MAX_REPORT_READ_LINES }, context, options, signal));
+        reportReadCount = 2;
+        const boundary = provenancedReportSegment(pre, post, sentPrompt, role);
+        report = extractReportFromSegment(post, role, boundary.end);
+      }
       return successResult(operation, {
         status: "complete",
         role,
@@ -1237,7 +1261,7 @@ export async function executeHerdrCommunication(params, context, options = {}, s
         promptSent: true,
         invocationCount: 1,
         waitCount: 1,
-        readCount: 1,
+        readCount: reportReadCount,
         report,
         reportMarkers: reportMarkersForRole(role),
       });
@@ -1250,8 +1274,15 @@ export async function executeHerdrCommunication(params, context, options = {}, s
       }
       return successResult(operation, { role, status, agentStatus: status, repository });
     }
-    const raw = await invokeHerdr(operation, request, context, options, signal);
-    const report = extractLatestHerdrReport(readText(raw), role);
+    let raw = await invokeHerdr(operation, request, context, options, signal);
+    let report;
+    try {
+      report = extractLatestHerdrReport(readText(raw), role);
+    } catch (error) {
+      if (!(error instanceof HerdrCommunicationError) || error.code !== "report_reversed") throw error;
+      raw = await invokeHerdr("read", { action: "read", role, readLines: MAX_REPORT_READ_LINES }, context, options, signal);
+      report = extractLatestHerdrReport(readText(raw), role);
+    }
     return successResult(operation, {
       role,
       report,

package/scripts/enforcement/pulse_core_pi.js

@@ -0,0 +1,268 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+// Pulse core (PULSE_DESIGN_v3 §2.2, §4, §5): a side-effect-free evaluation of
+// one selected board. It consumes validated board cards, active claim
+// observations, a validated automation policy (with its optional closed
+// `pulse` object), and model-availability observations supplied by trusted
+// adapters. It returns one Pulse result per card, composed free capacity per
+// role/model route, and a deterministic scheduling proposal.
+//
+// It never reads files, claims cards, spawns workers, starts timers, or
+// mutates policy. Eligibility grants no authority: the existing dispatcher
+// owns atomic claim and envelope creation.
+
+import {
+  canonicalJsonString, sha256Hex, isDispatchable,
+} from "./task_board_core_pi.js";
+export { canonicalJsonString, sha256Hex };
+
+export const PULSE_SCAN_SCHEMA = "agentic-driver.board-pulse.v1";
+
+// The five closed Pulse results (§5). Exactly one per evaluated card.
+export const PULSE_RESULTS = Object.freeze([
+  "READY_FOR_NEXT", "BLOCKED", "STALE", "DENIED", "REVIEW_REQUIRED",
+]);
+
+const PRIORITY_ORDER = Object.freeze({ P0: 0, P1: 1, P2: 2, P3: 3 });
+const AVAILABILITY = Object.freeze([
+  "available", "full", "unauthenticated", "unavailable", "unknown",
+]);
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+// Close the availability observation for one model. Only declared
+// preferred/fallback route models are considered; anything else is unknown
+// and unavailable for routing (§3.1: fails closed).
+export function modelAvailability({ model, observations = null, declaredModels = null }) {
+  if (declaredModels !== null && !declaredModels.includes(model)) return "unknown";
+  const observed = isPlainObject(observations) ? observations[model] : undefined;
+  if (observed === undefined) return "unknown";
+  if (!isPlainObject(observed)) return "unknown";
+  const status = observed.status;
+  if (status === "available" || status === "full"
+    || status === "unauthenticated" || status === "unavailable") return status;
+  return "unknown";
+}
+
+// True only when the model can take new work this tick. "full" means the
+// provider reported a live limit reached; the route is full, not unusable.
+export function modelUsable(availability) {
+  return availability === "available" || availability === "full";
+}
+
+// Composed free capacity for one role/model route (§4.2):
+//   free = min(configured route ceiling, role ceiling, policy-wide ceiling)
+//          - unique active work for role/model
+// Active work is deduplicated by attempt identity across claims and verified
+// sessions; a session bound to an active claim counts once.
+export function freeCapacity({ role, model, pulsePolicy, activeClaims = [], activeSessions = [], providerLimit = null }) {
+  const routing = pulsePolicy?.routing ?? {};
+  const roleEntry = routing[role];
+  const routes = [...(roleEntry?.preferred ?? []), ...(roleEntry?.fallback ?? [])];
+  const route = routes.find((entry) => entry?.model === model) ?? null;
+  if (!route) return { free: 0, configured: 0, reason: `model "${model}" is not a declared route for role "${role}"` };
+
+  // Deduplicate active work by attempt identity (envelope id when present,
+  // else session id). A session matching an active claim counts once.
+  const claimIdentities = new Set(
+    (activeClaims ?? [])
+      .filter((claim) => claim?.role === role && claimModel(claim) === model)
+      .map((claim) => claim?.envelopeId ?? claim?.envelope?.envelopeId ?? `claim:${claim?.cardId}`)
+      .filter((id) => typeof id === "string"),
+  );
+  const boundSessionIds = new Set(
+    (activeClaims ?? []).map((claim) => claim?.sessionId).filter((id) => typeof id === "string"),
+  );
+  const orphanSessions = (activeSessions ?? []).filter((session) => {
+    if (session?.role !== role || session?.model !== model) return false;
+    if (typeof session?.sessionId !== "string") return false;
+    if (boundSessionIds.has(session.sessionId)) return false;
+    // An observed orphan session counts separately only after reconciliation
+    // cannot bind it to an active attempt; ambiguity consumes capacity (§4.2).
+    return session.reconciled === true || session.reconciled === undefined;
+  });
+  const active = claimIdentities.size + orphanSessions.length;
+
+  const routeCeiling = route.maxConcurrent;
+  const roleCeiling = roleEntry?.maxConcurrent ?? routeCeiling;
+  const policyCeiling = Number.isInteger(pulsePolicy?.globalMaxConcurrent)
+    ? pulsePolicy.globalMaxConcurrent
+    : null;
+  const configured = Math.min(routeCeiling, roleCeiling, policyCeiling ?? routeCeiling);
+  const providerCap = Number.isInteger(providerLimit) && providerLimit >= 0 ? providerLimit : null;
+  const ceiling = providerCap === null ? configured : Math.min(configured, providerCap);
+  return { free: Math.max(0, ceiling - active), configured, reason: null };
+}
+
+// The model a claim is running under. Claims carry the exact model on their
+// envelope when Pulse created them; legacy claims without one count against
+// no specific model route — we attribute them to nothing rather than guess
+// (no silent substitution).
+function claimModel(claim) {
+  return typeof claim?.envelope?.model === "string" ? claim.envelope.model : null;
+}
+
+// Ordered candidate routes for a role: preferred first, then fallback in
+// declaration order (§3.1). Fallback is considered only when preferred
+// routes are unavailable or full.
+export function routesForRole(role, pulsePolicy) {
+  const entry = pulsePolicy?.routing?.[role];
+  if (!entry) return [];
+  return [
+    ...entry.preferred.map((route) => ({ ...route, tier: "preferred" })),
+    ...entry.fallback.map((route) => ({ ...route, tier: "fallback" })),
+  ];
+}
+
+// Evaluate one card and return exactly one Pulse result plus a reason (§5).
+// Inputs are already trusted: the card comes from parseBoard/validateBoard,
+// the policy from checkAutomationPolicy. Capacity never changes a card
+// result — it only changes `capacity` and `proposedDispatches`.
+export function evaluateCard({ card, boardIndex, activeClaims = [], pulsePolicy = null, modelObservations = null, declaredModels = null, acceptedRepositories = null }) {
+  // Provenance verification is the caller adapter's responsibility: it
+  // supplies cards with `statePath` only when the trusted writer state is
+  // available. The core stays side-effect-free and file-free.
+  const failed = isDispatchable(card, boardIndex).failedConditions ?? [];
+  const claimed = (activeClaims ?? []).some((claim) => claim?.cardId === card.cardId);
+  if (claimed) failed.push("card is already claimed by an active authenticated attempt");
+  if (failed.length > 0) {
+    const text = failed.join("; ");
+    if (claimed) {
+      return { result: "BLOCKED", reason: "card is already claimed by an active authenticated attempt" };
+    }
+    if (/hash|provenance|authority|tampered/.test(text)) {
+      return { result: "STALE", reason: text };
+    }
+    if (/expired|revoked|prohibited|not declared|placement|risk/i.test(text)) {
+      return { result: "DENIED", reason: text };
+    }
+    if (/dependenc|lane|blocked|cancelled|flag/i.test(text)) {
+      return { result: "BLOCKED", reason: text };
+    }
+    return { result: "REVIEW_REQUIRED", reason: text };
+  }
+
+  // Policy gate (§5 DENIED): no policy, expired/revoked policy, or a role the
+  // policy does not declare and route.
+  if (!isPlainObject(pulsePolicy) || pulsePolicy.enabled !== true) {
+    return { result: "REVIEW_REQUIRED", reason: "Pulse is not enabled for this board" };
+  }
+  const role = typeof card.role === "string" && card.role !== "" ? card.role : "implementer";
+  const routes = routesForRole(role, pulsePolicy);
+  if (routes.length === 0) {
+    return { result: "DENIED", reason: `no Pulse route is declared for role "${role}" (fails closed)` };
+  }
+  // Repository gate (§9): the card must identify a repository the policy
+  // accepts. A card naming exactly one repository is unambiguous; otherwise
+  // a single-repository policy supplies the default. Ambiguity fails closed.
+  if (Array.isArray(acceptedRepositories) && acceptedRepositories.length > 0) {
+    const named = Array.isArray(card.repositories) ? card.repositories.filter((r) => typeof r === "string" && r !== "") : [];
+    const repository = named.length === 1 ? named[0]
+      : named.length === 0 && acceptedRepositories.length === 1 ? acceptedRepositories[0]
+      : null;
+    if (repository === null || !acceptedRepositories.includes(repository)) {
+      return { result: "DENIED", reason: "card repository is ambiguous or not in the policy acceptedRepositories (fails closed)" };
+    }
+  }
+  // Route availability: at least one declared route must be usable. Without
+  // an authorised fallback this is REVIEW_REQUIRED (§5), never a substitution.
+  const usable = routes.filter((route) => modelUsable(modelAvailability({
+    model: route.model, observations: modelObservations, declaredModels,
+  })));
+  if (usable.length === 0) {
+    return { result: "REVIEW_REQUIRED", reason: `no usable declared route for role "${role}" (preferred unavailable without authorised fallback)` };
+  }
+  return { result: "READY_FOR_NEXT", reason: null, role, routes: usable };
+}
+
+// One full board scan (§4.3, §5). Deterministic: cards in board P0→P3 then
+// card-ID order; capacity in role-then-route declaration order; proposals in
+// selection order. No cross-board priority comparison happens here.
+export function scanBoard({ cards, boardPath, boardRevision = null, policyRevision = null, activeClaims = [], pulsePolicy = null, modelObservations = null, declaredModels = null, observedAt = null, placement = null }) {
+  const index = new Map(cards.map((card) => [card.cardId, card]));
+  const ordered = [...cards].sort((a, b) =>
+    (PRIORITY_ORDER[a.priority] ?? 99) - (PRIORITY_ORDER[b.priority] ?? 99)
+    || String(a.cardId).localeCompare(String(b.cardId)));
+
+  const cardResults = [];
+  const capacity = [];
+  const proposedDispatches = [];
+  const policyWideRemaining = Number.isInteger(pulsePolicy?.globalMaxConcurrent)
+    ? pulsePolicy.globalMaxConcurrent - (activeClaims ?? []).length
+    : null;
+
+  const roleOrder = pulsePolicy?.routing ? Object.keys(pulsePolicy.routing) : [];
+  for (const role of roleOrder) {
+    for (const route of routesForRole(role, pulsePolicy)) {
+      const availability = modelAvailability({ model: route.model, observations: modelObservations, declaredModels });
+      const free = freeCapacity({ role, model: route.model, pulsePolicy, activeClaims });
+      capacity.push({
+        role, model: route.model, configured: free.configured,
+        activeClaims: (activeClaims ?? []).filter((claim) => claim?.role === role && claimModel(claim) === route.model).length,
+        startingOrRunning: 0,
+        providerLimit: null,
+        free: availability === "available" || availability === "full" ? free.free : 0,
+        availability,
+      });
+    }
+  }
+
+  const remainingByRoute = new Map(capacity.map((entry) => [`${entry.role}\u0000${entry.model}`, entry.free]));
+  let globalRemaining = policyWideRemaining;
+  // Placement for proposals is supplied by the scheduler adapter (the pulse
+  // object does not carry it; the policy's placement field governs). In
+  // automated mode containment is the default when available (§3.2); the core
+  // never decides containment availability.
+  const scanPlacement = placement;
+
+  for (const card of ordered) {
+    const evaluation = evaluateCard({
+      card, boardIndex: index, boardPath, activeClaims, pulsePolicy,
+      modelObservations, declaredModels,
+      acceptedRepositories: pulsePolicy?.acceptedRepositories ?? null,
+    });
+    const entry = { title: card.title, role: evaluation.role ?? (typeof card.role === "string" && card.role !== "" ? card.role : "implementer"), result: evaluation.result, reason: evaluation.reason };
+    cardResults.push(entry);
+    if (evaluation.result !== "READY_FOR_NEXT") continue;
+
+    // Propose at most free capacity and policy-wide remaining capacity (§4.3
+    // step 5): preferred routes first, then declared fallback, in order.
+    let proposed = false;
+    for (const route of evaluation.routes) {
+      const key = `${entry.role}\u0000${route.model}`;
+      const remaining = remainingByRoute.get(key) ?? 0;
+      if (remaining <= 0) continue;
+      if (globalRemaining !== null && globalRemaining <= 0) break;
+      remainingByRoute.set(key, remaining - 1);
+      if (globalRemaining !== null) globalRemaining -= 1;
+      proposedDispatches.push({ title: card.title, role: entry.role, model: route.model, placement: scanPlacement });
+      proposed = true;
+      break;
+    }
+    if (!proposed && evaluation.routes.length > 0) {
+      // Ready but no free slot: the card result stays READY_FOR_NEXT (§5);
+      // capacity alone gates the proposal.
+      entry.reason = "ready; no free capacity on any declared route this tick";
+    }
+  }
+
+  const scan = {
+    schema: PULSE_SCAN_SCHEMA,
+    board: boardPath,
+    boardRevision,
+    policyRevision,
+    observedAt: observedAt ?? null,
+    cards: cardResults,
+    capacity,
+    proposedDispatches,
+    authorityCreated: false,
+  };
+  // Internal diagnostic hash only (§5): canonical input is the closed public
+  // result, serialized by the existing canonical JSON helper and SHA-256
+  // hashed. It grants no authority and is not part of the public shape.
+  const diagnosticHash = sha256Hex(canonicalJsonString(scan));
+  return { scan, diagnosticHash };
+}