@wjarka/cezarion 0.16.0 → 0.17.0

package/scripts/mock-cursor-print.mjs

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+// Load only when configured: ordinary mock turns retain their event-loop ordering.
+const failureControl = process.env.CEZ_MOCK_FAILURE_CONTROL === undefined ? undefined
+  : (await import('./mock-failure-control.mjs')).readFailureControl();
+// Print acknowledges an input on its first model work and cannot refuse one, so a held
+// acknowledgement and a held response both hold that first model work.
+const delivery = process.env.CEZ_MOCK_DELIVERY_CONTROL === undefined ? undefined
+  : (await import('./mock-delivery-control.mjs')).readDeliveryControl(['hold-ack', 'hold-response']);
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+// Publish a pid atomically (temporary sibling, then rename): a test reading it sees no
+// file or a whole pid, never the empty file whose Number() is 0 (hearsay-tools/cezarion#953).
+function watchdogWritePid(file, pid) { const tmp = `${file}.${process.pid}.tmp`; writeFileSync(tmp, pid); renameSync(tmp, file); }
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+// Dynamic, like every sibling import here, so a test's copy of this mock can repoint it.
+const { answerNudge, NO_WAIT_NUDGE_PREFIX } = await import('./mock-nudge.mjs');
+import { randomUUID } from 'node:crypto';
+
+const args = process.argv.slice(2);
+if (args.includes('--version')) { process.stdout.write('2026.10.01-e373342\n'); process.exit(0); }
+if (args.includes('__cezar_probe_invalid__')) {
+  process.stderr.write('Invalid --allowed-tools value(s): __cezar_probe_invalid__. Expected one of: '+
+    'shell_tool_call, delete_tool_call, glob_tool_call, grep_tool_call, read_tool_call, update_todos_tool_call, read_todos_tool_call, edit_tool_call, ls_tool_call, read_lints_tool_call, mcp_tool_call, sem_search_tool_call, create_plan_tool_call, web_search_tool_call, list_mcp_resources_tool_call, read_mcp_resource_tool_call, apply_agent_diff_tool_call, ask_question_tool_call, fetch_tool_call, switch_mode_tool_call, generate_image_tool_call, record_screen_tool_call, computer_use_tool_call, write_shell_stdin_tool_call, reflect_tool_call, setup_vm_environment_tool_call, truncated_tool_call, web_fetch_tool_call, report_bugfix_results_tool_call, ai_attribution_tool_call, pr_management_tool_call, mcp_auth_tool_call, await_tool_call, blame_by_file_path_tool_call, get_mcp_tools_tool_call, report_bug_tool_call, set_active_branch_tool_call, communicate_update_tool_call, send_final_summary_tool_call, update_pr_code_tour_tool_call, replace_env_tool_call, edit_pr_labels_tool_call, record_ci_investigation_findings_tool_call, fetch_cloud_agent_data_tool_call, send_to_user_tool_call, pi_read_tool_call, pi_bash_tool_call, pi_edit_tool_call, pi_write_tool_call, pi_grep_tool_call, pi_find_tool_call, pi_ls_tool_call, connect_scm_tool_call, search_conversations_tool_call, create_goal_tool_call, update_goal_tool_call, get_pr_code_tour_tool_call, write_canvas_tool_call, read_canvas_tool_call, task_tool_call, create_agent_tool_call, adopt_tool_call, send_to_agent_tool_call, send_message_tool_call, get_agent_status_tool_call, stop_agent_tool_call, read_agent_transcript_tool_call, start_grind_execution_tool_call, start_grind_planning_tool_call\n');
+  process.exit(1);
+}
+const flag = name => { const at = args.indexOf(name); return at < 0 ? undefined : args[at + 1]; };
+const resumeId = flag('--resume');
+const mode = process.env.CEZ_MOCK_CURSOR_PRINT_MODE ?? 'normal';
+const turn = resumeId ? 2 : 1;
+// Cursor accepts a print prompt on stdin. Preserve the positional form so a
+// regression back to argv delivery is visible to the runner tests.
+const valueFlags = new Set(['--output-format', '--model', '--resume', '--allowed-tools',
+  '--add-dir', '--plugin-dir', '--image']);
+let positionalPrompt = '';
+for (let i = 0; i < args.length; i++) {
+  if (valueFlags.has(args[i])) { i++; continue; }
+  if (!args[i].startsWith('-')) positionalPrompt = args[i];
+}
+const stdinChunks = [];
+if (!positionalPrompt) for await (const chunk of process.stdin) stdinChunks.push(chunk);
+const stdinPrompt = Buffer.concat(stdinChunks).toString('utf8');
+const promptArg = stdinPrompt || positionalPrompt;
+const promptBoundary = promptArg.lastIndexOf('\n\n---\n\n');
+const rawPrompt = promptBoundary < 0 ? promptArg : promptArg.slice(promptBoundary + '\n\n---\n\n'.length);
+const taggedScenarios = [
+  ['resume-done', 'a0000001'], ['autonomous-ask-cap', 'a0000002'],
+  ['autonomous-cap', 'a0000003'], ['silent-tail-late-turn-start', 'a0000004'],
+  ['silent-tail-no-reply', 'a0000005'], ['silent-tail-late-reply', 'a0000006'],
+  ['silent-tail-slow-done', 'a0000007'], ['silent-tail-again', 'a0000008'],
+  ['silent-tail', 'a0000009'], ['tool-tail', 'a000000a'],
+];
+const freshTag = taggedScenarios.find(([name]) => rawPrompt.includes(`mock:${name}`))?.[1];
+const id = resumeId && mode !== 'mismatch-on-resume' ? resumeId
+  : (freshTag ? freshTag + randomUUID().slice(8) : randomUUID());
+const stateFile = join(process.cwd(), '.ai', 'cezar', 'mock-cursor-print', `${id}.json`);
+let origin = taggedScenarios.find(([, tag]) => resumeId?.startsWith(tag))?.[0];
+if (resumeId && existsSync(stateFile)) {
+  try { origin = JSON.parse(readFileSync(stateFile, 'utf8')).origin ?? origin; } catch { /* isolated mock state */ }
+}
+if (freshTag) {
+  origin = taggedScenarios.find(([, tag]) => tag === freshTag)?.[0];
+  mkdirSync(join(process.cwd(), '.ai', 'cezar', 'mock-cursor-print'), { recursive: true });
+  writeFileSync(stateFile, JSON.stringify({ origin }));
+}
+// One process per turn: the session's opening scenario comes from its tag, not a latch.
+const silentOrigin = /^(silent-tail|tool-tail)/.test(origin ?? '');
+const prompt = silentOrigin ? rawPrompt : answerNudge(rawPrompt);
+const frame = value => process.stdout.write(`${JSON.stringify(value)}\n`);
+const assistant = text => frame({ type: 'assistant', session_id: id,
+  message: { role: 'assistant', content: [{ type: 'text', text }] } });
+const result = (text, error = false) => frame({ type: 'result', subtype: error ? 'error_during_execution' : 'success',
+  session_id: id, is_error: error, result: text });
+const readTool = (content = 'A project') => {
+  const call = { readToolCall: { args: { path: 'README.md' } } };
+  frame({ type: 'tool_call', subtype: 'started', call_id: 'read-1', session_id: id, tool_call: call });
+  frame({ type: 'tool_call', subtype: 'completed', call_id: 'read-1', session_id: id,
+    tool_call: { readToolCall: { ...call.readToolCall, result: { success: { content } } } } });
+};
+const waitForRelease = async (fallbackMs) => {
+  const file = process.env.CEZ_MOCK_RELEASE_FILE;
+  if (!file) { await new Promise(resolve => setTimeout(resolve, fallbackMs)); return; }
+  const deadline = Date.now() + 15_000;
+  while (!existsSync(file)) {
+    if (Date.now() > deadline) throw new Error('CEZ_MOCK_RELEASE_FILE was not created');
+    await new Promise(resolve => setTimeout(resolve, 10));
+  }
+};
+const finish = (text) => { assistant(text); result(text); };
+const log = process.env.CEZ_MOCK_CURSOR_PRINT_LOG;
+if (log) appendFileSync(log, `${JSON.stringify({ pid: process.pid, resumeId, id, args,
+  promptSource: stdinPrompt ? 'stdin' : 'argv', prompt: promptArg })}\n`);
+if (process.env.CEZ_MOCK_ARGS_FILE) {
+  appendFileSync(process.env.CEZ_MOCK_ARGS_FILE, `${JSON.stringify(args)}\n`);
+  const pluginDir = flag('--plugin-dir');
+  if (pluginDir) appendFileSync(process.env.CEZ_MOCK_ARGS_FILE,
+    `${JSON.stringify({ type: 'cursor-print-plugin', ...JSON.parse(readFileSync(`${pluginDir}/mcp.json`, 'utf8')) })}\n`);
+}
+if (process.env.CEZ_MOCK_STDIN_FILE && stdinPrompt) {
+  appendFileSync(process.env.CEZ_MOCK_STDIN_FILE,
+    `${JSON.stringify({ method: 'cursor-print/stdin', prompt: stdinPrompt })}\n`);
+}
+if (mode === 'delay-init') await new Promise(resolve => setTimeout(resolve, 10_000));
+// Reproduce a loaded host's per-process startup cost on every turn: Cursor print
+// spawns one process per turn, so a cap row pays it MAX_AUTO_CONTINUES + 1 times
+// (hearsay-tools/cezarion#1125).
+const spawnDelayMs = Number.parseInt(process.env.CEZ_MOCK_CURSOR_SPAWN_DELAY_MS ?? '0', 10) || 0;
+if (spawnDelayMs > 0) await new Promise(resolve => setTimeout(resolve, spawnDelayMs));
+const attempt = log ? readFileSync(log, 'utf8').trim().split('\n').length : 1;
+const rejectModel = () => process.stderr.write(`Cannot use this model: ${flag('--model')}. Available models: ${'other-model, '.repeat(1000)}\n`);
+if (mode === 'model-rejection-always' || (mode === 'model-rejection-once' && attempt === 1) ||
+  (mode === 'model-rejection-on-resume' && resumeId && attempt === 2)) {
+  rejectModel(); process.exit(1);
+}
+if (mode === 'model-rejection-held') {
+  rejectModel(); await waitForRelease(10_000); process.exit(1);
+}
+if (mode === 'unrelated-startup-error') { process.stderr.write('Account unavailable\n'); process.exit(1); }
+// hearsay-tools/cezarion#1112: a slow process start, before the init frame that opens the native turn.
+if (prompt.includes('mock:deferred-turn-start')) await (await import('./mock-deferred-turn-start.mjs')).deferredTurnStart();
+frame({ type: 'system', subtype: 'init', session_id: id, model: flag('--model') ?? 'auto', cwd: process.cwd() });
+if (delivery) {
+  await new Promise(resolve => delivery.ack(prompt, resolve));
+  await delivery.holdResponse(prompt);
+}
+if (mode === 'model-rejection-after-init' || mode === 'model-rejection-after-work') {
+  if (mode === 'model-rejection-after-work') assistant('Work already began');
+  rejectModel(); process.exit(1);
+}
+if (mode === 'no-result') process.exit(0);
+if (mode === 'portable-ask' && !resumeId) {
+  const ask = 'CEZ:ASK {"questions":[{"header":"Library","question":"Which library?","multiSelect":false,"options":[{"label":"Vitest","description":"Use Vitest"},{"label":"Jest","description":"Use Jest"}]}]}';
+  frame({ type: 'assistant', session_id: id, message: { role: 'assistant', content: [{ type: 'text', text: `Choose one.\n${ask}` }] } });
+  frame({ type: 'result', subtype: 'success', session_id: id, is_error: false, result: `Choose one.\n${ask}` });
+  process.exit(0);
+}
+if (mode === 'native-question') {
+  const args = { title: 'Choice', questions: [{ prompt: 'Choose', options: [{ label: 'Alpha' }, { label: 'Beta' }], allowMultiple: false }], runAsync: false };
+  const call = { askQuestionToolCall: { args } };
+  frame({ type: 'tool_call', subtype: 'started', call_id: 'question-1', session_id: id, tool_call: call });
+  frame({ type: 'tool_call', subtype: 'completed', call_id: 'question-1', session_id: id,
+    tool_call: { askQuestionToolCall: { args, result: { rejected: { reason: 'Questions skipped by the user, continue with the information you already have' } } } } });
+  finish('I could not ask the question.'); process.exit(0);
+}
+const selectedFailure = failureControl?.failureFor(prompt);
+const nativeFailure = selectedFailure instanceof Promise ? await selectedFailure : selectedFailure;
+if (failureControl ? nativeFailure === 'provider' : mode === 'provider-error') {
+  result('RetriableError: provider unavailable', true);
+  process.exit(0);
+}
+if (prompt.includes('mock:crash-stderr')) {
+  const { crashWithStderr } = await import('./mock-runner-crash.mjs');
+  crashWithStderr(prompt, '{"type":"assistant",');
+}
+if (prompt.includes('mock:autonomous') || prompt.startsWith('Continue working autonomously until the task is fully complete.')) {
+  const { autonomousReply } = await import('./mock-autonomous.mjs');
+  if (origin === 'autonomous-ask-cap' && resumeId && prompt.startsWith('Continue working autonomously until the task is fully complete.')) {
+    finish('Still working.'); process.exit(0);
+  }
+  const tagged = origin?.startsWith('autonomous') ? `${prompt} mock:${origin}` : prompt;
+  finish(autonomousReply(tagged)); process.exit(0);
+}
+if (prompt.includes('mock:silent-tail') || prompt.includes('mock:tool-tail') ||
+    (silentOrigin && prompt.includes(NO_WAIT_NUDGE_PREFIX))) {
+  const silent = await import('./mock-silent-tail.mjs');
+  if (silentOrigin && prompt.includes(NO_WAIT_NUDGE_PREFIX)) {
+    if (origin === 'silent-tail-no-reply') { setInterval(() => {}, 1000); await new Promise(() => {}); }
+    if (origin === 'silent-tail-late-reply') await new Promise(resolve => setTimeout(resolve, silent.LATE_REPLY_MS));
+    if (origin === 'silent-tail-slow-done') {
+      assistant(silent.SLOW_DONE_PREFIX);
+      // F10 can hold DONE while its test advances the reply clock; the default stays 400 ms.
+      await waitForRelease(silent.SLOW_DONE_TAIL_MS);
+    }
+    if (origin === 'silent-tail-again') { result(''); process.exit(0); }
+    finish(origin === 'tool-tail' ? silent.FINAL_MESSAGE_STANDING : silent.SILENT_TAIL_DONE);
+    process.exit(0);
+  }
+  assistant(prompt.includes('mock:tool-tail') ? silent.TOOL_TAIL_OPENING : silent.SILENT_TAIL_OPENING);
+  readTool(origin === 'silent-tail-again' ? silent.SILENT_TAIL_REASONING : 'A project'); result(''); process.exit(0);
+}
+if (origin === 'resume-done' && resumeId) { finish('Resumed work finished.\nCEZ:DONE'); process.exit(0); }
+if (prompt.includes('mock:cezar-tool')) {
+  const { toolPrompt } = await import('./mock-ci-tool.mjs');
+  finish(await toolPrompt('cursor', args, prompt)); process.exit(0);
+}
+if (prompt.includes('mock:ci-wait') || process.env.CEZ_MOCK_CI_PR) {
+  const { ciPrompt, probeCiTool } = await import('./mock-ci-tool.mjs');
+  const response = prompt.includes('mock:ci-wait') ? await ciPrompt('cursor', args, prompt)
+    : JSON.stringify((await probeCiTool('cursor', args)).response);
+  finish(response); process.exit(0);
+}
+if (prompt.includes('mock:no-progress')) {
+  if (prompt.includes('ignore-term')) process.on('SIGTERM', () => {});
+  if (prompt.includes('held-pipe')) spawn(process.execPath, ['-e', 'setTimeout(() => {}, 5000)'],
+    { stdio: ['ignore', process.stdout, process.stderr] });
+  if (prompt.includes('leftover')) {
+    const leftover = (file) => `process.on('SIGTERM',()=>{}); const fs = require('fs'); fs.writeFileSync(${JSON.stringify(`${file}.tmp`)}, String(process.pid)); fs.renameSync(${JSON.stringify(`${file}.tmp`)}, ${JSON.stringify(file)}); setTimeout(()=>{},20000)`;
+    spawn(process.execPath, ['-e', leftover('leftover-group.pid')], { stdio: 'ignore' });
+    spawn(process.execPath, ['-e', leftover('leftover-session.pid')], { stdio: 'ignore', detached: true }).unref();
+  }
+  // Publish readiness after mode setup: another process may signal us as soon as it sees it.
+  watchdogWritePid('watchdog.pid', String(process.pid));
+  setInterval(() => {}, 1000);
+  await new Promise(() => {});
+}
+if (prompt.includes('mock:busy-progress')) {
+  // N2: a long turn whose native output keeps it alive, then a done (hearsay-tools/cezarion#1620).
+  for (let i = 0; i < 24; i++) { assistant('working\n'); await new Promise(resolve => setTimeout(resolve, 100)); }
+  finish('busy complete\n\nCEZ:DONE'); process.exit(0);
+}
+if (prompt.includes('mock:hold-done')) { await waitForRelease(400); finish('parity hold-done: content after the pause\nCEZ:DONE'); process.exit(0); }
+if (prompt.includes('mock:hold-ask')) { await waitForRelease(400); finish('Pick one.\n\nCEZ:ASK {"questions":[{"header":"Library","question":"Which test library?","options":[{"label":"Vitest"},{"label":"Node test"}]}]}'); process.exit(0); }
+if (prompt.includes('mock:hold-gated')) { await waitForRelease(500); finish('parity hold-gated: content after the pause'); process.exit(0); }
+if (prompt.includes('mock:multi-pr-refs')) {
+  const { multiPrText, unrelatedPr } = await import('./mock-multi-pr.mjs');
+  readTool(unrelatedPr);
+  const text = multiPrText(prompt);
+  for (const block of text.split('\n')) assistant(block + '\n');
+  result(text); process.exit(0);
+}
+if (prompt.includes('mock:turn-messages:')) {
+  const { turnMessages } = await import('./mock-turn-messages.mjs');
+  for (const message of turnMessages(prompt)) assistant(message + '\n');
+  result(''); process.exit(0);
+}
+if (prompt.includes('mock:ask-snapshot')) {
+  finish(prompt.includes('mock:ask-snapshot-bad') ? 'CEZ:ASK {not valid json'
+    : 'Using the CEZ:ASK structured question format instead:\n\nCEZ:ASK {"questions":[{"header":"Library","question":"Which test library?","options":[{"label":"Vitest"},{"label":"Node test"}]}]}');
+  process.exit(0);
+}
+if (prompt.includes('mock:ask-prose')) { finish('Use `CEZ:ASK {"questions":[]}` in your reply.\n> CEZ:ASK {not valid json'); process.exit(0); }
+if (prompt.includes('mock:ask-bad')) { finish('Malformed question skipped.'); process.exit(0); }
+if (!failureControl && prompt.includes('mock:provider-error')) { result('RetriableError: provider unavailable', true); process.exit(0); }
+if (prompt.includes('mock:split-text')) {
+  const text = 'parity split text\nCEZ:MONITORING'; assistant(text); result(text); process.exit(0);
+}
+if (prompt.includes('mock:done') || (resumeId && /Library:|Tests:|Plan:/.test(prompt))) {
+  const text = 'Done.\nCEZ:DONE'; assistant(text); result(text); process.exit(0);
+}
+if (prompt.includes('mock:ask') && (!resumeId || prompt.includes('mock:ask-reply-late'))) {
+  const text = 'Pick one.\n\nCEZ:ASK {"questions":[{"header":"Library","question":"Which test library?","options":[{"label":"Vitest"},{"label":"Node test"}]}]}';
+  assistant(text); result(text); process.exit(0);
+}
+if (prompt.includes('mock:hold')) await new Promise(resolve => setTimeout(resolve, 500));
+if (prompt === 'inspect the working tree' || prompt.includes('mock:baseline')) {
+  readTool(); const text = 'Cursor inspected the workspace.'; assistant(text); result(text); process.exit(0);
+}
+if (prompt.includes('mock:agent-echo')) { finish(prompt); process.exit(0); }
+const text = `turn ${turn}: ${prompt}`;
+if (mode === 'delay-work' && resumeId) await new Promise(resolve => setTimeout(resolve, 200));
+assistant(text);
+if (mode === 'crash-after-work') process.exit(1);
+result(text);
+if (mode === 'duplicate-result') frame({ type: 'result', subtype: 'success', session_id: id, is_error: false, result: text });
+if (mode === 'late-frame') frame({ type: 'assistant', session_id: id,
+  message: { role: 'assistant', content: [{ type: 'text', text: 'LATE_FRAME' }] } });
+if (mode === 'result-before-exit') await new Promise(resolve => setTimeout(resolve, 250));

package/scripts/mock-deferred-turn-start.mjs

@@ -0,0 +1,16 @@
+/**
+ * hearsay-tools/cezarion#1112: a follow-up whose native turn starts late. A mock that sees
+ * the token in a follow-up holds that turn's native start past the 250 ms held-input
+ * recheck (HELD_HUMAN_INPUT_RECHECK_MS in workflows/run.ts), the window a loaded host
+ * opened between a Cursor print process spawning and its init frame.
+ *
+ * Callers test for the token inline before a dynamic import, so a mock without it keeps
+ * its exact event-loop ordering (an unconditional `await` would yield on every turn), and
+ * a testkit that copies a mock elsewhere and rewrites `import('./` still resolves it.
+ */
+export const DEFERRED_TURN_START_TOKEN = 'mock:deferred-turn-start';
+export const DEFERRED_TURN_START_MS = 800;
+
+export function deferredTurnStart() {
+  return new Promise(resolve => setTimeout(resolve, DEFERRED_TURN_START_MS));
+}

package/scripts/mock-delivery-control.d.mts

@@ -0,0 +1,23 @@
+export type DeliveryControlOptions =
+  | { kind: 'reject'; match: string; persistent?: boolean }
+  | { kind: 'hold-ack'; match: string }
+  | { kind: 'hold-response'; match: string };
+export type DeliveryKind = DeliveryControlOptions['kind'];
+export function createDeliveryControl(root: string, options: DeliveryControlOptions): {
+  path: string;
+  held(): boolean;
+  release(): void;
+  lift(): void;
+};
+/** Throws on a malformed control. A kind outside `supportedKinds` makes the mock exit with
+ *  an error naming the variable when an input matches, before it answers that input. */
+export function readDeliveryControl(supportedKinds: readonly DeliveryKind[]): {
+  kind: DeliveryKind;
+  /** True when this input must be rejected now; a non-persistent rule claims once across processes. */
+  rejects(text: string): boolean;
+  /** Sends the acknowledgement now, or after release for a matching hold-ack, without blocking the caller. */
+  ack(text: string, send: () => void): void;
+  /** Undefined when nothing is held; for a matching hold-response, a promise that resolves on release.
+   *  A synchronous answer lets a mock that cannot await decide at once whether to buffer. */
+  holdResponse(text: string): Promise<void> | undefined;
+};

package/scripts/mock-delivery-control.mjs

@@ -0,0 +1,80 @@
+// Native delivery controls belong to the mock, not to source-rewriting test helpers.
+// Only configured mocks import this module, so an unconfigured mock keeps its exact
+// event-loop order. The control changes timing only: what a turn says still follows
+// its input, and each mock writes its own native rejection and acknowledgement.
+import { closeSync, existsSync, openSync, readFileSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+
+const ENV = 'CEZ_MOCK_DELIVERY_CONTROL';
+const KINDS = ['reject', 'hold-ack', 'hold-response'];
+
+function validate(config) {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) throw new Error('expected a control object');
+  const keys = config.kind === 'reject' ? ['kind', 'match', 'persistent'] : ['kind', 'match'];
+  if (KINDS.includes(config.kind) && typeof config.match === 'string' && config.match.trim()
+    && (config.persistent === undefined || typeof config.persistent === 'boolean')
+    && Object.keys(config).every(key => keys.includes(key))) return config;
+  throw new Error('expected reject (optionally persistent), hold-ack or hold-response with a nonempty match');
+}
+
+/** Fixture setup and handles use the same marker paths as the mock reader. The
+ * fixture owns cleanup; none of this state depends on a native subprocess cwd. */
+export function createDeliveryControl(root, options) {
+  const path = join(resolve(root), 'native-delivery-control.json');
+  writeFileSync(path, JSON.stringify(validate(options)));
+  return {
+    path,
+    held: () => existsSync(`${path}.held`),
+    release: () => writeFileSync(`${path}.released`, ''),
+    lift: () => writeFileSync(`${path}.lifted`, ''),
+  };
+}
+
+/** Read once at mock startup. A configured but broken fixture must never fall
+ * through to an ordinary native turn. Absence is handled by each mock before
+ * importing, so its ordinary scheduling stays unchanged. */
+export function readDeliveryControl(supportedKinds) {
+  const path = process.env[ENV];
+  let config;
+  try {
+    if (!path || !isAbsolute(path)) throw new Error('expected an absolute control path');
+    config = validate(JSON.parse(readFileSync(path, 'utf8')));
+  } catch (error) {
+    throw new Error(`${ENV}: ${error.message}`, { cause: error });
+  }
+  // The variable reaches every mock a fixture starts, so a mixed-runner fixture (a Claude
+  // worker under an OMP parent) sees a kind its own wire cannot carry. Such a mock runs
+  // unconfigured until an input matches; then it fails closed before it answers.
+  const supported = supportedKinds.includes(config.kind);
+  const matches = (kind, text) => {
+    if (typeof text !== 'string' || !text.includes(config.match)) return false;
+    if (!supported) {
+      process.stderr.write(`${ENV}: this native mock does not support ${config.kind}\n`);
+      process.exit(1);
+    }
+    return config.kind === kind;
+  };
+  const released = () => existsSync(`${path}.released`);
+  return {
+    kind: config.kind,
+    rejects(text) {
+      if (!matches('reject', text) || existsSync(`${path}.lifted`)) return false;
+      if (config.persistent) return true;
+      // More than one matching input can arrive in a fixture. Exactly one claims
+      // the rejection, including when the inputs reach different subprocesses.
+      try { closeSync(openSync(`${path}.rejected`, 'wx')); }
+      catch (error) { if (error.code === 'EEXIST') return false; throw error; }
+      return true;
+    },
+    ack(text, send) {
+      if (!matches('hold-ack', text) || released()) { send(); return; }
+      writeFileSync(`${path}.held`, '');
+      const timer = setInterval(() => { if (released()) { clearInterval(timer); send(); } }, 5);
+    },
+    holdResponse(text) {
+      if (!matches('hold-response', text) || released()) return undefined;
+      writeFileSync(`${path}.held`, '');
+      return (async () => { while (!released()) await new Promise(resolve => setTimeout(resolve, 5)); })();
+    },
+  };
+}

package/scripts/mock-env-record.mjs

@@ -0,0 +1,11 @@
+// hearsay-tools/cezarion#784: harness parity reads which per-session variables reached each runner's
+// native process, the one the agent's Bash and agent-browser inherit. A test preloads it into every
+// mock with NODE_OPTIONS=--import=<this file's URL> and sets CEZ_MOCK_ENV_RECORD (the file to write)
+// and CEZ_MOCK_ENV_RECORD_NAMES (comma-separated names).
+import { writeFileSync } from 'node:fs';
+
+const path = process.env.CEZ_MOCK_ENV_RECORD;
+if (path) {
+  const names = (process.env.CEZ_MOCK_ENV_RECORD_NAMES ?? '').split(',').filter(Boolean);
+  writeFileSync(path, JSON.stringify(Object.fromEntries(names.map(name => [name, process.env[name] ?? null]))));
+}

package/scripts/mock-failure-control.d.mts

@@ -0,0 +1,13 @@
+export type NativeFailure = 'provider' | 'usage-limit' | 'unread';
+export type FailureControlOptions = { mode: 'gated-once' }
+  | { mode: 'persistent'; opening: string; failure: NativeFailure };
+export function createFailureControl(root: string, options: FailureControlOptions): {
+  path: string;
+  held(): boolean;
+  release(): void;
+  lift(): void;
+};
+export function readFailureControl(supportedFailures?: readonly NativeFailure[]): {
+  failure: NativeFailure;
+  failureFor(text: string): NativeFailure | undefined | Promise<NativeFailure | undefined>;
+};

package/scripts/mock-failure-control.mjs

@@ -0,0 +1,68 @@
+// Native failure controls belong to the mock, not to source-rewriting test helpers.
+// Only configured mocks import this module. Persistent decisions are synchronous:
+// in particular, Claude's unread exit must not yield to another stdin line.
+import { closeSync, existsSync, openSync, readFileSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+
+const ENV = 'CEZ_MOCK_FAILURE_CONTROL';
+const GATED_PROMPTS = ['mock:auth-error', 'mock:provider-error', 'Resume to receive the queued CI observation.'];
+const FAILURES = ['provider', 'usage-limit', 'unread'];
+
+function validate(config) {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) throw new Error('expected a control object');
+  if (config.mode === 'gated-once' && Object.keys(config).every(key => key === 'mode')) return config;
+  if (config.mode === 'persistent' && typeof config.opening === 'string' && config.opening.trim()
+    && FAILURES.includes(config.failure) && Object.keys(config).every(key => ['mode', 'opening', 'failure'].includes(key))) return config;
+  throw new Error('expected gated-once, or persistent with a nonempty opening and provider/usage-limit/unread failure');
+}
+
+/** Fixture setup and handles use the same marker paths as the mock reader. The
+ * fixture owns cleanup; none of this state depends on a native subprocess cwd. */
+export function createFailureControl(root, options) {
+  const path = join(resolve(root), 'native-failure-control.json');
+  writeFileSync(path, JSON.stringify(validate(options)));
+  return {
+    path,
+    held: () => existsSync(`${path}.held`),
+    release: () => writeFileSync(`${path}.released`, ''),
+    lift: () => writeFileSync(`${path}.lifted`, ''),
+  };
+}
+
+/** Read once at mock startup. A configured but broken fixture must never fall
+ * through to a successful native turn. Absence is handled by each mock before
+ * importing, so its ordinary scheduling stays unchanged. */
+export function readFailureControl(supportedFailures = ['provider']) {
+  const path = process.env[ENV];
+  let config;
+  try {
+    if (!path || !isAbsolute(path)) throw new Error('expected an absolute control path');
+    config = validate(JSON.parse(readFileSync(path, 'utf8')));
+    const failure = config.mode === 'gated-once' ? 'provider' : config.failure;
+    if (!supportedFailures.includes(failure)) throw new Error(`this native mock does not support ${failure}`);
+  } catch (error) {
+    throw new Error(`${ENV}: ${error.message}`, { cause: error });
+  }
+  const failure = config.mode === 'gated-once' ? 'provider' : config.failure;
+  return {
+    failure,
+    failureFor(text) {
+      if (typeof text !== 'string') return undefined;
+      if (config.mode === 'persistent') {
+        return text.includes(config.opening) && !existsSync(`${path}.lifted`) ? failure : undefined;
+      }
+      if (existsSync(`${path}.failed`) || !GATED_PROMPTS.some(prompt => text.includes(prompt))) return undefined;
+      return gatedFailure();
+    },
+  };
+
+  async function gatedFailure() {
+    writeFileSync(`${path}.held`, '');
+    while (!existsSync(`${path}.released`)) await new Promise(resolve => setTimeout(resolve, 5));
+    // More than one matching run can be held in a fixture. Exactly one claims
+    // the failure, including when the runs belong to different subprocesses.
+    try { closeSync(openSync(`${path}.failed`, 'wx')); }
+    catch (error) { if (error.code === 'EEXIST') return undefined; throw error; }
+    return failure;
+  }
+}

package/scripts/mock-multi-pr.mjs

@@ -0,0 +1,7 @@
+/** Shared content only; each adapter emits it through its own native wire. */
+export function multiPrText(prompt) {
+  return prompt.includes('mock:multi-pr-refs-continue')
+    ? 'CEZ:PR=813\nCEZ:PR=817\nCEZ:DONE'
+    : 'CEZ:PR=812\nCEZ:PR=813\nCEZ:PR=814\nCEZ:PR=815\nCEZ:PR=812\nCEZ:PR=816\nCEZ:DONE';
+}
+export const unrelatedPr = 'CEZ:PR=999\nCreated a PR: https://github.com/other/repo/pull/999';

package/scripts/mock-nudge.mjs

@@ -0,0 +1,45 @@
+// Cezar's no-wait nudge (hearsay-tools/cezarion#1234). Every native mock answers it the way an agent
+// should, by rewriting it into the mocks' own scenario prompts after the prompt is recorded: a
+// session with cezar tools calls cezar_ask with a card (`mock:cezar-tool`), and one taught the
+// markers ends with the ask line. CEZ_MOCK_NUDGE_REPLY=plain answers in plain text instead, so a
+// test can reach the no-wait fallback. CEZ_MOCK_COMPLETION_REPLY, when set, is the mock prompt that
+// answers Cezar's completion refusal nudge (hearsay-tools/cezarion#1301), so a test can choose the
+// reply turn; unset, the refusal gets the mocks' ordinary reply. `mock:ack-only` is a reply every
+// native mock understands: the harness acknowledges the prompt on its own wire (and reports it read
+// where that wire can) and opens no turn until more input arrives.
+import { FINAL_MESSAGE_NUDGE_PREFIX as NUDGE, silentTailOpened } from './mock-silent-tail.mjs';
+
+export const NO_WAIT_NUDGE_PREFIX = NUDGE;
+const QUESTIONS = [{ header: 'Next step', question: 'How should I continue?', options: [{ label: 'Keep going' }, { label: 'Stop here' }] }];
+// hearsay-tools/cezarion#1458: cezar_ask requires the context the user reads above the card.
+const CONTEXT = 'The task stopped without a next step.';
+
+const messages = (texts) => `mock:turn-messages:${Buffer.from(JSON.stringify(texts)).toString('base64')}`;
+const base64url = (text) => Buffer.from(text).toString('base64url');
+
+/** A session that opened a silent-tail or tool-tail scenario answers the nudge in that scenario. */
+export function silentNudge(prompt) {
+  return typeof prompt === 'string' && prompt.includes(NUDGE) && silentTailOpened();
+}
+
+/** Every completion refusal ends with this, whichever check refused it. */
+const COMPLETION_REFUSAL = 'then call cezar_done again.';
+const completionReply = (prompt) => process.env.CEZ_MOCK_COMPLETION_REPLY && prompt.includes(COMPLETION_REFUSAL) ? process.env.CEZ_MOCK_COMPLETION_REPLY : undefined;
+
+export function answerNudge(prompt) {
+  if (typeof prompt !== 'string') return prompt;
+  const completion = completionReply(prompt);
+  if (completion) return completion;
+  if (!prompt.includes(NUDGE) || silentTailOpened()) return prompt;
+  if (process.env.CEZ_MOCK_NUDGE_REPLY === 'plain') return messages(['Nothing more to add.']);
+  if (prompt.includes('CEZ:ASK')) return messages([`I need your call on the next step.\n\nCEZ:ASK ${JSON.stringify({ questions: QUESTIONS })}`]);
+  return `mock:cezar-tool cezar_ask ${base64url(JSON.stringify({ context: CONTEXT, questions: QUESTIONS }))} mock:then ${base64url('I asked how to continue.')}`;
+}
+
+/** OpenCode's prompt body: its text parts, joined, are the prompt. */
+export function answerNudgeBody(body) {
+  if (!body || ((!body.includes(NUDGE) || silentTailOpened()) && !completionReply(body))) return body;
+  const parsed = JSON.parse(body);
+  const text = (parsed.parts ?? []).map((part) => part.text ?? '').join('\n');
+  return JSON.stringify({ ...parsed, parts: [{ type: 'text', text: answerNudge(text) }] });
+}