elanous 0.2.42 → 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/visible-agent-mission.ts

@@ -1,6 +1,5 @@
 import { readFileSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
-import { screenNeedsTrust } from '../agent-mission/parse.js';
 import { sanitizeForPtyInput } from '../agent-mission/provision.js';
 
 export interface VisibleMissionPty {
@@ -18,14 +17,22 @@ export interface VisibleMissionResult {
   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;
@@ -38,10 +45,20 @@ const sleepDefault = (ms: number): Promise<void> => new Promise(resolve => setTi
 
 export function isAgentInputPrompt(screen: string): boolean {
   const plain = stripAnsi(screen);
-  return /(?:^|\n)\s*[›❯]\s*(?:Ask\b|Try\b|$)/m.test(plain)
+  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;
@@ -51,14 +68,59 @@ export async function runVisibleAgentMission(deps: VisibleMissionDeps): Promise<
   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()) return { ok: false, path: deps.outputPath, promptReady: false, missionVisible: false, promptReturned: false, completionMarker: false, error: 'Agent PTY exited before its prompt appeared' };
+    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();
-    if (screenNeedsTrust(lastScreen) && deps.handleTrust(lastScreen, bytes => deps.pty.write(bytes))) {
+    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;
     }
@@ -68,18 +130,20 @@ export async function runVisibleAgentMission(deps: VisibleMissionDeps): Promise<
   if (!promptReady) {
     return {
       ok: false, path: deps.outputPath, promptReady: false, missionVisible: false, promptReturned: false, completionMarker: false,
-      error: `Agent input prompt was not observed: ${lastScreen.slice(-240).replace(/\s+/g, ' ')}`,
+      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, error: 'Mission text is empty after input sanitization' };
+  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, error: 'Result path already exists; refusing to reuse a previous mission file' };
+    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, error: `Could not verify a fresh result path: ${error instanceof Error ? error.message : String(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}`;
@@ -87,12 +151,12 @@ export async function runVisibleAgentMission(deps: VisibleMissionDeps): Promise<
   const visibleMissionTail = mission.slice(-Math.min(24, mission.length));
   const visibilityDeadline = Date.now() + (deps.visibilityTimeoutMs ?? 5_000);
   while (Date.now() < visibilityDeadline) {
-    const visibleText = stripAnsi(deps.pty.snapshot()).replace(/\s+/g, ' ');
-    if (visibleText.includes(visibleMissionTail)) { missionVisible = true; break; }
+    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, error: 'Mission text was not visible in the agent PTY before submission' };
+    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');
 
@@ -101,7 +165,7 @@ export async function runVisibleAgentMission(deps: VisibleMissionDeps): Promise<
   while (Date.now() < completionDeadline) {
     if (!deps.pty.isAlive()) break;
     lastScreen = deps.pty.snapshot();
-    if (screenNeedsTrust(lastScreen) && deps.handleTrust(lastScreen, bytes => deps.pty.write(bytes))) {
+    if (deps.handleTrust(lastScreen, bytes => deps.pty.write(bytes))) {
       await sleep(500);
       continue;
     }
@@ -115,24 +179,25 @@ export async function runVisibleAgentMission(deps: VisibleMissionDeps): Promise<
     await sleep(pollMs);
   }
   if (!resultFileObserved) {
-    return { ok: false, path: deps.outputPath, promptReady, missionVisible, promptReturned, completionMarker: false, error: 'Agent did not create a non-empty result file before the timeout' };
+    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, error: 'Agent did not return to its input prompt after writing the result file' };
+    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, error: `Result file disappeared after the agent returned: ${error instanceof Error ? error.message : String(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, error: 'Result file is empty' };
+  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 markerPrompt = `Say ${completionMarkerText} alone.`;
+  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;
@@ -142,22 +207,27 @@ export async function runVisibleAgentMission(deps: VisibleMissionDeps): Promise<
     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, error: 'Completion marker request was not visible in the agent PTY' };
+    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, error: 'Completion marker appeared in the PTY input before submission' };
+    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;
-    if (screenShowsCompletionMarker(deps.pty.snapshot(), completionMarkerText)) { completionMarker = true; 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, error: 'Agent did not show its completion marker before the timeout' };
+    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 };
+  return { ok: true, path: deps.outputPath, content, firstLine, promptReady, missionVisible, promptReturned, completionMarker, initialScreen, ...(startupScreen ? { startupScreen } : {}) };
   } catch (error) {
     return {
       ok: false,
@@ -166,6 +236,8 @@ export async function runVisibleAgentMission(deps: VisibleMissionDeps): Promise<
       missionVisible,
       promptReturned,
       completionMarker,
+      ...(initialScreen ? { initialScreen } : {}),
+      ...(startupScreen ? { startupScreen } : {}),
       error: error instanceof Error ? error.message : String(error),
     };
   }
@@ -181,6 +253,10 @@ function stripAnsi(screen: string): string {
     .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/tools/agent.ts

@@ -245,8 +245,9 @@ const FALLBACK_GENERAL_PURPOSE: AgentDefinition = {
   systemPrompt:
     'You are a sub-agent spawned by a parent task. Run the work in the prompt to ' +
     'completion using the tools you have, then return ONE final message containing ' +
-    'the deliverable. Be terse — your output goes back into the parent\'s context.',
-  tools: ['Bash', 'Read', 'Edit', 'Grep', 'WebFetch'],
+    'the deliverable. The parent provides the available tool catalog; Agent recursion is removed ' +
+    'and all calls still pass through the parent dispatcher and its policy checks. ' +
+    'Be terse — your output goes back into the parent\'s context.',
 };
 
 export interface AgentToolArgs {
@@ -355,7 +356,7 @@ export function buildAgentTool(): LLMToolSpec {
       'and finish after the results arrive.\n' +
       'For parallel research, prefer completion_delivery="supplement" and budget_minutes=8: ask each child for its best verified evidence within the budget; late results appear as one chat line without reopening a TUI turn.\n' +
       '\n' +
-      'The sub-agent gets its own tools (Bash/Read/Edit/Grep/WebFetch by default) and its own ' +
+      'The sub-agent inherits the parent-provided tool catalog by default (Agent recursion is removed) and its own ' +
       'turn budget (default 20). It returns ONE final message which becomes your tool_result. ' +
       'Pass everything the worker needs (data, persona, framing) inside `prompt` — the worker ' +
       'starts with no memory of your conversation.',
@@ -457,6 +458,10 @@ export interface DispatchAgentOpts {
     dispatch: (name: string, args: Record<string, unknown>) => Promise<unknown>;
     workingDirectory: string;
   };
+  /** Allow the default general-purpose worker to inherit this host's catalog.
+   *  Opt-in for the TUI's policy-filtered catalog; CLI and MCP keep their
+   *  agent-definition allowlists unless they explicitly request inheritance. */
+  inheritGeneralPurposeToolCatalog?: boolean;
   /** Provider override (test stubs). When omitted, runner picks via
    *  agent definition's `model` field or parent default. */
   provider?: LLMProvider;
@@ -501,6 +506,8 @@ export interface DispatchAgentOpts {
   }) => void;
 }
 
+const BUILTIN_GENERAL_PURPOSE_DEFAULT_TOOLS = ['Bash', 'Read', 'Edit', 'Grep', 'WebFetch'] as const;
+
 export async function dispatchAgent(
   args: Record<string, unknown>,
   opts: DispatchAgentOpts = {},
@@ -965,9 +972,21 @@ export async function dispatchAgent(
     noTools: hasNoTools,
   });
 
+  // The built-in general-purpose definition's standard CLI allowlist is
+  // replaced only for TUI callers that explicitly opt into the already
+  // policy-filtered TUI catalog. MCP/CLI and user/project definitions keep
+  // their own allowlists.
+  const isBuiltinGeneralPurposeDefault = definition.name === 'general-purpose'
+    && definition.source === 'builtin'
+    && definition.tools?.length === BUILTIN_GENERAL_PURPOSE_DEFAULT_TOOLS.length
+    && BUILTIN_GENERAL_PURPOSE_DEFAULT_TOOLS.every((name, index) => definition.tools?.[index] === name);
+  const spawnDefinition = opts.inheritGeneralPurposeToolCatalog === true && isBuiltinGeneralPurposeDefault
+    ? { ...definition, tools: childTools.map(tool => tool.name) }
+    : definition;
+
   const startedAt = Date.now();
   const handle = globalAgentRegistry.spawn({
-    definition,
+    definition: spawnDefinition,
     prompt: childPrompt,
     ...(opts.parentSessionId ? { parentSessionId: opts.parentSessionId } : {}),
     label: spawnName ?? description,   // PFC-S1 P1: explicit `name`