runcap 0.1.0 → 0.2.0

package/src/mission-control.mjs

@@ -2,15 +2,19 @@ import { spawn } from "node:child_process";
 import { createHash } from "node:crypto";
 import http from "node:http";
 import { appendFile, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import process from "node:process";
+import { syncRun } from "./cloud.mjs";
+import { sendAlert } from "./alerts.mjs";
+import { compressRequestBody, estimateTokens } from "./compressor.mjs";
 
 const STORE_DIR = ".runcap";
 const MISSIONS_DIR = path.join(STORE_DIR, "missions");
 const PLANS_DIR = path.join(STORE_DIR, "plans");
 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");
 const ENV_EXAMPLE_FILE = ".env.example";
 
 const ERROR_PATTERNS = [
@@ -51,7 +55,7 @@ const ERROR_PATTERNS = [
   }
 ];
 
-export async function runMission({ command, label, fuelBefore }) {
+export async function runMission({ command, label, fuelBefore, autoGateway = false, mock = false }) {
   await ensureStore();
   const id = createMissionId(label);
   const missionDir = path.join(MISSIONS_DIR, id);
@@ -61,7 +65,29 @@ export async function runMission({ command, label, fuelBefore }) {
   const cwd = process.cwd();
   const before = await collectSnapshot(cwd);
   const preflight = buildPreflight(command.join(" "), before);
-  const output = await runChild(command, cwd);
+
+  // Zero-config: bring up a gateway for just this run and point the child's
+  // provider base URLs at it, so the cap is enforced without the user manually
+  // starting a gateway or exporting any base URL.
+  let gateway = null;
+  let childEnv = {};
+  const budgetBefore = readBudget();
+  const spentBefore = autoGateway ? (await readGatewaySummary({ windowMs: budgetWindowMs() })).estimatedCostUsd : 0;
+  if (autoGateway) {
+    gateway = await startEphemeralGateway({ mock });
+    childEnv = {
+      ANTHROPIC_BASE_URL: `${gateway.baseUrl}/v1`,
+      OPENAI_BASE_URL: `${gateway.baseUrl}/v1`,
+      OPENAI_API_BASE: `${gateway.baseUrl}/v1`
+    };
+  }
+
+  let output;
+  try {
+    output = await runChild(command, cwd, childEnv);
+  } finally {
+    if (gateway) await gateway.close().catch(() => {});
+  }
   const after = await collectSnapshot(cwd);
   const terminal = `${output.stdout}\n${output.stderr}`;
   const errors = parseErrors(terminal);
@@ -103,9 +129,21 @@ export async function runMission({ command, label, fuelBefore }) {
   await writeFile(path.join(missionDir, "report.html"), formatHtmlReport(mission));
   await writeFile(path.join(STORE_DIR, "latest"), id);
 
+  let capSummary = null;
+  if (autoGateway) {
+    const spentAfter = (await readGatewaySummary({ windowMs: budgetWindowMs() })).estimatedCostUsd;
+    capSummary = {
+      capUsd: budgetBefore,
+      spentThisRunUsd: Number((spentAfter - spentBefore).toFixed(6)),
+      spentWindowUsd: spentAfter,
+      mode: gateway?.gatewayMode ?? "proxy"
+    };
+  }
+
   return {
     id,
-    summary: shortSummary(mission)
+    summary: shortSummary(mission),
+    capSummary
   };
 }
 
@@ -207,6 +245,38 @@ export async function planMission(goal, options = {}) {
   return plan;
 }
 
+// Persist a hard cap to .runcap/budget.json so the gateway enforces it without
+// the user manually exporting AIM_DAILY_BUDGET_USD. env still wins if set.
+export async function setBudgetCap(capUsd, { source = "manual" } = {}) {
+  await ensureStore();
+  const value = Number(capUsd);
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error("Usage: runcap cap <usd> (a non-negative number).");
+  }
+  await writeFile(BUDGET_FILE, JSON.stringify({ capUsd: value, source, setAt: new Date().toISOString() }, null, 2));
+  const envNote = process.env.AIM_DAILY_BUDGET_USD
+    ? "\nNote: AIM_DAILY_BUDGET_USD is set in your env and overrides this file."
+    : "";
+  return `Hard cap set: $${value.toFixed(2)} per ${(process.env.AIM_BUDGET_WINDOW ?? "day")}. Saved to ${BUDGET_FILE}.${envNote}`;
+}
+
+export async function clearBudgetCap() {
+  await ensureStore();
+  if (existsSync(BUDGET_FILE)) await writeFile(BUDGET_FILE, JSON.stringify({ capUsd: null, clearedAt: new Date().toISOString() }, null, 2));
+  return "Stored cap cleared. The gateway will only enforce AIM_DAILY_BUDGET_USD if set.";
+}
+
+export function currentBudgetCap() {
+  const cap = readBudget();
+  if (cap === null) return "No cap set. Run `runcap cap <usd>` or `runcap plan --apply-cap`.";
+  const src = process.env.AIM_DAILY_BUDGET_USD ? "env AIM_DAILY_BUDGET_USD" : `file ${BUDGET_FILE}`;
+  return `Current hard cap: $${cap.toFixed(2)} per ${(process.env.AIM_BUDGET_WINDOW ?? "day")} (from ${src}).`;
+}
+
+export function hasStoredCap() {
+  return readStoredBudget() !== null;
+}
+
 export async function listPlans() {
   await ensureStore();
   const plans = await readPlans();
@@ -244,9 +314,15 @@ export async function setupProject() {
     "OPENAI_API_KEY=",
     "AIM_UPSTREAM_BASE_URL=https://api.openai.com/v1",
     "",
-    "# Optional budget guard. If estimated spend already exceeds this, gateway blocks new calls.",
+    "# Hard cap (USD) per budget window. The gateway prices each call from its",
+    "# own tokens and blocks it BEFORE forwarding if it would push spend over the cap.",
+    "# You can also set this with `runcap cap <usd>` or `runcap plan --apply-cap`.",
     "AIM_DAILY_BUDGET_USD=5",
     "",
+    "# Budget window: day (default, rolling 24h), session (since gateway start),",
+    "# all (never resets), or a number of hours. Caps reset per window.",
+    "AIM_BUDGET_WINDOW=day",
+    "",
     "# For demo mode without external API calls:",
     "AIM_GATEWAY_MODE=mock"
   ].join("\n");
@@ -292,6 +368,80 @@ export async function doctor() {
   ].join("\n");
 }
 
+// Guided first-run, shown when `runcap` is invoked with no arguments. Explains
+// in one screen what Runcap does, what it does NOT do, checks readiness, and
+// gives exactly ONE next step based on the current state — so a newcomer reaches
+// their first result without reading docs.
+export async function welcome() {
+  await ensureStore();
+  const hasOpenAiKey = Boolean(process.env.AIM_UPSTREAM_API_KEY ?? process.env.OPENAI_API_KEY);
+  const hasAnthropicKey = Boolean(process.env.ANTHROPIC_API_KEY);
+  const hasAnyKey = hasOpenAiKey || hasAnthropicKey;
+  const cap = readBudget();
+  const gateway = await readGatewaySummary({ windowMs: budgetWindowMs() });
+  const window = process.env.AIM_BUDGET_WINDOW ?? "day";
+
+  const tick = (ok) => (ok ? "[x]" : "[ ]");
+  const keyLabel = hasAnyKey
+    ? `API key detected (${[hasAnthropicKey && "Anthropic", hasOpenAiKey && "OpenAI"].filter(Boolean).join(" + ")})`
+    : "No API key in this shell (set ANTHROPIC_API_KEY or OPENAI_API_KEY)";
+  const capLabel = cap === null ? "No cap set yet" : `Cap set: $${cap.toFixed(2)} per ${window}`;
+
+  // One next step, chosen by what is missing.
+  let nextStep;
+  if (!hasAnyKey) {
+    nextStep = [
+      "Next: give Runcap the same provider key your agent already uses, e.g.",
+      "  export ANTHROPIC_API_KEY=sk-...      # or OPENAI_API_KEY=sk-...",
+      "Then run `runcap` again."
+    ];
+  } else if (cap === null) {
+    nextStep = [
+      "Next: set the most you want a run to spend, then run your agent through Runcap:",
+      "  runcap cap 5",
+      "  runcap run -- claude \"fix the failing test\"",
+      "Runcap starts a local gateway, points your agent at it, and blocks any call",
+      "that would push spend over $5, before it reaches the paid API.",
+      "",
+      "Not sure what to cap at? Estimate first:",
+      "  runcap plan --apply-cap -- \"the task you're about to run\""
+    ];
+  } else {
+    nextStep = [
+      `You're ready. Cap is $${cap.toFixed(2)} per ${window}. Run any agent through Runcap:`,
+      "  runcap run -- claude \"fix the failing test\"",
+      "  runcap run -- codex \"...\"      runcap run -- python my_agent.py",
+      "",
+      gateway.callCount > 0
+        ? `Spent so far this ${window}: $${gateway.estimatedCostUsd.toFixed(4)} across ${gateway.callCount} calls. See: runcap status`
+        : "No calls recorded yet. Your first `runcap run` will show the spend."
+    ];
+  }
+
+  return [
+    "Runcap: see and cap what your AI agent spends, before it spends it.",
+    "",
+    "What it does:",
+    "  - Prices each call your agent makes from its own tokens.",
+    "  - Blocks any call that would exceed your cap BEFORE it hits the paid API.",
+    "  - Shows you the real spend, per run and per day.",
+    "",
+    "What it does NOT do (so there are no surprises):",
+    "  - It does not give you an AI model. You bring your own provider API key.",
+    "  - It does not run tasks for you. You bring your own agent (Claude Code,",
+    "    Codex, a script: anything that calls OpenAI/Anthropic).",
+    "  - It is a local tool for that setup, not a no-account web app.",
+    "",
+    "Readiness:",
+    `  ${tick(hasAnyKey)} ${keyLabel}`,
+    `  ${tick(cap !== null)} ${capLabel}`,
+    "",
+    ...nextStep,
+    "",
+    "Full command list: `runcap help`."
+  ].join("\n");
+}
+
 export async function startDashboard({ port = 8791 } = {}) {
   await ensureStore();
   const server = http.createServer(async (request, response) => {
@@ -350,13 +500,15 @@ async function listenLocal(server, port, label) {
   });
 }
 
-export async function startGateway({ port = 8792, mock = false } = {}) {
-  await ensureStore();
+// Build (but do not start) the gateway HTTP server. Upstream targets are
+// captured here from explicit args or env, so the auto-wrapper can pin the real
+// upstream BEFORE it rewrites the child's base URLs to point at this gateway.
+function createGatewayServer({ port = 8792, mock = false, upstream = {} } = {}) {
   const gatewayMode = mock || process.env.AIM_GATEWAY_MODE === "mock" ? "mock" : "proxy";
-  const openaiKey = process.env.AIM_UPSTREAM_API_KEY ?? process.env.OPENAI_API_KEY;
-  const anthropicKey = process.env.ANTHROPIC_API_KEY;
-  const openaiBaseUrl = process.env.AIM_UPSTREAM_BASE_URL ?? process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1";
-  const anthropicBaseUrl = process.env.ANTHROPIC_BASE_URL ?? "https://api.anthropic.com/v1";
+  const openaiKey = upstream.openaiKey ?? process.env.AIM_UPSTREAM_API_KEY ?? process.env.OPENAI_API_KEY;
+  const anthropicKey = upstream.anthropicKey ?? process.env.ANTHROPIC_API_KEY;
+  const openaiBaseUrl = upstream.openaiBaseUrl ?? process.env.AIM_UPSTREAM_BASE_URL ?? process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1";
+  const anthropicBaseUrl = upstream.anthropicBaseUrl ?? process.env.ANTHROPIC_BASE_URL ?? "https://api.anthropic.com/v1";
   const anthropicVersion = process.env.ANTHROPIC_VERSION ?? "2023-06-01";
   if (gatewayMode !== "mock" && !openaiKey && !anthropicKey) {
     throw new Error("Missing upstream key. Set OPENAI_API_KEY (for /v1/chat/completions) and/or ANTHROPIC_API_KEY (for /v1/messages). The gateway cannot proxy without at least one.");
@@ -384,8 +536,33 @@ export async function startGateway({ port = 8792, mock = false } = {}) {
       const bodyText = await readRequestBody(request);
       const requestBody = safeJson(bodyText) ?? {};
       const budget = readBudget();
-      const summary = await readGatewaySummary();
-      if (budget !== null && summary.estimatedCostUsd >= budget) {
+      const summary = await readGatewaySummary({ windowMs: budgetWindowMs() });
+      // Compress the request body once (safe, lossless-by-construction). Disable with AIM_COMPRESS=off.
+      const compressionOn = (process.env.AIM_COMPRESS ?? "on").toLowerCase() !== "off";
+      let forwardBody = bodyText;
+      let compression = null;
+      if (compressionOn) {
+        const c = compressRequestBody(requestBody);
+        if (c.savedChars > 0 && c.touched > 0) {
+          forwardBody = JSON.stringify(c.body);
+          compression = {
+            savedTokens: c.savedTokens,
+            savedChars: c.savedChars,
+            beforeChars: c.before,
+            afterChars: c.after,
+            fieldsTouched: c.touched,
+            truth: "estimated"
+          };
+        }
+      }
+      // Pre-call cap: price THIS request from its own tokens and block before
+      // forwarding if (already spent in the window + this call) would exceed the
+      // cap. Catches both accumulated overspend and a single oversized call.
+      const preCall = estimateRequestCost(requestBody);
+      const callEstimate = preCall.estimatedUsd ?? 0;
+      const projectedCostUsd = Number((summary.estimatedCostUsd + callEstimate).toFixed(6));
+      if (budget !== null && projectedCostUsd > budget) {
+        const blockedByThisCall = summary.estimatedCostUsd < budget;
         const event = {
           at: new Date().toISOString(),
           path: url.pathname,
@@ -395,11 +572,39 @@ export async function startGateway({ port = 8792, mock = false } = {}) {
           usage: null,
           cost: null,
           truth: "budget_guard",
-          error: `Budget exceeded: ${summary.estimatedCostUsd} >= ${budget}`,
+          guard: {
+            spentUsd: summary.estimatedCostUsd,
+            callEstimateUsd: callEstimate,
+            callEstimateTruth: preCall.truth,
+            projectedUsd: projectedCostUsd,
+            capUsd: budget,
+            blockedByThisCall
+          },
+          error: blockedByThisCall
+            ? `Budget would be exceeded by this call: $${summary.estimatedCostUsd} spent + ~$${callEstimate} this call > cap $${budget}`
+            : `Budget exceeded: ${summary.estimatedCostUsd} >= ${budget}`,
           requestHash: createHash("sha1").update(bodyText).digest("hex")
         };
         await appendGatewayEvent(event);
-        sendJson(response, { error: event.error, truth: event.truth }, 429);
+        sendJson(response, { error: event.error, truth: event.truth, guard: event.guard }, 429);
+        const breachText = blockedByThisCall
+          ? `Runcap: cap protected. Blocked a ~$${callEstimate} call on ${event.model} before it ran ($${summary.estimatedCostUsd} already spent, cap $${budget}).`
+          : `Runcap: cap hit. Run blocked at $${summary.estimatedCostUsd} (cap $${budget}) on ${event.model}. The gateway stopped the call before it could spend more.`;
+        sendAlert(breachText)
+          .then((channels) => {
+            if (channels && channels.length) console.log(`Cap-breach alert sent to: ${channels.join(", ")}`);
+          })
+          .catch(() => {});
+        syncRun({
+          mission_id: null,
+          label: `gateway cap breach (${event.model})`,
+          estimate_low: budget,
+          estimate_high: projectedCostUsd,
+          cap: budget,
+          actual: summary.estimatedCostUsd,
+          capped: true,
+          status: "capped"
+        }).catch(() => {});
         return;
       }
       if (gatewayMode === "mock") {
@@ -414,6 +619,7 @@ export async function startGateway({ port = 8792, mock = false } = {}) {
           durationMs: Date.now() - started,
           usage: responseBody.usage,
           cost: estimateApiCost(responseBody.usage, requestBody.model ?? responseBody.model),
+          compression,
           truth: "mock_provider_usage",
           requestHash: createHash("sha1").update(bodyText).digest("hex")
         });
@@ -437,13 +643,16 @@ export async function startGateway({ port = 8792, mock = false } = {}) {
             "authorization": `Bearer ${upstreamKey}`,
             "content-type": request.headers["content-type"] ?? "application/json"
           };
-      // Anthropic base URLs already include /v1; avoid doubling it.
-      const pathForUpstream = isAnthropic ? url.pathname.replace(/^\/v1/, "") : url.pathname;
+      // Both default upstream base URLs already include /v1, and the child calls
+      // us at /v1/*. Strip the leading /v1 from the path when the upstream base
+      // already ends in /v1, so we never produce a doubled /v1/v1 (OpenAI 404).
+      const baseHasV1 = /\/v1\/?$/.test(upstreamBase);
+      const pathForUpstream = baseHasV1 ? url.pathname.replace(/^\/v1/, "") : url.pathname;
       const upstreamUrl = `${upstreamBase.replace(/\/$/, "")}${pathForUpstream}`;
       const upstreamResponse = await fetch(upstreamUrl, {
         method: "POST",
         headers,
-        body: bodyText
+        body: forwardBody
       });
       const responseText = await upstreamResponse.text();
       response.writeHead(upstreamResponse.status, {
@@ -461,9 +670,23 @@ export async function startGateway({ port = 8792, mock = false } = {}) {
         durationMs: Date.now() - started,
         usage: responseBody.usage ?? null,
         cost: estimateApiCost(responseBody.usage, requestBody.model ?? responseBody.model),
+        compression,
         truth: responseBody.usage ? "provider_usage" : "unknown",
         requestHash: createHash("sha1").update(bodyText).digest("hex")
       });
+      if (responseBody.usage) {
+        const spent = await readGatewaySummary({ windowMs: budgetWindowMs() });
+        syncRun({
+          mission_id: null,
+          label: "gateway session (actual spend)",
+          estimate_low: spent.estimatedCostUsd,
+          estimate_high: spent.estimatedCostUsd,
+          cap: budget,
+          actual: spent.estimatedCostUsd,
+          capped: false,
+          status: "running"
+        }).catch(() => {});
+      }
     } catch (error) {
       await appendGatewayEvent({
         at: new Date().toISOString(),
@@ -479,6 +702,13 @@ export async function startGateway({ port = 8792, mock = false } = {}) {
       sendJson(response, { error: error.message }, 500);
     }
   });
+  return { server, gatewayMode, openaiKey, anthropicKey, openaiBaseUrl, anthropicBaseUrl };
+}
+
+export async function startGateway({ port = 8792, mock = false } = {}) {
+  await ensureStore();
+  const { server, gatewayMode, openaiKey, anthropicKey, openaiBaseUrl, anthropicBaseUrl } =
+    createGatewayServer({ port, mock });
   await listenLocal(server, port, "gateway");
   console.log(`Runcap gateway: http://127.0.0.1:${port}/v1`);
   console.log(`Mode: ${gatewayMode}`);
@@ -491,11 +721,38 @@ export async function startGateway({ port = 8792, mock = false } = {}) {
   console.log("Press Ctrl+C to stop.");
 }
 
+// Start the gateway on an ephemeral free port for the duration of one wrapped
+// run, returning a handle the wrapper uses to point the child at it and to shut
+// 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 } = {}) {
+  await ensureStore();
+  const upstream = {
+    openaiKey: process.env.AIM_UPSTREAM_API_KEY ?? process.env.OPENAI_API_KEY,
+    anthropicKey: process.env.ANTHROPIC_API_KEY,
+    openaiBaseUrl: process.env.AIM_UPSTREAM_BASE_URL ?? process.env.OPENAI_BASE_URL ?? "https://api.openai.com/v1",
+    anthropicBaseUrl: process.env.ANTHROPIC_BASE_URL ?? "https://api.anthropic.com/v1"
+  };
+  const { server, gatewayMode } = createGatewayServer({ port: 0, mock, upstream });
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  const actualPort = server.address().port;
+  return {
+    port: actualPort,
+    baseUrl: `http://127.0.0.1:${actualPort}`,
+    gatewayMode,
+    close: () => new Promise((resolve) => server.close(resolve))
+  };
+}
+
 export async function showStatus(options = {}) {
   await ensureStore();
   const fuel = await readFuel();
   const fuelLine = fuel.currentPercent === null
-    ? "Fuel: unknown. Run `aim fuel set <percent>` to calibrate subscription limits."
+    ? "Fuel: unknown. Run `runcap fuel set <percent>` to calibrate subscription limits."
     : `Fuel: ${fuel.currentPercent}% (${fuel.source}, confidence: ${fuel.confidence})`;
   if (options.includeFuelOnly) return fuelLine;
 
@@ -588,13 +845,16 @@ function buildAiWorkPlan(goal, { quality = "high", fuelPercent = null, snapshot
   ].filter(Boolean).length;
   const hasRepo = Boolean(snapshot.packageJson);
   const hasVerification = hasRepo && Object.keys(snapshot.packageJson?.scripts ?? {}).some((name) => /test|build|lint|typecheck/.test(name));
-  const fuel = Number.isFinite(Number(fuelPercent)) ? Number(fuelPercent) : null;
+  const fuel = fuelPercent === null || fuelPercent === undefined || fuelPercent === "" || !Number.isFinite(Number(fuelPercent))
+    ? null
+    : Number(fuelPercent);
   const budgetRisk = bigSignals > 0 || (fuel !== null && fuel < 30) ? "High" : fuel !== null && fuel < 55 ? "Medium" : "Low";
   const expectedWasteReduction = budgetRisk === "High" ? "40-70%" : budgetRisk === "Medium" ? "25-45%" : "10-25%";
   const qualityRisk = quality === "cheap" && budgetRisk === "High" ? "High" : budgetRisk === "High" ? "Medium" : "Low";
   const routing = routeTask({ taskType, budgetRisk, quality, hasVerification });
   const proof = proofForTask({ taskType, hasVerification });
   const missions = missionBreakdown({ taskType, budgetRisk, proof });
+  const cost = estimatePlanCost({ budgetRisk, bigSignals, words, taskType, quality });
   return {
     id: createPlanId(cleanGoal),
     createdAt: new Date().toISOString(),
@@ -609,6 +869,12 @@ function buildAiWorkPlan(goal, { quality = "high", fuelPercent = null, snapshot
     budget: {
       risk: budgetRisk,
       expectedWasteReduction,
+      costLowUsd: cost.lowUsd,
+      costHighUsd: cost.highUsd,
+      costRange: cost.range,
+      recommendedCapUsd: cost.recommendedCapUsd,
+      recommendedCap: cost.recommendedCap,
+      costPrecision: cost.precision,
       reason: budgetRisk === "High"
         ? "The goal is broad or fuel is low. A single agent run is likely to waste context and repeat work."
         : "The goal can be controlled with smaller missions and proof checkpoints."
@@ -629,6 +895,49 @@ function buildAiWorkPlan(goal, { quality = "high", fuelPercent = null, snapshot
   };
 }
 
+// Estimate a USD cost RANGE for an agent run from scope signals, priced against
+// the sourced table. Deliberately a range, not an oracle: agent runs are
+// stochastic. The recommended cap sits above the high end so a normal run
+// completes but a runaway loop is stopped.
+function estimatePlanCost({ budgetRisk, bigSignals, words, taskType, quality }) {
+  // Base expected total tokens (input+output across the whole run, including
+  // the agent re-reading context on each loop). Software runs loop more.
+  let baseTokens = taskType === "software" ? 220000 : 120000;
+  baseTokens += words * 1500;
+  baseTokens += bigSignals * 350000;
+  if (budgetRisk === "High") baseTokens *= 2.4;
+  else if (budgetRisk === "Medium") baseTokens *= 1.5;
+
+  // Premium-model blended price ($/token): planning on a strong model is the
+  // expensive case, so we price the headline range against it to avoid
+  // under-promising. Opus-class: ~$5/M in, ~$25/M out, assume ~30% output.
+  const blendedPerToken = quality === "cheap"
+    ? (0.75 * 0.7 + 4.5 * 0.3) / 1_000_000   // cheap tier (gpt-5.4-mini)
+    : (5 * 0.7 + 25 * 0.3) / 1_000_000;       // strong tier (opus-class)
+
+  const mid = baseTokens * blendedPerToken;
+  // Range: runs vary widely, so +-45% around the midpoint.
+  const lowUsd = round2(mid * 0.55);
+  const highUsd = round2(mid * 1.45);
+  // Cap above the high end (1.5x) so a normal run finishes, a loop is killed.
+  const recommendedCapUsd = roundCap(highUsd * 1.5);
+  return {
+    lowUsd,
+    highUsd,
+    recommendedCapUsd,
+    range: `$${lowUsd.toFixed(2)}-$${highUsd.toFixed(2)}`,
+    recommendedCap: `$${recommendedCapUsd.toFixed(2)}`,
+    precision: "calculated_estimate_not_provider_bill"
+  };
+}
+
+function round2(n) { return Math.round(n * 100) / 100; }
+function roundCap(n) {
+  // Round caps to a friendly number: nearest $1 under $20, nearest $5 above.
+  if (n < 20) return Math.max(1, Math.ceil(n));
+  return Math.ceil(n / 5) * 5;
+}
+
 function classifyTask(lower) {
   if (/code|bug|test|build|app|api|database|typescript|react|python|deploy|auth|repo|github/.test(lower)) return "software";
   if (/video|script|post|content|image|marketing|copy|campaign|linkedin|youtube/.test(lower)) return "creative";
@@ -699,13 +1008,13 @@ function commandTemplatesForPlan(goal, missions) {
   }));
 }
 
-async function runChild(command, cwd) {
+async function runChild(command, cwd, extraEnv = {}) {
   const started = Date.now();
   const [program, ...args] = command;
   return await new Promise((resolve) => {
     const child = spawn(program, args, {
       cwd,
-      env: { ...process.env, AIM_WRAPPED: "1" },
+      env: { ...process.env, AIM_WRAPPED: "1", ...extraEnv },
       shell: false
     });
     let stdout = "";
@@ -1049,6 +1358,7 @@ async function dashboardStatus() {
   return {
     fuel,
     gateway,
+    budget: readBudget(),
     missionCount: missions.length,
     latest: missions[0] ?? null,
     counts: missions.reduce((acc, mission) => {
@@ -1068,26 +1378,83 @@ async function readGatewayEvents() {
   return text.split("\n").filter(Boolean).map((line) => safeJson(line)).filter(Boolean);
 }
 
-async function readGatewaySummary() {
-  const events = await readGatewayEvents();
+async function readGatewaySummary({ windowMs } = {}) {
+  const allEvents = await readGatewayEvents();
+  // When a window is given (used by the budget guard), only count spend whose
+  // timestamp falls inside it. The cap is then a per-window budget that resets,
+  // not an all-time counter that locks the gateway forever.
+  const events = windowMs
+    ? allEvents.filter((event) => {
+        const t = Date.parse(event.at ?? "");
+        return Number.isFinite(t) && Date.now() - t <= windowMs;
+      })
+    : allEvents;
   const successful = events.filter((event) => event.status >= 200 && event.status < 300);
-  const totalTokens = events.reduce((sum, event) => sum + Number(event.usage?.total_tokens ?? 0), 0);
+  const totalTokens = events.reduce((sum, event) => {
+    const u = event.usage;
+    if (!u) return sum;
+    const total = Number(u.total_tokens ?? 0) ||
+      Number(u.prompt_tokens ?? u.input_tokens ?? 0) + Number(u.completion_tokens ?? u.output_tokens ?? 0);
+    return sum + total;
+  }, 0);
   const estimatedCost = events.reduce((sum, event) => sum + Number(event.cost?.estimatedUsd ?? 0), 0);
+  const savedTokens = events.reduce((sum, event) => sum + Number(event.compression?.savedTokens ?? 0), 0);
+  // Value the saved tokens at a blended input rate from the price table so we can
+  // show one honest dollar figure. Per saved input token: use the model's input rate.
+  const savedUsd = events.reduce((sum, event) => {
+    const saved = Number(event.compression?.savedTokens ?? 0);
+    if (!saved) return sum;
+    const pricing = modelPricing(event.model);
+    const inputRate = pricing ? pricing.inputPerMillion : 3; // fall back to a mid Sonnet-ish rate
+    return sum + (saved * inputRate) / 1_000_000;
+  }, 0);
   return {
     callCount: events.length,
     successfulCallCount: successful.length,
     totalTokens,
     estimatedCostUsd: Number(estimatedCost.toFixed(6)),
+    savedTokens,
+    savedUsd: Number(savedUsd.toFixed(6)),
+    wouldHaveSpentUsd: Number((estimatedCost + savedUsd).toFixed(6)),
     truth: events.some((event) => event.truth === "provider_usage" || event.truth === "mock_provider_usage")
       ? "usage_plus_static_price_table"
       : "unknown",
+    windowMs: windowMs ?? null,
     recent: events.slice(-20).reverse()
   };
 }
 
+// How wide the budget window is, in ms. AIM_BUDGET_WINDOW controls it:
+//   "day" (default) → rolling 24h, "session" → since gateway start, "all" → no reset.
+const GATEWAY_STARTED_AT = Date.now();
+function budgetWindowMs() {
+  const mode = (process.env.AIM_BUDGET_WINDOW ?? "day").toLowerCase();
+  if (mode === "all") return undefined;
+  if (mode === "session") return Date.now() - GATEWAY_STARTED_AT;
+  const hours = Number(mode);
+  if (Number.isFinite(hours) && hours > 0) return hours * 60 * 60 * 1000;
+  return 24 * 60 * 60 * 1000; // "day" default
+}
+
+// The cap value. Precedence: AIM_DAILY_BUDGET_USD env > persisted budget.json
+// (written by `runcap plan` / `runcap cap`). Null means no cap is set.
 function readBudget() {
   const raw = process.env.AIM_DAILY_BUDGET_USD;
-  if (raw === undefined || raw === "") return null;
+  if (raw !== undefined && raw !== "") {
+    const value = Number(raw);
+    if (Number.isFinite(value) && value >= 0) return value;
+  }
+  const stored = readStoredBudget();
+  return stored;
+}
+
+function readStoredBudget() {
+  if (!existsSync(BUDGET_FILE)) return null;
+  let text = null;
+  try { text = readFileSync(BUDGET_FILE, "utf8"); } catch { return null; }
+  const parsed = safeJson(text);
+  const raw = parsed?.capUsd;
+  if (raw === null || raw === undefined || raw === "") return null;
   const value = Number(raw);
   return Number.isFinite(value) && value >= 0 ? value : null;
 }
@@ -1204,6 +1571,43 @@ function estimateApiCost(usage, model) {
   };
 }
 
+// Estimate the cost of a request BEFORE it is forwarded upstream, from the
+// request body alone. Input tokens are estimated from the serialized prompt;
+// output tokens from the caller's max_tokens (the worst case the provider can
+// bill). Returns null when the model has no verified price, so the guard can
+// decide whether to fail open or closed rather than guessing a number.
+function estimateRequestCost(requestBody) {
+  const model = requestBody?.model ?? "";
+  const pricing = modelPricing(model);
+  if (!pricing) return { estimatedUsd: null, truth: "unknown_price", model };
+
+  const promptText = JSON.stringify(
+    requestBody.messages ?? requestBody.system ?? requestBody.input ?? requestBody.prompt ?? ""
+  );
+  const inputTokens = estimateTokens(promptText);
+  // Worst-case output the provider could bill: honor the caller's stated cap,
+  // else assume a generous default so the guard is not fooled by an open-ended call.
+  const maxOutput = Number(
+    requestBody.max_tokens ??
+    requestBody.max_completion_tokens ??
+    requestBody.max_output_tokens ??
+    4096
+  );
+  const outputTokens = Number.isFinite(maxOutput) && maxOutput > 0 ? maxOutput : 4096;
+
+  const estimatedUsd =
+    (inputTokens / 1_000_000) * pricing.inputPerMillion +
+    (outputTokens / 1_000_000) * pricing.outputPerMillion;
+
+  return {
+    estimatedUsd: Number(estimatedUsd.toFixed(6)),
+    truth: "pre_call_estimate_from_request",
+    model,
+    inputTokens,
+    outputTokens
+  };
+}
+
 function modelPricing(model = "") {
   const name = String(model).toLowerCase();
   const batch = name.includes("batch");
@@ -1249,7 +1653,7 @@ function shortSummary(mission) {
 
 function formatPreflight({ command, preflight, fuel }) {
   const fuelLine = fuel.currentPercent === null
-    ? "Fuel: unknown. Set it with `aim fuel set <percent>` if using subscriptions."
+    ? "Fuel: unknown. Set it with `runcap fuel set <percent>` if using subscriptions."
     : `Fuel: ${fuel.currentPercent}% (${fuel.confidence} confidence)`;
   const scopeAdvice = preflight.scopeRisk === "high"
     ? "Do not launch as one broad mission. Split into one vertical slice with a verification command."
@@ -1273,7 +1677,7 @@ function formatPreflight({ command, preflight, fuel }) {
 
 function formatReport(mission) {
   const fuel = mission.fuelUsedPercent === null
-    ? `Fuel: before ${mission.fuelBefore ?? "unknown"}%, after unknown. Calibrate with \`aim fuel calibrate ${mission.id} <after-percent>\`.`
+    ? `Fuel: before ${mission.fuelBefore ?? "unknown"}%, after unknown. Calibrate with \`runcap fuel calibrate ${mission.id} <after-percent>\`.`
     : `Fuel used: ${mission.fuelUsedPercent}% (source: manual calibration, confidence: high).`;
   const errorLines = mission.errors.length
     ? mission.errors.map((error) => `- ${error.kind} (${error.confidence}): ${error.raw}`).join("\n")
@@ -1287,7 +1691,7 @@ function formatReport(mission) {
     `   Next action: ${rec.nextAction}`,
     `   Rescue prompt: ${rec.prompt}`
   ].join("\n")).join("\n\n");
-  return `# AI Mission Report
+  return `# Runcap Mission Report
 
 Mission: ${mission.id}
 Command: \`${mission.command.join(" ")}\`
@@ -1396,7 +1800,7 @@ function formatHtmlReport(mission) {
 <head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>AI Mission Report - ${escapeHtml(mission.label ?? mission.id)}</title>
+  <title>Runcap Mission Report - ${escapeHtml(mission.label ?? mission.id)}</title>
   <style>
     :root { color-scheme: dark; --bg:#0f1115; --panel:#181c22; --soft:#202630; --line:#303946; --text:#f5f7fb; --muted:#a7b0bd; --accent:#70d6ff; --warn:#ffd166; --bad:#ff6b6b; --good:#55d78a; }
     * { box-sizing:border-box; }
@@ -1478,78 +1882,96 @@ function renderDashboardHtml() {
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1">
   <title>Runcap</title>
+  <link rel="preconnect" href="https://api.fontshare.com" crossorigin>
+  <link href="https://api.fontshare.com/v2/css?f[]=clash-display@600,700&f[]=general-sans@400,500,600,700&f[]=jetbrains-mono@400,500&display=swap" rel="stylesheet">
   <style>
-    :root { color-scheme: dark; --bg:#080d13; --panel:#111821; --panel2:#17212d; --soft:#202b38; --line:#2c3948; --text:#f8fafc; --muted:#a8b3c2; --good:#52d789; --warn:#ffd166; --bad:#ff6868; --accent:#63d5ff; --violet:#b8a0ff; }
+    :root { color-scheme: light; --bg:#f6f7f9; --panel:#ffffff; --panel2:#fbfbfc; --soft:#f0f2f5; --line:#e6e8ec; --text:#0b0d12; --muted:#6b7280; --good:#0d9f6e; --warn:#b7791f; --bad:#dc2626; --accent:#4f46e5; --violet:#7c3aed; --shadow:0 1px 2px rgba(16,24,40,0.04), 0 8px 24px rgba(16,24,40,0.06); }
     * { box-sizing: border-box; }
-    body { margin:0; min-height:100vh; font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background:var(--bg); color:var(--text); }
-    body:before { content:""; position:fixed; inset:0; pointer-events:none; background:radial-gradient(circle at 20% 0%, rgba(99,213,255,0.12), transparent 32%), radial-gradient(circle at 90% 8%, rgba(184,160,255,0.1), transparent 34%), linear-gradient(180deg, rgba(255,255,255,0.03), transparent 260px); }
+    body { margin:0; min-height:100vh; font-family: "General Sans", ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background:var(--bg); color:var(--text); }
+    body:before { content:""; position:fixed; inset:0; pointer-events:none; background:radial-gradient(circle at 18% -4%, rgba(79,70,229,0.06), transparent 36%), radial-gradient(circle at 92% 4%, rgba(124,58,237,0.05), transparent 38%); }
     button, textarea, select, input { font:inherit; }
     .app { position:relative; display:grid; grid-template-columns: 320px minmax(0,1fr); min-height:100vh; }
-    aside { border-right:1px solid var(--line); background:rgba(8,13,19,0.82); padding:22px; overflow:auto; }
-    main { padding:28px; overflow:auto; }
-    h1 { margin:0; font-size:24px; letter-spacing:0; }
-    h2 { margin:0; font-size:38px; line-height:1.06; letter-spacing:0; }
-    h3 { margin:0; font-size:15px; }
+    aside { border-right:1px solid var(--line); background:var(--panel); padding:22px; overflow:auto; }
+    main { padding:32px 36px; overflow:auto; }
+    h1 { margin:0; font-family:"Clash Display", sans-serif; font-weight:700; font-size:23px; letter-spacing:-0.01em; }
+    h2 { margin:0; font-family:"Clash Display", sans-serif; font-weight:600; font-size:34px; line-height:1.08; letter-spacing:-0.02em; }
+    h3 { margin:0; font-family:"Clash Display", sans-serif; font-weight:600; font-size:15px; }
     p { margin:0; }
     .muted { color:var(--muted); }
     .brand { display:flex; align-items:center; gap:12px; margin-bottom:22px; }
-    .mark { width:42px; height:42px; border-radius:8px; display:grid; place-items:center; color:#061017; font-weight:900; background:linear-gradient(135deg, var(--accent), var(--good)); }
-    .tagline { color:var(--muted); font-size:13px; margin-top:4px; line-height:1.35; }
+    .mark { width:40px; height:40px; border-radius:11px; display:grid; place-items:center; color:#fff; font-family:"Clash Display",sans-serif; font-weight:700; background:linear-gradient(135deg, var(--accent), var(--violet)); box-shadow:var(--shadow); }
+    .tagline { color:var(--muted); font-size:13px; margin-top:3px; line-height:1.35; }
     .nav { display:grid; gap:8px; margin:18px 0 22px; }
-    .nav button { text-align:left; border:1px solid var(--line); background:rgba(17,24,33,0.82); color:var(--text); border-radius:8px; padding:12px; cursor:pointer; }
-    .nav button.active, .nav button:hover { border-color:var(--accent); background:#152434; }
-    .nav strong { display:block; }
+    .nav button { text-align:left; border:1px solid var(--line); background:var(--panel); color:var(--text); border-radius:11px; padding:12px 14px; cursor:pointer; transition:all .15s; }
+    .nav button.active, .nav button:hover { border-color:var(--accent); background:#f5f4ff; }
+    .nav strong { display:block; font-weight:600; }
     .nav span { display:block; color:var(--muted); font-size:12px; margin-top:3px; }
-    .side-title { margin:18px 0 10px; color:var(--muted); font-size:12px; font-weight:800; text-transform:uppercase; }
+    .side-title { margin:18px 0 10px; color:var(--muted); font-size:11px; font-weight:600; letter-spacing:0.06em; text-transform:uppercase; }
     .summary { display:grid; grid-template-columns:repeat(2,minmax(0,1fr)); gap:10px; }
-    .mini, .panel, .mission, .metric, .step, .plan-card, details { border:1px solid var(--line); background:rgba(17,24,33,0.9); border-radius:8px; }
-    .mini { padding:12px; min-height:76px; }
-    .mini strong { display:block; font-size:22px; }
+    .mini, .panel, .mission, .metric, .step, .plan-card, details { border:1px solid var(--line); background:var(--panel); border-radius:14px; }
+    .mini { padding:13px; min-height:76px; box-shadow:var(--shadow); }
+    .mini strong { display:block; font-family:"JetBrains Mono",monospace; font-size:22px; font-weight:500; }
     .mini span { color:var(--muted); font-size:12px; }
-    .mission { width:100%; color:inherit; text-align:left; cursor:pointer; margin:0 0 10px; padding:12px; }
+    .mission { width:100%; color:inherit; text-align:left; cursor:pointer; margin:0 0 10px; padding:13px; transition:all .15s; }
     .mission:hover, .mission.active { border-color:var(--accent); }
-    .mission.active { background:#142232; box-shadow: inset 3px 0 0 var(--accent); }
+    .mission.active { background:#f5f4ff; box-shadow: inset 3px 0 0 var(--accent); }
     .mission-head { display:flex; align-items:center; justify-content:space-between; gap:8px; margin-bottom:7px; }
-    .mission-name { font-weight:800; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
+    .mission-name { font-weight:600; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; }
     .mission-line { color:var(--muted); font-size:13px; line-height:1.35; }
-    .status { font-size:12px; border:1px solid var(--line); padding:4px 8px; border-radius:999px; white-space:nowrap; }
-    .stuck { color:var(--bad); border-color:rgba(255,104,104,0.5); }
-    .at_risk { color:var(--warn); border-color:rgba(255,209,102,0.5); }
-    .progressing { color:var(--good); border-color:rgba(82,215,137,0.5); }
+    .status { font-size:12px; border:1px solid var(--line); padding:4px 9px; border-radius:999px; white-space:nowrap; font-weight:500; }
+    .stuck { color:var(--bad); border-color:rgba(220,38,38,0.35); background:rgba(220,38,38,0.05); }
+    .at_risk { color:var(--warn); border-color:rgba(183,121,31,0.35); background:rgba(183,121,31,0.05); }
+    .progressing { color:var(--good); border-color:rgba(13,159,110,0.35); background:rgba(13,159,110,0.05); }
     .hero { display:grid; grid-template-columns:minmax(0,1.2fr) minmax(360px,0.8fr); gap:18px; margin-bottom:18px; }
-    .panel { padding:24px; }
-    .hero-copy { color:var(--muted); font-size:17px; line-height:1.55; margin-top:14px; max-width:880px; }
+    .panel { padding:26px; box-shadow:var(--shadow); }
+    .hero-copy { color:var(--muted); font-size:16px; line-height:1.55; margin-top:14px; max-width:880px; }
+    /* SAVINGS HERO — the one visible number (Kirill's core fix) */
+    .savings { grid-column:1 / -1; border:1px solid var(--line); border-radius:18px; padding:28px 30px; margin-bottom:18px; background:linear-gradient(135deg,#ffffff, #f7f6ff); box-shadow:var(--shadow); }
+    .savings-label { font-size:12px; font-weight:600; letter-spacing:0.08em; text-transform:uppercase; color:var(--muted); }
+    .savings-row { display:flex; align-items:flex-end; gap:14px; flex-wrap:wrap; margin-top:8px; }
+    .savings-big { font-family:"Clash Display",sans-serif; font-weight:700; font-size:clamp(40px,6vw,68px); line-height:1; letter-spacing:-0.03em; background:linear-gradient(135deg,var(--accent),var(--violet)); -webkit-background-clip:text; background-clip:text; -webkit-text-fill-color:transparent; }
+    .savings-unit { font-family:"JetBrains Mono",monospace; font-size:17px; color:var(--muted); padding-bottom:8px; }
+    .savings-sub { color:var(--muted); font-size:15px; margin-top:12px; }
+    .savings-sub b { color:var(--text); font-family:"JetBrains Mono",monospace; font-weight:500; }
+    .capbar { margin-top:18px; }
+    .capbar-track { height:12px; border-radius:999px; background:var(--soft); overflow:hidden; border:1px solid var(--line); }
+    .capbar-fill { height:100%; border-radius:999px; background:linear-gradient(90deg,var(--good),var(--accent)); transition:width .4s; }
+    .capbar-fill.warn { background:linear-gradient(90deg,var(--warn),#e8590c); }
+    .capbar-fill.over { background:linear-gradient(90deg,var(--bad),#991b1b); }
+    .capbar-meta { display:flex; justify-content:space-between; font-size:12px; color:var(--muted); margin-top:7px; font-family:"JetBrains Mono",monospace; }
     .badge-row { display:flex; flex-wrap:wrap; gap:8px; margin-top:18px; }
-    .badge { display:inline-flex; align-items:center; gap:6px; border:1px solid var(--line); color:var(--muted); border-radius:999px; padding:6px 10px; font-size:12px; }
-    .badge.good { color:var(--good); border-color:rgba(82,215,137,0.48); }
-    .badge.warn { color:var(--warn); border-color:rgba(255,209,102,0.48); }
-    .badge.bad { color:var(--bad); border-color:rgba(255,104,104,0.48); }
+    .badge { display:inline-flex; align-items:center; gap:6px; border:1px solid var(--line); color:var(--muted); border-radius:999px; padding:6px 11px; font-size:12px; background:var(--panel2); }
+    .badge.good { color:var(--good); border-color:rgba(13,159,110,0.35); }
+    .badge.warn { color:var(--warn); border-color:rgba(183,121,31,0.35); }
+    .badge.bad { color:var(--bad); border-color:rgba(220,38,38,0.35); }
     .metrics { display:grid; grid-template-columns:repeat(4,minmax(0,1fr)); gap:10px; margin-top:20px; }
-    .metric { padding:14px; }
-    .metric strong { display:block; font-size:24px; line-height:1.1; }
+    .metric { padding:15px; box-shadow:var(--shadow); }
+    .metric strong { display:block; font-family:"JetBrains Mono",monospace; font-size:23px; font-weight:500; line-height:1.1; }
     .metric span { display:block; color:var(--muted); font-size:12px; margin-top:6px; }
-    .planner textarea { width:100%; min-height:128px; resize:vertical; background:#0a1017; color:var(--text); border:1px solid var(--line); border-radius:8px; padding:13px; line-height:1.45; }
+    .planner textarea { width:100%; min-height:128px; resize:vertical; background:var(--panel2); color:var(--text); border:1px solid var(--line); border-radius:11px; padding:13px; line-height:1.45; }
     .field-row { display:grid; grid-template-columns:1fr 1fr; gap:10px; margin-top:10px; }
-    select, input { width:100%; background:#0a1017; color:var(--text); border:1px solid var(--line); border-radius:8px; padding:10px; }
-    label { display:block; color:var(--muted); font-size:12px; font-weight:750; margin:0 0 7px; }
-    .primary, .ghost { border-radius:8px; padding:10px 13px; cursor:pointer; font-weight:800; }
-    .primary { border:1px solid rgba(99,213,255,0.7); color:#061017; background:linear-gradient(135deg, var(--accent), var(--good)); }
-    .ghost { border:1px solid var(--line); color:var(--text); background:#0a1017; }
+    select, input { width:100%; background:var(--panel2); color:var(--text); border:1px solid var(--line); border-radius:11px; padding:11px; }
+    label { display:block; color:var(--muted); font-size:12px; font-weight:600; margin:0 0 7px; }
+    .primary, .ghost { border-radius:11px; padding:11px 16px; cursor:pointer; font-weight:600; transition:all .15s; }
+    .primary { border:1px solid transparent; color:#fff; background:linear-gradient(135deg, var(--accent), var(--violet)); box-shadow:0 6px 16px rgba(79,70,229,0.25); }
+    .primary:hover { filter:brightness(1.06); transform:translateY(-1px); }
+    .ghost { border:1px solid var(--line); color:var(--text); background:var(--panel); }
+    .ghost:hover { border-color:var(--accent); }
     .actions { display:flex; gap:10px; flex-wrap:wrap; margin-top:12px; }
     .plan-grid { display:grid; grid-template-columns:repeat(3,minmax(0,1fr)); gap:12px; margin:18px 0; }
-    .plan-card { padding:16px; }
-    .plan-card strong { display:block; margin-bottom:8px; }
+    .plan-card { padding:18px; box-shadow:var(--shadow); }
+    .plan-card strong { display:block; margin-bottom:8px; font-weight:600; }
     .plan-card p, .step p { color:var(--muted); line-height:1.48; }
     .timeline { display:grid; gap:10px; margin-top:14px; }
-    .step { padding:15px; display:grid; grid-template-columns:34px minmax(0,1fr); gap:12px; align-items:start; }
-    .num { width:28px; height:28px; border-radius:8px; display:grid; place-items:center; background:#0a1017; border:1px solid var(--line); color:var(--accent); font-weight:900; }
-    .rescue { border-color:rgba(99,213,255,0.55); background:#172433; }
-    .decision { color:var(--warn); font-weight:900; font-size:18px; margin:8px 0 0; }
-    pre { white-space:pre-wrap; margin:12px 0 0; background:#070b10; border:1px solid var(--line); border-radius:8px; padding:13px; line-height:1.5; overflow:auto; }
-    details { padding:14px 16px; margin-top:14px; }
-    summary { cursor:pointer; color:var(--muted); font-weight:800; }
+    .step { padding:16px; display:grid; grid-template-columns:34px minmax(0,1fr); gap:12px; align-items:start; box-shadow:var(--shadow); }
+    .num { width:28px; height:28px; border-radius:9px; display:grid; place-items:center; background:#f5f4ff; border:1px solid var(--line); color:var(--accent); font-family:"JetBrains Mono",monospace; font-weight:500; }
+    .rescue { border-color:rgba(79,70,229,0.4); background:linear-gradient(135deg,#ffffff,#f7f6ff); }
+    .decision { color:var(--bad); font-weight:600; font-size:18px; margin:8px 0 0; }
+    pre { white-space:pre-wrap; margin:12px 0 0; background:#0b0d12; color:#e6e8ec; border:1px solid var(--line); border-radius:11px; padding:14px; line-height:1.5; overflow:auto; font-family:"JetBrains Mono",monospace; font-size:13px; }
+    details { padding:14px 18px; margin-top:14px; box-shadow:var(--shadow); }
+    summary { cursor:pointer; color:var(--muted); font-weight:600; }
     .hidden { display:none; }
-    .empty { padding:40px; text-align:left; }
+    .empty { padding:42px; text-align:left; }
     .copy { margin-top:10px; }
     @media (max-width: 1180px) { .app { grid-template-columns:1fr; } aside { border-right:0; border-bottom:1px solid var(--line); } .hero, .plan-grid, .metrics { grid-template-columns:1fr; } .field-row { grid-template-columns:1fr; } }
   </style>
@@ -1558,10 +1980,10 @@ function renderDashboardHtml() {
   <div class="app">
     <aside>
       <div class="brand">
-        <div class="mark">AI</div>
+        <div class="mark">R</div>
         <div>
           <h1>Runcap</h1>
-          <div class="tagline">Plan AI work. Route models. Prove progress. Stop waste.</div>
+          <div class="tagline">Estimate cost. Cap spend. Compress tokens. Rescue stuck runs.</div>
         </div>
       </div>
       <div class="nav">
@@ -1574,10 +1996,10 @@ function renderDashboardHtml() {
         <div class="mission-line" id="truth">Gateway truth: loading...</div>
       </div>
       <div class="summary">
-        <div class="mini"><strong id="total">0</strong><span>checks</span></div>
-        <div class="mini"><strong id="needs">0</strong><span>need attention</span></div>
+        <div class="mini"><strong id="cost">$0</strong><span>spent so far</span></div>
+        <div class="mini"><strong id="saved" style="color:var(--good)">$0</strong><span>saved by compression</span></div>
         <div class="mini"><strong id="tokens">0</strong><span>API tokens</span></div>
-        <div class="mini"><strong id="cost">$0</strong><span>API estimate</span></div>
+        <div class="mini"><strong id="needs">0</strong><span>need attention</span></div>
       </div>
       <div class="side-title">Saved plans</div>
       <div id="plans"></div>
@@ -1602,13 +2024,16 @@ function renderDashboardHtml() {
       state.plans = plans;
       document.getElementById("fuel").textContent = status.fuel.currentPercent === null ? "Fuel: unknown" : "Fuel: " + status.fuel.currentPercent + "%";
       document.getElementById("truth").textContent = "Gateway truth: " + status.gateway.truth;
-      document.getElementById("total").textContent = status.missionCount;
       document.getElementById("needs").textContent = (status.counts.stuck ?? 0) + (status.counts.at_risk ?? 0);
-      document.getElementById("tokens").textContent = status.gateway.totalTokens;
-      document.getElementById("cost").textContent = "$" + status.gateway.estimatedCostUsd;
+      document.getElementById("tokens").textContent = Number(status.gateway.totalTokens || 0).toLocaleString();
+      document.getElementById("cost").textContent = "$" + (status.gateway.estimatedCostUsd ?? 0);
+      document.getElementById("saved").textContent = "$" + (status.gateway.savedUsd ?? 0);
+      state.gateway = status.gateway;
+      state.budget = status.budget;
       renderList();
       renderPlans();
       if (!state.plannerRendered) renderPlanner(status);
+      renderSavingsHero(status.gateway);
       if (!state.selected && missions[0]) showMission(missions[0].id, false);
       if (!missions[0]) renderEmptyMonitor();
     }
@@ -1637,10 +2062,40 @@ function renderDashboardHtml() {
         '</button>'
       ).join("");
     }
+    function renderSavingsHero(g) {
+      const el = document.getElementById("savings-hero");
+      if (!el || !g) return;
+      const saved = Number(g.savedUsd ?? 0);
+      const tokens = Number(g.savedTokens ?? 0);
+      const spent = Number(g.estimatedCostUsd ?? 0);
+      const wouldHave = Number(g.wouldHaveSpentUsd ?? spent);
+      const fmt = (n) => "$" + (n < 0.01 && n > 0 ? n.toFixed(4) : n.toFixed(2));
+      if (tokens === 0 && spent === 0) {
+        el.innerHTML = '<div class="savings"><div class="savings-label">Your savings will show here</div>' +
+          '<div class="savings-row"><div class="savings-big">$0.00</div><div class="savings-unit">saved so far</div></div>' +
+          '<div class="savings-sub">Point your agent at the Runcap gateway and every call is compressed and capped. This number grows on its own.</div></div>';
+        return;
+      }
+      // cap bar
+      let capHtml = '';
+      if (state.budget && state.budget > 0) {
+        const pct = Math.min(100, (spent / state.budget) * 100);
+        const cls = pct >= 100 ? 'over' : pct >= 80 ? 'warn' : '';
+        capHtml = '<div class="capbar"><div class="capbar-track"><div class="capbar-fill ' + cls + '" style="width:' + pct.toFixed(1) + '%"></div></div>' +
+          '<div class="capbar-meta"><span>spent ' + fmt(spent) + '</span><span>cap ' + fmt(state.budget) + '</span></div></div>';
+      }
+      el.innerHTML = '<div class="savings">' +
+        '<div class="savings-label">You saved</div>' +
+        '<div class="savings-row"><div class="savings-big">' + fmt(saved) + '</div><div class="savings-unit">' + tokens.toLocaleString() + ' tokens compressed away</div></div>' +
+        '<div class="savings-sub">You would have spent <b>' + fmt(wouldHave) + '</b>, Runcap compressed it down to <b>' + fmt(spent) + '</b>. Same answers, fewer tokens.</div>' +
+        capHtml +
+        '</div>';
+    }
     function renderPlanner(status) {
       state.plannerRendered = true;
       const fuel = status.fuel.currentPercent === null ? 24 : Number(status.fuel.currentPercent);
       document.getElementById("plan-view").innerHTML =
+        '<div id="savings-hero"></div>' +
         '<div class="hero">' +
         '<div class="panel">' +
         '<h2>Turn one expensive AI request into a managed plan.</h2>' +