elanous 0.2.35 → 0.2.36

package/src/ux-sim/dashboard-event-loop-stall-monitor-device.ts

@@ -0,0 +1,238 @@
+// L2 mock stage (ux-sim) for TUI-TYPING-LAG: a streaming scenario where a worker
+// floods the log plane while the user types, run through the PRODUCTION
+// StoreSink (src/mss/logging/log-store.ts · chunked drain via DebugLogBatchQueue
+// from src/debug/batch-queue.ts) and the PRODUCTION event-loop stall monitor
+// (src/dashboard/event-loop-stall-monitor.ts · `tui.event-loop` `stall`).
+//
+// The stage is a deterministic event loop on a fake clock. Main-thread cost is
+// charged explicitly (the clock only moves when work happens), so the thresholds
+// hold on fast and slow machines:
+//   • every StoreSink.emit charges `enqueueCostMs` (the worker burst's own task)
+//   • every row the fake store inserts charges `insertCostMs` (sqlite insert)
+//   • every key paint charges `renderCostMs`
+// One loop iteration runs only the tasks that were due BEFORE it started — a task
+// scheduled during the iteration waits for the next one, exactly like a chained
+// setImmediate — and a key that arrived meanwhile is delivered between iterations.
+//
+//   mode 'batched' — the sink is built exactly as the TUI builds it
+//                    (`logStoreDrainChunkForSurface('tui')`): each drain tick inserts one
+//                    bounded chunk, so a key waits for at most one chunk.
+//   mode 'inline'  — the default/CLI sink (pre-fix): one tick inserts the whole burst.
+import type { DebugBatchScheduler } from '../debug/batch-queue.js';
+import { LogStore, StoreSink, logStoreDrainChunkForSurface } from '../mss/logging/log-store.js';
+import type { LogRecord } from '../mss/logging/record.js';
+import { startEventLoopStallMonitor } from '../dashboard/event-loop-stall-monitor.js';
+
+export interface StageClock extends DebugBatchScheduler {
+  now(): number;
+  advance(ms: number): void;
+  /** Run every task that is due now, oldest first, including tasks they schedule. */
+  runDue(): number;
+  /** One event-loop iteration: run only the tasks due at its start. */
+  runIteration(): number;
+}
+
+interface StageTimer {
+  handle: number;
+  dueAt: number;
+  run: () => void;
+}
+
+export function createStageClock(startMs = 1_000_000): StageClock {
+  let current = startMs;
+  let nextHandle = 1;
+  let timers: StageTimer[] = [];
+  const dueNow = (): StageTimer[] => timers
+    .filter((timer) => timer.dueAt <= current)
+    .sort((a, b) => a.dueAt - b.dueAt || a.handle - b.handle);
+  const runOne = (timer: StageTimer): boolean => {
+    if (!timers.some((t) => t.handle === timer.handle)) return false;
+    timers = timers.filter((t) => t.handle !== timer.handle);
+    timer.run();
+    return true;
+  };
+  return {
+    now: () => current,
+    advance(ms) {
+      if (!Number.isFinite(ms) || ms < 0) throw new Error('stage clock advance must be a nonnegative finite number');
+      current += ms;
+    },
+    schedule(run, delayMs) {
+      const handle = nextHandle++;
+      timers = [...timers, { handle, dueAt: current + Math.max(0, delayMs), run }];
+      return handle;
+    },
+    cancel(handle) {
+      timers = timers.filter((timer) => timer.handle !== handle);
+    },
+    runDue() {
+      let ran = 0;
+      for (;;) {
+        const due = dueNow()[0];
+        if (!due) return ran;
+        if (runOne(due)) ran += 1;
+      }
+    },
+    runIteration() {
+      let ran = 0;
+      for (const timer of dueNow()) if (runOne(timer)) ran += 1;
+      return ran;
+    },
+  };
+}
+
+export interface StreamingStageOptions {
+  keypresses?: number;
+  workerEventsPerKey?: number;
+  insertCostMs?: number;
+  enqueueCostMs?: number;
+  renderCostMs?: number;
+  idleBetweenKeysMs?: number;
+  flushBatchSize?: number;
+  stallThresholdMs?: number;
+  mode?: 'batched' | 'inline';
+}
+
+export interface KeypressLagSample {
+  key: string;
+  index: number;
+  lagMs: number;
+  workerEvents: number;
+}
+
+export interface StreamingStageResult {
+  mode: 'batched' | 'inline';
+  samples: KeypressLagSample[];
+  maxLagMs: number;
+  /** Production `tui.event-loop` `stall` events (lag ≥ stallThresholdMs). */
+  stallCount: number;
+  stallLagsMs: number[];
+  stallThresholdMs: number;
+  workerEvents: number;
+  insertedRows: number;
+  insertBatches: number;
+  pendingEvents: number;
+  insertedSeqOrder: number[];
+}
+
+export interface DashboardStreamingStage {
+  pressKey(key: string): KeypressLagSample;
+  run(): StreamingStageResult;
+  result(): StreamingStageResult;
+  dispose(): void;
+}
+
+const DEFAULTS: Required<StreamingStageOptions> = {
+  keypresses: 12,
+  workerEventsPerKey: 800,
+  insertCostMs: 0.5,
+  enqueueCostMs: 0.01,
+  renderCostMs: 3,
+  idleBetweenKeysMs: 150,
+  flushBatchSize: 64,
+  stallThresholdMs: 250,
+  mode: 'batched',
+};
+
+export function createDashboardStreamingStage(options: StreamingStageOptions = {}): DashboardStreamingStage {
+  const config = { ...DEFAULTS, ...options };
+  const clock = createStageClock();
+  const insertedSeqOrder: number[] = [];
+  const samples: KeypressLagSample[] = [];
+  const stallLagsMs: number[] = [];
+  let workerEvents = 0;
+  let insertBatches = 0;
+
+  // Fake LogStore: the only surface StoreSink touches on the drain path is insertBatch.
+  const fakeStore = {
+    insertBatch(rows: Array<{ rec: LogRecord; surface: string }>): void {
+      insertBatches += 1;
+      for (const row of rows) {
+        insertedSeqOrder.push(Number((row.rec.data as { seq?: number } | undefined)?.seq ?? -1));
+        clock.advance(config.insertCostMs);
+      }
+    },
+  } as unknown as LogStore;
+
+  const drainChunkSize = config.mode === 'batched' ? logStoreDrainChunkForSurface('tui') : undefined;
+  const sink = new StoreSink(fakeStore, 'tui', {
+    flushBatchSize: config.flushBatchSize,
+    flushIntervalMs: 200,
+    installExitHandlers: false,
+    scheduler: clock,
+    ...(drainChunkSize !== undefined ? { drainChunkSize } : {}),
+  });
+
+  const disposeMonitor = startEventLoopStallMonitor({
+    thresholdMs: config.stallThresholdMs,
+    now: () => clock.now(),
+    setIntervalFn: (callback, intervalMs) => {
+      const tick = (): void => { callback(); clock.schedule(tick, intervalMs); };
+      clock.schedule(tick, intervalMs);
+      return {};
+    },
+    clearIntervalFn: () => {},
+    getContext: () => ({ streamingInFlight: true, thinkingMessage: 'Streaming' }),
+    log: (category, event, data) => {
+      if (category === 'tui.event-loop' && event === 'stall') stallLagsMs.push(Number(data.lagMs));
+    },
+  });
+
+  function pressKey(key: string): KeypressLagSample {
+    const index = samples.length;
+    // Worker burst — one task on the main thread emits N log records.
+    for (let seq = 0; seq < config.workerEventsPerKey; seq += 1) {
+      const globalSeq = index * config.workerEventsPerKey + seq;
+      sink.emit({ ts: new Date(clock.now()).toISOString(), category: 'worker', event: 'stream-chunk', data: { seq: globalSeq } });
+      workerEvents += 1;
+      clock.advance(config.enqueueCostMs);
+    }
+    // The key arrives now; the loop finishes the iteration already queued, then delivers it.
+    const arrivedAt = clock.now();
+    clock.runIteration();
+    clock.advance(config.renderCostMs);
+    const sample: KeypressLagSample = { key, index, lagMs: clock.now() - arrivedAt, workerEvents: config.workerEventsPerKey };
+    samples.push(sample);
+    // Drain the rest of the burst iteration by iteration, then idle until the next key.
+    while (clock.runIteration() > 0) { /* next iteration */ }
+    clock.advance(config.idleBetweenKeysMs);
+    clock.runDue();
+    return sample;
+  }
+
+  function result(): StreamingStageResult {
+    return {
+      mode: config.mode,
+      samples: [...samples],
+      maxLagMs: samples.reduce((max, sample) => Math.max(max, sample.lagMs), 0),
+      stallCount: stallLagsMs.length,
+      stallLagsMs: [...stallLagsMs],
+      stallThresholdMs: config.stallThresholdMs,
+      workerEvents,
+      insertedRows: insertedSeqOrder.length,
+      insertBatches,
+      pendingEvents: sink.pending,
+      insertedSeqOrder: [...insertedSeqOrder],
+    };
+  }
+
+  return {
+    pressKey,
+    result,
+    dispose: () => { disposeMonitor(); },
+    run() {
+      for (let index = 0; index < config.keypresses; index += 1) pressKey(`key-${index}`);
+      sink.flush();
+      return result();
+    },
+  };
+}
+
+export function runDashboardStreamingScenario(options: StreamingStageOptions = {}): StreamingStageResult {
+  const stage = createDashboardStreamingStage(options);
+  try {
+    return stage.run();
+  } finally {
+    stage.dispose();
+  }
+}

package/src/ux-sim/event-monkey.ts

@@ -264,10 +264,11 @@ export function emitInjectedEvent(options: EmitInjectedEventOptions): EmitInject
     }
     case 'scope-escape-held': {
       const outOfScopeEdits = ['src/index.ts', 'src/cli/tasks-cli.ts', 'docs/_index.md'];
+      // SCOPE-ESCAPE-AS-REFINE — a held edit now always carries its stop reason (orchestrator decideScopeExpansion); without one it is new scope.
       ledger.write('execution-scope-held', { outOfScopeEdits, nameCapReached: false, outsideCount: outOfScopeEdits.length,
-        worktreePath: `/tmp/elanous-sim/${job}`, branch, disposition: 'in-scope-only' });
+        worktreePath: `/tmp/elanous-sim/${job}`, branch, disposition: 'in-scope-only', stopReasons: ['deletion'], deleted: ['docs/_index.md'] });
       podChildRun();
-      childEvidence({ ok: false, exitCode: 1, outOfScopeEdits, detail: 'Out-of-scope edits held in the worktree; gate and publication skipped.' });
+      childEvidence({ ok: false, exitCode: 1, outOfScopeEdits, scopeStopReasons: ['deletion'], detail: 'Out-of-scope edits held in the worktree; gate and publication skipped.' });
       emit('self-implement.pod', 'child-error', { job, stage: 'soft-stopped', error: 'Out-of-scope edits held in the worktree' });
       break;
     }

package/src/ux-sim/fake-bin.ts

@@ -13,6 +13,7 @@
 // ⛔ This is not a simulator of the real tool: a spec only fixes stdout · stderr ·
 // exit code · lifetime, and records argv. Behaviour of the real tool stays with
 // tests that run where the tool exists.
+import { spawnSync } from 'node:child_process';
 import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { delimiter, isAbsolute, join } from 'node:path';
@@ -37,6 +38,14 @@ export interface FakeBinSpec {
    * a «died without a word» failure (`status` null · `signal` set). `exitCode` is then never reached.
    */
   readonly killSignal?: 'KILL' | 'TERM' | 'INT' | 'HUP' | 'ABRT' | 'SEGV';
+  /**
+   * Be the util-linux `script -q -e -c` PTY allocator itself: record the call, then `exec` the real
+   * util-linux `script` with the same argv. A test that spawns `sh -c 'script -q -e -c "$1" …'`
+   * then gets a real TTY (so `process.stdin.isTTY` is true inside the child) and the recording proves
+   * the PTY came from util-linux, not from a hand-rolled shim. Requires util-linux on PATH
+   * (`utilLinuxScript()`); incompatible with the output-faking fields below.
+   */
+  readonly pty?: boolean;
 }
 
 export interface FakeBinCall {
@@ -67,6 +76,29 @@ function shellQuote(value: string): string {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 
+let utilLinuxScriptCache: string | null | undefined;
+
+/**
+ * Absolute path of the util-linux `script` on PATH, or `null` when this host has none
+ * (macOS ships BSD `script`, whose `-q -e -c` flags differ — see `firstRunPtySupport()`).
+ * Probed once per process: `<path>/script --version` must answer `util-linux`.
+ */
+export function utilLinuxScript(): string | null {
+  if (utilLinuxScriptCache !== undefined) return utilLinuxScriptCache;
+  utilLinuxScriptCache = null;
+  for (const dir of (process.env.PATH ?? '').split(delimiter)) {
+    if (!dir) continue;
+    const candidate = join(dir, 'script');
+    if (!existsSync(candidate)) continue;
+    const probe = spawnSync(candidate, ['--version'], { encoding: 'utf8', timeout: 5_000 });
+    if (probe.status === 0 && `${probe.stdout ?? ''}${probe.stderr ?? ''}`.includes('util-linux')) {
+      utilLinuxScriptCache = candidate;
+      break;
+    }
+  }
+  return utilLinuxScriptCache;
+}
+
 function script(name: string, spec: FakeBinSpec, dataDir: string, logPath: string): string {
   const lines = ['#!/bin/sh'];
   // One record per call: name and each argv entry NUL-terminated (one printf), then an ASCII record
@@ -76,6 +108,11 @@ function script(name: string, spec: FakeBinSpec, dataDir: string, logPath: strin
   // for recorder and payload reads so a fake of one of those names cannot recursively call itself.
   lines.push(`rec=$(command -p mktemp ${shellQuote(join(dataDir, 'rec.XXXXXX'))})`);
   lines.push(`{ printf '%s\\0' ${shellQuote(name)} "$@"; printf '\\036'; } > "$rec"; command -p cat "$rec" >> ${shellQuote(logPath)}; command -p rm -f "$rec"`);
+  if (spec.pty === true) {
+    // Recorded already: exec the real util-linux script so the caller gets a genuine TTY.
+    lines.push(`exec ${shellQuote(utilLinuxScript()!)} "$@"`);
+    return `${lines.join('\n')}\n`;
+  }
   if (spec.whenArgsStartWith !== undefined && spec.otherwise !== undefined) {
     const words = spec.whenArgsStartWith;
     const tests = [`[ "$#" -ge ${words.length} ]`, ...words.map((word, index) => `[ "$${index + 1}" = ${shellQuote(word)} ]`)];
@@ -118,6 +155,14 @@ export function createFakeBins(specs: Readonly<Record<string, FakeBinSpec>>): Fa
     } else if (spec.otherwise !== undefined) {
       throw new Error(`fake-bin: ${name}: otherwise is only used with whenArgsStartWith`);
     }
+    if (spec.pty === true) {
+      if (spec.stdout !== undefined || spec.stderr !== undefined || spec.exitCode !== undefined
+        || spec.sleepSeconds !== undefined || spec.killSignal !== undefined
+        || spec.whenArgsStartWith !== undefined || spec.otherwise !== undefined) {
+        throw new Error(`fake-bin: ${name}: pty is a pass-through PTY allocator and takes no output/fake fields`);
+      }
+      if (utilLinuxScript() === null) throw new Error(`fake-bin: ${name}: pty needs the util-linux \`script\` on PATH (this host has none)`);
+    }
   }
   const root = mkdtempSync(join(tmpdir(), 'ux-sim-fake-bin-'));
   const dir = join(root, 'bin');

package/src/ux-sim/fake-herdr.ts

@@ -0,0 +1,238 @@
+// Fake herdr server for tests of code that drives the `herdr` CLI (TUI-HERDR-NAMED-AGENT).
+//
+// The real herdr 0.9.1 needs a live server socket and a terminal pane; a gate Pod has neither.
+// This device answers the few agent/pane calls `herdr-prompt.ts` makes, as a `HerdrCliRunner`
+// (argv in → rc · stdout · stderr out), from an in-memory pane table:
+//   agent get <target>                    → {"result":{"agent":{…}}} · agent_not_found (rc1)
+//   agent wait <target> [--until S]… [--timeout MS] → returns at once when the status already matches,
+//                                           otherwise on the next matching transition · timeout (rc1)
+//   pane run <pane> <text>                → records the submission · calls `onRun` (the test's «TUI»)
+//   pane report-agent <pane>… --source S --agent A --state X --seq N
+//                                         → self-reported agent (herdr «Integrate your own agent»)
+//   pane release-agent <pane> --source S --agent A --seq N → releases it
+//   pane report-agent-session …           → rc0 · no-op (measured: neither registers nor moves the state seq)
+//   agent list                            → reported agents (`reportedAgents()` is the same list)
+// Report faults (`reportFault`, TUI-HERDR-STATUS-STALE): a `pane report-agent` can answer as a client
+// timeout — `applied-then-timeout` (the server took it, the answer came too late: the 10-22 n8n shape)
+// or `timeout` (never applied). The answer is `{code:null, stderr:'timeout', timedOut:true}`.
+// Report/release seq rule measured on herdr 0.9.1 (10-22 · isolated session `tf-exit-race`):
+//   a report/release is applied only when its seq is above the last applied seq of that pane·source
+//   (smaller is rc0 and ignored); a release of an agent that is not registered is rc0 and does NOT
+//   record its seq — so a smaller-seq report arriving after it still registers (the exit-race ghost).
+// Error envelopes follow the shape measured on herdr 0.9.1 (10-22 · isolated session `tf-herdr-e4`):
+//   {"error":{"code":"…","message":"…"},"id":"cli:agent:get"} on stderr, exit 1.
+//
+// ⛔ This is not a herdr simulator: it fixes only those answers and the «matches now → return now»
+// wait rule from the herdr agent-automation doc. Real herdr behaviour stays with the isolated-session E4.
+
+export type FakeHerdrStatus = 'idle' | 'working' | 'blocked' | 'done' | 'unknown';
+
+export interface FakeHerdrPane {
+  readonly paneId: string;
+  /** Reported or detected agent label (`elanous`, `codex`, …). */
+  agent: string;
+  name?: string;
+  status: FakeHerdrStatus;
+  stateChangeSeq: number;
+}
+
+export interface FakeHerdrRunResult {
+  readonly code: number | null;
+  readonly stdout: string;
+  readonly stderr: string;
+  /** Set only by `reportFault` — the client gave up waiting (the report may or may not have been applied). */
+  readonly timedOut?: boolean;
+}
+
+/** How one `pane report-agent` call fails (see `FakeHerdrOpts.reportFault`). */
+export type FakeHerdrReportFault = 'applied-then-timeout' | 'timeout';
+
+export interface FakeHerdrSubmission {
+  readonly paneId: string;
+  readonly text: string;
+}
+
+export interface FakeHerdr {
+  /** The `HerdrCliRunner` the code under test receives. */
+  run(argv: readonly string[], timeoutMs: number): Promise<FakeHerdrRunResult>;
+  /** Move a pane to a new status (bumps `state_change_seq`, wakes matching waits). */
+  setStatus(paneId: string, status: FakeHerdrStatus): void;
+  pane(paneId: string): FakeHerdrPane | undefined;
+  /** Every `pane run` submission, in order. */
+  submissions(): FakeHerdrSubmission[];
+  /** Every argv the runner saw, in order. */
+  calls(): string[][];
+  /**
+   * The same answers as `run` for the commands that never wait (report-agent · release-agent ·
+   * report-agent-session · agent list) — for code whose runner is synchronous (the TUI exit path).
+   */
+  runSync(argv: readonly string[]): FakeHerdrRunResult;
+  /** Agents registered through `pane report-agent` and not released (what `agent list` shows). */
+  reportedAgents(): FakeHerdrReportedAgent[];
+}
+
+export interface FakeHerdrReportedAgent {
+  readonly paneId: string;
+  readonly source: string;
+  readonly agent: string;
+  readonly state: string;
+  readonly seq: number;
+}
+
+export interface FakeHerdrOpts {
+  readonly panes: ReadonlyArray<{ paneId: string; agent: string; name?: string; status: FakeHerdrStatus }>;
+  /** Called after a `pane run` is recorded — the test's TUI reacts here (e.g. working → idle). */
+  readonly onRun?: (submission: FakeHerdrSubmission, herdr: FakeHerdr) => void;
+  /**
+   * Fault for the n-th `pane report-agent` call (0-based, counted across run/runSync) — undefined answers normally.
+   * `applied-then-timeout` applies the report and then answers as a timeout; `timeout` answers without applying.
+   */
+  readonly reportFault?: (argv: readonly string[], index: number) => FakeHerdrReportFault | undefined;
+}
+
+const SETTLED: readonly FakeHerdrStatus[] = ['idle', 'done', 'blocked'];
+
+function errorBody(id: string, code: string, message: string): FakeHerdrRunResult {
+  return { code: 1, stdout: '', stderr: `${JSON.stringify({ error: { code, message }, id })}\n` };
+}
+
+function agentInfo(p: FakeHerdrPane): Record<string, unknown> {
+  return {
+    agent: p.agent,
+    agent_status: p.status,
+    pane_id: p.paneId,
+    state_change_seq: p.stateChangeSeq,
+    ...(p.name !== undefined ? { name: p.name } : {}),
+  };
+}
+
+export function createFakeHerdr(opts: FakeHerdrOpts): FakeHerdr {
+  const panes = new Map<string, FakeHerdrPane>();
+  for (const p of opts.panes) panes.set(p.paneId, { ...p, stateChangeSeq: 1 });
+  const subs: FakeHerdrSubmission[] = [];
+  const argvLog: string[][] = [];
+  const waiters = new Set<{ paneId: string; until: readonly FakeHerdrStatus[]; resolve: () => void }>();
+
+  /** pane·source → registered agent · last applied seq (kept after release). */
+  const reported = new Map<string, FakeHerdrReportedAgent>();
+  const lastSeq = new Map<string, number>();
+  const optsOf = (args: readonly string[]): { pane?: string; flags: Map<string, string> } => {
+    const flags = new Map<string, string>();
+    let pane: string | undefined;
+    for (let i = 0; i < args.length; i++) {
+      const a = args[i]!;
+      if (a.startsWith('--')) flags.set(a.slice(2), args[++i] ?? '');
+      else if (pane === undefined) pane = a;
+    }
+    return { pane, flags };
+  };
+
+  let reportIndex = 0;
+  const TIMEOUT: FakeHerdrRunResult = { code: null, stdout: '', stderr: 'timeout', timedOut: true };
+  /** `applyReport` with the scripted fault for `pane report-agent`. */
+  const answerReport = (argv: readonly string[]): FakeHerdrRunResult | undefined => {
+    if (argv[0] !== 'pane' || argv[1] !== 'report-agent') return applyReport(argv);
+    const fault = opts.reportFault?.(argv, reportIndex++);
+    if (fault === 'timeout') return TIMEOUT;
+    const r = applyReport(argv);
+    return fault === 'applied-then-timeout' ? TIMEOUT : r;
+  };
+
+  /** report-agent · release-agent · report-agent-session · agent list — answered at once (no waits). */
+  const applyReport = (argv: readonly string[]): FakeHerdrRunResult | undefined => {
+    const [group, cmd] = argv;
+    if (group === 'pane' && cmd === 'report-agent-session') return { code: 0, stdout: '', stderr: '' };
+    if (group === 'pane' && (cmd === 'report-agent' || cmd === 'release-agent')) {
+      const { pane, flags } = optsOf(argv.slice(2));
+      const source = flags.get('source') ?? '';
+      const seq = Number(flags.get('seq'));
+      if (pane === undefined || !source || !Number.isSafeInteger(seq)) {
+        return { code: 2, stdout: '', stderr: `fake-herdr: ${cmd} needs <pane> --source --seq\n` };
+      }
+      const key = `${pane}\u0000${source}`;
+      const prev = lastSeq.get(key);
+      if (prev !== undefined && seq <= prev) return { code: 0, stdout: '', stderr: '' };
+      if (cmd === 'release-agent') {
+        if (!reported.has(key)) return { code: 0, stdout: '', stderr: '' };
+        reported.delete(key);
+        lastSeq.set(key, seq);
+        return { code: 0, stdout: '', stderr: '' };
+      }
+      reported.set(key, { paneId: pane, source, agent: flags.get('agent') ?? '', state: flags.get('state') ?? reported.get(key)?.state ?? 'unknown', seq });
+      lastSeq.set(key, seq);
+      return { code: 0, stdout: '', stderr: '' };
+    }
+    if (group === 'agent' && cmd === 'list') {
+      const agents = [...reported.values()].map((a) => ({ agent: a.agent, agent_status: a.state, pane_id: a.paneId }));
+      return { code: 0, stdout: `${JSON.stringify({ id: 'cli:agent:list', result: { agents, type: 'agent_list' } })}\n`, stderr: '' };
+    }
+    return undefined;
+  };
+
+  const resolveTarget = (target: string): FakeHerdrPane | undefined =>
+    panes.get(target) ?? [...panes.values()].find((p) => p.name === target);
+
+  const herdr: FakeHerdr = {
+    async run(argv, timeoutMs) {
+      argvLog.push([...argv]);
+      const [group, cmd, target, ...rest] = argv;
+      if (group === 'agent' && cmd === 'get' && target !== undefined) {
+        const p = resolveTarget(target);
+        if (!p) return errorBody('cli:agent:get', 'agent_not_found', `agent target ${target} not found`);
+        return { code: 0, stdout: `${JSON.stringify({ id: 'cli:agent:get', result: { agent: agentInfo(p), type: 'agent_info' } })}\n`, stderr: '' };
+      }
+      if (group === 'agent' && cmd === 'wait' && target !== undefined) {
+        const p = resolveTarget(target);
+        if (!p) return errorBody('cli:agent:wait', 'agent_not_found', `agent target ${target} not found`);
+        const until: FakeHerdrStatus[] = [];
+        let waitTimeout: number | undefined;
+        for (let i = 0; i < rest.length; i++) {
+          if (rest[i] === '--until') until.push(rest[++i] as FakeHerdrStatus);
+          else if (rest[i] === '--timeout') waitTimeout = Number(rest[++i]);
+        }
+        const want = until.length > 0 ? until : SETTLED;
+        const ok = (): FakeHerdrRunResult => ({ code: 0, stdout: `${JSON.stringify({ id: 'cli:agent:wait', result: { agent: agentInfo(p), type: 'agent_info' } })}\n`, stderr: '' });
+        if (want.includes(p.status)) return ok();
+        const limit = Math.min(waitTimeout ?? Number.POSITIVE_INFINITY, timeoutMs);
+        return new Promise<FakeHerdrRunResult>((resolve) => {
+          const waiter = {
+            paneId: p.paneId,
+            until: want,
+            resolve: () => { clearTimeout(timer); waiters.delete(waiter); resolve(ok()); },
+          };
+          const timer = Number.isFinite(limit)
+            ? setTimeout(() => { waiters.delete(waiter); resolve(errorBody('cli:agent:wait', 'timeout', `timed out waiting for agent ${target}`)); }, limit)
+            : undefined;
+          waiters.add(waiter);
+        });
+      }
+      if (group === 'pane' && cmd === 'run' && target !== undefined) {
+        const p = panes.get(target);
+        if (!p) return errorBody('cli:pane:run', 'pane_not_found', `pane ${target} not found`);
+        const submission = { paneId: p.paneId, text: rest[0] ?? '' };
+        subs.push(submission);
+        opts.onRun?.(submission, herdr);
+        return { code: 0, stdout: '', stderr: '' };
+      }
+      const reportedResult = answerReport(argv);
+      if (reportedResult) return reportedResult;
+      return { code: 2, stdout: '', stderr: `fake-herdr: unsupported argv ${argv.join(' ')}\n` };
+    },
+    setStatus(paneId, status) {
+      const p = panes.get(paneId);
+      if (!p) throw new Error(`fake-herdr: no pane ${paneId}`);
+      p.status = status;
+      p.stateChangeSeq += 1;
+      for (const w of [...waiters]) if (w.paneId === paneId && w.until.includes(status)) w.resolve();
+    },
+    pane: (paneId) => panes.get(paneId),
+    submissions: () => [...subs],
+    runSync(argv) {
+      argvLog.push([...argv]);
+      return answerReport(argv) ?? { code: 2, stdout: '', stderr: `fake-herdr: runSync supports report/release/agent list only — ${argv.join(' ')}\n` };
+    },
+    calls: () => argvLog.map((a) => [...a]),
+    reportedAgents: () => [...reported.values()],
+  };
+  return herdr;
+}