zob-harness 0.13.0 → 0.14.0

package/.pi/capabilities/zob-public-runtime-capabilities.json

@@ -719,7 +719,7 @@
       "docRefs": [
         ".pi/extensions/zob-harness/src/AGENTS.md"
       ],
-      "noShipNotes": "Agent-initiated visible ZPeer ask; local_socket only, room-scoped with optional explicit roomId, mode defaults async, rate/loop guarded, raw bodies transient and durable records hash-only."
+      "noShipNotes": "Agent-initiated visible ZPeer ask; local_socket only, room-scoped with optional explicit roomId, mode defaults async, normal/urgent/force are rate/loop guarded, force requires a hashed reason and role/topology guards, raw bodies transient and durable records hash-only."
     },
     {
       "name": "zob_goal_room_send",

package/.pi/extensions/zob-harness/index.ts

@@ -352,6 +352,79 @@ export type {
   AutoResolveVerdict,
   ResolutionStrategyFn,
 } from "./src/domains/environment/auto-resolve.js";
+// WS-CH1 (capability-validation PART II keystone): the typed CapabilityContract
+// pillar (the 5th pillar alongside computeWorklist/EvidenceContract/EnvironmentContract).
+// The contract shape + registry + PURE primitives (no node:fs/node:child_process); the
+// body + readManifest IO + the role->required-tools map are project-registered (WS-CH3).
+// Metadata-only / body-free / network-disabled: AgentManifest/RoleRequirement/
+// CapabilityVerdict carry agent ids, tool names, mode names, manifest paths, fixCommand
+// strings only; FORBIDDEN_PLAINTEXT_KEYS applies (reused from the worklist domain).
+// CRITICAL SAFETY: NO auto-resolve on the contract (manifest edit = security-sensitive =
+// operator-gated, unlike Round 4 env auto-resolve).
+export {
+  buildFixPacket,
+  compareCapability,
+  manifestHasTool,
+  modePermitsWrite,
+  requiredToolsForRole,
+} from "./src/domains/capability/primitives.js";
+export type { CapabilityFixPacketEntry } from "./src/domains/capability/primitives.js";
+export {
+  capabilityBodyFreeViolations,
+  listCapabilityContractIds,
+  registerCapabilityContract,
+  resolveCapabilityContract,
+} from "./src/domains/capability/capability-contract.js";
+export type { CapabilityContract } from "./src/domains/capability/capability-contract.js";
+export type {
+  AgentManifest,
+  CapabilityVerdict,
+  RoleName,
+  RoleRequirement,
+} from "./src/domains/capability/types.js";
+// WS-CH2 (capability-validation PART II): the launch-time gate primitive + the
+// runtime nudge-backoff/gap primitives. runCapabilityGate reads each manifest once
+// (via the contract's readManifest), evaluates every agent against its role's
+// requirement, returns { ok, verdicts, fix_packet, shouldStart } with
+// shouldStart === ok BY CONSTRUCTION (fail-closed, no opt-out). Pure over
+// (contract, agentIds); never starts anything itself (mechanism in harness, action
+// in app). Idempotent + re-runnable (re-reads manifests on re-call). The nudge-
+// policy primitives compose the supervisor anti-spam policy: planBackoffNudge
+// (60s→2m→5m→15m cap + the structural capability_gap_stop), detectCapabilityGap
+// (gates escalation — slow-but-capable stays gap===false), capabilityGapFixPacket
+// (the metadata-only alert_no_ship fix packet), transitionOnCapabilityGap (forces
+// the terminal capability_gap:true stop once gap===true). Metadata-only /
+// body-free / network-disabled. No node:fs/node:child_process (the purity grep
+// returns nothing). CRITICAL SAFETY: NO auto-resolve (manifest edit = security-
+// sensitive = operator-gated, intentional divergence from Round 4 env auto-resolve).
+export { runCapabilityGate } from "./src/domains/capability/launch-gate.js";
+// NOTE: aliased as CapabilityLaunchGateOptions / CapabilityLaunchGateResult to
+// avoid a name collision with the WS-PH2 environment pillar's identically-named
+// LaunchGateOptions / LaunchGateResult exports above (index.ts ~L330). Both
+// shapes exist; consumers pick the capability gate via the `Capability*` prefix.
+export type {
+  LaunchGateOptions as CapabilityLaunchGateOptions,
+  LaunchGateResult as CapabilityLaunchGateResult,
+} from "./src/domains/capability/launch-gate.js";
+export {
+  DEFAULT_NUDGE_SCHEDULE,
+  NUDGE_BACKOFF_CAP_MS,
+  capabilityGapFixPacket,
+  detectCapabilityGap,
+  planBackoffNudge,
+  transitionOnCapabilityGap,
+} from "./src/domains/capability/nudge-policy.js";
+export type {
+  CapabilityGapAction,
+  CapabilityGapFixPacket,
+  CapabilityGapTransition,
+  DetectCapabilityGapInput,
+  DriverRecord,
+  GapResult,
+  NudgePlan,
+  NudgeSchedule,
+  PlanBackoffNudgeInput,
+} from "./src/domains/capability/nudge-policy.js";
 export { DEFAULT_PROMOTION_GATES, advancePromotionCandidate, appendPromotionLedger, createPromotionCandidate, promotionCandidateDir, promotionCandidateRef, promotionReportsDir, summarizePromotionCandidates, transitionAllowed, validatePromotionCandidate, writePromotionCandidate } from "./src/domains/promotion/candidate.js";
 export { addPromotionComsMessageRef, buildPromotionComsMessageRef, buildPromotionComsThread, validatePromotionComsMessageRef, validatePromotionComsReadiness, validatePromotionComsThread, writePromotionComsThread } from "./src/domains/promotion/coms.js";
 export { applyDocumentationPromotionInQuarantine, prepareDocumentationPromotion, validateDocumentationPromotion, validateDocumentationPromotionCandidate } from "./src/domains/promotion/documentation.js";

package/.pi/extensions/zob-harness/src/domains/capability/AGENTS.md

@@ -0,0 +1,72 @@
+# Capability domain (`src/domains/capability/`)
+
+WS-CH1 keystone of the capability-validation extraction (PART II). The FIFTH
+harness pillar alongside `computeWorklist` (Round 2), `EvidenceContract`
+(Round 3), and `EnvironmentContract` (Round 4): a typed `CapabilityContract` +
+registry + PURE check primitives that shift agent-capability validation (an
+agent's `allowedTools`/`defaultMode` vs the protocol's per-role required tools)
+from late runtime discovery (a stall + 59 nudge-spams when a structurally
+incapable agent is launched) to an early fail-closed launch gate every consumer
+gets for free.
+
+## Shape provenance
+
+- `AgentManifest` / `RoleRequirement` / `CapabilityVerdict` / `CapabilityContract`
+  mirror the WS-CH1 plan signatures (adapted JSDoc typedefs -> TS interfaces;
+  camelCase harness convention) verbatim. `registerCapabilityContract` /
+  `resolveCapabilityContract` / `listCapabilityContractIds` Map registry mirrors
+  `environment-contract.ts` (Round 4) EXACTLY.
+- The registry is keyed by `reducerId` (projects register under their
+  `reducer_id`; the transposer registers `reducerId='project-transposer'` in
+  WS-CH3). A missing contract resolves to `undefined` (typed-missing, NOT a
+  silent default) — same plan-specified divergence as `resolveEnvironmentContract`.
+
+## Purity contract (headline acceptance)
+
+- `primitives.ts` imports NO `node:fs`, NO `node:child_process`, NO
+  `spawnSync`/`readdirSync`/`readFileSync`/`exec`. It is PURE over the
+  `AgentManifest` / `RoleRequirement` / `CapabilityVerdict` data structures the
+  caller passes (the ONLY IO seam is the project-registered `readManifest`, which
+  the harness never calls — it is a signature only in CH1).
+- `types.ts` + `capability-contract.ts` import ONLY `src/core/**` + siblings
+  (`./types.js`, `../worklist/types.js` for `FORBIDDEN_PLAINTEXT_KEYS`). No
+  runtime; no `@earendil-works/pi-coding-agent`. This keeps the domain reusable by
+  transposer/pacman-style projections.
+
+## MUST DO
+
+- Keep the contract SHAPE-ONLY; the body (`evaluateCapability` dispatch +
+  `readManifest` IO + the role->required-tools map) is project-registered.
+  `readManifest` is the ONLY IO and is project-supplied (the harness defines the
+  signature only). Primitives stay pure over the inputs. Metadata-only /
+  body-free / network-disabled: agent ids, tool names, mode names, manifest paths,
+  fixCommand strings only.
+
+## MUST NOT
+
+- No `node:fs` / `node:child_process` (or `spawnSync`/`readdirSync`/`exec`) in
+  `primitives.ts`. No raw bodies/prompts/diffs/secrets in any manifest,
+  requirement, verdict, or fix packet. No network. No change to the worklist or
+  environment domains (read-only import of `FORBIDDEN_PLAINTEXT_KEYS`).
+- **CRITICAL SAFETY DIVERGENCE from Round 4**: NO auto-resolve method on the
+  contract (no `applyAutoResolve`, no auto-fix). Editing a ZAgent manifest changes
+  an agent's authority (allowedTools/defaultMode) = SECURITY-SENSITIVE = always
+  operator-gated, unlike Round 4's reversible environment auto-resolve. The
+  contract evaluates + surfaces a fix packet; applying the edit is app/operator-side.
+
+## Files
+
+- `types.ts` — `RoleName`, `AgentManifest`, `RoleRequirement`, `CapabilityVerdict`
+  (all readonly, metadata-only).
+- `capability-contract.ts` — `CapabilityContract`, `registerCapabilityContract` /
+  `resolveCapabilityContract` / `listCapabilityContractIds` Map registry,
+  `capabilityBodyFreeViolations`.
+- `primitives.ts` — `manifestHasTool`, `modePermitsWrite`, `requiredToolsForRole`,
+  `compareCapability`, `buildFixPacket` (PURE over the inputs; result interface
+  `CapabilityFixPacketEntry` exported).
+
+## Validation
+
+- `npm run check -- --pretty false` clean; `node --import tsx --test "test/capability/*"` green.
+- `grep primitives.ts for direct fs / process-spawn / exec tokens` returns
+  NOTHING (the purity proof).

package/.pi/extensions/zob-harness/src/domains/capability/capability-contract.ts

@@ -0,0 +1,121 @@
+// ZOB Harness — Agent capability validation contract + registry (WS-CH1 keystone,
+// capability-validation PART II).
+//
+// The FIFTH PILLAR alongside computeWorklist (Round 2), EvidenceContract
+// (Round 3), and EnvironmentContract (Round 4): a typed CapabilityContract that
+// every multi-agent consumer registers under its `reducer_id`, mirroring
+// registerEnvironmentContract's Map registry EXACTLY. The harness ships the SHAPE
+// (the contract interface + the pure primitives) + the registry; the BODY
+// (which roles need which tools) + the manifest READER (`readManifest` IO) are
+// project-registered (WS-CH3, deferred). CH1-style: shape-only, deferred body.
+//
+// CRITICAL SAFETY DIVERGENCE from Round-4 EnvironmentContract (documented here so
+// it is never accidentally re-introduced): there is NO auto-resolve method on
+// this contract. Round 4's EnvironmentContract had `snapshotEnvironment` + a
+// WS-PH3 `applyAutoResolve` framework (allowlisted + REVERSIBLE env fixes). A
+// capability gap is NOT auto-resolvable: editing a ZAgent manifest changes an
+// agent's authority (its allowedTools/defaultMode), which is a SECURITY-SENSITIVE
+// operation that must stay operator-gated. This contract therefore exposes ONLY
+// `evaluateCapability` (pure verdict) + `readManifest` (project-supplied IO) +
+// `requirements` (project-supplied role→required-tools body). The fix packet the
+// verdict surfaces is the END of what the harness does; applying the manifest edit
+// is app/operator-side (WS-CH2 launch-gate will turn a failing verdict into a
+// fail-closed block + a printed fix_command, never an auto-edit). This is the
+// same split as Round 4's `runLaunchGate` (mechanism in harness, action in app)
+// EXCEPT there is intentionally no `applyAutoResolve` sibling — the action is
+// always a human edit.
+//
+// Purity contract: imports ONLY from src/core/** + siblings (../worklist/types.js
+// for FORBIDDEN_PLAINTEXT_KEYS, ./types.js for the typed shapes — type-only,
+// erased at runtime). No IO; no runtime; no @earendil-works/pi-coding-agent
+// types. Metadata-only / body-free / network-disabled: CapabilityContract
+// consumers carry agent ids, tool names, mode names, manifest paths, and
+// fixCommand strings only; FORBIDDEN_PLAINTEXT_KEYS is enforced on every value
+// that enters the contract via capabilityBodyFreeViolations.
+import { FORBIDDEN_PLAINTEXT_KEYS } from "../worklist/types.js";
+import type {
+  AgentManifest,
+  CapabilityVerdict,
+  RoleName,
+  RoleRequirement,
+} from "./types.js";
+
+// --- The capability contract ------------------------------------------------
+// Project-registered under its `reducer_id` (the same keying as
+// EnvironmentContract / EvidenceContract / WorklistReducer). `evaluateCapability`
+// is the SINGLE SITE of capability satisfaction: pure over
+// (manifest, requirement); no IO. `readManifest` is the ONLY IO entry point —
+// the project supplies it (reads .pi/zagents/<id>.json -> AgentManifest); CH1
+// defines the signature only and never does IO in the harness. `requirements`
+// returns the project's role→required-tools body (from the protocol's
+// machine-readable `Required tools per role` section / .pi/capabilities/<id>.json).
+export interface CapabilityContract {
+  /** Canonical verdict, pure over (manifest, requirement). */
+  evaluateCapability(manifest: AgentManifest, requirement: RoleRequirement): CapabilityVerdict;
+  /** Project-supplied manifest reader (.pi/zagents/<id>.json -> AgentManifest). The ONLY IO. */
+  readManifest(agentId: string): AgentManifest;
+  /** Project-supplied role->required-tools body (from protocol / .pi/capabilities). */
+  requirements(): Record<RoleName, RoleRequirement>;
+}
+
+// --- Body-free enforcement ---------------------------------------------------
+// Mirrors environmentBodyFreeViolations / evidenceBodyFreeViolations /
+// worklistBodyFreeViolations: recursively scan an AgentManifest / RoleRequirement
+// / CapabilityVerdict / fix-packet value and report any FORBIDDEN_PLAINTEXT_KEYS
+// found (body/task/prompt/output/content/message/text/rationale/diff/patch).
+// Returns [] for a clean value. The launch gate (WS-CH2) will call this before
+// threading a manifest set into the contract; CH1 exposes it now so the contract
+// is body-free from the first use.
+export function capabilityBodyFreeViolations(value: unknown): string[] {
+  const violations: string[] = [];
+  const visit = (item: unknown, path: string): void => {
+    if (!item || typeof item !== "object") return;
+    if (Array.isArray(item)) {
+      for (let index = 0; index < item.length; index += 1) visit(item[index], `${path}[${index}]`);
+      return;
+    }
+    for (const [key, child] of Object.entries(item as Record<string, unknown>)) {
+      if (FORBIDDEN_PLAINTEXT_KEYS.has(key)) violations.push(`${path}.${key}`);
+      visit(child, `${path}.${key}`);
+    }
+  };
+  visit(value, "root");
+  return violations;
+}
+
+// --- Capability contract registry -------------------------------------------
+// Mirrors the EnvironmentContract registry (environment-contract.ts
+// registerEnvironmentContract / resolveEnvironmentContract /
+// listEnvironmentContractIds) and the EvidenceContract / WorklistReducer
+// registries: keyed by reducerId (projects register under their reducer_id; the
+// transposer will register reducerId='project-transposer' in WS-CH3). A MISSING
+// contract resolves to `undefined` — a typed-missing signal, NOT a silent
+// default — so the caller can fail-closed explicitly. (Same deliberate,
+// plan-specified divergence as resolveEnvironmentContract: the WS-CH1 plan
+// signature is `CapabilityContract | undefined`; the launch gate WS-CH2 will turn
+// undefined into an explicit fail-closed verdict.)
+const CAPABILITY_CONTRACTS = new Map<string, CapabilityContract>();
+
+export function registerCapabilityContract(
+  reducerId: string,
+  contract: CapabilityContract,
+): void {
+  if (!reducerId) throw new Error("registerCapabilityContract: reducerId is required");
+  if (!contract || typeof contract !== "object")
+    throw new Error(`registerCapabilityContract('${reducerId}'): contract is required`);
+  if (typeof contract.evaluateCapability !== "function")
+    throw new Error(`CapabilityContract '${reducerId}' is missing evaluateCapability(manifest, requirement)`);
+  if (typeof contract.readManifest !== "function")
+    throw new Error(`CapabilityContract '${reducerId}' is missing readManifest(agentId)`);
+  if (typeof contract.requirements !== "function")
+    throw new Error(`CapabilityContract '${reducerId}' is missing requirements()`);
+  CAPABILITY_CONTRACTS.set(reducerId, contract);
+}
+
+export function resolveCapabilityContract(reducerId: string): CapabilityContract | undefined {
+  return CAPABILITY_CONTRACTS.get(reducerId);
+}
+
+export function listCapabilityContractIds(): string[] {
+  return [...CAPABILITY_CONTRACTS.keys()];
+}

package/.pi/extensions/zob-harness/src/domains/capability/launch-gate.ts

@@ -0,0 +1,185 @@
+// ZOB Harness — Agent capability launch-time gate primitive (WS-CH2 keystone,
+// capability-validation PART II).
+//
+// The launch-time GATE on top of the WS-CH1 CapabilityContract: a pure primitive
+// `runCapabilityGate(contract, agentIds, options)` that reads each manifest ONCE
+// (via the contract's project-registered readManifest), evaluates every agent
+// against its role's requirement (via the contract's evaluateCapability), and
+// returns { ok, verdicts, fix_packet, shouldStart } — a pure verdict the app
+// gates ZTEAM_LAUNCHER start on. It NEVER starts anything itself (mechanism in
+// harness, action in app), preserving the shift-left split: the gate says
+// "should this run start?" and the app acts on the answer. Mirrors the Round-4
+// runLaunchGate invariant verbatim.
+//
+// THE HEADLINE DESIGN is fail-closed BY CONSTRUCTION — shouldStart === ok always,
+// with NO parameter to opt out (the whole point of shifting agent-capability
+// discovery from late runtime inside one agent — where it stalls ~2h and is
+// nudge-spammed 59 times — to early launch when the operator who edits manifests
+// is present). This is the temporal mirror of Round 4 applied to agent
+// CONFIGURATION instead of environmental preconditions.
+//
+// IDEMPOTENT + RE-RUNNABLE: runCapabilityGate re-reads manifests (fresh
+// contract.readManifest per agent) and re-evaluates on every call — it performs
+// NO memoization. This is the property that makes "edit manifest → re-launch"
+// work without a special path: after a manifest edit fixes a failing agent, a
+// second runCapabilityGate call re-reads the now-fixed manifest and re-derives
+// shouldStart === true.
+//
+// CRITICAL SAFETY DIVERGENCE from Round-4 EnvironmentContract (documented so it
+// is never accidentally re-introduced): there is NO auto-resolve here. The gate
+// EVALUATES + SURFACES a fix packet (buildFixPacket); APPLYING the manifest edit
+// is operator-gated (a manifest edit changes an agent's authority =
+// security-sensitive). grep this file for 'applyAutoResolve|autoFix|auto-resolve'
+// returns ONLY this comment block — there is no such method. The Round-4
+// environment launch-gate had an applyAutoResolve sibling (WS-PH3, allowlisted +
+// REVERSIBLE env fixes); this capability gate intentionally does NOT, because
+// editing a ZAgent manifest is a security-sensitive authority change that must
+// stay operator-gated.
+//
+// Purity contract (the headline acceptance): this module performs NO direct
+// filesystem access and NO process spawning. It imports type-only (erased at
+// runtime) from the siblings ./types.js + ./capability-contract.js + a single
+// runtime import of buildFixPacket (PURE) from ./primitives.js. The real IO
+// (reading .pi/zagents/<id>.json into an AgentManifest) lives ENTIRELY in the
+// project-registered readManifest (WS-CH3), never here. (The purity grep over
+// this file — scanning for node:fs / node:child_process / spawnSync /
+// readdirSync / readFileSync / exec( — returns NOTHING.)
+//
+// Metadata-only / body-free / network-disabled: LaunchGateResult /
+// CapabilityFixPacketEntry carry agent ids, tool names, mode names, manifest
+// paths, and fix_command strings only — no prompt bodies, no secrets, no
+// allowedPaths contents.
+import type { CapabilityContract } from "./capability-contract.js";
+import type { AgentManifest, CapabilityVerdict } from "./types.js";
+import { buildFixPacket, type CapabilityFixPacketEntry } from "./primitives.js";
+
+// Re-export the fix-packet entry shape so consumers import it from the gate's
+// surface (mirrors the WS-PH2 launch-gate re-exporting FixPacketEntry). The
+// shape is defined in primitives.ts (buildFixPacket); the gate re-exports it so
+// a downstream reader has one import site for the launch-gate result type.
+export type { CapabilityFixPacketEntry } from "./primitives.js";
+
+// --- Options ----------------------------------------------------------------
+export interface LaunchGateOptions {
+  /**
+   * Pluggable clock (deterministic in tests). The verdict itself is pure over
+   * (contract, manifests) and time-independent; this hook is reserved for an app
+   * to stamp emitted fix_packet entries. Reserved — not consumed by the core
+   * flow. (Mirrors the WS-PH2 runLaunchGate `now?` reserved hook.)
+   *
+   * NOTE: there is NO `manifests?` / `allowStart?` / `force?` option here. The
+   * manifests are read via the contract's readManifest (the only IO seam); and
+   * shouldStart === ok BY CONSTRUCTION with no opt-out — so no such option can
+   * exist. The only option is the reserved clock.
+   */
+  readonly now?: () => Date;
+}
+
+// --- Result -----------------------------------------------------------------
+export interface LaunchGateResult {
+  /** True iff EVERY evaluated agent's verdict.ok === true (fail-closed). */
+  readonly ok: boolean;
+  /** One verdict per evaluated agent (agents with no role requirement are skipped). */
+  readonly verdicts: readonly CapabilityVerdict[];
+  /** One entry per FAILING agent, in evaluation order. Empty iff ok === true. */
+  readonly fix_packet: readonly CapabilityFixPacketEntry[];
+  /**
+   * === ok BY CONSTRUCTION (fail-closed). There is NO option to opt out of this:
+   * the gate refuses to start whenever any agent fails its capability contract.
+   * This is the shift-left guarantee — agent capability validated at launch, not
+   * ~2h into a run via nudge-spam.
+   */
+  readonly shouldStart: boolean;
+}
+
+// --- The primitive ----------------------------------------------------------
+/**
+ * Pure over (contract, agentIds). For each agentId: (1) read the manifest ONCE
+ * via contract.readManifest; (2) look up the manifest's role requirement via
+ * contract.requirements()[manifest.role] — agents with NO requirement are SKIPPED
+ * (permissive for unknown roles, not blocking; documented); (3) evaluate via
+ * contract.evaluateCapability(manifest, requirement) (the contract method, so the
+ * project can override — it delegates to compareCapability by default);
+ * (4) ok = every verdict.ok === true; (5) fix_packet from the FAILING verdicts via
+ * buildFixPacket (one entry per failure); (6) shouldStart === ok BY CONSTRUCTION
+ * (no opt-out — the headline fail-closed shift-left guarantee).
+ *
+ * SYNC when readManifest returns synchronously; returns a
+ * Promise<LaunchGateResult> ONLY when readManifest returns a Promise (each
+ * manifest is read once, then the set is shared across the evaluation). The union
+ * return type accommodates both paths.
+ *
+ * IDEMPOTENT + RE-RUNNABLE: no memoization. A second call after a manifest edit
+ * re-reads and re-evaluates, so "edit manifest → re-launch" works without a
+ * special path. NEVER starts anything itself — it is a pure verdict the app acts
+ * on (same split as Round 4's runLaunchGate).
+ *
+ * NO AUTO-RESOLVE: this function evaluates + surfaces a fix packet; it does NOT
+ * apply any manifest edit. Applying the edit is operator-gated (security-
+ * sensitive authority change).
+ */
+export function runCapabilityGate(
+  contract: CapabilityContract,
+  agentIds: readonly string[],
+  // `options` is reserved (the `now?` clock hook); the core flow is pure over
+  // (contract, agentIds) and does not consume it. Kept on the signature so the
+  // reserved hook is available to an app without a breaking change later.
+  options: LaunchGateOptions = {},
+): LaunchGateResult | Promise<LaunchGateResult> {
+  // (1) Read each manifest ONCE via the contract's project-registered readManifest.
+  //     The IO lives in the contract (app-side), NEVER here. readManifest may be
+  //     sync OR async (a project may register an async reader); the declared
+  //     WS-CH1 signature is sync, but we tolerate a Promise return at runtime so a
+  //     project whose reader is async composes without a wrapper. Each manifest is
+  //     read exactly once (no repeated IO per agent).
+  const manifestReads = agentIds.map(
+    (agentId) => contract.readManifest(agentId) as AgentManifest | Promise<AgentManifest>,
+  );
+
+  // Build the verdict from resolved manifests. Pure over (contract, manifests).
+  const buildResult = (manifests: readonly AgentManifest[]): LaunchGateResult => {
+    const requirements = contract.requirements();
+    const verdicts: CapabilityVerdict[] = [];
+    const fix_packet: CapabilityFixPacketEntry[] = [];
+
+    for (const manifest of manifests) {
+      // (2) Look up the manifest's role requirement. Agents with no declared
+      //     requirement are SKIPPED (permissive for unknown roles, not blocking).
+      //     The launch gate evaluates only agents whose role has a protocol-declared
+      //     tool contract; an unknown role is treated as "no requirement" rather
+      //     than a blocker (the operator can add a requirement to enforce it).
+      const requirement = requirements[manifest.role];
+      if (!requirement) continue;
+
+      // (3) Evaluate via the contract method (delegates to compareCapability by
+      //     default; the project can override). Single site of capability
+      //     satisfaction per the WS-CH1 contract.
+      const verdict = contract.evaluateCapability(manifest, requirement);
+      verdicts.push(verdict);
+
+      // (5) fix_packet: one entry per FAILING agent, in evaluation order. Built
+      //     from the verdict + the manifest + the requirement via buildFixPacket
+      //     (the metadata-only remediation shape from primitives.ts).
+      if (!verdict.ok) {
+        fix_packet.push(buildFixPacket(verdict, manifest, requirement));
+      }
+    }
+
+    // (4) ok iff EVERY verdict.ok === true (fail-closed — any single failure
+    //     blocks start). An empty verdict set (no agents had requirements) is ok.
+    const ok = verdicts.every((v) => v.ok === true);
+
+    // (6) shouldStart === ok BY CONSTRUCTION. No option opts out of fail-closed.
+    //     This is the headline shift-left guarantee — derived from ok, never set
+    //     independently.
+    return { ok, verdicts, fix_packet, shouldStart: ok };
+  };
+
+  // SYNC when every readManifest returns synchronously; ASYNC only when at least
+  // one readManifest returns a Promise (await them all via Promise.all, then
+  // build the result once over the resolved set).
+  if (manifestReads.some((read) => read instanceof Promise)) {
+    return Promise.all(manifestReads).then(buildResult);
+  }
+  return buildResult(manifestReads as readonly AgentManifest[]);
+}