@hearsay-tools/squawk 0.0.0-stage → 0.17.0-pr3058.5683

package/dist/worktree-setup.js

@@ -0,0 +1,170 @@
+import { fallbackProjectWriteError } from './project-paths.js';
+import { productEnvEntries } from './core/product-env.js';
+import { WORKTREE_SETUP_DEFAULT_TIMEOUT_SECONDS, worktreeSetupConfigSchema, } from './contract/index.js';
+import { buildCommandEnv } from './core/agent-env.js';
+import { runGroupedCommand } from './workflows/grouped-command.js';
+/**
+ * Judge the raw `worktreeSetup` value. Absent or `commands: []` is no setup, which keeps a
+ * project without the key exactly as it was. A value that does not parse is `invalid` with the
+ * first problem, so the run can say why it skipped setup.
+ */
+export function resolveWorktreeSetup(raw) {
+    if (raw === undefined)
+        return { kind: 'none' };
+    const parsed = worktreeSetupConfigSchema.safeParse(raw);
+    if (!parsed.success) {
+        const first = parsed.error.issues[0];
+        const path = first?.path.join('.') ?? '';
+        const message = first?.message ?? 'invalid value';
+        return { kind: 'invalid', issue: path ? `${path}: ${message}` : message };
+    }
+    if (parsed.data.commands.length === 0)
+        return { kind: 'none' };
+    return {
+        kind: 'commands',
+        commands: parsed.data.commands,
+        timeoutSeconds: parsed.data.timeoutSeconds ?? WORKTREE_SETUP_DEFAULT_TIMEOUT_SECONDS,
+    };
+}
+/** Output kept per command: the tail, because an install reports its error at the end. */
+const OUTPUT_CAP = 20_000;
+/** How much of a failed command's output the agent is shown. */
+const AGENT_OUTPUT_CHARS = 4_000;
+/** Commands are shortened to this many characters in notes. */
+const NOTE_COMMAND_CHARS = 120;
+const CONFIG_LABEL = 'worktreeSetup in .ai/cezar/config.json';
+const MISSING_HINT = 'Dependencies or generated files may be missing. Fix the cause or run the setup yourself before tests or builds.';
+export const WORKTREE_SETUP_STATUSES = ['done', 'failed', 'stopped', 'invalid'];
+/**
+ * Run the commands in order in `cwd`, stopping at the first one that fails, times out or cannot
+ * start, or when the run is cancelled. Never throws: every way it ends is an outcome.
+ */
+export async function runWorktreeSetup(opts) {
+    const { plan, cwd, env, setInterrupt, isCancelled, onCommandResult } = opts;
+    const refusal = fallbackProjectWriteError(cwd);
+    if (refusal)
+        return { status: 'invalid', issue: refusal };
+    const started = Date.now();
+    for (const [index, command] of plan.commands.entries()) {
+        if (isCancelled())
+            return { status: 'stopped', durationMs: Date.now() - started };
+        const commandStarted = Date.now();
+        const result = await runGroupedCommand({
+            command,
+            cwd,
+            env,
+            setInterrupt,
+            timeoutMs: plan.timeoutSeconds * 1000,
+            keep: 'tail',
+            cap: OUTPUT_CAP,
+        });
+        const commandResult = {
+            command,
+            exitCode: result.exitCode,
+            timedOut: result.timedOut,
+            durationMs: Date.now() - commandStarted,
+            output: result.output,
+            ...(result.spawnError !== undefined ? { spawnError: result.spawnError } : {}),
+        };
+        onCommandResult(commandResult);
+        if (isCancelled())
+            return { status: 'stopped', durationMs: Date.now() - started };
+        const reason = result.spawnError !== undefined ? 'spawn' : result.timedOut ? 'timeout' : result.exitCode !== 0 ? 'exit' : undefined;
+        if (reason) {
+            return {
+                status: 'failed',
+                reason,
+                failed: commandResult,
+                skipped: plan.commands.slice(index + 1),
+                timeoutSeconds: plan.timeoutSeconds,
+                durationMs: Date.now() - started,
+            };
+        }
+    }
+    return { status: 'done', commands: plan.commands, durationMs: Date.now() - started };
+}
+/**
+ * The environment setup commands run with: the curated host-command env the live preview gives a
+ * dev server (no backend auth, no `gh` token; `CEZ_ENV_PASSTHROUGH` still applies), the run's own
+ * temp directory, its task id, and the project root so a command can copy an untracked `.env`.
+ */
+export function worktreeSetupEnv(opts) {
+    return buildCommandEnv({
+        extraEnv: { ...opts.tmpEnv, ...productEnvEntries('TASK_ID', opts.runId, opts.rebrand), ...productEnvEntries('PROJECT_ROOT', opts.projectRoot, opts.rebrand) },
+        ...(opts.source ? { source: opts.source } : {}),
+    });
+}
+export function formatSetupDuration(ms) {
+    const seconds = Math.max(0, Math.round(ms / 1000));
+    if (seconds < 60)
+        return `${seconds}s`;
+    return `${Math.floor(seconds / 60)}m ${seconds % 60}s`;
+}
+function shortCommand(command) {
+    return command.length > NOTE_COMMAND_CHARS ? `${command.slice(0, NOTE_COMMAND_CHARS - 1)}…` : command;
+}
+const quoted = (command) => `\`${shortCommand(command)}\``;
+/** "`npm ci` exited 1 after 12s" — the shared phrase of the end note and the agent note. */
+function failurePhrase(outcome) {
+    const command = quoted(outcome.failed.command);
+    if (outcome.reason === 'timeout')
+        return `${command} timed out after ${outcome.timeoutSeconds}s`;
+    if (outcome.reason === 'spawn')
+        return `${command} could not start (${outcome.failed.spawnError ?? 'unknown error'})`;
+    return `${command} exited ${outcome.failed.exitCode} after ${formatSetupDuration(outcome.failed.durationMs)}`;
+}
+export function worktreeSetupStartNote(commandCount) {
+    return `preparing the worktree — ${commandCount} command${commandCount === 1 ? '' : 's'} from ${CONFIG_LABEL}`;
+}
+export function worktreeSetupEndNote(outcome) {
+    switch (outcome.status) {
+        case 'done': return `worktree setup done in ${formatSetupDuration(outcome.durationMs)}`;
+        case 'failed': return `worktree setup failed — ${failurePhrase(outcome)}; starting the agent anyway`;
+        case 'stopped': return 'worktree setup stopped';
+        case 'invalid': return `worktree setup skipped — ${CONFIG_LABEL} is invalid (${outcome.issue})`;
+    }
+}
+/** A fence longer than any backtick run in `text`, so command output cannot close it early. */
+function fenced(text) {
+    const longest = Math.max(0, ...[...text.matchAll(/`+/g)].map((match) => match[0].length));
+    const fence = '`'.repeat(Math.max(3, longest + 1));
+    return `${fence}text\n${text}\n${fence}`;
+}
+/**
+ * The paragraph appended to the agent's opening message. On success it stops the agent repeating
+ * the install a repo's own instructions ask for; on failure it carries what went wrong. A stopped
+ * setup has no agent to tell.
+ */
+export function worktreeSetupAgentNote(outcome) {
+    switch (outcome.status) {
+        case 'done':
+            return `Cezar prepared this worktree before your session started: ${outcome.commands.map(quoted).join(', ')} (${formatSetupDuration(outcome.durationMs)}). Dependencies are installed; do not repeat this setup.`;
+        case 'failed': {
+            const skipped = outcome.skipped.length
+                ? ` The remaining commands did not run: ${outcome.skipped.map(quoted).join(', ')}.`
+                : '';
+            return `Cezar's worktree setup did not complete before your session started: ${failurePhrase(outcome)}.${skipped}\n\nIts last output:\n\n${fenced(outcome.failed.output.slice(-AGENT_OUTPUT_CHARS))}\n\n${MISSING_HINT}`;
+        }
+        case 'invalid':
+            return `Cezar's worktree setup did not run: ${CONFIG_LABEL} is invalid (${outcome.issue}). ${MISSING_HINT}`;
+        case 'stopped':
+            return undefined;
+    }
+}
+/** The one-line `RunRecord.worktreeSetup.error`; undefined when setup succeeded. */
+export function worktreeSetupRecordError(outcome) {
+    switch (outcome.status) {
+        case 'done': return undefined;
+        case 'stopped': return 'stopped';
+        case 'invalid': return `invalid config: ${outcome.issue}`;
+        case 'failed': {
+            const command = quoted(outcome.failed.command);
+            if (outcome.reason === 'timeout')
+                return `${command} timed out after ${outcome.timeoutSeconds}s`;
+            if (outcome.reason === 'spawn')
+                return `${command} could not start: ${outcome.failed.spawnError ?? 'unknown error'}`;
+            return `${command} exited ${outcome.failed.exitCode}`;
+        }
+    }
+}
+//# sourceMappingURL=worktree-setup.js.map

package/dist/worktree-setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-setup.js","sourceRoot":"","sources":["../src/worktree-setup.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,82 @@
 {
   "name": "@hearsay-tools/squawk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.17.0-pr3058.5683",
+  "description": "Local cockpit for running and tracking AI agent tasks in your repo. Uses your logged-in `claude` CLI and `gh` — zero config, zero database.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "cezarion": "dist/index.js",
+    "cez": "dist/index.js",
+    "hsq": "dist/hsq.js"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./app-type": "./dist/server/app-type.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "web/dist",
+    "scripts",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=24.21.0"
+  },
+  "scripts": {
+    "prebuild": "node scripts/sync-readme.mjs",
+    "build": "tsc",
+    "check:pack": "node scripts/check-pack.mjs",
+    "dev": "tsx src/index.ts",
+    "install-as-command": "node scripts/install-as-command.mjs --mode link",
+    "install-as-command:global": "node scripts/install-as-command.mjs --mode global",
+    "uninstall-as-command": "node scripts/install-as-command.mjs --mode uninstall",
+    "bench:family-reconcile": "node --import tsx scripts/benchmark-family-reconcile.ts",
+    "bench:run-store": "node --import tsx scripts/benchmark-run-store.ts",
+    "bench:stuck-destroys": "node --import tsx scripts/benchmark-stuck-destroys.ts",
+    "bench:workspace-events": "node --import tsx scripts/benchmark-workspace-events.ts",
+    "server-install": "tsx src/index.ts server-install",
+    "server-deploy": "tsx src/index.ts server-deploy",
+    "server-uninstall": "tsx src/index.ts server-uninstall",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:unit": "node --import ../../scripts/test-home-env.mjs --import tsx --test test/unit/*.test.ts",
+    "test:package": "node ../../scripts/test-package.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.json && tsc --noEmit -p tsconfig.test.json && tsc --noEmit -p tsconfig.scripts.json",
+    "typecheck:package": "tsc --noEmit -p tsconfig.package.json",
+    "postbuild": "node scripts/inline-contract.mjs",
+    "bench:project-probes": "node --import tsx scripts/benchmark-project-probes.mjs"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "@hono/node-server": "^1.13.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "hono": "^4.6.0",
+    "smol-toml": "^1.7.0",
+    "ws": "^8.21.1",
+    "yaml": "^2.5.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@babel/parser": "^8.0.8",
+    "@babel/types": "^8.0.8",
+    "@open-mercato/cezar-api-client": "0.17.0-pr3058.5683",
+    "@open-mercato/cezar-contract": "0.17.0-pr3058.5683",
+    "@types/node": "^24.19.1",
+    "@types/ws": "^8.18.1",
+    "esbuild": "^0.28.1",
+    "fast-check": "^4.10.2",
+    "tsx": "^4.19.0",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hearsay-tools/cezarion",
+    "directory": "packages/cezar"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "gitHead": "0bded14ae96458d5e4935c8ca2d0b2c1979f1879"
+}

package/scripts/benchmark-family-reconcile.ts

@@ -0,0 +1,119 @@
+import { benchmarkHome, prepareBenchmarkEnv } from './benchmark-home.ts';
+import { setRunStatus } from '../src/runs/run-store.testkit.ts';
+/**
+ * Family reconcile benchmark (hearsay-tools/cezarion#2378): what one reconcile pass over a settled
+ * conversation root costs as its message count grows, with a fixed member count.
+ *
+ *   npm run bench:family-reconcile -w @wjarka/cezarion
+ *   node --import tsx packages/cezar/scripts/benchmark-family-reconcile.ts --messages 50,300,1000 --baseline
+ *
+ * Flags: --messages (50,300,1000) --workers (2) --pad-kb (64, bytes added to each record's task so
+ * a decode costs what a real record does) --samples (5) --baseline (run every pass without
+ * `withReadCache`, as before hearsay-tools/cezarion#2378).
+ *
+ * Method:
+ * - One process per run. For each size it seeds, through the public store API, a settled root
+ *   with --workers settled workers and a conversation of that many progress messages between the
+ *   root and its workers, then reopens the store so every member is a cold row.
+ * - It runs one pass first: that pass writes the projections a settled family still lacks. Each
+ *   sample then flushes (the written members leave memory) and times `reconcileWorkerWaits(root)`,
+ *   the pass recovery runs for each conversation root, with `performance.now()`.
+ * - "decodes" counts `JSON.parse` calls on a string longer than the pad, which only a record
+ *   decode makes here, during the last timed pass.
+ * - Linear in members means decodes stay at members + 0 as messages grow, and the pass time grows
+ *   with the bytes of the root's ledger only.
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { parseArgs } from 'node:util';
+import type { ConversationMessage } from '@open-mercato/cezar-contract';
+// This benchmark reads settled runs and starts no runner.
+import { noRunners } from '../src/core/runners-under-test.testkit.ts';
+
+process.env.HSQ_PROJECT_WARMUP = process.env.CEZ_PROJECT_WARMUP = '0';
+const ownHome = prepareBenchmarkEnv();
+
+const { values } = parseArgs({ options: {
+  messages: { type: 'string', default: '50,300,1000' },
+  workers: { type: 'string', default: '2' },
+  'pad-kb': { type: 'string', default: '64' },
+  samples: { type: 'string', default: '5' },
+  baseline: { type: 'boolean', default: false },
+} });
+const sizes = values.messages.split(',').map(Number);
+const workerCount = Number(values.workers), padBytes = Number(values['pad-kb']) * 1024, samples = Number(values.samples);
+if (sizes.some(size => !Number.isInteger(size) || size < 1) || !Number.isInteger(workerCount) || workerCount < 1 || !(samples > 0)) {
+  throw new Error('--messages takes whole numbers >= 1, --workers a whole number >= 1, --samples > 0');
+}
+
+const { RunStore } = await import('../src/runs/store.ts');
+const { RunManager } = await import('../src/workflows/run.ts');
+const home = benchmarkHome((await import('../src/home/resolve.ts')).resolveHome({ purpose: 'cli' }));
+
+const pad = 'x'.repeat(padBytes);
+let decodes = 0;
+const parse = JSON.parse;
+JSON.parse = ((text: string, reviver?: Parameters<typeof JSON.parse>[1]) => {
+  if (typeof text === 'string' && text.length > padBytes) decodes++;
+  return parse(text, reviver);
+}) as typeof JSON.parse;
+
+function seed(dataDir: string, root: string, messageCount: number) {
+  const store = RunStore.open(dataDir);
+  const parent = store.createRun({ title: 'root', task: pad, workflow: 'quick-task', steps: [] });
+  store.updateRun(parent.id, { delegation: { role: 'root', permissions: [], receipts: [] } });
+  const workers = Array.from({ length: workerCount }, () => {
+    const id = randomUUID();
+    const worker = store.createOwnedRun({ title: 'worker', task: pad, workflow: 'quick-task', steps: [] }, parent.id, randomUUID(), {
+      role: 'worker', parentRunId: parent.id, permissions: [], workspace: {
+        ownerRunId: id, resourceId: randomUUID(), kind: 'owned-isolated',
+        path: join(root, 'workers', id), branch: `cez/${id.slice(0, 8)}`, baselineSha: '0'.repeat(40),
+      },
+    }, 'a'.repeat(64));
+    setRunStatus(store, worker.id, 'done');
+    return worker.id;
+  });
+  setRunStatus(store, parent.id, 'done');
+  const messages: ConversationMessage[] = Array.from({ length: messageCount }, (_, i) => {
+    const worker = workers[i % workers.length]!;
+    const [senderRunId, recipientRunId] = i % 2 ? [worker, parent.id] : [parent.id, worker];
+    return { id: randomUUID(), senderRunId, recipientRunId, kind: 'progress', text: `progress ${i}`,
+      createdAt: new Date(Date.UTC(2026, 9, 1) + i).toISOString(), requestHash: 'b'.repeat(64), state: 'accepted' };
+  });
+  store.commitConversation(parent.id, { messages, outcomes: [] });
+  store.close();
+  return parent.id;
+}
+
+const median = (xs: number[]) => [...xs].sort((a, b) => a - b)[Math.floor(xs.length / 2)]!;
+const rows: string[] = [];
+for (const size of sizes) {
+  const root = mkdtempSync(join(tmpdir(), 'cez-bench-reconcile-'));
+  try {
+    const dataDir = join(root, '.ai/cezar');
+    const rootId = seed(dataDir, root, size);
+    const store = RunStore.open(dataDir, { keepLive: true });
+    if (values.baseline) store.withReadCache = <T>(fn: () => T): T => fn();
+    const manager = new RunManager(store, root, { home, createRunner: noRunners });
+    manager.reconcileWorkerWaits(rootId); // writes the missing projections once
+    const times: number[] = [];
+    for (let i = 0; i < samples; i++) {
+      store.flush();
+      decodes = 0;
+      const start = performance.now();
+      manager.reconcileWorkerWaits(rootId);
+      times.push(performance.now() - start);
+    }
+    rows.push(`| ${size} | ${workerCount + 1} | ${decodes} | ${median(times).toFixed(1)} |`);
+    manager.dispose();
+    store.close();
+  } finally { rmSync(root, { recursive: true, force: true }); }
+}
+JSON.parse = parse;
+if (ownHome) rmSync(ownHome, { recursive: true, force: true });
+console.log(`Family reconcile pass, ${values.baseline ? 'baseline (no read cache)' : 'withReadCache'}, ${values['pad-kb']} KB pad per record, median of ${samples}\n`);
+console.log('| Messages per root | Members | Decodes | Pass ms |\n|---|---|---|---|');
+for (const row of rows) console.log(row);

package/scripts/benchmark-home.ts

@@ -0,0 +1,32 @@
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { legacyHomeEnv, productEnvEntries } from '../src/core/product-env.ts';
+import { Home } from '../src/home/home.ts';
+import { readInstallMarker } from '../src/home/install-marker.ts';
+
+/** Benchmarks may retain an explicit home, but must never use a live installation. */
+export function benchmarkHome(home: Home): Home {
+  const roots = new Set([home.config, home.rootOverride ?? home.root]);
+  if ([...roots].some(root => readInstallMarker(root)?.kind === 'live')) throw new Error('Benchmark refuses a live install marker');
+  Home.sandbox(home.rootOverride ?? home.root, { layout: home.layout });
+  return home;
+}
+
+/** Sandbox controls must override both inherited product prefixes. */
+export function setBenchmarkEnv(env: NodeJS.ProcessEnv = process.env): void {
+  Object.assign(env, productEnvEntries('DRY_RUN', '1', true), productEnvEntries('AUTONAME', '0', true));
+}
+
+/** Retain an explicit legacy sandbox or allocate an isolated benchmark home. */
+export function prepareBenchmarkEnv(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  setBenchmarkEnv(env);
+  const existing = legacyHomeEnv(env);
+  if (existing) {
+    Object.assign(env, productEnvEntries('HOME', existing, true));
+    return undefined;
+  }
+  const ownHome = mkdtempSync(join(tmpdir(), 'cez-bench-home-'));
+  Object.assign(env, productEnvEntries('HOME', ownHome, true));
+  return ownHome;
+}

package/scripts/benchmark-project-probes.mjs

@@ -0,0 +1,158 @@
+/**
+ * Isolated project-list HTTP workload for hearsay-tools/cezarion#2733.
+ * Run unchanged on both refs: node --import tsx <script> --out <file.json>.
+ * The fixture server measures its own CPU; the HTTP client runs in its parent.
+ * Git CPU is reaped-child CPU from /proc/self/stat (Linux, CLK_TCK precision).
+ * No agents, run stores, or live cockpit are involved. Setup is excluded.
+ */
+import childProcess, { fork } from 'node:child_process';
+import { syncBuiltinESMExports } from 'node:module';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { createServer } from 'node:http';
+import { loadavg, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { performance } from 'node:perf_hooks';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { parseArgs, promisify } from 'node:util';
+import { benchmarkHome } from './benchmark-home.ts';
+
+const { values } = parseArgs({ options: {
+  out: { type: 'string' }, repeats: { type: 'string', default: '5' },
+  'fixture-server': { type: 'boolean' },
+} });
+
+async function serveFixture() {
+  const originalExec = childProcess.execFile;
+  let commands = {};
+  function count(args) {
+    if (args[0] !== 'git') return;
+    const key = args[1].join(' ');
+    commands[key] = (commands[key] ?? 0) + 1;
+  }
+  // execFile has a custom promisifier. Count it as well as callback calls.
+  // A bound proxy target permits replacing the non-configurable custom symbol.
+  childProcess.execFile = new Proxy(originalExec.bind(null), {
+    apply(target, thisArg, args) { count(args); return Reflect.apply(target, thisArg, args); },
+    get(target, key, receiver) {
+      const value = Reflect.get(originalExec, key, receiver);
+      if (key !== promisify.custom || typeof value !== 'function') return value;
+      return (...args) => { count(args); return Reflect.apply(value, target, args); };
+    },
+  });
+  syncBuiltinESMExports();
+  const { listProjects, clearProjectProbeCache } = await import('../src/workspace/projects.ts');
+  const { mergeWriteWorkspaceConfig } = await import('../src/workspace/config.ts');
+  const { resolveHome } = await import('../src/home/resolve.ts');
+  const home = benchmarkHome(resolveHome({ purpose: 'cli' }));
+  const hz = Number(childProcess.execFileSync('getconf', ['CLK_TCK'], { encoding: 'utf8' }).trim());
+  const gitCpuMs = () => {
+    const fields = readFileSync('/proc/self/stat', 'utf8').split(') ')[1].split(' ');
+    return (Number(fields[13]) + Number(fields[14])) * 1000 / hz;
+  };
+  const server = createServer((_request, response) => {
+    listProjects(undefined, home).then((projects) => {
+      response.setHeader('content-type', 'application/json'); response.end(JSON.stringify(projects));
+    }).catch((error) => { response.statusCode = 500; response.end(String(error)); });
+  });
+  await new Promise((done) => server.listen(0, '127.0.0.1', done));
+  const url = `http://127.0.0.1:${server.address().port}/projects`;
+  let cpu;
+  let childCpu;
+  async function handle(message) {
+    if (message.kind === 'configure') {
+      await mergeWriteWorkspaceConfig((config) => {
+        config.projects = message.roots.map((root, i) => ({
+          id: `project-${i}`, name: `Project ${i}`, root, source: 'local',
+          addedAt: '2026-11-06T00:00:00Z', lastOpenedAt: '2026-11-06T00:00:00Z',
+        }));
+      }, home);
+    }
+    if (message.kind === 'clear') clearProjectProbeCache();
+    if (message.kind === 'begin') { commands = {}; cpu = process.cpuUsage(); childCpu = gitCpuMs(); }
+    if (message.kind !== 'end') return { url };
+    const delta = process.cpuUsage(cpu);
+    return { commands, serverCpuMs: (delta.user + delta.system) / 1000, gitChildCpuMs: gitCpuMs() - childCpu };
+  }
+  process.on('message', (message) => {
+    handle(message).then((result) => process.send({ result })).catch((error) => process.send({ error: String(error) }));
+  });
+  const close = () => { server.closeAllConnections(); server.close(() => process.exit(0)); };
+  process.on('disconnect', close);
+  process.on('SIGTERM', close);
+}
+
+/** One sequential control message; HTTP requests use the fixture's loopback port. */
+function control(child, message) {
+  return new Promise((resolve, reject) => {
+    const cleanup = () => { child.off('message', received); child.off('exit', exited); child.off('error', failed); };
+    const received = (reply) => { cleanup(); if (reply.error) reject(new Error(reply.error)); else resolve(reply.result); };
+    const exited = (code) => { cleanup(); reject(new Error(`Fixture exited (${code})`)); };
+    const failed = (error) => { cleanup(); reject(error); };
+    child.once('message', received); child.once('exit', exited); child.once('error', failed);
+    child.send(message);
+  });
+}
+
+async function benchmark() {
+  const repeats = Number(values.repeats);
+  if (!Number.isInteger(repeats) || repeats < 1) throw new Error('--repeats must be positive');
+  const fixture = mkdtempSync(join(tmpdir(), 'cez-project-probes-'));
+  let child;
+  const rows = [];
+  const git = (root, ...args) => childProcess.execFileSync('git', args, {
+    cwd: root, stdio: 'ignore', env: { ...process.env, GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null' },
+  });
+  try {
+    const roots = [];
+    for (let i = 0; i < 40; i++) {
+      const root = join(fixture, `repo-${i}`); mkdirSync(root); roots.push(root);
+      git(root, 'init', '-q', '-b', 'main');
+      git(root, '-c', 'user.name=bench', '-c', 'user.email=bench@local', '-c', 'maintenance.auto=false', 'commit', '--allow-empty', '-qm', 'base');
+      git(root, 'remote', 'add', 'origin', 'https://github.com/fixture/project.git');
+    }
+    const plain = join(fixture, 'plain'); mkdirSync(plain);
+    child = fork(fileURLToPath(import.meta.url), ['--fixture-server'], {
+      env: { ...process.env, CEZ_HOME: join(fixture, 'home'), HSQ_HOME: join(fixture, 'home') }, stdio: ['ignore', 'ignore', 'inherit', 'ipc'],
+    });
+    for (let repeat = 0; repeat < repeats; repeat++) {
+      for (const count of [1, 10, 40]) {
+        const { url } = await control(child, { kind: 'configure', roots: [...roots.slice(0, count), plain, join(fixture, 'missing')] });
+        for (const concurrency of [1, 4, 16]) {
+          for (const phase of ['cold', 'warm', 'expired', 'concurrent']) {
+            if (phase === 'cold' || phase === 'concurrent') await control(child, { kind: 'clear' });
+            // Use real expiry; never change the product's five-second TTL.
+            if (phase === 'expired') await sleep(5001);
+            const loadBefore = loadavg();
+            await control(child, { kind: 'begin' });
+            const latencies = await Promise.all(Array.from({ length: concurrency }, async () => {
+              const start = performance.now();
+              const response = await fetch(url, { signal: AbortSignal.timeout(30_000) });
+              if (!response.ok) throw new Error(await response.text());
+              const projects = await response.json();
+              if (projects.at(-1)?.status !== 'missing' || projects.at(-2)?.status !== 'not-git') throw new Error('Incorrect project status');
+              return performance.now() - start;
+            }));
+            const metrics = await control(child, { kind: 'end' });
+            latencies.sort((a, b) => a - b);
+            const percentile = (p) => latencies[Math.ceil(p * latencies.length) - 1];
+            rows.push({ repeat, repos: count, concurrency, phase, ...metrics,
+              requests: latencies.length, p50Ms: percentile(.5), p95Ms: percentile(.95), maxMs: latencies.at(-1),
+              loadBefore, loadAfter: loadavg() });
+          }
+        }
+      }
+    }
+    const result = { node: process.version, platform: process.platform,
+      cpus: readFileSync('/proc/self/status', 'utf8').match(/^Cpus_allowed_list:\s*(.*)$/m)?.[1], rows };
+    const json = JSON.stringify(result, null, 2) + '\n';
+    if (values.out) writeFileSync(values.out, json); else process.stdout.write(json);
+  } finally {
+    if (child && child.exitCode === null && child.signalCode === null) {
+      await new Promise((done) => { child.once('exit', done); child.kill('SIGTERM'); });
+    }
+    rmSync(fixture, { recursive: true, force: true });
+  }
+}
+
+if (values['fixture-server']) await serveFixture(); else await benchmark();