runcap 0.3.1 → 0.5.0

package/src/mission-control.mjs

@@ -8,10 +8,12 @@ import process from "node:process";
 import { syncRun } from "./cloud.mjs";
 import { sendAlert } from "./alerts.mjs";
 import { compressRequestBody, estimateTokens, requestShapeText, detectLoop, responseSignature } from "./compressor.mjs";
+import { evaluatePolicyVerdict, policyMeta, formatPolicyBlock } from "./policy.mjs";
 
 const STORE_DIR = ".runcap";
 const MISSIONS_DIR = path.join(STORE_DIR, "missions");
 const PLANS_DIR = path.join(STORE_DIR, "plans");
+const OUTCOMES_DIR = path.join(STORE_DIR, "outcomes");
 const FUEL_FILE = path.join(STORE_DIR, "fuel.json");
 const GATEWAY_EVENTS_FILE = path.join(STORE_DIR, "gateway-events.jsonl");
 const BUDGET_FILE = path.join(STORE_DIR, "budget.json");
@@ -147,6 +149,439 @@ export async function runMission({ command, label, fuelBefore, autoGateway = fal
   };
 }
 
+// Verified Outcome Cost: run an agent on one task, then run a verification
+// command, and only count the money as "delivered" if verification passes.
+// The unit the rest of the industry ignores: dollars per VERIFIED task, not
+// dollars per token. Reuses the same gateway cost, git-diff, and truth-label
+// machinery as runMission, so every number on the receipt is observed or
+// calculated, never guessed.
+export async function runOutcome({ task, verify, command, label, mock = false, guard = false, protect = [], allow = [], policy = null, capUsd = null }) {
+  if (!task || !task.trim()) throw new Error("runOutcome: a --task description is required.");
+  if (!verify || !verify.trim()) throw new Error("runOutcome: a --verify command is required (e.g. \"npm test && npm run build\").");
+  if (!Array.isArray(command) || command.length === 0) throw new Error("runOutcome: an agent command after `--` is required.");
+  // A policy-bound mission is always guarded: the verdict leans on the integrity
+  // grade, so trusting an unguarded verifier would let a tampered pass score PASS.
+  if (policy) guard = true;
+  await ensureStore();
+  await mkdir(OUTCOMES_DIR, { recursive: true });
+
+  // Per-mission hard cap: override the gateway's budget env for the duration of
+  // THIS run so only this mission's spend counts against capUsd, then restore.
+  // The gateway reads readBudget()/budgetWindowMs() per request, so this reuses
+  // the existing budget_guard 429 enforcement with no new budget code.
+  const prevBudgetEnv = process.env.AIM_DAILY_BUDGET_USD;
+  const prevWindowEnv = process.env.AIM_BUDGET_WINDOW;
+  if (capUsd != null) {
+    process.env.AIM_DAILY_BUDGET_USD = String(capUsd);
+    process.env.AIM_BUDGET_WINDOW = "session";
+  }
+  try {
+    return await runOutcomeInner();
+  } finally {
+    if (capUsd != null) {
+      if (prevBudgetEnv === undefined) delete process.env.AIM_DAILY_BUDGET_USD;
+      else process.env.AIM_DAILY_BUDGET_USD = prevBudgetEnv;
+      if (prevWindowEnv === undefined) delete process.env.AIM_BUDGET_WINDOW;
+      else process.env.AIM_BUDGET_WINDOW = prevWindowEnv;
+    }
+  }
+
+  async function runOutcomeInner() {
+
+  const windowMs = budgetWindowMs();
+  const spentBefore = (await readGatewaySummary({ windowMs })).estimatedCostUsd;
+  const cap = readBudget();
+  // Snapshot the ledger length BEFORE the run so we attribute events to this run
+  // by log position, not wall clock. Two runs in the same second would otherwise
+  // overlap a time window and double-count each other's calls and models.
+  const eventCountBefore = (await readGatewayEvents()).length;
+
+  // Guard: freeze a Task Contract BEFORE the agent touches anything. Verifying
+  // the result is meaningless if the agent can edit the verifier; so we hash the
+  // verifier files, snapshot package scripts, record the baseline commit, and
+  // confirm the task actually fails today (a pass on an already-green tree
+  // proves nothing the agent did). cwd is known only after the mission resolves
+  // it, so we resolve it the same way runMission does.
+  const guardCwd = process.cwd();
+  const contract = guard ? await freezeTaskContract({ cwd: guardCwd, verify, protect, allow }) : null;
+
+  // 1. Run the agent through the cap gateway so the spend is real and recorded.
+  const mission = await runMission({ command, label: label ?? "outcome", autoGateway: true, mock });
+  const missionRecord = await readMission(mission.id);
+
+  // 2. Cost actually spent on this run, measured from the gateway ledger delta.
+  const summaryAfter = await readGatewaySummary({ windowMs });
+  const spentAfter = summaryAfter.estimatedCostUsd;
+  const actualCostUsd = Number(Math.max(0, spentAfter - spentBefore).toFixed(6));
+  // Models/calls the run actually hit: exactly the events appended during it.
+  const runEvents = (await readGatewayEvents()).slice(eventCountBefore);
+  const models = [...new Set(runEvents.map((e) => e.model).filter((m) => m && m !== "unknown"))];
+  const llmCalls = runEvents.filter((e) => e.status >= 200 && e.status < 300 && e.usage).length;
+  // Did the gateway block a call to stay under the cap? A budget_guard 429 means
+  // the mission hit its ceiling - a policy-graded mission BLOCKS on it.
+  const budgetGuardTripped = runEvents.some((e) => e.status === 429 && e.truth === "budget_guard");
+  const costTruth = llmCalls > 0
+    ? "calculated_from_provider_usage_and_sourced_price_table"
+    : "no_llm_calls_through_gateway";
+
+  // 3. Verify: run the user's verification command. Its exit code is the oracle.
+  const verifyResult = await runShell(verify, missionRecord.cwd);
+  const verifyPassed = verifyResult.exitCode === 0;
+
+  // 4. Did the agent actually change anything? A pass on a no-op is not delivery.
+  const changedFiles = missionRecord.diffEvidence.changedFiles;
+  const producedDiff = changedFiles.length > 0;
+  const outcome = verifyPassed ? "VERIFIED" : "UNVERIFIED";
+  const verifiedOutcomeCostUsd = verifyPassed ? actualCostUsd : null;
+
+  // 5. Guard: did the agent pass the check FAIRLY? Re-hash the verifier, look
+  // for tampering, and grade the verification's trustworthiness on a 4-level
+  // scale instead of a binary pass.
+  const integrity = guard
+    ? await checkVerificationIntegrity({ contract, cwd: missionRecord.cwd, changedFiles, verifyPassed, verify })
+    : null;
+
+  const receipt = {
+    schema: policy ? "runcap.outcome-receipt/v0.3" : (guard ? "runcap.outcome-receipt/v0.2" : "runcap.outcome-receipt/v0.1"),
+    id: mission.id,
+    generatedAt: new Date().toISOString(),
+    task,
+    agent: { command, program: command[0] },
+    models,
+    verify: {
+      command: verify,
+      exitCode: verifyResult.exitCode,
+      passed: verifyPassed,
+      truth: "observed_exit_code"
+    },
+    cost: {
+      plannedCapUsd: cap,
+      actualCostUsd,
+      verifiedOutcomeCostUsd,
+      moneySpentWithoutVerifiedDeliveryUsd: verifyPassed ? 0 : actualCostUsd,
+      llmCalls,
+      budgetGuardTripped,
+      truth: costTruth
+    },
+    work: {
+      agentExitCode: missionRecord.exitCode,
+      agentDurationMs: missionRecord.durationMs,
+      verifyDurationMs: verifyResult.durationMs,
+      changedFiles,
+      changedFileCount: changedFiles.length,
+      producedDiff,
+      retries: { value: null, truth: "not_tracked_v0.1" },
+      truth: "observed_from_git_and_exit_code"
+    },
+    outcome,
+    verificationIntegrity: integrity,
+    costScope: {
+      measured: "observed_llm_calls_through_gateway_only",
+      note: "Verified Outcome Cost is the LLM spend that bought the result. It does NOT include subscriptions, CI minutes, sandbox compute, or human review time. For full agent economics, divide total spend across N attempts by strongly-verified outcomes (Expected Verified Outcome Cost, needs N>=5)."
+    },
+    missionReport: path.join(MISSIONS_DIR, mission.id, "report.md")
+  };
+
+  // Policy-bound mission: stamp the receipt with who/what + the rules (and the
+  // hash of the exact policy text), then grade an overall PASS/BLOCKED verdict.
+  // The hash lets a reviewer confirm which rules were in force for this run.
+  if (policy) {
+    receipt.policy = { ...policyMeta(policy), ...evaluatePolicyVerdict(receipt, policy.policy) };
+  }
+
+  const outcomeDir = path.join(OUTCOMES_DIR, mission.id);
+  await mkdir(outcomeDir, { recursive: true });
+  await writeFile(path.join(outcomeDir, "receipt.json"), JSON.stringify(receipt, null, 2));
+  await writeFile(path.join(outcomeDir, "receipt.md"), formatOutcomeReceipt(receipt));
+  await writeFile(path.join(OUTCOMES_DIR, "latest"), mission.id);
+
+  return { id: mission.id, receipt, summary: formatOutcomeReceipt(receipt) };
+  }
+}
+
+// Run a verification command string through the shell so operators can write
+// natural pipelines like "npm test && npm run build". Output streams live.
+async 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 await 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", (chunk) => { const t = chunk.toString(); stdout += t; process.stdout.write(t); });
+    child.stderr?.on("data", (chunk) => { const t = chunk.toString(); stderr += t; process.stderr.write(t); });
+    child.on("error", (error) => resolve({ stdout, stderr: stderr + `\n${error.message}`, exitCode: 127, durationMs: Date.now() - started }));
+    child.on("close", (exitCode) => resolve({ stdout, stderr, exitCode: exitCode ?? 1, durationMs: Date.now() - started }));
+  });
+}
+
+// --- Verification Integrity (runcap outcome --guard) ---------------------
+// The honest hole in outcome v0.1: it trusts the verifier. An agent can turn a
+// test green without doing the work - delete the test, rewrite the assertion,
+// repoint the `npm test` script, disable strict mode, mock the real API. The
+// guard freezes a contract before the run and re-checks it after, so a pass is
+// graded on a 4-level trust scale instead of a binary VERIFIED.
+
+const DEFAULT_PROTECTED_GLOBS = [
+  /(^|\/)[^/]*\.test\.[mc]?[jt]sx?$/,
+  /(^|\/)[^/]*\.spec\.[mc]?[jt]sx?$/,
+  /(^|\/)__tests__\//,
+  /(^|\/)tests?\//,
+  /(^|\/)package\.json$/,
+  /(^|\/)tsconfig[^/]*\.json$/,
+  /(^|\/)jest\.config\./,
+  /(^|\/)vitest\.config\./
+];
+
+// Pull the concrete file paths a verify command names so we can hash them and
+// detect edits. We can't statically parse an arbitrary shell pipeline, so we
+// take a deliberately simple, honest approach: any whitespace token that looks
+// like a path to an existing file is treated as a verifier file.
+function verifierFilesFrom(verify, cwd) {
+  const tokens = verify.split(/\s+/).filter(Boolean);
+  const files = [];
+  for (const raw of tokens) {
+    const tok = raw.replace(/^["']|["']$/g, "");
+    if (!/[./]/.test(tok)) continue;
+    const abs = path.isAbsolute(tok) ? tok : path.join(cwd, tok);
+    if (existsSync(abs) && !files.includes(abs)) files.push(abs);
+  }
+  return files;
+}
+
+function hashFile(absPath) {
+  try {
+    return createHash("sha256").update(readFileSync(absPath)).digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+function packageScriptsOf(cwd) {
+  const pkg = readOptionalSync(path.join(cwd, "package.json"));
+  if (!pkg) return null;
+  const parsed = safeJson(pkg);
+  return parsed && parsed.scripts ? parsed.scripts : {};
+}
+
+function readOptionalSync(file) {
+  try {
+    return readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+async function freezeTaskContract({ cwd, verify, protect, allow }) {
+  const head = await git(["rev-parse", "HEAD"], cwd);
+  const baselineCommit = head.error ? null : head.text;
+  const verifierFiles = verifierFilesFrom(verify, cwd).map((abs) => ({
+    path: path.relative(cwd, abs),
+    sha256: hashFile(abs)
+  }));
+  const packageScripts = packageScriptsOf(cwd);
+
+  // Does the task actually fail today? A verify that already passes on the
+  // baseline tree proves the agent did nothing. Run it before the agent moves.
+  const baseline = await runShell(verify, cwd);
+
+  return {
+    schema: "runcap.task-contract/v0.1",
+    frozenAt: new Date().toISOString(),
+    cwd,
+    baselineCommit,
+    verifyCommand: verify,
+    verifierFiles,
+    packageScripts,
+    protectedPaths: protect,
+    allowedPaths: allow,
+    baselineVerify: { exitCode: baseline.exitCode, passed: baseline.exitCode === 0 }
+  };
+}
+
+function isProtected(relPath, extraProtected) {
+  if (extraProtected.some((p) => relPath === p || relPath.startsWith(p.replace(/\/?$/, "/")))) return true;
+  return DEFAULT_PROTECTED_GLOBS.some((re) => re.test(relPath));
+}
+
+function withinAllowed(relPath, allowed) {
+  if (allowed.length === 0) return true;
+  return allowed.some((a) => relPath === a || relPath.startsWith(a.replace(/\/?$/, "/")));
+}
+
+async function checkVerificationIntegrity({ contract, cwd, changedFiles, verifyPassed, verify }) {
+  const violations = [];
+  const checks = [];
+  const record = (id, ok, detail) => { checks.push({ id, ok, detail, truth: "calculated_from_observed_state" }); if (!ok) violations.push(id); };
+
+  // 1. Verifier files unchanged (hash match).
+  for (const vf of contract.verifierFiles) {
+    const now = hashFile(path.join(cwd, vf.path));
+    if (vf.sha256 === null) { record(`verifier_file_unreadable:${vf.path}`, true, "could not hash at freeze time"); continue; }
+    record(`verifier_file_unchanged:${vf.path}`, now === vf.sha256, now === null ? "verifier file deleted after run" : (now === vf.sha256 ? "hash matches" : "verifier file edited after run"));
+  }
+
+  // 2. package.json scripts unchanged (can't repoint `npm test` at `true`).
+  if (contract.packageScripts) {
+    const after = packageScriptsOf(cwd);
+    const same = JSON.stringify(after) === JSON.stringify(contract.packageScripts);
+    record("package_scripts_unchanged", same, same ? "scripts identical" : "package.json scripts changed during run");
+  }
+
+  // 3. No protected/test file deleted, and changes stay within allowed scope.
+  for (const f of changedFiles) {
+    if (isProtected(f, contract.protectedPaths)) {
+      record(`protected_path_untouched:${f}`, false, "agent modified a protected/test/config path");
+    }
+    if (!withinAllowed(f, contract.allowedPaths)) {
+      record(`within_allowed_scope:${f}`, false, "change is outside the allowed paths");
+    }
+  }
+
+  // 4. The task actually failed before the run (otherwise a pass is meaningless).
+  const baseFailed = contract.baselineVerify && contract.baselineVerify.passed === false;
+  record("baseline_failed_before_run", !!baseFailed, baseFailed ? "verify failed on the baseline tree (the task was real)" : "verify already passed before the agent ran - the pass proves nothing");
+
+  // 5. Re-run verify against the baseline commit in a clean checkout: does the
+  // pass survive without the agent's uncommitted working-tree state? This
+  // catches a green that only exists because of untracked/uncommitted hacks.
+  let cleanRoom = { ran: false, passed: null, detail: "skipped (no baseline commit)" };
+  if (verifyPassed && contract.baselineCommit) {
+    cleanRoom = await verifyInCleanWorktree({ cwd, baselineCommit: contract.baselineCommit, verify, changedFiles });
+    record("verify_survives_clean_checkout", cleanRoom.passed === true, cleanRoom.detail);
+  }
+
+  // Grade. Tampering with the verifier is categorically worse than a weak pass:
+  // it means the green light itself is untrustworthy.
+  const verifierTampered = checks.some((c) => !c.ok && (c.id.startsWith("verifier_file_unchanged:") || c.id.startsWith("protected_path_untouched:") || c.id === "package_scripts_unchanged"));
+
+  let status;
+  if (!verifyPassed) {
+    status = "UNVERIFIED";
+  } else if (verifierTampered) {
+    status = "VERIFIER_COMPROMISED";
+  } else if (violations.length === 0) {
+    status = "VERIFIED_STRONG";
+  } else {
+    status = "VERIFIED_WEAK";
+  }
+
+  const reason = {
+    UNVERIFIED: "Verification did not pass.",
+    VERIFIER_COMPROMISED: "Verification passed, but the verifier itself was modified during the run. The green light cannot be trusted.",
+    VERIFIED_STRONG: "Verification passed and the verifier was untouched: tests/scripts unchanged, changes in scope, the task really failed before, and the pass survives a clean checkout.",
+    VERIFIED_WEAK: "Verification passed and the verifier was untouched, but at least one strong condition was not met (e.g. baseline failure not reproduced, or pass not reproduced in a clean checkout)."
+  }[status];
+
+  return {
+    schema: "runcap.verification-integrity/v0.1",
+    status,
+    reason,
+    contract: {
+      baselineCommit: contract.baselineCommit,
+      verifierFiles: contract.verifierFiles.map((f) => f.path),
+      protectedPaths: contract.protectedPaths,
+      allowedPaths: contract.allowedPaths,
+      baselineVerifyPassed: contract.baselineVerify ? contract.baselineVerify.passed : null
+    },
+    cleanRoom,
+    checks,
+    violations
+  };
+}
+
+// Re-run the verify command from the baseline commit in a throwaway worktree,
+// then copy in only the agent's changed files. If the pass came from real edits
+// to allowed files it survives; if it came from uncommitted local junk it dies.
+async function verifyInCleanWorktree({ cwd, baselineCommit, verify, changedFiles }) {
+  const tmpBase = path.join(STORE_DIR, "cleanroom");
+  await mkdir(tmpBase, { recursive: true });
+  const wt = path.join(tmpBase, `wt-${createHash("sha1").update(`${baselineCommit}${Date.now()}${Math.random()}`).digest("hex").slice(0, 8)}`);
+  const add = await git(["worktree", "add", "--detach", wt, baselineCommit], cwd);
+  if (add.error) {
+    return { ran: false, passed: null, detail: `clean-worktree check skipped: ${add.error}` };
+  }
+  try {
+    // Bring the agent's changed files into the clean baseline so we test the
+    // work, not the agent's whole dirty tree.
+    for (const rel of changedFiles) {
+      const src = path.join(cwd, rel);
+      const dst = path.join(wt, rel);
+      try {
+        await mkdir(path.dirname(dst), { recursive: true });
+        await writeFile(dst, await readFile(src));
+      } catch { /* deleted/binary file: leave baseline version */ }
+    }
+    const result = await runShell(verify, wt);
+    return {
+      ran: true,
+      passed: result.exitCode === 0,
+      detail: result.exitCode === 0
+        ? "pass reproduced from baseline + changed files in a clean checkout"
+        : "pass did NOT reproduce in a clean checkout (green depended on uncommitted local state)"
+    };
+  } finally {
+    await git(["worktree", "remove", "--force", wt], cwd);
+  }
+}
+
+function formatOutcomeReceipt(r) {
+  const usd = (n) => (n === null || n === undefined ? "n/a" : fmtUsd(n));
+  const lines = [
+    "Runcap outcome receipt",
+    "======================",
+    `Task:            ${r.task}`,
+    `Agent:           ${r.agent.command.join(" ")}`,
+    `Model(s):        ${r.models.length ? r.models.join(", ") : "none (no LLM calls through gateway)"}`,
+    `Planned cap:     ${r.cost.plannedCapUsd === null ? "no cap set" : usd(r.cost.plannedCapUsd)}`,
+    `Actual cost:     ${usd(r.cost.actualCostUsd)}  (${r.cost.llmCalls} priced LLM call(s), truth: ${r.cost.truth})`,
+    `Agent runtime:   ${(r.work.agentDurationMs / 1000).toFixed(1)}s   exit ${r.work.agentExitCode}`,
+    `Verify runtime:  ${(r.work.verifyDurationMs / 1000).toFixed(1)}s`,
+    `Retries:         not tracked (v0.1)`,
+    `Changed files:   ${r.work.changedFileCount}${r.work.changedFileCount ? " (" + r.work.changedFiles.join(", ") + ")" : ""}`,
+    `Verification:    \`${r.verify.command}\``,
+    `Verify result:   ${r.verify.passed ? "PASSED" : "FAILED"}  (exit ${r.verify.exitCode}, truth: observed)`,
+    "",
+    `Outcome:         ${r.outcome}`
+  ];
+  if (r.outcome === "VERIFIED") {
+    lines.push(`Verified Outcome Cost: ${usd(r.cost.verifiedOutcomeCostUsd)}  (money that bought a verified result)`);
+  } else {
+    lines.push(`Verified Outcome Cost: N/A  (verification did not pass)`);
+    lines.push(`Money spent without verified delivery: ${usd(r.cost.moneySpentWithoutVerifiedDeliveryUsd)}`);
+  }
+  if (r.verificationIntegrity) {
+    const vi = r.verificationIntegrity;
+    lines.push("");
+    lines.push(`Verification integrity: ${vi.status}`);
+    lines.push(`  ${vi.reason}`);
+    if (vi.violations.length) {
+      lines.push(`  Failed checks (${vi.violations.length}):`);
+      for (const c of vi.checks.filter((x) => !x.ok)) lines.push(`    - ${c.id}: ${c.detail}`);
+    }
+    if (vi.cleanRoom && vi.cleanRoom.ran) lines.push(`  Clean-checkout re-verify: ${vi.cleanRoom.passed ? "PASSED" : "FAILED"} (${vi.cleanRoom.detail})`);
+  }
+  if (r.policy) {
+    lines.push("");
+    lines.push(...formatPolicyBlock(r.policy));
+  }
+  return lines.join("\n") + "\n";
+}
+
+export async function latestOutcomeId() {
+  try {
+    return (await readFile(path.join(OUTCOMES_DIR, "latest"), "utf8")).trim();
+  } catch {
+    return null;
+  }
+}
+
+export async function renderOutcome(id) {
+  const file = path.join(OUTCOMES_DIR, id, "receipt.md");
+  return (await readFile(file, "utf8"));
+}
+
 export async function latestMissionId() {
   try {
     return (await readFile(path.join(STORE_DIR, "latest"), "utf8")).trim();
@@ -1599,7 +2034,12 @@ const MODEL_PRICES = [
   { match: ["gpt-4.1-mini"], inputPerMillion: 0.4, outputPerMillion: 1.6, cacheReadPerMillion: 0.1, provider: "openai" },
   { match: ["gpt-4.1"], inputPerMillion: 2, outputPerMillion: 8, cacheReadPerMillion: 0.5, provider: "openai" },
   { match: ["gpt-4o-mini"], inputPerMillion: 0.15, outputPerMillion: 0.6, cacheReadPerMillion: 0.075, provider: "openai" },
-  { match: ["gpt-4o"], inputPerMillion: 2.5, outputPerMillion: 10, cacheReadPerMillion: 1.25, provider: "openai" }
+  { match: ["gpt-4o"], inputPerMillion: 2.5, outputPerMillion: 10, cacheReadPerMillion: 1.25, provider: "openai" },
+  // DeepSeek (api-docs.deepseek.com/quick_start/pricing). OpenAI-compatible API,
+  // so the same gateway prices and caps it with no extra setup. deepseek-chat /
+  // deepseek-reasoner are the non-thinking / thinking modes of deepseek-v4-flash.
+  { match: ["deepseek-v4-pro"], inputPerMillion: 0.435, outputPerMillion: 0.87, cacheReadPerMillion: 0.003625, provider: "deepseek" },
+  { match: ["deepseek-v4-flash", "deepseek-chat", "deepseek-reasoner", "deepseek"], inputPerMillion: 0.14, outputPerMillion: 0.28, cacheReadPerMillion: 0.0028, provider: "deepseek" }
 ];
 
 function estimateApiCost(usage, model) {

package/src/policy.mjs

@@ -0,0 +1,208 @@
+// Policy-bound missions (runcap mission / policy / ci).
+//
+// A mission's rules are declared once in `.runcap/mission.yaml` (or .yml/.json),
+// enforced during the run by the existing gateway cap + verification guard, and
+// graded into a PASS/BLOCKED verdict a GitHub Action turns into a red/green PR
+// check. This module is deliberately pure: it parses the policy, validates it,
+// and grades an ALREADY-BUILT outcome receipt against it. It imports only
+// js-yaml + node builtins and never imports mission-control, so there is no
+// import cycle (mission-control imports FROM here, one direction).
+
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import yaml from "js-yaml";
+
+const POLICY_FILENAMES = ["mission.yaml", "mission.yml", "mission.json"];
+
+// Find and parse the policy. Precedence: an explicit path, else the first of
+// .runcap/mission.{yaml,yml,json} that exists. Returns null when none is found
+// so callers can decide whether a missing policy is an error.
+export function loadPolicy(cwd = process.cwd(), explicitPath) {
+  let source = null;
+  if (explicitPath) {
+    source = path.isAbsolute(explicitPath) ? explicitPath : path.join(cwd, explicitPath);
+    if (!existsSync(source)) throw new Error(`Policy file not found: ${explicitPath}`);
+  } else {
+    for (const name of POLICY_FILENAMES) {
+      const candidate = path.join(cwd, ".runcap", name);
+      if (existsSync(candidate)) { source = candidate; break; }
+    }
+  }
+  if (!source) return null;
+
+  const raw = readFileSync(source, "utf8");
+  let policy;
+  if (source.endsWith(".json")) {
+    // .json fallback uses native JSON.parse so the zero-config path needs no parser.
+    policy = JSON.parse(raw);
+  } else {
+    policy = yaml.load(raw);
+  }
+  if (!policy || typeof policy !== "object") {
+    throw new Error(`Policy file ${path.basename(source)} did not parse to an object.`);
+  }
+  return {
+    policy,
+    raw,
+    hash: createHash("sha256").update(raw).digest("hex"),
+    source
+  };
+}
+
+// Validate the policy shape. Errors block the mission; warnings are advisory.
+export function validatePolicy(policy) {
+  const errors = [];
+  const warnings = [];
+  if (!policy || typeof policy !== "object") {
+    return { ok: false, errors: ["Policy is empty or not an object."], warnings };
+  }
+
+  if (policy.version !== "v1") {
+    errors.push(`version must be "v1" (got ${JSON.stringify(policy.version)}).`);
+  }
+
+  const mission = policy.mission ?? {};
+  if (!mission.name || !String(mission.name).trim()) {
+    errors.push("mission.name is required.");
+  }
+
+  const verification = policy.verification ?? {};
+  if (!verification.command || !String(verification.command).trim()) {
+    errors.push("verification.command is required.");
+  }
+  if (verification.guard && !["strict", "off"].includes(verification.guard)) {
+    errors.push(`verification.guard must be "strict" or "off" (got ${JSON.stringify(verification.guard)}).`);
+  }
+
+  const budget = policy.budget ?? {};
+  const limit = budget.mission_hard_limit_usd;
+  if (!(typeof limit === "number" && Number.isFinite(limit) && limit > 0)) {
+    errors.push("budget.mission_hard_limit_usd is required and must be a positive number.");
+  }
+  if (budget.max_llm_calls !== undefined && !(Number.isFinite(budget.max_llm_calls) && budget.max_llm_calls > 0)) {
+    errors.push("budget.max_llm_calls, when set, must be a positive number.");
+  }
+  if (budget.max_runtime_minutes !== undefined && !(Number.isFinite(budget.max_runtime_minutes) && budget.max_runtime_minutes > 0)) {
+    errors.push("budget.max_runtime_minutes, when set, must be a positive number.");
+  }
+
+  const identity = policy.identity ?? {};
+  if (!identity.project && !identity.team) {
+    warnings.push("identity has no project or team - the receipt will not carry org attribution.");
+  }
+  if (!Array.isArray(verification.allow) || verification.allow.length === 0) {
+    warnings.push("verification.allow is empty - any changed path passes the scope check. Declare the paths a legitimate fix should touch.");
+  }
+  if (verification.guard === "off") {
+    warnings.push("verification.guard is off - a tampered verifier will NOT be caught.");
+  }
+
+  return { ok: errors.length === 0, errors, warnings };
+}
+
+// Grade an already-built outcome receipt against the policy. Pure: no I/O.
+// BLOCK is the conservative verdict - any single failing condition blocks the
+// mission so a reviewer never has to read past the verdict to know it is unsafe.
+export function evaluatePolicyVerdict(receipt, policy) {
+  const reasons = [];
+  const budget = policy?.budget ?? {};
+  const limit = budget.mission_hard_limit_usd;
+
+  const integrity = receipt.verificationIntegrity;
+  if (integrity && integrity.status === "VERIFIER_COMPROMISED") {
+    const tampered = (integrity.violations ?? []).filter((v) =>
+      v.startsWith("verifier_file_unchanged:") ||
+      v === "package_scripts_unchanged" ||
+      v.startsWith("protected_path_untouched:"));
+    reasons.push(`VERIFIER_COMPROMISED: the agent changed protected verification evidence${tampered.length ? " (" + tampered.join(", ") + ")" : ""}.`);
+  }
+
+  if (receipt.outcome === "UNVERIFIED") {
+    reasons.push("UNVERIFIED: verification did not pass.");
+  }
+
+  const scopeViolations = (integrity?.violations ?? []).filter((v) => v.startsWith("within_allowed_scope:"));
+  if (scopeViolations.length) {
+    reasons.push(`Out of allowed scope: ${scopeViolations.map((v) => v.replace("within_allowed_scope:", "")).join(", ")}.`);
+  }
+
+  const cost = receipt.cost ?? {};
+  if (typeof limit === "number" && typeof cost.actualCostUsd === "number" && cost.actualCostUsd > limit) {
+    reasons.push(`Over budget: $${cost.actualCostUsd} spent > $${limit} mission hard limit.`);
+  }
+  if (cost.budgetGuardTripped) {
+    reasons.push("Budget guard tripped: the gateway blocked a call to stay under the mission hard limit.");
+  }
+
+  if (Number.isFinite(budget.max_llm_calls) && typeof cost.llmCalls === "number" && cost.llmCalls > budget.max_llm_calls) {
+    reasons.push(`Too many LLM calls: ${cost.llmCalls} > max_llm_calls ${budget.max_llm_calls}.`);
+  }
+
+  const work = receipt.work ?? {};
+  if (Number.isFinite(budget.max_runtime_minutes) && typeof work.agentDurationMs === "number") {
+    const limitMs = budget.max_runtime_minutes * 60_000;
+    if (work.agentDurationMs > limitMs) {
+      reasons.push(`Over time budget: ${(work.agentDurationMs / 1000).toFixed(1)}s > max_runtime_minutes ${budget.max_runtime_minutes}.`);
+    }
+  }
+
+  return {
+    verdict: reasons.length === 0 ? "PASS" : "BLOCKED",
+    reasons,
+    truth: "calculated_from_policy_and_observed_receipt"
+  };
+}
+
+// The compact policy block embedded in the receipt: who/what + the rules and
+// the hash of the exact policy text that graded the run, so a reviewer can
+// confirm which rules were in force.
+export function policyMeta(policyResult) {
+  const p = policyResult.policy ?? {};
+  const identity = p.identity ?? {};
+  const mission = p.mission ?? {};
+  const budget = p.budget ?? {};
+  const verification = p.verification ?? {};
+  return {
+    schema: "runcap.policy/v1",
+    hash: policyResult.hash,
+    source: policyResult.source ? path.basename(policyResult.source) : null,
+    identity: {
+      project: identity.project ?? null,
+      team: identity.team ?? null,
+      cost_center: identity.cost_center ?? null,
+      owner: identity.owner ?? null
+    },
+    mission: { name: mission.name ?? null, task_class: mission.task_class ?? null },
+    limits: {
+      mission_hard_limit_usd: budget.mission_hard_limit_usd ?? null,
+      max_llm_calls: budget.max_llm_calls ?? null,
+      max_runtime_minutes: budget.max_runtime_minutes ?? null,
+      guard: verification.guard ?? "strict"
+    }
+  };
+}
+
+// Markdown lines for the printed receipt and the PR summary. Accepts the
+// `receipt.policy` block (policyMeta + verdict + reasons merged).
+export function formatPolicyBlock(receiptPolicy) {
+  if (!receiptPolicy) return [];
+  const id = receiptPolicy.identity ?? {};
+  const limits = receiptPolicy.limits ?? {};
+  const who = [id.project && `project ${id.project}`, id.team && `team ${id.team}`, id.cost_center && `cost center ${id.cost_center}`]
+    .filter(Boolean).join(" / ") || "no org attribution";
+  const lines = [
+    `Mission policy:  ${receiptPolicy.mission?.name ?? "(unnamed)"}${receiptPolicy.mission?.task_class ? " [" + receiptPolicy.mission.task_class + "]" : ""}`,
+    `  ${who}`,
+    `  Hard limit: ${limits.mission_hard_limit_usd === null || limits.mission_hard_limit_usd === undefined ? "none" : "$" + Number(limits.mission_hard_limit_usd).toFixed(2)}` +
+      `${limits.max_llm_calls ? ", max calls " + limits.max_llm_calls : ""}` +
+      `${limits.max_runtime_minutes ? ", max " + limits.max_runtime_minutes + " min" : ""}`,
+    `  Policy hash: ${receiptPolicy.hash}`,
+    `Mission verdict: ${receiptPolicy.verdict}`
+  ];
+  if (Array.isArray(receiptPolicy.reasons) && receiptPolicy.reasons.length) {
+    lines.push(`  Blocked because:`);
+    for (const r of receiptPolicy.reasons) lines.push(`    - ${r}`);
+  }
+  return lines;
+}