elanous 0.2.41 → 0.2.42

package/src/session/chat.ts

@@ -42,9 +42,15 @@ import {
 // ⭐ substrate 통합(PLAN-unified-autonomous-agent-substrate-2026-07-20) — goal-loop 아밍 시
 // chat 툴루프를 canonical 엔진(runGoalLoop→runCoreTurn→streamLLMWithTools)으로 라우팅.
 // ACP bridge(core-turn-bridge.ts)·dashboard(runGoalLoopHook)와 동일 엔진 재사용(재발명 제거).
-import { runGoalLoop, type CoreTurnContext, type CoreTurnDispatchTool } from '../core-turn/index.js';
+import { runCoreTurn, runGoalLoop, type CoreTurnContext, type CoreTurnDispatchTool } from '../core-turn/index.js';
 import { composeChildContext, type ChildContextProfile } from '../self-implement/child-context-composition.js';
 import { getHarnessSpace } from '../harness/harness-space.js';
+import { isResearchAgentIntent } from '../tool-hints/signals.js';
+import {
+  buildSessionRuntimeTurnSystemMessages,
+  createSessionPostureState,
+  resolveSessionTurnProfileWithHistory,
+} from '../session-runtime/index.js';
 
 export interface RunTurnOpts {
   userConfig: UserConfig;
@@ -59,6 +65,8 @@ export interface RunTurnOpts {
   /** Optional callback for each streamed text delta — telegram uses this to
    *  accumulate; CLI uses it to render live. */
   onDelta?: (delta: string) => void;
+  /** Replace a provisional streamed answer after a grounded TUI synthesis completes. */
+  onReplaceText?: (fullText: string) => void;
   /** Optional transient stream recovery status for the originating UI. */
   onStatusLine?: (line: string) => void;
   /** Optional provider override — for tests. */
@@ -294,6 +302,24 @@ export async function runTurn(opts: RunTurnOpts): Promise<RunTurnResult> {
   // just skip and continue.
   let memoryIds: string[] = [];
   let effectiveSystemPrompt = opts.systemPrompt;
+  // The Next TUI runs through this shared session adapter rather than the classic dashboard
+  // preamble. Give research turns the same verified-reconciliation instruction on this path.
+  if (meta.source === 'tui' && !effectiveSystemPrompt?.includes('## Proactive Reconciliation')) {
+    const priorUserTexts = messages
+      .filter(message => message.role === 'user' && typeof message.content === 'string')
+      .map(message => String(message.content));
+    const turnProfile = resolveSessionTurnProfileWithHistory({
+      userText: opts.userText,
+      priorUserTexts,
+      chatModeState: createSessionPostureState(),
+    });
+    const reconciliation = buildSessionRuntimeTurnSystemMessages(turnProfile, opts.userText)
+      .filter(message => String(message.content).includes('## Proactive Reconciliation'));
+    if (reconciliation.length > 0) {
+      const block = reconciliation.map(message => String(message.content)).join('\n\n');
+      effectiveSystemPrompt = effectiveSystemPrompt ? `${effectiveSystemPrompt}\n\n${block}` : block;
+    }
+  }
   if (!opts.skipMemoryInjection) {
     try {
       // LLM-judge recall(2026-07-19 · 기본 ON·대표 지시) — 키워드 대신 luna 의미판정으로 관련
@@ -485,7 +511,8 @@ export async function runTurn(opts: RunTurnOpts): Promise<RunTurnResult> {
     // streamLLMWithTools)으로 라우팅. 미아밍이면 아래 기존 single-turn 경로 그대로(회귀 0).
     const goalLoopCfg = opts.userConfig.llm.goalLoop;
     const armGoalLoop = opts.goalLoop === true || goalLoopCfg?.enabled === true;
-    if (armGoalLoop) {
+    const armTuiResearchTurn = opts.utteranceSurface === 'tui' && turnTools.length > 0 && isResearchAgentIntent(opts.userText);
+    if (armGoalLoop || armTuiResearchTurn) {
       // ⭐ CHILD-CONTEXT-BUDGET(0.2.35 칸) — 구현 자식(self-implement 공간)의 첫 goal-loop
       //    턴에서 실제 effectiveSystemPrompt·turnTools 스키마·userText(골)의 구성 바이트를
       //    composeChildContext 로 계측해 child.context-composition 사건 1회로 남긴다.
@@ -520,6 +547,7 @@ export async function runTurn(opts: RunTurnOpts): Promise<RunTurnResult> {
         signal: opts.signal ?? new AbortController().signal,
         callbacks: {
           onText: (delta) => { opts.onDelta?.(delta); },
+          onReplaceText: (fullText) => { opts.onReplaceText?.(fullText); },
           onGoalInterim: (interimText) => {
             appendMessage(opts.sessionId, {
               role: 'assistant', content: interimText, ts: new Date().toISOString(),
@@ -540,8 +568,14 @@ export async function runTurn(opts: RunTurnOpts): Promise<RunTurnResult> {
           ? { requestSizeGuard: guardedTurnLlmOpts.requestSizeGuard } : {}),
       };
       const maxIterations = opts.goalLoopMaxIterations ?? goalLoopCfg?.maxIterations;
-      const gl = await runGoalLoop(coreCtx, maxIterations !== undefined ? { maxIterations } : {});
-      text = gl.finalText;
+      if (armGoalLoop) {
+        const gl = await runGoalLoop(coreCtx, maxIterations !== undefined ? { maxIterations } : {});
+        text = gl.finalText;
+      } else {
+        const coreResult = await runCoreTurn(coreCtx);
+        text = coreResult.finalText;
+        if (coreResult.stopReason === 'auth_rejected') throw new Error(coreResult.errorMessage ?? 'Authentication was rejected');
+      }
     } else {
     text = await streamLLMWithTools(
       kept,

package/src/session-runtime/index.ts

@@ -26,7 +26,7 @@ import type { ToolRunResult, ToolRuntime } from '../tool-runtime/types.js';
 import { blockWriteToolSearchHydration, type ToolSearchRunResult } from '../tool-runtime/tool-search-runtime.js';
 import { findNativeTool, isNativeToolModelExposed } from '../native-tool-catalog.js';
 import { hasAstGrep } from '../skills/tools/ast-grep.js';
-import { buildOmniSearchTool, omniSearchAvailable } from '../skills/tools/omni-search.js';
+import { buildOmniSearchTool, researchOmniSearchAvailable } from '../skills/tools/omni-search.js';
 import { buildWebSearchTool } from '../skills/tools/web-search.js';
 import { buildWebFetchTool } from '../skills/tools/webfetch.js';
 import { buildSelfImplementDaemonSpec } from '../boot/daemon-tools/self-implement.js';
@@ -170,6 +170,8 @@ export interface SessionPostureSnapshot {
 }
 
 export interface SessionRuntimeDispatchDeps {
+  /** Current conversation session; used to scope background Agent receipts. */
+  sessionId?: string;
   signal?: AbortSignal;
   /** Current LLM tool call, for correlating a foreground harness stop target with the TUI call. */
   toolCallId?: string;
@@ -429,6 +431,7 @@ interface SessionNativeToolRule {
     signal?: AbortSignal,
     opts?: {
       pathPolicy?: PathPolicy;
+      sessionId?: string;
       agentHostTools?: LLMToolSpec[];
       agentDispatchTool?: (name: string, args: Record<string, unknown>) => Promise<unknown>;
       buildChildToolCatalog?: (cwd: string) => {
@@ -512,6 +515,7 @@ const SESSION_NATIVE_TOOL_RULES: SessionNativeToolRule[] = [
     build: () => buildAgentTool(),
     match: () => false,
     dispatch: async (args, signal, opts) => await dispatchAgent(args, {
+      parentSessionId: opts?.sessionId,
       signal,
       hostTools: opts?.agentHostTools,
       dispatchTool: opts?.agentDispatchTool,
@@ -587,10 +591,10 @@ const SESSION_NATIVE_TOOL_RULES: SessionNativeToolRule[] = [
     description: 'Multi-source research and triangulation across external signals.',
     build: () => buildOmniSearchTool(),
     match: (text) => hasResearchSearchIntent(text),
-    isAvailable: () => omniSearchAvailable(),
+    isAvailable: () => researchOmniSearchAvailable(),
     dispatch: async (args) => {
-      const { dispatchOmniSearch } = await import('../skills/tools/omni-search.js');
-      return await dispatchOmniSearch(args);
+      const { dispatchResearchOmniSearch } = await import('../skills/tools/omni-search.js');
+      return await dispatchResearchOmniSearch(args);
     },
   },
   {
@@ -969,9 +973,47 @@ export function buildSessionRuntimeTurnSystemMessages(
   if (scopedGuidance) {
     messages.push({ role: 'system', content: scopedGuidance });
   }
+  const reconcileGuidance = buildProactiveReconcileGuidance(userText);
+  if (turnProfile.surface.domain === 'research') {
+    if (reconcileGuidance) {
+      messages.push({ role: 'system', content: PROACTIVE_RECONCILIATION_GUIDANCE.join('\n') });
+    }
+  } else if (reconcileGuidance) {
+    messages.push({ role: 'system', content: reconcileGuidance });
+  }
   return messages;
 }
 
+/** A challenged tool/source claim is a request to repair the answer, not just
+ *  to narrate whether the earlier answer was grounded. Keep this guidance
+ *  scoped to explicit evidence challenges so ordinary turns stay unchanged. */
+function buildProactiveReconcileGuidance(userText?: string): string | null {
+  const text = String(userText ?? '').toLowerCase();
+  if (!text.trim()) return null;
+
+  const explicitChallenge = [
+    /\b(?:did you|have you|were you)\b.{0,80}\b(?:actually|really|use|used|run|check|verify|consult|cite)\b/,
+    /\b(?:you (?:did not|didn't|never)\s+(?:use|run|check|verify|consult))\b/,
+    /\b(?:verify|check|recheck|re-check|confirm)\b.{0,80}\b(?:previous|prior|original|earlier)\b/,
+    /\b(?:earlier|previous|prior|last)\b.{0,40}\b(?:skill|tool|source|evidence)\b.{0,40}\b(?:used|ran|checked|verified|cited)\b.{0,30}\b(?:actually|really|right|correct)\b/,
+    /(?:앞서|이전|직전|기존|그때).{0,40}(?:스킬|도구|툴).{0,40}(?:쓴|사용한|실행한).{0,30}(?:맞|했나|했는지)/,
+    /(?:스킬|도구|툴).{0,40}(?:제대로|실제로).{0,40}(?:찾았는지|찾았나|사용했는지|사용했나|썼는지|썼나)/,
+    /(?:라고\s*(?:했는데|했음에도|말했는데)|이야기했음에도).{0,80}(?:확인|결말|결론|답).{0,40}(?:조정|수정|바꾸|고치)/,
+    /(?:스킬|도구|근거|출처).{0,60}(?:실제로\s*사용|제대로\s*사용|확인했나|썼나|쓴\s*게\s*맞|안\s*썼|못\s*찾|재확인)/,
+  ];
+  if (!explicitChallenge.some(pattern => pattern.test(text))) return null;
+
+  return [
+    '## Proactive Reconciliation — Tool-use Correction — Reconcile the Original Request This Turn',
+    '',
+    'The user is challenging whether the prior answer used the requested tool, skill, source, or evidence.',
+    'Treat the original task as still open. Recover it and the prior conclusion from the conversation, then verify the challenged claim with an available capability.',
+    'If verification changes or invalidates the prior conclusion, shows the original task was not completed, or finds that evidence is missing, incomplete, or insufficient, continue the original task in this same user turn with verified available tools and give a corrected, evidence-grounded result.',
+    'If the requested capability is unavailable, say so plainly and continue the original task with another suitable available source when possible. Never claim a tool or skill ran when it did not.',
+    'Do not stop at an apology or verification-only report, do not ask the user to repeat the task, and do not emit a raw JSON dump unless explicitly requested. Answer in concise prose.',
+  ].join('\n');
+}
+
 function buildTurnScopedExplorationGuidance(userText?: string): string | null {
   if (isScopedAnalysisRequest(userText)) {
     return [
@@ -1239,6 +1281,7 @@ function buildSurfaceOperationalGuidance(surface: SessionSurfaceProfile): string
         'Bias toward multi-source external investigation: use WebSearch, WebFetch, and OmniSearch before concluding.',
         'WebSearch is provider-backed and may route through Grok live-search or Firecrawl; OmniSearch is the wider parallel path when you want triangulation across providers.',
         'Prefer cited, current, cross-checked findings over repo-local assumptions when the question reaches beyond the workspace.',
+        '',
       ].join('\n');
     case 'research/turn':
       return [
@@ -1247,6 +1290,7 @@ function buildSurfaceOperationalGuidance(surface: SessionSurfaceProfile): string
         'You are in `research/turn`.',
         'Handle the current turn as a lightweight external lookup. Prefer quick verification and concise sourced answers over deep autonomous exploration.',
         'Keep WebSearch ready by default. It is provider-backed and may use Grok live-search or Firecrawl; use WebFetch for full page bodies and OmniSearch when the user asks for deeper cross-provider research.',
+        '',
       ].join('\n');
     case 'control/agent':
       return [
@@ -1275,6 +1319,13 @@ function buildSurfaceOperationalGuidance(surface: SessionSurfaceProfile): string
   }
 }
 
+const PROACTIVE_RECONCILIATION_GUIDANCE = [
+  '## Proactive Reconciliation — Tool-use Correction — Reconcile the Original Request This Turn',
+  'When the user asks you to verify how an earlier answer was produced (tools, skills, or sources), check the actual results and compare them with the earlier conclusion.',
+  'Treat the original task as still open. If verification changes or invalidates that conclusion, shows the original task was not completed, or finds that the evidence is missing, incomplete, or insufficient to support the conclusion, treat it as unreliable and continue in this same user turn: redo the original task with verified available tools and answer the original task with the corrected, evidence-grounded result in ordinary prose.',
+  'Do not stop at an apology or verification-only report, do not ask the user to repeat the task, and do not emit a raw JSON dump unless explicitly requested. Answer in concise prose.',
+];
+
 export function createSessionPostureState(): SessionPostureState {
   return createChatModeState();
 }
@@ -1560,6 +1611,40 @@ export function resolveSessionTurnProfile(opts: {
   };
 }
 
+function isProactiveReconciliationFollowUp(userText: string): boolean {
+  const referencesPrior = /(?:earlier|previous|prior|last|앞선|앞서|이전|직전|기존|그때|라고\s*(?:했|말)|이야기했|요청했)/i.test(userText);
+  const referencesEvidence = /(?:answer|response|analysis|conclusion|tool|skill|source|evidence|답|응답|분석|결론|도구|툴|스킬|출처|근거)/i.test(userText);
+  const asksToVerify = /(?:verify|recheck|check|confirm|validate|challenge|correct|used|맞|확인|검증|재확인|사용|사실|실제)/i.test(userText);
+  return referencesPrior && referencesEvidence && asksToVerify;
+}
+
+/** Preserve an active research turn's surface when the user challenges its prior evidence. */
+export function resolveSessionTurnProfileWithHistory(opts: {
+  userText: string;
+  priorUserTexts?: readonly string[];
+  chatModeState: ChatModeState;
+  inputSource?: InputSourceRef | null;
+}): SessionTurnProfile {
+  const current = resolveSessionTurnProfile(opts);
+  if (current.surface.domain === 'research' || !isProactiveReconciliationFollowUp(opts.userText)) return current;
+  for (const priorUserText of [...(opts.priorUserTexts ?? [])].reverse()) {
+    const prior = resolveSessionTurnProfile({
+      userText: priorUserText,
+      chatModeState: opts.chatModeState,
+      inputSource: opts.inputSource,
+    });
+    if (prior.surface.domain === 'research') {
+      return resolveSessionTurnProfile({
+        userText: opts.userText,
+        chatModeState: opts.chatModeState,
+        preferredSurfaceId: prior.surface.id,
+        inputSource: opts.inputSource,
+      });
+    }
+  }
+  return current;
+}
+
 export function resolveSessionSurfaceStatus(opts: {
   userText?: string;
   chatModeState: ChatModeState;
@@ -1736,6 +1821,7 @@ export function buildSessionRuntimeToolSpecs(opts: {
   preferredSurfaceId?: SessionSurfaceId;
   controlMode?: boolean;
 }): LLMToolSpec[] {
+  const catalogStartedAt = performance.now();
   // TUI-DIET-D1-TAIL — the legacy userText-driven catalog (`rich !== false`) is gone;
   // every caller already passed rich=false, so the essential catalog is the only path.
   // The surface profile is still resolved for the always-on observation below.
@@ -1799,6 +1885,13 @@ export function buildSessionRuntimeToolSpecs(opts: {
       userTextChars: opts.userText.length,
     });
   }
+  try {
+    debug.log('session-runtime.latency', 'tool-catalog-ready', {
+      elapsedMs: Math.round((performance.now() - catalogStartedAt) * 10) / 10,
+      toolCount: finalSpecs.length,
+      surfaceId: surface.id,
+    });
+  } catch { /* observation must never delay a turn */ }
   return finalSpecs;
 }
 
@@ -2025,6 +2118,7 @@ export async function dispatchSessionRuntimeTool(
       }
       result = await nativeRule.dispatch(normalizedArgs, deps.signal, {
         pathPolicy: deps.pathPolicy,
+        sessionId: deps.sessionId,
         agentHostTools: deps.agentHostTools,
         agentDispatchTool: deps.agentDispatchTool,
         buildChildToolCatalog: deps.buildChildToolCatalog,

package/src/session-runtime/tier-flip.ts

@@ -325,7 +325,7 @@ function joinWithBlankLine(prefix: string, block: string): string {
 
 function appendTextToMessage(msg: LLMMessage, block: string): LLMMessage {
   if (typeof msg.content === 'string') {
-    return { role: msg.role, content: joinWithBlankLine(msg.content, block) };
+    return { ...msg, content: joinWithBlankLine(msg.content, block) };
   }
   // ContentBlock[] — append to the LAST text block; if none exists,
   // push a fresh one. Other block kinds (image / tool_use / tool_result)
@@ -336,11 +336,11 @@ function appendTextToMessage(msg: LLMMessage, block: string): LLMMessage {
     if (b.type === 'text') {
       const text = (b as { text?: string }).text ?? '';
       blocks[i] = { ...b, text: joinWithBlankLine(text, block) };
-      return { role: msg.role, content: blocks };
+      return { ...msg, content: blocks };
     }
   }
   blocks.push({ type: 'text', text: block } as ContentBlock);
-  return { role: msg.role, content: blocks };
+  return { ...msg, content: blocks };
 }
 
 /** Wave 2 W2.4 + W2.5 convenience — split specs AND inject the

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,186 @@
+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 {
+  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;
+  error?: string;
+}
+
+export interface VisibleMissionDeps {
+  pty: VisibleMissionPty;
+  mission: string;
+  outputPath: string;
+  handleTrust(screen: string, write: (bytes: string) => void): boolean;
+  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*(?:Ask\b|Try\b|$)/m.test(plain)
+    || /Ask anything|Ask (?:Codex|Claude)(?: Code)? to do anything|What would you like to do\?/i.test(plain);
+}
+
+/** 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;
+  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' };
+    lastScreen = deps.pty.snapshot();
+    if (screenNeedsTrust(lastScreen) && 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,
+      error: `Agent input prompt was not observed: ${lastScreen.slice(-240).replace(/\s+/g, ' ')}`,
+    };
+  }
+
+  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' };
+  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' };
+  } 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)}` };
+    }
+  }
+  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 = stripAnsi(deps.pty.snapshot()).replace(/\s+/g, ' ');
+    if (visibleText.includes(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' };
+  }
+  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 (screenNeedsTrust(lastScreen) && 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, 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' };
+  }
+
+  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)}` };
+  }
+  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' };
+
+  // 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.`;
+  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, 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' };
+  }
+  deps.pty.write('\r');
+
+  while (Date.now() < completionDeadline) {
+    if (!deps.pty.isAlive()) break;
+    if (screenShowsCompletionMarker(deps.pty.snapshot(), completionMarkerText)) { completionMarker = true; break; }
+    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: true, path: deps.outputPath, content, firstLine, promptReady, missionVisible, promptReturned, completionMarker };
+  } catch (error) {
+    return {
+      ok: false,
+      path: deps.outputPath,
+      promptReady,
+      missionVisible,
+      promptReturned,
+      completionMarker,
+      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 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 : [] };
+}