openzoo 0.48.22 → 0.48.24

package/bin/openzoo.js

@@ -1,4 +1,58 @@
 #!/usr/bin/env node
+// NODE >=18 OR NOTHING — AND HEAL IT IF WE CAN.
+//
+// package.json says engines >=18 but npm only WARNS, so an old node walked
+// straight in and died somewhere useless: there is no global `fetch` before 18,
+// so the very first probe threw, a bare `catch` swallowed it, and the user was
+// left staring at "starting the proxy in the background..." forever with no
+// error to report. Reported from the wild on macOS.
+//
+// Detect-and-exit is not enough when the machine usually HAS a good node sitting
+// in nvm/homebrew and merely isn't using it. Find one and re-exec through it;
+// only give up (with the exact fix) when there is genuinely nothing to run on.
+// NOTE: plain 'fs'/'path' specifiers, not 'node:fs'. The node: prefix only
+// resolves from 14.13.1, and this block's whole job is to run on the old
+// runtime we are rejecting — an import error here would defeat the message.
+import { existsSync, readdirSync } from 'fs';
+import { execFileSync, spawnSync } from 'child_process';
+import { homedir } from 'os';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+
+const MIN_NODE = 18;
+if (Number(process.versions.node.split('.')[0]) < MIN_NODE && !process.env.OPENZOO_NODE_REEXEC) {
+  const candidates = ['/opt/homebrew/bin/node', '/usr/local/bin/node', '/usr/bin/node'].filter(existsSync);
+  // nvm keeps every install under ~/.nvm/versions/node/vNN.../bin/node —
+  // newest first, so we land on the best available rather than the oldest.
+  try {
+    const nvm = join(process.env.NVM_DIR || join(homedir(), '.nvm'), 'versions', 'node');
+    for (const v of readdirSync(nvm)
+      .filter((d) => /^v\d+/.test(d))
+      .sort((a, b) => parseInt(b.slice(1), 10) - parseInt(a.slice(1), 10))) {
+      const p = join(nvm, v, 'bin', 'node');
+      if (existsSync(p)) candidates.push(p);
+    }
+  } catch { /* no nvm, fine */ }
+
+  for (const node of candidates) {
+    let v = 0;
+    try { v = Number(execFileSync(node, ['-v'], { encoding: 'utf8' }).trim().slice(1).split('.')[0]); } catch { continue; }
+    if (v < MIN_NODE) continue;
+    console.error(`openzoo: node ${process.versions.node} is too old (need >=${MIN_NODE}) — re-running under ${node} (v${v})`);
+    const r = spawnSync(node, [fileURLToPath(import.meta.url), ...process.argv.slice(2)], {
+      stdio: 'inherit',
+      env: { ...process.env, OPENZOO_NODE_REEXEC: '1' },
+    });
+    process.exit(r.status === null ? 1 : r.status);
+  }
+
+  console.error(`openzoo: needs Node >=${MIN_NODE}, you are on ${process.versions.node}.`);
+  console.error('  no newer node found on this machine. install one, then re-run:');
+  console.error('    brew install node            # macOS');
+  console.error('    nvm install 20 && nvm use 20 # if you use nvm');
+  process.exit(1);
+}
+
 const cmd = process.argv[2] || 'proxy';
 
 const HELP = `openzoo — local x402-paying proxy + MCP server for openzoo.fun

package/lib/info.js

@@ -24,8 +24,53 @@ function fmtUi(raw, decimals) {
  * price is known ($1 stables); everything else gets an honest `?`.
  * A chain whose RPC does not answer prints as unreachable — never as zero.
  */
+/**
+ * USD per whole token, by SYMBOL, straight from the 402 quote.
+ *
+ * The quote already carries `extra.tokenUsd` for every asset it settles in —
+ * the very "priced at the 402" this file kept promising in a footnote while
+ * printing `$?`. So a wallet holding 845,486 TOKEN summed to "≈ $0.11 known".
+ * Symbols come back wrapped (wTOKENx, wLEOSx, wUSDGx); strip the wrapper so a
+ * row for the plain token the user actually holds finds its price.
+ */
+async function quotedPrices() {
+  const out = {};
+  try {
+    // Imported here, not at module scope, matching affordableUsd below — this
+    // file is loaded by `openzoo address`, which must work with no network.
+    const { withNamespace } = await import('./namespace.js');
+    const r = await fetch(`${config.apiBase}/v1/credits/topup`, {
+      method: 'POST',
+      headers: withNamespace({ 'content-type': 'application/json' }),
+      body: JSON.stringify({ usd: 1 }),
+    });
+    if (r.status !== 402) return out;
+    const ch = await r.json().catch(() => ({}));
+    for (const row of ch.accepts || []) {
+      const usd = Number(row?.extra?.tokenUsd);
+      const sym = String(row?.extra?.symbol || '');
+      if (!sym || !Number.isFinite(usd)) continue;
+      // wTOKENx -> TOKEN, wUSDGx -> USDG, yUSDCx -> USDC
+      const plain = sym.replace(/^[wy]/, '').replace(/x$/, '').toUpperCase();
+      out[sym.toUpperCase()] = usd;
+      if (!(plain in out)) out[plain] = usd;
+    }
+  } catch { /* offline: fall back to printing what we know */ }
+  return out;
+}
+
 export async function printBalance() {
   const { keypair, evmPrivateKey } = loadOrCreateWallet();
+  const px = await quotedPrices();
+  const priceOf = (sym) => px[String(sym).toUpperCase()];
+  const show = (sym, ui) => {
+    const p = priceOf(sym);
+    if (p == null) return ' ($?)';
+    const v = ui * p;
+    // Sub-cent holdings read as "$0.00", which is indistinguishable from
+    // worthless; show enough digits that a real balance is visible.
+    return ` ($${v >= 0.01 || v === 0 ? v.toFixed(2) : v.toFixed(6)})`;
+  };
   const evmAddress = privateKeyToAccount(evmPrivateKey).address;
   const connection = new Connection(config.rpcUrl, 'confirmed');
 
@@ -34,14 +79,17 @@ export async function printBalance() {
     Promise.all(FUNDING_ASSETS.map((a) => tokenBalance(connection, keypair.publicKey, a.mint))),
     connection.getBalance(keypair.publicKey),
   ]);
-  const usdcUi = balances[0].ui ?? 0;
-  let knownUsd = usdcUi;
+  // Seeded at zero: every asset is priced from the quote below, so seeding
+  // with USDC would count it twice.
+  let knownUsd = 0;
   let anyFunds = balances.some((b) => b.raw);
 
   console.log(`Solana — ${keypair.publicKey.toBase58()}`);
   FUNDING_ASSETS.forEach((a, i) => {
-    const usd = a.symbol === 'USDC' ? ` ($${(balances[i].ui ?? 0).toFixed(2)})` : ' ($?, valued at the 402)';
-    console.log(`  ${a.symbol.padEnd(11)}: ${balances[i].ui ?? 0}${usd}`);
+    const ui = balances[i].ui ?? 0;
+    const p = priceOf(a.symbol);
+    if (p != null) knownUsd += ui * p;
+    console.log(`  ${a.symbol.padEnd(11)}: ${ui}${show(a.symbol, ui)}`);
   });
   console.log(`  ${'SOL'.padEnd(11)}: ${lamports / 1e9} (gas — optional, payments are sponsored)`);
 
@@ -57,9 +105,9 @@ export async function printBalance() {
       assets.forEach((a, i) => {
         const ui = fmtUi(raws[i], a.decimals);
         if (raws[i] > 0n) anyFunds = true;
-        if (a.usd != null) knownUsd += ui * a.usd;
-        const usd = a.usd != null ? ` ($${(ui * a.usd).toFixed(2)})` : ' ($?)';
-        console.log(`  ${a.symbol.padEnd(11)}: ${ui}${usd}`);
+        const p = priceOf(a.symbol) ?? a.usd;
+        if (p != null) knownUsd += ui * p;
+        console.log(`  ${a.symbol.padEnd(11)}: ${ui}${p != null ? show(a.symbol, ui) : ' ($?)'}`);
       });
       console.log(`  ${'ETH'.padEnd(11)}: ${fmtUi(native, 18)} (gas — optional, payments are sponsored)`);
     } catch {
@@ -67,7 +115,7 @@ export async function printBalance() {
     }
   }
 
-  console.log(`value : ≈ $${knownUsd.toFixed(2)} known (stable legs; TOKEN and the RH memecoins are priced at the 402, shown as $?)`);
+  console.log(`value : ≈ $${knownUsd.toFixed(2)}${Object.keys(px).length ? ' (every asset priced at the 402)' : ' known (402 unreachable — unpriced assets shown as $?)'}`);
   if (!anyFunds) {
     console.log(`fund  : ${fundingLine(keypair.publicKey.toBase58())}`);
     console.log(`        or USDC on Base to ${evmAddress}`);
@@ -110,10 +158,20 @@ export async function affordableUsd() {
     const perUsd = BigInt(row.maxAmountRequired || '0');
     if (perUsd <= 0n) continue;
     try {
-      const bal = await client.balanceForAccept?.(row);
-      const raw = typeof bal === 'bigint' ? bal : BigInt(bal?.raw ?? 0);
-      const usd = Number(raw * 1000n / perUsd) / 1000;
-      if (usd > best) best = usd;
+      // SPENDABLE, not merely wrapped. Every quote names the WRAPPER, and the
+      // plain token is converted at payment time (topUpQuotedAsset /
+      // acquireWrappedIfNeeded) — so counting only pre-wrapped balance told a
+      // user holding 14,847 TOKEN that their wallet "covers only $1.0230" and
+      // sent them off to fund an account that was already funded.
+      let usd;
+      if (client.spendableUsdForAccept) {
+        usd = await client.spendableUsdForAccept(row);
+      } else {
+        const bal = await client.balanceForAccept?.(row);
+        const raw = typeof bal === 'bigint' ? bal : BigInt(bal?.raw ?? 0);
+        usd = Number(raw * 1000n / perUsd) / 1000;
+      }
+      if (Number.isFinite(usd) && usd > best) best = usd;
     } catch { /* a rail we cannot read is simply not a candidate */ }
   }
   return best;

package/lib/launch.js

@@ -49,21 +49,54 @@ function resolveClaudeCli() {
  * Both get ANTHROPIC_BASE_URL so inference pays x402.
  */
 export async function launchClaude(argv) {
-  const base = `http://localhost:${config.port}/v1`;
+  // let, not const: startProxy can heal onto a different port and every URL
+  // below must follow the port we actually bound.
+  let base = `http://localhost:${config.port}/v1`;
   // AUTO-START THE PROXY. One command should just work — if nothing is listening,
   // boot the proxy in THIS process (it stays alive because claude runs in the
   // foreground below), rather than making the user run `npx openzoo` first.
   let up = false;
   try { up = (await fetch(`${base}/models`, { signal: AbortSignal.timeout(3000) })).ok; } catch { up = false; }
   if (!up) {
-    console.error('openzoo: starting the proxy in the background...');
-    const { startProxy } = await import('./proxy.js');
-    await startProxy({ silent: true, autoTunnel: true });
+    // NEVER GO SILENT DURING STARTUP. silent:true routes the proxy's own lines
+    // to ~/.openzoo/proxy.log so payment receipts cannot corrupt Claude Code's
+    // stdio — correct DURING the session, wrong BEFORE it, because it made a
+    // slow step and a dead step look identical. Reported from the wild as
+    // "always gets stuck at 'starting the proxy in the background...'": there
+    // was nothing on screen for up to 46s and then, at worst, one terse line.
+    // A ticking elapsed counter is the difference between "hung" and "working".
+    process.stderr.write('openzoo: starting the proxy...');
+    const t0 = Date.now();
+    const tick = setInterval(() => {
+      process.stderr.write(`\ropenzoo: starting the proxy... ${((Date.now() - t0) / 1000).toFixed(0)}s`);
+    }, 1000);
+    tick.unref?.();
+    const done = (msg) => { clearInterval(tick); process.stderr.write(`\r\x1b[2Kopenzoo: ${msg}\n`); };
+    try {
+      const { startProxy } = await import('./proxy.js');
+      await startProxy({ silent: true, autoTunnel: true });
+    } catch (err) {
+      // An exception here used to surface as an eternal spinner. Say what broke.
+      done(`proxy failed to start: ${err?.message || err}`);
+      console.error('  full log: ~/.openzoo/proxy.log');
+      console.error('  try: OPENZOO_NO_TUNNEL=1 npx openzoo claude   (skips the cloudflared download)');
+      process.exit(1);
+    }
+    // The proxy may have healed onto a different port (8402 busy). config.port
+    // is the one it ACTUALLY bound, so re-derive every URL from it — the old
+    // code kept polling the port it wished for and timed out on a live proxy.
+    base = `http://localhost:${config.port}/v1`;
     for (let i = 0; i < 20 && !up; i++) {
       await new Promise((r) => setTimeout(r, 300));
       try { up = (await fetch(`${base}/models`, { signal: AbortSignal.timeout(2000) })).ok; } catch { /* keep waiting */ }
     }
-    if (!up) { console.error(`openzoo: proxy did not come up on ${base}`); process.exit(1); }
+    if (!up) {
+      done(`proxy did not answer on ${base}`);
+      console.error('  full log: ~/.openzoo/proxy.log');
+      console.error('  try: OPENZOO_NO_TUNNEL=1 npx openzoo claude   (skips the cloudflared download)');
+      process.exit(1);
+    }
+    done(`proxy up on :${config.port} (${((Date.now() - t0) / 1000).toFixed(1)}s)`);
   }
   // TERMINAL (Claude Code CLI) IS THE DEFAULT — it is the guaranteed-x402 path
   // and honours ANTHROPIC_BASE_URL. --desktop explicitly opens the desktop app

package/lib/pay.js

@@ -150,6 +150,66 @@ export class PayClient {
     return BigInt(raw || 0);
   }
 
+  /**
+   * What this wallet can actually PAY with on this rail, in settlement-asset
+   * units — wrapped holdings PLUS the plain token it can convert on the fly.
+   *
+   * balanceForAccept answers a different question: how much of the WRAPPED
+   * asset is sitting there right now. Every quote names the wrapper (wTOKENx,
+   * the RH vault twins), so a wallet holding 845,486 plain TOKEN read as
+   * "$3.14 covered" — only the sliver already wrapped — while `openzoo balance`
+   * showed the full holding priced as `$?`. Two different wrong answers about
+   * the same wallet, and a user was told to fund an account with $177 in it.
+   *
+   * buildPaymentFor already wraps what it needs at payment time (topUpQuotedAsset
+   * on Solana, acquireWrappedIfNeeded on EVM), so the convertible balance IS
+   * spendable and the estimate was simply lying by omission. Advisory only:
+   * anything unreadable degrades to the wrapped figure rather than throwing,
+   * because this feeds a display and a top-up hint, never a settlement.
+   */
+  async spendableUsdForAccept(accept) {
+    const perUsd = BigInt(accept.maxAmountRequired || '0');
+    if (perUsd <= 0n) return 0;
+    const wrappedRaw = await this.balanceForAccept(accept).catch(() => 0n);
+    let usd = Number(wrappedRaw * 1000n / perUsd) / 1000;
+
+    // Price the PLAIN token with the quote's own tokenUsd, NOT with the pool's
+    // supply/reserves ratio. That ratio is share accounting, not a price: the
+    // live wTOKENx pool reads supply/reserves ≈ 5659, so treating it as a
+    // conversion rate valued 845,486 TOKEN at $1,004,132. The 402 already
+    // publishes what a whole token is worth, and the wrapper is a claim on the
+    // same asset — so underlying and wrapped are priced identically, which is
+    // exactly what `openzoo balance` now shows.
+    const px = Number(accept?.extra?.tokenUsd);
+    if (!Number.isFinite(px) || px <= 0) return usd;
+    const rail = railOf(accept);
+    try {
+      if (rail === 'solana') {
+        const pool = await resolvePool(this.connection, accept.asset);
+        if (!pool) return usd;
+        const under = await tokenBalance(this.connection, this.keypair.publicKey,
+          pool.underlying.toBase58());
+        usd += Number(under?.ui || 0) * px;
+        return usd;
+      }
+      // EVM wrappers are ERC-4626; asset() names the plain token behind them.
+      const { createPublicClient, http } = await import('viem');
+      const pc = createPublicClient({ transport: http(evmRpcFor(rail)) });
+      const ABI = [
+        { name: 'asset', type: 'function', stateMutability: 'view', inputs: [], outputs: [{ type: 'address' }] },
+        { name: 'decimals', type: 'function', stateMutability: 'view', inputs: [], outputs: [{ type: 'uint8' }] },
+      ];
+      const under = await pc.readContract({ address: accept.asset, abi: ABI, functionName: 'asset', args: [] });
+      const raw = await evmTokenBalance({ rpcUrl: evmRpcFor(rail), token: under, owner: this.evmAddress });
+      if (!raw || raw <= 0n) return usd;
+      const dec = Number(accept?.extra?.decimals ?? 18);
+      usd += (Number(raw) / 10 ** dec) * px;
+      return usd;
+    } catch {
+      return usd;          // not a wrapper, or a rail we cannot read
+    }
+  }
+
   async buildPaymentFor(accept, onStage) {
     const rail = railOf(accept);
     if (rail === 'solana') {

package/lib/proxy.js

@@ -16,6 +16,7 @@ import { forgetContext } from './contexts.js';
 import { injectBrief } from './brief.js';
 import { withNamespace } from './namespace.js';
 import { anthropicToOpenAI, openAIToAnthropic, writeAnthropicSse } from './anthropic.js';
+import { responsesToChat, chatToResponses, writeResponsesSse } from './responses.js';
 
 const HOP_BY_HOP = new Set([
   'host', 'connection', 'keep-alive', 'transfer-encoding', 'upgrade',
@@ -41,7 +42,7 @@ const HOP_BY_HOP = new Set([
 function normalizePath(url) {
   const [path, query] = (url || '/').split(/(?=\?)/);
   let p = path.replace(/^(?:\/v1)+(?=\/v1\/)/, '');       // /v1/v1/x -> /v1/x
-  if (!/^\/v1(\/|$)/.test(p) && /^\/(hrr|chat|models|completions|embeddings|usage)/.test(p)) p = `/v1${p}`;
+  if (!/^\/v1(\/|$)/.test(p) && /^\/(hrr|chat|models|completions|embeddings|usage|responses)/.test(p)) p = `/v1${p}`;
   return p === path ? url : `${p}${query || ''}`;
 }
 
@@ -547,7 +548,51 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
     // answer back on the way out. See lib/anthropic.js.
     let anthropicMode = false;
     let anthropicModel = null;
+    let responsesMode = false;
+    let responsesModel = null;
+    let responsesCustom = null;   // names of freeform tools needing custom_tool_call on the way back
     const rawPath = (req.url || '').split('?')[0];
+
+    // RESPONSES API. Some harnesses speak only this wire format — OpenAI's
+    // Codex Security CLI pins `wire_api: "responses"` in its provider table, so
+    // a bare 404 here made it fall back to wss://api.openai.com and bypass the
+    // proxy entirely while reporting the failure as an auth error. Translate
+    // in, translate out; everything between stays on the chat path.
+    if (req.method === 'POST' && (rawPath === '/v1/responses' || rawPath === '/responses')) {
+      try {
+        const inbound = JSON.parse(bodyBuf.toString('utf8'));
+        // TEMP CAPTURE: dump the first few Responses requests so the agent's
+        // actual wire usage (store / previous_response_id / tool shapes) can be
+        // read rather than inferred. Guarded by an env var so it is off unless
+        // asked for.
+        if (process.env.OZ_CAPTURE_RESPONSES) {
+          try {
+            const fs = await import('node:fs');
+            const dir = process.env.OZ_CAPTURE_RESPONSES;
+            fs.mkdirSync(dir, { recursive: true });
+            const n = fs.readdirSync(dir).length;
+            // Capture the LATER turns too. Turn 1 is already understood; the
+            // unknown is what codex sends back after running a tool, so bias
+            // the capture toward requests that carry a tool result.
+            const hasResult = Array.isArray(inbound.input)
+              && inbound.input.some((i) => i && String(i.type || '').endsWith('_call_output'));
+            const tag = hasResult ? 'result' : 'plain';
+            if (n < 24) fs.writeFileSync(`${dir}/${tag}-${n}.json`, JSON.stringify(inbound, null, 2));
+          } catch { /* capture must never break a paid call */ }
+        }
+        responsesModel = inbound.model;
+        const meta = {};
+        bodyBuf = Buffer.from(JSON.stringify(responsesToChat(inbound, meta)));
+        responsesCustom = meta.custom;
+        responsesMode = true;
+        req.url = '/v1/chat/completions';
+        url = `${config.apiBase}${req.url}`;
+      } catch {
+        jsonErr(res, 400, 'invalid responses body');
+        return;
+      }
+    }
+
     if (req.method === 'POST' && (rawPath === '/v1/messages' || rawPath === '/messages')) {
       try {
         const inbound = JSON.parse(bodyBuf.toString('utf8'));
@@ -604,6 +649,18 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
       const hit = replayGet(rKey);
       if (hit) {
         log('identical request within 30s — served the cached completion, NOT re-paid');
+        // The cache stores the CHAT shape. A Responses caller must get its own
+        // wire format back, or the replay path silently answers in a format the
+        // client cannot parse — a bug that only appears on the SECOND identical
+        // request, which is exactly when nobody is watching.
+        if (responsesMode) {
+          if (wantsStream) { writeResponsesSse(res, hit.data, responsesModel, null, responsesCustom); return; }
+          const rh = { 'content-type': 'application/json' };
+          if (hit.settle) rh['x-payment-response'] = hit.settle;
+          res.writeHead(200, rh);
+          res.end(JSON.stringify(chatToResponses(hit.data, responsesModel, responsesCustom)));
+          return;
+        }
         if (wantsStream) { serveAsSse(res, hit.data, null); return; }
         const h = { 'content-type': 'application/json' };
         if (hit.settle) h['x-payment-response'] = hit.settle;
@@ -752,6 +809,20 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
             res.end(JSON.stringify(msg));
             return;
           }
+          if (responsesMode) {
+            // A Responses client that asked to stream is WAITING for
+            // `response.completed`; handing it a JSON body closes the socket
+            // mid-stream and it reports "stream disconnected before
+            // completion". Honour the streaming contract when it asked for it.
+            if (wantsStream) { writeResponsesSse(res, data, responsesModel, response, responsesCustom); return; }
+            const out = chatToResponses(data, responsesModel, responsesCustom);
+            const h = { 'content-type': 'application/json' };
+            const settleHdr = response.headers.get('x-payment-response');
+            if (settleHdr) h['x-payment-response'] = settleHdr;
+            res.writeHead(200, h);
+            res.end(JSON.stringify(out));
+            return;
+          }
           if (wantsStream) { serveAsSse(res, data, response); return; }
           const h = { 'content-type': 'application/json' };
           const settleHdr = response.headers.get('x-payment-response');
@@ -790,10 +861,40 @@ export async function startProxy({ silent = false, requireToken = null, sessionM
   // AND a tunnel token, so the RunPod-fronted port stays gated exactly like the
   // public tunnel path.
   const bindHost = process.env.OPENZOO_BIND || '127.0.0.1';
-  await new Promise((resolve, reject) => {
-    server.on('error', reject);
-    server.listen(config.port, bindHost, resolve);
-  });
+  // SELF-HEAL A TAKEN PORT. A killed-but-not-reaped run, a second terminal, or
+  // anything else already on 8402 made listen() reject and took the whole start
+  // down — and because `openzoo claude` starts us with silent:true, the user saw
+  // only "starting the proxy in the background..." and no reason. Walk up to the
+  // next free port instead of dying; the caller reads config.port back out, so
+  // every URL printed afterwards is the one we actually bound.
+  //
+  // EXCEPTION: if the thing already on the port is a HEALTHY openzoo proxy,
+  // reuse it rather than starting a rival that splits spend across two wallets.
+  const wanted = config.port;
+  for (let attempt = 0; ; attempt++) {
+    try {
+      await new Promise((resolve, reject) => {
+        const onErr = (e) => { server.removeListener('error', onErr); reject(e); };
+        server.on('error', onErr);
+        server.listen(config.port, bindHost, () => { server.removeListener('error', onErr); resolve(); });
+      });
+      break;
+    } catch (e) {
+      if (e?.code !== 'EADDRINUSE' || attempt >= 12) throw e;
+      if (attempt === 0) {
+        try {
+          const probe = await fetch(`http://127.0.0.1:${config.port}/v1/models`, { signal: AbortSignal.timeout(2500) });
+          if (probe.ok) {
+            say(`openzoo: a healthy proxy is already on :${config.port} — reusing it`);
+            return { server: null, client, reused: true, port: config.port, spent: () => 0, publicUrl: null, tunnelToken: null, tunnelError: null };
+          }
+        } catch { /* not ours, or wedged — take the next port */ }
+      }
+      config.port += 1;
+      say(`openzoo: :${config.port - 1} busy — trying :${config.port}`);
+    }
+  }
+  if (config.port !== wanted) say(`openzoo: listening on :${config.port} (:${wanted} was busy)`);
 
   // AUTO-PREPAY. Paying on-chain per call is where the latency lives: the
   // gateway answers its 402 challenge in ~0.12s while a full settled call