runcap 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runcap",
-  "version": "0.3.0",
+  "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.",
   "license": "MIT",
   "type": "module",
@@ -45,7 +45,7 @@
     "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/validate-demo.mjs",
+    "test": "node ./scripts/delta-test.mjs && node ./scripts/loop-test.mjs && node ./scripts/loop-e2e.mjs && node ./scripts/validate-demo.mjs",
     "test:delta": "node ./scripts/delta-test.mjs",
     "test:loop": "node ./scripts/loop-test.mjs",
     "status": "node ./bin/runcap.mjs status",

package/scripts/loop-e2e.mjs

@@ -0,0 +1,137 @@
+// End-to-end proof that the response-side loop gate works through the REAL
+// gateway over HTTP, not just in unit tests. We stand up a tiny local "upstream"
+// that returns a caller-chosen error string, point the real Runcap gateway at
+// it, and drive near-identical prompts through the wire:
+//   A) error CHANGES each turn (convergence)  -> gateway must NOT flag a loop
+//   B) error STAYS the same each turn (circling) -> gateway MUST flag a loop
+// The gateway records its loop verdict per call in the gateway event log, which
+// we read back to assert the real server behaved correctly.
+//
+// Pure Node, no framework. Exits non-zero on any failure so it can gate CI.
+
+import http from "node:http";
+import os from "node:os";
+import path from "node:path";
+import { mkdtempSync, readFileSync, existsSync } from "node:fs";
+
+// Isolate all gateway state (the .runcap event log lives under cwd) in a
+// throwaway dir so this never touches real data. The gateway writes its event
+// log to ./.runcap, so we chdir into the temp dir before starting it.
+const tmpHome = mkdtempSync(path.join(os.tmpdir(), "runcap-e2e-"));
+process.chdir(tmpHome);
+process.env.AIM_COMPRESS = "off";      // keep the wire bytes predictable
+process.env.AIM_LOOP_DETECT = "on";
+
+// A controllable upstream: returns an OpenAI-shaped completion whose assistant
+// text is whatever error we tell it to via a field in the request body. We use
+// the body (not a header) on purpose: the gateway forwards the request body
+// upstream but rewrites headers, so the body is the channel that actually
+// reaches this stub through the real gateway.
+const upstream = http.createServer((req, res) => {
+  let body = "";
+  req.on("data", (c) => (body += c));
+  req.on("end", () => {
+    let err = "default error";
+    try { err = JSON.parse(body)?.mock_error ?? err; } catch {}
+    const payload = {
+      id: "chatcmpl-stub",
+      object: "chat.completion",
+      created: Math.floor(Date.now() / 1000),
+      model: "stub-model",
+      choices: [{ index: 0, message: { role: "assistant", content: String(err) }, finish_reason: "stop" }],
+      usage: { prompt_tokens: 50, completion_tokens: 10, total_tokens: 60 }
+    };
+    res.writeHead(200, { "content-type": "application/json" });
+    res.end(JSON.stringify(payload));
+  });
+});
+
+async function listen(server, port = 0) {
+  await new Promise((r) => server.listen(port, "127.0.0.1", r));
+  return server.address().port;
+}
+
+let failures = 0;
+function check(name, pass, detail) {
+  if (!pass) failures++;
+  console.log(`${pass ? "PASS" : "FAIL"}  ${name}${detail ? "  — " + detail : ""}`);
+}
+
+const stableTail = [
+  "You are a coding agent. Fix the failing build.",
+  ...Array.from({ length: 40 }, (_, i) => `context line ${i}: prior file content the agent keeps resending`)
+].join("\n");
+
+async function send(port, wording, mockError) {
+  // mock_error rides in the body so it survives the gateway's header rewrite and
+  // reaches the upstream stub, which echoes it back as the assistant response.
+  const body = JSON.stringify({
+    model: "stub-model",
+    mock_error: mockError,
+    messages: [{ role: "user", content: stableTail + "\nLet me try this: " + wording }]
+  });
+  const res = await fetch(`http://127.0.0.1:${port}/v1/chat/completions`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body
+  });
+  await res.text();
+}
+
+function readEvents() {
+  const log = path.join(tmpHome, ".runcap", "gateway-events.jsonl");
+  if (!existsSync(log)) return [];
+  return readFileSync(log, "utf8").trim().split("\n").filter(Boolean).map((l) => JSON.parse(l));
+}
+
+// Loop verdicts accumulate across both scenarios in one shared gateway process
+// (the shape history is per-process), so each scenario asserts against only the
+// events it produced. We snapshot the event count before scenario B.
+
+const run = async () => {
+  const upstreamPort = await listen(upstream);
+  process.env.AIM_UPSTREAM_BASE_URL = `http://127.0.0.1:${upstreamPort}/v1`;
+  process.env.AIM_UPSTREAM_API_KEY = "test-key";
+
+  // Import AFTER env is set so the gateway reads our isolated config.
+  const { startEphemeralGateway } = await import("../src/mission-control.mjs");
+  const gw = await startEphemeralGateway();
+  const gwPort = gw.port;
+
+  // Scenario A: same prompt framing, but the error MOVES every turn (convergence).
+  for (const [w, e] of [
+    ["guard the undefined", "TypeError: cannot read property 'id' of undefined"],
+    ["optional chain", "TypeError: cannot read property 'name' of undefined"],
+    ["default to {}", "ReferenceError: parser is not defined"],
+    ["try/catch", "AssertionError: expected 200 but got 404"]
+  ]) {
+    await send(gwPort, w, e);
+  }
+  const afterA = readEvents();
+  const aFlagged = afterA.filter((ev) => ev.loop && ev.loop.looping).length;
+  check("E2E convergence (moving error) is NOT flagged through real gateway", aFlagged === 0,
+    `loops flagged in scenario A=${aFlagged}`);
+
+  // Scenario B: same prompt framing AND the SAME error every turn (circling).
+  const stuck = "TypeError: cannot read property 'id' of undefined";
+  for (const w of ["attempt one", "attempt two reworded", "attempt three reworded", "attempt four reworded", "attempt five reworded"]) {
+    await send(gwPort, w, stuck);
+  }
+  const afterB = readEvents().slice(afterA.length); // only scenario-B events
+  const bFlagged = afterB.filter((ev) => ev.loop && ev.loop.looping).length;
+  check("E2E circling (stuck error) IS flagged through real gateway", bFlagged > 0,
+    `loops flagged in scenario B=${bFlagged}`);
+
+  await gw.close();
+  upstream.close();
+};
+
+run()
+  .then(() => {
+    console.log("\n" + (failures === 0 ? "ALL LOOP E2E TESTS PASSED" : `${failures} LOOP E2E TEST(S) FAILED`));
+    process.exit(failures === 0 ? 0 : 1);
+  })
+  .catch((e) => {
+    console.error("E2E harness error:", e);
+    process.exit(1);
+  });

package/scripts/loop-test.mjs

@@ -7,7 +7,7 @@
 //
 // Pure Node, no test framework. Exits non-zero on any failure so it can gate CI.
 
-import { detectLoop, requestShapeText } from "../src/compressor.mjs";
+import { detectLoop, requestShapeText, responseSignature } from "../src/compressor.mjs";
 
 let failures = 0;
 function check(name, pass, detail) {
@@ -80,5 +80,49 @@ function attempt(wording) {
     `openai="${openai}" anthropic="${anthropic}"`);
 }
 
+// --- Test 6: response-side gate — similar prompts but a MOVING error is NOT a loop ---
+// The edge case raised on the thread: a converging run also sends near-identical
+// prompts (same files, same framing) while it closes in on the fix. The tell is
+// the observation: if the error/test output changes between turns, that's
+// progress, not circling. Prompts are near-identical here, but each response
+// carries a DIFFERENT error, so the gate must keep it from being flagged.
+{
+  const history = [attempt("try A"), attempt("try B"), attempt("try C")];
+  const current = attempt("try D");
+  const responseSignatures = [
+    "TypeError: cannot read property 'id' of undefined",
+    "TypeError: cannot read property 'name' of undefined",
+    "ReferenceError: parser is not defined"
+  ];
+  const currentResponseSignature = "AssertionError: expected 200 but got 404";
+  const r = detectLoop(current, history, { responseSignatures, currentResponseSignature });
+  check("similar prompts but MOVING error are NOT flagged (convergence)", !r.looping && r.responseMoved,
+    `looping=${r.looping}, repeats=${r.repeats}, responseMoved=${r.responseMoved}`);
+}
+
+// --- Test 7: response-side gate — similar prompts AND a STUCK error IS a loop ---
+// Same near-identical prompts, but the identical error keeps coming back. Now
+// both signals agree the run is circling, so it must still be flagged.
+{
+  const history = [attempt("try A"), attempt("try B"), attempt("try C")];
+  const current = attempt("try D");
+  const sameError = "TypeError: cannot read property 'id' of undefined";
+  const responseSignatures = [sameError, sameError, sameError];
+  const currentResponseSignature = sameError;
+  const r = detectLoop(current, history, { responseSignatures, currentResponseSignature });
+  check("similar prompts AND stuck error ARE flagged as loop", r.looping && !r.responseMoved && r.repeats >= 3,
+    `looping=${r.looping}, repeats=${r.repeats}, responseMoved=${r.responseMoved}`);
+}
+
+// --- Test 8: responseSignature extracts the error/text from both provider shapes ---
+{
+  const openai = responseSignature({ choices: [{ message: { content: "boom: it failed" } }] });
+  const anthropic = responseSignature({ content: [{ type: "text", text: "boom: it failed" }] });
+  const errEnvelope = responseSignature({ error: { message: "rate limited" } });
+  check("responseSignature reads OpenAI, Anthropic, and error shapes",
+    openai === "boom: it failed" && anthropic === "boom: it failed" && errEnvelope === "rate limited",
+    `openai="${openai}" anthropic="${anthropic}" err="${errEnvelope}"`);
+}
+
 console.log("\n" + (failures === 0 ? "ALL LOOP TESTS PASSED" : `${failures} LOOP TEST(S) FAILED`));
 process.exit(failures === 0 ? 0 : 1);

package/scripts/make-demo-svg.mjs

@@ -16,27 +16,28 @@ 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.1 },
-  { t: "Recommended cap:  $10", c: C.ok, at: 1.5 },
-  { t: "", c: C.text, at: 1.6 },
-  { t: "$ ANTHROPIC_BASE_URL=http://127.0.0.1:8792/v1 \\", c: C.prompt, at: 2.2 },
-  { t: "    AIM_DAILY_BUDGET_USD=10 runcap gateway", c: C.prompt, at: 2.6 },
-  { t: "gateway up  ·  compression on  ·  hard cap armed", c: C.dim, at: 3.2 },
-  { t: "", c: C.text, at: 3.3 },
-  { t: "→ request   10,144 tokens", c: C.text, at: 3.9 },
-  { t: "→ compressed 1,260 tokens   (JSON + logs trimmed, prose untouched)", c: C.ok, at: 4.6 },
-  { t: "", c: C.text, at: 4.7 },
-  { t: "You saved $7.40  ·  would have spent $18.40  ·  cap $10", c: C.accent, at: 5.4 },
-  { t: "", c: C.text, at: 5.5 },
-  { t: "→ next call would cross the ceiling", c: C.text, at: 6.1 },
-  { t: "HTTP 429  budget_guard  — run stopped before money left your account", c: C.bad, at: 6.8 }
+  { 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 }
 ];
 
-const W = 920, H = 560;
+const W = 920, 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 = 8.0; // loop length seconds
+const total = 9.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
@@ -46,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, 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: plan, cap, compress, detect loop, stop">
   <defs>
     <linearGradient id="brand" x1="0" y1="0" x2="1" y2="0">
       <stop offset="0" stop-color="#22d3ee"/><stop offset="1" stop-color="#34d399"/>
@@ -64,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 · rescue</text>
+    <text x="100" y="33" fill="#8a8a8a" font-family="'JetBrains Mono',monospace" font-size="14">runcap · estimate · cap · compress · loop · rescue</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/make-linkedin-loop-video.mjs

@@ -0,0 +1,338 @@
+// Renders a LinkedIn-ready MP4 for the Runcap loop-detection post.
+// Narrative: a circling agent looks busy but burns money -> Runcap catches the
+// loop in real time -> proven 37.9% compression -> hard cap stops the run.
+// Output: docs/assets/media/runcap-linkedin-loop-demo.mp4
+// Requires: playwright + ffmpeg available on the machine.
+import { spawnSync } from "node:child_process";
+import { mkdirSync, readdirSync, rmSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { chromium } from "playwright";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const root = resolve(__dirname, "..");
+const outDir = resolve(root, "docs/assets/media");
+const framesDir = "/private/tmp/runcap-linkedin-loop-frames";
+const outFile = join(outDir, "runcap-linkedin-loop-demo.mp4");
+
+const width = 1080;
+const height = 1080;
+const fps = 30;
+const duration = 13;
+const frameCount = fps * duration;
+
+mkdirSync(outDir, { recursive: true });
+mkdirSync(framesDir, { recursive: true });
+for (const file of readdirSync(framesDir)) {
+  if (file.startsWith("frame-") && file.endsWith(".png")) {
+    rmSync(join(framesDir, file));
+  }
+}
+
+const html = `<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8" />
+  <style>
+    * { box-sizing: border-box; }
+    html, body {
+      margin: 0;
+      width: ${width}px;
+      height: ${height}px;
+      overflow: hidden;
+      background: #f4f6fb;
+      font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      color: #f8fafc;
+    }
+    .stage {
+      width: ${width}px;
+      height: ${height}px;
+      padding: 58px;
+      display: grid;
+      place-items: center;
+      background:
+        radial-gradient(circle at 15% 10%, rgba(167, 139, 250, .2), transparent 32%),
+        radial-gradient(circle at 85% 12%, rgba(34, 211, 238, .16), transparent 34%),
+        linear-gradient(135deg, #eef2ff, #f8fafc);
+    }
+    .card {
+      width: 964px;
+      height: 964px;
+      border-radius: 42px;
+      padding: 42px;
+      background: #080b12;
+      box-shadow: 0 36px 90px rgba(15, 23, 42, .25);
+      position: relative;
+      overflow: hidden;
+    }
+    .card::before {
+      content: "";
+      position: absolute;
+      inset: 0;
+      background:
+        radial-gradient(circle at 50% -10%, rgba(167, 139, 250, .18), transparent 36%),
+        linear-gradient(180deg, rgba(255,255,255,.06), transparent 28%);
+      pointer-events: none;
+    }
+    .top {
+      position: relative;
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      color: #94a3b8;
+      font-size: 23px;
+      letter-spacing: -0.02em;
+    }
+    .brand {
+      display: flex;
+      gap: 14px;
+      align-items: center;
+      font-weight: 800;
+      color: #fff;
+      font-size: 30px;
+    }
+    .logo {
+      width: 42px;
+      height: 42px;
+      border-radius: 13px;
+      display: grid;
+      place-items: center;
+      background: linear-gradient(135deg, #22d3ee, #34d399);
+      color: #021014;
+      font-weight: 900;
+    }
+    .pill {
+      border: 1px solid rgba(148, 163, 184, .28);
+      background: rgba(15, 23, 42, .68);
+      color: #cbd5e1;
+      border-radius: 999px;
+      padding: 10px 16px;
+      font-size: 18px;
+      font-weight: 650;
+    }
+    .content {
+      position: relative;
+      height: 818px;
+      padding-top: 44px;
+    }
+    .headline {
+      margin: 0;
+      color: #f8fafc;
+      font-size: 68px;
+      line-height: .98;
+      letter-spacing: -0.06em;
+      max-width: 840px;
+    }
+    .sub {
+      margin-top: 22px;
+      color: #cbd5e1;
+      font-size: 29px;
+      line-height: 1.28;
+      letter-spacing: -0.03em;
+      max-width: 820px;
+    }
+    .accent { color: #67e8f9; }
+    .green { color: #34d399; }
+    .red { color: #fb7185; }
+    .violet { color: #a78bfa; }
+    .mono {
+      font-family: "SF Mono", "JetBrains Mono", Menlo, Consolas, monospace;
+      letter-spacing: -0.04em;
+    }
+    .terminal {
+      margin-top: 38px;
+      border: 1px solid rgba(148, 163, 184, .22);
+      background: rgba(2, 6, 23, .82);
+      border-radius: 24px;
+      padding: 26px;
+      font-size: 24px;
+      line-height: 1.5;
+      color: #dbeafe;
+      box-shadow: inset 0 1px 0 rgba(255,255,255,.05);
+    }
+    .terminal .line { opacity: 1; }
+    .warning {
+      margin-top: 28px;
+      border: 1px solid rgba(167, 139, 250, .4);
+      background: rgba(167, 139, 250, .12);
+      color: #ddd6fe;
+      border-radius: 22px;
+      padding: 22px 26px;
+      font-size: 28px;
+      font-weight: 850;
+      letter-spacing: -0.04em;
+    }
+    .numbers {
+      margin-top: 46px;
+      display: grid;
+      grid-template-columns: 1fr 1fr;
+      gap: 28px;
+      align-items: end;
+    }
+    .number-card {
+      border-radius: 26px;
+      padding: 28px;
+      background: rgba(15, 23, 42, .9);
+      border: 1px solid rgba(148, 163, 184, .22);
+    }
+    .label {
+      color: #94a3b8;
+      font-size: 22px;
+      margin-bottom: 12px;
+      letter-spacing: -0.03em;
+    }
+    .big {
+      font-size: 78px;
+      line-height: .9;
+      font-weight: 900;
+      letter-spacing: -0.08em;
+    }
+    .bar {
+      margin-top: 32px;
+      height: 34px;
+      border-radius: 999px;
+      background: rgba(148, 163, 184, .16);
+      overflow: hidden;
+      border: 1px solid rgba(148, 163, 184, .24);
+    }
+    .fill {
+      height: 100%;
+      width: 37.9%;
+      border-radius: 999px;
+      background: linear-gradient(90deg, #22d3ee, #34d399);
+    }
+    .footer {
+      position: absolute;
+      left: 42px;
+      right: 42px;
+      bottom: 34px;
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      color: #94a3b8;
+      font-size: 20px;
+    }
+    .scene {
+      position: absolute;
+      inset: 44px 0 0 0;
+      opacity: 0;
+      transform: translateY(24px) scale(.985);
+      transition: opacity .24s ease, transform .24s ease;
+    }
+    .scene.active {
+      opacity: 1;
+      transform: translateY(0) scale(1);
+    }
+  </style>
+</head>
+<body>
+  <div class="stage">
+    <div class="card">
+      <div class="top">
+        <div class="brand"><div class="logo">R</div> Runcap</div>
+        <div class="pill">local-first AI cost control</div>
+      </div>
+      <div class="content">
+        <section class="scene active" id="s0">
+          <h1 class="headline">Your AI agent looks busy. It is just circling.</h1>
+          <p class="sub">Same failure, reworded every turn. It produces output, makes no progress, and keeps spending your tokens.</p>
+          <div class="terminal mono">
+            <div class="line">attempt 1: guard the undefined with an if check</div>
+            <div class="line">attempt 2: add an optional chain before .id</div>
+            <div class="line">attempt 3: default the object to {} first</div>
+            <div class="line red">test still fails. budget still draining.</div>
+          </div>
+        </section>
+        <section class="scene" id="s1">
+          <h1 class="headline">Plain hashing never catches this.</h1>
+          <p class="sub">The prompt is similar but never byte-identical between loops, so the hash changes every turn and nothing trips.</p>
+          <div class="terminal mono">
+            <div class="line">hash(attempt 1) = a91f...  hash(attempt 2) = c4d2...</div>
+            <div class="line red">different hash every time -&gt; loop invisible</div>
+          </div>
+        </section>
+        <section class="scene" id="s2">
+          <h1 class="headline">Runcap measures similarity, not hashes.</h1>
+          <p class="sub">A local gateway sees every request in real time and compares each prompt's shape against the recent run.</p>
+          <div class="warning">loop: last 3 prompts 97.7% identical, no progress. The agent is circling the same failure.</div>
+          <div class="terminal mono">
+            <div class="line green">$ runcap status</div>
+            <div class="line violet">Loop warning: stepping in before it burns more budget.</div>
+          </div>
+        </section>
+        <section class="scene" id="s3">
+          <h1 class="headline">And it compresses every call it lets through.</h1>
+          <div class="numbers">
+            <div class="number-card">
+              <div class="label">baseline prompt</div>
+              <div class="big red mono">1,186</div>
+              <div class="label">tokens</div>
+            </div>
+            <div class="number-card">
+              <div class="label">with Runcap</div>
+              <div class="big green mono">737</div>
+              <div class="label">tokens</div>
+            </div>
+          </div>
+          <div class="bar"><div class="fill"></div></div>
+          <p class="sub"><span class="green">37.9% saved</span> on a real OpenAI call. The model still answered correctly about the changed line.</p>
+        </section>
+        <section class="scene" id="s4">
+          <h1 class="headline">Estimate. Cap. Compress. Catch the loop.</h1>
+          <p class="sub">Point your OpenAI or Anthropic-compatible tools at the local gateway. When the ceiling is crossed, the next call stops.</p>
+          <div class="terminal mono">
+            <div class="line green">$ AIM_DAILY_BUDGET_USD=10 runcap gateway</div>
+            <div class="line">gateway up · compress on · hard cap armed · loop guard on</div>
+            <div class="line red">HTTP 429 budget_guard</div>
+            <div class="line accent">stopped before money left your account</div>
+          </div>
+        </section>
+      </div>
+      <div class="footer">
+        <span class="mono">npm install -g runcap</span>
+        <span>Free · MIT · 100% local</span>
+      </div>
+    </div>
+  </div>
+  <script>
+    const scenes = [...document.querySelectorAll(".scene")];
+    window.renderFrame = (seconds) => {
+      const index =
+        seconds < 2.8 ? 0 :
+        seconds < 5.2 ? 1 :
+        seconds < 8.2 ? 2 :
+        seconds < 10.6 ? 3 : 4;
+      scenes.forEach((scene, i) => scene.classList.toggle("active", i === index));
+    };
+  </script>
+</body>
+</html>`;
+
+const browser = await chromium.launch({ headless: true });
+const page = await browser.newPage({ viewport: { width, height }, deviceScaleFactor: 1 });
+await page.setContent(html);
+await page.waitForTimeout(100);
+
+for (let i = 0; i < frameCount; i += 1) {
+  const seconds = i / fps;
+  await page.evaluate((t) => window.renderFrame(t), seconds);
+  await page.screenshot({ path: join(framesDir, `frame-${String(i).padStart(4, "0")}.png`) });
+}
+await browser.close();
+
+const ffmpeg = spawnSync("ffmpeg", [
+  "-y",
+  "-framerate", String(fps),
+  "-i", join(framesDir, "frame-%04d.png"),
+  "-c:v", "libx264",
+  "-pix_fmt", "yuv420p",
+  "-movflags", "+faststart",
+  "-crf", "18",
+  outFile
+], { stdio: "inherit" });
+
+if (ffmpeg.status !== 0) {
+  process.exit(ffmpeg.status ?? 1);
+}
+
+console.log(`wrote ${outFile}`);

package/src/compressor.mjs

@@ -405,32 +405,100 @@ export function requestShapeText(body) {
   return parts.join("\n");
 }
 
+// Pull the "did the work move?" signal out of an upstream RESPONSE. Similar
+// prompts alone can't tell circling from convergence: a run closing in on a fix
+// also sends near-identical prompts turn after turn. The tell is whether the
+// observation changed - the error/test output coming back. We reduce a response
+// to the assistant's returned text (plus any explicit error), which carries the
+// error/stack/test signature the next prompt is reacting to.
+export function responseSignature(body) {
+  if (!body || typeof body !== "object") return "";
+  const parts = [];
+  const push = (content) => {
+    if (typeof content === "string") parts.push(content);
+    else if (Array.isArray(content)) {
+      for (const p of content) if (p && typeof p === "object" && typeof p.text === "string") parts.push(p.text);
+    }
+  };
+  // OpenAI chat: choices[].message.content
+  if (Array.isArray(body.choices)) {
+    for (const ch of body.choices) {
+      if (ch && typeof ch === "object" && ch.message) push(ch.message.content);
+    }
+  }
+  // Anthropic messages: content blocks at top level
+  if (Array.isArray(body.content)) push(body.content);
+  // Provider error envelopes (OpenAI {error:{message}}, Anthropic {error:{message}})
+  if (body.error) {
+    if (typeof body.error === "string") parts.push(body.error);
+    else if (typeof body.error.message === "string") parts.push(body.error.message);
+  }
+  return parts.join("\n");
+}
+
 // Given the current request and a rolling history of prior request shapes,
 // decide whether the agent is circling. Returns { looping, repeats, similarity }.
 // History is oldest->newest of prior requestShapeText() strings in this session.
+//
+// Prompt similarity is the cheap pre-filter. When response signatures are
+// available it becomes a GATE, not the verdict: a run only counts as circling
+// when the prompts are near-identical AND the upstream response did not move
+// (same error/output signature). A converging run sends similar prompts but the
+// observation shifts, so it passes. Pass responseSignatures (oldest->newest,
+// aligned with history) and currentResponseSignature to enable the gate; omit
+// them and detection falls back to prompt-similarity-only (prior behavior).
 export function detectLoop(currentShape, history, {
   similarityThreshold = LOOP_SIMILARITY,
-  minRepeats = LOOP_MIN_REPEATS
+  minRepeats = LOOP_MIN_REPEATS,
+  responseSignatures = null,
+  currentResponseSignature = null,
+  responseMovedThreshold = LOOP_SIMILARITY
 } = {}) {
   if (!currentShape || !Array.isArray(history) || history.length === 0) {
-    return { looping: false, repeats: 0, similarity: 0 };
+    return { looping: false, repeats: 0, similarity: 0, responseMoved: false };
   }
   const curLines = String(currentShape).split("\n");
+  const haveResponses = Array.isArray(responseSignatures) && currentResponseSignature != null;
   let repeats = 0;
   let lastSimilarity = 0;
-  // Walk backward through history; count the unbroken run of near-identical turns.
+  let responseMoved = false;
+
+  // Response-side gate. Prompt similarity alone can't separate circling from
+  // convergence: a run closing in on a fix also sends near-identical prompts.
+  // The tell is the observation - the error/output coming back. A change in the
+  // response between consecutive turns is progress, and it breaks the run the
+  // same way a dissimilar prompt does. So we walk backward counting only the
+  // trailing turns that are BOTH prompt-similar AND error-stuck; the first turn
+  // where the prompt differs OR the response moved ends the run. This means a
+  // run that made progress and THEN got stuck on one error still flags once it
+  // has circled that same error long enough. With no response data we fall back
+  // to prompt-similarity-only (prior behavior).
+  //
+  // Responses, newest->oldest: currentResponseSignature (what the current prompt
+  // is reacting to), then responseSignatures[N-1], [N-2], ... A "stuck" step
+  // between turn i and the next-newer turn means their responses match.
+  let newerResp = haveResponses ? currentResponseSignature : null;
   for (let i = history.length - 1; i >= 0; i--) {
     const sim = lineSimilarity(curLines, String(history[i]).split("\n"));
-    if (sim >= similarityThreshold) {
-      repeats += 1;
-      lastSimilarity = sim;
-    } else {
-      break;
+    if (sim < similarityThreshold) break;
+    if (haveResponses) {
+      const olderResp = responseSignatures[i];
+      const haveBoth = olderResp != null && newerResp != null &&
+        String(olderResp).length && String(newerResp).length;
+      if (haveBoth) {
+        const respSim = lineSimilarity(String(newerResp).split("\n"), String(olderResp).split("\n"));
+        if (respSim < responseMovedThreshold) { responseMoved = true; break; }
+      }
+      newerResp = olderResp;
     }
+    repeats += 1;
+    lastSimilarity = sim;
   }
+
   return {
     looping: repeats >= minRepeats,
     repeats,
-    similarity: Number(lastSimilarity.toFixed(3))
+    similarity: Number(lastSimilarity.toFixed(3)),
+    responseMoved
   };
 }

package/src/mission-control.mjs

@@ -7,7 +7,7 @@ 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";
 
 const STORE_DIR = ".runcap";
 const MISSIONS_DIR = path.join(STORE_DIR, "missions");
@@ -528,6 +528,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 +558,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 +663,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 +711,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 +788,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,