@hearsay-tools/squawk 0.0.0-stage → 0.17.0-dev.5682

package/scripts/inline-contract.mjs

@@ -0,0 +1,165 @@
+/**
+ * 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.
+ *
+ * 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 { 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 = 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');
+// 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 = [];
+const scan = (dir) => {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (p !== outdir) scan(p);
+    } else if (/\.(js|d\.ts|js\.map)$/.test(entry.name)) {
+      SPEC.lastIndex = 0;
+      if (SPEC.test(readFileSync(p, 'utf8'))) referrers.push(p);
+    }
+  }
+};
+scan(dist);
+
+rmSync(outdir, { recursive: true, force: true });
+if (referrers.length === 0) {
+  console.log('inline-contract ok — nothing in dist references the contract, nothing bundled');
+  process.exit(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.
+const bundled = await build({
+  metafile: true,
+  entryPoints: [entry],
+  outfile: join(outdir, 'index.js'),
+  bundle: true,
+  format: 'esm',
+  platform: 'neutral',
+  target: 'es2022',
+  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
+// `./bin/tsc`, so resolving that subpath directly is ERR_PACKAGE_PATH_NOT_EXPORTED.
+const require_ = createRequire(import.meta.url);
+const tsManifest = require_.resolve('typescript/package.json');
+const tscBin = join(dirname(tsManifest), require_(tsManifest).bin.tsc);
+
+// The declarations for the bundle above. `tsc` mirrors `src/**` into `outdir`, so `index.d.ts`
+// lands beside `index.js` and its relative siblings (`./health.js` → `./health.d.ts`) resolve as
+// TypeScript expects. Those siblings have no runtime twin, which is correct: the bundle is
+// self-contained and nothing imports those paths at runtime.
+execFileSync(
+  process.execPath,
+  [
+    tscBin,
+    '--project',
+    join(contractRoot, 'tsconfig.json'),
+    '--emitDeclarationOnly',
+    '--declarationMap',
+    'false',
+    '--sourceMap',
+    'false',
+    '--outDir',
+    outdir,
+  ],
+  { stdio: 'inherit' },
+);
+if (!existsSync(join(outdir, 'index.d.ts'))) {
+  console.error('inline-contract: tsc emitted no index.d.ts — the bundled contract would ship untyped');
+  process.exit(1);
+}
+
+for (const p of referrers) {
+  let rel = relative(dirname(p), join(outdir, 'index.js')).replaceAll('\\', '/');
+  if (!rel.startsWith('.')) rel = `./${rel}`;
+  writeFileSync(p, readFileSync(p, 'utf8').replace(SPEC, `'${rel}'`), 'utf8');
+}
+console.log(`inline-contract ok — contract bundled with declarations, ${referrers.length} file(s) repointed`);

package/scripts/install-as-command.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+// `npm run install-as-command` (+ `:global` and the `uninstall-as-command`
+// counterpart): build this checkout and put a global `cezarion`/`cez`
+// command on PATH pointing at THIS working tree — the local-dev equivalent of
+// `npx cezarion`, with no publish and no `npx` download. Spec 013.
+//
+//   --mode link       build → `npm link`             (live; `npm run build` refreshes it)
+//   --mode global     build → `npm install --global .` (self-contained snapshot)
+//   --mode uninstall                  `npm rm --global @wjarka/cezarion`
+//   --no-build        skip the build (relink an already-built dist)
+//
+// The install decisions live in the unit-tested src/install-as-command.ts
+// (compiled to dist by the build); this script owns spawning + exit codes.
+// npm is invoked through process.execPath + npm_execpath — same cross-platform
+// pattern as scripts/dev.mjs / scripts/check-pack.mjs (no .cmd shim assumptions).
+
+import { productIdentity } from '../src/home/identity.ts';
+import { spawnSync, execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const argv = process.argv.slice(2);
+
+const modeIdx = argv.indexOf('--mode');
+const mode = modeIdx >= 0 ? argv[modeIdx + 1] : 'link';
+const noBuild = argv.includes('--no-build');
+if (!['link', 'global', 'uninstall'].includes(mode)) {
+  console.error(`install-as-command: unknown --mode "${mode}" (expected link | global | uninstall)`);
+  process.exit(1);
+}
+
+// npm invocation shim (identical to dev.mjs / check-pack.mjs).
+// 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);
+  const file = viaNode ? process.execPath : npmCli;
+  const full = viaNode ? [npmExecpath, ...args] : args;
+  const shell = !viaNode && process.platform === 'win32';
+  if (capture) {
+    return execFileSync(file, full, { cwd: repoRoot, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, shell });
+  }
+  const res = spawnSync(file, full, { cwd: repoRoot, stdio: 'inherit', shell });
+  return res.status ?? 1;
+}
+
+const distDir = path.join(repoRoot, 'dist');
+const build = mode !== 'uninstall' && !noBuild;
+
+if (mode !== 'uninstall' && noBuild && !existsSync(path.join(distDir, 'index.js'))) {
+  console.error('install-as-command: --no-build was set but dist/ is missing — run once without --no-build first.');
+  process.exit(1);
+}
+
+if (build) {
+  console.log('install-as-command: building (npm run build)…');
+  const code = npm(['run', 'build']);
+  if (code !== 0) {
+    console.error('install-as-command: build failed — nothing installed.');
+    process.exit(code);
+  }
+}
+
+// Load the tested planner from dist. Present after any build; for uninstall on a
+// never-built checkout it may be absent, so fall back to the known command.
+let planner = null;
+const plannerPath = path.join(distDir, 'install-as-command.js');
+if (existsSync(plannerPath)) {
+  planner = await import(pathToFileURL(plannerPath).href);
+}
+const PACKAGE_NAME = planner?.PACKAGE_NAME ?? productIdentity(false).npmPackage;
+const steps = planner
+  ? planner.planInstall({ mode, build }).steps
+  : [{ args: ['rm', '--global', PACKAGE_NAME], label: `remove global ${PACKAGE_NAME}` }];
+
+for (const step of steps) {
+  console.log(`install-as-command: npm ${step.args.join(' ')} (${step.label})`);
+  const code = npm(step.args);
+  if (code !== 0) {
+    if (mode === 'uninstall') {
+      // Idempotent: `npm rm -g` of an absent package is a no-op success.
+      console.log('install-as-command: nothing to uninstall (already absent).');
+      break;
+    }
+    console.error(`install-as-command: \`npm ${step.args.join(' ')}\` failed (see npm output above).`);
+    console.error(
+      '  If this is an EACCES on a root-owned global prefix, set a user-writable one\n' +
+        '  (e.g. `npm config set prefix ~/.npm-global`) and retry — do NOT use sudo.',
+    );
+    process.exit(code);
+  }
+}
+
+if (mode === 'uninstall') {
+  console.log(`install-as-command: global ${planner?.BIN_NAMES.join(' / ') ?? 'cezarion / cez'} removed.`);
+  process.exit(0);
+}
+
+const commandName = planner?.COMMAND_NAME ?? 'cez';
+
+// Verify the shims and print a PATH hint.
+let prefix = '';
+try {
+  prefix = npm(['prefix', '--global'], { capture: true }).trim();
+} catch {
+  // best-effort — the install already succeeded above
+}
+if (planner && prefix) {
+  const binDir = planner.globalBinDir(prefix, process.platform);
+  const present = planner.globalShimPaths(prefix, process.platform).filter((p) => existsSync(p));
+  const names = planner.BIN_NAMES.join(', ');
+  if (present.length === planner.BIN_NAMES.length) {
+    console.log(`\ninstall-as-command: installed ${names} → ${binDir}`);
+  } else {
+    console.log(`\ninstall-as-command: done, but only ${present.length}/${planner.BIN_NAMES.length} shims found in ${binDir}`);
+  }
+  console.log(`  Ensure this is on your PATH:\n    ${binDir}`);
+  console.log(`  Then, from any repo:  ${commandName} --help`);
+} else {
+  console.log(`\ninstall-as-command: done. Ensure your npm global bin dir is on PATH, then run \`${commandName} --help\`.`);
+}

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

@@ -0,0 +1,103 @@
+/** 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 { timingSnapshot, timingDelta, blockingBudget } from './transcript-facts-timing.mjs';
+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 (/^(CEZ|HSQ)_/.test(key)) delete process.env[key];
+process.env.HSQ_HOME = process.env.CEZ_HOME = join(root, 'home');
+process.env.HSQ_DRY_RUN = process.env.CEZ_DRY_RUN = '1';
+const runtime = { url: new URL('../dist/', import.meta.url), ext: 'js' };
+let dataDir;
+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));
+  // Seed where the built revision's cockpit reads each project, so a cockpit start moves nothing.
+  const { projectPaths } = await import(new URL('project-paths.js', runtime.url));
+  dataDir = projectPaths(join(root, 'cold-project')).write;
+  const { startServer } = await import(new URL('server/server.js', runtime.url));
+  const { resolveHome } = await import(new URL('home/resolve.js', runtime.url));
+  const home = resolveHome({ purpose: 'cli' });
+  const { Home } = await import(new URL('home/home.js', runtime.url));
+  Home.sandbox(home.rootOverride ?? home.root, { layout: home.layout });
+  // 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(projectPaths(root).write);
+  await bootStore.factsWarmIdle();
+  server = startServer({ home, 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();
+  let end;
+  let warming;
+  const samples = [];
+  while (end === undefined) {
+    const requestStart = performance.now();
+    const measurementStart = timingSnapshot();
+    const pendingResponse = fetch(endpoint, { signal: AbortSignal.timeout(2_000) });
+    // The first request includes synchronous project-open work too.
+    if (!store) {
+      store = RunStore.open(dataDir);
+      warming = store.factsWarmIdle().then(() => { end = performance.now(); });
+    }
+    const response = await pendingResponse;
+    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 measurement = timingDelta(measurementStart, timingSnapshot());
+    samples.push({ startMs: requestStart - start, endMs: requestEnd - start, latencyMs: requestEnd - requestStart,
+      ...measurement, ...blockingBudget(measurement) });
+    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,
+    maxBlockingMs: Math.max(...samples.map(sample => sample.blockingMs)),
+    maxMainThreadCpuMs: Math.max(...samples.map(sample => sample.mainThreadCpuMs)),
+    sampleCount: samples.length, maxLatencyMs: Math.max(...samples.map(sample => sample.latencyMs)), samples };
+  console.log(JSON.stringify(result));
+  // Exclude run-queue delay, but retain synchronous blocking and request latency.
+  assert.ok(result.maxBlockingMs < 50, `max health blocking ${result.maxBlockingMs.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,69 @@
+/** 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.
+ * Gate loop CPU and blocking time; exclude host run-queue delay.
+ */
+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 { timingSnapshot, timingDelta, blockingBudget } from './transcript-facts-timing.mjs';
+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 = timingSnapshot();
+  timer = setInterval(() => {
+    const current = timingSnapshot();
+    const sample = timingDelta(previous, current);
+    ticks.push({ at: current.at, lagMs: Math.max(0, sample.elapsedMs - periodMs), ...sample, ...blockingBudget(sample, periodMs) });
+    previous = current;
+  }, 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)),
+    maxBlockingMs: Math.max(...ticks.map(tick => tick.blockingMs)),
+    maxMainThreadCpuMs: Math.max(...ticks.map(tick => tick.mainThreadCpuMs)),
+    samples: ticks.map(({ at, ...sample }) => ({ offsetMs: at - start, ...sample })) };
+  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);
+  // Exclude planned timer sleep and run-queue delay, but retain synchronous blocking.
+  assert.ok(result.maxBlockingMs < 20, `max interval blocking ${result.maxBlockingMs.toFixed(3)}ms must be <20ms`);
+} finally {
+  clearInterval(timer);
+  store?.close();
+  rmSync(dir, { recursive: true, force: true });
+}

package/scripts/mock-autonomous.mjs

@@ -0,0 +1,13 @@
+// Shared responses only; each caller encodes its own native runner wire (#426).
+// `lifecycle([name, args])` makes the caller's cezar tool call and returns a note for the text.
+import { DONE, ask } from './mock-ci-tool.mjs';
+let cap = false;
+export async function autonomousReply(prompt, lifecycle) {
+  const askCap = prompt.includes('mock:autonomous-cezar-ask-cap');
+  if (prompt.includes('mock:autonomous-cap') || askCap) cap = true;
+  if (askCap) return 'Pick one.' + await lifecycle(ask());
+  if (prompt.startsWith('Continue working autonomously until the task is fully complete.')) {
+    return cap ? 'Still working.' : 'Autonomous work finished.' + await lifecycle(DONE);
+  }
+  return 'Still working.';
+}

package/scripts/mock-ci-tool.mjs

@@ -0,0 +1,159 @@
+// Offline harness fixtures share the real bundled MCP protocol, never a fake receipt.
+import { readFileSync, existsSync } from 'node:fs';
+import { publishFile } from './mock-publish.mjs';
+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', { kind: 'pr', pr });
+}
+
+// Calls one cezar tool the way the real harness would: through the wired MCP server (or Pi/OMP extension).
+export async function probeCezarTool(backend, wire, name, args, record = true) {
+  const result = backend === 'pi' || backend === 'omp'
+    ? await probeExtensionTool(backend, wire, name, args)
+    : await probeMcpTool(mcpServerOf(backend, wire), name, args);
+  if (record && process.env.CEZ_MOCK_CI_RESULT) publishFile(process.env.CEZ_MOCK_CI_RESULT, JSON.stringify(result));
+  return result;
+}
+
+/** Pi and OMP load the tools as an extension the mock imports and calls in process. */
+async function probeExtensionTool(backend, wire, name, args) {
+  const extensions = wire.flatMap((arg, index) => arg === '--extension' ? [wire[index + 1]] : []);
+  const path = extensions.find(path => basename(path) === `${backend}-ci-wait.mjs`);
+  if (!path) throw new Error('CI extension absent');
+  // The real Pi loader compiles TS when running from source; installed script uses JS.
+  if (existsSync(new URL('../src/ci-wait/mcp.ts', import.meta.url))) { const { register } = await import('tsx/esm/api'); register(); }
+  const { default: extension } = await import(pathToFileURL(path));
+  const tools = [];
+  extension({ registerTool(tool) { tools.push(tool); } });
+  const tool = tools.find(tool => tool.name === name);
+  if (!tool) throw new Error(`${name} not registered`);
+  // 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);
+  return { names: tools.map(tool => tool.name), response };
+}
+
+/** `${NAME}` placeholders in a server's env resolve from this process, as the harness does. */
+const expandEnv = (env) => Object.fromEntries(Object.entries(env ?? {}).map(([key, value]) =>
+  [key, value.replace(/\$\{([^}]+)\}/g, (_, name) => process.env[name] ?? '')]));
+
+/** The cezar MCP server a runner's wire names, with the environment it starts under. */
+function mcpServerOf(backend, wire) {
+  if (backend === 'claude') {
+    const server = Object.values(JSON.parse(wire[wire.indexOf('--mcp-config') + 1]).mcpServers)[0];
+    return { server, env: expandEnv(server.env) };
+  }
+  if (backend === 'codex') {
+    const server = Object.entries(wire.config ?? {}).find(([key]) => key.startsWith('mcp_servers.cezar_ci_'))?.[1];
+    return { server, env: Object.fromEntries((server?.env_vars ?? []).map(name => [name, process.env[name]])) };
+  }
+  if (backend === 'cursor') return cursorServerOf(wire);
+  const local = Object.entries(wire.mcp ?? {}).find(([key]) => key.startsWith('cezar_ci_'))?.[1];
+  return { server: local && { command: local.command[0], args: local.command.slice(1) }, env: { ...process.env, ...local?.environment } };
+}
+
+/** Cursor print names the server in its plugin directory; the ACP-shaped wire lists it inline. */
+function cursorServerOf(wire) {
+  if (!Array.isArray(wire)) {
+    const server = wire.mcpServers.find(server => server.name.startsWith('cezar_ci_'));
+    return { server, env: Object.fromEntries(server?.env.map(({ name, value }) => [name, value]) ?? []) };
+  }
+  const dir = wire[wire.indexOf('--plugin-dir') + 1];
+  const servers = JSON.parse(readFileSync(join(dir, 'mcp.json'), 'utf8')).mcpServers;
+  const server = Object.entries(servers).find(([name]) => name.startsWith('cezar_ci_'))?.[1];
+  return { server, env: expandEnv(server?.env) };
+}
+
+async function probeMcpTool({ server, env }, name, args) {
+  if (!server) throw new Error('CI server absent');
+  const client = new Client({ name: 'offline-harness', version: '1' });
+  try {
+    await client.connect(new StdioClientTransport({ command: server.command, args: server.args, env, stderr: 'pipe' }));
+    const list = await client.listTools();
+    return { names: list.tools.map(tool => tool.name), response: await client.callTool({ name, arguments: args }) };
+  } finally { await client.close(); }
+}
+
+// hearsay-tools/cezarion#2397: a scripted reply that finishes, asks or waits calls the cezar
+// lifecycle tool over the session's own wire before its turn ends, as an agent does. It
+// returns '' (a refusal is the tool's answer, not the mock's failure), or a note for the turn
+// text when the tool could not be reached, so the transcript says why the turn did not settle.
+export async function lifecycleCall(backend, wire, name, args) {
+  try { await probeCezarTool(backend, wire, name, args, false); return ''; }
+  catch (error) { return `\n\n(mock: ${name} failed: ${error?.message ?? error})`; }
+}
+/** The one-question card the portable ask scenarios send. */
+export const LIBRARY_QUESTIONS = [{ header: 'Library', question: 'Which test library?', options: [{ label: 'Vitest' }, { label: 'Node test' }] }];
+export const ASK_CONTEXT = 'A choice is needed before I continue.';
+export const DONE = ['cezar_done', {}];
+export const ask = (questions = LIBRARY_QUESTIONS, context = ASK_CONTEXT) => ['cezar_ask', { context, questions }];
+export const wait = (note = 'Re-check the downstream work.') => ['cezar_wait', { kind: 'timer', seconds: 60, note }];
+
+// 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);
+}
+
+const CEZAR_TOOL_NAME = /cezar-tool\s+([a-z_]+)/;
+
+/** The native approval gate needs the first tool's name before executing the prompt. */
+export function cezarToolName(text) {
+  return new RegExp(`mock:${CEZAR_TOOL_NAME.source}`).exec(text)?.[1];
+}
+
+// `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. `mock:gate <base64 path>` between
+// them holds the turn there until that file exists, so a test can act between two calls, or
+// between the last call and the turn end (hearsay-tools/cezarion#2397).
+export async function toolPrompt(backend, wire, text) {
+  const steps = [...text.matchAll(new RegExp(`mock:(?:${CEZAR_TOOL_NAME.source}\\s+([A-Za-z0-9+/=_-]+)|gate\\s+([A-Za-z0-9+/=_-]+))`, 'g'))];
+  if (!steps.some(step => step[1])) throw new Error('mock:cezar-tool needs a tool name and base64 JSON arguments');
+  const responses = [];
+  let last;
+  for (const [, name, encoded, gate] of steps) {
+    if (gate) { await gateOpen(Buffer.from(gate, 'base64').toString('utf8')); continue; }
+    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');
+}
+
+async function gateOpen(path) {
+  const deadline = Date.now() + 15_000;
+  while (!existsSync(path)) {
+    if (Date.now() > deadline) throw new Error(`mock:gate ${path} was not opened`);
+    await new Promise(resolve => setTimeout(resolve, 10));
+  }
+}
+
+// `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]);
+  const fixture = fileURLToPath(new URL('../../web/e2e/fixtures/preview-app.mjs', import.meta.url));
+  const result = await probeCezarTool(backend, wire, 'cezar_preview_serve', { command: `node "${fixture}" ${port}`, port, label: 'web' });
+  return JSON.stringify(result.response);
+}