elanous 0.2.41 → 0.2.43

package/src/setup/service-keys.ts

@@ -0,0 +1,241 @@
+import { randomBytes } from 'node:crypto';
+import { closeSync, existsSync, fchmodSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { stdin, stdout } from 'node:process';
+import { SERVICE_KEY_CATALOG } from './llm-env-detect.js';
+
+const SERVICE_KEY_ENV_NAMES = new Set(SERVICE_KEY_CATALOG
+  .filter(item => item.kind === 'api-key')
+  .flatMap(item => item.envNames));
+
+/** Read a multi-line dotenv paste in raw mode. No pasted character is echoed; Ctrl-D finishes. */
+export async function readMaskedServiceEnvPaste(): Promise<string> {
+  if (!stdin.isTTY || typeof stdin.setRawMode !== 'function') throw new Error('secret input requires a terminal');
+  stdout.write('Paste .env assignments; input stays hidden. Press Ctrl-D when finished.\n');
+  const priorRaw = stdin.isRaw;
+  stdin.setRawMode(true);
+  stdin.resume();
+  stdin.setEncoding('utf8');
+  return new Promise((resolve, reject) => {
+    let value = '';
+    const cleanup = () => {
+      stdin.removeListener('data', onData);
+      stdin.setRawMode(priorRaw);
+    };
+    const onData = (chunk: string) => {
+      for (const char of chunk) {
+        const code = char.charCodeAt(0);
+        if (code === 4) {
+          stdout.write('\n');
+          cleanup();
+          resolve(value);
+          return;
+        }
+        if (code === 3) {
+          stdout.write('\n');
+          cleanup();
+          reject(new Error('cancelled'));
+          return;
+        }
+        if (char === '\r') continue;
+        if (char === '\n') {
+          value += '\n';
+          stdout.write('\n');
+          continue;
+        }
+        if (char === '\b' || code === 127) {
+          const characters = Array.from(value);
+          if (characters.length > 0) {
+            const removedNewline = characters.at(-1) === '\n';
+            characters.pop();
+            value = characters.join('');
+            stdout.write(removedNewline ? '\u001b[1A\r\u001b[K' : '\b \b');
+          }
+          continue;
+        }
+        if (code < 32) continue;
+        value += char;
+        stdout.write('*');
+      }
+    };
+    stdin.on('data', onData);
+  });
+}
+
+export type ParsedServiceKeyEnv = ReadonlyMap<string, string>;
+
+/** Parse dotenv assignments without expansion and never include values in errors. */
+export function parseServiceKeyEnv(text: string): ParsedServiceKeyEnv {
+  const values = new Map<string, string>();
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const match = line.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+    if (!match) throw new Error('invalid env assignment');
+    const name = match[1]!;
+    if (!SERVICE_KEY_ENV_NAMES.has(name)) throw new Error(`unsupported env name: ${name}`);
+    if (values.has(name)) throw new Error(`duplicate env name: ${name}`);
+    let value = match[2]!.trim();
+    if (value.startsWith('"') || value.startsWith("'")) {
+      const quote = value[0]!;
+      if (value.length < 2 || value.at(-1) !== quote) throw new Error(`invalid quoted value for ${name}`);
+      value = value.slice(1, -1);
+    } else {
+      value = value.replace(/\s+#.*$/, '').trim();
+    }
+    if (!value || value.includes('\0')) throw new Error(`empty or invalid value for ${name}`);
+    values.set(name, value);
+  }
+  return values;
+}
+
+export interface ServiceKeyStatus {
+  id: string;
+  label: string;
+  envNames: string[];
+  configured: boolean;
+  kind: string;
+}
+
+function cachePath(name: string, cacheDir: string): string {
+  if (!SERVICE_KEY_ENV_NAMES.has(name)) throw new Error(`unsupported env name: ${name}`);
+  return join(cacheDir, name.toLowerCase());
+}
+
+function cachedValue(name: string, cacheDir: string): string | undefined {
+  const path = cachePath(name, cacheDir);
+  if (!existsSync(path)) return undefined;
+  try {
+    const stat = lstatSync(path);
+    if (!stat.isFile()) return undefined;
+    return readFileSync(path, 'utf8').trim() || undefined;
+  } catch { return undefined; }
+}
+
+export function serviceKeyStatus(options: {
+  env?: NodeJS.ProcessEnv;
+  cacheDir?: string;
+} = {}): ServiceKeyStatus[] {
+  const env = options.env ?? process.env;
+  const cacheDir = options.cacheDir ?? (process.env.ELANOUS_KEY_CACHE_DIR?.trim() || join(homedir(), '.cache'));
+  return SERVICE_KEY_CATALOG.map(item => ({
+    id: item.id,
+    label: item.label,
+    envNames: [...item.envNames],
+    kind: item.kind,
+    configured: item.kind === 'api-key'
+      ? item.envNames.some(name => Boolean(env[name]?.trim() || cachedValue(name, cacheDir)))
+      : false,
+  }));
+}
+
+/** Persist accepted service keys into the established ~/.cache/<env lowercase> store. */
+export function storeServiceKeys(values: ParsedServiceKeyEnv, options: {
+  cacheDir?: string;
+  env?: NodeJS.ProcessEnv;
+} = {}): { stored: string[] } {
+  const cacheDir = options.cacheDir ?? (process.env.ELANOUS_KEY_CACHE_DIR?.trim() || join(homedir(), '.cache'));
+  const env = options.env ?? process.env;
+  for (const [name, value] of values) {
+    cachePath(name, cacheDir);
+    if (!value.trim() || value.includes('\0')) throw new Error(`invalid value for ${name}`);
+  }
+  mkdirSync(cacheDir, { recursive: true, mode: 0o700 });
+  const dirStat = lstatSync(cacheDir);
+  if (!dirStat.isDirectory()) throw new Error('invalid key cache directory');
+  for (const [name, value] of values) {
+    const path = cachePath(name, cacheDir);
+    const temp = `${path}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
+    try {
+      const fd = openSync(temp, 'wx', 0o600);
+      try {
+        fchmodSync(fd, 0o600);
+        writeFileSync(fd, `${value.trim()}\n`);
+        fsyncSync(fd);
+      } finally { closeSync(fd); }
+      renameSync(temp, path);
+      env[name] = value.trim();
+    } finally { rmSync(temp, { force: true }); }
+  }
+  return { stored: [...values.keys()].sort() };
+}
+
+export type ServiceKeyVerification = 'verified' | 'invalid' | 'rate-limited' | 'unavailable' | 'unsupported';
+
+export interface VerifyServiceKeyOptions {
+  /** Existing per-provider endpoint, such as llm.rotation[].baseUrl. */
+  baseUrl?: string;
+  cacheDir?: string;
+  env?: NodeJS.ProcessEnv;
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+}
+
+function modelsUrl(baseUrl: string | undefined, defaultRoot: string): string {
+  const root = (baseUrl || defaultRoot).replace(/\/+$/, '');
+  return `${root}/models`;
+}
+
+/** One bounded minimal request. Results contain only a category and status code; errors and URLs are discarded. */
+export async function verifyServiceKey(id: string, key: string, options: VerifyServiceKeyOptions = {}): Promise<{ result: ServiceKeyVerification; httpStatus?: number }> {
+  const env = options.env ?? process.env;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const timeoutMs = Math.max(100, options.timeoutMs ?? 5_000);
+  let url: string;
+  let init: RequestInit;
+  const bearer = (endpoint: string): void => {
+    url = endpoint;
+    init = { method: 'GET', headers: { authorization: `Bearer ${key}` } };
+  };
+  switch (id) {
+    case 'exa':
+      url = 'https://api.exa.ai/search';
+      init = { method: 'POST', headers: { 'content-type': 'application/json', 'x-api-key': key }, body: JSON.stringify({ query: 'credential check', numResults: 1 }) };
+      break;
+    case 'firecrawl':
+      url = 'https://api.firecrawl.dev/v2/scrape';
+      init = { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` }, body: JSON.stringify({ url: 'https://example.com', formats: ['markdown'] }) };
+      break;
+    case 'xai': bearer(modelsUrl(options.baseUrl, 'https://api.x.ai/v1')); break;
+    case 'tavily':
+      url = 'https://api.tavily.com/search';
+      init = { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ api_key: key, query: 'credential check', max_results: 1 }) };
+      break;
+    case 'openrouter': bearer('https://openrouter.ai/api/v1/key'); break;
+    case 'linear':
+      url = 'https://api.linear.app/graphql';
+      init = { method: 'POST', headers: { 'content-type': 'application/json', authorization: key }, body: JSON.stringify({ query: 'query { viewer { id } }' }) };
+      break;
+    case 'telegram': bearer(`https://api.telegram.org/bot${key}/getMe`); break;
+    case 'openai-api': bearer(modelsUrl(options.baseUrl || process.env.OPENAI_BASE_URL, 'https://api.openai.com/v1')); break;
+    case 'anthropic-api':
+      url = 'https://api.anthropic.com/v1/models';
+      init = { method: 'GET', headers: { 'x-api-key': key, 'anthropic-version': '2023-06-01' } };
+      break;
+    case 'gemini-api':
+      url = 'https://generativelanguage.googleapis.com/v1beta/models';
+      init = { method: 'GET', headers: { 'x-goog-api-key': key } };
+      break;
+    case 'opengateway': bearer('https://apis.opengateway.ai/v1/models'); break;
+    case 'telegram-chat': {
+      const bot = env.ELANOUS_TELEGRAM_BOT_TOKEN?.trim() || cachedValue('ELANOUS_TELEGRAM_BOT_TOKEN', options.cacheDir ?? (process.env.ELANOUS_KEY_CACHE_DIR?.trim() || join(homedir(), '.cache')));
+      if (!bot) return { result: 'unsupported' };
+      url = `https://api.telegram.org/bot${bot}/getChat?chat_id=${encodeURIComponent(key)}`;
+      init = { method: 'GET' };
+      break;
+    }
+    default: return { result: 'unsupported' };
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchImpl(url!, { ...init!, signal: controller.signal });
+    if (response.status >= 200 && response.status < 300) return { result: 'verified', httpStatus: response.status };
+    if (response.status === 401 || response.status === 403) return { result: 'invalid', httpStatus: response.status };
+    if (response.status === 429) return { result: 'rate-limited', httpStatus: response.status };
+    return { result: 'unavailable', httpStatus: response.status };
+  } catch {
+    return { result: 'unavailable' };
+  } finally { clearTimeout(timer); }
+}

package/src/sidetab-core/model.ts

@@ -181,11 +181,13 @@ export const NEXT_SIDETAB_TOOL_NAME = 'NextSidetab';
 const NEXT_SIDETAB_CALL = 'elanous.sidetab.call';
 const NEXT_SIDETAB_RESULT = 'elanous.sidetab.result';
 
-export type NextSidetabAction = 'list' | 'switch' | 'attach' | 'detach' | 'new' | 'kill';
+export type NextSidetabAction = 'list' | 'switch' | 'attach' | 'detach' | 'new' | 'mission' | 'kill';
 export interface NextSidetabRequest {
   action: NextSidetabAction;
   target?: string;
   character?: 'shell' | 'elanous';
+  mission?: string;
+  agent?: 'codex' | 'claude';
   confirm?: boolean;
 }
 export interface NextSidetabCall { type: typeof NEXT_SIDETAB_CALL; callId: string; request: NextSidetabRequest }
@@ -198,6 +200,7 @@ export interface NextSidetabHostDeps {
   attach(row: SidetabRow): Promise<unknown>;
   detach(): unknown;
   spawn(character: 'shell' | 'elanous'): unknown;
+  runMission?(agent: 'codex' | 'claude', mission: string): Promise<unknown>;
   kill(row: SidetabRow): unknown;
 }
 export interface NextSidetabIpcProcess {
@@ -207,13 +210,15 @@ export interface NextSidetabIpcProcess {
 
 export const nextSidetabToolSpec: LLMToolSpec = {
   name: NEXT_SIDETAB_TOOL_NAME,
-  description: 'Control the Next TUI side tab: list/view sessions and PTYs, switch sessions, attach or detach, start a local shell or elanous PTY, or kill a PTY. Ask the user to confirm before calling kill with confirm=true. Starting coding agents is not supported.',
+  description: 'Control the Next TUI side tab: list/view sessions and PTYs, switch sessions, attach or detach, start a local shell or elanous PTY, run a mission in a visible Codex or Claude side-tab and return its verified result file, or kill a PTY. Ask the user to confirm before calling kill with confirm=true.',
   parameters: {
     type: 'object',
     properties: {
-      action: { type: 'string', enum: ['list', 'switch', 'attach', 'detach', 'new', 'kill'] },
+      action: { type: 'string', enum: ['list', 'switch', 'attach', 'detach', 'new', 'mission', 'kill'] },
       target: { type: 'string', description: 'Optional exact or partial row id/label; required for targeted actions.' },
       character: { type: 'string', enum: ['shell', 'elanous'], description: 'Only used with action=new.' },
+      mission: { type: 'string', description: 'Mission text to type visibly into a new Codex or Claude side-tab PTY; the tool appends a result-file path and checks the completion marker.' },
+      agent: { type: 'string', enum: ['codex', 'claude'], description: 'Coding agent for action=mission; defaults to codex.' },
       confirm: { type: 'boolean', description: 'Must be true only after the user explicitly confirmed killing the selected PTY.' },
     },
     required: ['action'],
@@ -236,13 +241,20 @@ export async function answerNextSidetabCall(handler: NextSidetabHandler, call: N
 
 export function createNextSidetabHostHandler(deps: NextSidetabHostDeps): NextSidetabHandler {
   return async (request) => {
-    if (!request || !['list', 'switch', 'attach', 'detach', 'new', 'kill'].includes(request.action)) {
+    if (!request || !['list', 'switch', 'attach', 'detach', 'new', 'mission', 'kill'].includes(request.action)) {
       return { error: '지원하지 않는 사이드탭 동작입니다' };
     }
     if (request.action === 'new') {
       if (request.character !== 'shell' && request.character !== 'elanous') return { error: 'character는 shell 또는 elanous여야 합니다' };
       return deps.spawn(request.character);
     }
+    if (request.action === 'mission') {
+      const mission = request.mission?.trim();
+      if (!mission) return { error: 'mission 텍스트가 필요합니다' };
+      if (!deps.runMission) return { error: '사이드탭 미션 실행기가 연결되지 않았습니다' };
+      if (request.agent !== undefined && request.agent !== 'codex' && request.agent !== 'claude') return { error: 'agent는 codex 또는 claude여야 합니다' };
+      return deps.runMission(request.agent ?? 'codex', mission);
+    }
     if (request.action === 'detach') return deps.detach();
     const rows = await deps.rows();
     if (request.action === 'list') return rows.map(({ id, label, kind, badge, sessionId }) => ({ id, label, kind, badge, ...(sessionId ? { sessionId } : {}) }));
@@ -265,6 +277,7 @@ export function createReplNextSidetabTool(
   proc: NextSidetabIpcProcess,
   env: NodeJS.ProcessEnv = process.env,
   timeoutMs = 15_000,
+  missionTimeoutMs = 420_000,
 ): { spec: LLMToolSpec; dispatch: (args: Record<string, unknown>) => Promise<unknown> } | null {
   if (env.ELANOUS_NEXT_TUI_SIDETAB_IPC !== '1' || typeof proc.send !== 'function') return null;
   const send = proc.send.bind(proc);
@@ -283,10 +296,11 @@ export function createReplNextSidetabTool(
     spec: nextSidetabToolSpec,
     dispatch: (args) => new Promise((resolve) => {
       const callId = `s${++sequence}`;
+      const callTimeoutMs = args.action === 'mission' ? missionTimeoutMs : timeoutMs;
       const timer = setTimeout(() => {
         if (!waiting.delete(callId)) return;
         resolve({ error: 'Next TUI did not answer the side-tab request' });
-      }, timeoutMs);
+      }, callTimeoutMs);
       waiting.set(callId, (result) => { clearTimeout(timer); resolve(result); });
       try {
         send({ type: NEXT_SIDETAB_CALL, callId, request: args as unknown as NextSidetabRequest } satisfies NextSidetabCall);

package/src/sidetab-core/visible-agent-mission.ts

@@ -0,0 +1,262 @@
+import { readFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { sanitizeForPtyInput } from '../agent-mission/provision.js';
+
+export interface VisibleMissionPty {
+  snapshot(): string;
+  write(bytes: string): void;
+  isAlive(): boolean;
+}
+
+export interface VisibleMissionResult {
+  ok: boolean;
+  path: string;
+  content?: string;
+  firstLine?: string;
+  promptReady: boolean;
+  missionVisible: boolean;
+  promptReturned: boolean;
+  completionMarker: boolean;
+  /** Bounded first PTY frame, retained to diagnose startup screens that intercepted input. */
+  initialScreen?: string;
+  startupScreen?: AgentStartupScreen;
+  error?: string;
+}
+
+export type VisibleAgentCli = 'codex' | 'claude';
+export type AgentStartupScreen = 'codex-update-choice' | 'claude-update-choice' | 'claude-login' | 'claude-workspace-trust';
+
+export interface VisibleMissionDeps {
+  pty: VisibleMissionPty;
+  agent?: VisibleAgentCli;
+  mission: string;
+  outputPath: string;
+  handleTrust(screen: string, write: (bytes: string) => void): boolean;
+  onStartupScreen?(screen: AgentStartupScreen): void;
+  readFile?(path: string): string;
+  sleep?(ms: number): Promise<void>;
+  readyTimeoutMs?: number;
+  visibilityTimeoutMs?: number;
+  completionTimeoutMs?: number;
+  pollMs?: number;
+}
+
+const sleepDefault = (ms: number): Promise<void> => new Promise(resolve => setTimeout(resolve, ms));
+
+export function isAgentInputPrompt(screen: string): boolean {
+  const plain = stripAnsi(screen);
+  return /(?:^|\n)\s*(?:│\s*)?[›❯](?:\s*(?:Ask\b|Try\b|$)|\s*│)/m.test(plain)
+    || /Ask anything|Ask (?:Codex|Claude)(?: Code)? to do anything|What would you like to do\?/i.test(plain);
+}
+
+/** Classify only known startup blockers; never copy arbitrary PTY contents into logs. */
+export function classifyAgentStartupScreen(agent: VisibleAgentCli | undefined, screen: string): AgentStartupScreen | undefined {
+  const plain = stripAnsi(screen);
+  if (agent === 'codex' && /update available/i.test(plain) && /\besc(?:ape)?\s+(?:to\s+)?skip\b/i.test(plain)) return 'codex-update-choice';
+  if (agent === 'claude' && /update available/i.test(plain)) return 'claude-update-choice';
+  if (agent === 'claude' && /(?:sign in|log in|login|authentication required|claude\.ai\/login)/i.test(plain)) return 'claude-login';
+  if (agent === 'claude' && /(?:Yes, I trust this folder|Quick safety check|Accessing workspace)/i.test(plain)) return 'claude-workspace-trust';
+  return undefined;
+}
+
+/** Drive a visible agent PTY, verify its result, then request a separate completion marker. */
+export async function runVisibleAgentMission(deps: VisibleMissionDeps): Promise<VisibleMissionResult> {
+  const sleep = deps.sleep ?? sleepDefault;
+  const pollMs = deps.pollMs ?? 150;
+  const readFile = deps.readFile ?? ((path: string) => readFileSync(path, 'utf8'));
+  let promptReady = false;
+  let missionVisible = false;
+  let promptReturned = false;
+  let completionMarker = false;
+  let initialScreen: string | undefined;
+  let startupScreen: AgentStartupScreen | undefined;
+  let codexUpdateSkipSent = false;
+  let startupScreenReported = false;
+  const observeStartupScreen = (screen: string): AgentStartupScreen | undefined => {
+    const detected = classifyAgentStartupScreen(deps.agent, screen);
+    // This field describes the blocker present in the current/final frame,
+    // not a startup dialog that has already been dismissed.
+    startupScreen = detected;
+    if (detected) {
+      if (!startupScreenReported) {
+        startupScreenReported = true;
+        deps.onStartupScreen?.(detected);
+      }
+    }
+    return detected;
+  };
+  try {
+  const readyDeadline = Date.now() + (deps.readyTimeoutMs ?? 60_000);
+  let lastScreen = '';
+
+  while (Date.now() < readyDeadline) {
+    if (!deps.pty.isAlive()) {
+      // The process may exit before the first poll; its final frame can still
+      // identify the startup screen that prevented the prompt from appearing.
+      try {
+        lastScreen = deps.pty.snapshot();
+        initialScreen ??= lastScreen.slice(-1_200);
+        observeStartupScreen(lastScreen);
+      } catch { /* an exited remote PTY may no longer expose its final frame */ }
+      return { ok: false, path: deps.outputPath, promptReady: false, missionVisible: false, promptReturned: false, completionMarker: false, ...(initialScreen ? { initialScreen } : {}), ...(startupScreen ? { startupScreen } : {}), error: 'Agent PTY exited before its prompt appeared' };
+    }
+    lastScreen = deps.pty.snapshot();
+    initialScreen ??= lastScreen.slice(-1_200);
+    const detectedScreen = observeStartupScreen(lastScreen);
+    if (detectedScreen) {
+      if (detectedScreen === 'codex-update-choice') {
+        if (!codexUpdateSkipSent) {
+          codexUpdateSkipSent = true;
+          deps.pty.write('\u001b');
+        }
+        // Codex may retain its dismissed update banner beside the live
+        // composer. Once Escape was sent, let the prompt check win in that
+        // frame instead of waiting forever for the banner to disappear.
+        if (!isAgentInputPrompt(lastScreen)) {
+          await sleep(500);
+          continue;
+        }
+      }
+    }
+    // Backend handlers recognize their own narrow auth/trust prompts; gating
+    // readiness on workspace-trust text leaves other first-run screens stuck.
+    if (detectedScreen !== 'codex-update-choice' && deps.handleTrust(lastScreen, bytes => deps.pty.write(bytes))) {
+      await sleep(500);
+      continue;
+    }
+    if (isAgentInputPrompt(lastScreen)) { promptReady = true; break; }
+    await sleep(pollMs);
+  }
+  if (!promptReady) {
+    return {
+      ok: false, path: deps.outputPath, promptReady: false, missionVisible: false, promptReturned: false, completionMarker: false,
+      initialScreen,
+      ...(startupScreen ? { startupScreen } : {}),
+      error: 'Agent input prompt was not observed before the startup timeout',
+    };
+  }
+
+  const mission = sanitizeForPtyInput(deps.mission, 4_000);
+  if (!mission) return { ok: false, path: deps.outputPath, promptReady, missionVisible: false, promptReturned: false, completionMarker: false, ...(startupScreen ? { startupScreen } : {}), error: 'Mission text is empty after input sanitization' };
+  try {
+    readFile(deps.outputPath);
+    return { ok: false, path: deps.outputPath, promptReady, missionVisible: false, promptReturned: false, completionMarker: false, ...(startupScreen ? { startupScreen } : {}), error: 'Result path already exists; refusing to reuse a previous mission file' };
+  } catch (error) {
+    if (!isFileNotFound(error)) {
+      return { ok: false, path: deps.outputPath, promptReady, missionVisible: false, promptReturned: false, completionMarker: false, ...(startupScreen ? { startupScreen } : {}), error: `Could not verify a fresh result path: ${error instanceof Error ? error.message : String(error)}` };
+    }
+  }
+  const missionPrompt = `Write the result to the exact file path ${deps.outputPath} (create parent directories if needed). ${mission}`;
+  deps.pty.write(missionPrompt);
+  const visibleMissionTail = mission.slice(-Math.min(24, mission.length));
+  const visibilityDeadline = Date.now() + (deps.visibilityTimeoutMs ?? 5_000);
+  while (Date.now() < visibilityDeadline) {
+    const visibleText = normalizeVisibleText(deps.pty.snapshot());
+    if (visibleText.includes(normalizeVisibleText(visibleMissionTail))) { missionVisible = true; break; }
+    await sleep(Math.min(pollMs || 25, Math.max(1, visibilityDeadline - Date.now())));
+  }
+  if (!missionVisible) {
+    return { ok: false, path: deps.outputPath, promptReady, missionVisible: false, promptReturned: false, completionMarker: false, initialScreen, ...(startupScreen ? { startupScreen } : {}), error: 'Mission text was not visible in the agent PTY before submission' };
+  }
+  deps.pty.write('\r');
+
+  const completionDeadline = Date.now() + (deps.completionTimeoutMs ?? 300_000);
+  let resultFileObserved = false;
+  while (Date.now() < completionDeadline) {
+    if (!deps.pty.isAlive()) break;
+    lastScreen = deps.pty.snapshot();
+    if (deps.handleTrust(lastScreen, bytes => deps.pty.write(bytes))) {
+      await sleep(500);
+      continue;
+    }
+    if (!resultFileObserved) {
+      try {
+        const candidate = readFile(deps.outputPath);
+        resultFileObserved = Boolean(candidate.trim());
+      } catch { /* the agent has not written the result file yet */ }
+    }
+    if (resultFileObserved && isAgentInputPrompt(lastScreen)) { promptReturned = true; break; }
+    await sleep(pollMs);
+  }
+  if (!resultFileObserved) {
+    return { ok: false, path: deps.outputPath, promptReady, missionVisible, promptReturned, completionMarker: false, ...(startupScreen ? { startupScreen } : {}), error: 'Agent did not create a non-empty result file before the timeout' };
+  }
+  if (!promptReturned) {
+    return { ok: false, path: deps.outputPath, promptReady, missionVisible, promptReturned: false, completionMarker: false, ...(startupScreen ? { startupScreen } : {}), error: 'Agent did not return to its input prompt after writing the result file' };
+  }
+
+  let content: string;
+  try { content = readFile(deps.outputPath); }
+  catch (error) {
+    return { ok: false, path: deps.outputPath, promptReady, missionVisible, promptReturned, completionMarker: false, ...(startupScreen ? { startupScreen } : {}), error: `Result file disappeared after the agent returned: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  const firstLine = content.split(/\r?\n/).map(line => line.trim()).find(Boolean);
+  if (!firstLine) return { ok: false, path: deps.outputPath, promptReady, missionVisible, promptReturned, completionMarker: false, ...(startupScreen ? { startupScreen } : {}), error: 'Result file is empty' };
+
+  // Keep the marker request separate and short: the marker itself never occurs
+  // in the mission prompt, so only the agent's final output can satisfy it.
+  const completionMarkerText = `M-${randomUUID().replaceAll('-', '').slice(0, 12)}`;
+  const completionMarkerPath = `${deps.outputPath}.completion-${completionMarkerText}`;
+  const markerPrompt = `Say ${completionMarkerText} alone and write it to the exact file path ${completionMarkerPath}.`;
+  deps.pty.write(markerPrompt);
+  const markerVisibleDeadline = Date.now() + (deps.visibilityTimeoutMs ?? 5_000);
+  let markerRequestVisible = false;
+  while (Date.now() < markerVisibleDeadline) {
+    const markerInputScreen = stripAnsi(deps.pty.snapshot()).replace(/\s+/g, ' ');
+    if (markerInputScreen.includes(completionMarkerText)) { markerRequestVisible = true; break; }
+    await sleep(Math.min(pollMs || 25, Math.max(1, markerVisibleDeadline - Date.now())));
+  }
+  if (!markerRequestVisible) {
+    return { ok: false, path: deps.outputPath, firstLine, promptReady, missionVisible, promptReturned, completionMarker: false, ...(startupScreen ? { startupScreen } : {}), error: 'Completion marker request was not visible in the agent PTY' };
+  }
+  if (screenShowsCompletionMarker(deps.pty.snapshot(), completionMarkerText)) {
+    return { ok: false, path: deps.outputPath, firstLine, promptReady, missionVisible, promptReturned, completionMarker: false, ...(startupScreen ? { startupScreen } : {}), error: 'Completion marker appeared in the PTY input before submission' };
+  }
+  deps.pty.write('\r');
+
+  while (Date.now() < completionDeadline) {
+    try {
+      if (readFile(completionMarkerPath).trim() === completionMarkerText) { completionMarker = true; break; }
+    } catch { /* the agent has not written the completion marker file yet */ }
+    if (!deps.pty.isAlive()) break;
+    try {
+      if (screenShowsCompletionMarker(deps.pty.snapshot(), completionMarkerText)) { completionMarker = true; break; }
+    } catch { /* detached PTYs may no longer expose a screen snapshot */ }
+    await sleep(pollMs);
+  }
+  if (!completionMarker) {
+    return { ok: false, path: deps.outputPath, firstLine, promptReady, missionVisible, promptReturned, completionMarker: false, ...(startupScreen ? { startupScreen } : {}), error: 'Agent did not show its completion marker before the timeout' };
+  }
+  return { ok: true, path: deps.outputPath, content, firstLine, promptReady, missionVisible, promptReturned, completionMarker, initialScreen, ...(startupScreen ? { startupScreen } : {}) };
+  } catch (error) {
+    return {
+      ok: false,
+      path: deps.outputPath,
+      promptReady,
+      missionVisible,
+      promptReturned,
+      completionMarker,
+      ...(initialScreen ? { initialScreen } : {}),
+      ...(startupScreen ? { startupScreen } : {}),
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+function screenShowsCompletionMarker(screen: string, marker: string): boolean {
+  const escaped = marker.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`^\\s*(?:(?:[•⏺└│╰⎿])\\s*)?${escaped}\\s*$`, 'm').test(stripAnsi(screen));
+}
+
+function stripAnsi(screen: string): string {
+  return screen.replace(/\u001b\][^\u0007]*(?:\u0007|\u001b\\)/g, '')
+    .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, '');
+}
+
+function normalizeVisibleText(screen: string): string {
+  return stripAnsi(screen).replace(/[\u00a0\u2007\u202f]/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+function isFileNotFound(error: unknown): boolean {
+  return typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
+}

package/src/skills/name-match.ts

@@ -0,0 +1,20 @@
+/** Canonicalize a spoken/typed skill slug while retaining letters and digits. */
+export function normalizeSkillName(value: string): string {
+  return value.normalize('NFKC').toLowerCase().replace(/[\s\p{P}\p{S}_]+/gu, '');
+}
+
+/** Return a canonical catalog entry only when the normalized name is unique. */
+export function resolveSkillName<T extends { name: string }>(
+  requested: string,
+  entries: readonly T[],
+): { entry?: T; ambiguous: T[] } {
+  // Keep accidental surrounding whitespace out of execution; only the
+  // slug's internal separators are fuzzy.
+  if (requested !== requested.trim()) return { ambiguous: [] };
+  const normalized = normalizeSkillName(requested);
+  if (!normalized) return { ambiguous: [] };
+  const matches = entries.filter((entry) => normalizeSkillName(entry.name) === normalized);
+  return matches.length === 1
+    ? { entry: matches[0], ambiguous: [] }
+    : { ambiguous: matches.length > 1 ? matches : [] };
+}