openzoo 0.48.69 → 0.48.71

package/lib/launch.js

@@ -230,7 +230,18 @@ export async function launchClaude(argv) {
         + 'const sp=j.spilled||{};'
         + 'const tk=Number(sp.tokensApprox)||0;'
         + 'const ht=tk>=1e6?(tk/1e6).toFixed(1)+"M":tk>=1e3?Math.round(tk/1e3)+"k":String(tk);'
-        + 'const spill=tk?("  \\u00b7 "+ht+" tok offloaded"):"";'
+        + 'const paid=Number(j.paidCalls)||0;'
+        + 'const sc=Number(sp.calls)||0;'
+        + 'const fb=Number(sp.fileBinds)||0;'
+        + 'const rb=Number(sp.reusedBinds)||0;'
+        + 'const ls=sp.lastSend||{};'
+        + 'const bits=[];'
+        + 'bits.push("spilled "+sc+"/"+paid+" calls");'
+        + 'if(rb)bits.push(rb+" reused");'
+        + 'bits.push(fb+" filebind");'
+        + 'if(ls.sent!=null&&ls.msgs!=null)bits.push("sending "+ls.sent+"/"+ls.msgs);'
+        + 'if(tk)bits.push(ht+" tok offloaded");'
+        + 'const spill=bits.length?("  \\u00b7 "+bits.join("  \\u00b7 ")):"";'
         // "how can I easily see what credit i'm left" — asked by a user who
         // could not tell whether x402 had charged them at all.
         + 'const cr=(j.creditUsd==null)?"":("  \\u00b7 $"+Number(j.creditUsd).toFixed(2)+" credit");'

package/lib/proxy.js

@@ -12,6 +12,9 @@ import { PayClient, QuoteTooHighError, UnderfundedError } from './pay.js';
 import { tokenBalance } from './x402.js';
 import { evmTokenBalance } from './evm.js';
 import { bindCorpus, contextCacheDisabled, BIND_MIN_CHARS } from './hrr.js';
+import {
+  loadBoundChars, noteCorpusLedger, filesForCorpus, createSpillStats, corpusCharsForSend,
+} from './spill.js';
 import { maybeRewriteModel, rewritablePath, augmentModelList, ALIAS_IDS } from './models.js';
 import { forgetContext } from './contexts.js';
 import { injectBrief } from './brief.js';
@@ -122,6 +125,10 @@ const boundFiles = new Set();
 // context_id -> total chars BOUND (turns + files appended). The counterfactual
 // basis must reflect what the corpus actually holds, not just this turn's slice.
 const boundChars = new Map();
+// sessionKey -> { contextId, chars } so a sidecar restart can keep appending
+// to the same context and still send the accumulated x-hrr-corpus-chars.
+const sessionLedger = new Map();
+loadBoundChars(boundChars, { sessions: sessionLedger, boundFiles });
 
 // THIS MAP SURVIVES A RESTART, OR THE COUNTERFACTUAL DOES NOT.
 //
@@ -363,9 +370,53 @@ function msgText(m) {
  * severed at a plain `user` message — everything before one is self-contained.
  * A system message is never spilled: it is the operating contract, not history.
  */
-async function spillTranscript(body, log, req) {
+async function spillTranscript(body, log, req, stats) {
   const msgs = Array.isArray(body?.messages) ? body.messages : null;
-  if (!msgs || msgs.length < 6) return null;
+  if (!msgs?.length) return null;
+
+  // FILES FIRST. The cut/length gates below used to run before filesForCorpus,
+  // so a short agent turn that Read a file never bound it � and when the
+  // extract itself returned empty, nothing logged. Extract + log unconditionally.
+  const fileResult = filesForCorpus(msgs, { boundFiles, log });
+  const files = fileResult.text;
+  const sessionId = req?.headers?.['x-claude-code-session-id']
+    || req?.headers?.['x-session-id']
+    || req?.headers?.['x-claude-session-id']
+    || (typeof body?.metadata?.user_id === 'string' ? body.metadata.user_id : null);
+  let sessionKey = sessionId ? `sid:${sessionId}` : null;
+
+  const ledgerOpts = () => ({ sessionKey, sessions: sessionLedger, boundFiles });
+  const bindFilesInBackground = (label) => {
+    if (!files) return;
+    const known = (sessionKey && spillMemo.get(sessionKey))
+      || (sessionKey && sessionLedger.get(sessionKey))
+      || null;
+    const appendTo = known?.contextId || null;
+    void bindCorpus(files, {
+      appendTo,
+      onStage: (stage, info) => {
+        if (stage === 'binding') log(`binding ${info.bytes} bytes (${mb(info.bytes)}MB) of FILES (${label})`);
+      },
+    }).then((b) => {
+      if (!b?.contextId) return;
+      noteCorpusLedger(boundChars, {
+        contextId: b.contextId,
+        reused: Boolean(appendTo),
+        corpusChars: 0,
+        fileChars: files.length,
+        ...ledgerOpts(),
+      });
+      stats?.noteFileBind(fileResult.files, fileResult.bytes);
+      if (sessionKey && !spillMemo.has(sessionKey)) {
+        spillMemo.set(sessionKey, { corpus: '', contextId: b.contextId, hash: b.hash });
+      }
+    }).catch((e) => log(`file bind failed: ${e.message}`));
+  };
+
+  if (msgs.length < 6) {
+    bindFilesInBackground('conversation under 6 messages, background');
+    return null;
+  }
 
   // Keep the recent tail, but never more than half the transcript: a fixed 8 on
   // a 10-message body left only index 2 to search, which is rarely a user turn,
@@ -415,7 +466,10 @@ async function spillTranscript(body, log, req) {
       if (severable(i)) { cut = i; break; }
     }
   }
-  if (cut <= firstSpillable) return null;         // nothing safely severable
+  if (cut <= firstSpillable) {
+    bindFilesInBackground('no severable cut, files only');
+    return null;                                  // nothing safely severable
+  }
 
   // TRIM THE TAIL BY BYTES, NOT MESSAGE COUNT.
   //
@@ -529,93 +583,40 @@ async function spillTranscript(body, log, req) {
   // sitting on this machine. Binding it makes the corpus large immediately
   // instead of eventually, and makes the truncated read whole again.
   //
-  // Read-only, bounded, deduped by path+mtime, and failures are silent: this
-  // runs on the request path and must never be the reason a turn does not go.
-  const filesForCorpus = () => {
-    if (process.env.OPENZOO_BIND_FILES === '0') return '';
-    const cap = Number(process.env.OPENZOO_BIND_FILE_MAX || 400_000);
-    const out = [];
-    const seen = new Set();
-    for (const m of msgs) {
-      const blocks = Array.isArray(m?.content) ? m.content : [];
-      const calls = Array.isArray(m?.tool_calls) ? m.tool_calls : [];
-      const paths = [];
-      for (const b of blocks) {
-        const p = b?.input?.file_path || b?.input?.path;
-        if (typeof p === 'string') paths.push(p);
-      }
-      for (const c of calls) {
-        try {
-          const a = JSON.parse(c?.function?.arguments || '{}');
-          if (typeof a.file_path === 'string') paths.push(a.file_path);
-          else if (typeof a.path === 'string') paths.push(a.path);
-        } catch { /* not json args */ }
-      }
-      for (const p of paths) {
-        if (seen.has(p) || !path.isAbsolute(p)) continue;
-        seen.add(p);
-        try {
-          const st = fs.statSync(p);
-          if (!st.isFile() || st.size > cap) continue;
-          const key = `${p}:${st.mtimeMs}`;
-          if (boundFiles.has(key)) continue;
-          boundFiles.add(key);
-          out.push(`FILE ${p}\n${fs.readFileSync(p, 'utf8')}`);
-        } catch { /* unreadable, gone, or binary — simply not corpus */ }
-      }
-    }
-    return out.join('\n\n');
-  };
-
+  // Read-only, bounded, deduped by path+mtime. Path extraction + the file-bind
+  // log already ran at the top of this function (files / fileResult).
+  //
   // FILES RIDE THE BACKGROUND, NEVER THE CRITICAL PATH.
   //
-  // The FIRST bind of a session is necessarily synchronous — the request cannot
+  // 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.
   //
-  // 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.
   const turns = msgs.slice(firstSpillable, cut).map(msgText).filter(Boolean).join('\n\n');
-  const files = filesForCorpus();
   const corpus = turns;
+  if (!sessionKey) sessionKey = corpus.slice(0, 2048);
 
   // 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
+  // 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
+  // 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.
-  const sessionId = req?.headers?.['x-claude-code-session-id']
-    || req?.headers?.['x-session-id']
-    || req?.headers?.['x-claude-session-id']
-    || (typeof body?.metadata?.user_id === 'string' ? body.metadata.user_id : null);
-  const sessionKey = sessionId ? `sid:${sessionId}` : corpus.slice(0, 2048);
   if (corpus.length <= BIND_MIN_CHARS) {
-    if (files) {
-      const known = spillMemo.get(sessionKey);
-      void bindCorpus(files, {
-        appendTo: known?.contextId || null,
-        onStage: (stage, info) => {
-          if (stage === 'binding') log(`binding ${mb(info.bytes)}MB of FILES (conversation under spill threshold, background)`);
-        },
-      }).then((b) => {
-        if (!b?.contextId) return;
-        boundChars.set(b.contextId, (boundChars.get(b.contextId) || 0) + files.length);
-        persistBoundChars();
-        if (!known) spillMemo.set(sessionKey, { corpus, contextId: b.contextId, hash: b.hash });
-      }).catch((e) => log(`file bind failed: ${e.message}`));
-    }
+    bindFilesInBackground('conversation under spill threshold, background');
     return null;
   }
 
@@ -650,11 +651,30 @@ async function spillTranscript(body, log, req) {
   //   anthropic-beta, anthropic-version, x-app, x-claude-code-session-id,
   //   x-stainless-*
   const anchor = sessionKey;
-  const prior = spillMemo.get(anchor);
+  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);
   let bind;
-  if (prior && corpus.startsWith(prior.corpus) && corpus.length > prior.corpus.length) {
+  let deltaChars = 0;
+  let appended = false;
+  if (prior?.restored && prior.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.
+    void bindCorpus(corpus, {
+      appendTo: prior.contextId,
+      onStage: (stage, info) => {
+        if (stage === 'binding') log(`appending ${mb(info.bytes)}MB to ${prior.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);
-    // FIRE AND FORGET. This delta is history for FUTURE turns — the answer
+    deltaChars = delta.length;
+    // 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
@@ -662,7 +682,7 @@ async function spillTranscript(body, log, req) {
     //
     // 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
+    // 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, {
@@ -671,6 +691,7 @@ async function spillTranscript(body, log, req) {
         if (stage === 'binding') log(`appending ${mb(info.bytes)}MB to ${prior.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 };
   } else {
     bind = await bindCorpus(corpus, {
@@ -679,17 +700,28 @@ async function spillTranscript(body, log, req) {
       },
     });
   }
+  // CONVERSATION LEDGER � every successful bind AND append, not only when
+  // files exist. First bind initializes to the bound corpus size; each append
+  // adds the delta; file bytes ride on top. This is what makes x-hrr-corpus-chars
+  // the accumulated bound corpus instead of this-turn's prefix.
+  noteCorpusLedger(boundChars, {
+    contextId: bind.contextId,
+    reused: appended,
+    corpusChars: corpus.length,
+    deltaChars,
+    fileChars: files.length,
+    ...ledgerOpts(),
+  });
   // APPEND THE FILES AFTER, off the clock. Fire-and-forget against the context
   // we just secured: this turn is already answerable without them, and the next
   // ask gets them for free. `boundFiles` already deduped by path:mtime, so this
   // uploads each version exactly once no matter how often the agent re-reads it.
   if (files) {
-    boundChars.set(bind.contextId, (boundChars.get(bind.contextId) || corpus.length) + files.length);
-    persistBoundChars();
+    stats?.noteFileBind(fileResult.files, fileResult.bytes);
     void bindCorpus(files, {
       appendTo: bind.contextId,
       onStage: (stage, info) => {
-        if (stage === 'binding') log(`appending ${mb(info.bytes)}MB of FILES to ${bind.contextId} (background)`);
+        if (stage === 'binding') log(`appending ${info.bytes} bytes (${mb(info.bytes)}MB) of FILES to ${bind.contextId} (background)`);
       },
     }).catch((e) => log(`file append failed (corpus lags one turn): ${e.message}`));
   }
@@ -744,14 +776,26 @@ async function spillTranscript(body, log, req) {
     corpus,
     reused: bind.reused,
     savedBytes: bind.bytes,
+    sent,
+    msgs: msgs.length,
   };
 }
 
-async function maybeCacheCorpus(req, bodyBuf, log) {
+async function maybeCacheCorpus(req, bodyBuf, log, stats) {
   if (contextCacheDisabled()) return null;
   if (req.method !== 'POST' || !(req.url || '').includes('/chat/completions')) return null;
   if (req.headers['x-hrr-context']) return null; // harness manages its own context
-  if (bodyBuf.length <= BIND_MIN_CHARS) return null;
+  if (bodyBuf.length <= BIND_MIN_CHARS) {
+    // Still walk the transcript: a short agent turn that Read a file should
+    // bind it even when there is nothing large enough to spill.
+    try {
+      const body = JSON.parse(bodyBuf.toString('utf8'));
+      if (Array.isArray(body?.messages) && body.messages.length) {
+        return spillTranscript(body, log, req, stats);
+      }
+    } catch { /* not json */ }
+    return null;
+  }
   let body;
   try { body = JSON.parse(bodyBuf.toString('utf8')); } catch { return null; }
   const msgs = Array.isArray(body?.messages) ? body.messages : null;
@@ -764,17 +808,24 @@ async function maybeCacheCorpus(req, bodyBuf, log) {
   const oneShot = typeof last?.content === 'string'
     && last.content.length > BIND_MIN_CHARS
     && last.content.lastIndexOf('\n\n') >= BIND_MIN_CHARS;
-  if (!oneShot) return spillTranscript(body, log, req);
+  if (!oneShot) return spillTranscript(body, log, req, stats);
   const cut = last.content.lastIndexOf('\n\n');
   const corpus = last.content.slice(0, cut);
   const ask = last.content.slice(cut + 2).trim();
-  if (!ask || ask.length > 8000) return spillTranscript(body, log, req);
+  if (!ask || ask.length > 8000) return spillTranscript(body, log, req, stats);
 
   const bind = await bindCorpus(corpus, {
     onStage: (stage, info) => {
       if (stage === 'binding') log(`binding ${mb(info.bytes)}MB corpus to holographic memory (one-time)...`);
     },
   });
+  noteCorpusLedger(boundChars, {
+    contextId: bind.contextId,
+    reused: false,
+    corpusChars: corpus.length,
+    sessions: sessionLedger,
+    boundFiles,
+  });
   if (bind.reused) {
     log(`corpus already bound (${bind.hash.slice(0, 12)}… → ${bind.contextId}) — skipped ${mb(bind.bytes)}MB upload`);
   } else {
@@ -788,6 +839,8 @@ async function maybeCacheCorpus(req, bodyBuf, log) {
     corpus,
     reused: bind.reused,
     savedBytes: bind.bytes,
+    sent: 1,
+    msgs: msgs.length,
   };
 }
 
@@ -850,16 +903,14 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
   // SPILL ACCOUNTING. The product's whole claim is that context is offloaded
   // instead of re-sent, and nothing measured it — the status line showed spend
   // and call count, which is the cost side with none of the benefit.
-  let spillCalls = 0;
-  let spilledChars = 0;
-  let spillReuses = 0;
+  const spill = createSpillStats();
+  let lastSpillSend = null;
   // Spend/direct for ONLY the calls that spilled. The session-wide savingX
   // averages these with every small turn that had nothing to offload, so it
   // slides toward 1.0 as a conversation grows — which reads as the mechanism
   // degrading when it is just the mix changing. OBSERVED: 1.3166 -> 1.1823
   // while spilled calls and offloaded tokens both sat completely still.
-  let spillSpend = 0;
-  let spillDirect = 0;
+  // spillSpend / spillDirect live on `spill` (createSpillStats).
   // ACTUAL UPSTREAM SPEND, FROM THE PROVIDER — not our estimate of it.
   //
   // Every other dollar figure here is derived from OpenRouter's CATALOG price
@@ -998,19 +1049,14 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
           reachedVia: viaTunnel ? 'public tunnel' : 'localhost',
           publicTunnel: tunnelGate?.publicUrl ? `${tunnelGate.publicUrl}/v1` : null,
           servedRequests,
-          spilled: {
-            calls: spillCalls,
-            chars: spilledChars,
-            // ~4 chars/token is the usual rough rule; this is the context that
-            // did NOT ride upstream on those calls, which is the number the
-            // saving is actually made of.
-            tokensApprox: Math.round(spilledChars / 4),
-            reusedBinds: spillReuses,
-            spend: spillSpend,
-            direct: spillDirect,
-            savedUsd: Math.max(0, spillDirect - spillSpend),
-            savingX: spillSpend > 0 ? Number((spillDirect / spillSpend).toFixed(4)) : null,
-          },
+          spilled: (() => {
+            const ledgerTotal = [...boundChars.values()].reduce((a, b) => a + b, 0);
+            return {
+              ...spill.snapshot({ boundChars: ledgerTotal }),
+              boundChars: ledgerTotal,
+              lastSend: lastSpillSend,
+            };
+          })(),
           spendUsd: sessionSpent,
           creditUsd,
           // WHAT THE SAME CALLS WOULD HAVE COST DIRECT. Spend on its own is a
@@ -1433,7 +1479,7 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
     try {
       let cached = null;
       try {
-        cached = await maybeCacheCorpus(req, bodyBuf, log);
+        cached = await maybeCacheCorpus(req, bodyBuf, log, spill);
       } catch (err) {
         log(`context cache skipped for this call: ${err.message}`);
       }
@@ -1462,11 +1508,10 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
       let didSpill = false;
       let result;
       if (cached) {
-        spillCalls += 1;
+        spill.noteSpill({ corpusChars: cached.corpus?.length || 0, reused: cached.reused });
         didSpill = true;
-        spilledChars += cached.corpus?.length || 0;
-        if (cached.reused) spillReuses += 1;
-        result = await send(cached.body, cached.contextId, cached.topK, boundChars.get(cached.contextId) || cached.corpus?.length);
+        if (cached.sent != null) lastSpillSend = { sent: cached.sent, msgs: cached.msgs };
+        result = await send(cached.body, cached.contextId, cached.topK, corpusCharsForSend(boundChars, cached.contextId, cached.corpus?.length));
         // Sidecar wiped between runs: the gateway 404s BEFORE the 402 (nothing
         // paid). Never fail on a stale manifest — re-bind once and retry.
         if (result.response.status === 404) {
@@ -1475,7 +1520,7 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
             log('bound context is gone on the zoo — re-binding once...');
             forgetContext(config.apiBase, cached.hash);
             const rebound = await bindCorpus(cached.corpus, { force: true });
-            result = await send(cached.body, rebound.contextId, cached.topK, boundChars.get(rebound.contextId) || cached.corpus?.length);
+            result = await send(cached.body, rebound.contextId, cached.topK, corpusCharsForSend(boundChars, rebound.contextId, cached.corpus?.length));
           } else {
             res.writeHead(404, { 'content-type': 'application/json' });
             res.end(text);
@@ -1506,8 +1551,8 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
           // orders of magnitude above what was billed. directUsd is exact and
           // always present; savesVsDirect is the same number as a ratio.
           if (didSpill) {
-            spillSpend += receipt.billedUsd || 0;
-            spillDirect += typeof receipt.directUsd === 'number' ? receipt.directUsd : (receipt.billedUsd || 0);
+            spill.spillSpend += receipt.billedUsd || 0;
+            spill.spillDirect += typeof receipt.directUsd === 'number' ? receipt.directUsd : (receipt.billedUsd || 0);
           }
           sessionDirect += typeof receipt.directUsd === 'number'
             ? receipt.directUsd
@@ -1527,10 +1572,10 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
         // the receipt lines go to a file (they corrupt a TUI). But the running
         // total should still be visible — so write it to the terminal TITLE via
         // an OSC escape, which updates the window/tab title without touching the
-        // TUI's content. `openzoo ● $0.0042 · 12 calls` in the title bar, live.
+        // TUI's content. `openzoo ◝ $0.0042 · 12 calls` in the title bar, live.
         if (receipt.ok && typeof receipt.billedUsd === 'number') { paidCalls += 1; }
         if (sayFile) {
-          try { process.stderr.write(`]0;openzoo ● $${sessionSpent.toFixed(4)} · ${paidCalls} call${paidCalls === 1 ? '' : 's'}`); } catch { /* no tty */ }
+          try { process.stderr.write(`]0;openzoo ◝ $${sessionSpent.toFixed(4)} · ${paidCalls} call${paidCalls === 1 ? '' : 's'}`); } catch { /* no tty */ }
         }
         scheduleRefresh(4000); // settlement lands on-chain in a few seconds
       }
@@ -1583,8 +1628,8 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
             // 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)}`);
-            spillSpend += x.billedUsd;
-            spillDirect += typeof x.directUsd === 'number' ? x.directUsd : x.billedUsd;
+            spill.spillSpend += x.billedUsd;
+            spill.spillDirect += typeof x.directUsd === 'number' ? x.directUsd : x.billedUsd;
           }
           paidCalls += 1;
           if (viaTunnel) tunnelSpent += x.billedUsd;
@@ -1639,8 +1684,8 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
         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)}`);
-          spillSpend += x.billedUsd;
-          spillDirect += typeof x.directUsd === 'number' ? x.directUsd : x.billedUsd;
+          spill.spillSpend += x.billedUsd;
+          spill.spillDirect += typeof x.directUsd === 'number' ? x.directUsd : x.billedUsd;
         }
         paidCalls += 1;
         if (viaTunnel) tunnelSpent += x.billedUsd;

package/lib/spill.js

@@ -0,0 +1,400 @@
+/**
+ * Spill-side bookkeeping that used to live (and die) inside proxy.js.
+ *
+ * Three things the status line needs, and that a live session was not getting:
+ *   1. A corpus ledger that accumulates bind + append + file bytes, persisted
+ *      so a sidecar restart still knows how big the bound context is.
+ *   2. File-path extraction that matches Claude Code / Anthropic tool_use
+ *      (and the OpenAI shape those requests are translated into).
+ *   3. Counters for spilled calls, file-bind events, and offloaded chars —
+ *      incremented on the spill path, never on a pass-through.
+ *
+ * Kept as pure-enough helpers so test/spill.test.js can cover them without
+ * standing up the proxy or the gateway.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const PATH_KEYS = new Set([
+  'file_path', 'path', 'target_file', 'filePath', 'filename', 'file',
+  'targetFile', 'filepath',
+]);
+const PATH_ARRAY_KEYS = new Set(['files', 'file_paths', 'paths', 'filePaths']);
+
+export function boundCharsFile(home = os.homedir()) {
+  return process.env.OPENZOO_BOUND_CHARS_PATH
+    || path.join(home, '.openzoo', 'bound-chars.json');
+}
+
+/**
+ * Load ~/.openzoo/bound-chars.json into the maps the proxy holds.
+ * Missing / corrupt file is a cold start, not an error.
+ */
+export function loadBoundChars(boundChars, extra = {}) {
+  const file = extra.file || boundCharsFile(extra.home);
+  let raw;
+  try { raw = fs.readFileSync(file, 'utf8'); } catch { return { ok: false, reason: 'missing' }; }
+  let data;
+  try { data = JSON.parse(raw); } catch { return { ok: false, reason: 'corrupt' }; }
+  const chars = data?.chars && typeof data.chars === 'object' ? data.chars
+    : (data && typeof data === 'object' && !data.sessions && !data.files ? data : {});
+  for (const [id, n] of Object.entries(chars)) {
+    const v = Number(n);
+    if (id && Number.isFinite(v) && v > 0) boundChars.set(id, v);
+  }
+  if (extra.sessions && data?.sessions && typeof data.sessions === 'object') {
+    for (const [k, v] of Object.entries(data.sessions)) {
+      if (k && v && typeof v.contextId === 'string') extra.sessions.set(k, v);
+    }
+  }
+  if (extra.boundFiles && Array.isArray(data?.files)) {
+    for (const key of data.files) {
+      if (typeof key === 'string') extra.boundFiles.add(key);
+    }
+  }
+  return { ok: true, contexts: boundChars.size };
+}
+
+export function persistBoundChars(boundChars, extra = {}) {
+  const file = extra.file || boundCharsFile(extra.home);
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const payload = {
+      chars: Object.fromEntries(boundChars),
+    };
+    if (extra.sessions) payload.sessions = Object.fromEntries(extra.sessions);
+    if (extra.boundFiles) payload.files = [...extra.boundFiles];
+    const tmp = `${file}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(payload));
+    fs.renameSync(tmp, file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Accumulate bound bytes for a context.
+ *
+ *   init  — first bind: ledger becomes `chars` (the bound corpus size)
+ *   add   — append / file: ledger += chars
+ *
+ * Persist after every successful update so a crash mid-session keeps the count.
+ */
+export function accumulateBoundChars(boundChars, contextId, chars, opts = {}) {
+  if (!contextId || !Number.isFinite(chars) || chars < 0) return boundChars.get(contextId) || 0;
+  const next = opts.init ? chars : (boundChars.get(contextId) || 0) + chars;
+  boundChars.set(contextId, next);
+  if (opts.sessionKey && opts.sessions) {
+    opts.sessions.set(opts.sessionKey, { contextId, chars: next });
+  }
+  if (opts.persist !== false) persistBoundChars(boundChars, opts);
+  return next;
+}
+
+/**
+ * Conversation chars use Math.max so a stale smaller ledger (the 34056
+ * files-only row) cannot cap a later, larger prefix. New file bytes add on top.
+ *
+ *   next = max(prev, corpusChars) + fileChars
+ */
+export function noteCorpusLedger(boundChars, {
+  contextId, corpusChars = 0, fileChars = 0, ...opts
+} = {}) {
+  if (!contextId) return 0;
+  const prev = boundChars.get(contextId) || 0;
+  const next = Math.max(prev, Number(corpusChars) || 0) + (Number(fileChars) || 0);
+  boundChars.set(contextId, next);
+  if (opts.sessionKey && opts.sessions) {
+    opts.sessions.set(opts.sessionKey, { contextId, chars: next });
+  }
+  persistBoundChars(boundChars, opts);
+  return next;
+}
+
+/** send() must not let `stale || thisTurn` pick the smaller number. */
+export function corpusCharsForSend(boundChars, contextId, thisTurn) {
+  return Math.max(boundChars.get(contextId) || 0, thisTurn || 0);
+}
+
+/** Expand ~ and resolve relative paths against cwd. Returns null if unusable. */
+export function resolveReadablePath(p, cwd = process.cwd()) {
+  if (typeof p !== 'string') return null;
+  let s = p.trim();
+  if (!s || s.length > 1024 || /[\n\r]/.test(s)) return null;
+  if (/^https?:\/\//i.test(s)) return null;
+  if (s.startsWith('~/') || s === '~') s = path.join(os.homedir(), s.slice(1).replace(/^\//, '') || '');
+  if (!path.isAbsolute(s)) s = path.resolve(cwd, s);
+  return s;
+}
+
+function looksLikePath(s) {
+  if (typeof s !== 'string') return false;
+  const t = s.trim();
+  if (t.length < 2 || t.length > 1024 || /[\n\r]/.test(t)) return false;
+  if (/^https?:\/\//i.test(t)) return false;
+  return /[\\/]/.test(t) || /\.\w{1,10}$/.test(t) || t.startsWith('~') || t.startsWith('.');
+}
+
+function parseArgs(args) {
+  if (args == null) return {};
+  if (typeof args === 'object' && !Array.isArray(args)) return args;
+  if (typeof args === 'string') {
+    const t = args.trim();
+    if (!t) return {};
+    try { return JSON.parse(t); } catch { return {}; }
+  }
+  return {};
+}
+
+function collectStructuredPaths(args, out) {
+  if (!args || typeof args !== 'object') return;
+  for (const k of PATH_KEYS) {
+    if (typeof args[k] === 'string' && args[k]) out.push(args[k]);
+  }
+  for (const k of PATH_ARRAY_KEYS) {
+    if (!Array.isArray(args[k])) continue;
+    for (const x of args[k]) {
+      if (typeof x === 'string') out.push(x);
+      else if (x && typeof x === 'object') collectStructuredPaths(x, out);
+    }
+  }
+}
+
+const CWD_HINT = /(?:current working directory is[:\s]+|<cwd>\s*|cwd:\s+)([^\s<]+)/i;
+
+export function parseCwdHint(text) {
+  if (typeof text !== 'string' || !text) return null;
+  const m = text.match(CWD_HINT);
+  if (!m) return null;
+  const p = m[1].trim();
+  return path.isAbsolute(p) ? p : null;
+}
+
+/**
+ * Pull path-like tokens out of a Bash `command` string.
+ * `head -80 programs/README.md` and `cat /abs/file` both count; bare `ls` does not.
+ */
+export function extractBashPaths(command, cwd = process.cwd()) {
+  const found = [];
+  if (typeof command !== 'string' || !command) return { paths: found, cwd };
+  let localCwd = cwd;
+  for (const part of command.split(/(?:&&|\|\||;|\n)/)) {
+    const cd = part.match(/^\s*cd\s+(?:\/[dD]\s+)?(['"]?)(.+?)\1\s*$/);
+    if (cd) {
+      const dest = resolveReadablePath(cd[2].trim(), localCwd);
+      if (dest) localCwd = dest;
+      continue;
+    }
+    for (const m of part.matchAll(/(['"])([^'"]+)\1/g)) {
+      const t = m[2].trim();
+      if (looksLikePath(t) || path.isAbsolute(t)) found.push({ raw: t, cwd: localCwd });
+    }
+    for (const tok of part.split(/\s+/)) {
+      const t = tok.replace(/^[`'"]|[`'"]$/g, '');
+      if (!t || t.startsWith('-') || t.startsWith('$') || t === '.' || t === '..') continue;
+      if (looksLikePath(t) || path.isAbsolute(t)) found.push({ raw: t, cwd: localCwd });
+    }
+  }
+  return { paths: found, cwd: localCwd };
+}
+
+/**
+ * Live Claude Code msgs are OpenAI-shaped (spill runs AFTER anthropicToOpenAI).
+ * Read/Edit/Write land on tool_calls[].function.arguments as a JSON string
+ * {file_path:"/abs/..."}. Bash is {command:"head -80 programs/README.md"}.
+ * Do not expect Read tool_result to carry the path. Do not harvest import
+ * paths out of tool_result bodies.
+ */
+export function extractFileCandidates(msgs, { cwd = process.cwd() } = {}) {
+  const structured = [];
+  const bash = [];
+  let currentCwd = cwd;
+  if (!Array.isArray(msgs)) return { structured, bash, cwd: currentCwd };
+  for (const m of msgs) {
+    if (!m || typeof m !== 'object') continue;
+    if (m.role === 'tool' && typeof m.content === 'string') {
+      const hint = parseCwdHint(m.content);
+      if (hint) currentCwd = hint;
+    }
+    const calls = [
+      ...(Array.isArray(m.tool_calls) ? m.tool_calls : []),
+      ...(m.function_call ? [m.function_call] : []),
+    ];
+    for (const c of calls) {
+      const args = parseArgs(c?.function?.arguments ?? c?.arguments);
+      const fromArgs = [];
+      collectStructuredPaths(args, fromArgs);
+      for (const raw of fromArgs) structured.push({ raw, cwd: currentCwd });
+      if (typeof args.command === 'string') {
+        const got = extractBashPaths(args.command, currentCwd);
+        for (const p of got.paths) bash.push({ ...p, bash: true });
+        currentCwd = got.cwd;
+      }
+    }
+    // Harmless leftover: pre-conversion Anthropic tool_use. Live Claude Code
+    // never has this by the time spillTranscript runs.
+    const blocks = Array.isArray(m.content) ? m.content : [];
+    for (const b of blocks) {
+      if (b?.input) {
+        const fromInput = [];
+        collectStructuredPaths(b.input, fromInput);
+        for (const raw of fromInput) structured.push({ raw, cwd: currentCwd });
+        if (typeof b.input.command === 'string') {
+          const got = extractBashPaths(b.input.command, currentCwd);
+          for (const p of got.paths) bash.push({ ...p, bash: true });
+          currentCwd = got.cwd;
+        }
+      }
+    }
+  }
+  return { structured, bash, cwd: currentCwd };
+}
+
+export function extractFilePaths(msgs, opts) {
+  const { structured, bash } = extractFileCandidates(msgs, opts);
+  const seen = new Set();
+  const out = [];
+  for (const item of [...structured, ...bash]) {
+    const t = typeof item === 'string' ? item : item?.raw;
+    if (typeof t !== 'string') continue;
+    const s = t.trim();
+    if (!s || seen.has(s)) continue;
+    seen.add(s);
+    out.push(s);
+  }
+  return out;
+}
+
+const SKIP_DIR_NAMES = new Set(['node_modules', '.git', 'dist', 'build', '__pycache__', '.venv', 'target']);
+
+function fileBindLog({ kept, bytes, enoent, cap, dir, rel, bash }) {
+  return `file-bind kept=${kept} bytes=${bytes} skip enoent=${enoent} cap=${cap} dir=${dir} rel=${rel} bash=${bash}`;
+}
+
+/**
+ * Read every new file the agent touched and return the corpus slice to bind.
+ *
+ * Live path is OpenAI tool_calls (Read/Edit/Write + Bash command). Relative
+ * paths resolve against cwd / last "current working directory is …" hint.
+ * Directories expand to children that are files under the cap.
+ *
+ * Always logs `file-bind kept=N bytes=B skip enoent=X cap=Y dir=Z rel=W bash=K`
+ * so grep-for-FILES is no longer the only signal. Bytes, not 0.0MB.
+ */
+export function filesForCorpus(msgs, {
+  boundFiles,
+  cwd = process.cwd(),
+  cap = Number(process.env.OPENZOO_BIND_FILE_MAX || 400_000),
+  disabled = process.env.OPENZOO_BIND_FILES === '0',
+  log = () => {},
+  statSync = (p) => fs.statSync(p),
+  readFileSync = (p) => fs.readFileSync(p, 'utf8'),
+  readdirSync = (p) => fs.readdirSync(p),
+} = {}) {
+  const empty = { kept: 0, bytes: 0, enoent: 0, cap: 0, dir: 0, rel: 0, bash: 0 };
+  if (disabled) {
+    log(fileBindLog(empty));
+    return { text: '', files: 0, bytes: 0, reason: 'disabled', ...empty };
+  }
+  const { structured, bash } = extractFileCandidates(msgs, { cwd });
+  const candidates = [
+    ...structured.map((p) => ({ ...p, bash: false })),
+    ...bash.map((p) => ({ ...p, bash: true })),
+  ];
+  const skip = { enoent: 0, cap: 0, dir: 0, rel: 0 };
+  const seen = new Set();
+  const chunks = [];
+
+  const tryBind = (abs) => {
+    if (!abs || seen.has(abs)) return;
+    seen.add(abs);
+    let st;
+    try { st = statSync(abs); } catch { skip.enoent += 1; return; }
+    if (st.isDirectory()) {
+      skip.dir += 1;
+      let kids = [];
+      try { kids = readdirSync(abs); } catch { skip.enoent += 1; return; }
+      for (const name of kids) {
+        if (!name || name.startsWith('.') || SKIP_DIR_NAMES.has(name)) continue;
+        const kid = path.join(abs, name);
+        let ks;
+        try { ks = statSync(kid); } catch { skip.enoent += 1; continue; }
+        if (ks.isFile()) tryBind(kid);
+      }
+      return;
+    }
+    if (!st.isFile()) { skip.enoent += 1; return; }
+    if (st.size > cap) { skip.cap += 1; return; }
+    const key = `${abs}:${st.mtimeMs}`;
+    if (boundFiles?.has(key)) return;
+    boundFiles?.add(key);
+    try {
+      chunks.push(`FILE ${abs}\n${readFileSync(abs)}`);
+    } catch {
+      skip.enoent += 1;
+    }
+  };
+
+  for (const item of candidates) {
+    const raw = item.raw;
+    if (!path.isAbsolute(raw) && !(raw.startsWith('~/') || raw === '~')) skip.rel += 1;
+    const abs = resolveReadablePath(raw, item.cwd || cwd);
+    if (!abs) { skip.enoent += 1; continue; }
+    tryBind(abs);
+  }
+
+  const text = chunks.join('\n\n');
+  const stats = {
+    kept: chunks.length,
+    bytes: text.length,
+    enoent: skip.enoent,
+    cap: skip.cap,
+    dir: skip.dir,
+    rel: skip.rel,
+    bash: bash.length,
+  };
+  log(fileBindLog(stats));
+  return { text, files: chunks.length, bytes: text.length, reason: chunks.length ? null : 'none-kept', ...stats };
+}
+
+/** Session counters the HUD reads off /v1/info. */
+export function createSpillStats() {
+  return {
+    spillCalls: 0,
+    spilledChars: 0,
+    spillReuses: 0,
+    fileBinds: 0,
+    fileBindBytes: 0,
+    spillSpend: 0,
+    spillDirect: 0,
+    noteSpill({ corpusChars = 0, reused = false } = {}) {
+      this.spillCalls += 1;
+      this.spilledChars += corpusChars;
+      if (reused) this.spillReuses += 1;
+    },
+    noteFileBind(n, bytes = 0) {
+      if (!n) return;
+      this.fileBinds += n;
+      this.fileBindBytes += bytes;
+      this.spilledChars += bytes;
+    },
+    snapshot({ boundChars = null } = {}) {
+      const unique = boundChars == null ? this.spilledChars : boundChars;
+      return {
+        calls: this.spillCalls,
+        chars: this.spilledChars,
+        // Unique bound size — do not re-add the same prefix on every reuse.
+        tokensApprox: Math.round(unique / 4),
+        reusedBinds: this.spillReuses,
+        fileBinds: this.fileBinds,
+        fileBindBytes: this.fileBindBytes,
+        spend: this.spillSpend,
+        direct: this.spillDirect,
+        savedUsd: Math.max(0, this.spillDirect - this.spillSpend),
+        savingX: this.spillSpend > 0 ? Number((this.spillDirect / this.spillSpend).toFixed(4)) : null,
+      };
+    },
+  };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openzoo",
-  "version": "0.48.69",
-  "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.",
+  "version": "0.48.71",
+  "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.",
   "license": "MIT",
   "type": "module",
   "bin": {