elanous 0.2.35 → 0.2.37

package/src/ux-sim/cli-config-audit-device.ts

@@ -0,0 +1,121 @@
+// ── CFG-STORE2-HISTORY-REVERT · config 감사 이력 장치 (ux-sim L2) ──
+//
+// 실 CLI(`src/index.ts` 의 `config` 명령 트리)를 «같은 격리 config 저장소» 위에서 여러 번 부른다.
+// in-process-cli.ts 의 턴 하나는 자기 temp 뿌리를 만들고 지운다 — set → history → revert 한 바퀴는
+// 같은 저장소·같은 감사 원장이 이어져야 하므로 이 장치는 stateRoot 를 소유하고 재사용한다
+// (InProcessCliOptions.stateRoot · 정리는 dispose 가 한다).
+//
+// ⛔ 경계
+//   • 저장소는 이 장치의 temp 뿌리뿐이다 — 실제 ~/.elanous 를 건드리지 않는다(in-process-cli 격리 그대로).
+//   • 여기서 값을 «만들지» 않는다 — 값·감사 행은 실 CLI 의 set/unset/history/revert 가 만든 것만 관측한다.
+//   • 비밀 원문은 이 장치의 어떤 접근자도 새로 노출하지 않는다: 원장·stdout 을 그대로 돌려줄 뿐이다.
+
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { readConfigHistory, type ConfigChangeRow } from '../cli/config-audit.js';
+import { simInProcessCli } from './in-process-cli.js';
+
+/** 장치가 실 CLI 에 넘긴 인자와 그 턴의 결과. */
+export interface ConfigAuditTurn {
+  readonly args: readonly string[];
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+/** 실 CLI `config` 명령 트리를 격리 HOME 위에서 돌리는 장치. */
+export interface CliConfigAuditDevice {
+  /** 격리된 config 뿌리(= config.json 과 config-changes.db 가 사는 자리). */
+  readonly stateRoot: string;
+  /** 사용자 config 파일 자리. */
+  readonly configPath: string;
+  /** 감사 원장(config_changes) 파일 자리. */
+  readonly ledgerPath: string;
+  /** 임의 인자 한 턴 — 허용 목록 밖 명령은 장치가 거부한다. */
+  run(...args: string[]): Promise<ConfigAuditTurn>;
+  set(path: string, value: unknown): Promise<ConfigAuditTurn>;
+  unset(path: string): Promise<ConfigAuditTurn>;
+  history(path: string): Promise<ConfigAuditTurn>;
+  revert(path: string): Promise<ConfigAuditTurn>;
+  /** 그 키의 감사 행(시간 오름차순) — 실 CLI 가 남긴 원장 그대로. */
+  ledger(path: string): ConfigChangeRow[];
+  /** 저장된 config 에서 그 자리의 값(없으면 undefined). */
+  value(path: string): unknown;
+  /** 원장 파일 원문(비밀 원문 부재 검사용). */
+  ledgerText(): string;
+  /** 격리 뿌리 제거. 두 번 불러도 안전. */
+  dispose(): void;
+}
+
+const ALLOWED_PATHS: readonly (readonly string[])[] = [
+  ['config', 'set'],
+  ['config', 'unset'],
+  ['config', 'get'],
+  ['config', 'history'],
+  ['config', 'revert'],
+];
+
+/** 점 표기 경로로 값 하나를 꺼낸다. */
+function pick(root: unknown, path: string): unknown {
+  let node = root;
+  for (const segment of path.split('.').filter(Boolean)) {
+    if (node === null || typeof node !== 'object') return undefined;
+    node = (node as Record<string, unknown>)[segment];
+  }
+  return node;
+}
+
+/** CLI 인자 형태 — 문자열은 그대로(사용자 config 문법), 그 밖은 JSON. */
+function argValue(value: unknown): string {
+  return typeof value === 'string' ? value : JSON.stringify(value);
+}
+
+/** 격리 config 저장소 + 감사 원장을 함께 들고 있는 장치를 만든다. */
+export function createCliConfigAuditDevice(): CliConfigAuditDevice {
+  const stateRoot = mkdtempSync(join(tmpdir(), 'ux-sim-config-audit-'));
+  const configPath = join(stateRoot, 'config.json');
+  const ledgerPath = join(stateRoot, 'config-changes.db');
+
+  const run = async (...args: string[]): Promise<ConfigAuditTurn> => {
+    try {
+      const result = await simInProcessCli(args, { allowPaths: ALLOWED_PATHS, stateRoot });
+      return { args, exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr };
+    } catch (err) {
+      // 거부된 명령(허용 목록 밖·미등록 하위 명령)도 «한 턴» 이다 — 던지지 않고 실패 턴으로 돌려준다.
+      return { args, exitCode: 1, stdout: '', stderr: err instanceof Error ? err.message : String(err) };
+    }
+  };
+
+  const readConfig = (): Record<string, unknown> => {
+    try {
+      const parsed: unknown = JSON.parse(readFileSync(configPath, 'utf8'));
+      return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+        ? (parsed as Record<string, unknown>)
+        : {};
+    } catch {
+      return {};
+    }
+  };
+
+  return {
+    stateRoot,
+    configPath,
+    ledgerPath,
+    run,
+    set: (path, value) => run('config', 'set', path, argValue(value)),
+    unset: (path) => run('config', 'unset', path),
+    history: (path) => run('config', 'history', path),
+    revert: (path) => run('config', 'revert', path),
+    ledger: (path) => readConfigHistory(path, ledgerPath),
+    value: (path) => pick(readConfig(), path),
+    ledgerText: () => {
+      try {
+        return readFileSync(ledgerPath, 'utf8');
+      } catch {
+        return '';
+      }
+    },
+    dispose: () => rmSync(stateRoot, { recursive: true, force: true }),
+  };
+}

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-gh.ts

@@ -0,0 +1,174 @@
+import type { MergedPrRunner, MergedPrRunResult } from '../release-loop/landed-but-yellow.js';
+import { createHash } from 'node:crypto';
+
+/** GitHub data at the CLI boundary; sweep decisions remain in the production callers. */
+export interface FakeGhPr {
+  number: number;
+  title: string;
+  branch: string;
+  draft?: boolean;
+  closed?: boolean;
+  createdAt: string;
+  updatedAt: string;
+  mergedAt?: string;
+  mergeSha?: string;
+  body?: string;
+  head?: string;
+  labels?: string[];
+  files?: string[];
+  comments?: string[];
+}
+
+export interface FakeGhFault {
+  /** A matching invocation fails this many times, then succeeds. */
+  kind: 'unexpected-eof' | 'rate-limit';
+  match: RegExp;
+  times: number;
+}
+
+export interface FakeGh {
+  /** Same synchronous gh execution boundary as githubDraftSweepAdapters. */
+  api(args: string[]): string;
+  /** GitHub process-result boundary for callers that route git separately. */
+  run(command: string, args: readonly string[], cwd?: string): MergedPrRunResult;
+  /** Same async gh process boundary as fetchMergedChecklistPrs / release checklist. */
+  runAsync: MergedPrRunner;
+  readonly calls: string[][];
+  readonly prs: FakeGhPr[];
+}
+
+export function createFakeGh(input: { prs: FakeGhPr[]; faults?: FakeGhFault[]; repository?: string; now?: () => Date }): FakeGh {
+  const prs = input.prs.map((pr) => ({ ...pr, labels: [...(pr.labels ?? [])], files: [...(pr.files ?? [])], comments: [...(pr.comments ?? [])] }));
+  const faults = (input.faults ?? []).map((fault) => ({ ...fault, remaining: fault.times }));
+  const calls: string[][] = [];
+  const repo = input.repository ?? 'example/repo';
+  const now = input.now ?? (() => new Date());
+  const find = (number: number) => {
+    const pr = prs.find((entry) => entry.number === number);
+    if (!pr) throw new Error(`fake-gh: unknown PR #${number}`);
+    return pr;
+  };
+  const pull = (pr: FakeGhPr) => ({
+    number: pr.number, title: pr.title, draft: pr.draft ?? false, state: pr.mergedAt || pr.closed ? 'closed' : 'open',
+    head: { ref: pr.branch, sha: pr.head ?? `head${pr.number}` }, base: { ref: 'main' },
+    labels: pr.labels!.map((name) => ({ name })), created_at: pr.createdAt, updated_at: pr.updatedAt,
+    merged_at: pr.mergedAt ?? null, body: pr.body ?? null, merge_commit_sha: pr.mergeSha ?? null,
+  });
+  const slice = <T>(rows: T[], page: number, size = 100): T[] => rows.slice((page - 1) * size, page * size);
+  const pageChunks = <T>(rows: T[], size: number): T[][] => Array.from({ length: Math.ceil(rows.length / size) }, (_, index) => slice(rows, index + 1, size));
+  const perPage = (url: URL): number => {
+    const configured = url.searchParams.get('per_page');
+    const size = configured === null ? 30 : Number(configured);
+    if (!Number.isSafeInteger(size) || size < 1 || size > 100) throw new Error(`fake-gh: invalid per_page ${configured}`);
+    return size;
+  };
+  const json = (value: unknown) => JSON.stringify(value);
+  const api = (args: string[]): string => {
+    calls.push([...args]);
+    const call = args.join(' ');
+    const fault = faults.find((candidate) => {
+      if (candidate.remaining <= 0) return false;
+      candidate.match.lastIndex = 0;
+      return candidate.match.test(call);
+    });
+    if (fault) {
+      fault.remaining--;
+      const message = fault.kind === 'unexpected-eof' ? 'GraphQL: unexpected EOF' : 'API rate limit exceeded';
+      const error = new Error(message) as Error & { stderr: string };
+      error.stderr = message;
+      throw error;
+    }
+    if (args[0] === 'api') {
+      if (args[1] === 'graphql') {
+        const query = args[3] ?? '';
+        const repository: Record<string, unknown> = {};
+        const connectionPageSize = (name: 'files' | 'comments' | 'reviews'): number => {
+          const match = new RegExp(`${name}\\(first:\\s*(\\d+)\\)`).exec(query);
+          return match ? Number(match[1]) : 100;
+        };
+        for (const match of query.matchAll(/p(\d+): pullRequest/g)) {
+          const pr = find(Number(match[1]));
+          const filePageSize = connectionPageSize('files');
+          const commentPageSize = connectionPageSize('comments');
+          const reviewPageSize = connectionPageSize('reviews');
+          repository[`p${pr.number}`] = { number: pr.number, headRefOid: pr.head ?? `head${pr.number}`,
+            headRef: { target: { committedDate: pr.updatedAt } },
+            files: { totalCount: pr.files!.length, nodes: slice(pr.files!.map((path) => ({ path })), 1, filePageSize), pageInfo: { hasNextPage: pr.files!.length > filePageSize } },
+            comments: { totalCount: pr.comments!.length, nodes: slice(pr.comments!.map((body) => ({ body })), 1, commentPageSize), pageInfo: { hasNextPage: pr.comments!.length > commentPageSize } },
+            reviews: { totalCount: 0, nodes: [], pageInfo: { hasNextPage: false } },
+            mergeCommit: pr.mergeSha ? { oid: pr.mergeSha, message: pr.title } : null };
+        }
+        return json({ data: { repository } });
+      }
+      const endpoint = args.at(-1) ?? '';
+      const url = new URL(endpoint, 'https://api.github.test/');
+      const path = url.pathname;
+      const page = Number(url.searchParams.get('page') ?? 1);
+      const pageSize = perPage(url);
+      let match: RegExpExecArray | null;
+      if (/\/pulls$/.test(path)) {
+        const state = url.searchParams.get('state');
+        if (state !== 'open' && state !== 'closed') throw new Error(`fake-gh: invalid state ${state}`);
+        return json(slice(prs.filter((pr) => (state === 'closed') === Boolean(pr.mergedAt || pr.closed)).map(pull), page, pageSize));
+      }
+      if ((match = /\/pulls\/(\d+)\/files$/.exec(path))) return json(slice(find(Number(match[1])).files!.map((filename) => ({ filename })), page, pageSize));
+      if ((match = /\/issues\/(\d+)\/comments$/.exec(path))) {
+        const createdAt = now().toISOString();
+        const rows = find(Number(match[1])).comments!.map((body) => ({ body, created_at: createdAt }));
+        if (args.includes('--paginate')) {
+          const pages = pageChunks(rows, pageSize);
+          return json(args.includes('--slurp') ? pages : pages.flat());
+        }
+        const rowsForPage = slice(rows, page, pageSize);
+        return json(args.includes('--slurp') ? [rowsForPage] : rowsForPage);
+      }
+      if ((match = /\/pulls\/(\d+)\/reviews$/.exec(path))) return json(slice([], page, pageSize));
+      if ((match = /\/pulls\/(\d+)\/commits$/.exec(path))) return json(slice([], page, pageSize));
+      if ((match = /\/pulls\/(\d+)$/.exec(path))) return json(pull(find(Number(match[1]))));
+      if ((match = /\/commits\/([^/]+)\/status$/.exec(path))) return json({ state: 'success' });
+      if ((match = /\/commits\/([^/]+)\/check-runs$/.exec(path))) return json({ total_count: 1, check_runs: [{ conclusion: 'success' }] });
+      if ((match = /\/commits\/([^/]+)$/.exec(path))) return json({ commit: { message: prs.find((pr) => pr.mergeSha === match![1])?.title ?? '' }, files: [] });
+    }
+    if (args[0] === 'pr' && args[1] === 'list') {
+      const limitIndex = args.indexOf('--limit');
+      const limit = limitIndex === -1 ? 30 : Number(args[limitIndex + 1]);
+      if (!Number.isSafeInteger(limit) || limit < 0) throw new Error('fake-gh: invalid --limit');
+      const since = /merged:>=(\d{4}-\d\d-\d\d)/.exec(args[args.indexOf('--search') + 1] ?? '')?.[1];
+      const until = /merged:<([^ ]+)/.exec(args[args.indexOf('--search') + 1] ?? '')?.[1];
+      return json(prs.filter((pr) => pr.mergedAt && (!since || pr.mergedAt >= since) && (!until || pr.mergedAt < until))
+        .slice(0, limit).map((pr) => ({ number: pr.number, title: pr.title, body: pr.body ?? null, mergedAt: pr.mergedAt })));
+    }
+    if (args[0] === 'pr' && args[1] === 'view') {
+      const pr = find(Number(args[2]));
+      return json({ number: pr.number, state: pr.mergedAt ? 'MERGED' : pr.closed ? 'CLOSED' : 'OPEN',
+        mergeCommit: pr.mergeSha ? { oid: pr.mergeSha } : null, url: `https://github.com/${repo}/pull/${pr.number}` });
+    }
+    if (args[0] === 'pr' && args[1] === 'edit') {
+      const pr = find(Number(args[2]));
+      const add = args[args.indexOf('--add-label') + 1];
+      if (args.includes('--add-label') && add && !pr.labels!.includes(add)) pr.labels!.push(add);
+      args.forEach((value, index) => { if (value === '--remove-label') pr.labels = pr.labels!.filter((label) => label !== args[index + 1]); });
+      return '';
+    }
+    if (args[0] === 'pr' && args[1] === 'close') { find(Number(args[2])).closed = true; return ''; }
+    if (args[0] === 'pr' && args[1] === 'merge') {
+      const pr = find(Number(args[2]));
+      pr.mergedAt = now().toISOString();
+      pr.mergeSha ??= createHash('sha1').update(`${repo}#${pr.number}:${pr.head ?? `head${pr.number}`}`).digest('hex');
+      pr.closed = true;
+      pr.draft = false;
+      return '';
+    }
+    if (args[0] === 'label' && args[1] === 'create') return '';
+    throw new Error(`fake-gh: unexpected command ${call}`);
+  };
+  const run: FakeGh['run'] = (command, args) => {
+    if (command !== 'gh') throw new Error(`fake-gh: ${command} must use its own runner`);
+    try { return { status: 0, stdout: api([...args]), stderr: '' }; }
+    catch (error) {
+      const failure = error as Error & { stderr?: string };
+      return { status: 1, stdout: '', stderr: failure.stderr ?? failure.message ?? String(error) };
+    }
+  };
+  return { api, run, runAsync: async (command, args, cwd) => run(command, args, cwd), calls, prs };
+}