@evoclock/pi-agentic-driver 0.9.0 → 0.9.2

package/scripts/enforcement/guest_containment_taxonomy.v1.json

@@ -10,7 +10,7 @@
     {"id":"GC-FSW-003","class":"GC-FSW","severity":"ELEVATED","action":"deny","match":"file-growth-anomaly: unexpected growth in cache/package directories (~/.npm, ~/.cache/pip, /var/cache/*) beyond the size-delta threshold","evidence":"METR evaluation logs: bulk cache staging of payloads","since":"v1","disposition":"detector:fs-sweep size-delta sampling (gc_cache_growth_sample; aggregate ELEVATED, GC_CACHE_GROWTH_KIB per sweep)"},
     {"id":"GC-SHR-001","class":"GC-SHR","severity":"HIGH","action":"deny","match":"shared-cache-write: writes to paths shared with other agents or the coordinator; with host-share absent any such attempt is a deny","evidence":"receipt proves host-share=absent; writes would indicate boundary violation","since":"v1","disposition":"detector:fs-path; share paths auto-arm via gc_share_mounted (/proc/mounts); shared-cache roots classify as SHR when unarmed"},
     {"id":"GC-SHR-002","class":"GC-SHR","severity":"HIGH","action":"deny","match":"cross-agent-channel: creation of or writes to inter-agent coordination paths (maildirs, task-queue files, agent state files)","evidence":"HF incident multi-agent escalation; METR coordination/sabotage threat model","since":"v1","disposition":"detector:fs-path+shim-argv heuristics (Maildir, task-queue, agent-channel, coordination paths)"},
-    {"id":"GC-NET-001","class":"GC-NET","severity":"HIGH","action":"deny","match":"socket-open: any entry in /proc/net/tcp, /proc/net/tcp6, /proc/net/udp at any sweep","evidence":"fixture boots with no network device; any socket is exfiltration-capable","since":"v1","disposition":"detector:net-proc-sweep"},
+    {"id":"GC-NET-001","class":"GC-NET","severity":"HIGH","action":"deny","match":"socket-open: any entry in /proc/net/tcp, /proc/net/tcp6, /proc/net/udp not present in the pre-arming socket baseline, at any sweep","evidence":"fixture boots with no network device; any socket is exfiltration-capable","since":"v1","disposition":"detector:net-proc-sweep-baselined"},
     {"id":"GC-NET-002","class":"GC-NET","severity":"HIGH","action":"deny","match":"network-tool-invocation: shim-detects wget, curl, nc, ssh, telnet, ping regardless of arguments","evidence":"METR self-replication exfiltration patterns; HF incident remote control","since":"v1","disposition":"detector:shim-argv"},
     {"id":"GC-CRED-001","class":"GC-CRED","severity":"CRITICAL","action":"deny","match":"credential-path-read: opens of ~/.ssh/, ~/.aws/, ~/.netrc, ~/.git-credentials, token files","evidence":"credential theft is step one in every reported agent-escape chain","since":"v1","disposition":"detector:shim-argv"},
     {"id":"GC-CRED-002","class":"GC-CRED","severity":"CRITICAL","action":"deny","match":"env-secret-probing: attempts to dump or scan the environment for secret-shaped keys","evidence":"METR evaluation logs; HF incident postmortem credential harvest attempts","since":"v1","disposition":"detector:shim-argv"},

package/scripts/enforcement/herdr_async_dispatch_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
 
 // Async continuous worker dispatch and pulse. One bounded step on top of the
 // shipped herdr-communication interface: a worker progresses through an
@@ -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

@@ -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
 
 import {
   accessSync,
@@ -14,7 +14,7 @@ import { resolve } from "node:path";
 
 export const HERDR_COMMUNICATION_TOOL = "agentic_herdr_communication";
 export const HERDR_COMMUNICATION_SCHEMA = "agentic-driver.herdr-communication.v1";
-export const HERDR_VERSION = "0.8.2";
+export const HERDR_VERSION = "0.9.1";
 // One versioned policy: every schema-valid dynamic role is eligible except the
 // coordinator class (`coordinator` and `coordinator-*`).
 export const HERDR_ROLE_POLICY = Object.freeze({
@@ -25,12 +25,17 @@ export const HERDR_ROLE_PATTERN = "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$";
 const HERDR_ROLE_REGEXP = new RegExp(HERDR_ROLE_PATTERN);
 export const HERDR_COMMUNICATION_ACTIONS = Object.freeze(["list", "get", "prompt", "wait", "read"]);
 
-// The Homebrew link is the configured driver-node path observed for Herdr 0.8.2.
-// It is deliberately not resolved through PATH or HERDR_BIN_PATH.  A package
-// upgrade changes the realpath and therefore fails closed until this pin is
-// reviewed.  Linux callers have no configured production path in this package.
+// The Homebrew link is the configured driver-node path. It is deliberately
+// not resolved through PATH or HERDR_BIN_PATH. The realpath is validated as
+// <Cellar root>/herdr/<any-version>/bin/herdr so a Homebrew upgrade does not
+// break the trust seam: the executable must be the Homebrew-managed herdr
+// binary (same path family), executable, and a regular file, but the version
+// number is not pinned because pinning would break every package upgrade.
+// The semantic version constant above records the version this integration was
+// last validated against and is advisory only. Linux callers have no
+// configured production path in this package.
 export const TRUSTED_HERDR_EXECUTABLE = "/opt/homebrew/bin/herdr";
-const TRUSTED_HERDR_REALPATH_FRAGMENT = `/Cellar/herdr/${HERDR_VERSION}/bin/herdr`;
+const TRUSTED_HERDR_REALPATH_PATTERN = /\/Cellar\/herdr\/[0-9]+\.[0-9]+\.[0-9]+\/bin\/herdr$/;
 const WORKER_REPOSITORY_REGISTRY = "config/herdr-worker-repositories.v1.json";
 const WORKER_REPOSITORY_SCHEMA = "agentic-driver.herdr-worker-repositories.v1";
 const WORKER_REPOSITORY_FIELDS = new Set(["schema", "repositories"]);
@@ -42,6 +47,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 +406,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) {
@@ -415,7 +432,7 @@ function productionExecutable() {
     real = realpathSync(TRUSTED_HERDR_EXECUTABLE);
     const stat = statSync(real);
     accessSync(real, fsConstants.X_OK);
-    if (!stat.isFile() || !real.endsWith(TRUSTED_HERDR_REALPATH_FRAGMENT)) throw new Error("version mismatch");
+    if (!stat.isFile() || !TRUSTED_HERDR_REALPATH_PATTERN.test(real)) throw new Error("trust mismatch");
   } catch {
     throw communicationError("trusted_executable_unavailable", `the configured Herdr ${HERDR_VERSION} executable was not observed`);
   }
@@ -458,7 +475,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 +485,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 +1240,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 +1266,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 +1279,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/herdr_lifecycle_pi.js

@@ -1,8 +1,8 @@
 // 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
 
 // Guarded spawn_worker composite capability (Tranche 07). One tool, one closed
-// request, one documented Herdr 0.8.2 layout/start sequence, bounded read-back,
+// request, one documented Herdr layout/start sequence, bounded read-back,
 // and a bounded receipt. This is deliberately NOT a general Herdr management
 // surface: no raw management verbs, no terminal remote control, no model
 // allowlist constant. Pane placement uses pane split directly; tab placement
@@ -767,7 +767,7 @@ export async function executeHerdrSpawnWorker(params, context, options = {}, sig
     }
     canonicalRoot = reconfirmedRoot;
 
-    // Herdr 0.8.2 owns new-shell readiness. Follow its documented topology:
+    // Herdr owns new-shell readiness. Follow its documented topology:
     // split directly for pane placement, or create a tab for tab placement.
     let coordinator = null;
     if (placement !== "tab") {

package/scripts/enforcement/linux_microvm_cutover_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
 
 import { createHash, randomBytes } from "node:crypto";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";

package/scripts/enforcement/native_tui_context.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
 
 // Public native-TUI context predicate shared by the shipped enforcement
 // interfaces. Restriction-gated actions stay fail-closed: anything that is

package/scripts/enforcement/pulse_core_pi.js

@@ -0,0 +1,292 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// 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 —
+// UNLESS an explicit provider-limit observation says otherwise (router design
+// §9 item 1): a bare "full" with no provider limit is treated as unusable
+// because capacity cannot be verified, and capacity races must fail closed.
+export function modelUsable(availability, { providerLimit = null, providerActive = null } = {}) {
+  if (availability === "available") return true;
+  if (availability === "full") {
+    return Number.isInteger(providerLimit) && Number.isInteger(providerActive)
+      && providerLimit > 0 && providerActive < providerLimit;
+  }
+  return false;
+}
+
+// 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;
+  // §9 item 2: the policy-wide ceiling is the automation policy's own
+  // maxConcurrent (the actual global ceiling). The legacy pulsePolicy
+  // .globalMaxConcurrent lookup is removed — that field never existed in the
+  // closed pulse shape.
+  const policyCeiling = Number.isInteger(pulsePolicy?.maxConcurrent)
+    ? pulsePolicy.maxConcurrent
+    : 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, providerLimit = null, providerActive = 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.
+  // "full" counts as usable only with an explicit provider limit (§9 item 1).
+  const usable = routes.filter((route) => modelUsable(modelAvailability({
+    model: route.model, observations: modelObservations, declaredModels,
+  }), {
+    providerLimit,
+    providerActive: isPlainObject(providerActive) ? providerActive[route.model] : providerActive,
+  }));
+  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, activeSessions = [], providerLimit = 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 = [];
+  // §9 item 2: the policy-wide ceiling is the automation policy's
+  // maxConcurrent. §9 item 3: the production path supplies activeSessions
+  // and providerLimit; the scan composes them into capacity.
+  const policyWideRemaining = Number.isInteger(pulsePolicy?.maxConcurrent)
+    ? pulsePolicy.maxConcurrent - (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, activeSessions, providerLimit });
+      capacity.push({
+        role, model: route.model, configured: free.configured,
+        activeClaims: (activeClaims ?? []).filter((claim) => claim?.role === role && claimModel(claim) === route.model).length,
+        startingOrRunning: 0,
+        providerLimit: Number.isInteger(providerLimit) && providerLimit >= 0 ? providerLimit : null,
+        free: modelUsable(availability, { providerLimit, providerActive: (activeSessions ?? []).filter((s) => s?.model === route.model).length }) ? 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,
+      providerLimit,
+      providerActive: Object.fromEntries(routesForRole(
+        typeof card.role === "string" && card.role !== "" ? card.role : "implementer",
+        pulsePolicy,
+      ).map((route) => [route.model, (activeSessions ?? []).filter((session) => session?.model === route.model).length])),
+    });
+    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 };
+}