@wjarka/cezarion 0.16.0 → 0.17.0

package/scripts/benchmark-run-store-fixture.ts

@@ -24,6 +24,7 @@
  * `running` run. It draws from its own seeded stream, so the finished records keep the bytes and
  * ids the first benchmark table measured; `serve` opens with `keepLive`, which leaves them live.
  */
+import type { CiWait } from '@open-mercato/cezar-contract';
 import type { RunRecord } from '../src/runs/store.ts';
 
 export const FIXTURE_PROFILES = ['legacy', 'post-778'] as const;
@@ -136,7 +137,7 @@ const iso = (ms: number) => new Date(ms).toISOString();
 const REPO = 'https://github.com/example-org/example-repo';
 const MINUTE = 60_000;
 
-interface Draft { record: RunRecord; skillPrompt?: string; extraPrompt?: string }
+interface Draft { record: RunRecord; skillPrompt?: string; extraPrompt?: string | undefined }
 
 /**
  * `runs` finished records plus `liveRunCount(runs)` live ones, newest first (the order `RunStore`
@@ -367,7 +368,9 @@ function rootRun(rng: Rng, id: string, workerIds: readonly string[], at: number)
     }
   }
   record.delegation = delegation;
-  if (rng.chance(0.1)) record.lastCiWait = ciWait(rng, at);
+  // A schema-3 field, kept so the finished records stay the bytes the first table measured:
+  // store schema 4 reads it into `lastWaits` (`upgradeLegacyWaits`).
+  if (rng.chance(0.1)) (record as RunRecord & { lastCiWait?: ReturnType<typeof ciWait> }).lastCiWait = ciWait(rng, at);
   return record;
 }
 
@@ -408,7 +411,8 @@ function agentInputs(rng: Rng, parentRunId: string, sender: string, recipient: s
   return inputs;
 }
 
-function ciWait(rng: Rng, at: number): NonNullable<RunRecord['lastCiWait']> {
+// A schema-3 `ciWait` row predates the PR wait target (hearsay-tools/cezarion#1425).
+function ciWait(rng: Rng, at: number): Omit<CiWait, 'until' | 'wakeOnConflict'> {
   const pr = rng.int(1, 999);
   const headSha = rng.hex(40);
   const id = rng.uuid();

package/scripts/check-pack.mjs

@@ -20,7 +20,9 @@ const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'
 
 // Under `npm run`, npm_execpath is npm's own cli.js — running it through
 // process.execPath works on every platform (no .cmd shim needed on Windows).
-const npmExecpath = process.env.npm_execpath;
+// pnpm 12 sets npm_execpath to a native executable; these operations need npm.
+const npmExecpath = /(?:^|[\\/])npm-cli\.js$/.test(process.env.npm_execpath ?? '')
+  ? process.env.npm_execpath : undefined;
 const packArgs = ['pack', '--dry-run', '--json'];
 const npmCli = process.platform === 'win32' ? 'npm.cmd' : 'npm';
 const stdout = npmExecpath

package/scripts/inline-contract.mjs

@@ -1,42 +1,28 @@
 /**
- * Bundle `@open-mercato/cezar-contract` into `dist` after `tsc`.
+ * Bundle private runtime contract code and declarations into the published service dist, then
+ * rewrite emitted root and subpath references. Keep source imports unchanged. Remove this step
+ * when private runtime resolution is no longer needed.
  *
- * The contract and the api-client are PRIVATE and ship no build of their own — they are linked as
- * workspace packages and consumed as TypeScript source, which is what every other consumer wants:
- * the cockpit's Vite bundles them, vitest transforms them.
- *
- * This package is the exception, because it is PUBLISHED. `workspace/migrations.ts` imports
- * `workspaceUiStateSchema` — a zod value, not a type — so the installed CLI resolves the contract
- * at runtime, and a tarball naming a package npm has never seen would fail on install. So the
- * build folds it in: esbuild compiles the contract's source to one ESM file under `dist/contract/`,
- * `tsc` emits its declarations beside it, and the emitted references are repointed at both.
- *
- * Nothing is copied at the SOURCE level — the package graph still states the dependency, and this
- * runs only when `dist` actually names it. Delete this the day the contract is published, or the
- * day nothing here imports a contract VALUE.
- *
- * DECLARATIONS ship next to the bundle, and that is not optional. The scan below matches `.d.ts`
- * as well as `.js`, so emitted type imports get repointed too (`dist/ui-state.d.ts` names
- * `WorkspaceUiState`). esbuild emits JavaScript only, so a bundle on its own leaves those
- * declarations naming a module TypeScript cannot resolve — `TS7016`, and the type silently
- * degrades to `any` for anyone consuming the published package. Every tsconfig here sets
- * `skipLibCheck`, so nothing in this repo would have said a word. `tsc --emitDeclarationOnly`
- * mirrors the contract's `src` tree into `dist/contract/`, which is what makes
- * `./contract/index.js` resolve to a real `./contract/index.d.ts`.
+ * Every subpath repoints to one bundle of `packages/contract/src/index.ts`, so it exports only
+ * the names that index re-exports. A module the index reaches through a named re-export (`ask.ts`
+ * names a few of `ask-schema.ts`'s) keeps only those names in the bundle. The build fails when an
+ * emitted import names a contract value the bundle lacks (hearsay-tools/cezarion#1431).
  */
 import { execFileSync } from 'node:child_process';
 import { createRequire } from 'node:module';
 import { existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { dirname, join, relative } from 'node:path';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { build } from 'esbuild';
 
 const here = dirname(fileURLToPath(import.meta.url));
-const dist = join(here, '..', 'dist');
+const dist = process.argv[2] ? resolve(process.argv[2]) : join(here, '..', 'dist');
 const contractRoot = join(here, '..', '..', 'contract');
 const entry = join(contractRoot, 'src', 'index.ts');
 const outdir = join(dist, 'contract');
-const SPEC = /(['"])@open-mercato\/cezar-contract\1/g;
+// The bare name and every module subpath (`@open-mercato/cezar-contract/runs`, hearsay-tools/cezarion#1237).
+const SPEC = /(['"])@open-mercato\/cezar-contract(?:\/[^'"]*)?\1/g;
+const CONTRACT = /^@open-mercato\/cezar-contract(?:\/[^'"]*)?$/;
 
 /** Emitted files that name the package — the copy happens only if it is really used. */
 const referrers = [];
@@ -61,7 +47,8 @@ if (referrers.length === 0) {
 
 // `zod` stays external: it is a real dependency of this package, so npm resolves it normally and
 // the tarball does not carry a second copy.
-await build({
+const bundled = await build({
+  metafile: true,
   entryPoints: [entry],
   outfile: join(outdir, 'index.js'),
   bundle: true,
@@ -71,6 +58,72 @@ await build({
   external: ['zod'],
 });
 
+// A wildcard re-export has no named import for the linker below to validate. Check its
+// runtime export set before rewriting it: otherwise a missing module silently becomes the
+// root bundle's unrelated exports (hearsay-tools/cezarion#1813).
+const rootExports = new Set(Object.values(bundled.metafile.outputs).flatMap((output) => output.exports));
+for (const file of referrers.filter((name) => name.endsWith('.js'))) {
+  for (const match of readFileSync(file, 'utf8').matchAll(/export\s+\*\s+from\s+['"](@open-mercato\/cezar-contract\/([^'"]+))['"]/g)) {
+    const source = join(contractRoot, 'src', `${match[2]}.ts`);
+    const original = await build({
+      entryPoints: [source], bundle: true, write: false, metafile: true,
+      format: 'esm', platform: 'neutral', external: ['zod'],
+    });
+    const missing = Object.values(original.metafile.outputs).flatMap((output) => output.exports)
+      .filter((name) => !rootExports.has(name));
+    if (missing.length) {
+      console.error(`inline-contract: ${relative(dist, file)} wildcard re-export of "${match[1]}" loses root exports: ${missing.join(', ')}`);
+      process.exit(1);
+    }
+  }
+}
+
+// Link every emitted importer against the bundle, as Node does when the CLI starts, before
+// anything is repointed. Each specifier loads as a module of its own that re-exports the bundle,
+// so esbuild's message names the subpath. Every other import stays external: only contract
+// names are checked. `import-is-undefined` covers a namespace member the bundle lacks.
+const bundle = join(outdir, 'index.js');
+const importers = referrers.filter((p) => p.endsWith('.js'));
+const gaps = importers.length === 0 ? [] : await build({
+  entryPoints: importers,
+  absWorkingDir: dist,
+  outdir: join(dist, '.inline-contract-check'),
+  write: false,
+  bundle: true,
+  format: 'esm',
+  platform: 'neutral',
+  logLevel: 'silent',
+  logOverride: { 'import-is-undefined': 'error' },
+  plugins: [{
+    name: 'contract-exports',
+    setup(check) {
+      check.onResolve({ filter: /.*/ }, (args) => {
+        if (args.kind === 'entry-point') return undefined;
+        if (CONTRACT.test(args.path)) return { path: args.path, namespace: 'contract' };
+        if (args.namespace === 'contract') return { path: bundle };
+        return { external: true };
+      });
+      check.onLoad({ filter: /.*/, namespace: 'contract' }, () => ({ contents: `export * from ${JSON.stringify(bundle)};` }));
+    },
+  }],
+}).then(() => [], (error) => {
+  if (!Array.isArray(error?.errors)) throw error;
+  return error.errors;
+});
+if (gaps.length > 0) {
+  for (const { text, location } of gaps) {
+    const where = location ? `${join(basename(dist), location.file)}:${location.line}` : basename(dist);
+    const name = /import "([^"]+)"/i.exec(text)?.[1];
+    const subpath = /"contract:([^"]+)"/.exec(text)?.[1];
+    console.error(name && subpath
+      ? `inline-contract: ${where} imports "${name}" from "${subpath}", which dist/contract/index.js does not export`
+      : `inline-contract: ${where}: ${text}`);
+  }
+  console.error('inline-contract: the bundle holds only the names packages/contract/src/index.ts re-exports. '
+    + 'Re-export each name there: an `export *` of its module, or the named re-export that reaches it.');
+  process.exit(1);
+}
+
 // `tsc` is located through the module graph rather than a guessed `node_modules` path, because
 // `typescript` is a devDependency of THIS package and may sit here or be hoisted to the workspace
 // root. Via the manifest's own `bin` entry: TypeScript 7's `exports` map does not publish

package/scripts/install-as-command.mjs

@@ -31,7 +31,9 @@ if (!['link', 'global', 'uninstall'].includes(mode)) {
 }
 
 // npm invocation shim (identical to dev.mjs / check-pack.mjs).
-const npmExecpath = process.env.npm_execpath;
+// pnpm 12 sets npm_execpath to a native executable; these operations need npm.
+const npmExecpath = /(?:^|[\\/])npm-cli\.js$/.test(process.env.npm_execpath ?? '')
+  ? process.env.npm_execpath : undefined;
 const npmCli = process.platform === 'win32' ? 'npm.cmd' : 'npm';
 function npm(args, { capture = false } = {}) {
   const viaNode = Boolean(npmExecpath);

package/scripts/measure-transcript-facts-health.mjs

@@ -0,0 +1,87 @@
+/** Integration-only: npm run build:server && node packages/cezar/scripts/measure-transcript-facts-health.mjs
+ * Boots the actual loopback server; deliberately never imported by the fast tests.
+ */
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import { once } from 'node:events';
+import { mkdtempSync, readdirSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { seedColdHistories, verifyFacts } from './transcript-facts-fixture.mjs';
+
+const root = mkdtempSync(join(process.platform === 'win32' ? tmpdir() : '/tmp', 'cez-facts-health-'));
+// The experiment has no external peers, credentials, background updater, or real home.
+for (const key of Object.keys(process.env)) if (key.startsWith('CEZ_')) delete process.env[key];
+process.env.CEZ_HOME = join(root, 'home');
+process.env.CEZ_DRY_RUN = '1';
+const runtime = { url: new URL('../dist/', import.meta.url), ext: 'js' };
+const dataDir = join(root, 'cold-project', '.ai/cezar');
+let store;
+let bootStore;
+let server;
+const watchdog = setTimeout(() => { console.error('health measurement exceeded 30s'); process.exitCode = 1; server?.closeAllConnections(); server?.close(); store?.close(); bootStore?.close(); }, 30_000);
+try {
+  const { RunStore } = await import(new URL('runs/store.js', runtime.url));
+  const { startServer } = await import(new URL('server/server.js', runtime.url));
+  // Keep git discovery away from the user's parent repository, even if TMPDIR
+  // was set inside a cezar worktree. This repo contains only the experiment.
+  execFileSync('git', ['init', '--initial-branch=main'], { cwd: root, stdio: 'ignore' });
+  const fixtures = await seedColdHistories(dataDir, runtime);
+  global.gc?.();
+  // Project-open scenario: establish the real HTTP/client path before opening a
+  // second cold store on this same event loop. No transcript sidecar is primed.
+  bootStore = RunStore.open(join(root, '.ai/cezar'));
+  await bootStore.factsWarmIdle();
+  server = startServer({ repoRoot: root, store: bootStore, manager: {}, version: 'task4-measurement', bindHost: '127.0.0.1' }, 0);
+  if (!server.listening) await once(server, 'listening');
+  const address = server.address();
+  assert.ok(address && typeof address !== 'string');
+  const endpoint = `http://127.0.0.1:${address.port}/api/v1/health`;
+  const primingStart = performance.now();
+  const prime = await fetch(endpoint, { signal: AbortSignal.timeout(2_000) });
+  assert.equal(prime.status, 200);
+  assert.equal((await prime.json()).version, 'task4-measurement');
+  const primingLatencyMs = performance.now() - primingStart;
+  assert.equal(readdirSync(join(dataDir, 'runs')).filter(name => name.endsWith('.facts.json')).length, 0);
+  const start = performance.now();
+  store = RunStore.open(dataDir);
+  let end;
+  const warming = store.factsWarmIdle().then(() => { end = performance.now(); });
+  const samples = [];
+  while (end === undefined) {
+    const requestStart = performance.now();
+    const cpuStart = process.threadCpuUsage();
+    const response = await fetch(endpoint, { signal: AbortSignal.timeout(2_000) });
+    assert.equal(response.status, 200);
+    assert.equal((await response.json()).version, 'task4-measurement');
+    const requestEnd = performance.now();
+    // Include EVERY request begun while cold warm-up was active, even one ending after it.
+    const cpu = process.threadCpuUsage(cpuStart);
+    samples.push({ startMs: requestStart - start, endMs: requestEnd - start, latencyMs: requestEnd - requestStart,
+      mainThreadCpuMs: (cpu.user + cpu.system) / 1000 });
+    await delay(5);
+  }
+  await warming;
+  assert.ok(samples.length > 0, 'health requests must overlap cold warming');
+  assert.ok(samples.every(sample => sample.startMs < end - start && sample.endMs > 0));
+  const result = { kind: 'transcript-facts-http-health', runtime: runtime.url.href,
+    endpoint: '/api/v1/health', scenario: 'already-listening server during cold project open', primingLatencyMs,
+    ...verifyFacts(dataDir, fixtures, store), durationMs: end - start,
+    sampleCount: samples.length, maxLatencyMs: Math.max(...samples.map(sample => sample.latencyMs)), samples };
+  console.log(JSON.stringify(result));
+  assert.ok(result.maxLatencyMs < 50, `max health latency ${result.maxLatencyMs.toFixed(3)}ms must be <50ms`);
+} finally {
+  clearTimeout(watchdog);
+  let cleanupTimer;
+  try {
+    if (server) await Promise.race([server.shutdownForRestart(), new Promise((_, reject) => {
+      cleanupTimer = setTimeout(() => reject(new Error('server cleanup timed out')), 5_000);
+    })]);
+  } finally {
+    clearTimeout(cleanupTimer);
+    store?.close();
+    bootStore?.close();
+    rmSync(root, { recursive: true, force: true });
+  }
+}

package/scripts/measure-transcript-facts-lag.mjs

@@ -0,0 +1,68 @@
+/** Dedicated server-free regression (intentionally outside parallel Vitest discovery).
+ * node --expose-gc --import tsx packages/cezar/scripts/measure-transcript-facts-lag.mjs
+ * Built runtime: pass an absolute dist directory. Baseline source: pass its src directory and ts.
+ * A separate process removes test-runner loop work, NOT unrelated host CPU scheduling.
+ * Keep every sample and the strict wall-time ceiling; investigate load instead of retrying here.
+ */
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { setTimeout as delay } from 'node:timers/promises';
+import { seedColdHistories, verifyFacts } from './transcript-facts-fixture.mjs';
+
+const runtime = { url: process.argv[2] ? pathToFileURL(process.argv[2] + '/') : new URL('../src/', import.meta.url), ext: process.argv[3] ?? (process.argv[2] ? 'js' : 'ts') };
+const { RunStore } = await import(new URL('runs/store.' + runtime.ext, runtime.url));
+const dir = mkdtempSync(join(tmpdir(), 'cez-facts-lag-'));
+let store;
+let timer;
+try {
+  const fixtures = await seedColdHistories(dir, runtime);
+  // Fixture allocation/collection belongs to setup, not the measured warm path.
+  global.gc?.();
+  const periodMs = 20;
+  const ticks = [];
+  let previous = performance.now();
+  let previousCpu = process.threadCpuUsage();
+  timer = setInterval(() => {
+    const at = performance.now();
+    const cpu = process.threadCpuUsage();
+    ticks.push({ at, lagMs: Math.max(0, at - previous - periodMs),
+      mainThreadCpuMs: (cpu.user + cpu.system - previousCpu.user - previousCpu.system) / 1000 });
+    previousCpu = cpu;
+    previous = at;
+  }, periodMs);
+  // Establish a real interval before starting; retain the first tick after completion too.
+  await delay(periodMs * 2);
+  const start = performance.now();
+  store = RunStore.open(dir);
+  await store.factsWarmIdle();
+  const end = performance.now();
+  while (!ticks.some(tick => tick.at > end)) await delay(periodMs);
+  clearInterval(timer);
+  const overlapping = ticks.filter(tick => tick.at >= start && tick.at <= end);
+  const result = { kind: 'transcript-facts-lag', runtime: runtime.url.href, periodMs,
+    ...verifyFacts(dir, fixtures, store), durationMs: end - start, ticks: ticks.length,
+    beforeTicks: ticks.filter(tick => tick.at < start).length,
+    trailingTicks: ticks.filter(tick => tick.at > end).length,
+    overlappingTicks: overlapping.length, maxLagMs: Math.max(...ticks.map(tick => tick.lagMs)),
+    samples: ticks.map(tick => ({ offsetMs: tick.at - start, lagMs: tick.lagMs, mainThreadCpuMs: tick.mainThreadCpuMs })) };
+  console.log(JSON.stringify(result));
+  assert.equal(result.histories, 700);
+  assert.equal(result.sidecars, 700);
+  assert.equal(result.plain, 350);
+  assert.equal(result.brotli, 350);
+  assert.equal(result.events, 105_592);
+  assert.ok(result.largestBytes > 40_000_000);
+  assert.equal(result.coldSidecars, 0);
+  assert.ok(result.beforeTicks > 0, 'must establish the interval before warming');
+  assert.ok(result.trailingTicks > 0, 'must retain a trailing tick after warming');
+  assert.ok(overlapping.length > 0, 'must sample during cold warm-up');
+  assert.ok(result.durationMs > 0);
+  assert.ok(result.maxLagMs < 20, `max extra interval lag ${result.maxLagMs.toFixed(3)}ms must be <20ms`);
+} finally {
+  clearInterval(timer);
+  store?.close();
+  rmSync(dir, { recursive: true, force: true });
+}

package/scripts/mock-ci-tool.mjs

@@ -1,13 +1,13 @@
 // Offline harness fixtures share the real bundled MCP protocol, never a fake receipt.
-import { writeFileSync, existsSync } from 'node:fs';
-import { basename } from 'node:path';
+import { writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { basename, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
 
 export async function probeCiTool(backend, wire, pr = process.env.CEZ_MOCK_CI_PR) {
   if (!pr) return;
-  return probeCezarTool(backend, wire, 'cezar_wait_for_ci', { pr });
+  return probeCezarTool(backend, wire, 'cezar_wait', { kind: 'pr', pr });
 }
 
 // Calls one cezar tool the way the real harness would: through the wired MCP server (or Pi/OMP extension).
@@ -24,7 +24,11 @@ export async function probeCezarTool(backend, wire, name, args) {
     extension({ registerTool(tool) { tools.push(tool); } });
     const tool = tools.find(tool => tool.name === name);
     if (!tool) throw new Error(`${name} not registered`);
-    result = { names: tools.map(tool => tool.name), response: await tool.execute('ci-1', args) };
+    // A registered tool pi's tool selection hides answers the model the way pi 1.0.4 does.
+    const response = backend === 'pi' && !piAdmits(wire, name)
+      ? { isError: true, content: [{ type: 'text', text: `Tool ${name} not found` }] }
+      : await tool.execute('ci-1', args);
+    result = { names: tools.map(tool => tool.name), response };
   } else {
     let server; let env;
     if (backend === 'claude') {
@@ -34,8 +38,16 @@ export async function probeCezarTool(backend, wire, name, args) {
       server = Object.entries(wire.config ?? {}).find(([key]) => key.startsWith('mcp_servers.cezar_ci_'))?.[1];
       env = Object.fromEntries((server?.env_vars ?? []).map(name => [name, process.env[name]]));
     } else if (backend === 'cursor') {
-      server = wire.mcpServers.find(server => server.name.startsWith('cezar_ci_'));
-      env = Object.fromEntries(server?.env.map(({name,value}) => [name,value]) ?? []);
+      if (Array.isArray(wire)) {
+        const dir = wire[wire.indexOf('--plugin-dir') + 1];
+        const servers = JSON.parse(readFileSync(join(dir, 'mcp.json'), 'utf8')).mcpServers;
+        server = Object.entries(servers).find(([name]) => name.startsWith('cezar_ci_'))?.[1];
+        env = Object.fromEntries(Object.entries(server?.env ?? {}).map(([key, value]) =>
+          [key, value.replace(/\$\{([^}]+)\}/g, (_, name) => process.env[name] ?? '')]));
+      } else {
+        server = wire.mcpServers.find(server => server.name.startsWith('cezar_ci_'));
+        env = Object.fromEntries(server?.env.map(({name,value}) => [name,value]) ?? []);
+      }
     } else {
       const local = Object.entries(wire.mcp ?? {}).find(([key]) => key.startsWith('cezar_ci_'))?.[1];
       server = local && { command: local.command[0], args: local.command.slice(1) };
@@ -53,12 +65,43 @@ export async function probeCezarTool(backend, wire, name, args) {
   return result;
 }
 
+// pi reads --tools as an allowlist and --no-tools as an empty one; with neither (cezar's default
+// list sends --no-builtin-tools), an extension's tools are active once registered
+// (hearsay-tools/cezarion#1305).
+function piAdmits(wire, name) {
+  const index = wire.lastIndexOf('--tools');
+  if (index !== -1) return wire[index + 1].split(',').includes(name);
+  return !wire.includes('--no-tools');
+}
+
 export async function ciPrompt(backend, wire, text) {
   const pr = /mock:ci-wait(?:\s+(https:\/\/[^\s\"\\]+))?/.exec(text)?.[1] ?? 'https://github.com/owner/repo/pull/1';
   const result = await probeCiTool(backend, wire, pr);
   return JSON.stringify(result.response);
 }
 
+// `mock:cezar-tool <name> <base64-json-args>` calls any cezar tool with those arguments
+// (hearsay-tools/cezarion#1233). Base64, standard or URL-safe, survives every wire's escaping.
+// Several calls run in order within one turn; `"wait_id": "last"` names the wait the previous
+// answer registered, so a turn can open a wait and cancel it.
+export async function toolPrompt(backend, wire, text) {
+  const matches = [...text.matchAll(/mock:cezar-tool\s+([a-z_]+)\s+([A-Za-z0-9+/=_-]+)/g)];
+  if (!matches.length) throw new Error('mock:cezar-tool needs a tool name and base64 JSON arguments');
+  const responses = [];
+  let last;
+  for (const [, name, encoded] of matches) {
+    const args = JSON.parse(Buffer.from(encoded, 'base64').toString('utf8'));
+    if (args.wait_id === 'last') args.wait_id = last;
+    const result = await probeCezarTool(backend, wire, name, args);
+    try { last = JSON.parse(result.response.content[0].text.split('\n')[0]).wait_id ?? last; } catch { /* a refusal names no wait */ }
+    responses.push(JSON.stringify(result.response));
+  }
+  // `mock:then <base64 text>` ends the turn with that text after the calls (an ask line, say).
+  const then = /mock:then\s+([A-Za-z0-9+/=_-]+)/.exec(text);
+  if (then) responses.push(Buffer.from(then[1], 'base64').toString('utf8'));
+  return responses.join('\n');
+}
+
 // `mock:preview-serve <port>` registers the e2e fixture app (`node preview-app.mjs <port>`) as a live preview.
 export async function previewPrompt(backend, wire, text) {
   const port = Number(/mock:preview-serve\s+(\d+)/.exec(text)?.[1]);

package/scripts/mock-claude-model-refusal.mjs

@@ -0,0 +1,42 @@
+// Native Claude stream-json fixtures, with independent per-input retry counts.
+const attempts = new Map();
+const model = 'claude-test-model';
+export async function modelRefusalReply(text, uuid, emit, replay) {
+  const mode = text.split(':')[2];
+  const count = (attempts.get(text) ?? 0) + 1;
+  attempts.set(text, count);
+  const selected = mode === 'changed' ? 'claude-other-model' : model;
+  emit({ type: 'system', subtype: 'init', ...(mode === 'missing-session' ? {} : { session_id: mode === 'changed-session' ? 'other-session' : mode === 'empty-session' ? '' : 'model-refusal-session' }),
+    ...(mode === 'missing-model' ? {} : { model: mode === 'empty-model' ? '' : selected }) });
+  if (mode === 'seed' || mode === 'queued-seed' || (mode === 'once' && count > 1) || mode === 'later') {
+    replay(uuid, text);
+    emit({ type: 'assistant', message: { role: 'assistant', content: [{ type: 'text', text: `Completed ${text}` }] } });
+    // Leave the final model call complete while another stdin line queues.
+    if (mode === 'queued-seed') await new Promise(resolve => setTimeout(resolve, 250));
+    emit({ type: 'result', subtype: 'success', result: `Completed ${text}`,
+      usage: { input_tokens: 10, output_tokens: 5 }, user_message_uuids: [uuid], queued_turn_count: 0 });
+    return;
+  }
+  const refused = mode === 'wrong-model' ? 'claude-wrong-model' : selected;
+  let message = `There's an issue with the selected model (${refused}). It may not exist or you may not have access to it. Run --model to pick a different model.`;
+  if (mode === 'auth') message = 'Failed to authenticate. API Error: 401 OAuth access token has been revoked.';
+  if (mode === 'limit') message = 'API Error: Request rejected (429) · All credentials are cooling down. Please try again later.';
+  if (mode.startsWith('system-')) emit({ type: 'system', subtype: mode.slice(7).replaceAll('-', '_'), task_id: 'already-started' });
+  if (mode === 'tool-progress') emit({ type: 'tool_progress', tool_use_id: 'already-started', tool_name: 'Bash', elapsed_time_seconds: 1 });
+  if (mode === 'work') emit({ type: 'assistant', message: { role: 'assistant', content: [{ type: 'tool_use', id: 'already-ran', name: 'Bash', input: { command: 'touch result' } }] } });
+  if (mode === 'prose') emit({ type: 'assistant', message: { role: 'assistant', content: [{ type: 'text', text: 'I already changed the file.' }] } });
+  if (mode === 'assistant-usage') emit({ type: 'assistant', message: { role: 'assistant', content: [], usage: { input_tokens: 1, output_tokens: 0 } } });
+  // Both real diagnostic sources: the visible assistant frame and is_error result.
+  emit({ type: 'assistant', message: { role: 'assistant', content: [{ type: 'text', text: message }] } });
+  const usage = { input_tokens: mode === 'used' ? 1 : 0, output_tokens: 0,
+    service_tier: 'standard', cache_read_input_tokens: mode === 'cached' ? 1 : 0 };
+  if (mode === 'missing-count') delete usage.output_tokens;
+  if (mode === 'invalid-count') usage.input_tokens = -1;
+  emit({ type: 'result', subtype: 'success', is_error: true, result: message,
+    modelUsage: { [selected]: { inputTokens: mode === 'model-tokens' ? 1 : 0,
+      outputTokens: 0, costUSD: mode === 'model-cost' ? 0.01 : mode === 'model-invalid' ? null : 0,
+      contextWindow: 200000, maxOutputTokens: 64000 } },
+    ...(mode === 'missing-usage' ? {} : { usage }),
+    ...(mode === 'paid' ? { total_cost_usd: 0.01 } : { total_cost_usd: 0 }),
+    user_message_uuids: [uuid], queued_turn_count: 0 });
+}