runcap 0.3.1 → 0.5.0

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"/>

package/scripts/mission-test.mjs

@@ -0,0 +1,148 @@
+// Proves a policy-bound mission grades a real run into a PASS/BLOCKED verdict and
+// that the verdict drives the process exit code (so CI fails on a blocked mission).
+// Everything runs offline through the mock cap gateway inside a throwaway git repo:
+//   - an honest fix within scope, under cap        → PASS, exit 0
+//   - an agent that rewrites the verifier           → BLOCKED (VERIFIER_COMPROMISED)
+//   - an edit outside the declared allow scope      → BLOCKED (out of scope)
+//   - a mission whose first call trips the hard cap → BLOCKED (budget guard)
+// It also drives the real `bin/runcap.mjs` so the exit codes and the GitHub
+// Action's `runcap ci` PR summary are tested as a reviewer would see them.
+
+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, readFileSync } from "node:fs";
+
+const SRC_DIR = process.env.RUNCAP_SRC ?? path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "src");
+const BIN = path.join(SRC_DIR, "..", "bin", "runcap.mjs");
+
+const tmp = mkdtempSync(path.join(os.tmpdir(), "runcap-mission-"));
+process.chdir(tmp);
+
+mkdirSync(path.join(tmp, "app"), { recursive: true });
+mkdirSync(path.join(tmp, ".runcap"), { recursive: true });
+// broken.mjs starts wrong, 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");
+// A tracked file OUTSIDE the allow scope: editing it must trip the scope check.
+// (The guard reads `git diff --name-status`, which sees tracked edits - the
+// honest unit of "out of scope" for this scenario.)
+writeFileSync(path.join(tmp, "app", "other.mjs"), "export const other = 0;\n");
+
+const spend = (msg) =>
+  "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:'" + msg + "'}]})}).then(r=>r.text());";
+
+// Honest agent: spends, fixes the source file (the one allowed change).
+writeFileSync(path.join(tmp, "agent-fix.mjs"),
+  spend("fix it") + "const {writeFile}=await import('node:fs/promises');await writeFile('app/broken.mjs','export const ok = true;\\n');\n");
+// Cheating agent: rewrites the VERIFIER so it always passes instead of fixing the bug.
+writeFileSync(path.join(tmp, "agent-cheat.mjs"),
+  spend("cheat") + "const {writeFile}=await import('node:fs/promises');await writeFile('app/verify.mjs','console.log(\"ok\");\\n');\n");
+// Out-of-scope agent: fixes the bug (verify passes) BUT also edits a tracked file outside `allow`.
+writeFileSync(path.join(tmp, "agent-scope.mjs"),
+  spend("scope") + "const {writeFile}=await import('node:fs/promises');await writeFile('app/broken.mjs','export const ok = true;\\n');await writeFile('app/other.mjs','export const other = 1;\\n');\n");
+
+// The mission policy a reviewer commits to the repo.
+const POLICY = `version: v1
+identity:
+  project: checkout
+  team: payments
+mission:
+  name: Fix the failing checkout test
+  task_class: bugfix
+budget:
+  mission_hard_limit_usd: 5
+  max_llm_calls: 12
+verification:
+  command: "node app/verify.mjs"
+  guard: strict
+  protect: ["app/verify.mjs"]
+  allow: ["app/broken.mjs"]
+`;
+writeFileSync(path.join(tmp, ".runcap", "mission.yaml"), POLICY);
+
+// A second policy with a hair-thin cap, so the gateway trips the budget guard pre-flight.
+const TINY_POLICY = POLICY.replace("mission_hard_limit_usd: 5", "mission_hard_limit_usd: 0.0000001");
+writeFileSync(path.join(tmp, ".runcap", "mission-tiny.yaml"), TINY_POLICY);
+
+// 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"));
+const { loadPolicy } = await import(path.join(SRC_DIR, "policy.mjs"));
+
+// Each scenario starts from the committed baseline so one run's edits (the cheat
+// run's rewritten verifier especially) never leak into the next.
+const resetToBaseline = () => { g("checkout", "-f", "HEAD"); g("clean", "-fdq", "-e", ".runcap"); };
+
+const loaded = loadPolicy(tmp);
+
+// 1. Honest fix, within scope, under cap → PASS with a strong verification.
+const fix = await runOutcome({ task: "fix ok", verify: "node app/verify.mjs", command: ["node", "agent-fix.mjs"], label: "mission-fix", mock: true, guard: true, protect: ["app/verify.mjs"], allow: ["app/broken.mjs"], capUsd: 5, policy: loaded });
+check("honest fix verifies", 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("honest fix mission verdict PASS", fix.receipt.policy?.verdict === "PASS", JSON.stringify(fix.receipt.policy?.reasons));
+check("receipt carries the policy hash", /^[0-9a-f]{64}$/.test(fix.receipt.policy?.hash ?? ""), fix.receipt.policy?.hash);
+check("receipt carries org attribution", fix.receipt.policy?.identity?.project === "checkout" && fix.receipt.policy?.identity?.team === "payments");
+check("receipt bumps to v0.3 schema", fix.receipt.schema === "runcap.outcome-receipt/v0.3", fix.receipt.schema);
+
+// 2. Cheat by rewriting the verifier → BLOCKED, VERIFIER_COMPROMISED.
+resetToBaseline();
+const cheat = await runOutcome({ task: "fix ok", verify: "node app/verify.mjs", command: ["node", "agent-cheat.mjs"], label: "mission-cheat", mock: true, guard: true, protect: ["app/verify.mjs"], allow: ["app/broken.mjs"], capUsd: 5, policy: loaded });
+check("cheat run mission verdict BLOCKED", cheat.receipt.policy?.verdict === "BLOCKED", `verdict=${cheat.receipt.policy?.verdict}`);
+check("cheat run names VERIFIER_COMPROMISED", (cheat.receipt.policy?.reasons ?? []).some((r) => r.includes("VERIFIER_COMPROMISED")), JSON.stringify(cheat.receipt.policy?.reasons));
+
+// 3. Edit outside the declared scope → BLOCKED, out-of-scope.
+resetToBaseline();
+const scope = await runOutcome({ task: "fix ok", verify: "node app/verify.mjs", command: ["node", "agent-scope.mjs"], label: "mission-scope", mock: true, guard: true, protect: ["app/verify.mjs"], allow: ["app/broken.mjs"], capUsd: 5, policy: loaded });
+check("out-of-scope run mission verdict BLOCKED", scope.receipt.policy?.verdict === "BLOCKED", `verdict=${scope.receipt.policy?.verdict}`);
+check("out-of-scope run names the scope breach", (scope.receipt.policy?.reasons ?? []).some((r) => r.toLowerCase().includes("scope")), JSON.stringify(scope.receipt.policy?.reasons));
+
+// 4. A hair-thin cap trips the gateway budget guard → BLOCKED, budget reason.
+resetToBaseline();
+const tinyLoaded = loadPolicy(tmp, ".runcap/mission-tiny.yaml");
+const broke = await runOutcome({ task: "fix ok", verify: "node app/verify.mjs", command: ["node", "agent-fix.mjs"], label: "mission-broke", mock: true, guard: true, protect: ["app/verify.mjs"], allow: ["app/broken.mjs"], capUsd: 0.0000001, policy: tinyLoaded });
+check("tiny cap trips the budget guard", broke.receipt.cost.budgetGuardTripped === true, `tripped=${broke.receipt.cost.budgetGuardTripped}`);
+check("budget trip mission verdict BLOCKED", broke.receipt.policy?.verdict === "BLOCKED", `verdict=${broke.receipt.policy?.verdict}`);
+check("budget trip names the budget guard", (broke.receipt.policy?.reasons ?? []).some((r) => r.toLowerCase().includes("budget")), JSON.stringify(broke.receipt.policy?.reasons));
+
+// 5. The real bin must exit 0 on PASS and 1 on BLOCKED so CI fails on a bad mission.
+const runBin = (args, extraEnv = {}) => {
+  try {
+    const stdout = execFileSync("node", [BIN, ...args], { 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 ?? "") };
+  }
+};
+
+resetToBaseline();
+const binPass = runBin(["mission", "run", "--mock", "--", "node", "agent-fix.mjs"]);
+check("`runcap mission run` exits 0 on a PASS mission", binPass.code === 0, `code=${binPass.code}`);
+check("PASS run prints the verdict", /Mission verdict: PASS/.test(binPass.stdout), binPass.stdout.slice(-200));
+
+resetToBaseline();
+const binBlock = runBin(["mission", "run", "--mock", "--", "node", "agent-cheat.mjs"]);
+check("`runcap mission run` exits 1 on a BLOCKED mission", binBlock.code === 1, `code=${binBlock.code}`);
+
+// 6. `runcap ci` (the GitHub Action's grader) must write the PR summary and exit 1 on BLOCKED.
+//    It grades the latest receipt on disk - which the BLOCKED cheat run just wrote.
+const summaryFile = path.join(tmp, "step-summary.md");
+writeFileSync(summaryFile, "");
+const ci = runBin(["ci", "--policy", ".runcap/mission.yaml"], { GITHUB_STEP_SUMMARY: summaryFile });
+check("`runcap ci` exits 1 when the graded receipt is BLOCKED", ci.code === 1, `code=${ci.code}`);
+const summary = readFileSync(summaryFile, "utf8");
+check("`runcap ci` writes a PR summary to GITHUB_STEP_SUMMARY", /Runcap mission verdict: BLOCKED/.test(summary), summary.slice(0, 200));
+
+console.log("\n" + (failures === 0 ? "ALL MISSION TESTS PASSED" : `${failures} MISSION TEST(S) FAILED`));
+process.exit(failures === 0 ? 0 : 1);

package/scripts/outcome-test.mjs

@@ -0,0 +1,48 @@
+// Proves runOutcome produces an honest receipt end-to-end through the REAL cap
+// gateway (mock upstream, so no network/keys), for both the VERIFIED and
+// UNVERIFIED cases. The agent spends recorded tokens; the verify command's exit
+// code is the oracle; Verified Outcome Cost is the actual spend only when verify
+// passes. Runs in an isolated temp cwd so it never touches real .runcap data.
+
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { mkdtempSync, writeFileSync, mkdirSync } from "node:fs";
+
+// Resolve the engine relative to this script so the test runs from any cwd
+// (it chdir's into a temp dir below, so a relative import would break).
+const SRC_DIR = process.env.RUNCAP_SRC ?? path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "src");
+
+const tmp = mkdtempSync(path.join(os.tmpdir(), "runcap-outcome-"));
+process.chdir(tmp);
+
+// A tiny agent that spends through the gateway and writes (or doesn't write) a fix.
+mkdirSync(path.join(tmp, "app"), { 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, "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");
+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");
+
+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"));
+
+const nop = await runOutcome({ task: "fix ok", verify: "node app/verify.mjs", command: ["node", "agent-nop.mjs"], label: "nop", mock: true });
+check("no-fix run is UNVERIFIED", nop.receipt.outcome === "UNVERIFIED", `outcome=${nop.receipt.outcome}`);
+check("no-fix run still spent real money", nop.receipt.cost.actualCostUsd > 0, `cost=${nop.receipt.cost.actualCostUsd}`);
+check("no-fix Verified Outcome Cost is null", nop.receipt.cost.verifiedOutcomeCostUsd === null);
+check("no-fix counts money without delivery", nop.receipt.cost.moneySpentWithoutVerifiedDeliveryUsd > 0);
+
+const fix = await runOutcome({ task: "fix ok", verify: "node app/verify.mjs", command: ["node", "agent-fix.mjs"], label: "fix", mock: true });
+check("fix run is VERIFIED", fix.receipt.outcome === "VERIFIED", `outcome=${fix.receipt.outcome}`);
+check("fix Verified Outcome Cost equals actual spend", fix.receipt.cost.verifiedOutcomeCostUsd === fix.receipt.cost.actualCostUsd);
+check("fix counts zero undelivered money", fix.receipt.cost.moneySpentWithoutVerifiedDeliveryUsd === 0);
+check("cost truth is calculated from usage + price table", /price_table/.test(fix.receipt.cost.truth));
+
+console.log("\n" + (failures === 0 ? "ALL OUTCOME TESTS PASSED" : `${failures} OUTCOME TEST(S) FAILED`));
+process.exit(failures === 0 ? 0 : 1);

package/scripts/policy-test.mjs

@@ -0,0 +1,121 @@
+// Proves src/policy.mjs parses, validates, and grades correctly. Pure unit test:
+// no gateway, no git, no agent - just the policy module over hand-built inputs.
+// Covers: YAML parse + hash, .json fallback, required-field validation, the
+// guard/scope warnings, and every BLOCK condition in evaluatePolicyVerdict.
+
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { mkdtempSync, writeFileSync, mkdirSync } from "node:fs";
+
+const SRC_DIR = process.env.RUNCAP_SRC ?? path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "src");
+const { loadPolicy, validatePolicy, evaluatePolicyVerdict, policyMeta } = await import(path.join(SRC_DIR, "policy.mjs"));
+
+let failures = 0;
+const check = (name, pass, detail) => { if (!pass) failures++; console.log(`${pass ? "PASS" : "FAIL"}  ${name}${detail ? "  — " + detail : ""}`); };
+
+const tmp = mkdtempSync(path.join(os.tmpdir(), "runcap-policy-"));
+mkdirSync(path.join(tmp, ".runcap"), { recursive: true });
+
+const VALID_YAML = `version: v1
+identity:
+  project: checkout
+  team: payments
+mission:
+  name: Fix the failing checkout test
+  task_class: bugfix
+budget:
+  mission_hard_limit_usd: 10
+  max_llm_calls: 12
+  max_runtime_minutes: 30
+verification:
+  command: "node app/verify.mjs"
+  guard: strict
+  protect: ["tests/**"]
+  allow: ["src/checkout/**"]
+`;
+
+// 1. Valid YAML loads, parses, hashes, validates clean.
+writeFileSync(path.join(tmp, ".runcap", "mission.yaml"), VALID_YAML);
+const loaded = loadPolicy(tmp);
+check("loadPolicy finds .runcap/mission.yaml", loaded && loaded.source.endsWith("mission.yaml"));
+check("loadPolicy computes a sha256 hash", /^[0-9a-f]{64}$/.test(loaded.hash), loaded.hash);
+check("valid policy parses mission.name", loaded.policy.mission.name === "Fix the failing checkout test");
+const v1 = validatePolicy(loaded.policy);
+check("valid policy validates ok", v1.ok === true, JSON.stringify(v1.errors));
+check("valid policy with allow has no scope warning", !v1.warnings.some((w) => w.includes("allow is empty")));
+const meta = policyMeta(loaded);
+check("policyMeta carries identity + hash", meta.identity.project === "checkout" && meta.hash === loaded.hash);
+check("policyMeta carries the limits", meta.limits.mission_hard_limit_usd === 10 && meta.limits.max_llm_calls === 12);
+
+// 2. .json fallback parses with native JSON.parse (no parser needed).
+const tmp2 = mkdtempSync(path.join(os.tmpdir(), "runcap-policy-json-"));
+mkdirSync(path.join(tmp2, ".runcap"), { recursive: true });
+writeFileSync(path.join(tmp2, ".runcap", "mission.json"), JSON.stringify({
+  version: "v1",
+  mission: { name: "json mission" },
+  budget: { mission_hard_limit_usd: 5 },
+  verification: { command: "npm test" }
+}));
+const jsonLoaded = loadPolicy(tmp2);
+check("loadPolicy reads .json fallback", jsonLoaded && jsonLoaded.source.endsWith("mission.json"));
+check("json policy validates ok", validatePolicy(jsonLoaded.policy).ok === true);
+
+// 3. Missing verification.command → invalid.
+const noVerify = validatePolicy({ version: "v1", mission: { name: "x" }, budget: { mission_hard_limit_usd: 1 } });
+check("missing verification.command is invalid", noVerify.ok === false && noVerify.errors.some((e) => e.includes("verification.command")));
+
+// 4. Bad version → invalid.
+const badVersion = validatePolicy({ version: "v2", mission: { name: "x" }, budget: { mission_hard_limit_usd: 1 }, verification: { command: "npm test" } });
+check("wrong version is invalid", badVersion.ok === false && badVersion.errors.some((e) => e.includes("version")));
+
+// 5. Missing budget cap → invalid.
+const noBudget = validatePolicy({ version: "v1", mission: { name: "x" }, verification: { command: "npm test" } });
+check("missing mission_hard_limit_usd is invalid", noBudget.ok === false && noBudget.errors.some((e) => e.includes("mission_hard_limit_usd")));
+
+// 6. No allow scope → warning (not error).
+const noAllow = validatePolicy({ version: "v1", mission: { name: "x" }, budget: { mission_hard_limit_usd: 1 }, verification: { command: "npm test", allow: [] } });
+check("empty allow produces a warning", noAllow.ok === true && noAllow.warnings.some((w) => w.includes("allow is empty")));
+
+// 7. evaluatePolicyVerdict: a clean VERIFIED receipt → PASS.
+const policy = loaded.policy;
+const cleanReceipt = {
+  outcome: "VERIFIED",
+  verificationIntegrity: { status: "VERIFIED_STRONG", violations: [] },
+  cost: { actualCostUsd: 0.0007, llmCalls: 2, budgetGuardTripped: false },
+  work: { agentDurationMs: 5000 }
+};
+check("clean receipt grades PASS", evaluatePolicyVerdict(cleanReceipt, policy).verdict === "PASS");
+
+// 8. Compromised verifier → BLOCKED with the reason.
+const compromised = { ...cleanReceipt, verificationIntegrity: { status: "VERIFIER_COMPROMISED", violations: ["verifier_file_unchanged:app/verify.mjs"] } };
+const cv = evaluatePolicyVerdict(compromised, policy);
+check("compromised verifier grades BLOCKED", cv.verdict === "BLOCKED" && cv.reasons.some((r) => r.includes("VERIFIER_COMPROMISED")));
+
+// 9. UNVERIFIED → BLOCKED.
+const unver = { ...cleanReceipt, outcome: "UNVERIFIED", verificationIntegrity: { status: "UNVERIFIED", violations: [] } };
+check("unverified grades BLOCKED", evaluatePolicyVerdict(unver, policy).verdict === "BLOCKED");
+
+// 10. Out-of-allow scope → BLOCKED.
+const scope = { ...cleanReceipt, verificationIntegrity: { status: "VERIFIED_STRONG", violations: ["within_allowed_scope:src/other.mjs"] } };
+const sc = evaluatePolicyVerdict(scope, policy);
+check("out-of-scope edit grades BLOCKED", sc.verdict === "BLOCKED" && sc.reasons.some((r) => r.toLowerCase().includes("scope")));
+
+// 11. Over the dollar cap → BLOCKED.
+const overCost = { ...cleanReceipt, cost: { actualCostUsd: 11, llmCalls: 2, budgetGuardTripped: false } };
+check("over the cap grades BLOCKED", evaluatePolicyVerdict(overCost, policy).verdict === "BLOCKED");
+
+// 12. budget_guard tripped → BLOCKED.
+const guardTrip = { ...cleanReceipt, cost: { actualCostUsd: 1, llmCalls: 2, budgetGuardTripped: true } };
+check("budget guard trip grades BLOCKED", evaluatePolicyVerdict(guardTrip, policy).verdict === "BLOCKED");
+
+// 13. Too many LLM calls → BLOCKED.
+const tooMany = { ...cleanReceipt, cost: { actualCostUsd: 1, llmCalls: 99, budgetGuardTripped: false } };
+check("too many llm calls grades BLOCKED", evaluatePolicyVerdict(tooMany, policy).verdict === "BLOCKED");
+
+// 14. Over the runtime budget → BLOCKED.
+const slow = { ...cleanReceipt, work: { agentDurationMs: 31 * 60_000 } };
+check("over runtime budget grades BLOCKED", evaluatePolicyVerdict(slow, policy).verdict === "BLOCKED");
+
+console.log("\n" + (failures === 0 ? "ALL POLICY TESTS PASSED" : `${failures} POLICY TEST(S) FAILED`));
+process.exit(failures === 0 ? 0 : 1);

package/scripts/render-media-screenshots.mjs

@@ -0,0 +1,37 @@
+import { chromium } from "playwright";
+import { pathToFileURL } from "node:url";
+import { resolve } from "node:path";
+
+const root = resolve(import.meta.dirname, "..");
+const mediaDir = resolve(root, "docs/assets/media");
+
+const shots = [
+  {
+    html: resolve(mediaDir, "cover.html"),
+    png: resolve(mediaDir, "cover.png"),
+    width: 1200,
+    height: 630
+  },
+  {
+    html: resolve(mediaDir, "demo.html"),
+    png: resolve(mediaDir, "demo.png"),
+    width: 1200,
+    height: 750
+  }
+];
+
+const browser = await chromium.launch();
+try {
+  for (const shot of shots) {
+    const page = await browser.newPage({
+      viewport: { width: shot.width, height: shot.height },
+      deviceScaleFactor: 2
+    });
+    await page.goto(pathToFileURL(shot.html).href, { waitUntil: "networkidle" });
+    await page.screenshot({ path: shot.png, fullPage: false });
+    await page.close();
+    console.log(`rendered ${shot.png}`);
+  }
+} finally {
+  await browser.close();
+}