runcap 0.3.0 → 0.5.0

package/src/mission-control.mjs

@@ -7,11 +7,13 @@ import path from "node:path";
 import process from "node:process";
 import { syncRun } from "./cloud.mjs";
 import { sendAlert } from "./alerts.mjs";
-import { compressRequestBody, estimateTokens, requestShapeText, detectLoop } from "./compressor.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();
@@ -528,6 +963,13 @@ function createGatewayServer({ port = 8792, mock = false, upstream = {} } = {})
   // but-not-identical turns, which plain hashing never catches.
   const loopEnabled = (process.env.AIM_LOOP_DETECT ?? "on").toLowerCase() !== "off";
   const shapeHistory = [];
+  // Response signatures aligned with shapeHistory (the observation each prior
+  // prompt produced). Lets the loop detector tell circling from convergence:
+  // similar prompts only count as a loop when the response did not move either.
+  // Each entry is a mutable holder { sig } so the slot for an in-flight turn can
+  // be captured by reference and filled once its upstream response returns, even
+  // if concurrent turns push new entries or shift() trims the array meanwhile.
+  const responseHistory = [];
   const SHAPE_HISTORY_MAX = 12;
   const server = http.createServer(async (request, response) => {
     const started = Date.now();
@@ -551,15 +993,32 @@ function createGatewayServer({ port = 8792, mock = false, upstream = {} } = {})
 
       const bodyText = await readRequestBody(request);
       const requestBody = safeJson(bodyText) ?? {};
-      // Loop signal: compare this request's shape against the recent run.
+      // Loop signal: compare this request's shape against the recent run. The
+      // response signatures gate prompt-similarity so a converging run (similar
+      // prompts, but the error/output is changing) is not flagged as circling.
       let loop = null;
+      let currentShape = null;
+      let responseSlot = null; // holder for THIS turn's response signature
       if (loopEnabled) {
         const shape = requestShapeText(requestBody);
         if (shape) {
-          const result = detectLoop(shape, shapeHistory);
-          loop = { looping: result.looping, repeats: result.repeats, similarity: result.similarity, truth: "calculated" };
+          currentShape = shape;
+          const result = detectLoop(shape, shapeHistory, {
+            responseSignatures: responseHistory.map((h) => h.sig),
+            currentResponseSignature: responseHistory.length ? responseHistory[responseHistory.length - 1].sig : null
+          });
+          loop = {
+            looping: result.looping,
+            repeats: result.repeats,
+            similarity: result.similarity,
+            responseMoved: result.responseMoved,
+            truth: "calculated"
+          };
           shapeHistory.push(shape);
+          responseSlot = { sig: "" }; // filled by reference once upstream returns
+          responseHistory.push(responseSlot);
           if (shapeHistory.length > SHAPE_HISTORY_MAX) shapeHistory.shift();
+          if (responseHistory.length > SHAPE_HISTORY_MAX) responseHistory.shift();
         }
       }
       const budget = readBudget();
@@ -639,6 +1098,8 @@ function createGatewayServer({ port = 8792, mock = false, upstream = {} } = {})
       if (gatewayMode === "mock") {
         const responseBody = mockCompletion(requestBody, url.pathname);
         const responseText = JSON.stringify(responseBody);
+        // Record before unblocking the client so a concurrent next turn sees it.
+        if (responseSlot) responseSlot.sig = responseSignature(responseBody);
         send(response, 200, responseText, "application/json; charset=utf-8");
         await appendGatewayEvent({
           at: new Date().toISOString(),
@@ -685,13 +1146,14 @@ function createGatewayServer({ port = 8792, mock = false, upstream = {} } = {})
         body: forwardBody
       });
       const responseText = await upstreamResponse.text();
+      const responseBody = safeJson(responseText) ?? {};
+      // Record before unblocking the client so a concurrent next turn sees it.
+      if (responseSlot) responseSlot.sig = responseSignature(responseBody);
       response.writeHead(upstreamResponse.status, {
         "content-type": upstreamResponse.headers.get("content-type") ?? "application/json",
         "cache-control": "no-store"
       });
       response.end(responseText);
-
-      const responseBody = safeJson(responseText) ?? {};
       await appendGatewayEvent({
         at: new Date().toISOString(),
         path: url.pathname,
@@ -761,7 +1223,7 @@ export async function startGateway({ port = 8792, mock = false } = {}) {
 // it down afterward. Upstream is pinned from the CURRENT env before the child's
 // base URLs are rewritten, so the gateway proxies to the real provider, not to
 // itself.
-async function startEphemeralGateway({ mock = false } = {}) {
+export async function startEphemeralGateway({ mock = false } = {}) {
   await ensureStore();
   const upstream = {
     openaiKey: process.env.AIM_UPSTREAM_API_KEY ?? process.env.OPENAI_API_KEY,
@@ -1572,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) {