@evoclock/pi-agentic-driver 0.9.1 → 0.9.3

package/janus/tests/single_flight.test.ts

@@ -0,0 +1,84 @@
+// SPDX-FileCopyrightText: 2026 Julen Gamboa <j.a.r.gamboa@gmail.com>
+// SPDX-License-Identifier: AGPL-3.0-only
+
+// Unit tests: single-flight per evalInputDigest (M9) and the global
+// concurrency cap with busy rejection.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { SingleFlight } from "../janus/single_flight.js";
+import { JanusError } from "../janus/errors.js";
+
+test("identical digests coalesce onto one task", async () => {
+  const sf = new SingleFlight(4);
+  let runs = 0;
+  const task = () =>
+    sf.run("digest-a", async () => {
+      runs += 1;
+      await new Promise((r) => setTimeout(r, 50));
+      return "result";
+    });
+
+  const [a, b, c] = await Promise.all([task(), task(), task()]);
+  assert.equal(runs, 1);
+  assert.equal(a, "result");
+  assert.equal(b, "result");
+  assert.equal(c, "result");
+});
+
+test("distinct digests run as separate tasks", async () => {
+  const sf = new SingleFlight(4);
+  let runs = 0;
+  const make = (digest: string) =>
+    sf.run(digest, async () => {
+      runs += 1;
+      return digest;
+    });
+  await Promise.all([make("d1"), make("d2"), make("d3")]);
+  assert.equal(runs, 3);
+});
+
+test("global cap rejects distinct digests with busy", async () => {
+  const sf = new SingleFlight(2);
+  const release: (() => void)[] = [];
+  const make = (digest: string) =>
+    sf.run(digest, () => new Promise<string>((resolvePromise) => release.push(() => resolvePromise(digest))));
+
+  void make("d1");
+  void make("d2");
+  assert.throws(() => make("d3"), (error: unknown) => {
+    return error instanceof JanusError && error.code === "busy";
+  });
+  for (const r of release) r();
+});
+
+test("digests are released after completion", async () => {
+  const sf = new SingleFlight(1);
+  await sf.run("d1", async () => "x");
+  // Cap of 1 must allow the next request after the first completes.
+  assert.equal(await sf.run("d2", async () => "y"), "y");
+  assert.equal(await sf.run("d1", async () => "z"), "z");
+});
+
+test("failed flights release their digest", async () => {
+  const sf = new SingleFlight(1);
+  await assert.rejects(
+    sf.run("d1", async () => {
+      throw new Error("boom");
+    }),
+    /boom/,
+  );
+  assert.equal(await sf.run("d1", async () => "recovered"), "recovered");
+});
+
+test("coalesced waiters share a failed flight's rejection", async () => {
+  const sf = new SingleFlight(4);
+  const task = () =>
+    sf.run("digest-fail", async () => {
+      await new Promise((r) => setTimeout(r, 20));
+      throw new Error("gateway down");
+    });
+  const results = await Promise.allSettled([task(), task()]);
+  assert.equal(results[0]?.status, "rejected");
+  assert.equal(results[1]?.status, "rejected");
+});

package/janus/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2023"],
+    "types": ["node"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitOverride": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["janus/**/*.ts", "tests/**/*.ts"]
+}

package/janus/user.janus.plist

@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+  janus launchd template — a STARTING POINT, not a finished service file.
+  Everything marked ADJUST below is user-specific by design; the template
+  ships with placeholders because the label, paths, and log locations belong
+  to the user's machine, not to this repository.
+
+  Install:
+    1. Copy the template somewhere out of the repo:
+         cp janus/user.janus.plist ~/Library/LaunchAgents/user.janus.plist
+    2. ADJUST the values marked below (Label, WorkingDirectory, log paths).
+    3. Load it:
+         launchctl load ~/Library/LaunchAgents/user.janus.plist
+
+  The service binds 127.0.0.1 only and reads the gateway key from the
+  Keychain at runtime; no environment variables are required.
+-->
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <!-- ADJUST: any label you like; the file name should match it. -->
+    <string>user.janus</string>
+    <key>ProgramArguments</key>
+    <array>
+        <!-- ADJUST if your tooling lives elsewhere (e.g. /usr/local/bin/npx). -->
+        <string>/opt/homebrew/bin/npx</string>
+        <string>tsx</string>
+        <string>janus/server.ts</string>
+    </array>
+    <key>WorkingDirectory</key>
+    <!-- ADJUST: the janus/ directory of your checkout. -->
+    <string>/path/to/pi-agentic-driver/janus</string>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+    <key>StandardOutPath</key>
+    <!-- ADJUST: where stdout goes. -->
+    <string>/tmp/janus.stdout.log</string>
+    <key>StandardErrorPath</key>
+    <!-- ADJUST: where stderr goes. -->
+    <string>/tmp/janus.stderr.log</string>
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <!-- ADJUST if your npx lives on a different PATH. -->
+        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
+    </dict>
+</dict>
+</plist>

package/lib/adapters/diff-scope.mjs

@@ -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
 
 // diff-scope adapter — changed-range extraction for code-phage.
 //

package/lib/adapters/evidence.mjs

@@ -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
 
 // evidence adapter — content-bound source anchors for code-phage.
 //

package/lib/adapters/narrative.mjs

@@ -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
 
 // narrative adapter — structured, concern-grouped review narrative.
 //

package/lib/adapters/review-feedback.mjs

@@ -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
 
 // review-feedback adapter — two-intent review items for code-phage.
 //

package/lib/adapters/visualization.mjs

@@ -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
 
 // visualization adapter — optional bounded visual payloads for code-phage.
 //

package/lib/code-phage-core.mjs

@@ -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 } from "node:crypto";
 import { lstatSync, readFileSync, realpathSync, statSync } from "node:fs";

package/lib/python_ast_metrics.py

@@ -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
 
 #!/usr/bin/env python3
 """AST-backed complexity metrics for code-phage.

package/lib/typescript_ast_metrics.mjs

@@ -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 ts from "typescript";
 

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@evoclock/pi-agentic-driver",
-  "version": "0.9.1",
+  "version": "0.9.3",
   "description": "Guardrail extensions for Agentic Driver: advisory review, bounded Herdr communication, and guarded worker lifecycle.",
   "type": "module",
-  "license": "AGPL-3.0-or-later",
+  "license": "AGPL-3.0-only",
+  "engines": {
+    "node": ">=22.5.0"
+  },
   "keywords": [
     "pi-package",
     "pi-extension",
@@ -70,7 +73,15 @@
     "scripts/enforcement/task_board_core_pi.js",
     "scripts/enforcement/pulse_core_pi.js",
     "scripts/enforcement/pulse_scheduler_pi.js",
-    "skills/pulse/SKILL.md"
+    "scripts/enforcement/router_engine_pi.js",
+    "scripts/enforcement/router_schemas_pi.js",
+    "scripts/enforcement/router_ranking_pi.js",
+    "scripts/enforcement/router_store_pi.js",
+    "scripts/enforcement/router_replacement_pi.js",
+    "scripts/enforcement/router_runtime_pi.js",
+    ".agentic-driver/router.defaults.json",
+    "skills/pulse/SKILL.md",
+    "janus"
   ],
   "pi": {
     "extensions": [

package/scripts/aidr_writing_review.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, randomUUID } from "node:crypto";
 import fs, { realpathSync } from "node:fs";

package/scripts/enforcement/attended_authority_guard.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
 
 // Attended-authority destructive-command guard for Pi.
 //

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

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"]);
@@ -427,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`);
   }

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

@@ -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
 
 // 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
@@ -48,9 +48,17 @@ export function modelAvailability({ model, observations = null, declaredModels =
 }
 
 // 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";
+// 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):
@@ -88,8 +96,12 @@ export function freeCapacity({ role, model, pulsePolicy, activeClaims = [], acti
 
   const routeCeiling = route.maxConcurrent;
   const roleCeiling = roleEntry?.maxConcurrent ?? routeCeiling;
-  const policyCeiling = Number.isInteger(pulsePolicy?.globalMaxConcurrent)
-    ? pulsePolicy.globalMaxConcurrent
+  // §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;
@@ -121,7 +133,7 @@ export function routesForRole(role, pulsePolicy) {
 // 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 }) {
+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.
@@ -169,9 +181,13 @@ export function evaluateCard({ card, boardIndex, activeClaims = [], pulsePolicy
   }
   // 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)` };
   }
@@ -181,7 +197,7 @@ export function evaluateCard({ card, boardIndex, activeClaims = [], pulsePolicy
 // 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 }) {
+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)
@@ -190,21 +206,24 @@ export function scanBoard({ cards, boardPath, boardRevision = null, policyRevisi
   const cardResults = [];
   const capacity = [];
   const proposedDispatches = [];
-  const policyWideRemaining = Number.isInteger(pulsePolicy?.globalMaxConcurrent)
-    ? pulsePolicy.globalMaxConcurrent - (activeClaims ?? []).length
+  // §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 });
+      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: null,
-        free: availability === "available" || availability === "full" ? free.free : 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,
       });
     }
@@ -223,6 +242,11 @@ export function scanBoard({ cards, boardPath, boardRevision = null, policyRevisi
       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);