elanous 0.2.41 → 0.2.43

package/src/acp/codex-app-server-client.ts

@@ -7,15 +7,14 @@
 //   - server-originated request handling (server → client with id)
 //   - lifecycle (close · exit)
 //
-// Deliberately NOT wired into agent-manager yet — 3.B.2 is the arc
-// that connects this client to `EmbodiedAgentSession` and flips the
-// CodexApprovalAdapter from logOnly to real approval routing.
-//
 // The stream interface is abstract so tests can drive the client with
 // synthetic Duplex streams. `spawnCodexAppServer()` is the production
-// factory that shells out to `codex app-server`.
+// factory that shells out to `codex app-server`; an explicit remoteSocketPath
+// opts the ACP agent into the shadow side-tab socket without changing stdio defaults.
 
-import { spawn as spawnChild, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { spawn as spawnChild, type ChildProcess, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { createConnection } from 'node:net';
+import { PassThrough } from 'node:stream';
 import { resolvePreferredCodexBinary } from './codex-auth.js';
 import { createInterface, type Interface as ReadlineInterface } from 'node:readline';
 import type { Readable, Writable } from 'node:stream';
@@ -444,6 +443,16 @@ export class CodexAppServerClient {
     }
     this.closed = true;
   }
+
+  /** Reject only requests sent over a disconnected transport; the socket
+   *  factory may reconnect, so the client itself remains usable. */
+  _markDisconnected(error: Error): void {
+    for (const entry of this.pending.values()) {
+      if (entry.timeoutHandle) clearTimeout(entry.timeoutHandle);
+      entry.reject(error);
+    }
+    this.pending.clear();
+  }
 }
 
 // ─── Factory · spawn real codex binary ──────────────────────────────
@@ -453,6 +462,8 @@ export interface SpawnCodexAppServerOpts {
   codexBinary?: string;
   /** Subcommand args · default `['app-server']`. */
   codexArgs?: readonly string[];
+  /** Explicit opt-in endpoint for Codex remote side-tab mode. */
+  remoteSocketPath?: string;
   /** Env vars merged onto current env · e.g. `CODEX_API_KEY`.
    *  ⛔⭐ 계약: 넘긴 값이 «이기고» 나머지 부모 env 는 «보존»된다. 그리고 이 병합은
    *  `process.env` 를 «안 바꾼다» — 계정별 쿼터 측정(`usage --account`)이 여기에 걸려 있다. */
@@ -470,6 +481,80 @@ export interface SpawnedCodexAppServer {
   readonly child: ChildProcessWithoutNullStreams;
 }
 
+function createUnixSocketStreams(socketPath: string, onDisconnect: (error: Error) => void): {
+  stdin: PassThrough;
+  stdout: PassThrough;
+} {
+  const stdin = new PassThrough();
+  const stdout = new PassThrough();
+  let closed = false;
+  let activeSocket: ReturnType<typeof createConnection> | undefined;
+  let activeSocketError: ((error: Error) => void) | undefined;
+  let activeSocketClose: (() => void) | undefined;
+  let reconnectTimer: ReturnType<typeof setTimeout> | undefined;
+  let connect: () => void = () => {};
+  const scheduleReconnect = (): void => {
+    if (closed || reconnectTimer) return;
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = undefined;
+      connect();
+    }, 100);
+    reconnectTimer.unref();
+  };
+  const retireSocket = (
+    socket: ReturnType<typeof createConnection>,
+    error: Error | undefined,
+    notifyClient: boolean,
+  ): void => {
+    if (activeSocket !== socket) return;
+    activeSocket = undefined;
+    // A destroyed destination stays registered with PassThrough.pipe unless
+    // explicitly detached. Leaving it there makes the next request write to
+    // the dead socket as well as the replacement socket.
+    stdin.unpipe(socket);
+    socket.unpipe(stdout);
+    if (activeSocketError) socket.removeListener('error', activeSocketError);
+    if (activeSocketClose) socket.removeListener('close', activeSocketClose);
+    activeSocketError = undefined;
+    activeSocketClose = undefined;
+    socket.destroy();
+    if (notifyClient) onDisconnect(error ?? new Error('codex app-server socket disconnected'));
+    else scheduleReconnect(); // Initial late startup retries; reconnect after a live transport is deferred.
+  };
+  connect = (): void => {
+    if (closed) return;
+    const socket = createConnection(socketPath);
+    let didConnect = false;
+    activeSocket = socket;
+    const onSocketError = (error: Error): void => retireSocket(socket, error, didConnect);
+    const onSocketClose = (): void => retireSocket(socket, undefined, didConnect);
+    activeSocketError = onSocketError;
+    activeSocketClose = onSocketClose;
+    socket.on('error', onSocketError);
+    socket.once('close', onSocketClose);
+    socket.once('connect', () => {
+      if (closed || activeSocket !== socket) {
+        socket.destroy();
+        return;
+      }
+      didConnect = true;
+      stdin.pipe(socket);
+      // Keep the client-facing readable open across reconnects.
+      socket.pipe(stdout, { end: false });
+    });
+  };
+  stdin.once('close', () => {
+    closed = true;
+    if (reconnectTimer) clearTimeout(reconnectTimer);
+    reconnectTimer = undefined;
+    if (activeSocket) retireSocket(activeSocket, undefined, false);
+    stdout.end();
+  });
+  connect();
+  return { stdin, stdout };
+}
+
+
 /** Build the argv for `codex app-server`, always FORCING codex's
  *  `code_mode_host` feature OFF.
  *
@@ -493,11 +578,53 @@ export function buildCodexAppServerArgs(codexArgs?: readonly string[]): string[]
   return args;
 }
 
-/** Spawn the `codex app-server` binary and wrap its stdio in a client.
- *
- *  3.B.1 ships this as a plain factory · no agent-manager integration.
- *  3.B.2 will wrap it behind `EmbodiedAgentSession` and flip the
- *  backend-registry `codex-app-server` transport on. */
+/** Build both command lines for the opt-in Codex remote shadow surface.
+ *  The default app-server factory remains stdio-backed; callers must
+ *  explicitly select these arguments to expose a Unix-domain endpoint. */
+export function buildCodexRemoteSideTabArgs(socketPath: string): {
+  appServerArgs: string[];
+  remoteTuiArgs: string[];
+} {
+  if (!socketPath.trim()) throw new Error('socket path is required');
+  const endpoint = `unix://${socketPath}`;
+  return {
+    appServerArgs: ['app-server', '--listen', endpoint, '-c', 'features.code_mode_host=false'],
+    remoteTuiArgs: ['--remote', endpoint],
+  };
+}
+
+/** Spawn options for the shadow mode; absent socketPath preserves stdio. */
+export function buildCodexAppServerSpawnArgs(opts: {
+  codexArgs?: readonly string[];
+  remoteSocketPath?: string;
+}): string[] {
+  const args = buildCodexAppServerArgs(opts.codexArgs);
+  if (!opts.remoteSocketPath) return args;
+  if (args.some((arg) => arg === '--listen' || arg.startsWith('--listen='))) {
+    throw new Error('remote socket path conflicts with codexArgs --listen');
+  }
+  const endpoint = `unix://${opts.remoteSocketPath}`;
+  return [...args.slice(0, -2), '--listen', endpoint, ...args.slice(-2)];
+}
+
+export function spawnCodexRemoteTui(opts: {
+  codexBinary: string;
+  socketPath: string;
+  cwd?: string;
+  env?: Record<string, string>;
+  spawnImpl?: typeof spawnChild;
+}): ChildProcess {
+  const spawnFn = opts.spawnImpl ?? spawnChild;
+  return spawnFn(opts.codexBinary, buildCodexRemoteSideTabArgs(opts.socketPath).remoteTuiArgs, {
+    cwd: opts.cwd,
+    env: { ...process.env, ...(opts.env ?? {}) },
+    stdio: 'inherit',
+  });
+}
+
+/** Spawn the `codex app-server` binary and wrap its stdio or explicit
+ *  Unix-socket connection in a client. The ACP agent manager selects the
+ *  socket form only when the Codex remote side-tab opt-in is configured. */
 export function spawnCodexAppServer(
   opts: SpawnCodexAppServerOpts = {},
 ): SpawnedCodexAppServer {
@@ -507,7 +634,10 @@ export function spawnCodexAppServer(
   // models ("requires a newer version of Codex"). See
   // resolvePreferredCodexBinary.
   const binary = opts.codexBinary ?? resolvePreferredCodexBinary();
-  const args = buildCodexAppServerArgs(opts.codexArgs);
+  const args = buildCodexAppServerSpawnArgs({
+    codexArgs: opts.codexArgs,
+    remoteSocketPath: opts.remoteSocketPath,
+  });
   // ⛔⭐ 테스트 심 — env 병합 «계약»(넘긴 값이 이기고 나머지 부모 env 는 보존)을 무는 유일한 방법이다.
   //   계정별 쿼터 측정이 이 병합에 걸려 있고, 여기가 틀리면 「B 를 재려다 A 를 잰다」가 된다.
   const spawnFn = opts.spawnImpl ?? spawnChild;
@@ -516,9 +646,16 @@ export function spawnCodexAppServer(
     env: { ...process.env, ...(opts.env ?? {}) },
     stdio: ['pipe', 'pipe', 'pipe'],
   });
-  const client = new CodexAppServerClient({
-    stdin: child.stdin,
-    stdout: child.stdout,
+  // Remote mode speaks over the Unix socket, leaving the app-server child's
+  // stdout disconnected. Drain it so a verbose child cannot fill the pipe.
+  if (opts.remoteSocketPath) child.stdout.resume();
+  let client: CodexAppServerClient | undefined;
+  const socketStreams = opts.remoteSocketPath
+    ? createUnixSocketStreams(opts.remoteSocketPath, (error) => client?._markDisconnected(error))
+    : undefined;
+  client = new CodexAppServerClient({
+    stdin: socketStreams?.stdin ?? child.stdin,
+    stdout: socketStreams?.stdout ?? child.stdout,
     stderr: child.stderr,
     requestTimeoutMs: opts.requestTimeoutMs,
   });
@@ -537,5 +674,5 @@ export function spawnCodexAppServer(
       }
     }
   });
-  return { client, child };
+  return { client: client!, child };
 }

package/src/acp/core-turn-bridge.ts

@@ -38,6 +38,7 @@ import { nextTurnFallbackProvider, resolveDefaultProvider, type LLMMessage, type
 import { readAutohealProviderFallback } from '../self-health/autoheal.js';
 import { debug, redactSecretText } from '../debug/log.js';
 import { CoreTurnAuthRejectedError } from '../core-turn/auth-rejected-notice.js';
+import { globalTaskNotificationQueue, renderTaskNotificationsXml } from '../agent/task-notification.js';
 import {
   runCoreTurn,
   runGoalLoop,
@@ -56,6 +57,8 @@ import { isFactQuestion } from './fact-question.js';
 import { resolveSessionSurfaceProfile } from '../session-runtime/index.js';
 import { classifyTuiChatIntent, formatTuiRouteLine, isSeatOpsDirective, type TuiChatRoute } from '../core-turn/short-question.js';
 import { HARNESS_ROLE_ENV } from '../harness/harness-space.js';
+import { RESEARCH_TOOL_ALLOWLIST, RESEARCH_TURN_MAX_TOOL_TURNS } from '../core-turn/research-policy.js';
+import { isResearchAgentIntent } from '../tool-hints/signals.js';
 import { createReasoningThoughtBuffer } from './reasoning-thought-buffer.js';
 import {
   REQUEST_SIZE_MAX_CHARS,
@@ -77,7 +80,7 @@ const QUICK_TOOLS: Record<QuickTuiRoute, readonly string[]> = {
   '조회': ['decisions_pending', 'ops_seats', 'ops_status', 'release_status', 'logs_query', 'context_now', 'memory_recall', 'Read'],
   '설정 변경': ['DashboardConfigGet', 'DashboardConfigSet', 'LlmListAvailableModels', 'prompt_getRuntimeConfig', 'prompt_setRuntimeConfig', 'view_getConfig', 'view_applyRuntimeConfig', 'view_saveConfig', 'memory_recall'],
   // MsgList is a read-only ledger listing (never acks); MsgPost · MsgAck · RunShell · Bash stay out (TUI-QUICK-ROUTE-EXPLICIT-CMD).
-  '조사': ['WebSearch', 'OmniSearch', 'Grep', 'Glob', 'Read', 'fact_check', 'memory_recall', 'MsgList', 'Agent'],
+  '조사': RESEARCH_TOOL_ALLOWLIST,
   // ScheduleWakeup (H5) wakes this TUI in-process; schedule_manage is OS cron — both belong to «상시 일».
   '상시 일': ['schedule_manage', 'schedule_list', 'schedule_create', 'schedule_update', 'ScheduleWakeup', 'session_manage', 'ops_status', 'memory_recall'],
 };
@@ -328,6 +331,7 @@ export function bridgeCoreTurnToAcp(
       // (10-14 13:48 운영 TUI OP: route short-question·goalLoop ⊕ factQuestion → 소진 뒤 헛호출 7회).
       const surfaceProfile = resolveSessionSurfaceProfile({ userText: turnCtx.userText });
       const factShaped = isFactQuestion(turnCtx.userText);
+      const researchTurn = isResearchAgentIntent(turnCtx.userText);
       // A quick research/turn lookup still keeps the fact budget. Only the
       // multi-source research/agent route needs enough rounds to compare axes.
       const factQuestion = factShaped && !armGoalLoop && surfaceProfile.id !== 'research/agent';
@@ -336,7 +340,12 @@ export function bridgeCoreTurnToAcp(
         catch { /* observation cannot interrupt a turn */ }
       }
       const explicitMaxToolTurns = deps.resolveMaxToolTurns?.({ sessionId: turnCtx.sessionId });
-      const maxToolTurns = explicitMaxToolTurns ?? (factQuestion ? getUserConfig().chat.factQuestion.maxToolTurns : undefined);
+      const resolvedMaxToolTurns = explicitMaxToolTurns ?? (factQuestion
+        ? getUserConfig().chat.factQuestion.maxToolTurns
+        : researchTurn ? RESEARCH_TURN_MAX_TOOL_TURNS : undefined);
+      const maxToolTurns = researchTurn && resolvedMaxToolTurns !== undefined
+        ? Math.min(resolvedMaxToolTurns, RESEARCH_TURN_MAX_TOOL_TURNS)
+        : resolvedMaxToolTurns;
       const withFactInstruction = (seed: LLMMessage[]): LLMMessage[] => factQuestion
         ? [{ role: 'system', content: FACT_QUESTION_INSTRUCTION }, ...seed]
         : seed;
@@ -452,6 +461,11 @@ export function bridgeCoreTurnToAcp(
           ? runGoalLoop(c, {
               // ACP owns an interactive provider loop: keep its post-completion response contract.
               terminalCompletionShortcut: false,
+              drainIterationMessages: () => {
+                const pending = globalTaskNotificationQueue.drainForParentSessionOrUnscoped(c.sessionId);
+                const xml = renderTaskNotificationsXml(pending);
+                return xml ? [{ role: 'user', content: xml }] : [];
+              },
               ...(goalLoopCfg?.maxIterations !== undefined ? { maxIterations: goalLoopCfg.maxIterations } : {}),
               // #29 처방 — 자리 판정으로 goal loop 에 «되돌아온» 턴만 빈 evidence 완료를 답으로 받는다.
               ...(route.reason.startsWith('seat-') ? { lenientCompletionEvidence: true } : {}),
@@ -543,6 +557,11 @@ export function bridgeCoreTurnToAcp(
             streamedTextSum += delta;
             void turnCtx.push(delta);
           },
+          onReplaceText: (full) => {
+            reasoningThoughts.flush();
+            streamedTextSum = full;
+            void turnCtx.pushWithMeta(full, { elanous: { textOperation: 'replace' } });
+          },
           // P2-bridge-ext — forward tool + usage events as ACP
           // sessionUpdate notifications so extension-aware clients
           // (dashboard as ACP client / future web / iphone) can
@@ -712,14 +731,13 @@ export function bridgeCoreTurnToAcp(
               }
             } else if (originalFinalStreamed) {
               void turnCtx.push(followupSuffix);
+            } else if (needsReSurface && needsFollowup) {
+              // A budget follow-up is an explicit replacement of the last assistant answer,
+              // not the legacy forced-synthesis boundary used by ordinary final answers.
+              void turnCtx.pushWithMeta(visibleFinalText!, { elanous: { textOperation: 'replace' } });
             } else if (needsReSurface) {
-              // Emit a clear-then-replace pair so clients that follow
-              // the empty-chunk-as-clear convention (dashboard plain
-              // chat) reset their per-round buffer before receiving
-              // the substantive answer. The empty signal does nothing
-              // for clients that just append (web / iphone — they
-              // would only have the new finalAssistantText delta to
-              // work with anyway).
+              // Forced synthesis without a validation supplement retains the legacy clear+final
+              // boundary. Clients that treat an empty chunk as a round reset rely on this pair.
               void turnCtx.push('');
               void turnCtx.push(visibleFinalText!);
             }

package/src/acp/event-router.ts

@@ -42,7 +42,7 @@ export interface AcpSessionUpdate {
   title?: string;
   toolCallId?: string;
   status?: string;
-  _meta?: { reasoning?: unknown };
+  _meta?: { reasoning?: unknown; elanous?: { textOperation?: unknown } };
   /** Plan event 가 ref 를 직접 들고 오는 경우 (현재 ACP spec 에 없으면
    *  router 가 turn-기반 fallback ref 사용). */
   planId?: string;
@@ -100,6 +100,9 @@ interface SessionState {
    *  body.text 를 update 로 누적. */
   activeAssistantBlockId: string | null;
   activeAssistantText: string;
+  /** Last assistant block for this turn, retained across thought/tool delimiters
+   *  so an authoritative synthesis can replace a provisional answer. */
+  replaceableAssistantBlockId: string | null;
   /** Same shape for thought chunks. */
   activeThoughtBlockId: string | null;
   activeThoughtText: string;
@@ -112,6 +115,7 @@ function freshSessionState(): SessionState {
     sysSeq: 0,
     activeAssistantBlockId: null,
     activeAssistantText: '',
+    replaceableAssistantBlockId: null,
     activeThoughtBlockId: null,
     activeThoughtText: '',
   };
@@ -168,6 +172,7 @@ export function createAcpEventRouter(): AcpEventRouter {
       flushActiveThought(state);
       state.turnSeq += 1;
       state.blockSeq = 0;
+      state.replaceableAssistantBlockId = null;
       const id = makeUserTurnBlockId(sessionId, state.turnSeq, state.blockSeq);
       const block: MessageBlock = {
         id,
@@ -199,6 +204,19 @@ export function createAcpEventRouter(): AcpEventRouter {
         case 'agent_message_chunk': {
           const c = u.content;
           if (c?.type !== 'text' || typeof c.text !== 'string') return;
+          const isReplace = u._meta?.elanous?.textOperation === 'replace';
+          const replaceTargetId = state.activeAssistantBlockId ?? state.replaceableAssistantBlockId;
+          if (isReplace && replaceTargetId !== null) {
+            flushActiveThought(state);
+            state.activeAssistantText = c.text;
+            const id = replaceTargetId;
+            stream.update(id, (cur) => ({
+              ...cur,
+              body: { ...cur.body, text: c.text } as MessageBlock['body'],
+            }));
+            state.activeAssistantBlockId = id;
+            return;
+          }
           if (state.activeAssistantBlockId === null) {
             // New assistant block — close any active thought first so
             // append/update events stay temporally ordered for
@@ -211,6 +229,7 @@ export function createAcpEventRouter(): AcpEventRouter {
               state.blockSeq,
             );
             state.activeAssistantBlockId = id;
+            state.replaceableAssistantBlockId = id;
             state.activeAssistantText = c.text;
             stream.push({
               id,

package/src/acp/server.ts

@@ -1679,6 +1679,12 @@ function wireAcpConnection(
           content: { type: 'text', text: chunk },
         };
         if (_meta) update._meta = _meta;
+        const elanousMeta = _meta?.elanous;
+        if (elanousMeta && typeof elanousMeta === 'object' && !Array.isArray(elanousMeta)
+          && (elanousMeta as Record<string, unknown>).textOperation === 'replace') {
+          aggregatorAgentText = chunk;
+          try { c5dProducer?.replaceText(chunk); } catch { /* fail-soft */ }
+        }
         await broadcast(
           req.sessionId,
           update as Parameters<typeof broadcast>[1],

package/src/agent/registry.ts

@@ -123,6 +123,7 @@ export class AgentRegistry {
       id: randomUUID(),
       definition: opts.definition,
       prompt: opts.prompt,
+      ...(opts.parentSessionId ? { parentSessionId: opts.parentSessionId } : {}),
       depth,
       ...(opts.label ? { label: opts.label } : {}),
       ...(opts.correlationId ? { correlationId: opts.correlationId } : {}),
@@ -136,6 +137,7 @@ export class AgentRegistry {
       ...(opts.teamName ? { teamName: opts.teamName } : {}),
       ...(opts.cwd ? { cwd: opts.cwd } : {}),
       ...(opts.background ? { background: true } : {}),
+      ...(opts.completionDelivery ? { completionDelivery: opts.completionDelivery } : {}),
       // MSS M1.2: brand the spawn with an AgentUri (caller may pre-mint
       // for cross-task tracing; default = fresh mint). The legacy UUID
       // `id` stays the registry key — agentUri rides alongside.

package/src/agent/task-notification.ts

@@ -5,7 +5,7 @@
 // "(running in background)" message on the same turn. To surface the
 // eventual result, we collect a `PendingTaskNotification` per completed
 // background task and inject a `<task-notification>` XML user message
-// at the start of the parent's NEXT turn.
+// at the start of the parent's next turn or at a live goal-loop boundary.
 //
 // Why XML injection instead of a tool ──
 //  • Tool-loop parents would need to remember to poll; the reliability
@@ -43,11 +43,14 @@ export const TASK_NOTIFICATION_OUTPUT_CAP = 500;
 
 export interface PendingTaskNotification {
   taskId: string;
+  parentSessionId?: string;
   agentName: string;
   /** Caller-supplied short label (Agent tool's `name` arg). */
   label?: string;
   /** Team context this task belonged to (Agent tool's `team_name`). */
   teamName?: string;
+  /** Parent-selected route; supplemental results never reopen a TUI turn. */
+  completionDelivery?: 'follow-up' | 'supplement';
   /** Final state of the task — parent LLM sees this to choose follow-up. */
   state: 'done' | 'error' | 'aborted';
   /** Child's final text (capped at TASK_NOTIFICATION_OUTPUT_CAP). */
@@ -150,11 +153,26 @@ export class TaskNotificationQueue {
     }
   }
 
-  /** Return all pending notifications AND clear the queue. Parents
-   *  call this exactly once per turn-start. */
+  /** Return all pending notifications and remove them from the queue. */
   drain(): PendingTaskNotification[] {
-    const out = this.queue;
-    this.queue = [];
+    return this.drainMatching(() => true);
+  }
+
+  /** Drain only results owned by one parent session; leave sibling sessions queued. */
+  drainForParentSession(parentSessionId: string): PendingTaskNotification[] {
+    return this.drainMatching((item) => item.parentSessionId === parentSessionId);
+  }
+
+  /** Drain one session's receipts plus legacy sessionless receipts; keep sibling sessions queued. */
+  drainForParentSessionOrUnscoped(parentSessionId: string): PendingTaskNotification[] {
+    return this.drainMatching((item) => item.parentSessionId === undefined || item.parentSessionId === parentSessionId);
+  }
+
+  private drainMatching(matches: (item: PendingTaskNotification) => boolean): PendingTaskNotification[] {
+    const out = this.queue.filter(matches);
+    if (out.length === 0) return out;
+    const drained = new Set(out);
+    this.queue = this.queue.filter((item) => !drained.has(item));
     this.persist();
     // NOTE: we keep `seen` populated so a listener firing a second
     // time for the same task (rare but possible under races) still
@@ -260,9 +278,11 @@ function buildPendingFromTask(task: AgentTask): PendingTaskNotification | null {
   const output = task.result ?? '';
   return {
     taskId: task.id,
+    ...(task.parentSessionId ? { parentSessionId: task.parentSessionId } : {}),
     agentName: task.definition.name,
     ...(task.label ? { label: task.label } : {}),
     ...(task.teamName ? { teamName: task.teamName } : {}),
+    ...(task.completionDelivery ? { completionDelivery: task.completionDelivery } : {}),
     state,
     output,
     truncated: false,

package/src/agent/types.ts

@@ -154,6 +154,8 @@ export interface AgentTask {
    *  the runner drains events in the background; completion emits
    *  a task-notification (PFC-S1 P2). */
   background?: boolean;
+  /** How a background completion reaches an idle parent TUI. */
+  completionDelivery?: 'follow-up' | 'supplement';
   /** MSS M1.2: branded URI form of this spawn's identity. The
    *  registry mints one alongside the UUID-keyed `id`. Downstream
    *  MSS bridges (M3 signal sender · M4 memory participant) reference
@@ -183,6 +185,8 @@ export interface AgentSpawnOpts {
   definition: AgentDefinition;
   /** User message / query the agent should answer. */
   prompt: string;
+  /** Session that owns this spawn; scopes background completion delivery. */
+  parentSessionId?: string;
   /** Short task label — used by UI panes (e.g. agent-roster in
    *  wd-scratch) to distinguish spawns that share a definition.
    *  Stored verbatim on AgentTask.label. Optional; when omitted,
@@ -225,6 +229,8 @@ export interface AgentSpawnOpts {
    *  immediately and drains events off-thread. Completion emits a
    *  task-notification (see src/agent/task-notification.ts, P2). */
   background?: boolean;
+  /** Parent-selected routing for background completions. */
+  completionDelivery?: 'follow-up' | 'supplement';
   /** MSS M1.2: when the caller has already minted an AgentUri (e.g. a
    *  parent spawn pre-allocating ids for tracing), pass it here.
    *  Otherwise registry.spawn mints one. */

package/src/agent-mission/browser-roundtrip-coordinator.ts

@@ -0,0 +1,85 @@
+import type { ToolRuntimeContext } from '../tool-runtime/types.js';
+import type { BrowserHandArgs, BrowserHandDeps, BrowserHandResult } from '../tool-runtime/browser-hand-runtime.js';
+
+export type BrowserHandRunner = (args: BrowserHandArgs, ctx?: ToolRuntimeContext, deps?: BrowserHandDeps) => Promise<BrowserHandResult>;
+
+export interface HumanBrowserSelection {
+  /** Linear subtask chosen by the person for this browser roundtrip. */
+  linearSubtaskId: string;
+  /** Whether the person also chose page content to reflect in that subtask. */
+  includeThisToo?: boolean;
+  /** Optional text/tab the person explicitly selected to reflect in that subtask. */
+  selection?: { text?: string; tab?: string };
+}
+
+export interface BrowserRoundtripRequest extends Omit<BrowserHandArgs, 'linearSubtaskId' | 'selection' | 'includeThisToo'> {
+  includeThisToo?: boolean;
+  humanSelection?: HumanBrowserSelection;
+}
+
+export interface BrowserRoundtripResult {
+  scene: 'browser-roundtrip';
+  selectedSubtaskId: string | null;
+  sourceUrl: string;
+  result: BrowserHandResult;
+}
+
+/**
+ * Coordinates the demo's human-selected browser handoff through the production
+ * BrowserHand safety path. BrowserHand owns approval, host checks, one safe
+ * alternate-source attempt, capture, and the optional Linear reflection.
+ */
+export async function coordinateBrowserRoundtrip(
+  request: BrowserRoundtripRequest,
+  deps: BrowserHandDeps,
+  runBrowserHand: BrowserHandRunner,
+  ctx?: ToolRuntimeContext,
+): Promise<BrowserRoundtripResult> {
+  const selection = request.humanSelection;
+  if (!selection) {
+    return {
+      scene: 'browser-roundtrip',
+      selectedSubtaskId: null,
+      sourceUrl: request.url,
+      result: {
+        ok: false,
+        reason: 'human-selection-required',
+        output: '사람이 Linear 서브태스크를 선택해야 브라우저 왕복을 시작합니다.',
+      },
+    };
+  }
+
+  const selectedSubtaskId = selection.linearSubtaskId.trim();
+  if (!selectedSubtaskId) {
+    return {
+      scene: 'browser-roundtrip',
+      selectedSubtaskId: null,
+      sourceUrl: request.url,
+      result: {
+        ok: false,
+        reason: 'invalid-input',
+        output: 'Linear 서브태스크 UUID가 필요합니다.',
+      },
+    };
+  }
+  const args: BrowserHandArgs = {
+    url: request.url,
+    target: request.target,
+    armed: request.armed,
+    linearSubtaskId: selectedSubtaskId,
+    ...(request.persona ? { persona: request.persona } : {}),
+    ...(request.alternateUrl ? { alternateUrl: request.alternateUrl } : {}),
+    ...(request.includeThisToo !== undefined
+      ? { includeThisToo: request.includeThisToo }
+      : selection.includeThisToo !== undefined ? { includeThisToo: selection.includeThisToo } : {}),
+    // Empty selection objects mean that no page text/tab was chosen; only explicit content is forwarded.
+    ...(selection.selection ? { selection: selection.selection } : {}),
+  };
+  const result = await runBrowserHand(args, ctx, deps);
+  return {
+    scene: 'browser-roundtrip',
+    selectedSubtaskId,
+    sourceUrl: result.repairNode?.detourUrl || request.url,
+    result,
+  };
+}

package/src/agent-mission/claude-headless.ts

@@ -30,10 +30,11 @@ const string = (value: unknown): string | null => typeof value === 'string' ? va
 const number = (value: unknown): number | null => typeof value === 'number' && Number.isFinite(value) ? value : null;
 
 /** Run the non-interactive Claude CLI with a pipe, never passing the prompt as an argv value. */
-export async function runClaudeHeadless({ cwd, prompt, env, spawn = nodeSpawn, timeoutMs = 1_800_000, maxTurns, onSpawn }: {
+export async function runClaudeHeadless({ cwd, prompt, env, resumeSessionId, spawn = nodeSpawn, timeoutMs = 1_800_000, maxTurns, onSpawn }: {
   cwd: string;
   prompt: string;
   env: NodeJS.ProcessEnv;
+  resumeSessionId?: string;
   spawn?: Spawn;
   timeoutMs?: number;
   maxTurns?: number;
@@ -42,6 +43,7 @@ export async function runClaudeHeadless({ cwd, prompt, env, spawn = nodeSpawn, t
   if (maxTurns !== undefined && (!Number.isSafeInteger(maxTurns) || maxTurns < 1)) {
     throw new Error('Claude headless maxTurns must be a positive integer');
   }
+  if (resumeSessionId !== undefined && !resumeSessionId.trim()) throw new Error('Claude resume session id must not be empty');
   let child: ChildProcessWithoutNullStreams;
   const base: ClaudeHeadlessResult = {
     ok: false, reason: 'no-result', exitCode: null, result: null, subtype: null,
@@ -51,6 +53,7 @@ export async function runClaudeHeadless({ cwd, prompt, env, spawn = nodeSpawn, t
   try {
     child = spawn('claude', [
       '-p', '--output-format', 'stream-json', '--verbose', '--dangerously-skip-permissions',
+      ...(resumeSessionId === undefined ? [] : ['--resume', resumeSessionId]),
       ...(maxTurns === undefined ? [] : ['--max-turns', String(maxTurns)]),
     ], { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] });
   } catch {