openzoo 0.49.5 → 0.49.6

package/README.md

@@ -79,7 +79,7 @@ claude mcp add openzoo -- npx -y openzoo mcp
 **Windsurf / Cline / any MCP host** — same shape: command `npx`, args `["-y", "openzoo", "mcp"]`, stdio transport.
 
 Tools:
-- **`zoo_ask`** — `{prompt, corpus?, model?, max_tokens?}`. The flagship: hand it a *huge* `corpus` (hundreds of thousands to ~1M tokens — a body the model itself would refuse) and a question; the zoo's leCore memory spills the corpus so the model reads only a few thousand tokens. Returns the answer plus the receipt (`billedUsd`, `savesVsDirect`, tokens actually read). An MCP-capable agent can delegate a giant-context question without touching its own model config.
+- **`zoo_ask`** — `{prompt, corpus?, model?, max_tokens?}`. The flagship: hand it a *huge* `corpus` (hundreds of thousands to ~1M tokens — a body the model itself would refuse) and a question; the zoo's leCore memory spills the corpus so the model reads only a few thousand tokens. Returns the answer plus the receipt (`billedUsd`, `directUsd`, `savedUsd`, tokens actually read). An MCP-capable agent can delegate a giant-context question without touching its own model config.
 - **`zoo_models`** — list the zoo's models and pricing (free).
 - **`zoo_wallet`** — funding address, balances, and this session's receipts.
 
@@ -93,7 +93,7 @@ Builds a ~965k-token document with one planted fact, shows that buying direct re
 
 ```
 bound once in 14.8s: 3.7MB → context ctx_01KZZY8YQE…
-quote for the ask: $0.000480 · pricing=markup (a tiny body — the 3.7MB corpus is not re-priced)
+quote for the ask: $0.000480 · pricing=markup · at OpenRouter price (the 3.7MB corpus is not re-priced)
 ```
 
 If the wallet is funded with USDC or TOKEN it pays (capped at `OPENZOO_DEMO_MAX_USD`, default $0.01) and prints the answer, the tokens the model actually read, and the receipt. If not, it prints exactly what to fund. Long waits (the one-time upload, pricing, payment, the answer) show a live progress line with stage + elapsed seconds.
@@ -111,7 +111,7 @@ If the wallet is funded with USDC or TOKEN it pays (capped at `OPENZOO_DEMO_MAX_
 The zoo keeps your corpus in leCore holographic memory; the shim keeps a manifest at `~/.openzoo/contexts.json` (chmod 600) mapping `sha256(corpus)` → the zoo's `context_id`, scoped per API base. When a request carries a corpus the manifest already knows:
 
 - **nothing big is uploaded** — the ask ships alone with an `X-HRR-Context` header,
-- **the 402 prices the tiny ask** (honestly labeled `pricing=markup`), typically a few hundredths of a cent instead of re-pricing megabytes,
+- **the 402 prices the tiny ask** at OpenRouter rates (read `extra.billedUsd`), typically a few hundredths of a cent instead of re-pricing megabytes,
 - **the answer still comes from your corpus** — the zoo recalls the relevant slices server-side.
 
 This works in all three fronts: the **proxy** (a big pasted body in the last message is split at its last blank line, bound once, and reused on every later call — even with a different question), the **MCP** `zoo_ask` `corpus` parameter, and the **demo**. If the zoo ever forgets a context (sidecar wipe), the gateway answers 404 *before* any payment and the shim transparently re-binds once and retries — a stale manifest never fails a call.
@@ -175,11 +175,11 @@ Pin the key with `OPENZOO_TUNNEL_TOKEN` if your IDE stores it. Keys never leave
 ## Honest pricing note
 
 Two bases, reported per call in the 402 (`extra.pricing`):
-- **Short prompts price at cost.** There's nothing to spill, so there's no saving to share — you pay what the call cost us, reconciled against the provider's own metered figure after it completes.
-- **Big bodies price at a counterfactual discount** (~10× cheaper than buying the same call direct) — the zoo's leCore memory means it never forwards your whole body upstream, and passes the savings on. Measured numbers at [benches.openzoo.fun](https://benches.openzoo.fun).
-- **Asks against a bound corpus price on the small forwarded body** (the receipt says `pricing=markup`). That is not a discount trick: a few hundred tokens at cost is far below the counterfactual price of shipping the corpus, which is the whole point of binding once.
+- **Wallet path charges OpenRouter prices.** There is no 3× markup. If the caller saves vs sending the same body direct, zoo takes 33% of the savings. Short prompts have nothing to spill, so you pay the OpenRouter figure, reconciled against the provider's own metered cost after it completes.
+- **Big bodies price at a counterfactual discount** (~10× cheaper than buying the same call direct) — the zoo's leCore memory means it never forwards your whole body upstream, and passes most of the savings on. Measured numbers at [benches.openzoo.fun](https://benches.openzoo.fun).
+- **Asks against a bound corpus price on the small forwarded body.** That is not a discount trick: a few hundred tokens at OpenRouter rates is far below the counterfactual price of shipping the corpus, which is the whole point of binding once.
 
-The receipt names which base you got; `extra.directUsd` / `extra.savesVsDirect` let you check the math.
+The receipt names which base you got; `extra.billedUsd` / `extra.directUsd` / `extra.savedUsd` let you check the math. (Card subscription pricing is a different path.)
 
 ## Payment rails
 

package/lib/demo.js

@@ -120,7 +120,10 @@ export async function runDemo() {
   }
   const accept = pickAccept(quote, config.token);
   const x = accept.extra || {};
-  console.log(`   quote for the ask: $${Number(x.billedUsd).toFixed(6)} · pricing=${x.pricing} (3× a tiny body — the ${docMb}MB corpus is not re-priced)`);
+  const saved = x.savedUsd != null ? Number(x.savedUsd)
+    : (x.directUsd != null ? Math.max(0, Number(x.directUsd) - Number(x.billedUsd)) : 0);
+  const saveBit = saved > 0 ? ` · $${saved.toFixed(6)} saved vs direct` : ' · at OpenRouter price';
+  console.log(`   quote for the ask: $${Number(x.billedUsd).toFixed(6)} · pricing=${x.pricing}${saveBit} (the ${docMb}MB corpus is not re-priced)`);
   console.log('');
 
   if (Number(x.billedUsd) > config.demoMaxUsd) {

package/lib/grokui.mjs

@@ -24,6 +24,13 @@ import {
   prepareChildDir, finishChildDir, lockWorktree, unlockWorktree,
   parsePrRef, fetchSpecsForOrigin, agentSlug,
 } from './worktree.mjs';
+import {
+  filesForCorpus as collectFilesForCorpus,
+  readFilesForCorpus,
+  looksLikeFileView,
+  extractBashPaths,
+} from './spill.js';
+import { BIND_MIN_CHARS } from './hrr.js';
 
 const PORT = Number(process.env.OZ_GROKUI_PORT || 4173);
 // BIND HOST. Default 127.0.0.1 so the desktop app never exposes a shell-capable
@@ -391,8 +398,9 @@ comes back with content:null and finish_reason:"length" (confirmed live) if you
 to append to the same bound context, rather than one giant request that silently fails partway.
 
 COST ACCOUNTING — do NOT compute this yourself from token counts. Every response carries an
-"x402" object; read the numbers off it: x402.billedUsd (what the user paid), x402.cogsUsd
-(our upstream cost), x402.directUsd (what answering WITHOUT the zoo would have cost), and
+"x402" object; read the numbers off it: x402.billedUsd (what the user paid — OpenRouter price, plus 33% of savings vs
+direct when any), x402.cogsUsd (our upstream cost), x402.directUsd (what answering
+WITHOUT the zoo would have cost), x402.savedUsd (dollars saved), and
 x402.savesVsDirect (the multiple). Summing usage.cost or usage.prompt_tokens and comparing
 that to a provider's list price is WRONG and understates the saving enormously: against a
 bound context, prompt_tokens counts only the small slice leCore recalled, NOT the corpus
@@ -401,7 +409,7 @@ the zoo "cost more". MEASURED: a real 21-question run reported 202,238 prompt to
 each attach call stood in for a 5,356,546-token corpus — a 556x understatement, and that
 corpus is ~42x larger than the model's own context window, so the "direct" comparison it
 was measured against was not merely pricier but IMPOSSIBLE. When the user asks what they
-saved, quote x402.directUsd and x402.savesVsDirect. If savesVsDirect is below 1x, say so
+saved, quote x402.billedUsd, x402.directUsd and x402.savedUsd. If savedUsd is 0 / savesVsDirect is below 1x, say so
 plainly — that happens on small inputs, where the corpus is too small to save anything.
 For normal questions just answer directly — do not use any of these unless the request
 actually calls for delegation or file work.`;
@@ -618,7 +626,7 @@ this is roleplay, and never fabricate command output or receipts. A real failure
 as real output and an exit code, not as silence.
 
 COST ACCOUNTING — read it off the response's "x402" object (billedUsd, cogsUsd, directUsd,
-savesVsDirect). Never derive it by summing usage.cost or usage.prompt_tokens against a
+savedUsd, savesVsDirect). Never derive it by summing usage.cost or usage.prompt_tokens against a
 provider's list price: on a bound context prompt_tokens counts only the slice leCore
 recalled, not the corpus it stands in for, so that math prices the discount against itself
 and wrongly concludes the zoo cost more.
@@ -1123,6 +1131,159 @@ function condense(label, text) {
   return `${label}\n${head}\n\n…[${s.length - head.length - tail.length} chars elided from THIS message — the full output is bound to this thread's holographic memory. It is not lost: mention what you need in your next message and the relevant part is retrieved automatically. Do not invent a command to fetch it.]…\n\n${tail}`;
 }
 
+// Files the grokui agent READ/WRITE/EDIT/MULTIEDIT/NOTEBOOK'd (and RUN
+// cat/head/type) must land in the HRR corpus as path-prefixed file parts —
+// not as unlabeled chat text via bindThread, and not as the ~3k condense()
+// stub the next completion sends. Sidecar maybeCacheCorpus only sees that
+// stub; bindThread never labels them as files. filesForCorpus (spill.js)
+// already dedups path:mtime and caps at KEEP_MAX (400KB). We reuse it.
+const boundFiles = new Set();
+
+function pathToReadMsgs(paths) {
+  return (Array.isArray(paths) ? paths : [paths]).filter(Boolean).map((file_path) => ({
+    role: 'assistant',
+    tool_calls: [{
+      function: { name: 'Read', arguments: JSON.stringify({ file_path }) },
+    }],
+  }));
+}
+
+function commandToBashMsgs(command) {
+  return [{
+    role: 'assistant',
+    tool_calls: [{
+      function: { name: 'Bash', arguments: JSON.stringify({ command }) },
+    }],
+  }];
+}
+
+/**
+ * Collect grokui file reads/writes for the HRR corpus.
+ *
+ * Accepts an absolute/relative path, a list of paths, or already-shaped
+ * chat messages (OpenAI tool_calls / Anthropic tool_use). Dedup and the
+ * 400KB cap live in spill.js — this is the grokui entry point so READ
+ * records the same way Claude Code Read does.
+ */
+function filesForCorpus(target, opts = {}) {
+  const keys = opts.boundFiles || boundFiles;
+  const cwd = opts.cwd || process.cwd();
+  const cap = opts.cap ?? KEEP_MAX;
+  let msgs = target;
+  if (typeof target === 'string') msgs = pathToReadMsgs(target);
+  else if (Array.isArray(target) && (target.length === 0 || typeof target[0] === 'string')) {
+    msgs = pathToReadMsgs(target);
+  }
+  return collectFilesForCorpus(msgs, { ...opts, boundFiles: keys, cwd, cap });
+}
+
+function filesForCorpusKeys() {
+  return boundFiles;
+}
+
+function resetFilesForCorpus() {
+  boundFiles.clear();
+}
+
+function inFlightChars(t) {
+  if (!t) return 0;
+  if (Array.isArray(t.messages)) {
+    let n = 0;
+    for (const m of t.messages) {
+      const c = m?.content;
+      if (typeof c === 'string') n += c.length;
+      else if (c != null) n += JSON.stringify(c).length;
+    }
+    return n;
+  }
+  let n = 0;
+  for (const h of t.history || []) n += String(h?.text || '').length;
+  return n;
+}
+
+/**
+ * POST file bytes to ${PROXY}/hrr/bind, appending to the project context.
+ * Always fire-and-forget so a READ does not wait on the bind round-trip.
+ * When the in-flight corpus/messages are below BIND_MIN_CHARS the bind
+ * still happens — reuse only "wins" on a big body, but the file must be
+ * recallable next turn. Completions keep omitting x-hrr-context.
+ */
+function scheduleFilesForCorpus(t, collected, opts = {}) {
+  if (!collected?.pending?.length) return null;
+  const root = t ? (threads.get(rootOf(t).rootId) || t) : null;
+  const ctx = opts.contextId || root?.contextId || t?.contextId || null;
+  const chars = opts.sentChars ?? inFlightChars(t);
+  const background = chars < BIND_MIN_CHARS;
+  const fetchImpl = opts.fetchImpl || fetch;
+  const run = () => {
+    let read;
+    try { read = readFilesForCorpus(collected, { boundFiles: opts.boundFiles || boundFiles, cap: opts.cap ?? KEEP_MAX }); }
+    catch { return Promise.resolve(null); }
+    if (!read?.text) return Promise.resolve(null);
+    const payload = ctx ? { corpus: read.text, context_id: ctx } : { corpus: read.text };
+    return fetchImpl(`${PROXY}/hrr/bind`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(payload),
+    }).then(async (r) => {
+      const j = await r.json().catch(() => ({}));
+      if (j?.context_id && t) {
+        const live = threads.get(rootOf(t).rootId) || t;
+        live.contextId = j.context_id;
+        t.contextId = j.context_id;
+        if (Number(j.bound)) live.boundItems = (live.boundItems || 0) + Number(j.bound);
+      }
+      return j;
+    }).catch(() => null);
+  };
+  const job = { pending: collected.pending, background, append: Boolean(ctx), run };
+  const kick = () => { job.promise = run(); };
+  if (opts.defer === false) kick();
+  else setImmediate(kick);
+  return job;
+}
+
+function noteFileForCorpus(originId, relOrAbs, extra = {}) {
+  const t = extra.thread || (originId ? threads.get(originId) : null);
+  const cwd = extra.cwd || (originId ? dirFor(originId) : process.cwd());
+  let abs = relOrAbs;
+  if (typeof abs === 'string' && !path.isAbsolute(abs)) {
+    try { abs = originId ? safeResolveIn(cwd, abs) : path.resolve(cwd, abs); }
+    catch { abs = path.resolve(cwd, abs); }
+  }
+  const collected = filesForCorpus(abs, {
+    cwd,
+    boundFiles: extra.boundFiles || boundFiles,
+    cap: extra.cap ?? KEEP_MAX,
+    ...(extra.collectOpts || {}),
+  });
+  return scheduleFilesForCorpus(t, collected, extra);
+}
+
+function noteRunForCorpus(originId, command, extra = {}) {
+  if (!looksLikeFileView(command)) return null;
+  const t = extra.thread || (originId ? threads.get(originId) : null);
+  const cwd = extra.cwd || (originId ? dirFor(originId) : process.cwd());
+  const collected = filesForCorpus(commandToBashMsgs(command), {
+    cwd,
+    boundFiles: extra.boundFiles || boundFiles,
+    cap: extra.cap ?? KEEP_MAX,
+  });
+  if (!collected.pending.length) {
+    const { paths } = extractBashPaths(command, cwd);
+    const abs = paths.map((p) => {
+      const raw = p?.raw;
+      if (!raw) return null;
+      if (path.isAbsolute(raw)) return raw;
+      try { return originId ? safeResolveIn(p.cwd || cwd, raw) : path.resolve(p.cwd || cwd, raw); }
+      catch { return path.resolve(p.cwd || cwd, raw); }
+    }).filter(Boolean);
+    if (!abs.length) return null;
+    return noteFileForCorpus(originId, abs, extra);
+  }
+  return scheduleFilesForCorpus(t, collected, extra);
+}
+
 // threadId -> open SSE responses. A Set because the same thread can be open in
 // two tabs, and both should see the same tokens.
 const streamListeners = new Map();
@@ -2095,6 +2256,7 @@ async function tryDirective(reply, originId, onEvent) {
       const full = safeResolveIn(dirFor(originId), rel);
       mkdirSync(path.dirname(full), { recursive: true });
       writeFileSync(full, content);
+      noteFileForCorpus(originId, full);
       return `Wrote ${rel} (${Buffer.byteLength(content)} bytes) to ${dirFor(originId)}.${await previewAck(originId, rel)}`;
     } catch (e) { return `Couldn't write ${rel}: ${e.message}`; }
   }
@@ -2102,7 +2264,9 @@ async function tryDirective(reply, originId, onEvent) {
   if (readD) {
     const rel = readD[1].trim();
     try {
-      const data = readFileSync(safeResolveIn(dirFor(originId), rel), 'utf8');
+      const full = safeResolveIn(dirFor(originId), rel);
+      const data = readFileSync(full, 'utf8');
+      noteFileForCorpus(originId, full);
       return `${rel}:\n${keepWhole(data)}`;
     } catch (e) { return `Couldn't read ${rel}: ${e.message}`; }
   }
@@ -2121,6 +2285,7 @@ async function tryDirective(reply, originId, onEvent) {
       if (hits === 0) return `EDIT ${rel}: that exact text isn't in the file — READ it first, the copy must match byte for byte.`;
       if (hits > 1) return `EDIT ${rel}: that text appears ${hits} times — include more surrounding context so it matches exactly once.`;
       writeFileSync(full, before.replace(oldStr, newStr));
+      noteFileForCorpus(originId, full);
       return `Edited ${rel} (${before.length} -> ${before.replace(oldStr, newStr).length} bytes).${await previewAck(originId, rel)}`;
     } catch (e) { return `Couldn't edit ${rel}: ${e.message}`; }
   }
@@ -2147,6 +2312,7 @@ async function tryDirective(reply, originId, onEvent) {
         applied.push(o.slice(0, 40));
       }
       writeFileSync(full, next);
+      noteFileForCorpus(originId, full);
       return `MULTIEDIT ${rel}: ${applied.length} edit(s) applied (${before.length} -> ${next.length} bytes).${await previewAck(originId, rel)}`;
     } catch (e) { return `Couldn't multiedit ${rel}: ${e.message}`; }
   }
@@ -2167,6 +2333,7 @@ async function tryDirective(reply, originId, onEvent) {
       // Stale outputs next to new code are worse than none.
       if (doc.cells[idx].cell_type === 'code') { doc.cells[idx].outputs = []; doc.cells[idx].execution_count = null; }
       writeFileSync(full, JSON.stringify(doc, null, 1));
+      noteFileForCorpus(originId, full);
       return `NOTEBOOK ${rel}: replaced cell ${idx} (${doc.cells[idx].cell_type}); outputs cleared.`;
     } catch (e) { return `Couldn't edit ${rel}: ${e.message}`; }
   }
@@ -2520,6 +2687,7 @@ async function runTurn(threadId, userText, onEvent, images) {
         if (t.runMode === 'auto') {
           emitLiveStatus(t.id, paint, peekDirectiveStatus('', command));
           const output = await execCommand(command, dirFor(t.id));
+          noteRunForCorpus(t.id, command, { cwd: dirFor(t.id) });
           const shown = `$ ${command}\n${output}`;
           t.history.push({ who: 'bot', text: shown, name: m.name, color: m.color });
           paint({ type: 'final', name: m.name, color: m.color, text: shown });
@@ -2663,6 +2831,7 @@ async function runTurn(threadId, userText, onEvent, images) {
     if (t.runMode === 'auto') {
       emitLiveStatus(t.id, paint, peekDirectiveStatus('', command));
       const output = await execCommand(command, dirFor(t.id));
+      noteRunForCorpus(t.id, command, { cwd: dirFor(t.id) });
       if (!stillMine()) return;
       const shown = `$ ${command}\n${output}`;
       t.history.push({ who: 'bot', text: shown });
@@ -5614,6 +5783,7 @@ const server = http.createServer((req, res) => {
       res.writeHead(200, { 'content-type': 'application/json' });
       res.end('{"ok":true}');
       execCommand(command, cwd).then((output) => {
+        noteRunForCorpus(t.id, command, { cwd });
         entry.runStatus = 'done';
         entry.runOutput = output;
         saveThreads();
@@ -5722,4 +5892,6 @@ export {
   isDoneReply, isTransientModelFail, isEmptyToolResult, enqueueAutoHop, childKickoff, findByName,
   attachChildDir, finishChildDir,
   lockWorktree, unlockWorktree, parsePrRef, fetchSpecsForOrigin, agentSlug,
+  filesForCorpus, noteFileForCorpus, noteRunForCorpus, resetFilesForCorpus,
+  filesForCorpusKeys, scheduleFilesForCorpus, inFlightChars, BIND_MIN_CHARS, KEEP_MAX,
 };

package/lib/gui.html

@@ -194,7 +194,10 @@ async function send() {
     const x = d.x402 || {};
     state.calls += 1;
     if (typeof x.billedUsd === "number") state.spent += x.billedUsd;
-    if (typeof x.savesVsDirect === "number" && x.savesVsDirect > 0) state.saved += x.savesVsDirect;
+    if (typeof x.savedUsd === "number" && x.savedUsd > 0) state.saved += x.savedUsd;
+    else if (typeof x.directUsd === "number" && typeof x.billedUsd === "number") {
+      state.saved += Math.max(0, x.directUsd - x.billedUsd);
+    }
     const bits = [];
     if (typeof x.billedUsd === "number") bits.push(`$${x.billedUsd.toFixed(4)}`);
     if (x.lecore?.engaged) bits.push(`🧠 ${x.lecore.recalled ?? "?"} slices`);

package/lib/mcp.js

@@ -80,7 +80,7 @@ export function buildMcpServer() {
       + '(client-usable ceiling ~128M tokens; keep one call under ~9.8M) is bound once and the model reads only '
       + 'a few thousand tokens of it. Re-asking against an already-bound corpus is near-free and much faster, so '
       + 'send the corpus once and ask many questions. Returns the answer plus a payment receipt '
-      + '(billedUsd, savesVsDirect, tokens actually read).',
+      + '(billedUsd, directUsd, savedUsd, tokens actually read).',
     inputSchema: {
       prompt: z.string().describe('The question or instruction.'),
       corpus: z.string().optional().describe('Optional big context body (document dump, logs, book...). Placed before the prompt.'),
@@ -128,6 +128,8 @@ export function buildMcpServer() {
         receipt: receipt ? {
           line: receipt.line,
           billedUsd: receipt.billedUsd,
+          directUsd: receipt.directUsd,
+          savedUsd: receipt.savedUsd,
           savesVsDirect: receipt.savesVsDirect,
           pricing: receipt.pricing,
           rail: receipt.rail,

package/lib/pay.js

@@ -413,6 +413,9 @@ export class PayClient {
       line: receiptLine(accept, settle),
       rail: railOf(accept),
       billedUsd: accept.extra?.billedUsd,
+      directUsd: accept.extra?.directUsd,
+      savedUsd: accept.extra?.savedUsd,
+      cogsUsd: accept.extra?.cogsUsd,
       savesVsDirect: accept.extra?.savesVsDirect,
       pricing: accept.extra?.pricing,
       symbol: accept.extra?.symbol,

package/lib/proxy.js

@@ -15,6 +15,8 @@ import { bindCorpus, contextCacheDisabled, BIND_MIN_CHARS } from './hrr.js';
 import {
   loadBoundChars, noteCorpusLedger, filesForCorpus, readFilesForCorpus, boundAbsFromKeys,
   createSpillStats, corpusCharsForSend, applySpillCut, msgText, hudDollarX,
+  spillPricedLine,
+  planConversationBind, rememberSpillMemo, SPILL_CONTENT_ANCHOR_CHARS,
 } from './spill.js';
 import { rewritablePath, augmentModelList, ALIAS_IDS, rewriteChatModel, zooModelIds, CLASSIFY_MAX_TOKENS } from './models.js';
 import { forgetContext } from './contexts.js';
@@ -26,7 +28,7 @@ import { loadSessionSpend, saveSessionSpend } from './session.js';
 import { creditBalance, quotedPrices } from './info.js';
 import { subscriptionPublicView } from './subscription.js';
 import { priceHoldings } from './livestatus.js';
-import { receiptUsedCogs } from './racesettle.js';
+import { receiptUsedCogs, receiptDirectUsd } from './racesettle.js';
 import { rewriteWrapClientError } from './wrap.js';
 
 const HOP_BY_HOP = new Set([
@@ -423,11 +425,6 @@ async function spillTranscript(body, log, req, stats, extra = {}) {
     });
   };
 
-  if (msgs.length < 6) {
-    bindFilesInBackground('conversation under 6 messages, background');
-    return null;
-  }
-
   // LIVE SELF-TUNER. Env knobs seed the first cut; after cut+stub the proxy
   // scores the HUD dollar multiple (spill direct/billed) and retunes
   // keep/min-turns/budget (stubMore for SEARCH, not live file bodies)
@@ -488,35 +485,23 @@ async function spillTranscript(body, log, req, stats, extra = {}) {
   //
   // FILES RIDE THE BACKGROUND, NEVER THE CRITICAL PATH.
   //
-  // The FIRST bind of a session is necessarily synchronous � the request cannot
-  // go until the context_id exists, because it travels as x-hrr-context. Folding
-  // file bytes into that bind put a 400KB upload in front of the caller's turn,
-  // which is the cold-bind stall this whole exercise was meant to remove: the
-  // bind endpoint measures 0.34-0.48s on a 613KB corpus, and that is 0.34-0.48s
-  // the user waits before a single token appears.
+  // The first conversation bind is also fire-and-forget: turn 1 may go out
+  // unspilled while the bind runs, then later turns recall a tail + contextId.
+  // Folding file bytes into a synchronous first bind used to put a 400KB
+  // upload in front of the caller's turn (0.34-0.48s on a 613KB corpus).
   //
-  // Nothing recalls a file during the turn that read it � the model already has
+  // Nothing recalls a file during the turn that read it � the model already has
   // the tool result in its window. Files are only worth having bound for the
-  // NEXT ask. So the conversation binds inline and the files are appended after
-  // the fact, off the clock.
+  // NEXT ask, so they append after the conversation bind completes.
   const turns = msgs.slice(firstSpillable, cut).map(msgText).filter(Boolean).join('\n\n');
   const corpus = turns;
-  if (!sessionKey) sessionKey = corpus.slice(0, 2048);
+  if (!sessionKey) sessionKey = corpus.slice(0, SPILL_CONTENT_ANCHOR_CHARS);
 
-  // FILES BIND EVEN WHEN THE CONVERSATION IS TOO SMALL TO SPILL.
-  //
-  // The threshold exists to stop us binding a two-line chat � it was never
-  // meant to gate FILES. But bailing here skipped them entirely, so a fresh
-  // session that reads a 200KB file bound nothing and scored 1.00x forever:
-  // OBSERVED on a live session that read files all turn and never produced a
-  // corpus, because its conversation stayed under the threshold the whole time.
-  //
-  // A file is worth binding on its own merit. So when the turns are too small
-  // to spill but files exist, bind the files anyway � in the background,
-  // against this session's context � and let this turn go unspilled. The corpus
-  // is then waiting for the next ask.
-  if (corpus.length <= BIND_MIN_CHARS) {
-    bindFilesInBackground('conversation under spill threshold, background');
+  // Conversation prefix binds at any size. BIND_MIN_CHARS only gates the
+  // one-shot corpus+question path in maybeCacheCorpus � a real but small
+  // early-turn prefix used to be discarded here ("only large ones").
+  if (!corpus) {
+    bindFilesInBackground('empty conversation prefix, files only');
     return null;
   }
 
@@ -524,7 +509,7 @@ async function spillTranscript(body, log, req, stats, extra = {}) {
   //
   // A transcript grows by one message per turn, so the whole-corpus hash misses
   // every time and the old code re-uploaded the ENTIRE prefix on every single
-  // turn — OBSERVED live: 0.4MB bound three turns running, a fresh context id
+  // turn � OBSERVED live: 0.4MB bound three turns running, a fresh context id
   // each time, while only a few KB was actually new. Bind cost grew with
   // conversation length and was re-paid per message.
   //
@@ -537,7 +522,7 @@ async function spillTranscript(body, log, req, stats, extra = {}) {
   // The anchor was the first 2KB of corpus, which works only because a
   // transcript's opening never changes. It is fragile in exactly the cases that
   // matter: two sessions that open identically (same system block, same first
-  // instruction — the norm for an agent) collide onto ONE bound context and
+  // instruction � the norm for an agent) collide onto ONE bound context and
   // interleave their histories, and any edit near the top of a transcript
   // silently orphans the binding and re-uploads the whole thing.
   //
@@ -545,60 +530,109 @@ async function spillTranscript(body, log, req, stats, extra = {}) {
   // back to the content anchor when it is not. Same memo, better key.
   // CAPTURED FROM A LIVE claude-cli/2.1.232 REQUEST, not guessed. The first
   // version of this checked x-session-id / x-claude-session-id /
-  // metadata.user_id — none of which Claude Code sends, so it silently fell
+  // metadata.user_id � none of which Claude Code sends, so it silently fell
   // back to the content anchor on every request and the feature did nothing.
   // The real header list is:
   //   anthropic-beta, anthropic-version, x-app, x-claude-code-session-id,
   //   x-stainless-*
-  const anchor = sessionKey;
-  const persisted = sessionKey ? sessionLedger.get(sessionKey) : null;
-  const prior = spillMemo.get(anchor) || (persisted?.contextId
-    ? { contextId: persisted.contextId, hash: persisted.hash || '', corpus: null, restored: true }
-    : null);
+  //
+  // COLD-BIND. Turn 1 may go unspilled (full messages, no x-hrr-context) while
+  // the first bind runs in the background � same spirit as file-bind, so the
+  // opening ask is not stalled. The in-flight/completed bind is memoized on
+  // the session key; later turns recall a tail + contextId. Subsequent
+  // appends stay fire-and-forget deltas.
+  let bindPlan = planConversationBind({
+    sessionKey,
+    corpus,
+    spillMemo,
+    sessionLedger,
+  });
+  const anchor = bindPlan.key || sessionKey;
+
+  if (bindPlan.action === 'cold-bind') {
+    const ready = bindCorpus(corpus, {
+      onStage: (stage, info) => {
+        if (stage === 'binding') log(`binding ${mb(info.bytes)}MB of transcript to holographic memory (background)...`);
+      },
+    }).then((b) => {
+      if (!b?.contextId) return b;
+      noteCorpusLedger(boundChars, {
+        contextId: b.contextId,
+        reused: false,
+        corpusChars: corpus.length,
+        deltaChars: 0,
+        fileChars: 0,
+        ...ledgerOpts(),
+      });
+      rememberSpillMemo(spillMemo, anchor, { corpus, contextId: b.contextId, hash: b.hash });
+      bindFilesInBackground('background', { appendTo: b.contextId, asAppend: true });
+      return b;
+    }).catch((e) => {
+      log(`bind failed (turn went unspilled): ${e.message}`);
+      const cur = spillMemo.get(anchor);
+      if (cur?.pending) spillMemo.delete(anchor);
+      return null;
+    });
+    rememberSpillMemo(spillMemo, anchor, { corpus, pending: true, ready });
+    return null;
+  }
+
+  if (bindPlan.action === 'await-pending') {
+    const finished = await bindPlan.ready.catch((e) => {
+      log(`bind failed (history may lag one turn): ${e.message}`);
+      return null;
+    });
+    if (!finished?.contextId) {
+      bindFilesInBackground('first bind failed, files only');
+      return null;
+    }
+    bindPlan = planConversationBind({
+      sessionKey: anchor,
+      corpus,
+      spillMemo,
+      sessionLedger,
+    });
+  }
+
+  if (bindPlan.action !== 'recall' || !bindPlan.contextId) {
+    bindFilesInBackground('no context yet, files only');
+    return null;
+  }
+
   let bind;
   let deltaChars = 0;
   let appended = false;
-  if (prior?.restored && prior.contextId) {
+  if (bindPlan.restored && bindPlan.contextId) {
     // Sidecar came back up: we still know the context_id and the accumulated
     // char count, but not the prior prefix string, so we cannot slice a delta.
     // Re-append the current prefix (some overlap is harmless) and keep the
-    // restored ledger � do not add corpus.length again.
+    // restored ledger � do not add corpus.length again.
     void bindCorpus(corpus, {
-      appendTo: prior.contextId,
+      appendTo: bindPlan.contextId,
       onStage: (stage, info) => {
-        if (stage === 'binding') log(`appending ${mb(info.bytes)}MB to ${prior.contextId} (restored session, background)`);
+        if (stage === 'binding') log(`appending ${mb(info.bytes)}MB to ${bindPlan.contextId} (restored session, background)`);
       },
     }).catch((e) => log(`append failed (history may lag one turn): ${e.message}`));
     appended = true;
-    bind = { contextId: prior.contextId, hash: prior.hash, reused: true, bytes: 0 };
-  } else if (prior && typeof prior.corpus === 'string' && corpus.startsWith(prior.corpus) && corpus.length > prior.corpus.length) {
-    const delta = corpus.slice(prior.corpus.length);
+    bind = { contextId: bindPlan.contextId, hash: bindPlan.hash, reused: true, bytes: 0 };
+  } else if (bindPlan.append && bindPlan.delta) {
+    const delta = bindPlan.delta;
     deltaChars = delta.length;
-    // FIRE AND FORGET. This delta is history for FUTURE turns � the answer
+    // FIRE AND FORGET. This delta is history for FUTURE turns � the answer
     // being generated right now is served from the tail plus what is already
     // bound, so waiting on the upload buys nothing and costs the user the
     // round trip on every single turn. The context id is already known, so
     // nothing is lost by not waiting for it.
-    //
-    // The FIRST bind is deliberately NOT async: the request must carry
-    // x-hrr-context, and that id does not exist until the bind returns. Firing
-    // that one off would send the opening turn with no context at all � a
-    // silently worse answer traded for a shorter pause, which is the wrong way
-    // round.
     void bindCorpus(delta, {
-      appendTo: prior.contextId,
+      appendTo: bindPlan.contextId,
       onStage: (stage, info) => {
-        if (stage === 'binding') log(`appending ${mb(info.bytes)}MB to ${prior.contextId} (delta, background)`);
+        if (stage === 'binding') log(`appending ${mb(info.bytes)}MB to ${bindPlan.contextId} (delta, background)`);
       },
     }).catch((e) => log(`append failed (history may lag one turn): ${e.message}`));
     appended = true;
-    bind = { contextId: prior.contextId, hash: prior.hash, reused: true, bytes: delta.length };
+    bind = { contextId: bindPlan.contextId, hash: bindPlan.hash, reused: true, bytes: delta.length };
   } else {
-    bind = await bindCorpus(corpus, {
-      onStage: (stage, info) => {
-        if (stage === 'binding') log(`binding ${mb(info.bytes)}MB of transcript to holographic memory...`);
-      },
-    });
+    bind = { contextId: bindPlan.contextId, hash: bindPlan.hash, reused: true, bytes: 0 };
   }
   // CONVERSATION LEDGER � every successful bind AND append, not only when
   // files exist. First bind initializes to the bound corpus size; each append
@@ -618,8 +652,7 @@ async function spillTranscript(body, log, req, stats, extra = {}) {
   // uploads each version exactly once no matter how often the agent re-reads it.
   // Read + readdir are inside setImmediate � they must not run before send().
   bindFilesInBackground('background', { appendTo: bind.contextId, asAppend: true });
-  spillMemo.set(anchor, { corpus, contextId: bind.contextId, hash: bind.hash });
-  if (spillMemo.size > 32) spillMemo.delete(spillMemo.keys().next().value);
+  rememberSpillMemo(spillMemo, anchor, { corpus, contextId: bind.contextId, hash: bind.hash });
   // Count the tail that is actually forwarded after stub/trim � older
   // continue-turn rounds after the ask may have been dropped, so
   // msgs.length - cut would keep lastSend growing with the raw pile.
@@ -793,7 +826,6 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
     say(`session restored: $${sessionSpent.toFixed(6)} � ${paidCalls} paid call${paidCalls === 1 ? '' : 's'}`);
   }
   process.on('exit', rememberSpend);
-  const MARKUP = 3; // confirmed constant, see .claude/wiki.md "Margin needs a like-for-like denominator"
   const noteQuote = (x) => {
     const billed = Number(x?.billedUsd);
     if (!Number.isFinite(billed) || billed < 0) return;
@@ -1519,30 +1551,20 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
       if (paid && receipt) {
         if (receipt.ok && typeof receipt.billedUsd === 'number') {
           sessionSpent += receipt.billedUsd;
-          // cogs: no per-call field for it, but MARKUP is a known constant
-          // (3x — confirmed against the gateway's own margin math), and
-          // billedUsd = cogs * markup on a straight-markup call. Close enough
-          // on a counterfactual (leCore-discounted) call too since markup is
-          // still the ceiling those get capped against.
-          // Prefer the gateway's own cogsUsd. Deriving it as billedUsd/MARKUP
-          // is only correct on a straight-markup call: under counterfactual
-          // pricing billedUsd is min(direct×discount, markupUsd), so the
-          // division understates cost and overstates margin.
-          sessionCogs += receiptUsedCogs(receipt, MARKUP);
+          // Wallet path: no 3x. Prefer extra.cogsUsd / billedUsd / directUsd /
+          // savedUsd from the 402. billedUsd is the OpenRouter price (plus
+          // zoo's 33% of savings when the caller beat direct).
+          sessionCogs += receiptUsedCogs(receipt);
           noteQuote(receipt);
           // direct = what answering this WITHOUT the zoo would have cost. On an
           // attach call that is the whole bound corpus, which is why it can be
-          // orders of magnitude above what was billed. directUsd is exact and
-          // always present; savesVsDirect is the same number as a ratio.
+          // orders of magnitude above what was billed. Read extra.directUsd /
+          // extra.savedUsd; do not invent billed * 3.
           if (didSpill) {
             spill.spillSpend += receipt.billedUsd || 0;
-            spill.spillDirect += typeof receipt.directUsd === 'number' ? receipt.directUsd : (receipt.billedUsd || 0);
+            spill.spillDirect += receiptDirectUsd(receipt);
           }
-          sessionDirect += typeof receipt.directUsd === 'number'
-            ? receipt.directUsd
-            : typeof receipt.savesVsDirect === 'number'
-              ? receipt.savesVsDirect * receipt.billedUsd
-              : receipt.billedUsd;
+          sessionDirect += receiptDirectUsd(receipt);
           // The public-URL ceiling meters only public-origin spend — your own
           // local calls never eat into it.
           if (viaTunnel) tunnelSpent += receipt.billedUsd;
@@ -1599,23 +1621,19 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
         if (!paid && data?.x402 && typeof data.x402.billedUsd === 'number') {
           const x = data.x402;
           sessionSpent += x.billedUsd;
-          sessionCogs += receiptUsedCogs(x, MARKUP);
+          sessionCogs += receiptUsedCogs(x);
           noteQuote(x);
-          sessionDirect += typeof x.directUsd === 'number' ? x.directUsd : x.billedUsd;
+          sessionDirect += receiptDirectUsd(x);
           if (didSpill) {
             // THE number that settles why a spilled call did or did not save:
             // the gateway only prices a counterfactual when corpusTokens >
             // promptTokens, so a tail that rivals the corpus silently falls
-            // back to markup and direct collapses onto billed.
-            const lc = x.lecore || {};
-            // counterfactualTokensUsed is the basis the gateway ACTUALLY priced
-            // on. lecore.corpusTokens is often absent and reading it printed
-            // 'corpus ?' on calls that were pricing fine — which sent a whole
-            // night's debugging after a number that was never the input.
-            const basis = x.counterfactualTokensUsed ?? lc.corpusTokens;
-            log(`spill priced: ${x.pricing} · basis ${basis ?? '?'} tok vs sent ${lc.tokensBefore ?? '?'} -> ${lc.tokensAfter ?? '?'} · billed ${(x.billedUsd ?? 0).toFixed(5)} direct ${(x.directUsd ?? 0).toFixed(5)}`);
+            // back to at-cost and direct collapses onto billed.
+            // Tell-line prints the gateway's actual counterfactual only.
+            // Never fall back to lecore.corpusTokens (often == tokensBefore).
+            log(spillPricedLine(x));
             spill.spillSpend += x.billedUsd;
-            spill.spillDirect += typeof x.directUsd === 'number' ? x.directUsd : x.billedUsd;
+            spill.spillDirect += receiptDirectUsd(x);
           }
           paidCalls += 1;
           if (viaTunnel) tunnelSpent += x.billedUsd;
@@ -1665,15 +1683,14 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
       const meterStreamed = (x) => {
         if (paid || typeof x?.billedUsd !== 'number') return;
         sessionSpent += x.billedUsd;
-        sessionCogs += receiptUsedCogs(x, MARKUP);
+        sessionCogs += receiptUsedCogs(x);
         noteQuote(x);
-        sessionDirect += typeof x.directUsd === 'number' ? x.directUsd : x.billedUsd;
+        sessionDirect += receiptDirectUsd(x);
         if (typeof x.actualUsd === 'number' && x.actualUsd >= 0) { sessionActual += x.actualUsd; actualCalls += 1; billedWithActual += x.billedUsd || 0; }
         if (didSpill) {
-          const lc = x.lecore || {};
-          log(`spill priced (streamed): ${x.pricing} · basis ${x.counterfactualTokensUsed ?? '?'} tok vs sent ${lc.tokensBefore ?? '?'} -> ${lc.tokensAfter ?? '?'} · billed ${(x.billedUsd ?? 0).toFixed(5)} direct ${(x.directUsd ?? 0).toFixed(5)}`);
+          log(spillPricedLine(x, { streamed: true }));
           spill.spillSpend += x.billedUsd;
-          spill.spillDirect += typeof x.directUsd === 'number' ? x.directUsd : x.billedUsd;
+          spill.spillDirect += receiptDirectUsd(x);
         }
         paidCalls += 1;
         if (viaTunnel) tunnelSpent += x.billedUsd;

package/lib/racesettle.js

@@ -155,13 +155,29 @@ export function capRaceByCredit(n, { creditUsd, quoteUsd } = {}) {
  * House cost from the receipt. Do not subtract race_unused — unused
  * grant-back is not a user refund, and shrinking cogs would hide house loss.
  * Does not clamp to billed — HUD embers when cogs exceed what was paid.
+ *
+ * Wallet path: there is no 3× markup. Prefer the gateway's cogsUsd; otherwise
+ * billedUsd (OpenRouter price, plus zoo's 33% of savings when the 402 has any).
  */
-export function receiptUsedCogs(x, markup = 3) {
+export function receiptUsedCogs(x) {
   if (!x || typeof x !== 'object') return 0;
-  const billedRaw = Number(x.billedUsd);
-  const billedOk = Number.isFinite(billedRaw) && billedRaw >= 0;
   if (typeof x.cogsUsd === 'number' && Number.isFinite(x.cogsUsd)) return x.cogsUsd;
-  return billedOk ? billedRaw / markup : 0;
+  const billedRaw = Number(x.billedUsd);
+  return Number.isFinite(billedRaw) && billedRaw >= 0 ? billedRaw : 0;
+}
+
+/** Counterfactual from the 402: extra.directUsd, else billed + savedUsd. */
+export function receiptDirectUsd(x) {
+  if (typeof x?.directUsd === 'number' && Number.isFinite(x.directUsd)) return x.directUsd;
+  const billed = Number(x?.billedUsd);
+  const billedOk = Number.isFinite(billed) && billed >= 0;
+  if (typeof x?.savedUsd === 'number' && Number.isFinite(x.savedUsd) && billedOk) {
+    return billed + x.savedUsd;
+  }
+  if (typeof x?.savesVsDirect === 'number' && Number.isFinite(x.savesVsDirect) && billedOk) {
+    return x.savesVsDirect * billed;
+  }
+  return billedOk ? billed : 0;
 }
 
 /**
@@ -169,12 +185,10 @@ export function receiptUsedCogs(x, markup = 3) {
  * first-call rewrite, never a race_unused user refund.
  * cogs is the house cost on that receipt (HUD embers when cogs > spent).
  */
-export function meterRaceReceipt(x, markup = 3) {
+export function meterRaceReceipt(x) {
   const billed = Number(x?.billedUsd);
   const spentUsd = Number.isFinite(billed) ? billed : 0;
-  const usedCogs = receiptUsedCogs(x, markup);
-  const direct = typeof x?.directUsd === 'number' ? x.directUsd : spentUsd;
-  return { spentUsd, cogsUsd: usedCogs, directUsd: direct };
+  return { spentUsd, cogsUsd: receiptUsedCogs(x), directUsd: receiptDirectUsd(x) };
 }
 
 export function inferRaceTier(models, fallback = 'medium') {

package/lib/spill.js

@@ -118,6 +118,31 @@ export function corpusCharsForSend(boundChars, contextId, thisTurn) {
   return Math.max(boundChars.get(contextId) || 0, thisTurn || 0);
 }
 
+/**
+ * Pricing / unspilled basis: the unspilled size, never the shrunken sent
+ * (tokensAfter) size. Same unit on both args — tokens or chars, not mixed.
+ */
+export function unspilledBasis({ tokensBefore, corpus } = {}) {
+  return Math.max(Number(tokensBefore) || 0, Number(corpus) || 0);
+}
+
+/**
+ * Gateway counterfactual the tell-line must print. Missing / non-finite /
+ * non-positive → null (`basis ?`). Never reads lecore.corpusTokens.
+ */
+export function spillPricedTellBasis(x) {
+  const n = Number(x?.counterfactualTokensUsed);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+/** Exact `spill priced:` / `spill priced (streamed):` line the proxy logs. */
+export function spillPricedLine(x, { streamed = false } = {}) {
+  const lc = x?.lecore || {};
+  const basis = spillPricedTellBasis(x);
+  const prefix = streamed ? 'spill priced (streamed):' : 'spill priced:';
+  return `${prefix} ${x?.pricing} · basis ${basis ?? '?'} tok vs sent ${lc.tokensBefore ?? '?'} -> ${lc.tokensAfter ?? '?'} · billed ${(x?.billedUsd ?? 0).toFixed(5)} direct ${(x?.directUsd ?? 0).toFixed(5)}`;
+}
+
 /** Expand ~ and resolve relative paths against cwd. Returns null if unusable. */
 export function resolveReadablePath(p, cwd = process.cwd()) {
   if (typeof p !== 'string') return null;
@@ -1256,9 +1281,9 @@ function lastUserAskIndex(msgs, firstSpillable) {
   return -1;
 }
 
-function countRealTurns(msgs, from) {
+function countRealTurns(msgs, from, to = msgs.length) {
   let n = 0;
-  for (let i = from; i < msgs.length; i++) {
+  for (let i = from; i < to; i++) {
     const r = msgs[i]?.role;
     if (r === 'user' || r === 'assistant') n += 1;
   }
@@ -1356,7 +1381,9 @@ export function trimUnseverablePairs(msgs, {
 
 /**
  * Pick a severable cut: keep a recent tail, honour the byte budget, floor
- * at minTurns of user/assistant, and never drop the last user ask.
+ * at minTurns of user/assistant on a LONG thread, and never drop the last
+ * user ask. minTurns must not empty the bind prefix — a short AUTO thread
+ * binds early turns and may forward a tail with fewer than minTurns.
  */
 export function cutTranscript(msgs, knobs = {}) {
   const k = sanitizeKnobs({ ...envKnobs(), ...knobs });
@@ -1398,21 +1425,38 @@ export function cutTranscript(msgs, knobs = {}) {
   }
   if (tailStart > cut) cut = tailStart;
 
+  const lastUser = lastUserAskIndex(msgs, firstSpillable);
+
+  // minTurns may still size the tail on a long thread. If walking earlier
+  // would empty the bind prefix (the old firstSpillable+1 fallback), keep a
+  // non-empty prefix and allow fewer than minTurns in the tail. On a short
+  // thread that cannot satisfy minTurns at all, pin the last ask so early
+  // user/assistant turns bind instead of riding in the forwarded tail.
   if (countRealTurns(msgs, cut) < minTurns) {
+    let moved = false;
     for (let i = cut - 1; i > firstSpillable; i--) {
-      if (isSeverable(msgs, i, firstSpillable) && countRealTurns(msgs, i) >= minTurns) { cut = i; break; }
-      if (i === firstSpillable + 1) { if (isSeverable(msgs, i, firstSpillable)) cut = i; break; }
+      if (isSeverable(msgs, i, firstSpillable) && countRealTurns(msgs, i) >= minTurns) {
+        cut = i;
+        moved = true;
+        break;
+      }
+    }
+    if (!moved && lastUser > firstSpillable && isSeverable(msgs, lastUser, firstSpillable)) {
+      cut = lastUser;
     }
   }
 
-  const lastUser = lastUserAskIndex(msgs, firstSpillable);
   if (lastUser > firstSpillable && cut > lastUser) cut = lastUser;
 
-  // Never shrink below 2 real turns when that would drop the ask — the ask
-  // always stays; expand earlier only if two turns exist and remain after it.
+  // 2-real-turn floor protects the last user ask: never drop it, and expand
+  // the tail to two turns on a LONG thread. Do not steal the first
+  // user+assistant pair from the prefix just to pad a short tail.
   if (lastUser > firstSpillable && countRealTurns(msgs, cut) < 2) {
     for (let i = cut - 1; i > firstSpillable; i--) {
-      if (isSeverable(msgs, i, firstSpillable) && countRealTurns(msgs, i) >= 2) { cut = i; break; }
+      if (!isSeverable(msgs, i, firstSpillable) || countRealTurns(msgs, i) < 2) continue;
+      if (countRealTurns(msgs, firstSpillable, i) < 2) continue;
+      cut = i;
+      break;
     }
     if (cut > lastUser) cut = lastUser;
   }
@@ -1420,6 +1464,121 @@ export function cutTranscript(msgs, knobs = {}) {
   return { cut, firstSpillable, lastUser, knobs: k };
 }
 
+/** Opening slice used as a content-anchor when no session header is sent. */
+export const SPILL_CONTENT_ANCHOR_CHARS = 2048;
+
+/**
+ * Find a memoized / ledger bind for this request. Prefers an explicit
+ * session key; otherwise matches a stored prefix so a growing content-anchor
+ * (grokui AUTO sends no session header) still recalls the same contextId.
+ */
+export function lookupSpillMemo(spillMemo, sessionLedger, { sessionKey, corpus } = {}) {
+  if (sessionKey && spillMemo?.has(sessionKey)) {
+    return { key: sessionKey, source: 'memo', ...spillMemo.get(sessionKey) };
+  }
+  if (sessionKey && sessionLedger?.has(sessionKey)) {
+    const led = sessionLedger.get(sessionKey);
+    if (led?.contextId) return { key: sessionKey, source: 'ledger', restored: !led.corpus, ...led };
+  }
+  if (corpus && spillMemo) {
+    for (const [k, v] of spillMemo) {
+      if (typeof v?.corpus === 'string' && v.corpus.length && corpus.startsWith(v.corpus)) {
+        return { key: k, source: 'memo-prefix', ...v };
+      }
+    }
+    const opening = corpus.slice(0, SPILL_CONTENT_ANCHOR_CHARS);
+    for (const [k, v] of spillMemo) {
+      if (typeof k !== 'string' || k.startsWith('sid:')) continue;
+      if (opening.startsWith(k) || (k && k.startsWith(opening))) {
+        return { key: k, source: 'memo-anchor', ...v };
+      }
+    }
+  }
+  return null;
+}
+
+export function rememberSpillMemo(spillMemo, key, entry, { max = 32 } = {}) {
+  if (!spillMemo || !key) return;
+  spillMemo.set(key, entry);
+  while (spillMemo.size > max) spillMemo.delete(spillMemo.keys().next().value);
+}
+
+/**
+ * Decide first-bind vs later-turn recall. No I/O — bindCorpus is injected
+ * by the caller (or mocked in tests).
+ *
+ *   cold-bind     — fire-and-forget first bind; this turn may go unspilled
+ *   await-pending — later turn while that bind is in flight; await, then tail
+ *   recall        — contextId known; send tail (+ optional delta append)
+ */
+export function planConversationBind({ sessionKey, corpus, spillMemo, sessionLedger } = {}) {
+  const key = sessionKey || (corpus ? corpus.slice(0, SPILL_CONTENT_ANCHOR_CHARS) : null);
+  const prior = lookupSpillMemo(spillMemo, sessionLedger, { sessionKey: key, corpus });
+  if (!prior) {
+    return { action: 'cold-bind', send: 'full', key, corpus };
+  }
+  if (prior.pending && !prior.contextId) {
+    return {
+      action: 'await-pending',
+      send: 'tail',
+      key: prior.key || key,
+      corpus,
+      ready: prior.ready,
+    };
+  }
+  if (prior.contextId) {
+    let delta = '';
+    let append = false;
+    if (prior.restored) {
+      append = true;
+    } else if (typeof prior.corpus === 'string' && corpus.startsWith(prior.corpus) && corpus.length > prior.corpus.length) {
+      delta = corpus.slice(prior.corpus.length);
+      append = true;
+    }
+    return {
+      action: 'recall',
+      send: 'tail',
+      key: prior.key || key,
+      corpus,
+      contextId: prior.contextId,
+      hash: prior.hash,
+      reused: true,
+      append,
+      delta,
+      restored: Boolean(prior.restored),
+    };
+  }
+  return { action: 'cold-bind', send: 'full', key, corpus };
+}
+
+/**
+ * Cut the transcript and plan the conversation bind. Tests use this instead
+ * of standing up the proxy or a live gateway.
+ */
+export function planTranscriptSpill(msgs, {
+  knobs,
+  sessionKey,
+  spillMemo,
+  sessionLedger,
+  corpusChars = 0,
+  adapt = false,
+  persist = false,
+  ...cutOpts
+} = {}) {
+  const adapted = applySpillCut(msgs, {
+    knobs,
+    corpusChars,
+    adapt,
+    persist,
+    ...cutOpts,
+  });
+  const empty = { ...adapted, corpus: '', bindPlan: null };
+  if (adapted.cut <= adapted.firstSpillable) return empty;
+  const corpus = msgs.slice(adapted.firstSpillable, adapted.cut).map(msgText).filter(Boolean).join('\n\n');
+  const bindPlan = planConversationBind({ sessionKey, corpus, spillMemo, sessionLedger });
+  return { ...adapted, corpus, bindPlan };
+}
+
 function stubForCut(msgs, cut, opts) {
   return stubBoundFileResults(msgs, {
     boundFiles: opts.boundFiles,

package/lib/x402.js

@@ -22,7 +22,7 @@ import {
  *                  payTo: "<wallet>", resource, description, maxTimeoutSeconds,
  *                  extra: { facilitator, feePayer, symbol, billedUsd, tokenUsd,
  *                           pricedAt, pricing: "markup"|"counterfactual",
- *                           markup? , directUsd?, savesVsDirect?,
+ *                           billedUsd, directUsd?, savedUsd?, savesVsDirect?,
  *                           acquire?: { method: "spl-token-wrap", steps: WRAP_ACQUIRE_STEPS } } } ],
  *     error: "payment required",
  *     help: "Wrap ix has 9 accounts. Program CPIs the deposit — do not send a separate TransferChecked. 0x6a = NotEnoughAccounts (old 5-account wrap is dead)." }
@@ -232,12 +232,21 @@ export function receiptLine(accept, settle) {
   // reaches the spill threshold, so there is nothing to compress and nothing
   // to save — which is worth saying out loud, because the fix on the caller's
   // side is to BIND a corpus, not to change models.
-  const ratio = x.savesVsDirect != null ? Number(x.savesVsDirect) : null;
+  const billed = Number(x.billedUsd);
+  const direct = x.directUsd != null ? Number(x.directUsd) : null;
+  const saved = x.savedUsd != null ? Number(x.savedUsd)
+    : (Number.isFinite(billed) && Number.isFinite(direct) ? Math.max(0, direct - billed) : null);
+  const ratio = x.savesVsDirect != null ? Number(x.savesVsDirect)
+    : (Number.isFinite(billed) && billed > 0 && Number.isFinite(direct) ? direct / billed : null);
+  // Wallet path: OpenRouter price, plus 33% of savings vs direct when any.
+  // Never print extra.markup — that field is leftover 3× and is not the quote.
   const saves = ratio != null
     ? (ratio >= 1.05
         ? ` (${ratio.toFixed(1)}× cheaper than direct)`
-        : ' (at direct price — nothing to compress; bind a corpus to save)')
-    : (x.markup != null ? ` (markup ${x.markup}×, short body)` : '');
+        : ' (at OpenRouter price — nothing to compress; bind a corpus to save)')
+    : (Number.isFinite(saved) && saved > 0
+        ? ` ($${saved.toFixed(4)} saved vs direct)`
+        : ' (at OpenRouter price — short body)');
   const tx = settle?.transaction || settle?.txHash || settle?.signature;
   const rail = railOf(accept);
   return `paid ${usd}${saves}${rail ? ` · rail ${rail}` : ''}${tx ? ` · tx ${tx}` : ''}`;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openzoo",
-  "version": "0.49.5",
-  "description": "Local x402-paying proxy + MCP server for openzoo.fun \u2014 point any OpenAI-compatible harness (Cursor, Claude Code, aider, SDKs) at localhost and it pays per call from a local burner wallet. Solana and Base rails live; Robinhood experimental.",
+  "version": "0.49.6",
+  "description": "Local x402-paying proxy + MCP server for openzoo.fun — point any OpenAI-compatible harness (Cursor, Claude Code, aider, SDKs) at localhost and it pays per call from a local burner wallet. Solana and Base rails live; Robinhood experimental.",
   "license": "MIT",
   "type": "module",
   "bin": {
@@ -16,7 +16,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node --test test/*.test.js"
+    "test": "node --test test/*.test.js && node scripts/assert-grokui-pin.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",