openzoo 0.49.5 → 0.49.7

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;
@@ -527,6 +552,15 @@ export function hudDollarX({
 /** Tool result larger than this is "fat" — stub it in the forwarded tail. */
 export const FAT_TOOL_CHARS = 400;
 
+/**
+ * Over-budget forwarded-tail shrink (SHRINK_OVER). When the tail exceeds
+ * this many chars (or the caller `budget`), oldest tool_results are
+ * considered for `[bound]` stubs. A stub is emitted only if HRR recall
+ * actually returns overlapping bytes for that item — `boundFiles` /
+ * `boundAbs` is not proof.
+ */
+export const SHRINK_OVER = 6000;
+
 /**
  * Last-round bodies under this floor stay even after a follow-up ask
  * (0.48.77: a 461-byte bound Read must remain visible). Older rounds use
@@ -642,6 +676,84 @@ function toolContentLength(content) {
   return 0;
 }
 
+function toolContentText(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content.map((b) => (typeof b === 'string' ? b : String(b?.text ?? b?.content ?? ''))).join('');
+  }
+  if (content && typeof content === 'object') return JSON.stringify(content);
+  return content == null ? '' : String(content);
+}
+
+/** Normalize a recall hook result to text. Empty means a miss. */
+export function recallText(got) {
+  if (got == null) return '';
+  if (typeof got === 'string') return got;
+  if (typeof Buffer !== 'undefined' && Buffer.isBuffer(got)) return got.toString('utf8');
+  if (typeof got === 'object') {
+    if (typeof got.text === 'string') return got.text;
+    if (typeof got.content === 'string') return got.content;
+    if (typeof got.bytes === 'string') return got.bytes;
+    if (typeof Buffer !== 'undefined' && Buffer.isBuffer(got.bytes)) return got.bytes.toString('utf8');
+  }
+  return '';
+}
+
+/** True when recalled text is non-empty and overlaps the original body. */
+export function recallOverlapsBody(recalled, body) {
+  const a = recallText(recalled);
+  const b = toolContentText(body);
+  if (!a || !b) return false;
+  if (b.includes(a) || a.includes(b)) return true;
+  const n = Math.min(32, a.length, b.length);
+  if (n < 1) return false;
+  for (let i = 0; i + n <= a.length; i += Math.max(1, Math.floor(n / 2))) {
+    if (b.includes(a.slice(i, i + n))) return true;
+  }
+  return false;
+}
+
+/**
+ * Probe `recall` for this tool_result / file. True only when the hook
+ * actually produced overlapping bytes — not when we merely think the
+ * path is bound.
+ */
+export function recallReturnedBytes(recall, item = {}) {
+  if (typeof recall !== 'function') return false;
+  let got;
+  try {
+    const content = toolContentText(item.content);
+    got = recall({
+      id: item.id,
+      paths: item.paths || [],
+      content,
+      query: item.query || (Array.isArray(item.paths) && item.paths[0]) || content.slice(0, 80),
+    });
+  } catch {
+    return false;
+  }
+  return recallOverlapsBody(got, item.content);
+}
+
+/**
+ * Local recall over already-bound corpus text. Hard-proof stand-in when a
+ * live HRR probe is not available: the exact bytes must be in the corpus
+ * AND the probe must return a non-empty overlapping slice.
+ */
+export function corpusRecall(corpus) {
+  const text = typeof corpus === 'string' ? corpus : '';
+  return (item = {}) => {
+    if (!text) return '';
+    const body = toolContentText(item.content);
+    const snippet = body.length >= 16 ? body.slice(0, 64) : body;
+    if (snippet && text.includes(snippet)) {
+      const i = text.indexOf(snippet);
+      return text.slice(i, i + Math.min(Math.max(body.length, snippet.length), 8192));
+    }
+    return '';
+  };
+}
+
 function resolveBoundPath(raw, cwd, boundAbs) {
   if (!boundAbs?.size) return null;
   const t = typeof raw === 'string' ? raw.trim() : '';
@@ -654,10 +766,17 @@ function resolveBoundPath(raw, cwd, boundAbs) {
 
 /**
  * After a file is bound, drop its tool_result / file body from the forwarded
- * tail. Keep the path and a short marker. The model already has the bytes in
- * the bound corpus via recall; shipping them again makes sent ≈ corpus and
- * the gateway's `counterfactualTokens > promptTokens` gate barely fires
- * (live: 5MB filebind, lastSend 13/107, savingX 1.22 instead of ~7x).
+ * tail. Keep the path and a short marker. Shipping those bytes again makes
+ * sent ≈ corpus and the gateway's `counterfactualTokens > promptTokens`
+ * gate barely fires (live: 5MB filebind, lastSend 13/107, savingX 1.22
+ * instead of ~7x).
+ *
+ * A `[bound]` marker is a promise that HRR recall can return those bytes.
+ * `boundAbs` / `boundFiles` only means we think we bound the path — that
+ * is not proof. On the SHRINK_OVER path (tail over `budget`), and whenever
+ * a `recall` hook is installed on a budgeted tail, stub only if recall
+ * actually returns non-empty overlapping content. Prefer the original body
+ * over a lying stub (context missing, file not in corpus, recall miss).
  *
  * Cheap rewrite — no disk I/O. First-read results (not yet in boundAbs) and
  * non-file tool output stay verbatim UNLESS `aggressive` / `stubMore` or a
@@ -703,6 +822,9 @@ export function stubBoundFileResults(msgs, {
   // assistant(tool_calls)+results chain. Ignored when the tail is severable.
   keepTail = null,
   fatChars = FAT_TOOL_CHARS,
+  // (query) => bytes. SHRINK_OVER [bound] stubs require a non-empty
+  // overlapping hit. boundFiles alone is not enough.
+  recall = null,
 } = {}) {
   const absSet = boundAbs || boundAbsFromKeys(boundFiles);
   const wantBudget = budget != null && Number.isFinite(Number(budget));
@@ -791,6 +913,29 @@ export function stubBoundFileResults(msgs, {
     return false;
   };
 
+  const recallCache = new Map();
+  const probeRecall = (id, content) => {
+    const key = id || toolContentText(content);
+    if (recallCache.has(key)) return recallCache.get(key);
+    const ok = recallReturnedBytes(recall, {
+      id,
+      content,
+      paths: idPaths.get(id) || [],
+    });
+    recallCache.set(key, ok);
+    return ok;
+  };
+
+  const allowBoundStub = (id, content, { overBudget = false } = {}) => {
+    // SHRINK_OVER leftovers always need real recall bytes (fail closed
+    // when no hook is installed). When a recall hook is installed on a
+    // budgeted tail, every [bound] claim uses the same gate.
+    if (overBudget || (wantBudget && typeof recall === 'function')) {
+      return probeRecall(id, content);
+    }
+    return true;
+  };
+
   let stubbed = 0;
   let dropped = 0;
   let messages = msgs;
@@ -824,6 +969,7 @@ export function stubBoundFileResults(msgs, {
     if (m.role === 'tool') {
       const n = toolContentLength(m.content);
       if (!shouldStubBody(m.tool_call_id, n) || isStubText(m.content)) return m;
+      if (!allowBoundStub(m.tool_call_id, m.content)) return m;
       dropped += n;
       stubbed += 1;
       return { ...m, content: stubFor(m.tool_call_id, n) };
@@ -857,6 +1003,7 @@ export function stubBoundFileResults(msgs, {
       if (b?.type !== 'tool_result') return b;
       const n = toolContentLength(b.content);
       if (!shouldStubBody(b.tool_use_id, n) || isStubText(b.content)) return b;
+      if (!allowBoundStub(b.tool_use_id, b.content)) return b;
       dropped += n;
       stubbed += 1;
       changed = true;
@@ -865,11 +1012,12 @@ export function stubBoundFileResults(msgs, {
     return changed ? { ...next, content: blocks } : next;
   });
 
-  // Byte budget wins inside a tool chain. cutTranscript cannot move tailStart
-  // past assistant(tool_calls) / role:tool (pairing 400s the provider), so a
-  // 300-result storm used to ride in at ~728k after file-only stubs. Stub
-  // bodies first, then fat tool_call JSON; if still over, drop older pairs.
-  // Never drop the ask. Never orphan a remaining tool_result.
+  // SHRINK_OVER: byte budget wins inside a tool chain. cutTranscript cannot
+  // move tailStart past assistant(tool_calls) / role:tool (pairing 400s the
+  // provider), so a 300-result storm used to ride in at ~728k after file-only
+  // stubs. Stub bodies first, then fat tool_call JSON; if still over, drop
+  // older pairs. Never drop the ask. Never orphan a remaining tool_result.
+  // Never write `[bound]` unless recall returned those bytes.
   if (wantBudget) {
     const cap = Number(budget);
     let used = sliceChars(messages, fromIndex);
@@ -883,6 +1031,7 @@ export function stubBoundFileResults(msgs, {
           if (isStubText(m.content)) continue;
           const n = toolContentLength(m.content);
           if (!shouldStubBody(m.tool_call_id, n, { overBudget: true })) continue;
+          if (!allowBoundStub(m.tool_call_id, m.content, { overBudget: true })) continue;
           const stub = stubFor(m.tool_call_id, n);
           if (stub.length >= n) continue;
           used = used - n + stub.length;
@@ -916,6 +1065,7 @@ export function stubBoundFileResults(msgs, {
           if (b?.type !== 'tool_result' || used <= cap || isStubText(b.content)) return b;
           const n = toolContentLength(b.content);
           if (!shouldStubBody(b.tool_use_id, n, { overBudget: true })) return b;
+          if (!allowBoundStub(b.tool_use_id, b.content, { overBudget: true })) return b;
           const stub = stubFor(b.tool_use_id, n);
           if (stub.length >= n) return b;
           used = used - n + stub.length;
@@ -959,7 +1109,7 @@ export const LAST_SEND_TIGHTEN = 24;
 export const KNOB_DEFAULTS = Object.freeze({
   keepTail: 8,
   minTurns: 6,
-  budget: 6000,
+  budget: SHRINK_OVER,
   stubMore: false,
 });
 
@@ -1256,9 +1406,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 +1506,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 });
@@ -1370,6 +1522,8 @@ export function cutTranscript(msgs, knobs = {}) {
   const minTurns = Math.max(2, k.minTurns);
   const budget = k.budget;
 
+  const lastUser = lastUserAskIndex(msgs, firstSpillable);
+
   let cut = -1;
   for (let i = msgs.length - keepTail; i > firstSpillable; i--) {
     if (isSeverable(msgs, i, firstSpillable)) { cut = i; break; }
@@ -1380,7 +1534,7 @@ export function cutTranscript(msgs, knobs = {}) {
     }
   }
   if (cut <= firstSpillable) {
-    return { cut: -1, firstSpillable, lastUser: lastUserAskIndex(msgs, firstSpillable), knobs: k };
+    return { cut: -1, firstSpillable, lastUser, knobs: k };
   }
 
   // Only moves the cut at a severable index. A current-turn tool storm
@@ -1388,31 +1542,67 @@ export function cutTranscript(msgs, knobs = {}) {
   // index inside the chain, so this walk is a no-op — the byte budget is
   // applied by stubbing bodies in stubBoundFileResults, not by orphaning
   // a tool_result.
+  //
+  // When the overflow IS severable (grokui text hops: a fat previous
+  // command output sitting just before the current ask), start the tail
+  // AFTER that message so the live window is actually bounded. Starting
+  // AT the overflowing index left the fat hop in the forwarded body —
+  // spent≈direct on 1-model AUTO even after a cut existed.
   let tailStart = cut;
   {
     let used = 0;
     for (let i = msgs.length - 1; i >= cut; i--) {
       used += msgText(msgs[i]).length;
-      if (used > budget && isSeverable(msgs, i, firstSpillable)) { tailStart = i; break; }
+      if (used <= budget) continue;
+      const after = i + 1;
+      // Plain user/assistant hops only. Jumping after a tool_result would
+      // drop the current tool chain from the tail (orphans / lost pairing);
+      // those storms stay in-window and get stubbed.
+      const overflow = msgs[i];
+      const plainHop = overflow?.role === 'user' || (overflow?.role === 'assistant' && !toolCallIds(overflow).length);
+      if (plainHop && lastUser >= 0 && after <= lastUser && after > firstSpillable
+          && isSeverable(msgs, after, firstSpillable)) {
+        tailStart = after;
+        break;
+      }
+      if (isSeverable(msgs, i, firstSpillable)) { tailStart = i; break; }
     }
   }
   if (tailStart > cut) cut = tailStart;
 
+  // minTurns may still size the tail on a long thread, but never past the
+  // byte budget (that pulled fat 1-model hops back so sent≈unspilled).
+  // If walking earlier would empty the bind prefix, keep a non-empty prefix
+  // and allow fewer than minTurns. On a short thread that cannot satisfy
+  // minTurns at all, pin the last ask so early turns bind.
   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) {
+        if (sliceChars(msgs, i) > budget) break;
+        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, and do
+  // not expand past the byte budget (that re-imported fat 1-model hops).
   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;
+      if (sliceChars(msgs, i) > budget) break;
+      cut = i;
+      break;
     }
     if (cut > lastUser) cut = lastUser;
   }
@@ -1420,6 +1610,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,
@@ -1429,6 +1734,7 @@ function stubForCut(msgs, cut, opts) {
     aggressive: Boolean(opts.aggressive),
     budget: opts.budget,
     keepTail: opts.keepTail,
+    recall: opts.recall,
   });
 }
 
@@ -1452,6 +1758,7 @@ export function applySpillCut(msgs, {
   home,
   dollarX,
   lastSend,
+  recall,
 } = {}) {
   const persistOpts = { persist, file, home };
   let k = sanitizeKnobs(knobs || getLiveKnobs(persistOpts));
@@ -1472,7 +1779,7 @@ export function applySpillCut(msgs, {
     // 300-result storm is not forwarded at full size.
     const stubFrom = plan.firstSpillable >= 0 ? plan.firstSpillable : 0;
     let stubbed = stubForCut(msgs, stubFrom, {
-      boundFiles, boundAbs, cwd, aggressive: k.stubMore, budget: k.budget, keepTail: k.keepTail,
+      boundFiles, boundAbs, cwd, aggressive: k.stubMore, budget: k.budget, keepTail: k.keepTail, recall,
     });
     let sentChars = sliceChars(stubbed.messages, stubFrom);
     const corpus = Math.max(Number(corpusChars) || 0, sentChars);
@@ -1492,7 +1799,7 @@ export function applySpillCut(msgs, {
       action = decision.action;
       if (decision.recut) {
         stubbed = stubForCut(msgs, stubFrom, {
-          boundFiles, boundAbs, cwd, aggressive: k.stubMore, budget: k.budget, keepTail: k.keepTail,
+          boundFiles, boundAbs, cwd, aggressive: k.stubMore, budget: k.budget, keepTail: k.keepTail, recall,
         });
         sentChars = sliceChars(stubbed.messages, stubFrom);
         ratio = spillRatio(corpus, sentChars);
@@ -1518,7 +1825,7 @@ export function applySpillCut(msgs, {
   };
 
   let stubbed = stubForCut(msgs, plan.cut, {
-    boundFiles, boundAbs, cwd, aggressive: k.stubMore, budget: k.budget, keepTail: k.keepTail,
+    boundFiles, boundAbs, cwd, aggressive: k.stubMore, budget: k.budget, keepTail: k.keepTail, recall,
   });
   let stats = measure(plan.cut, stubbed, k);
   let action = 'hold';
@@ -1539,7 +1846,7 @@ export function applySpillCut(msgs, {
       plan = cutTranscript(msgs, k);
       if (plan.cut > plan.firstSpillable) {
         stubbed = stubForCut(msgs, plan.cut, {
-          boundFiles, boundAbs, cwd, aggressive: k.stubMore, budget: k.budget, keepTail: k.keepTail,
+          boundFiles, boundAbs, cwd, aggressive: k.stubMore, budget: k.budget, keepTail: k.keepTail, recall,
         });
         stats = measure(plan.cut, stubbed, k);
       }
@@ -1562,6 +1869,119 @@ export function applySpillCut(msgs, {
   };
 }
 
+/**
+ * Same threshold hrr.js BIND_MIN_CHARS uses. Kept here so the 1-model /
+ * raced AUTO decision can be tested without standing up the bind client.
+ */
+export const SPILL_MIN_PREFIX_CHARS = Number(process.env.OPENZOO_CONTEXT_MIN_CHARS || 16384);
+
+/**
+ * zoo_ask / chat-surface shape: one huge final string ending in `\n\n<ask>`.
+ * Agent transcripts (Claude Code, grokui) never look like this.
+ */
+export function isOneShotCorpusAsk(msgs, minChars = SPILL_MIN_PREFIX_CHARS) {
+  if (!Array.isArray(msgs) || !msgs.length) return false;
+  const last = msgs[msgs.length - 1];
+  if (typeof last?.content !== 'string') return false;
+  if (last.content.length <= minChars) return false;
+  if (last.content.lastIndexOf('\n\n') < minChars) return false;
+  const ask = last.content.slice(last.content.lastIndexOf('\n\n') + 2).trim();
+  return Boolean(ask && ask.length <= 8000);
+}
+
+function emptySpillDecision(msgs, reason) {
+  return {
+    mode: 'passthrough',
+    reason,
+    setHrrContext: false,
+    forwarded: msgs,
+    prefix: '',
+    head: [],
+    tail: msgs,
+    sentChars: sliceChars(msgs),
+    unspilledChars: sliceChars(msgs),
+  };
+}
+
+/**
+ * THE spill/bind/forward gate. 1-model grokui and raced grokui AUTO both
+ * POST /chat/completions through maybeCacheCorpus → this decision. `race`,
+ * `race_need`, and `tier` on the body are ignored — the cut is a property
+ * of messages[], not of how many models will read them.
+ *
+ * Oversized: bind the old prefix, forward system + bounded tail, and the
+ * sidecar must set x-hrr-context (setHrrContext). Small: passthrough,
+ * no bind, no header. Does not talk to the network.
+ */
+export function decideChatSpill(body, opts = {}) {
+  const msgs = Array.isArray(body?.messages) ? body.messages : null;
+  if (!msgs?.length) return emptySpillDecision(msgs, 'no-messages');
+  const minChars = opts.minPrefixChars ?? SPILL_MIN_PREFIX_CHARS;
+
+  if (isOneShotCorpusAsk(msgs, minChars)) {
+    const last = msgs[msgs.length - 1];
+    const at = last.content.lastIndexOf('\n\n');
+    const prefix = last.content.slice(0, at);
+    const ask = last.content.slice(at + 2).trim();
+    const forwarded = [...msgs.slice(0, -1), { ...last, content: ask }];
+    return {
+      mode: 'oneshot',
+      reason: 'corpus-question',
+      setHrrContext: true,
+      prefix,
+      ask,
+      forwarded,
+      head: msgs.slice(0, -1),
+      tail: [{ ...last, content: ask }],
+      sentChars: sliceChars(forwarded),
+      unspilledChars: sliceChars(msgs),
+    };
+  }
+
+  const adapted = applySpillCut(msgs, opts);
+  if (adapted.cut <= adapted.firstSpillable) {
+    if (adapted.stubbed?.dropped || adapted.stubbed?.stubbed) {
+      return {
+        mode: 'stub-only',
+        reason: 'no-cut-stubbed',
+        setHrrContext: false,
+        adapted,
+        forwarded: adapted.stubbed.messages,
+        prefix: '',
+        head: [],
+        tail: adapted.stubbed.messages,
+        sentChars: sliceChars(adapted.stubbed.messages),
+        unspilledChars: sliceChars(msgs),
+      };
+    }
+    return { ...emptySpillDecision(msgs, 'no-cut'), adapted };
+  }
+
+  const prefix = msgs.slice(adapted.firstSpillable, adapted.cut)
+    .map(msgText).filter(Boolean).join('\n\n');
+  if (prefix.length <= minChars) {
+    return { ...emptySpillDecision(msgs, 'prefix-under-threshold'), adapted, prefix };
+  }
+
+  const head = msgs.slice(0, adapted.firstSpillable);
+  const tail = adapted.stubbed.messages.slice(adapted.cut);
+  const forwarded = [...head, ...tail];
+  return {
+    mode: 'spill',
+    reason: 'oversized-prefix',
+    setHrrContext: true,
+    adapted,
+    prefix,
+    head,
+    tail,
+    forwarded,
+    cut: adapted.cut,
+    firstSpillable: adapted.firstSpillable,
+    sentChars: sliceChars(forwarded),
+    unspilledChars: sliceChars(msgs),
+  };
+}
+
 /** Session counters the HUD reads off /v1/info. */
 export function createSpillStats() {
   return {

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}` : ''}`;