elanous 0.2.29 → 0.2.32

package/src/tui-client/dashboard-session.ts

@@ -201,6 +201,7 @@ export class DashboardSession {
       dispatchTool: opts.dispatchTool,
       ...(opts.onTurnComplete ? { onTurnComplete: opts.onTurnComplete } : {}),
       ...(opts.resolveModel ? { resolveModel: opts.resolveModel } : {}),
+      ...(opts.resolveSeat ? { resolveSeat: opts.resolveSeat } : {}),
       ...(opts.resolveMaxToolTurns
         ? { resolveMaxToolTurns: opts.resolveMaxToolTurns }
         : {}),
@@ -467,6 +468,14 @@ export class DashboardSession {
     this.sessionId = newSessionId;
   }
 
+  /** TUI-H8 ② — `/session new` 이 백엔드(ACP) 세션까지 새로 받는다. 같은 연결에서 `session/new` 를 다시 불러
+   *  새 id 로 갈아탄다(종전엔 TUI 기록만 비우고 ACP sessionId 가 그대로였다 · #69). 새 id 를 돌려준다. */
+  async renew(cwd: string): Promise<string> {
+    const { sessionId } = await this.client.newSession({ cwd, mcpServers: [] });
+    this.sessionId = sessionId;
+    return sessionId;
+  }
+
   /** Send a single user prompt and await the turn's stopReason.
    *  Streaming text deltas and tool / usage events are delivered via
    *  the optional callbacks on `req`. */

package/src/tui.ts

@@ -5,6 +5,7 @@
 import chalk from 'chalk';
 import { StringDecoder } from 'node:string_decoder';
 import { perf } from './perf-counters.js';
+import { noteInputLagKey, noteInputLagPaint } from './tui/input-lag-probe.js';
 import { debug } from './debug/log.js';
 
 // ── ANSI escape sequences ──
@@ -523,6 +524,12 @@ const _keyQueue: Key[] = [];
 export type KeyTraceSource = 'main' | 'stream' | 'input';
 
 let _keyTracer: ((key: Key, source: KeyTraceSource) => void) | null = null;
+let _lastHumanKeyAt = 0;
+
+/** 마지막으로 배달된 사람 키 시각(ms · 0 = 아직 없음) — 내부 턴 문(H2)의 조용창 판정에 쓴다. */
+export function lastHumanKeyAt(): number {
+  return _lastHumanKeyAt;
+}
 
 /** Install a tracer invoked with every dispatched Key. Set to null to
  *  detach. Exceptions thrown by the tracer are swallowed so a broken
@@ -534,6 +541,8 @@ export function setKeyTracer(fn: ((key: Key, source: KeyTraceSource) => void) |
 /** Call the installed tracer, if any. Safe to invoke unconditionally —
  *  becomes a noop when no tracer is registered. */
 export function traceKey(key: Key, source: KeyTraceSource): void {
+  // H2 내부 턴 문 — «마지막 사람 키» 시각. 빈 이름(readKey 취소·빈 깨움)·리스너 표지는 사람 키가 아니다.
+  if (key.name && !key.name.startsWith('listener-')) _lastHumanKeyAt = Date.now();
   if (!_keyTracer) return;
   try { _keyTracer(key, source); } catch { /* swallow — never break input */ }
 }
@@ -903,6 +912,7 @@ export function readKey(source: KeyTraceSource = 'main'): Promise<Key> {
       // split across chunk boundaries need a pending buffer that belongs
       // to this stream alone.
       const keys = _stdinParser.push(data);
+      if (keys.length > 0) noteInputLagKey(keys.length);
 
       // 2026-04-30 — also drain `_keyQueue` here so an `injectKey`
       // call that happened while `readKey` was already awaiting on
@@ -955,7 +965,9 @@ export function readKey(source: KeyTraceSource = 'main'): Promise<Key> {
  *  §8.6 — "(A) auto-Enter via injectKey" approach. */
 export function injectKey(key: Key): boolean {
   if (!_raw) return false;
+  noteInputLagKey();
   _keyQueue.push(key);
+  _injectedKeys.add(key);
   // Wake any in-flight readKey awaiting on stdin by emitting an empty
   // chunk. The handler's queue-drain branch picks up the injected key
   // immediately.
@@ -965,6 +977,38 @@ export function injectKey(key: Key): boolean {
   return true;
 }
 
+/** `injectKey` 로 들어온 키 표지 — `takeInjectedKeys` 가 stdin 잔여 키(readKey 몫)는 두고 주입 키만 꺼낸다. */
+const _injectedKeys = new WeakSet<Key>();
+
+/** ⭐ TUI-ESC-ABORT-TOOLS (2026-10-15) — 턴 중 스트리밍 리스너(`attachStreamingKeys`)가
+ *  바깥에서 주입된 키(`pty key` · 제어 IPC input-key → `injectKey`)를 받게 큐에서 꺼낸다.
+ *  ⛔ readKey 가 걸려 있으면(`_cancelReadKey`) 큐는 그 readKey 의 몫이다 — 빈 배열을 돌려준다.
+ *  ⛔ stdin 청크 잔여 키(readKey 가 넣은 것)는 건드리지 않는다. readKey 의 drain 동작은 그대로다. */
+export function takeInjectedKeys(): Key[] {
+  if (_cancelReadKey || _keyQueue.length === 0) return [];
+  const taken: Key[] = [];
+  for (let i = 0; i < _keyQueue.length; ) {
+    const k = _keyQueue[i]!;
+    if (_injectedKeys.has(k)) {
+      taken.push(k);
+      _keyQueue.splice(i, 1);
+    } else {
+      i += 1;
+    }
+  }
+  // 같은 Key 객체가 두 번 주입될 수 있으므로 표지는 다 꺼낸 «뒤에» 지운다.
+  for (const k of taken) _injectedKeys.delete(k);
+  return taken;
+}
+
+/** ⭐ H2 내부 턴 문 — 걸려 있는 readKey 를 «빈 키»로 깨운다(키를 만들지도 큐에 넣지도 않는다).
+ *  stdin 에 남은 바이트는 그대로 다음 readKey 몫이다. 걸린 readKey 가 없으면 false. */
+export function cancelPendingReadKey(): boolean {
+  if (!_cancelReadKey) return false;
+  _cancelReadKey();
+  return true;
+}
+
 /** 아직 readKey 가 소비하지 않은 키 수 — 외부 입력 대기열이 «사용자 키보다 앞서» 끼어들지 않게 본다. */
 export function pendingKeyCount(): number {
   return _keyQueue.length;
@@ -997,6 +1041,13 @@ export function resetRenderCache(): void {
   _lastFrameCols = 0;
 }
 
+/** True when the frame cache says `row` (0-based) currently shows
+ *  exactly `text` — a direct writer can skip repainting it. Invalidated
+ *  rows hold a sentinel that never matches. */
+export function renderCacheRowIs(row: number, text: string): boolean {
+  return row >= 0 && row < _lastFrameLines.length && _lastFrameLines[row] === text;
+}
+
 /** Invalidate a specific row in the frame cache without nuking the
  *  whole thing. Callers that do direct stdout writes to a narrow
  *  band (input prompt, cursor moves) use this instead of
@@ -1061,6 +1112,7 @@ export function render(lines: string[], opts: RenderOptions = {}): void {
   }
   perf.recordStdoutWrite(buf.length, true);
   perf.markDrawEnd();
+  noteInputLagPaint();
 
   _lastFrameLines = lines.slice(0, lineCount);
   _lastFrameRows = rows;

package/src/user-config/gemini-server-tools.ts

@@ -0,0 +1,9 @@
+export function parseGeminiServerTools(raw: unknown): { googleSearch?: boolean; codeExecution?: boolean; urlContext?: boolean } | undefined {
+  if (!raw || typeof raw !== 'object') return undefined;
+  const obj = raw as Record<string, unknown>;
+  const out: { googleSearch?: boolean; codeExecution?: boolean; urlContext?: boolean } = {};
+  if (obj.googleSearch === true) out.googleSearch = true;
+  if (obj.codeExecution === true) out.codeExecution = true;
+  if (obj.urlContext === true) out.urlContext = true;
+  return (Object.keys(out).length > 0) ? out : undefined;
+}

package/src/user-config.ts

@@ -71,6 +71,7 @@ import { migrateLegacyXdgUserConfig } from './storage/legacy-elanous-config-migr
 import { withFileLockSync } from './storage/file-lock.js';
 import { debug } from './debug/log.js';
 import { setConfigTimeZoneSource } from './time/format.js';
+import { parseGeminiServerTools } from './user-config/gemini-server-tools.js';
 import type { FoldMode } from './log-entry.js';
 import {
   CLAUDE_PACKAGE_MISSING,
@@ -85,6 +86,7 @@ import {
   parseGroundingSources,
   type GroundingConfig,
 } from './grounding/sources.js';
+import { parseSeatTurnCapConfig, type SeatTurnCapConfig } from './core-turn/seat-turn-cap.js';
 
 // ── SkillRouter (existing) ───────────────────────────────────────────
 
@@ -1544,6 +1546,8 @@ export function parseErrorReportsConfig(raw: unknown): ErrorReportsConfig | unde
 
 export interface ChatConfig {
   factQuestion: { maxToolTurns: number };
+  /** TUI-SEAT-TURN-CAP — 자리 TUI goal loop 한정 core 턴 상한 덮어쓰기(기본값 = core-turn/seat-turn-cap.ts). 설정했을 때만 있다. */
+  seatTurnCap?: Partial<SeatTurnCapConfig>;
   /** Short questions may receive a tool-free first reply. Default true. */
   fastPath: boolean;
   conciseness: ChatConcisenessConfig;
@@ -3656,6 +3660,8 @@ export interface OrchestratorLoopConfig {
   seatCaps: Record<OrchestratorSeat, number>;
   /** Max new delegations per tick; absent means no limit. */
   maxDelegatePerTick?: number;
+  /** Dispatch placement preference and local concurrency lane. Defaults preserve the existing Pod preference and one local lane. */
+  dispatch: { podTarget: number; localLane: number };
   /** Per-seat release gate; absent seats retain the spawn-budget default. */
   releaseGate?: Partial<Record<OrchestratorSeat, number>>;
   trafficMode: 'shadow' | 'live';
@@ -3673,7 +3679,7 @@ export interface OrchestratorLoopConfig {
 }
 
 export const ORCHESTRATOR_DEFAULTS: OrchestratorLoopConfig = {
-  mode: 'shadow', seatTrees: {}, seatCaps: { TC: 8, UX: 6, MK: 6, OP: 4 }, trafficMode: 'shadow', idleRequest: 'shadow', finishGate: 'shadow',
+  mode: 'shadow', seatTrees: {}, seatCaps: { TC: 8, UX: 6, MK: 6, OP: 4 }, dispatch: { podTarget: 18, localLane: 1 }, trafficMode: 'shadow', idleRequest: 'shadow', finishGate: 'shadow',
 };
 
 export function parseOrchestratorLoopConfig(raw: unknown): OrchestratorLoopConfig {
@@ -3696,7 +3702,14 @@ export function parseOrchestratorLoopConfig(raw: unknown): OrchestratorLoopConfi
   }
   const mode = value.mode === 'off' || value.mode === 'live' ? value.mode : 'shadow';
   const maxDelegatePerTick = value.maxDelegatePerTick;
-  return { mode, seatTrees, seatCaps,
+  const rawDispatch = value.dispatch && typeof value.dispatch === 'object' && !Array.isArray(value.dispatch)
+    ? value.dispatch as Record<string, unknown> : {};
+  const dispatch = { ...ORCHESTRATOR_DEFAULTS.dispatch };
+  for (const field of ['podTarget', 'localLane'] as const) {
+    const setting = rawDispatch[field];
+    if (typeof setting === 'number' && Number.isSafeInteger(setting) && setting >= 0) dispatch[field] = setting;
+  }
+  return { mode, seatTrees, seatCaps, dispatch,
     ...(typeof maxDelegatePerTick === 'number' && Number.isSafeInteger(maxDelegatePerTick) && maxDelegatePerTick >= 0 ? { maxDelegatePerTick } : {}),
     ...(Object.keys(releaseGate).length ? { releaseGate } : {}),
     trafficMode: value.trafficMode === 'live' ? 'live' : 'shadow',
@@ -3792,8 +3805,10 @@ export interface GateRemoteConfig {
   host?: string;
   /** Local 1-min load average above which checks go remote (default 20). */
   loadThreshold?: number;
-  /** Concurrent heavy checks per remote host (default and ceiling 2 — config may only lower it). */
+  /** Legacy default cap for hosts without an entry in hostCaps (1..2, default 2). */
   hostCap?: number;
+  /** Per SSH host concurrent heavy-check slots (1..8); overrides hostCap for that host. */
+  hostCaps?: Record<string, number>;
   /** Bare mirror on the host (default ~/mirror/elanous-agent.git — shared with the release gate). */
   mirror?: string;
   /** Seconds to wait for a free host slot before running locally (default 600). */
@@ -3811,6 +3826,12 @@ export function parseGateRemoteConfig(raw: unknown): GateRemoteConfig | undefine
     if (typeof v === 'number' && Number.isFinite(v) && v >= 0) out[key] = v;
   }
   if (typeof r.hostCap === 'number' && Number.isSafeInteger(r.hostCap) && r.hostCap > 0 && r.hostCap <= 2) out.hostCap = r.hostCap;
+  if (r.hostCaps && typeof r.hostCaps === 'object' && !Array.isArray(r.hostCaps)) {
+    const caps = Object.fromEntries(Object.entries(r.hostCaps).filter(([host, cap]) =>
+      /^(?:[\w.-]+@)?[\w.-]+$/.test(host) && !host.startsWith('-') &&
+      typeof cap === 'number' && Number.isSafeInteger(cap) && cap >= 1 && cap <= 8)) as Record<string, number>;
+    if (Object.keys(caps).length) out.hostCaps = caps;
+  }
   return Object.keys(out).length ? out : undefined;
 }
 
@@ -3871,7 +3892,7 @@ export interface UserConfig {
   guardian?: { mode?: 'shadow' | 'live'; /** Orphan CLI GC on the guardian tick: off = no ps collection, shadow (default) = evidence only, on = evidence then SIGTERM. */ orphanGc?: 'off' | 'shadow' | 'on' };
   /** Task-agent live move allow-list (`src/task-agent/live-moves.ts` validates its vocabulary).
    *  Absent = env ELANOUS_TASK_AGENT_LIVE_MOVES, else none (pure shadow). */
-  taskAgent?: { liveMoves?: string[]; /** TA-REJUDGE-PERIODIC — steward tick runs `tasks rejudge --all` every N minutes (absent/0 = off). */ rejudgeEveryMinutes?: number; /** 1-minute load average above which that tick is skipped (default 60). */ rejudgeMaxLoad?: number; /** TA-REPAIR-TICK-CAP — new repair launches per `tasks rejudge --all` (default 3, 0 = none). */ repairMaxPerTick?: number; parentHost?: { host?: string; cwd?: string; elanous?: string; configDir?: string; podPool?: string; approvalCapacity?: number } | Array<{ host?: string; cwd?: string; elanous?: string; configDir?: string; podPool?: string; approvalCapacity?: number }> };
+  taskAgent?: { liveMoves?: string[]; /** TA-REJUDGE-PERIODIC — steward tick runs `tasks rejudge --all` every N minutes (absent/0 = off). */ rejudgeEveryMinutes?: number; /** 1-minute load average above which that tick is skipped (default 60). */ rejudgeMaxLoad?: number; /** TA-REPAIR-TICK-CAP — new repair launches per `tasks rejudge --all` (default 3, 0 = none). */ repairMaxPerTick?: number; /** TA-LAND-AFTER-REVIEW — opt-in external queue adapter, never a direct merge command. */ landQueue?: { command: string; remote: string }; parentHost?: { host?: string; cwd?: string; elanous?: string; configDir?: string; podPool?: string; approvalCapacity?: number } | Array<{ host?: string; cwd?: string; elanous?: string; configDir?: string; podPool?: string; approvalCapacity?: number }> };
   events?: EventsConfig;
   /** GATE-REMOTE — see GateRemoteConfig. Absent = defaults (auto on · node-b · load 20 · cap 2). */
   gateRemote?: GateRemoteConfig;
@@ -3907,7 +3928,7 @@ export interface UserConfig {
   followUp?: 'shadow' | 'live';
 };
   /** ☸️ Pod 실행 칸 — `pool` = 기존 기본 풀(`컨텍스트[@ssh호스트][:상한][#k3d-레지스트리:포트]` 쉼표 · 앞이 우선). harness 실행은 인자·ELANOUS_POD_POOL·harness.podPool 다음으로 읽는다. */
-  pod?: { pool?: string; /** 호스트 Git 미러 디렉터리 — Pod Job 에 읽기 전용으로 마운트한다. */ hostMirror?: string; /** 원격 그라운딩 엔드포인트(호스트 nexus · tailnet 주소) — Pod 가 토큰으로 «질의→인용»만 묻는다(P13). */ groundingUrl?: string; /** 읽기 전용 Pod lease 권장에 쓰는 계정별 동시 수. */ lease?: { perAccount?: number }; /** 실측 권고를 Pod 발사 기본값으로 쓸지 (기본 off). */ memory?: { adviseDefaults?: boolean }; /** 명령 Job 자식 로그(child.log) 상한 바이트. 양의 정수만. 넘으면 끝부분 우선. */ childLogMaxBytes?: number };
+  pod?: { pool?: string; /** 호스트 Git 미러 디렉터리 — Pod Job 에 읽기 전용으로 마운트한다. */ hostMirror?: string; /** 원격 그라운딩 엔드포인트(호스트 nexus · tailnet 주소) — Pod 가 토큰으로 «질의→인용»만 묻는다(P13). */ groundingUrl?: string; /** 읽기 전용 Pod lease 권장에 쓰는 계정별 동시 수. */ lease?: { perAccount?: number }; /** 실측 권고를 Pod 발사 기본값으로 쓸지 (기본 off). */ memory?: { adviseDefaults?: boolean }; /** 명령 Job 자식 로그(child.log) 상한 바이트. 양의 정수만. 넘으면 끝부분 우선. */ childLogMaxBytes?: number; /** warm Pod 재사용 실전 손잡이(소비자별 · 기본 off · 문자 그대로 true 만). 판정 = pod-warm-switch.ts `decideWarmReuse` — 증거가 모자라면 flag 가 켜져도 off. */ warmReuse?: { gateRecheck?: boolean; land?: boolean; ta?: boolean; /** 연속 일치 표본 하한(양의 정수 · 기본 3). */ minMatchSamples?: number } };
   skillRouter: SkillRouterConfig;
   llm: LLMConfig;
   skills: SkillsConfig;
@@ -4195,7 +4216,21 @@ function parseTaskAgentConfig(raw: unknown): UserConfig['taskAgent'] {
     if (Number.isSafeInteger(repairMaxPerTick) && (repairMaxPerTick as number) >= 0) rejudge.repairMaxPerTick = repairMaxPerTick as number;
     else warnUserConfigDrop('taskAgent.repairMaxPerTick', `음이 아닌 정수가 아니다(${JSON.stringify(repairMaxPerTick)}) — 기본 3`);
   }
-  const extras = { ...rejudge, ...(parentHost ? { parentHost } : {}) };
+  const queueRaw = (raw as Record<string, unknown>).landQueue;
+  let landQueue: { command: string; remote: string } | undefined;
+  if (queueRaw !== undefined) {
+    if (queueRaw && typeof queueRaw === 'object' && !Array.isArray(queueRaw)
+      && typeof (queueRaw as Record<string, unknown>).command === 'string'
+      && isAbsolute((queueRaw as Record<string, string>).command)
+      && typeof (queueRaw as Record<string, unknown>).remote === 'string'
+      && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test((queueRaw as Record<string, string>).remote)) {
+      landQueue = { command: (queueRaw as Record<string, string>).command, remote: (queueRaw as Record<string, string>).remote };
+    } else {
+      warnUserConfigDrop('taskAgent.landQueue', '절대 command 경로와 유효한 remote 호스트가 필요 — 착지 fail-closed');
+      landQueue = { command: '', remote: '' };
+    }
+  }
+  const extras = { ...rejudge, ...(parentHost ? { parentHost } : {}), ...(landQueue ? { landQueue } : {}) };
   const liveMoves = (raw as Record<string, unknown>).liveMoves;
   if (liveMoves === undefined) return Object.keys(extras).length ? extras : undefined;
   // 설정이 «있으면» 환경 변수로 내려가지 않는다 — 배열이 아니면 빈 목록(fail-closed), 문자열 밖 항목은 글자로 바꿔 넘겨
@@ -5083,6 +5118,17 @@ export function buildUserConfig(path: string = defaultPath()): UserConfig {
         return typeof lease.perAccount === 'number' && Number.isSafeInteger(lease.perAccount) && lease.perAccount > 0
           ? lease.perAccount : 4;
       })() },
+      warmReuse: (() => {
+        const warm = legacyPod.warmReuse && typeof legacyPod.warmReuse === 'object' && !Array.isArray(legacyPod.warmReuse)
+          ? (legacyPod.warmReuse as Record<string, unknown>) : {};
+        return {
+          gateRecheck: warm.gateRecheck === true,
+          land: warm.land === true,
+          ta: warm.ta === true,
+          minMatchSamples: typeof warm.minMatchSamples === 'number' && Number.isSafeInteger(warm.minMatchSamples) && warm.minMatchSamples > 0
+            ? warm.minMatchSamples : 3,
+        };
+      })(),
     },
     harness: {
       edgeRail: (() => {
@@ -5452,6 +5498,7 @@ export function buildUserConfig(path: string = defaultPath()): UserConfig {
           && Number.isSafeInteger(chatFactQuestion.maxToolTurns) && chatFactQuestion.maxToolTurns > 0
           ? chatFactQuestion.maxToolTurns : CHAT_DEFAULTS.factQuestion.maxToolTurns,
       },
+      ...((): { seatTurnCap?: Partial<SeatTurnCapConfig> } => { const c = parseSeatTurnCapConfig(chat.seatTurnCap); return c ? { seatTurnCap: c } : {}; })(),
       fastPath: chat.fastPath === false || chat.fastPath === 'false' ? false : CHAT_DEFAULTS.fastPath,
       conciseness: {
         enabled: chatConciseness.enabled === false ? false : CHAT_CONCISENESS_DEFAULTS.enabled,
@@ -7078,16 +7125,6 @@ function parseMemoryJudge(raw: unknown): { enabled?: boolean; model?: string; cr
   return (out.enabled !== undefined || out.model !== undefined || out.crossRecall !== undefined) ? out : undefined;
 }
 
-function parseGeminiServerTools(raw: unknown): { googleSearch?: boolean; codeExecution?: boolean; urlContext?: boolean } | undefined {
-  if (!raw || typeof raw !== 'object') return undefined;
-  const obj = raw as Record<string, unknown>;
-  const out: { googleSearch?: boolean; codeExecution?: boolean; urlContext?: boolean } = {};
-  if (obj.googleSearch === true) out.googleSearch = true;
-  if (obj.codeExecution === true) out.codeExecution = true;
-  if (obj.urlContext === true) out.urlContext = true;
-  return (Object.keys(out).length > 0) ? out : undefined;
-}
-
 function parseAnswerPriority(raw: unknown): 'cost' | 'balanced' | 'quality' | 'exhaustive' | undefined {
   return raw === 'cost' || raw === 'balanced' || raw === 'quality' || raw === 'exhaustive'
     ? raw

package/src/util/spawn-sync-output.ts

@@ -1,5 +1,12 @@
 import { spawnSync, type SpawnSyncOptionsWithStringEncoding } from 'node:child_process';
 
+/**
+ * Default maxBuffer for harness · Pod · gate `spawnSync` calls that read child output.
+ * Node's 1 MiB default truncated `git ls-files` (1.54 MiB in W2b · 0.2.30 HARD #3) — same value as #28476.
+ * The ratchet `test/spawn-sync-max-buffer.test.ts` keeps new readers in those trees on an explicit maxBuffer.
+ */
+export const SPAWN_SYNC_MAX_BUFFER = 16 * 1024 * 1024;
+
 /** Read command text completely or fail closed; never return a partial stdout. */
 export function spawnSyncText(
   cmd: string,

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

@@ -0,0 +1,154 @@
+// Fake executables on PATH for tests whose code under test spawns an external CLI
+// (grok · magick · tesseract · …) that a gate Pod does not have.
+//
+// The industry-standard shape is a «PATH shim»: a tiny shell script with the real
+// name, placed first on PATH. This module only makes that shape shared, so tests
+// stop hand-writing `writeFileSync + chmodSync` (MOCK-REVIEW R6 · MOCK-DEVICES-2 ⓑ).
+//
+// Bun resolves a child's executable from the PATH the process STARTED with when the
+// call passes no `env`; `test/preload-child-env.ts` makes a later PATH change visible
+// to such calls. Code that passes its own `env` must receive `fakeBins.env` (or a
+// PATH built from `fakeBins.path()`).
+//
+// ⛔ 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 { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { delimiter, join } from 'node:path';
+
+export interface FakeBinSpec {
+  readonly stdout?: string;
+  readonly stderr?: string;
+  /** Exit code (default 0). */
+  readonly exitCode?: number;
+  /** Stay alive this long before exiting — for long-running daemons a test kills. */
+  readonly sleepSeconds?: number;
+}
+
+export interface FakeBinCall {
+  readonly name: string;
+  readonly argv: readonly string[];
+}
+
+export interface FakeBins {
+  /** Directory holding the fake executables. */
+  readonly dir: string;
+  /** Absolute path of one fake executable. */
+  bin(name: string): string;
+  /** PATH with the fake directory first (default base: the current PATH). */
+  path(base?: string): string;
+  /** `process.env` with the fake PATH, for code that passes its own `env`. */
+  readonly env: NodeJS.ProcessEnv;
+  /** Every recorded invocation, in order. */
+  calls(): FakeBinCall[];
+  /** Resolve once at least `count` invocations are recorded (a spawned child records asynchronously). */
+  waitForCalls(count: number, timeoutMs?: number): Promise<FakeBinCall[]>;
+  cleanup(): void;
+}
+
+const NAME = /^[A-Za-z0-9._+-]+$/;
+
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+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
+  // separator \x1e (a second printf). `calls()` drops the unterminated tail, so a reader never sees half a record.
+  lines.push(`{ printf '%s\\0' ${shellQuote(name)} "$@"; printf '\\036'; } >> ${shellQuote(logPath)}`);
+  if (spec.stdout !== undefined) {
+    const file = join(dataDir, `${name}.stdout`);
+    writeFileSync(file, spec.stdout);
+    lines.push(`cat ${shellQuote(file)}`);
+  }
+  if (spec.stderr !== undefined) {
+    const file = join(dataDir, `${name}.stderr`);
+    writeFileSync(file, spec.stderr);
+    lines.push(`cat ${shellQuote(file)} >&2`);
+  }
+  const exitCode = spec.exitCode ?? 0;
+  if (spec.sleepSeconds !== undefined && spec.sleepSeconds > 0) {
+    const seconds = Math.ceil(spec.sleepSeconds);
+    // exit 0: `exec` so killing the fake kills the sleep itself. Any other code needs the shell to
+    // outlive the sleep; a fake killed mid-sleep then leaves `sleep` until `sleepSeconds` ends.
+    if (exitCode === 0) lines.push(`exec sleep ${seconds}`);
+    else lines.push(`sleep ${seconds}`);
+  }
+  lines.push(`exit ${exitCode}`);
+  return `${lines.join('\n')}\n`;
+}
+
+export function createFakeBins(specs: Readonly<Record<string, FakeBinSpec>>): FakeBins {
+  for (const name of Object.keys(specs)) {
+    if (!NAME.test(name) || name === '.' || name === '..') throw new Error(`fake-bin: invalid executable name ${JSON.stringify(name)}`);
+  }
+  const root = mkdtempSync(join(tmpdir(), 'ux-sim-fake-bin-'));
+  const dir = join(root, 'bin');
+  const dataDir = join(root, 'data');
+  const logPath = join(root, 'calls.log');
+  try {
+    mkdirSync(dir);
+    mkdirSync(dataDir);
+    writeFileSync(logPath, '');
+    for (const [name, spec] of Object.entries(specs)) {
+      const file = join(dir, name);
+      writeFileSync(file, script(name, spec, dataDir, logPath));
+      chmodSync(file, 0o755);
+    }
+  } catch (error) {
+    rmSync(root, { recursive: true, force: true });
+    throw error;
+  }
+  const path = (base = process.env.PATH ?? '') => (base ? `${dir}${delimiter}${base}` : dir);
+  return {
+    dir,
+    bin: (name) => join(dir, name),
+    path,
+    get env() {
+      return { ...process.env, PATH: path() };
+    },
+    calls() {
+      if (!existsSync(logPath)) return [];
+      // The segment after the last separator is either empty or a record still being written — never count it.
+      return readFileSync(logPath, 'utf8')
+        .split('\x1e')
+        .slice(0, -1)
+        .map((record) => {
+          const [name = '', ...argv] = record.split('\0').slice(0, -1);
+          return { name, argv };
+        });
+    },
+    async waitForCalls(count, timeoutMs = 5_000) {
+      const deadline = Date.now() + timeoutMs;
+      for (;;) {
+        const recorded = this.calls();
+        if (recorded.length >= count) return recorded;
+        if (Date.now() >= deadline) throw new Error(`fake-bin: expected ${count} call(s) within ${timeoutMs}ms, saw ${recorded.length}`);
+        await new Promise((resolve) => setTimeout(resolve, 20));
+      }
+    },
+    cleanup: () => rmSync(root, { recursive: true, force: true }),
+  };
+}
+
+/**
+ * Put fake executables first on `process.env.PATH` for the duration of `run`,
+ * then restore PATH and remove the files — also when `run` throws.
+ */
+export async function withFakeBins<T>(
+  specs: Readonly<Record<string, FakeBinSpec>>,
+  run: (fakeBins: FakeBins) => T | Promise<T>,
+): Promise<T> {
+  const fakeBins = createFakeBins(specs);
+  const previousPath = process.env.PATH;
+  process.env.PATH = fakeBins.path(previousPath ?? '');
+  try {
+    return await run(fakeBins);
+  } finally {
+    if (previousPath === undefined) delete process.env.PATH;
+    else process.env.PATH = previousPath;
+    fakeBins.cleanup();
+  }
+}

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

@@ -0,0 +1,36 @@
+// Bun's real test timer implementation, scoped so exceptions cannot leave
+// Date or timers mocked for the next test. Use only in serial tests: timer
+// replacement is process-global and does not affect child processes.
+import { jest } from 'bun:test';
+
+export interface SimClock {
+  tick(ms: number): void;
+  setTime(now: number | Date): void;
+  now(): number;
+  pendingTimers(): number;
+}
+
+let active = false;
+
+export async function withSimClock<T>(now: number | Date, run: (clock: SimClock) => Promise<T> | T): Promise<T> {
+  if (active) throw new Error('sim clock is process-global; run scenarios serially');
+  active = true;
+  try {
+    jest.useFakeTimers({ now });
+    const clock: SimClock = {
+      tick(ms) {
+        if (!Number.isFinite(ms) || ms < 0) throw new Error('sim clock tick must be a nonnegative finite number');
+        jest.advanceTimersByTime(ms);
+      },
+      setTime(value) { jest.setSystemTime(value); },
+      now() { return Date.now(); },
+      pendingTimers() { return jest.getTimerCount(); },
+    };
+    return await run(clock);
+  }
+  finally {
+    jest.clearAllTimers();
+    jest.useRealTimers();
+    active = false;
+  }
+}

package/src/ux-sim/headless-tui.ts

@@ -0,0 +1,72 @@
+// Capture the real dashboard/tui renderer at the stdout boundary, then let
+// the already-installed xterm parser interpret its ANSI bytes. No child PTY.
+import { Terminal } from '@xterm/headless';
+import { renderDashboardFrame, type DashboardFrameInput } from '../dashboard/index.js';
+import { resetRenderCache } from '../tui.js';
+
+export interface HeadlessDashboardFrame {
+  lines: string[];
+  input: DashboardFrameInput;
+}
+
+export interface HeadlessDashboardSnapshot {
+  bytes: string;
+  lines: string[];
+  cursor: { row: number; col: number };
+}
+
+let capturing = false;
+
+/** Serial-only: stdout and tui's frame cache are process globals. */
+export async function simHeadlessDashboardFrames(
+  frames: readonly HeadlessDashboardFrame[],
+  size: { rows: number; cols: number } = { rows: 30, cols: 100 },
+): Promise<HeadlessDashboardSnapshot[]> {
+  if (capturing) throw new Error('headless TUI simulation is already capturing stdout');
+  if (size.rows < 1 || size.cols < 1) throw new Error('headless TUI size must be positive');
+  const terminal = new Terminal({ rows: size.rows, cols: size.cols, scrollback: 0, allowProposedApi: true });
+  capturing = true;
+  const stdout = process.stdout;
+  const originalWrite = stdout.write;
+  const originalRows = Object.getOwnPropertyDescriptor(stdout, 'rows');
+  const originalColumns = Object.getOwnPropertyDescriptor(stdout, 'columns');
+  const snapshots: HeadlessDashboardSnapshot[] = [];
+  try {
+    Object.defineProperty(stdout, 'rows', { configurable: true, value: size.rows });
+    Object.defineProperty(stdout, 'columns', { configurable: true, value: size.cols });
+    resetRenderCache();
+    for (const frame of frames) {
+      const chunks: string[] = [];
+      stdout.write = ((chunk: string | Uint8Array, encoding?: BufferEncoding | ((error?: Error | null) => void), callback?: (error?: Error | null) => void) => {
+        chunks.push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString());
+        const done = typeof encoding === 'function' ? encoding : callback;
+        done?.(null);
+        return true;
+      }) as typeof stdout.write;
+      try {
+        renderDashboardFrame(frame.lines, frame.input);
+      } finally {
+        stdout.write = originalWrite;
+      }
+      const bytes = chunks.join('');
+      await new Promise<void>((resolve) => terminal.write(bytes, resolve));
+      const buffer = terminal.buffer.active;
+      snapshots.push({
+        bytes,
+        lines: Array.from({ length: size.rows }, (_, row) =>
+          buffer.getLine(buffer.viewportY + row)?.translateToString(true) ?? ''),
+        cursor: { row: buffer.cursorY + 1, col: buffer.cursorX + 1 },
+      });
+    }
+    return snapshots;
+  } finally {
+    stdout.write = originalWrite;
+    if (originalRows) Object.defineProperty(stdout, 'rows', originalRows);
+    else Reflect.deleteProperty(stdout, 'rows');
+    if (originalColumns) Object.defineProperty(stdout, 'columns', originalColumns);
+    else Reflect.deleteProperty(stdout, 'columns');
+    resetRenderCache();
+    terminal.dispose();
+    capturing = false;
+  }
+}

package/src/ux-sim/in-process-cli.ts

@@ -23,6 +23,7 @@ export interface InProcessCliOptions {
 type MutableCommand = {
   commands: MutableCommand[];
   name(): string;
+  aliases(): string[];
   _optionValues?: Record<string, unknown>;
   _optionValueSources?: Record<string, string>;
   args: string[];
@@ -35,7 +36,7 @@ function registeredCommandPath(root: MutableCommand, args: readonly string[]): s
   let command = root;
   for (const arg of args) {
     if (arg.startsWith('-')) break;
-    const child = command.commands.find((candidate) => candidate.name() === arg);
+    const child = command.commands.find((candidate) => candidate.name() === arg || candidate.aliases().includes(arg));
     if (!child) break;
     path.push(arg);
     command = child;