@amenophis1er/foreman 0.1.6 → 0.1.8

package/src/guard.ts

@@ -0,0 +1,131 @@
+/**
+ * Who is allowed to talk to Foreman, and from where.
+ *
+ * Foreman has no login: it trusts the network it listens on (loopback, and
+ * the tailnet when there is one). That trust is only worth anything if a
+ * request really comes from there, and two ordinary browser behaviours break
+ * it without any network access at all:
+ *
+ *  - DNS rebinding. A page on `evil.example` can point its own name at
+ *    127.0.0.1 and then fetch `http://evil.example:4177/runs` — same-origin
+ *    as far as the browser is concerned, so no CORS preflight, and the
+ *    response goes back to the attacker. The packets do arrive on loopback;
+ *    what gives it away is the Host header, which still says
+ *    `evil.example:4177`. Refusing every Host that is not a name Foreman
+ *    actually answers to closes it — hence 421 Misdirected Request.
+ *
+ *  - Cross-site writes. Any page the operator happens to visit can POST a
+ *    form or `fetch(..., {mode:'no-cors'})` at `http://localhost:4177/mkdir`.
+ *    The browser labels those: an `Origin` header on the request, or
+ *    `Sec-Fetch-Site: cross-site`. Unsafe methods are refused unless that
+ *    label says the request came from Foreman's own page.
+ *
+ * Non-browser callers — curl, `src/cli.ts`, the Telegram code paths, the
+ * tests — send neither header, and are left alone. This is a guard against
+ * the browser, not an authentication scheme; it does not pretend to keep out
+ * anyone who can already open a socket to the port.
+ */
+import type http from 'node:http';
+import path from 'node:path';
+import { underAnyRoot } from './policy.js';
+
+/** What a Host header may say, given the port and the tailnet. */
+interface GuardOpts {
+  port: number;
+  tailnet: { ip: string; dnsName?: string } | null;
+  /** `FOREMAN_BIND=all`: the operator opened it wide on purpose, so any Host is theirs. */
+  bindAll?: boolean;
+}
+
+export type GuardVerdict = { ok: true } | { ok: false; status: 421 | 403; error: string };
+
+/** Methods that cannot change anything, so a cross-site one is harmless. */
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+
+/**
+ * The `host:port` strings Foreman answers to. The MagicDNS name is kept
+ * separately because `tailscale serve` may front it on 443 (or any other
+ * HTTPS port), so its port is whatever the proxy chose and cannot be checked.
+ */
+function expectedHosts(opts: GuardOpts): { exact: Set<string>; anyPort: Set<string> } {
+  const exact = new Set([
+    `localhost:${opts.port}`,
+    `127.0.0.1:${opts.port}`,
+    `[::1]:${opts.port}`,
+  ]);
+  if (opts.tailnet?.ip) exact.add(`${opts.tailnet.ip}:${opts.port}`);
+  const anyPort = new Set<string>();
+  if (opts.tailnet?.dnsName) anyPort.add(opts.tailnet.dnsName.toLowerCase());
+  return { exact, anyPort };
+}
+
+/** `laptop.ts.net:8443` → `laptop.ts.net`; `[::1]:4177` → `[::1]`. */
+function hostOnly(hostHeader: string): string {
+  if (hostHeader.startsWith('[')) return hostHeader.slice(0, hostHeader.indexOf(']') + 1);
+  const i = hostHeader.lastIndexOf(':');
+  return i > 0 ? hostHeader.slice(0, i) : hostHeader;
+}
+
+function hostRecognised(host: string, opts: GuardOpts): boolean {
+  const h = host.toLowerCase();
+  const { exact, anyPort } = expectedHosts(opts);
+  return exact.has(h) || anyPort.has(hostOnly(h));
+}
+
+/**
+ * Is this request one Foreman should answer? Host first (rebinding), then —
+ * for anything that can change state — the browser's own account of where the
+ * request came from.
+ */
+export function requestAllowed(
+  req: { method?: string; headers: http.IncomingHttpHeaders },
+  opts: GuardOpts,
+): GuardVerdict {
+  const host = typeof req.headers.host === 'string' ? req.headers.host.trim() : '';
+  if (!opts.bindAll) {
+    if (!host || !hostRecognised(host, opts)) return { ok: false, status: 421, error: 'unrecognised Host' };
+  } else if (!host) {
+    return { ok: false, status: 421, error: 'unrecognised Host' };
+  }
+
+  const method = (req.method ?? 'GET').toUpperCase();
+  if (SAFE_METHODS.has(method)) return { ok: true };
+
+  const origin = typeof req.headers.origin === 'string' ? req.headers.origin.trim() : '';
+  if (origin) {
+    return originAllowed(origin, host, opts)
+      ? { ok: true }
+      : { ok: false, status: 403, error: 'cross-site request refused' };
+  }
+  // No Origin: either a non-browser caller (curl, the CLI, the tests), or a
+  // browser that told us where it came from the other way. `same-origin` and
+  // `none` (typed in the address bar) are ours; `cross-site` and `same-site`
+  // are not.
+  const fetchSite = String(req.headers['sec-fetch-site'] ?? '').trim().toLowerCase();
+  if (!fetchSite || fetchSite === 'same-origin' || fetchSite === 'none') return { ok: true };
+  return { ok: false, status: 403, error: 'cross-site request refused' };
+}
+
+/** An Origin is ours when it is http/https at a host we answer to. */
+function originAllowed(origin: string, host: string, opts: GuardOpts): boolean {
+  let u: URL;
+  try { u = new URL(origin); } catch { return false; }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return false;
+  // With bindAll there is no list to check against, so the standard
+  // same-origin rule is the honest one: the Origin must be the Host.
+  if (opts.bindAll) {
+    const authority = u.host.toLowerCase();
+    return authority === host.toLowerCase();
+  }
+  return hostRecognised(u.host.toLowerCase(), opts);
+}
+
+/**
+ * May Foreman look at (or write into) `target`? True when it resolves to one
+ * of `roots` or somewhere beneath one. `path.resolve` collapses `..` first,
+ * so `~/Projects/../../etc` is judged as `/etc` and refused; containment
+ * itself is `underAnyRoot`, which is already the rule the permission cards use.
+ */
+export function pathPermitted(target: string, roots: Iterable<string>): boolean {
+  return underAnyRoot(path.resolve(target), roots);
+}

package/src/http-body.test.ts

@@ -0,0 +1,42 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  ATTACHMENT_BODY_LIMIT, BodyError, DEFAULT_BODY_LIMIT, bodyLimitFor, parseBody,
+} from './http-body.js';
+
+test('bodyLimitFor: only POST /attachments gets the large cap', () => {
+  assert.equal(bodyLimitFor('POST', '/attachments'), ATTACHMENT_BODY_LIMIT);
+  assert.equal(bodyLimitFor('post', '/attachments'), ATTACHMENT_BODY_LIMIT);
+  assert.equal(bodyLimitFor('GET', '/attachments'), DEFAULT_BODY_LIMIT);
+  assert.equal(bodyLimitFor('POST', '/mkdir'), DEFAULT_BODY_LIMIT);
+  assert.equal(bodyLimitFor('POST', '/attachments/extra'), DEFAULT_BODY_LIMIT);
+  assert.equal(bodyLimitFor(undefined, '/runs'), DEFAULT_BODY_LIMIT);
+});
+
+test('parseBody: an empty body is an empty object', () => {
+  assert.deepEqual(parseBody(''), {});
+  assert.deepEqual(parseBody('   '), {});
+  assert.deepEqual(parseBody(Buffer.alloc(0)), {});
+});
+
+test('parseBody: an object comes back as itself', () => {
+  assert.deepEqual(parseBody('{"a":1,"b":"x"}'), { a: 1, b: 'x' });
+  assert.deepEqual(parseBody(Buffer.from('{"nested":{"k":true}}')), { nested: { k: true } });
+});
+
+test('parseBody: JSON that is not an object has no fields to read', () => {
+  assert.deepEqual(parseBody('[1,2,3]'), {});
+  assert.deepEqual(parseBody('42'), {});
+  assert.deepEqual(parseBody('null'), {});
+  assert.deepEqual(parseBody('"hello"'), {});
+});
+
+test('parseBody: junk is the client’s fault, not a 500', () => {
+  assert.throws(() => parseBody('{bad'), (err: unknown) => {
+    assert.ok(err instanceof BodyError);
+    assert.equal(err.status, 400);
+    assert.equal(err.message, 'invalid JSON body');
+    return true;
+  });
+  assert.throws(() => parseBody('{"a":}'), BodyError);
+});

package/src/http-body.ts

@@ -0,0 +1,57 @@
+/**
+ * How much request body Foreman will read, and what a bad one costs.
+ *
+ * Every route reads its JSON into memory. Without a cap, one request with a
+ * long-running body holds the process's whole heap hostage — no authentication
+ * stands between a stray script and that, and the operator's other missions
+ * die with the server. So there is a cap, and exceeding it is a 413 rather
+ * than an OOM.
+ *
+ * The cap is per route rather than global because one route is legitimately
+ * huge: attachments arrive base64-encoded inside the JSON body, and
+ * `src/attachments.ts` already allows ten files of 10 MiB each — roughly
+ * 133 MiB on the wire once base64 has added its third. Every other route
+ * carries a mission brief or a settings object, which 1 MiB covers many times
+ * over.
+ */
+
+/** Enough for any brief, settings blob or model list; small enough to be free. */
+export const DEFAULT_BODY_LIMIT = 1 * 1024 * 1024;
+
+/** Ten 10 MiB files, base64-inflated, plus room for the JSON around them. */
+export const ATTACHMENT_BODY_LIMIT = 128 * 1024 * 1024;
+
+/** A body problem with the answer already decided: 400 for junk, 413 for too much. */
+export class BodyError extends Error {
+  constructor(public status: number, message: string) {
+    super(message);
+    this.name = 'BodyError';
+  }
+}
+
+/** The cap for this route: the large one only where large bodies are the point. */
+export function bodyLimitFor(method: string | undefined, pathname: string): number {
+  const m = (method ?? '').toUpperCase();
+  return m === 'POST' && pathname === '/attachments' ? ATTACHMENT_BODY_LIMIT : DEFAULT_BODY_LIMIT;
+}
+
+/**
+ * The body as an object. An empty body is `{}` (routes read optional fields
+ * off it and validate for themselves), and so is valid JSON that is not one —
+ * an array, a number or a bare string has none of the named fields the
+ * handlers destructure, so it is the empty object as far as they can tell.
+ * Only unparseable input is an error, and it is the client's: 400, not a 500
+ * whose body is the text of a `SyntaxError`.
+ */
+export function parseBody(buf: Buffer | string): Record<string, unknown> {
+  const text = typeof buf === 'string' ? buf : buf.toString();
+  if (!text.trim()) return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new BodyError(400, 'invalid JSON body');
+  }
+  return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+    ? (parsed as Record<string, unknown>) : {};
+}

package/src/memory.test.ts

@@ -0,0 +1,46 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import os from 'node:os';
+import path from 'node:path';
+import { mkdtemp, readFile } from 'node:fs/promises';
+import { MEMORY_CAP_BYTES, memorySection, readMemory, scrubSecrets, writeMemory } from './memory.js';
+
+test('scrubSecrets removes what looks like a credential and keeps the line readable', () => {
+  const r = scrubSecrets([
+    'Run tests with: npm test',
+    'ANTHROPIC_API_KEY=sk-ant-api03-abcdefghijklmnopqrstuvwxyz0123456789',
+    'GitHub token ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ012345 is in the CI',
+    'aws: AKIAIOSFODNN7EXAMPLE',
+    'Bearer: abcdefghijklmnopqrstuvwxyz1234567890',
+    'The port 8420 is taken by the preview server',
+  ].join('\n'));
+  assert.ok(r.redacted >= 4, String(r.redacted));
+  assert.match(r.text, /^Run tests with: npm test$/m);
+  assert.match(r.text, /^ANTHROPIC_API_KEY=\[redacted\]$/m);
+  assert.doesNotMatch(r.text, /ghp_ABCDEF/);
+  assert.doesNotMatch(r.text, /AKIAIOSFODNN7EXAMPLE/);
+  assert.match(r.text, /port 8420 is taken/);
+});
+
+test('writeMemory: full-page replace, secrets stripped, capped at a page or two, then readMemory sees it', async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), 'memory-'));
+  const w = await writeMemory(dir, '# Notes\n- tests: npm test\n- API_TOKEN=abcdefghijklmnop1234\n');
+  assert.equal(w.redacted, 1); assert.equal(w.trimmed, false);
+  const m = await readMemory(dir);
+  assert.match(m.text, /- tests: npm test\n- API_TOKEN=\[redacted\]\n$/);
+  assert.ok(m.updatedAt);
+  const big = await writeMemory(dir, Array.from({ length: 2000 }, (_, i) => `- line ${i} about the project`).join('\n'));
+  assert.equal(big.trimmed, true);
+  assert.ok(big.bytes <= MEMORY_CAP_BYTES);
+  assert.ok((await readFile(path.join(dir, '.foreman', 'MEMORY.md'), 'utf8')).endsWith('\n'));
+});
+
+test('memorySection: the director is told to write an empty memory; workers and the planner get nothing for empty; all get the page otherwise', () => {
+  assert.match(memorySection('', 'director'), /empty\. Before you finish, write it with mcp__foreman__remember/);
+  assert.equal(memorySection('', 'worker'), '');
+  assert.equal(memorySection('', 'planner'), '');
+  const s = memorySection('- port 8420 is taken', 'worker');
+  assert.match(s, /PROJECT MEMORY — what earlier crews learned/);
+  assert.match(s, /---\n- port 8420 is taken\n---/);
+  assert.match(memorySection('x', 'planner'), /Ground your advice in it/);
+});

package/src/memory.ts

@@ -0,0 +1,107 @@
+/**
+ * Project memory: the page of notes a good contractor keeps about a site.
+ *
+ * `.foreman/MEMORY.md` — one file per project, human-readable, a page or two
+ * at most. How to run the tests, which port is taken, where the CSS lives
+ * and why, what the client hates. Read by the director, the workers and the
+ * planner at the start of every turn; written by the director at the end of
+ * a mission through one tool; visible in the rail so the human can see what
+ * their project "believes", and edit it with any text editor.
+ *
+ * Memory makes the crew better informed, never more powerful: it is prose
+ * in a prompt, and everything the crew may do is still exactly what the
+ * tool policy and the budget allow. It also never carries a secret — the
+ * server strips anything that looks like one before writing.
+ */
+import path from 'node:path';
+import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+
+export const MEMORY_FILE = '.foreman/MEMORY.md';
+/** Bytes kept in the file. Past this the director is asked to prune, not append. */
+export const MEMORY_CAP_BYTES = 8 * 1024;
+/** Bytes injected into a prompt; the tail is dropped with a note if the file is larger. */
+const INJECT_CAP_BYTES = 6 * 1024;
+
+export function memoryPath(folder: string): string {
+  return path.join(folder, MEMORY_FILE);
+}
+
+export async function readMemory(folder: string): Promise<{ text: string; updatedAt?: number }> {
+  const file = memoryPath(folder);
+  const text = await readFile(file, 'utf8').catch(() => '');
+  const st = text ? await stat(file).catch(() => null) : null;
+  return { text, updatedAt: st?.mtimeMs };
+}
+
+/**
+ * Things that must not live in a page of notes, whatever the model meant:
+ * API keys, tokens, private keys, and `KEY=value` lines for secret-looking
+ * names. Replaced, not dropped, so the line still reads as a line.
+ */
+const SECRET_PATTERNS: RegExp[] = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+  /\b(sk|rk|pk)-(?:live|test|proj|ant)?-?[A-Za-z0-9_-]{16,}\b/g,
+  /\b(?:ghp|gho|ghu|ghs|ghr|github_pat)_[A-Za-z0-9_]{20,}\b/g,
+  /\bxox[abprs]-[A-Za-z0-9-]{10,}\b/g,
+  /\bAKIA[0-9A-Z]{16}\b/g,
+  /\bAIza[0-9A-Za-z_-]{30,}\b/g,
+  /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g,
+  /\b([A-Z0-9_]*(?:SECRET|TOKEN|PASSWORD|PASSWD|API_KEY|APIKEY|PRIVATE_KEY)[A-Z0-9_]*)\s*[=:]\s*["']?[^\s"']{8,}["']?/gi,
+  /\b(?:bearer|token|password|secret|api[_-]?key)\s*[:=]\s*["']?[A-Za-z0-9_\-./+=]{16,}["']?/gi,
+];
+
+/** Strip what looks like a credential. Returns the text and how many replacements were made. */
+export function scrubSecrets(text: string): { text: string; redacted: number } {
+  let redacted = 0;
+  let out = text;
+  for (const re of SECRET_PATTERNS) {
+    out = out.replace(re, (m, name?: string) => {
+      redacted += 1;
+      // Keep the variable name when there was one, so the line still explains itself.
+      return typeof name === 'string' && /^[A-Z0-9_]+$/.test(name) && m.startsWith(name) ? `${name}=[redacted]` : '[redacted]';
+    });
+  }
+  return { text: out, redacted };
+}
+
+/**
+ * Write the whole memory. The director hands over the full page, not a
+ * delta, because "rewrite the stale line" is the behaviour we want and
+ * append-only files only grow. Trimmed to the cap; the caller is told.
+ */
+export async function writeMemory(folder: string, text: string): Promise<{ bytes: number; redacted: number; trimmed: boolean }> {
+  const scrubbed = scrubSecrets(text.replace(/\r\n/g, '\n').trim());
+  let body = scrubbed.text;
+  let trimmed = false;
+  if (Buffer.byteLength(body, 'utf8') > MEMORY_CAP_BYTES) {
+    body = Buffer.from(body, 'utf8').subarray(0, MEMORY_CAP_BYTES).toString('utf8').replace(/[^\n]*$/, '').trimEnd();
+    trimmed = true;
+  }
+  await mkdir(path.dirname(memoryPath(folder)), { recursive: true });
+  await writeFile(memoryPath(folder), body ? `${body}\n` : '');
+  return { bytes: Buffer.byteLength(body, 'utf8'), redacted: scrubbed.redacted, trimmed };
+}
+
+/**
+ * The memory as a prompt section, for the director, the workers and the
+ * planner. Empty memory says so in one line rather than vanishing, so the
+ * crew knows the file exists to be written.
+ */
+export function memorySection(text: string, role: 'director' | 'worker' | 'planner'): string {
+  const t = text.trim();
+  if (!t) {
+    return role === 'director'
+      ? `\nPROJECT MEMORY (${MEMORY_FILE}): empty. Before you finish, write it with mcp__foreman__remember — a page at most of facts the next crew needs here.\n`
+      : '';
+  }
+  let body = t;
+  if (Buffer.byteLength(body, 'utf8') > INJECT_CAP_BYTES) {
+    body = Buffer.from(body, 'utf8').subarray(0, INJECT_CAP_BYTES).toString('utf8').replace(/[^\n]*$/, '') + '\n[… memory is longer than a page; the rest was not shown. Prune it.]';
+  }
+  const lead = role === 'director'
+    ? `PROJECT MEMORY (${MEMORY_FILE}) — what earlier crews learned about this project. Trust it over guessing; correct it when it is wrong. Before you finish, rewrite it with mcp__foreman__remember so the next crew starts where you end.`
+    : role === 'worker'
+      ? 'PROJECT MEMORY — what earlier crews learned about this project. Trust it over guessing; tell the director if it is wrong.'
+      : `PROJECT MEMORY (${MEMORY_FILE}) — what the crew learned about this project on earlier missions. Ground your advice in it, and say when a proposal would change something it records.`;
+  return `\n${lead}\n---\n${body}\n---\n`;
+}

package/src/notify/commands.ts

@@ -66,7 +66,7 @@ export const HELP_TEXT = [
   '',
   '/projects — the fleet, with what is running',
   '/status — the runs in flight and what they need',
-  '/new <name> — create a project under your projects root and link it',
+  '/new <name> — create a project under your projects root and link it; /new <git url> clones it there first',
   '/plan <project> <what you want> — talk to that project\'s planner',
   '/run <project> <brief> — skip the talk: start a mission at the project\'s default cap',
   '/stop [project] — stop the planner reply in flight',

package/src/notify/telegram.ts

@@ -94,7 +94,7 @@ export function telegramTransport(token: string, chatId: string, apiBase = TELEG
 export const BOT_COMMANDS: Array<{ command: string; description: string }> = [
   { command: 'projects', description: 'The fleet, with what is running' },
   { command: 'status', description: 'Runs in flight, spend, what needs you' },
-  { command: 'new', description: 'Create a project: /new <name>' },
+  { command: 'new', description: 'Create a project: /new <name>, or clone one: /new <git url>' },
   { command: 'plan', description: 'Talk to a planner: /plan <project> <what you want>' },
   { command: 'run', description: 'Skip the talk: /run <project> <brief>' },
   { command: 'stop', description: 'Stop the planner reply in flight' },

package/src/notify.ts

@@ -241,6 +241,11 @@ export function shape(env: Envelope, ctx: NotifyContext): Shaped | null {
     case 'mission_incomplete':
       return { key: `incomplete:${env.runId}`, gate: 'done',
         text: `${head('Not done')}${runLine}\n${esc(clip(d.text))}${foot}` };
+    case 'pull_request': {
+      if (d.error || !d.url) return null;
+      return { key: `pr:${env.runId}`, gate: 'done',
+        text: `${head(d.method === 'gh' ? 'Pull request opened' : 'Branch pushed')}${runLine}\n<a href="${esc(String(d.url))}">${esc(String(d.url))}</a>` };
+    }
     case 'service_exposed': {
       // Informational, and worth a tap: the crew put something on the air.
       const url = String(d.url ?? '');

package/src/orchestrator.test.ts

@@ -9,6 +9,7 @@ import {
   stalledWorkerReport, workerStatusBlock,
   watchRepeats, watchSilence, REPEAT_EXEMPT, observeToolUse,
   DEFAULT_ASK_TIMEOUT_MS, armAskTimeout, unattendedAnswer, unattendedDenyMessage,
+  tokenCapLabel,
 } from './orchestrator.js';
 import { makePolicy, type PendingPermission } from './policy.js';
 import type { AgentEnv } from './provider.js';
@@ -1145,3 +1146,106 @@ test('pendingAsks exposes an open question with its text and options, and forget
   await p;
   assert.deepEqual(run.pendingAsks(), []);
 });
+
+// ---------------------------------------------------------------------------
+// The token cap: the bound that holds where dollars cannot
+// ---------------------------------------------------------------------------
+
+/**
+ * A run whose usage is whatever the test says it is. Usage is read through
+ * liveUsage(), so setting `meta.usage` is enough — the confirmed half of the
+ * figure the cap actually consults.
+ */
+function cappedRun(over: Partial<RunMeta> = {}, usage?: Partial<{
+  inputTokens: number; outputTokens: number; cacheReadTokens: number; cacheWriteTokens: number;
+}>) {
+  const run = new MissionRun(
+    meta({ costBasis: 'free', ...over }), () => {}, () => {}, noopAgentEnv,
+  ) as unknown as {
+    meta: RunMeta; turns: number;
+    capReached(): string | null;
+    budgetLine(): string;
+  };
+  if (usage) {
+    run.meta.usage = {
+      inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, ...usage,
+    };
+  }
+  return run;
+}
+
+test('capReached says nothing while the token total is under the cap', () => {
+  const run = cappedRun({}, {
+    inputTokens: 1_000_000, outputTokens: 100_000,
+    cacheReadTokens: 1_000_000, cacheWriteTokens: 500_000,
+  });
+  assert.equal(run.capReached(), null);
+});
+
+test('capReached counts cache tokens too, and fires at the default 20M', () => {
+  // Under on input and output alone; over once cache is counted — which is
+  // exactly the run the cap exists for, since cache reads are most of the
+  // traffic on a long director loop.
+  const run = cappedRun({}, {
+    inputTokens: 2_000_000, outputTokens: 400_000,
+    cacheReadTokens: 16_000_000, cacheWriteTokens: 1_600_000,
+  });
+  const cap = run.capReached();
+  assert.ok(cap?.startsWith('TOKEN CAP REACHED'), `got ${cap}`);
+  assert.match(cap!, /20\.0M tokens/);
+});
+
+test('capReached: the ledger\'s largest finished missions stay under the default', () => {
+  // 15.9M tokens, done, $8.55 — a real Fable run from this machine. A cap
+  // that would have ended it is a cap set wrong.
+  const run = cappedRun({}, { inputTokens: 300_000, outputTokens: 200_000, cacheReadTokens: 15_000_000, cacheWriteTokens: 400_000 });
+  assert.equal(run.capReached(), null);
+});
+
+test('capReached honours an explicit maxTokens over the default', () => {
+  const run = cappedRun({ maxTokens: 1_000_000 }, { inputTokens: 1_200_000 });
+  assert.ok(run.capReached()?.startsWith('TOKEN CAP REACHED'));
+  const roomy = cappedRun({ maxTokens: 40_000_000 }, { inputTokens: 25_000_000 });
+  assert.equal(roomy.capReached(), null);
+});
+
+test('the turn cap still wins when turns and tokens are both past their caps', () => {
+  const run = cappedRun({ maxTurns: 10, maxTokens: 1_000 }, { inputTokens: 9_000_000 });
+  run.turns = 50;
+  assert.match(run.capReached()!, /^TURN CAP REACHED/);
+});
+
+test('the token cap binds free and unpriced runs, and never a priced one', () => {
+  for (const basis of ['free', 'unpriced'] as const) {
+    const run = cappedRun({ costBasis: basis }, { inputTokens: 25_000_000 });
+    assert.ok(run.capReached()?.startsWith('TOKEN CAP REACHED'), `basis ${basis}`);
+  }
+  // Priced: dollars are the cap. Under budget, tokens alone end nothing;
+  // over budget, it is the budget that speaks.
+  const priced = cappedRun({ costBasis: 'priced', budgetUsd: 5 }, { inputTokens: 25_000_000 });
+  priced.meta.costUsd = 1;
+  assert.equal(priced.capReached(), null);
+  priced.meta.costUsd = 5;
+  assert.match(priced.capReached()!, /^BUDGET CAP REACHED/);
+});
+
+test('budgetLine tells an unmetered director its turn AND token bounds', () => {
+  const free = cappedRun({ costBasis: 'free' }).budgetLine();
+  assert.match(free, /150 director turns and 20M tokens/);
+  const unpriced = cappedRun({ costBasis: 'unpriced' }).budgetLine();
+  assert.match(unpriced, /150 director turns and 20M tokens/);
+  // A custom cap is quoted as set, not as the default.
+  assert.match(cappedRun({ maxTokens: 2_000_000 }).budgetLine(), /2M tokens/);
+  // A priced run still speaks in dollars, and says nothing about tokens.
+  const priced = cappedRun({ costBasis: 'priced' }).budgetLine();
+  assert.match(priced, /^Budget: \$5\.00/);
+  assert.doesNotMatch(priced, /tokens/);
+});
+
+test('tokenCapLabel rounds to a figure a director can hold in mind', () => {
+  assert.equal(tokenCapLabel(20_000_000), '20M tokens');
+  assert.equal(tokenCapLabel(5_000_000), '5M tokens');
+  assert.equal(tokenCapLabel(1_500_000), '1.5M tokens');
+  assert.equal(tokenCapLabel(250_000), '250k tokens');
+  assert.equal(tokenCapLabel(400), '400 tokens');
+});