elanous 0.2.41 → 0.2.43

package/src/ux-sim/scenario.ts

@@ -1,21 +1,29 @@
-import { closeSync, constants, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, realpathSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
+import { closeSync, constants, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { extname, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createHash, randomUUID } from 'node:crypto';
 import { parse as parseYaml } from 'yaml';
 import { debug } from '../debug/log.js';
+import type { LogSink } from '../mss/logging/sink.js';
 import { streamCodexResponsesEvents } from '../llm.js';
 import { LogStore, StoreSink, type LogStoreRow } from '../mss/logging/log-store.js';
 import { getTestStateRoot } from '../nexus/paths.js';
 import { simRenderLogFrame } from './render-frame.js';
+import { assessDraftInventory, buildDraftInventory } from './draft-inventory-builder.js';
+
+export type ScenarioTrigger = {
+  id: string;
+  type: 'codex.responses.fetch' | 'codex.responses.fetch-network-error' | 'ux.draft-inventory.evaluate';
+  status?: number;
+  count?: number;
+};
 
 export interface ScenarioV0 {
   version: 0;
   id: string;
   isolation: 'test';
   seed: number;
-  triggers: [{ id: string; type: 'codex.responses.fetch' | 'codex.responses.fetch-network-error'; status?: number; count?: number }];
+  triggers: [ScenarioTrigger];
   expect: {
     screen: { mode: 'widget'; snapshot: { contains: string[]; excludes?: string[] } };
     logs: [{ category: string; event: string; level: string; count?: number; data?: Record<string, unknown> }];
@@ -24,8 +32,10 @@ export interface ScenarioV0 {
 
 export interface ScenarioResult {
   id: string;
+  runId: string;
   seed: number;
   evidenceArtifact: string;
+  runEvidence: { category: string; event: string; persisted: boolean };
   pass: boolean;
   trigger: { id: string; type: string; status: number | null; expectedCount: number; fetchCount: number; error: string | null };
   screen: { pass: boolean; containsMissing: string[]; excludesFound: string[]; snapshot: string };
@@ -35,6 +45,7 @@ export interface ScenarioResult {
 
 let previousScenarioTurn: Promise<void> = Promise.resolve();
 const REPOSITORY_ROOT = fileURLToPath(new URL('../..', import.meta.url));
+const SENSITIVE_EXPECTATION_KEY = /(?:token|secret|password|prompt|authorization|credential|api.?key|request.?body)/i;
 
 function record(value: unknown, where: string): Record<string, unknown> {
   if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${where} must be an object`);
@@ -46,6 +57,21 @@ function exactKeys(value: Record<string, unknown>, allowed: readonly string[], w
   if (extra.length) throw new Error(`${where} has unsupported key(s): ${extra.join(', ')}`);
 }
 
+function validateExpectationData(value: Record<string, unknown>, where = 'scenario.expect.logs[0].data'): void {
+  for (const [key, entry] of Object.entries(value)) {
+    if (SENSITIVE_EXPECTATION_KEY.test(key)) throw new Error(`${where} cannot include sensitive field: ${key}`);
+    if (entry && typeof entry === 'object' && !Array.isArray(entry)) {
+      validateExpectationData(entry as Record<string, unknown>, `${where}.${key}`);
+    } else if (Array.isArray(entry)) {
+      entry.forEach((item, index) => {
+        if (item && typeof item === 'object' && !Array.isArray(item)) {
+          validateExpectationData(item as Record<string, unknown>, `${where}.${key}[${index}]`);
+        }
+      });
+    }
+  }
+}
+
 function requiredString(value: unknown, where: string): string {
   if (typeof value !== 'string' || value.trim() === '') throw new Error(`${where} must be a non-empty string`);
   return value;
@@ -64,10 +90,11 @@ export function parseScenarioV0(source: string): ScenarioV0 {
   const trigger = record(value.triggers[0], 'scenario.triggers[0]');
   exactKeys(trigger, ['id', 'type', 'status', 'count'], 'scenario.triggers[0]');
   const triggerId = requiredString(trigger.id, 'scenario.triggers[0].id');
-  if (trigger.type !== 'codex.responses.fetch' && trigger.type !== 'codex.responses.fetch-network-error') throw new Error(`unregistered scenario trigger: ${String(trigger.type)}`);
+  if (trigger.type !== 'codex.responses.fetch' && trigger.type !== 'codex.responses.fetch-network-error' && trigger.type !== 'ux.draft-inventory.evaluate') throw new Error(`unregistered scenario trigger: ${String(trigger.type)}`);
   if (trigger.type === 'codex.responses.fetch' && (!Number.isInteger(trigger.status) || (trigger.status as number) < 400 || (trigger.status as number) > 499)) throw new Error('codex.responses.fetch.status must be an HTTP 4xx status');
-  if (trigger.type === 'codex.responses.fetch-network-error' && trigger.status !== undefined) throw new Error('codex.responses.fetch-network-error does not accept status');
+  if ((trigger.type === 'codex.responses.fetch-network-error' || trigger.type === 'ux.draft-inventory.evaluate') && trigger.status !== undefined) throw new Error(`${trigger.type} does not accept status`);
   if (trigger.count !== undefined && (!Number.isInteger(trigger.count) || (trigger.count as number) < 1)) throw new Error('codex.responses.fetch.count must be a positive integer');
+  if (trigger.type === 'ux.draft-inventory.evaluate' && trigger.count !== 200) throw new Error('ux.draft-inventory.evaluate.count must be 200');
 
   const expect = record(value.expect, 'scenario.expect');
   exactKeys(expect, ['screen', 'logs'], 'scenario.expect');
@@ -88,17 +115,26 @@ export function parseScenarioV0(source: string): ScenarioV0 {
   exactKeys(expectedLog, ['category', 'event', 'level', 'count', 'data'], 'scenario.expect.logs[0]');
   const category = requiredString(expectedLog.category, 'scenario.expect.logs[0].category');
   const event = requiredString(expectedLog.event, 'scenario.expect.logs[0].event');
+  if (category === 'ux.sim.scenario' && event === 'completed') {
+    throw new Error('scenario.expect.logs cannot use reserved event ux.sim.scenario/completed');
+  }
   const level = requiredString(expectedLog.level, 'scenario.expect.logs[0].level');
   if (expectedLog.count !== undefined && (!Number.isInteger(expectedLog.count) || (expectedLog.count as number) < 0)) throw new Error('scenario.expect.logs[0].count must be a non-negative integer');
   if (expectedLog.count === 0 && trigger.type !== 'codex.responses.fetch-network-error') throw new Error('zero expected log events are allowed only for codex.responses.fetch-network-error');
-  if (expectedLog.data !== undefined) record(expectedLog.data, 'scenario.expect.logs[0].data');
+  if (expectedLog.data !== undefined) {
+    const data = record(expectedLog.data, 'scenario.expect.logs[0].data');
+    validateExpectationData(data);
+    if (category === 'llm.codex' && event === 'request-rejected-shape' && 'status' in data && typeof data.status !== 'number') {
+      throw new Error('scenario.expect.logs[0].data.status must be numeric');
+    }
+  }
 
   return {
     version: 0,
     id,
     isolation: 'test',
     seed: value.seed as number,
-    triggers: [{ id: triggerId, type: trigger.type, ...(trigger.status !== undefined ? { status: trigger.status as number } : {}), ...(trigger.count !== undefined ? { count: trigger.count as number } : {}) }],
+    triggers: [{ id: triggerId, type: trigger.type as ScenarioTrigger['type'], ...(trigger.status !== undefined ? { status: trigger.status as number } : {}), ...(trigger.count !== undefined ? { count: trigger.count as number } : {}) }],
     expect: {
       screen: {
         mode: 'widget',
@@ -191,61 +227,155 @@ export async function runScenarioV0(scenario: ScenarioV0): Promise<ScenarioResul
 }
 
 async function runScenarioV0Exclusive(scenario: ScenarioV0): Promise<ScenarioResult> {
-  const root = mkdtempSync(join(tmpdir(), `ux-sim-${scenario.id}-`));
-  const store = new LogStore(join(root, 'logs.db'), { instance: `ux-sim:${scenario.id}` });
-  const sink = new StoreSink(store, `ux-sim:${scenario.id}`, { installExitHandlers: false });
+  const stateRoot = getTestStateRoot()!;
+  assertNoSymlinkComponents(stateRoot);
+  mkdirSync(stateRoot, { recursive: true });
+  if (!lstatSync(stateRoot).isDirectory()) throw new Error('scenario test-state root must be a directory');
+  const logsDir = join(stateRoot, 'logs');
+  assertNoSymlinkComponents(logsDir);
+  mkdirSync(logsDir, { recursive: true });
+  assertNoSymlinkComponents(logsDir);
+  if (!lstatSync(logsDir).isDirectory()) throw new Error('scenario logs path must be a directory');
+  const logsPath = join(logsDir, 'logs.db');
+  assertNoSymlinkComponents(logsPath);
+  try {
+    const logsStat = lstatSync(logsPath);
+    if (!logsStat.isFile()) throw new Error('scenario logs path must be a regular file');
+    if (logsStat.nlink > 1) throw new Error('scenario logs path must not be a hardlink');
+  } catch (error) {
+    if (error instanceof Error && error.message === 'scenario logs path must be a regular file') throw error;
+    if (error instanceof Error && error.message === 'scenario logs path must not be a hardlink') throw error;
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+  }
+  const runId = randomUUID();
+  const instance = `ux-sim:${scenario.id}:${runId}`;
+  const store = new LogStore(logsPath, { instance });
+  const storeSink = new StoreSink(store, instance, { installExitHandlers: false });
+  const expectedLog = scenario.expect.logs[0];
+  const trigger = scenario.triggers[0];
+  const sink: LogSink = {
+    name: storeSink.name,
+    emit(rec) {
+      if (rec.category === 'ux.sim.scenario' && rec.event === 'completed') {
+        const data = rec.data && typeof rec.data === 'object' ? rec.data as Record<string, unknown> : {};
+        storeSink.emit({
+          ts: rec.ts,
+          category: rec.category,
+          event: rec.event,
+          data: { runId, scenarioId: scenario.id, deviceVerdict: data.deviceVerdict },
+        });
+      } else if (rec.category === expectedLog?.category && rec.event === expectedLog.event) {
+        storeSink.emit({
+          ts: rec.ts,
+          category: rec.category,
+          event: rec.event,
+          level: rec.level,
+          ...(expectedLog.data ? {
+            data: trigger.type === 'ux.draft-inventory.evaluate'
+              ? { runId, ...projectSubset(rec.data, expectedLog.data) }
+              : projectSubset(rec.data, expectedLog.data),
+          } : {}),
+        });
+      }
+    },
+  };
   const off = debug.registerSink(sink);
   const originalFetch = globalThis.fetch;
-  const trigger = scenario.triggers[0];
   let errorMessage: string | null = null;
   let fetchCount = 0;
-  globalThis.fetch = (async (input: RequestInfo | URL) => {
-    fetchCount++;
-    if (String(input) !== 'https://chatgpt.com/backend-api/codex/responses') throw new Error('scenario fake fetch received an unregistered URL');
-    if (trigger.type === 'codex.responses.fetch-network-error') throw new Error(`scenario network error seed=${scenario.seed}`);
-    return new Response('{"detail":"Bad Request"}', { status: trigger.status!, headers: { 'content-type': 'application/json' } });
-  }) as unknown as typeof fetch;
+  let triggerObserved = false;
+  let screenLines: string[] = [];
+  if (trigger.type.startsWith('codex.')) {
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      fetchCount++;
+      if (String(input) !== 'https://chatgpt.com/backend-api/codex/responses') throw new Error('scenario fake fetch received an unregistered URL');
+      if (trigger.type === 'codex.responses.fetch-network-error') throw new Error(`scenario network error seed=${scenario.seed}`);
+      return new Response('{"detail":"Bad Request"}', { status: trigger.status!, headers: { 'content-type': 'application/json' } });
+    }) as unknown as typeof fetch;
+  }
 
   try {
-    try {
-      for await (const _event of streamCodexResponsesEvents('https://chatgpt.com/backend-api/codex/responses', 'scenario-fake-token', {
-        model: 'gpt-6-sol',
-        instructions: 'scenario test request',
-        input: [{ role: 'user', content: [{ type: 'input_text', text: `scenario test input seed=${scenario.seed}` }] }],
-        tools: [{ type: 'function', name: 'RunShell', description: 'test tool', parameters: {} }],
-      }, undefined, { promptCache: false })) { /* consume the deterministic fake response */ }
-    } catch (error) {
-      errorMessage = error instanceof Error ? error.message : String(error);
+    if (trigger.type === 'ux.draft-inventory.evaluate') {
+      const result = assessDraftInventory(buildDraftInventory(trigger.count));
+      const data = {
+        runId,
+        total: result.total,
+        byScenario: result.byScenario,
+        byAction: result.byAction,
+        triageByAction: result.triageByAction,
+        mismatchCount: result.mismatches.length,
+        protectedOrRunningClosed: result.protectedOrRunningClosed,
+      };
+      debug.log('ux.sim.draft-inventory', 'assessed', data);
+      screenLines = [
+        'Draft inventory simulation',
+        `total=${result.total}`,
+        `mismatches=${result.mismatches.length}`,
+        `protectedOrRunningClosed=${result.protectedOrRunningClosed}`,
+      ];
+      triggerObserved = result.total === trigger.count
+        && Object.values(result.byScenario).every((count) => count === 25)
+        && result.mismatches.length === 0
+        && result.protectedOrRunningClosed === 0;
+    } else {
+      try {
+        for await (const _event of streamCodexResponsesEvents('https://chatgpt.com/backend-api/codex/responses', 'scenario-fake-token', {
+          model: 'gpt-6-sol',
+          instructions: 'scenario test request',
+          input: [{ role: 'user', content: [{ type: 'input_text', text: `scenario test input seed=${scenario.seed}` }] }],
+          tools: [{ type: 'function', name: 'RunShell', description: 'test tool', parameters: {} }],
+        }, undefined, { promptCache: false })) { /* consume the deterministic fake response */ }
+      } catch (error) {
+        errorMessage = error instanceof Error ? error.message : String(error);
+      }
+      triggerObserved = fetchCount === (trigger.count ?? 1) && errorMessage !== null;
+      screenLines = errorMessage ? [errorMessage] : [];
     }
 
-    const screenText = simRenderLogFrame({ phase: 'idle', lines: errorMessage ? [errorMessage] : [] }, { width: 100, height: 12 }).text;
+    const screenText = simRenderLogFrame({ phase: 'idle', lines: screenLines }, { width: 100, height: 12 }).text;
     const containsMissing = scenario.expect.screen.snapshot.contains.filter((fragment) => !screenText.includes(fragment));
     const excludesFound = (scenario.expect.screen.snapshot.excludes ?? []).filter((fragment) => screenText.includes(fragment));
 
-    sink.flush();
+    storeSink.flush();
     const expected = scenario.expect.logs[0];
-    const rows = store.query({ exactCategories: [expected.category], events: [expected.event], limit: 1000 });
+    const rows = store.query({ exactCategories: [expected.category], events: [expected.event], instances: [instance], limit: 1000 });
     const expectedCount = expected.count ?? 1;
     const levelMismatch = rows.some((row) => row.level !== expected.level);
     const dataMismatch = expected.data ? rows.flatMap((row) => matchesSubset(rowData(row), expected.data!)) : [];
     const logPass = rows.length === expectedCount && !levelMismatch && dataMismatch.length === 0;
     const screenPass = containsMissing.length === 0 && excludesFound.length === 0;
     const failureReasons: string[] = [];
-    const expectedTriggerCount = trigger.count ?? 1;
-    if (fetchCount !== expectedTriggerCount) failureReasons.push(`trigger-count-mismatch:expected-${expectedTriggerCount}-observed-${fetchCount}`);
-    if (errorMessage === null) failureReasons.push('provider-error-not-observed');
+    const expectedTriggerCount = trigger.type.startsWith('codex.') ? trigger.count ?? 1 : 1;
+    const observedTriggerCount = trigger.type.startsWith('codex.') ? fetchCount : triggerObserved ? 1 : 0;
+    if (trigger.type.startsWith('codex.') && fetchCount !== expectedTriggerCount) failureReasons.push(`trigger-count-mismatch:expected-${expectedTriggerCount}-observed-${fetchCount}`);
+    if (!triggerObserved) failureReasons.push(trigger.type.startsWith('codex.') ? 'provider-error-not-observed' : 'draft-inventory-evaluation-failed');
     if (!screenPass) failureReasons.push('screen-snapshot-mismatch');
     if (rows.length === 0 && expectedCount > 0) failureReasons.push('expected-log-event-absent');
     else if (rows.length !== expectedCount) failureReasons.push(`log-event-count-mismatch:expected-${expectedCount}-observed-${rows.length}`);
     if (levelMismatch) failureReasons.push(`log-level-mismatch:expected-${expected.level}-observed-${rows[0]?.level ?? 'none'}`);
     if (dataMismatch.length) failureReasons.push('log-data-mismatch');
 
+    const devicePass = failureReasons.length === 0;
+    const runEvidence = { category: 'ux.sim.scenario', event: 'completed' } as const;
+    debug.log(runEvidence.category, runEvidence.event, {
+      runId,
+      scenarioId: scenario.id,
+      deviceVerdict: devicePass ? 'PASS' : 'FAIL',
+    });
+    storeSink.flush();
+    const persistedRunEvents = store.queryByDataKeys({ exactCategories: [runEvidence.category], runIds: [runId] })
+      .filter((row) => row.event === runEvidence.event);
+    const runEventPersisted = persistedRunEvents.length === 1;
+    if (!runEventPersisted) failureReasons.push('run-evidence-event-not-persisted');
+
     const result: ScenarioResult = {
       id: scenario.id,
+      runId,
       seed: scenario.seed,
       evidenceArtifact: '',
+      runEvidence: { ...runEvidence, persisted: runEventPersisted },
       pass: failureReasons.length === 0,
-      trigger: { id: trigger.id, type: trigger.type, status: trigger.status ?? null, expectedCount: expectedTriggerCount, fetchCount, error: errorMessage },
+      trigger: { id: trigger.id, type: trigger.type, status: trigger.status ?? null, expectedCount: expectedTriggerCount, fetchCount: observedTriggerCount, error: errorMessage },
       screen: { pass: screenPass, containsMissing, excludesFound, snapshot: screenText },
       logs: {
         pass: logPass,
@@ -271,37 +401,44 @@ async function runScenarioV0Exclusive(scenario: ScenarioV0): Promise<ScenarioRes
     mkdirSync(evidenceDir, { recursive: true });
     assertNoSymlinkComponents(evidenceDir);
     if (!lstatSync(evidenceDir).isDirectory()) throw new Error('scenario evidence directory must stay inside test state');
-    const evidenceArtifact = join(evidenceDir, `${scenario.id}-seed-${scenario.seed}.json`);
+    const evidenceArtifact = join(evidenceDir, `${scenario.id}-seed-${scenario.seed}-run-${runId}.json`);
     result.evidenceArtifact = evidenceArtifact;
     const artifact = {
       version: 0,
       id: scenario.id,
+      runId,
       seed: scenario.seed,
       pass: result.pass,
       trigger: { type: result.trigger.type, ...(result.trigger.status !== null ? { status: result.trigger.status } : {}), expectedCount: result.trigger.expectedCount, fetchCount: result.trigger.fetchCount, errorObserved: result.trigger.error !== null },
       screen: { pass: result.screen.pass, snapshotSha256: createHash('sha256').update(result.screen.snapshot).digest('hex'), containsMissingCount: result.screen.containsMissing.length, excludesFoundCount: result.screen.excludesFound.length },
       logs: { pass: result.logs.pass, expectedCount: result.logs.expectedCount, observedCount: result.logs.observedCount, levelMismatch: result.logs.levelMismatch, dataMismatchCount: result.logs.dataMismatch.length },
+      runEvidence: { runId: result.runId, persisted: result.runEvidence.persisted },
       failureReasonCount: result.failureReasons.length,
     };
-    const tempArtifact = join(evidenceDir, `.${scenario.id}-${randomUUID()}.tmp`);
-    const fd = openSync(tempArtifact, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
-    try {
-      writeFileSync(fd, `${JSON.stringify(artifact, null, 2)}\n`);
-      closeSync(fd);
-      assertNoSymlinkComponents(evidenceDir);
-      renameSync(tempArtifact, evidenceArtifact);
-    } catch (error) {
-      try { closeSync(fd); } catch { /* already closed */ }
-      try { unlinkSync(tempArtifact); } catch { /* absent after successful rename */ }
-      throw error;
-    }
+    writeScenarioEvidenceArtifact(evidenceDir, evidenceArtifact, artifact);
     return result;
   } finally {
     globalThis.fetch = originalFetch;
     off();
-    sink.close();
+    storeSink.close();
     store.close();
-    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+/** Write one already-validated evidence record atomically without following a target link. */
+export function writeScenarioEvidenceArtifact(evidenceDir: string, evidenceArtifact: string, artifact: unknown): void {
+  assertNoSymlinkComponents(evidenceDir);
+  const tempArtifact = join(evidenceDir, `.${randomUUID()}.tmp`);
+  const fd = openSync(tempArtifact, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+  try {
+    writeFileSync(fd, `${JSON.stringify(artifact, null, 2)}\n`);
+    closeSync(fd);
+    assertNoSymlinkComponents(evidenceDir);
+    renameSync(tempArtifact, evidenceArtifact);
+  } catch (error) {
+    try { closeSync(fd); } catch { /* already closed */ }
+    try { unlinkSync(tempArtifact); } catch { /* absent after successful rename */ }
+    throw error;
   }
 }
 

package/src/ux-sim/service-key-setup.ts

@@ -0,0 +1,50 @@
+import { createServer, type Server } from 'node:http';
+
+export type FakeOpenAiApiMode = 'ok' | 'unauthorized' | 'rate-limited' | 'disconnect' | 'slow';
+
+/** Local OpenAI-compatible /v1/models endpoint for testing the production key verifier. */
+export async function startFakeOpenAiCompatibleApi(mode: FakeOpenAiApiMode, delayMs = 350): Promise<{
+  baseUrl: string;
+  requests: () => number;
+  close: () => Promise<void>;
+}> {
+  let requestCount = 0;
+  const timers = new Set<ReturnType<typeof setTimeout>>();
+  const server: Server = createServer((request, response) => {
+    requestCount++;
+    if (request.url !== '/v1/models') {
+      response.writeHead(404).end();
+      return;
+    }
+    if (mode === 'disconnect') {
+      request.socket.destroy();
+      return;
+    }
+    if (mode === 'slow') {
+      const timer = setTimeout(() => {
+        timers.delete(timer);
+        if (!response.destroyed) response.writeHead(200, { 'content-type': 'application/json' }).end('{"data":[]}');
+      }, delayMs);
+      timers.add(timer);
+      return;
+    }
+    const status = mode === 'ok' ? 200 : mode === 'unauthorized' ? 401 : 429;
+    response.writeHead(status, { 'content-type': 'application/json' }).end(mode === 'ok' ? '{"data":[]}' : '{}');
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => resolve());
+  });
+  const address = server.address();
+  if (!address || typeof address === 'string') throw new Error('fake OpenAI API did not bind a TCP port');
+  return {
+    baseUrl: `http://127.0.0.1:${address.port}/v1`,
+    requests: () => requestCount,
+    close: () => new Promise<void>((resolve, reject) => {
+      for (const timer of timers) clearTimeout(timer);
+      timers.clear();
+      server.close(error => error ? reject(error) : resolve());
+      server.closeAllConnections();
+    }),
+  };
+}

package/src/ux-sim/term-slash-device.ts

@@ -0,0 +1,74 @@
+// /term mock-device stage — invoke the production slash registry/handler with
+// mocked terminal ports so subcommand combinations never need another PTY.
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { SlashCommandRegistry } from '../dashboard/slash-runtime/registry.js';
+import { createDashboardTermSlashRuntime } from '../dashboard/term-slash-runtime.js';
+import { registerTermSlash, type TermSlashContext } from '../tui/slash/term.js';
+
+export interface TermSlashScenarioResult {
+  subcommand: string;
+  expected: string;
+  evidence: string;
+}
+
+const format = (text: string) => text;
+
+/** Run the fast command matrix through the same production handler used by TUI. */
+export async function runTermSlashMockScenarios(): Promise<TermSlashScenarioResult[]> {
+  const root = mkdtempSync(join(tmpdir(), 'term-slash-mock-'));
+  const previousState = process.env.ELANOUS_STATE_DIR;
+  const previousHome = process.env.ELANOUS_TEST_HOME;
+  process.env.ELANOUS_STATE_DIR = root;
+  process.env.ELANOUS_TEST_HOME = root;
+  try {
+    const calls: string[] = [];
+    const ctx = {
+      chatLines: [] as string[], setChatScrollOffset: () => {},
+      accent: format, warning: format, error: format, draw: () => {},
+      termSlash: {
+        slashRuntime: createDashboardTermSlashRuntime({ accent: format, muted: format, warning: format, error: format, text: format }),
+        openNewTerminal: (command?: string) => { calls.push(`new:${command}`); },
+        openSessionPicker: () => { calls.push('switch'); },
+        sessionRegistry: {
+          list: () => [], foreground: () => null, kill: (id: string) => { calls.push(`kill:${id}`); },
+        },
+        terminalMatrix: { list: () => [], get: () => null, listPipes: () => [] },
+        broadcastBus: { groups: () => [] },
+        channelBus: { channels: () => [] },
+      },
+    } as unknown as TermSlashContext;
+    const registry = new SlashCommandRegistry<TermSlashContext, never>();
+    registerTermSlash(registry);
+    const cases = [
+      ['help', [], '/term new'], ['help', ['experimental'], '/term matrix'],
+      ['new', ['echo', 'hi'], 'new:echo hi'], ['list', [], 'No terminal sessions.'],
+      ['attach', [], '/term attach requires'], ['detach', [], 'No foreground session'],
+      ['switch', [], 'switch'], ['kill', [], 'No session to kill'],
+      ['resume', [], 'No persisted sessions'], ['snapshot', [], 'Usage: /term snapshot'],
+      ['matrix', [], '(no terminals'], ['move', [], 'Usage: /term move'],
+      ['group', [], '(no broadcast groups'], ['channel', [], '(no channels'],
+      ['pipe', [], 'Usage: /term pipe'], ['readonly', [], 'Usage: /term readonly'],
+      ['recharacter', [], 'Usage: /term recharacter'],
+    ] as const;
+    const results: TermSlashScenarioResult[] = [];
+    for (const [subcommand, args, expected] of cases) {
+      const lineStart = ctx.chatLines.length;
+      const callStart = calls.length;
+      await registry.dispatch('term', [subcommand, ...args], ctx);
+      results.push({
+        subcommand,
+        expected,
+        evidence: [...ctx.chatLines.slice(lineStart), ...calls.slice(callStart)].join('\n'),
+      });
+    }
+    return results;
+  } finally {
+    if (previousState === undefined) delete process.env.ELANOUS_STATE_DIR;
+    else process.env.ELANOUS_STATE_DIR = previousState;
+    if (previousHome === undefined) delete process.env.ELANOUS_TEST_HOME;
+    else process.env.ELANOUS_TEST_HOME = previousHome;
+    rmSync(root, { recursive: true, force: true });
+  }
+}

package/src/ux-sim/turn-throw-sim.ts

@@ -0,0 +1,31 @@
+export interface TurnThrowSimOptions {
+  stage: string;
+  delayMs?: number;
+  error?: Error;
+  sleep?: (milliseconds: number) => Promise<void>;
+}
+
+export type TurnThrowSim = (stage: string) => Promise<void>;
+
+const defaultSleep = (milliseconds: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, milliseconds));
+
+export function createTurnThrowSim(options: TurnThrowSimOptions): TurnThrowSim {
+  if (!options.stage.trim()) throw new Error('turn throw simulation stage must be non-empty');
+  const delayMs = options.delayMs ?? 0;
+  if (!Number.isFinite(delayMs) || delayMs < 0) throw new Error('turn throw simulation delayMs must be a non-negative finite number');
+  return async (stage) => {
+    if (stage !== options.stage) return;
+    if (delayMs > 0) await (options.sleep ?? defaultSleep)(delayMs);
+    throw options.error ?? new Error(`simulated turn body failure at ${stage}`);
+  };
+}
+
+/** The production path remains inert unless the explicit simulation environment is configured. */
+export const runConfiguredTurnThrowSim: TurnThrowSim = async (stage) => {
+  const configuredStage = process.env.ELANOUS_UX_SIM_TURN_THROW_STAGE;
+  if (!configuredStage) return;
+  const parsedDelay = Number(process.env.ELANOUS_UX_SIM_TURN_THROW_DELAY_MS ?? '0');
+  const simulate = createTurnThrowSim({ stage: configuredStage, delayMs: parsedDelay });
+  await simulate(stage);
+};

package/src/version/packed-revision.json

@@ -1 +1 @@
-{"commit":"479072f6639b631e74d2a88a4e2f982193e00f89"}
+{"commit":"3d63e99aabe026e15c2e342227d354458d2ada73"}

package/src/voice/voice-tts-singleton.ts

@@ -157,13 +157,16 @@ export function resolveDaemonTtsProviderIdWithDepsForTesting(deps: TtsAvailabili
   return resolveProviderId(deps);
 }
 
-export async function initDaemonTtsProvider(): Promise<TTSProvider | null> {
+async function initDaemonTtsProviderWithAvailabilityDeps(
+  deps: TtsAvailabilityDeps,
+  instantiate: typeof instantiateForId = instantiateForId,
+): Promise<TTSProvider | null> {
   if (cached) return cached;
   if (initInFlight) return initInFlight;
   initInFlight = (async () => {
-    const id = resolveProviderId();
+    const id = resolveProviderId(deps);
     try {
-      const provider = await instantiateForId(id);
+      const provider = await instantiate(id);
       cached = provider;
       if (debug.enabled) {
         debug.log('voice.tts.singleton', 'init.ok', {
@@ -186,6 +189,18 @@ export async function initDaemonTtsProvider(): Promise<TTSProvider | null> {
   return initInFlight;
 }
 
+export function initDaemonTtsProvider(): Promise<TTSProvider | null> {
+  return initDaemonTtsProviderWithAvailabilityDeps(defaultTtsAvailabilityDeps);
+}
+
+/** Initialize with a fixed host-availability probe for deterministic tests. */
+export function initDaemonTtsProviderWithDepsForTesting(
+  deps: TtsAvailabilityDeps,
+  instantiate: typeof instantiateForId = instantiateForId,
+): Promise<TTSProvider | null> {
+  return initDaemonTtsProviderWithAvailabilityDeps(deps, instantiate);
+}
+
 /** Sync getter — returns the cached singleton or null. Call after
  *  `initDaemonTtsProvider` has resolved. */
 export function getDaemonTtsProvider(): TTSProvider | null {

package/src/web-search/exa.ts

@@ -0,0 +1,77 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import type { WebSearchHit, WebSearchProvider, WebSearchQuery, WebSearchResult } from './provider.js';
+
+const EXA_SEARCH_API = 'https://api.exa.ai/search';
+
+export interface ExaWebSearchDeps {
+  fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+  getEnv?: (name: string) => string | undefined;
+  readFile?: (path: string) => string;
+  homeDir?: () => string;
+}
+
+interface ExaResult {
+  url?: unknown;
+  title?: unknown;
+  highlights?: unknown;
+  text?: unknown;
+  score?: unknown;
+  publishedDate?: unknown;
+}
+
+function resolveExaApiKey(deps: ExaWebSearchDeps): string {
+  const fromEnvironment = deps.getEnv ? deps.getEnv('EXA_API_KEY') : process.env.EXA_API_KEY;
+  if (fromEnvironment?.trim()) return fromEnvironment.trim();
+  try {
+    const path = `${(deps.homeDir ?? homedir)()}/.cache/exa_api_key`;
+    return (deps.readFile ?? ((file) => readFileSync(file, 'utf8')))(path).trim();
+  } catch {
+    return '';
+  }
+}
+
+export function buildExaWebSearchProvider(deps: ExaWebSearchDeps = {}): WebSearchProvider {
+  return {
+    id: 'exa',
+    displayName: 'Exa',
+    available: () => resolveExaApiKey(deps).length > 0,
+    async search(query: WebSearchQuery, signal?: AbortSignal): Promise<WebSearchResult> {
+      const apiKey = resolveExaApiKey(deps);
+      if (!apiKey) throw new Error('Exa API key not configured');
+      const limit = Math.max(1, Math.min(query.limit ?? 5, 20));
+      let response: Response;
+      try {
+        response = await (deps.fetch ?? fetch)(EXA_SEARCH_API, {
+          method: 'POST',
+          headers: { 'x-api-key': apiKey, 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            query: query.query,
+            numResults: limit,
+            contents: { highlights: { maxCharacters: 500 } },
+          }),
+          signal,
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(message.split(apiKey).join('[redacted]'));
+      }
+      if (!response.ok) throw new Error(`Exa search HTTP ${response.status}`);
+      const payload = await response.json() as { results?: ExaResult[] };
+      const hits: WebSearchHit[] = (Array.isArray(payload.results) ? payload.results : [])
+        .map((result) => ({
+          url: String(result.url ?? ''),
+          title: String(result.title ?? result.url ?? '(untitled)'),
+          snippet: Array.isArray(result.highlights)
+            ? result.highlights.filter((value): value is string => typeof value === 'string').join('\n')
+            : String(result.text ?? ''),
+          ...(typeof result.score === 'number' ? { score: result.score } : {}),
+          ...(typeof result.publishedDate === 'string' && !Number.isNaN(Date.parse(result.publishedDate))
+            ? { publishedAt: Date.parse(result.publishedDate) }
+            : {}),
+        }))
+        .filter((hit) => hit.url);
+      return { hits, providerName: 'exa', durationMs: 0 };
+    },
+  };
+}