@amenophis1er/foreman 0.1.0

package/src/fork.test.ts

@@ -0,0 +1,31 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { forkLabel, forkSeed } from './planner.js';
+
+test('forkSeed: the transcript line names the run, the prompt carries brief, doc and report', () => {
+  const seed = forkSeed({
+    title: 'IRONOATH Strength House', mission: 'Build a single-page site…', status: 'done',
+    endedAt: Date.UTC(2026, 8, 5, 15, 14), missionDoc: '# MISSION\n- [x] index.html exists', report: 'Mission complete. Built the site.',
+  });
+  assert.equal(seed.shown, 'Plan the next step after “IRONOATH Strength House”.');
+  assert.match(seed.prompt, /Previous mission — IRONOATH Strength House \(done, /);
+  assert.match(seed.prompt, /Build a single-page site…/);
+  assert.match(seed.prompt, /index\.html exists/);
+  assert.match(seed.prompt, /Mission complete\. Built the site\./);
+  assert.match(seed.prompt, /Do not re-propose or redo/);
+  assert.match(seed.prompt, /ask_user/);
+});
+
+test('forkSeed: no title falls back to the brief\'s first line; missing doc and report leave no empty sections', () => {
+  const seed = forkSeed({ mission: '\n  Add a contact form\nmore detail', status: 'interrupted', missionDoc: null, report: '' });
+  assert.equal(forkLabel({ mission: '\n  Add a contact form\nmore' }), 'Add a contact form');
+  assert.equal(seed.shown, 'Plan the next step after “Add a contact form”.');
+  assert.doesNotMatch(seed.prompt, /mission doc/);
+  assert.doesNotMatch(seed.prompt, /final report/);
+});
+
+test('forkSeed: long inputs are clipped and say so', () => {
+  const seed = forkSeed({ mission: 'm', status: 'done', missionDoc: 'x'.repeat(7000), report: null });
+  assert.match(seed.prompt, /more characters not shown/);
+  assert.ok(seed.prompt.length < 7000);
+});

package/src/gateway/ledger.cjs

@@ -0,0 +1,326 @@
+/**
+ * The gateway's token ledger — a Foreman-owned wrapper around the ported
+ * llm-gateway.
+ *
+ * WHY THIS IS A SEPARATE FILE. `llm-gateway.cjs` is a verbatim copy from a
+ * sibling project, and the Step 2 decision was that it stays one so re-syncing
+ * is a `cp` and its upstream test suite keeps applying. Counting tokens needs
+ * the request (which run is this?) and the response (how many tokens?), which
+ * is exactly the request path that decision refused to edit. So this binds the
+ * socket instead, and hands each request to the ported handler untouched.
+ *
+ * WHY IT EXISTS AT ALL. An OpenAI-compatible endpoint reports usage only on
+ * the *final* chunk of a stream, and the SDK only surfaces it on the `result`
+ * message that ends a turn. A director in one long turn — every tool call,
+ * every file write, one turn — therefore shows `0 tok` for minutes while
+ * really having spent a hundred thousand. The gateway is the only place that
+ * sees the numbers as they flow.
+ *
+ * ATTRIBUTION. Foreman points each agent at `.../run/<key>`, and the Agent SDK
+ * preserves that prefix (measured, not assumed: it sends
+ * `POST /run/<key>/v1/messages?beta=true`). The key carries the resume attempt
+ * as well as the run id, so a resumed run starts a fresh bucket and its
+ * persisted total is never counted twice by a gateway that outlived it.
+ *
+ * REQUEST DUMPS. Set FOREMAN_GATEWAY_DUMP_DIR and every POST to /v1/messages
+ * is written to disk, request and response outcome, before it is served. This
+ * exists because a stall was only ever reproducible with the real worker
+ * payload — the SDK's full system prompt plus its whole tool set — and no
+ * hand-built request came close. The only honest way to replay it is to have
+ * kept it. Off by default: the files hold prompts and repository contents.
+ */
+const http = require('node:http');
+const fs = require('node:fs');
+const path = require('node:path');
+const { Readable } = require('node:stream');
+const gateway = require('./llm-gateway.cjs');
+
+const PORT = Number(process.env.LLM_GATEWAY_PORT || 0);
+const MODE = process.env.LLM_GATEWAY_MODE || 'openai';
+const DUMP_DIR = process.env.FOREMAN_GATEWAY_DUMP_DIR || '';
+
+/** key -> running totals. In memory: a restarted gateway has counted nothing. */
+const ledger = new Map();
+
+const empty = () => ({
+  inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, calls: 0,
+});
+
+const n = (v) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : 0);
+
+/**
+ * Fold one response's usage into a key's total.
+ *
+ * `costUsd` is only ever recorded when the upstream states it (OpenRouter
+ * does, per response). Foreman never derives one here — a gateway inventing a
+ * dollar figure is the precise failure the cost basis exists to prevent.
+ */
+function record(key, usage, costUsd) {
+  if (!key || !usage) return;
+  const t = ledger.get(key) ?? empty();
+  t.inputTokens += n(usage.input_tokens ?? usage.prompt_tokens);
+  t.outputTokens += n(usage.output_tokens ?? usage.completion_tokens);
+  t.cacheReadTokens += n(usage.cache_read_input_tokens);
+  t.cacheWriteTokens += n(usage.cache_creation_input_tokens);
+  t.calls += 1;
+  if (typeof costUsd === 'number' && Number.isFinite(costUsd) && costUsd >= 0) {
+    t.costUsd = (t.costUsd ?? 0) + costUsd;
+  }
+  ledger.set(key, t);
+}
+
+/**
+ * Pull usage out of whatever the handler wrote back.
+ *
+ * Two shapes reach here and both are handled by looking for the same field
+ * rather than by knowing which mode produced it: a single JSON body carrying
+ * `usage`, or an SSE stream whose `message_delta` frame carries it at the end.
+ * Anything unparseable is skipped in silence — a ledger is an observation, and
+ * must never be able to fail a request it is only watching.
+ */
+function extractUsage(body) {
+  if (!body.includes('"usage"')) return null;
+  let found = null;
+  let cost;
+  const consider = (obj) => {
+    if (!obj || typeof obj !== 'object') return;
+    if (obj.usage && typeof obj.usage === 'object') {
+      // The last usage object wins: a stream's closing `message_delta` is
+      // more complete than anything before it.
+      found = obj.usage;
+      if (typeof obj.usage.cost === 'number') cost = obj.usage.cost;
+    }
+  };
+  if (body.startsWith('data:') || body.includes('\ndata:')) {
+    for (const line of body.split('\n')) {
+      const t = line.trim();
+      if (!t.startsWith('data:')) continue;
+      const payload = t.slice(5).trim();
+      if (!payload || payload === '[DONE]') continue;
+      try { consider(JSON.parse(payload)); } catch { /* partial frame */ }
+    }
+  } else {
+    try { consider(JSON.parse(body)); } catch { /* not json */ }
+  }
+  return found ? { usage: found, costUsd: cost } : null;
+}
+
+/**
+ * Watch a response without changing it.
+ *
+ * Chunks are buffered only while they could still contain a usage object, and
+ * the buffer is capped: a ledger must not turn a long streamed answer into
+ * unbounded memory. Every write is passed straight through first, so nothing
+ * here can delay or alter what the agent receives.
+ *
+ * `observe`, when given, is told the outcome once at end — status, timing,
+ * size, whether usage ever appeared. The dumper hangs off this rather than
+ * wrapping `res` a second time: two observers patching write/end would each
+ * see the other's wrapper, and a bug in either would be twice as hard to place.
+ */
+function tee(res, key, observe) {
+  const { write, end } = res;
+  let buf = '';
+  let bytes = 0;
+  let firstByteMs = null;
+  const started = Date.now();
+  const CAP = 256 * 1024;
+  const absorb = (chunk) => {
+    if (!chunk) return;
+    const len = typeof chunk === 'string' ? Buffer.byteLength(chunk) : chunk.length;
+    if (len > 0 && firstByteMs === null) firstByteMs = Date.now() - started;
+    bytes += len;
+    if (buf.length > CAP) return;
+    // Buffer.from, not chunk.toString(): a Uint8Array's own toString() ignores
+    // the encoding and yields "101,118,101,..." — comma-separated byte values
+    // that parse as nothing and would silently record zero tokens forever.
+    buf += typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8');
+  };
+  res.write = function (chunk, ...rest) {
+    absorb(chunk);
+    return write.call(this, chunk, ...rest);
+  };
+  res.end = function (chunk, ...rest) {
+    absorb(chunk);
+    let sawUsage = false;
+    try {
+      const got = extractUsage(buf);
+      sawUsage = !!got;
+      if (got && key) record(key, got.usage, got.costUsd);
+    } catch { /* never fail a response over bookkeeping */ }
+    if (observe) {
+      try {
+        observe({
+          status: res.statusCode, durationMs: Date.now() - started, bytes, sawUsage, firstByteMs,
+        });
+      } catch { /* an observer is not allowed to fail the response either */ }
+    }
+    return end.call(this, chunk, ...rest);
+  };
+}
+
+/** Header copy safe to write to disk: the two places a credential travels. */
+function redactHeaders(headers) {
+  const out = {};
+  for (const [k, v] of Object.entries(headers || {})) {
+    out[k] = /^(x-api-key|authorization)$/i.test(k) ? '[redacted]' : v;
+  }
+  return out;
+}
+
+/**
+ * The few numbers that tell a stalled request apart from a healthy one at a
+ * glance, without opening a multi-megabyte file. `system` is a string or an
+ * array of text blocks depending on the SDK version; both are measured.
+ */
+function summarize(body, bodyBytes) {
+  const s = { model: null, stream: null, systemChars: 0, toolCount: 0, messageCount: 0, bodyBytes };
+  if (!body || typeof body !== 'object') return s;
+  s.model = typeof body.model === 'string' ? body.model : null;
+  s.stream = !!body.stream;
+  if (typeof body.system === 'string') s.systemChars = body.system.length;
+  else if (Array.isArray(body.system)) {
+    for (const b of body.system) if (b && typeof b.text === 'string') s.systemChars += b.text.length;
+  }
+  if (Array.isArray(body.tools)) s.toolCount = body.tools.length;
+  if (Array.isArray(body.messages)) s.messageCount = body.messages.length;
+  return s;
+}
+
+/**
+ * Build the request dumper, or nothing when the directory is unset.
+ *
+ * `begin` writes the request file and returns the function that writes its
+ * response file; both swallow everything. A dump is a diagnostic aid bolted
+ * onto the request path, and the one thing worse than a missing dump is a
+ * worker that failed because its gateway could not write a file.
+ */
+function makeDumper(dir, log = (line) => process.stderr.write(`${line}\n`)) {
+  if (!dir) return null;
+  let seq = 0;
+  let made = false;
+  return {
+    dir,
+    begin(key, req, raw) {
+      try {
+        if (!made) { fs.mkdirSync(dir, { recursive: true }); made = true; }
+        const ts = new Date();
+        // The key is `<runId>.<attempt>`-ish but comes off the wire; keep the
+        // filename to characters every filesystem accepts.
+        const safeKey = String(key ?? 'unkeyed').replace(/[^A-Za-z0-9._-]/g, '_');
+        const name = `${ts.toISOString().replace(/[:.]/g, '-')}-${safeKey}-${++seq}`;
+        const text = Buffer.from(raw).toString('utf8');
+        let body = text;
+        try { body = JSON.parse(text); } catch { /* keep the raw string: a bad body is the finding */ }
+        const summary = summarize(body, raw.length);
+        fs.writeFileSync(path.join(dir, `${name}.json`), JSON.stringify({
+          ts: ts.toISOString(), key, url: req.url, headers: redactHeaders(req.headers), body, summary,
+        }));
+        const label = key ?? 'unkeyed';
+        log(`[dump] ${label} -> ${summary.model} tools=${summary.toolCount} system=${summary.systemChars} stream=${summary.stream}`);
+        return (info) => {
+          try {
+            fs.writeFileSync(path.join(dir, `${name}.response.json`), JSON.stringify(info));
+            log(`[dump] ${label} <- ${info.status} in ${info.durationMs}ms ${info.bytes}B usage=${info.sawUsage}`);
+          } catch { /* see above */ }
+        };
+      } catch {
+        return () => {};
+      }
+    },
+  };
+}
+
+/** Drain a request into memory. */
+function readAll(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on('data', (c) => chunks.push(c));
+    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('error', reject);
+  });
+}
+
+/**
+ * A stand-in request the handler cannot tell from the original.
+ *
+ * The body has been drained to dump it, so the handler gets a stream that
+ * plays it back. Sharing a 'data' listener with the handler instead would
+ * work today only because each handler subscribes before its first `await`
+ * — an ordering inside a verbatim upstream file that a re-sync may not
+ * keep, and whose failure mode is a silently truncated prompt. The handlers
+ * read exactly headers, method, url, on and pipe (measured, not assumed).
+ */
+function replay(req, raw) {
+  const r = new Readable({ read() {} });
+  r.headers = req.headers;
+  r.method = req.method;
+  r.url = req.url;
+  r.push(raw);
+  r.push(null);
+  return r;
+}
+
+function startServer() {
+  const handler = MODE === 'passthrough' ? gateway.handlePassthrough
+    : MODE === 'codex' ? gateway.handleCodex
+    : gateway.handleOpenAI;
+  const dumper = makeDumper(DUMP_DIR);
+  if (dumper) process.stderr.write(`[dump] writing /v1/messages requests to ${dumper.dir}\n`);
+
+  const server = http.createServer((req, res) => {
+    // Foreman's own read side. Never proxied upstream.
+    if (req.method === 'GET' && req.url.startsWith('/_foreman/usage')) {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify(Object.fromEntries(ledger)));
+      return;
+    }
+
+    // Strip the run key so the ported handler sees the path it expects. An
+    // unkeyed request still works and is simply not attributed — a gateway
+    // that refused traffic it could not label would turn a bookkeeping
+    // feature into an outage.
+    const m = /^\/run\/([^/]+)(\/.*)$/.exec(req.url || '');
+    const key = m ? decodeURIComponent(m[1]) : null;
+    if (m) req.url = m[2];
+
+    const wantDump = !!dumper && req.method === 'POST' && (req.url || '').startsWith('/v1/messages');
+    // Assigned once the request file is written; the tee calls it at end.
+    let finishDump = () => {};
+    if (key || wantDump) tee(res, key, wantDump ? (info) => finishDump(info) : undefined);
+
+    const fail = (e) => {
+      if (!res.headersSent) res.writeHead(502, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({
+        type: 'error',
+        error: { type: 'api_error', message: String((e && e.message) || e) },
+      }));
+    };
+    if (wantDump) {
+      // Drain, dump, then serve from the replay. The undumped path below is
+      // untouched: the handler still gets the live socket stream.
+      readAll(req).then((raw) => {
+        finishDump = dumper.begin(key, req, raw);
+        return handler(replay(req, raw), res);
+      }).catch(fail);
+    } else {
+      Promise.resolve(handler(req, res)).catch(fail);
+    }
+  });
+  server.on('error', (e) => {
+    if (e.code === 'EADDRINUSE') process.exit(0);
+    throw e;
+  });
+  server.listen(PORT, '127.0.0.1', () => {
+    const addr = server.address();
+    process.stdout.write(
+      `llm-gateway (${MODE}) listening on 127.0.0.1:${addr.port} -> ${process.env.LLM_GATEWAY_TARGET_URL}\n`,
+    );
+  });
+}
+
+module.exports = {
+  extractUsage, record, ledger, tee, makeDumper, summarize, redactHeaders, replay,
+};
+
+if (require.main === module) startServer();

package/src/gateway/ledger.test.ts

@@ -0,0 +1,255 @@
+/**
+ * The gateway's token ledger.
+ *
+ * What is under test is an observation that must never affect what it
+ * observes: the response an agent receives has to be byte-identical whether
+ * or not anyone is counting, and a request that cannot be attributed must
+ * still be served. The counting itself is second to that.
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import { mkdtempSync, readdirSync, readFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const require_ = createRequire(import.meta.url);
+const ledgerMod = require_('./ledger.cjs') as {
+  extractUsage(body: string): { usage: Record<string, number>; costUsd?: number } | null;
+  record(key: string, usage: unknown, costUsd?: number): void;
+  ledger: Map<string, Record<string, number>>;
+};
+const gateway = require_('./llm-gateway.cjs') as Record<string, unknown>;
+
+test('the ported handlers are exported, which is what lets the socket be wrapped', () => {
+  // A divergence from the verbatim upstream copy. If a re-sync drops it, the
+  // wrapper cannot bind the socket and every gateway run stops being counted
+  // — silently, which is why this is asserted rather than assumed.
+  for (const name of ['handleOpenAI', 'handleCodex', 'handlePassthrough']) {
+    assert.equal(typeof gateway[name], 'function', `${name} must stay exported`);
+  }
+});
+
+test('usage is read from a single JSON response', () => {
+  const got = ledgerMod.extractUsage(JSON.stringify({
+    type: 'message', usage: { input_tokens: 120, output_tokens: 34 },
+  }));
+  assert.equal(got?.usage.input_tokens, 120);
+  assert.equal(got?.usage.output_tokens, 34);
+});
+
+test('usage is read from the closing frame of a stream, not an earlier one', () => {
+  // An OpenAI-compatible endpoint reports usage only at the end, and the
+  // gateway's `message_start` carries zeros. Taking the first match would
+  // record nothing for every streamed response there is.
+  const body = [
+    'data: {"type":"message_start","message":{"usage":{"input_tokens":0,"output_tokens":0}}}',
+    '',
+    'data: {"type":"content_block_delta","delta":{"text":"hi"}}',
+    '',
+    'data: {"type":"message_delta","usage":{"input_tokens":9001,"output_tokens":42}}',
+    '',
+    'data: [DONE]',
+    '',
+  ].join('\n');
+  const got = ledgerMod.extractUsage(body);
+  assert.equal(got?.usage.input_tokens, 9001);
+  assert.equal(got?.usage.output_tokens, 42);
+});
+
+test('a body with no usage, or a torn one, yields nothing rather than throwing', () => {
+  assert.equal(ledgerMod.extractUsage('{"type":"message"}'), null);
+  assert.equal(ledgerMod.extractUsage('not json at all'), null);
+  assert.equal(ledgerMod.extractUsage(''), null);
+  // A stream cut mid-frame: the complete frames before it still count.
+  const torn = 'data: {"type":"message_delta","usage":{"input_tokens":5,"output_tokens":1}}\n\ndata: {"typ';
+  assert.equal(ledgerMod.extractUsage(torn)?.usage.input_tokens, 5);
+});
+
+test('an upstream-reported cost is carried, and never invented', () => {
+  // OpenRouter states `usage.cost` per response. Where it does, that is the
+  // truthful figure; where it does not, the ledger leaves the field absent
+  // rather than deriving one.
+  const withCost = ledgerMod.extractUsage(JSON.stringify({
+    usage: { input_tokens: 1, output_tokens: 1, cost: 0.00042 },
+  }));
+  assert.equal(withCost?.costUsd, 0.00042);
+  const without = ledgerMod.extractUsage(JSON.stringify({
+    usage: { input_tokens: 1, output_tokens: 1 },
+  }));
+  assert.equal(without?.costUsd, undefined);
+});
+
+test('totals accumulate per key, and keys do not bleed into each other', () => {
+  ledgerMod.ledger.clear();
+  ledgerMod.record('run-a.0', { input_tokens: 100, output_tokens: 10 });
+  ledgerMod.record('run-a.0', { input_tokens: 50, output_tokens: 5 });
+  ledgerMod.record('run-b.0', { input_tokens: 7, output_tokens: 1 });
+
+  assert.deepEqual(ledgerMod.ledger.get('run-a.0'), {
+    inputTokens: 150, outputTokens: 15, cacheReadTokens: 0, cacheWriteTokens: 0, calls: 2,
+  });
+  assert.equal(ledgerMod.ledger.get('run-b.0')?.inputTokens, 7);
+});
+
+test('a resumed run gets a fresh bucket, so persisted tokens are never counted twice', () => {
+  // The attempt number is part of the key precisely because a gateway can
+  // outlive the run that started it.
+  ledgerMod.ledger.clear();
+  ledgerMod.record('run-a.0', { input_tokens: 100, output_tokens: 10 });
+  ledgerMod.record('run-a.1', { input_tokens: 30, output_tokens: 3 });
+  assert.equal(ledgerMod.ledger.get('run-a.0')?.inputTokens, 100);
+  assert.equal(ledgerMod.ledger.get('run-a.1')?.inputTokens, 30);
+});
+
+test('OpenAI-shaped usage counts the same as Anthropic-shaped', () => {
+  // Both reach the ledger depending on mode and on where in the translation
+  // the response was observed.
+  ledgerMod.ledger.clear();
+  ledgerMod.record('k', { prompt_tokens: 200, completion_tokens: 20 });
+  assert.equal(ledgerMod.ledger.get('k')?.inputTokens, 200);
+  assert.equal(ledgerMod.ledger.get('k')?.outputTokens, 20);
+});
+
+test('nonsense in a usage object is ignored rather than poisoning a total', () => {
+  ledgerMod.ledger.clear();
+  ledgerMod.record('k', { input_tokens: 'lots', output_tokens: -5, cache_read_input_tokens: NaN });
+  assert.deepEqual(ledgerMod.ledger.get('k'), {
+    inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, calls: 1,
+  });
+});
+
+// ---- request dumps --------------------------------------------------------
+
+const dumps = ledgerMod as unknown as {
+  makeDumper(dir: string, log?: (line: string) => void): null | {
+    dir: string;
+    begin(key: string | null, req: { url?: string; headers?: Record<string, unknown> }, raw: Buffer):
+      (info: Record<string, unknown>) => void;
+  };
+  replay(req: { headers: unknown; method: string; url: string }, raw: Buffer): NodeJS.ReadableStream & {
+    headers: unknown; method: string; url: string;
+  };
+  tee(res: Record<string, unknown>, key: string | null, observe?: (info: Record<string, unknown>) => void): void;
+};
+
+const scratch = () => mkdtempSync(join(tmpdir(), 'foreman-dump-'));
+
+const fakeReq = (headers: Record<string, string>, url = '/v1/messages?beta=true') => (
+  { headers, method: 'POST', url }
+);
+
+test('dumping is a no-op when the directory is unset', () => {
+  // Off by default is the whole point: these files hold prompts and repository
+  // contents, and no one should find them on disk without having asked.
+  assert.equal(dumps.makeDumper(''), null);
+  assert.equal(dumps.makeDumper(undefined as unknown as string), null);
+});
+
+test('a request is written with its secrets redacted and its shape summarised', () => {
+  const dir = join(scratch(), 'nested', 'not-yet-made');
+  const lines: string[] = [];
+  const d = dumps.makeDumper(dir, (l) => lines.push(l))!;
+  const body = {
+    model: 'kimi-k3:cloud', stream: true, max_tokens: 8,
+    system: [{ type: 'text', text: 'abc' }, { type: 'text', text: 'de' }],
+    tools: [{ name: 'Read' }, { name: 'Edit' }, { name: 'Bash' }],
+    messages: [{ role: 'user', content: 'hi' }, { role: 'assistant', content: 'yo' }],
+  };
+  const raw = Buffer.from(JSON.stringify(body));
+  const finish = d.begin('run-a.0', fakeReq({
+    'x-api-key': 'sk-secret', authorization: 'Bearer also-secret', 'content-type': 'application/json',
+  }), raw);
+
+  assert.ok(existsSync(dir), 'the dump dir is created on first use');
+  const files = readdirSync(dir).sort();
+  assert.equal(files.length, 1);
+  assert.match(files[0], /-run-a\.0-1\.json$/);
+  const got = JSON.parse(readFileSync(join(dir, files[0]), 'utf8'));
+  assert.equal(got.key, 'run-a.0');
+  assert.equal(got.url, '/v1/messages?beta=true');
+  assert.equal(got.headers['x-api-key'], '[redacted]');
+  assert.equal(got.headers.authorization, '[redacted]');
+  assert.equal(got.headers['content-type'], 'application/json');
+  assert.deepEqual(got.body, body);
+  assert.deepEqual(got.summary, {
+    model: 'kimi-k3:cloud', stream: true, systemChars: 5, toolCount: 3, messageCount: 2,
+    bodyBytes: raw.length,
+  });
+  assert.deepEqual(lines, ['[dump] run-a.0 -> kimi-k3:cloud tools=3 system=5 stream=true']);
+
+  finish({ status: 200, durationMs: 1234, bytes: 99, sawUsage: true, firstByteMs: 12 });
+  const after = readdirSync(dir).sort();
+  assert.deepEqual(after, [files[0], files[0].replace(/\.json$/, '.response.json')]);
+  assert.deepEqual(JSON.parse(readFileSync(join(dir, after[1]), 'utf8')), {
+    status: 200, durationMs: 1234, bytes: 99, sawUsage: true, firstByteMs: 12,
+  });
+  assert.equal(lines[1], '[dump] run-a.0 <- 200 in 1234ms 99B usage=true');
+});
+
+test('a malformed body is still dumped, as the raw string, and still reaches the handler', async () => {
+  // The bad body may be the very thing being diagnosed, so it is kept
+  // verbatim; and the dump must not be what turns it into a failure.
+  const dir = scratch();
+  const d = dumps.makeDumper(dir, () => {})!;
+  const raw = Buffer.from('{"model": "x", not json');
+  const req = fakeReq({ 'x-api-key': 'k' });
+  d.begin(null, req, raw);
+  const [file] = readdirSync(dir);
+  assert.match(file, /-unkeyed-1\.json$/);
+  const got = JSON.parse(readFileSync(join(dir, file), 'utf8'));
+  assert.equal(got.body, '{"model": "x", not json');
+  assert.equal(got.summary.model, null);
+  assert.equal(got.summary.bodyBytes, raw.length);
+
+  // What the handler would then read: the same bytes, under the same identity.
+  const r = dumps.replay(req, raw);
+  assert.equal(r.method, 'POST');
+  assert.equal(r.url, '/v1/messages?beta=true');
+  assert.equal(r.headers, req.headers);
+  const chunks: Buffer[] = [];
+  for await (const c of r as AsyncIterable<Buffer>) chunks.push(c);
+  assert.equal(Buffer.concat(chunks).toString(), raw.toString());
+});
+
+test('an unwritable dump dir does not fail the request', () => {
+  // A file where a directory should be: mkdir -p cannot succeed.
+  const blocker = join(scratch(), 'file');
+  require_('node:fs').writeFileSync(blocker, '');
+  const d = dumps.makeDumper(join(blocker, 'sub'), () => {})!;
+  const finish = d.begin('k', fakeReq({}), Buffer.from('{}'));
+  assert.equal(typeof finish, 'function');
+  assert.doesNotThrow(() => finish({ status: 200 }));
+});
+
+test('the tee reports the response outcome once, and still passes every byte through', () => {
+  const written: unknown[] = [];
+  const res = {
+    statusCode: 200,
+    write(chunk: unknown) { written.push(chunk); return true; },
+    end(chunk?: unknown) { if (chunk !== undefined) written.push(chunk); return this; },
+  };
+  const seen: Record<string, unknown>[] = [];
+  ledgerMod.ledger.clear();
+  dumps.tee(res as unknown as Record<string, unknown>, 'run-t.0', (info) => seen.push(info));
+  res.write('data: {"type":"message_start"}\n\n');
+  res.write(Buffer.from('data: {"type":"message_delta","usage":{"input_tokens":3,"output_tokens":1}}\n\n'));
+  res.end('data: [DONE]\n');
+
+  assert.equal(seen.length, 1);
+  assert.equal(seen[0].status, 200);
+  assert.equal(seen[0].sawUsage, true);
+  assert.equal(seen[0].bytes, written.reduce<number>((a, c) => a + Buffer.byteLength(c as string), 0));
+  assert.equal(typeof seen[0].durationMs, 'number');
+  assert.equal(typeof seen[0].firstByteMs, 'number');
+  assert.equal(written.length, 3, 'nothing is swallowed or duplicated');
+  assert.equal(ledgerMod.ledger.get('run-t.0')?.inputTokens, 3, 'counting still happens alongside');
+});
+
+test('an observer that throws cannot break the response', () => {
+  let ended = false;
+  const res = { statusCode: 200, write() { return true; }, end() { ended = true; return this; } };
+  dumps.tee(res as unknown as Record<string, unknown>, null, () => { throw new Error('boom'); });
+  assert.doesNotThrow(() => res.end());
+  assert.ok(ended);
+});