elanous 0.2.40 → 0.2.42

package/src/sidetab-core/model.ts

@@ -1,4 +1,5 @@
 import { resolveInstanceName } from '../instance-identity.js';
+import type { LLMToolSpec } from '../llm.js';
 import { listPtyManifestRows, type PtyManifestRow } from '../pty-shell/pty-manifest.js';
 import { describePtyRunState } from '../pty-shell/tui-run-state.js';
 
@@ -174,3 +175,152 @@ export function formatSidetabLines(
   if (mode === 'list' && lines.length < Math.floor(height)) lines.push(fit(' + new · /side new'));
   return lines;
 }
+
+/** NL/IPC side-tab contract and action policy, kept independent from either TUI renderer. */
+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' | '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 }
+export interface NextSidetabResult { type: typeof NEXT_SIDETAB_RESULT; callId: string; result: unknown }
+export type NextSidetabHandler = (request: NextSidetabRequest) => Promise<unknown>;
+export interface NextSidetabHostDeps {
+  rows(): readonly SidetabRow[] | Promise<readonly SidetabRow[]>;
+  selected(): number;
+  switchSession(row: SidetabRow): Promise<unknown>;
+  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 {
+  send?: (message: unknown) => boolean | void;
+  on(event: 'message', listener: (message: unknown) => void): unknown;
+}
+
+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, 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', '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'],
+    additionalProperties: false,
+  },
+};
+
+export function isNextSidetabCall(value: unknown): value is NextSidetabCall {
+  const call = value as Partial<NextSidetabCall> | null;
+  return Boolean(call && call.type === NEXT_SIDETAB_CALL && typeof call.callId === 'string'
+    && call.request && typeof call.request === 'object');
+}
+
+export async function answerNextSidetabCall(handler: NextSidetabHandler, call: NextSidetabCall): Promise<NextSidetabResult> {
+  try { return { type: NEXT_SIDETAB_RESULT, callId: call.callId, result: await handler(call.request) }; }
+  catch (error) {
+    return { type: NEXT_SIDETAB_RESULT, callId: call.callId, result: { error: error instanceof Error ? error.message : String(error) } };
+  }
+}
+
+export function createNextSidetabHostHandler(deps: NextSidetabHostDeps): NextSidetabHandler {
+  return async (request) => {
+    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 } : {}) }));
+    const target = request.target?.trim();
+    const exact = target ? rows.find((item) => item.id === target)
+      ?? rows.find((item) => item.label.toLowerCase() === target.toLowerCase()) : undefined;
+    const partial = target && !exact ? rows.filter((item) => item.label.toLowerCase().includes(target.toLowerCase())) : [];
+    if (partial.length > 1) return { error: `사이드탭 항목이 여러 개 일치합니다: ${target}` };
+    const row = exact ?? partial[0] ?? (target ? undefined : rows[deps.selected()]);
+    if (!row) return { error: target ? `사이드탭 항목을 찾지 못했습니다: ${target}` : '선택된 사이드탭 항목이 없습니다' };
+    if (request.action === 'switch') return row.kind === 'tui' ? deps.switchSession(row) : { error: 'Next TUI 세션만 전환할 수 있습니다' };
+    if (request.action === 'attach') return deps.attach(row);
+    if (row.currentProcess) return { error: '현재 TUI 세션은 사이드탭에서 종료할 수 없습니다' };
+    if (request.confirm !== true) return { needsConfirmation: true, message: `PTY 종료 확인 필요: ${row.label}` };
+    return deps.kill(row);
+  };
+}
+
+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);
+  const waiting = new Map<string, (result: unknown) => void>();
+  let sequence = 0;
+  const listener = (message: unknown): void => {
+    const result = message as Partial<NextSidetabResult> | null;
+    if (!result || result.type !== NEXT_SIDETAB_RESULT || typeof result.callId !== 'string') return;
+    const resolve = waiting.get(result.callId);
+    if (!resolve) return;
+    waiting.delete(result.callId);
+    resolve(result.result);
+  };
+  proc.on('message', listener);
+  return {
+    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' });
+      }, callTimeoutMs);
+      waiting.set(callId, (result) => { clearTimeout(timer); resolve(result); });
+      try {
+        send({ type: NEXT_SIDETAB_CALL, callId, request: args as unknown as NextSidetabRequest } satisfies NextSidetabCall);
+      } catch (error) {
+        waiting.delete(callId);
+        clearTimeout(timer);
+        resolve({ error: `Next TUI IPC send failed: ${error instanceof Error ? error.message : String(error)}` });
+      }
+    }),
+  };
+}
+
+export function registerNextSidetabReplTool(
+  specs: LLMToolSpec[],
+  dispatchByName: Map<string, (args: Record<string, unknown>) => Promise<unknown>>,
+  proc: NextSidetabIpcProcess,
+  env: NodeJS.ProcessEnv = process.env,
+): void {
+  const tool = createReplNextSidetabTool(proc, env);
+  if (!tool) return;
+  specs.push(tool.spec);
+  dispatchByName.set(tool.spec.name, tool.dispatch);
+}

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 : [] };
+}

package/src/skills/tools/agent.ts

@@ -271,6 +271,10 @@ export interface AgentToolArgs {
    *  child keeps running; completion emits a task-notification
    *  (P2) which the parent sees in the next turn's user message. */
   run_in_background?: boolean;
+  /** How a background completion reaches an idle parent TUI. */
+  completion_delivery?: 'follow-up' | 'supplement';
+  /** Best-effort wall-clock budget for a research child, in minutes. */
+  budget_minutes?: number;
   /** When true, a background launch that hits the fan-out ceiling WAITS on
    *  the session's shared admission queue instead of being refused: it spawns
    *  as soon as a live background agent terminals (subagent waits are
@@ -349,6 +353,7 @@ export function buildAgentTool(): LLMToolSpec {
       'Delegate heavy multistep work that would overflow your context, fan out independent units in parallel, ' +
       'and hand off long investigations; use run_in_background for long-running work so you can keep coordinating ' +
       '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 ' +
       'turn budget (default 20). It returns ONE final message which becomes your tool_result. ' +
@@ -377,6 +382,17 @@ export function buildAgentTool(): LLMToolSpec {
           type: 'boolean',
           description: 'When true, returns the spawn handle immediately instead of waiting for completion. The child keeps running; its final message arrives in your next turn as a <task-notification> user message. Use for long-running explorations (multi-minute research, 10+ tool calls) so you can keep working in parallel.',
         },
+        completion_delivery: {
+          type: 'string',
+          enum: ['follow-up', 'supplement'],
+          description: 'Background-only routing. supplement adds one concise chat line when the child finishes and never opens a new TUI turn; follow-up keeps default result retrieval.',
+        },
+        budget_minutes: {
+          type: 'number',
+          minimum: 1,
+          maximum: 60,
+          description: 'Background-only best-effort wall-clock research budget. Ask the child to stop researching at this point and return currently verified evidence; default 8 minutes for supplement delivery.',
+        },
         wait_for_slot: {
           type: 'boolean',
           description: 'Only meaningful with run_in_background. When the per-session background fan-out ceiling is already full, this launch waits on the shared admission queue instead of being refused, and spawns as soon as one live background agent finishes. Waiting subagent spawns (ones that name a subagent_type) are admitted before general-purpose ones; launches with the same class keep arrival order. Omit it to get the immediate "NOT SPAWNED" refusal and re-issue later.',
@@ -423,6 +439,8 @@ export function buildAgentTool(): LLMToolSpec {
 }
 
 export interface DispatchAgentOpts {
+  /** Owning conversation session, copied to background completion receipts. */
+  parentSessionId?: string;
   /** Tools the host makes available — typically the same tool list the
    *  parent skill is using, MINUS the Agent tool itself (no recursion).
    *  When omitted, the sub-agent runs with no tools (text-only). */
@@ -507,6 +525,10 @@ export async function dispatchAgent(
 
   // PFC-S1 P1: new optional fields.
   const runInBackground = args.run_in_background === true;
+  const completionDelivery = args.completion_delivery === 'supplement' ? 'supplement' : 'follow-up';
+  const requestedBudgetMinutes = typeof args.budget_minutes === 'number' && Number.isFinite(args.budget_minutes)
+    ? Math.max(1, Math.min(60, Math.floor(args.budget_minutes)))
+    : (completionDelivery === 'supplement' ? 8 : undefined);
   const waitsForSlot = args.wait_for_slot === true;
   const spawnName = typeof args.name === 'string' && args.name.trim() ? args.name.trim() : undefined;
   const teamName = typeof args.team_name === 'string' && args.team_name.trim() ? args.team_name.trim() : undefined;
@@ -923,9 +945,12 @@ export async function dispatchAgent(
   }
 
   const hasNoTools = childTools.length === 0;
-  const childPrompt = hasNoTools
+  const budgetPrompt = runInBackground && completionDelivery === 'supplement' && requestedBudgetMinutes
+    ? `\n\n[Research time budget: ${requestedBudgetMinutes} minutes]\nReturn the best currently verified evidence within this budget. Do not wait for more sources or extend the research; state remaining uncertainty in the final message.`
+    : '';
+  const childPrompt = (hasNoTools
     ? `${prompt}\n\nNo tools are available; if a request requires reading files or executing commands, report that as unavailable rather than guessing.`
-    : prompt;
+    : prompt) + budgetPrompt;
 
   debug.log('agent.spawn', 'dispatch', {
     cid: debugCorrelationId,
@@ -935,6 +960,7 @@ export async function dispatchAgent(
     promptChars: childPrompt.length,
     model: definition.model || '(inherit)',
     maxTurns: requestedMaxTurns,
+    ...(runInBackground ? { completionDelivery, ...(requestedBudgetMinutes ? { researchBudgetMinutes: requestedBudgetMinutes } : {}) } : {}),
     tools: childTools.map(t => t.name),
     noTools: hasNoTools,
   });
@@ -943,6 +969,7 @@ export async function dispatchAgent(
   const handle = globalAgentRegistry.spawn({
     definition,
     prompt: childPrompt,
+    ...(opts.parentSessionId ? { parentSessionId: opts.parentSessionId } : {}),
     label: spawnName ?? description,   // PFC-S1 P1: explicit `name`
                           // wins, else fall back to the task label
                           // (kept for existing callers).
@@ -963,6 +990,7 @@ export async function dispatchAgent(
     ...(teamName ? { teamName } : {}),
     ...(childCwd ? { cwd: childCwd } : {}),
     ...(runInBackground ? { background: true } : {}),
+    ...(runInBackground ? { completionDelivery } : {}),
   });
 
   // Terminal release for this dispatch's reserved fan-out slot: the

package/src/skills/tools/omni-search.ts

@@ -73,16 +73,39 @@ export function buildOmniSearchTool(): LLMToolSpec {
   };
 }
 
+const RESEARCH_GROK_TIMEOUT_MS = 8_000;
+
 export async function dispatchOmniSearch(
   rawArgs: Record<string, unknown>,
   opts: OmniSearchDispatchOpts = {},
+): Promise<OmniSearchResult> {
+  return dispatchWithProviders(validate(rawArgs), opts);
+}
+
+export async function dispatchResearchOmniSearch(
+  rawArgs: Record<string, unknown>,
+  opts: OmniSearchDispatchOpts = {},
 ): Promise<OmniSearchResult> {
   const args = validate(rawArgs);
+  const selected = getAvailableResearchProviders();
+  const requested = args.engines === undefined ? undefined : new Set(args.engines.map(id => id.toLowerCase()));
+  const providers = requested === undefined
+    ? selected
+    : selected.filter(provider => requested.has(provider.id.toLowerCase()));
+  return dispatchWithProviders(args, opts, providers, { grokTimeoutMs: RESEARCH_GROK_TIMEOUT_MS });
+}
+
+async function dispatchWithProviders(
+  args: OmniSearchArgs,
+  opts: OmniSearchDispatchOpts,
+  selectedProviders?: ReturnType<typeof getAvailableWebSearchProviders>,
+  researchLimits?: { grokTimeoutMs: number },
+): Promise<OmniSearchResult> {
   const merge = args.merge ?? 'interleave';
   const limit = Math.max(1, Math.min(args.limit ?? DEFAULT_LIMIT, MAX_LIMIT));
 
-  let providers = getAvailableWebSearchProviders();
-  if (args.engines && args.engines.length > 0) {
+  let providers = selectedProviders ?? getAvailableWebSearchProviders();
+  if (!selectedProviders && args.engines && args.engines.length > 0) {
     const wanted = new Set(args.engines.map(e => e.toLowerCase()));
     providers = providers.filter(p => wanted.has(p.id.toLowerCase()));
   }
@@ -105,13 +128,33 @@ export async function dispatchOmniSearch(
     const start = Date.now();
     emit({ engine: p.id, phase: 'start' });
     try {
-      const result = await p.search({
+      const query = {
         query: args.query,
         limit,
         allowDomains: args.allow_domains,
         blockDomains: args.block_domains,
         recencyDays: args.recency_days,
-      });
+      };
+      let result;
+      if (researchLimits && (p.id === 'grok' || p.id === 'grok-api')) {
+        const controller = new AbortController();
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        try {
+          result = await Promise.race([
+            p.search(query, controller.signal),
+            new Promise<never>((_, reject) => {
+              timer = setTimeout(() => {
+                controller.abort();
+                reject(new DOMException(`Grok research search timed out after ${researchLimits.grokTimeoutMs}ms`, 'TimeoutError'));
+              }, researchLimits.grokTimeoutMs);
+            }),
+          ]);
+        } finally {
+          if (timer !== undefined) clearTimeout(timer);
+        }
+      } else {
+        result = await p.search(query);
+      }
       perEngine[p.id] = { hits: result.hits, durationMs: Date.now() - start };
       for (const hit of result.hits) {
         try {
@@ -165,11 +208,30 @@ export async function dispatchOmniSearch(
   };
 }
 
-/** Probe-compatible: at least 2 search providers available. */
+/** Probe-compatible: at least 2 search providers available for ordinary omni_search. */
 export function omniSearchAvailable(): boolean {
   return getAvailableWebSearchProviders().length >= 2;
 }
 
+/** Research-only probe: require the bounded Grok/Firecrawl research pair. */
+export function researchOmniSearchAvailable(): boolean {
+  return getAvailableResearchProviders().length >= 2;
+}
+
+export function getAvailableResearchSearchEngineIds(): string[] {
+  return getAvailableResearchProviders().map(provider => provider.id);
+}
+
+function getAvailableResearchProviders(): ReturnType<typeof getAvailableWebSearchProviders> {
+  const available = getAvailableWebSearchProviders();
+  const grok = available.find(provider => provider.id === 'grok')
+    ?? available.find(provider => provider.id === 'grok-api');
+  return [
+    ...(grok ? [grok] : []),
+    ...available.filter(provider => provider.id === 'firecrawl'),
+  ];
+}
+
 function interleaveHits(perEngine: Record<string, { hits: WebSearchHit[] }>): WebSearchHit[] {
   const lists = Object.values(perEngine).map(v => v.hits.slice());
   const merged: WebSearchHit[] = [];

package/src/task-agent/parent-host.ts

@@ -43,6 +43,17 @@ export type ParentHostSetting = Partial<ParentHostConfig> | readonly Partial<Par
 export const PARENT_HOST_ENV = 'ELANOUS_TA_PARENT_HOST';
 const DEFAULT_REMOTE_ELANOUS = '$HOME/.local/share/elanous/bin/elanous';
 const DEFAULT_REMOTE_CONFIG_DIR = '$HOME/.elanous';
+/**
+ * 원격 부모 상태 루트의 출처 태그 — 루트(`ELANOUS_STATE_DIR`)와 «한 벌»로 넘긴다(src/agent/identity-env.ts).
+ * HQ 가 git worktree/`--test` 라면 그 env 에 `derived` 가 실린다. 루트만 원격 값으로 바꾸고 태그를 그대로
+ * 흘리면 원격 부모는 «명시한 운영 루트 + 파생 태그»를 받아 자기 우주를 test 로 오독한다 —
+ * `SOURCE === 'derived'` 를 보는 codexCredentialRoot(src/budget/codex-reset-credit-state.ts)·
+ * harnessLaunchPolicyConfig(src/harness/harness-substrate-default.ts) 가 그 자리다.
+ * 떼어 띄운 운영 부모의 기존 꼴(src/task-orchestrator/surfaces/pod-si-warm-runner.ts)과 같은 `explicit` 를 찍는다.
+ */
+const REMOTE_STATE_DIR_SOURCE = 'explicit';
+/** 원격 발사에서 HQ 값을 버리고 원격 기준으로 다시 찍는 상태 루트 env(한 벌). */
+const STATE_ROOT_ENV_KEYS: ReadonlySet<string> = new Set(['ELANOUS_STATE_DIR', 'ELANOUS_STATE_DIR_SOURCE']);
 const HOST_RE = /^[A-Za-z0-9][A-Za-z0-9._@-]{0,127}$/;
 /** A parent can wait for a child for tens of minutes; the two-minute HTTP refresh floor is too short here. */
 export const PARENT_CHILD_CREDENTIAL_MIN_REMAINING_MS = 60 * 60_000;
@@ -227,7 +238,9 @@ export function remoteLaunchScript(target: ParentHostConfig, args: readonly stri
   const log = remoteParentLogPath(target, env.ELANOUS_RUN_ID ?? 'unknown');
   // --config-dir keeps the parent's operational config/state; authStorePath()
   // reads XDG_CONFIG_HOME/elanous/auth.json first, as the entrypoint test proves.
-  const envPart = [...Object.entries(env).filter(([key]) => key !== 'ELANOUS_STATE_DIR' && /^[A-Z_][A-Z0-9_]*$/.test(key)).map(([key, value]) => `${key}=${key === 'XDG_CONFIG_HOME' || key === 'CODEX_HOME' || key === 'GH_CONFIG_DIR' ? remotePath(value) : shellQuote(value)}`), `ELANOUS_STATE_DIR=${remotePath(configDir)}`].join(' ');
+  // 상태 루트는 태그와 한 벌로 넘긴다(REMOTE_STATE_DIR_SOURCE 주석) — HQ 의 derived 태그가
+  // 함께 흐르면 방금 명시한 운영 루트를 원격 부모가 test 우주로 오독한다.
+  const envPart = [...Object.entries(env).filter(([key]) => !STATE_ROOT_ENV_KEYS.has(key) && /^[A-Z_][A-Z0-9_]*$/.test(key)).map(([key, value]) => `${key}=${key === 'XDG_CONFIG_HOME' || key === 'CODEX_HOME' || key === 'GH_CONFIG_DIR' ? remotePath(value) : shellQuote(value)}`), `ELANOUS_STATE_DIR=${remotePath(configDir)}`, `ELANOUS_STATE_DIR_SOURCE=${shellQuote(REMOTE_STATE_DIR_SOURCE)}`].join(' ');
   const argv = [remotePath(elanous), '--config-dir', remotePath(configDir), ...remoteParentArgs(args, target.podPool).map(shellQuote)].join(' ');
   // 준비가 실패하면 «확실히 안 띄웠다»(not-launched=…)를 찍고 끝낸다 — 그때만 호출부가 로컬로 돌아간다.
   // 띄운 뒤에는 짧게 살아 있는지 보고 pid 를 찍는다(조기 종료면 early-exit — 역시 «안 돈다»가 확실).

package/src/task-agent/pod-distributor-entry.ts

@@ -0,0 +1,3 @@
+/** Caller-side marker for the tasks-hand Pod admission path. It is not passed into the child Pod. */
+export const POD_DISTRIBUTOR_ENTRY_ENV = 'ELANOUS_POD_DISTRIBUTOR_ENTRY';
+export const TASK_HAND_POD_DISTRIBUTOR_ENTRY = 'tasks-hand';