elanous 0.2.42 → 0.2.43

package/src/tool-runtime/graph-mcp-runtimes.ts

@@ -0,0 +1,240 @@
+// External graph control uses the same wizard, editor run API, and runner as the local UI.
+// The MCP HTTP boundary filters mutating tools by token scope before dispatch.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { LLMToolSpec } from '../llm.js';
+import { debug } from '../debug/log.js';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { generateGraphFromPrompt } from '../graph-wizard/generate.js';
+import { handleGraphsCreate } from '../nexus/api/graphs-api.js';
+import { handleGraphRunGet, handleGraphRunStart } from '../graph-runner/graph-run-api.js';
+import { proposeGrowth } from '../graph-runner/graph-grow.js';
+import { runGraph, type GraphRunState } from '../graph-runner/runner.js';
+import { parseGraphTemplateYaml } from '../self-implement/graph-yaml.js';
+import type { ToolRuntime, ToolRuntimeContext } from './types.js';
+
+const GRAPH_ID = /^[a-z0-9-]+$/;
+const RUN_ID = /^ed-[a-z0-9]+-[a-f0-9]{6}$/;
+type Args = Record<string, unknown>;
+type Result = { output: string; [key: string]: unknown };
+export interface GraphMcpDeps {
+  root?: string;
+  mineDir?: string;
+  recipesFile?: string;
+  generate?: typeof generateGraphFromPrompt;
+  growth?: typeof proposeGrowth;
+  run?: typeof runGraph;
+}
+let testDeps: GraphMcpDeps = {};
+export function setGraphMcpDepsForTest(deps: GraphMcpDeps | undefined): void { testDeps = deps ?? {}; }
+const rootOf = () => testDeps.root ?? effectiveInstanceRoot();
+
+function value(args: Args, key: string): string | null {
+  const item = args[key];
+  return typeof item === 'string' && item.trim() ? item.trim() : null;
+}
+
+function error(tool: string, reason: string): Result {
+  return { output: `${tool}: ${reason}`, error: reason };
+}
+
+function observe(tool: string, action: string, ctx: ToolRuntimeContext, fields: Record<string, unknown>): void {
+  debug.log('mcp.graph', action, { tool, caller: ctx.mcpClient ?? 'unknown', ...fields });
+}
+
+function spec(name: string, description: string, properties: Record<string, unknown>, required: string[]): LLMToolSpec {
+  return { name, description, parameters: { type: 'object', properties, required } };
+}
+
+const composeSpec = spec('graph_compose', 'Preview a validated graph from one research goal. Does not save or run it.',
+  { goal: { type: 'string' } }, ['goal']);
+const startSpec = spec('graph_run_start', 'Start an existing saved graph, or save and start a graph_compose result. Requires a write-scoped MCP token.',
+  { graphId: { type: 'string' }, compose: { type: 'object', description: 'graph_compose result: id, yaml, optional validated steps.' },
+    reason: { type: 'string' } }, ['reason']);
+const statusSpec = spec('graph_run_status', 'Read bounded node states, outputs, and source IDs for a graph run.',
+  { graphId: { type: 'string' }, runId: { type: 'string' } }, ['graphId', 'runId']);
+const nodeSpec = spec('graph_node_op', 'Operate on a saved run: retry from a failed node, or add a validated growth node as a new linked run. Requires a write-scoped MCP token.',
+  { graphId: { type: 'string' }, runId: { type: 'string' }, op: { type: 'string', enum: ['retry', 'add-node'] },
+    nodeId: { type: 'string' }, outcome: { type: 'string' }, reason: { type: 'string' } },
+  ['graphId', 'runId', 'op', 'nodeId', 'reason']);
+
+function storedRun(graphId: string, runId: string, root: string): GraphRunState | null {
+  if (!GRAPH_ID.test(graphId) || !RUN_ID.test(runId)) return null;
+  try {
+    const state = JSON.parse(readFileSync(join(root, 'graph-runs', graphId, `${runId}.json`), 'utf8')) as GraphRunState;
+    return state.graphId === graphId && state.runId === runId ? state : null;
+  } catch { return null; }
+}
+
+async function compose(args: Args, ctx: ToolRuntimeContext): Promise<Result> {
+  const goal = value(args, 'goal');
+  if (!goal) return error('graph_compose', 'goal is required');
+  try {
+    const result = await (testDeps.generate ?? generateGraphFromPrompt)({ prompt: goal, kind: 'harness' });
+    observe('graph_compose', result.ok ? 'composed' : 'rejected', ctx, { graphId: result.id, reason: result.summary });
+    return { output: result.summary, ...result, compose: result.ok
+      ? { id: result.id, yaml: result.yaml, ...(result.steps ? { steps: result.steps } : {}) } : null };
+  } catch (cause) {
+    const reason = cause instanceof Error ? cause.message : String(cause);
+    observe('graph_compose', 'failed', ctx, { reason });
+    return error('graph_compose', reason);
+  }
+}
+
+async function start(args: Args, ctx: ToolRuntimeContext): Promise<Result> {
+  const reason = value(args, 'reason');
+  const supplied = args.compose;
+  const candidate = supplied && typeof supplied === 'object' && !Array.isArray(supplied)
+    ? supplied as Record<string, unknown> : null;
+  const graphId = candidate ? value(candidate, 'id') : value(args, 'graphId');
+  if (!reason || !graphId || !GRAPH_ID.test(graphId)) return error('graph_run_start', 'valid graphId and reason are required');
+  if (candidate) {
+    if (typeof candidate.yaml !== 'string') return error('graph_run_start', 'compose.yaml is required');
+    const created = await handleGraphsCreate(new Request('http://localhost/v1/graphs', {
+      method: 'POST', headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ id: graphId, yaml: candidate.yaml, ...(candidate.steps ? { steps: candidate.steps } : {}) }),
+    }), { ...(testDeps.mineDir ? { mineDir: testDeps.mineDir } : {}) });
+    if (!created.ok) {
+      const detail = await created.text();
+      observe('graph_run_start', 'refused', ctx, { graphId, reason, status: created.status });
+      return error('graph_run_start', `save refused (${created.status}): ${detail.slice(0, 300)}`);
+    }
+  }
+  const response = handleGraphRunStart(graphId, {
+    ...(testDeps.mineDir ? { mineDir: testDeps.mineDir } : {}),
+    root: rootOf(),
+    ...(testDeps.recipesFile ? { recipesFile: testDeps.recipesFile } : {}),
+  });
+  const body = await response.json() as Record<string, unknown>;
+  observe('graph_run_start', response.ok ? 'started' : 'refused', ctx,
+    { graphId, runId: body.runId ?? null, reason, status: response.status });
+  return { output: response.ok ? `Started ${graphId} run ${body.runId}` : `Start refused: ${JSON.stringify(body)}`,
+    ...body, status: response.status };
+}
+
+async function status(args: Args, ctx: ToolRuntimeContext): Promise<Result> {
+  const graphId = value(args, 'graphId');
+  const runId = value(args, 'runId');
+  if (!graphId || !runId || !GRAPH_ID.test(graphId) || !RUN_ID.test(runId)) return error('graph_run_status', 'invalid graphId or runId');
+  const response = handleGraphRunGet(graphId, runId, { root: rootOf() });
+  const body = await response.json() as Record<string, unknown>;
+  if (!response.ok) {
+    const reason = typeof body.reason === 'string' ? body.reason
+      : typeof body.error === 'string' ? body.error : `request failed (${response.status})`;
+    observe('graph_run_status', 'refused', ctx, { graphId, runId, status: response.status, error: reason });
+    return error('graph_run_status', reason);
+  }
+  const state = storedRun(graphId, runId, rootOf());
+  let truncated = false;
+  const clip = (text: string, max: number) => {
+    if (text.length > max) truncated = true;
+    return text.slice(0, max);
+  };
+  const allNodes = state?.nodes.map(node => {
+    const record = node.output && typeof node.output === 'object' && !Array.isArray(node.output)
+      ? node.output as Record<string, unknown> : null;
+    const sourceIds = [record?.sourceIds, record?.refs, record?.citations]
+      .flatMap(item => Array.isArray(item) ? item.filter((id): id is string => typeof id === 'string') : [])
+      .slice(0, 30);
+    const encodedOutput = node.output === undefined ? undefined : JSON.stringify(node.output);
+    if (sourceIds.length > 10) truncated = true;
+    return { nodeId: clip(node.nodeId, 160), ok: node.ok, exit: node.exit, executed: node.executed,
+      ...(node.error ? { error: clip(node.error, 300) } : {}),
+      sourceIds: sourceIds.slice(0, 10).map(id => clip(id, 120)),
+      ...(encodedOutput === undefined ? {} : { output: clip(encodedOutput, 800) }) };
+  }) ?? [];
+  const rawPath = Array.isArray(body.path) ? body.path : [];
+  const errorText = typeof body.error === 'string' ? body.error : undefined;
+  let nodes = [...allNodes].sort((a, b) => Number(b.ok === false) - Number(a.ok === false)).slice(0, 30);
+  let path = rawPath.slice(0, 100).map(nodeId => clip(String(nodeId), 160));
+  if (allNodes.length > nodes.length || rawPath.length > path.length) truncated = true;
+  const statusValue = clip(String(body.status ?? 'unknown'), 40);
+  const graphIdValue = clip(graphId, 120);
+  const runIdValue = clip(runId, 120);
+  const startedAt = typeof body.startedAt === 'string' ? clip(body.startedAt, 100) : undefined;
+  const finishedAt = typeof body.finishedAt === 'string' ? clip(body.finishedAt, 100) : undefined;
+  const boundedError = errorText ? clip(errorText, 1000) : undefined;
+  const serialize = () => JSON.stringify({
+    graphId: graphIdValue, runId: runIdValue, status: statusValue,
+    ...(startedAt ? { startedAt } : {}), ...(finishedAt ? { finishedAt } : {}),
+    ...(boundedError ? { error: boundedError } : {}), path, nodes, truncated,
+  });
+  let encoded = serialize();
+  while (Buffer.byteLength(encoded, 'utf8') > 24000 && nodes.length > 0) {
+    nodes = nodes.slice(0, -1);
+    truncated = true;
+    encoded = serialize();
+  }
+  while (Buffer.byteLength(encoded, 'utf8') > 24000 && path.length > 0) {
+    path = path.slice(0, -1);
+    truncated = true;
+    encoded = serialize();
+  }
+  if (Buffer.byteLength(encoded, 'utf8') > 24000) {
+    truncated = true;
+    path = [];
+    nodes = [];
+    encoded = serialize();
+  }
+  observe('graph_run_status', 'read', ctx, { graphId, runId, status: body.status ?? response.status });
+  return { output: encoded, ...JSON.parse(encoded) as Record<string, unknown> };
+}
+
+async function nodeOp(args: Args, ctx: ToolRuntimeContext): Promise<Result> {
+  const graphId = value(args, 'graphId');
+  const runId = value(args, 'runId');
+  const op = value(args, 'op');
+  const nodeId = value(args, 'nodeId');
+  const reason = value(args, 'reason');
+  if (!graphId || !runId || !GRAPH_ID.test(graphId) || !RUN_ID.test(runId) || !nodeId || !reason
+    || !['retry', 'add-node'].includes(op ?? '')) return error('graph_node_op', 'invalid graphId, runId, op, nodeId, or reason');
+  if (op === 'add-node' && !value(args, 'outcome'))
+    return error('graph_node_op', 'add-node requires the observed node outcome');
+  const root = rootOf();
+  const state = storedRun(graphId, runId, root);
+  if (!state || state.status !== 'failed' || !state.path.includes(nodeId))
+    return error('graph_node_op', 'a failed run and node on its saved path are required');
+  const graphFile = join(root, 'graph-run-work', graphId, runId, 'graph.yaml');
+  if (op === 'retry') {
+    try {
+      // Runner enforces the saved source hash, approval boundary, and failed-path limit.
+      const next = await (testDeps.run ?? runGraph)(graphFile, { resumeRunId: runId, fromNodeId: nodeId, deps: { root } });
+      observe('graph_node_op', op, ctx, { graphId, runId, nodeId, reason, status: next.status });
+      return { output: `${op}: ${next.status}`, graphId, runId, status: next.status, path: next.path };
+    } catch (cause) {
+      const message = cause instanceof Error ? cause.message : String(cause);
+      observe('graph_node_op', 'refused', ctx, { graphId, runId, nodeId, op, reason, error: message });
+      return error('graph_node_op', message);
+    }
+  }
+  try {
+    const parsed = parseGraphTemplateYaml(readFileSync(graphFile, 'utf8'), graphFile);
+    if (!parsed.template || parsed.errors.length) return error('graph_node_op', 'saved graph is invalid');
+    const nodeOutput = [...state.nodes].reverse().find(node => node.nodeId === nodeId)?.output;
+    const outcome = value(args, 'outcome')!;
+    const growth = await (testDeps.growth ?? proposeGrowth)({ graph: parsed.template, nodeId, outcome, runId, output: nodeOutput },
+      undefined, () => 'unknown', { root });
+    if (!growth.ok) {
+      observe('graph_node_op', 'refused', ctx, { graphId, runId, nodeId, op, reason, detail: growth.reason });
+      return error('graph_node_op', growth.reason);
+    }
+    const returnTo = growth.growth.edges.find(edge => edge.from === growth.growth.node.nodeId)?.to;
+    if (!returnTo) return error('graph_node_op', 'growth has no return node');
+    const next = await (testDeps.run ?? runGraph)(graphFile, { variant: { goal: `mcp_${runId}`,
+      plan: { growth: { node: growth.growth.node, from: nodeId, outcome,
+        returnTo } } }, input: { source: 'mcp', parentRunId: runId, reason }, deps: { root } });
+    observe('graph_node_op', 'add-node', ctx, { graphId, runId: next.runId, parentRunId: runId, nodeId, reason, status: next.status });
+    return { output: `add-node: ${next.status}`, graphId, runId: next.runId, parentRunId: runId, status: next.status };
+  } catch (cause) {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    observe('graph_node_op', 'refused', ctx, { graphId, runId, nodeId, op, reason, error: message });
+    return error('graph_node_op', message);
+  }
+}
+
+export const GRAPH_MCP_RUNTIMES: ToolRuntime<Args, Result>[] = [
+  { id: 'graph_compose', spec: composeSpec, surfaces: ['mcp'], run: compose },
+  { id: 'graph_run_start', spec: startSpec, surfaces: ['mcp'], run: start },
+  { id: 'graph_run_status', spec: statusSpec, surfaces: ['mcp'], run: status },
+  { id: 'graph_node_op', spec: nodeSpec, surfaces: ['mcp'], run: nodeOp },
+];

package/src/tool-runtime/index.ts

@@ -62,11 +62,14 @@ import { skillExecRuntime } from './skill-exec-runtime.js';
 import { elanousObsidianSearchRuntime } from './elanous-obsidian-search-runtime.js';
 import { elanousObsidianInfoRuntime } from './elanous-obsidian-info-runtime.js';
 import { ELANOUS_ASANA_RUNTIMES } from './elanous-asana-runtimes.js';
+import { elanousLinearSecretaryRuntime } from './elanous-linear-secretary-runtime.js';
+import { elanousLinearIssueRuntime } from './elanous-linear-issue-runtime.js';
 import { elanousFsListRuntime } from './elanous-fs-list-runtime.js';
 import { elanousFsReadRuntime } from './elanous-fs-read-runtime.js';
 import { elanousShowroomBroadcastRuntime } from './elanous-showroom-broadcast-runtime.js';
 import { elanousAutopilotLaunchRuntime } from './elanous-autopilot-launch-runtime.js';
 import { elanousTaskSubmitRuntime } from './elanous-task-submit-runtime.js';
+import { GRAPH_MCP_RUNTIMES } from './graph-mcp-runtimes.js';
 import { persistentGroundingRuntime } from './persistent-grounding-runtime.js';
 import { goalAuthorRuntime } from './goal-author-runtime.js';
 import { bootstrapMcpProxyRuntimes } from './mcp-proxy-bootstrap.js';
@@ -167,11 +170,14 @@ export function registerAllDefaultToolRuntimes(opts: RegisterAllDefaultToolRunti
   registerToolRuntime(elanousObsidianSearchRuntime);
   registerToolRuntime(elanousObsidianInfoRuntime);
   for (const rt of ELANOUS_ASANA_RUNTIMES) registerToolRuntime(rt);
+  registerToolRuntime(elanousLinearSecretaryRuntime);
+  registerToolRuntime(elanousLinearIssueRuntime);
   registerToolRuntime(elanousFsListRuntime);
   registerToolRuntime(elanousFsReadRuntime);
   registerToolRuntime(elanousShowroomBroadcastRuntime);
   registerToolRuntime(elanousAutopilotLaunchRuntime);
   registerToolRuntime(elanousTaskSubmitRuntime);
+  for (const rt of GRAPH_MCP_RUNTIMES) registerToolRuntime(rt);
   for (const rt of SELF_COGNITION_RUNTIMES) registerToolRuntime(rt);
   for (const rt of ELANOUS_CONTROL_RUNTIMES) registerToolRuntime(rt);
   // External MCP proxies already declare surfaces `['mcp','tui']`, but the

package/src/tool-runtime/types.ts

@@ -66,6 +66,9 @@ export interface ToolRuntimeContext {
     dispatch: (name: string, args: Record<string, unknown>) => Promise<unknown>;
     workingDirectory: string;
   };
+  /** TUI-only opt-in for inheriting the parent's policy-filtered catalog when
+   *  the general-purpose agent definition omits its own tool allowlist. */
+  inheritGeneralPurposeToolCatalog?: boolean;
   /** M5 (PLAN-rich-dev-feedback-multi-surface · 2026-05-13) —
    *  optional progress emitter. Runtimes that produce streaming
    *  side effects (bash stdout tail, search hit streaming, edit

package/src/tui/entry.ts

@@ -99,6 +99,9 @@ export async function showNextTui(options: NextTuiOptions = {}): Promise<void> {
   let sidetabChordTimer: ReturnType<typeof setTimeout> | null = null;
   let sidetabRemoteFrame: string | null = null;
   let sidetabRows: import('./sidetab/list.js').SidetabRow[] = [];
+  let herdrSidetabRows: import('./sidetab/list.js').SidetabRow[] = [];
+  let herdrSidetabRefreshPending = false;
+  let herdrSidetabPortal: import('./sidetab/herdr-portal.js').HerdrSidetabPortal | null = null;
   let sidetabApi: typeof import('./sidetab/list.js') | null = null;
   // ⚠️ `as` 단언은 «null 로 좁혀지는» 흐름 분석을 푸는 것 — 값은 클로저(ensureSidetabAttachments) 안에서만 바뀐다.
   let sidetabAttachments: import('./sidetab/attach.js').SidetabAttachmentController | null = null as import('./sidetab/attach.js').SidetabAttachmentController | null;
@@ -357,6 +360,8 @@ export async function showNextTui(options: NextTuiOptions = {}): Promise<void> {
 
   const ensureSidetabAttachments = async (): Promise<void> => {
     if (sidetabAttachments) return;
+    const herdrPortalModule = await import('./sidetab/herdr-portal.js');
+    herdrSidetabPortal ??= herdrPortalModule.createHerdrSidetabPortal();
     const installer = await import('../agent-mission/tool-install.js') as unknown as {
       detectAgentCli?: (agent: 'codex' | 'claude') => Promise<{
         agent: 'codex' | 'claude'; installed: boolean; version: string | null;
@@ -364,6 +369,8 @@ export async function showNextTui(options: NextTuiOptions = {}): Promise<void> {
       }>;
     };
     sidetabAttachments = (await import('./sidetab/attach.js')).createSidetabAttachmentController({
+      herdrPortal: herdrSidetabPortal,
+      logEvent: (category, event, data) => debug.log(category, event, data),
       drawBase: () => {
         paintingCoordinatorFrame = true;
         try { render(); } finally { paintingCoordinatorFrame = false; }
@@ -403,9 +410,11 @@ export async function showNextTui(options: NextTuiOptions = {}): Promise<void> {
     sidetabSelected = next.selected;
     sidetabMode = 'list';
     if (sidetabOpen && sidetabRefreshTimer === null) {
+      void refreshHerdrSidetabRows();
       sidetabRefreshTimer = setInterval(() => {
         if (!sidetabOpen || !sidetabApi) return;
         refreshSidetabRows();
+        void refreshHerdrSidetabRows();
         render();
       }, 1000);
     } else if (!sidetabOpen && sidetabRefreshTimer !== null) {
@@ -417,12 +426,24 @@ export async function showNextTui(options: NextTuiOptions = {}): Promise<void> {
   const refreshSidetabRows = (): void => {
     if (!sidetabApi) return;
     const selectedId = sidetabRows[sidetabSelected]?.id;
-    sidetabRows = sidetabApi.loadSidetabRows(sidetabAll);
+    sidetabRows = [...sidetabApi.loadSidetabRows(sidetabAll), ...herdrSidetabRows];
     const preservedIndex = selectedId ? sidetabRows.findIndex((row) => row.id === selectedId) : -1;
     sidetabSelected = preservedIndex >= 0
       ? preservedIndex
       : Math.min(sidetabSelected, Math.max(0, sidetabRows.length - 1));
   };
+  const refreshHerdrSidetabRows = async (): Promise<void> => {
+    if (herdrSidetabRefreshPending) return;
+    herdrSidetabRefreshPending = true;
+    try {
+      const portal = await import('./sidetab/herdr-portal.js');
+      herdrSidetabPortal ??= portal.createHerdrSidetabPortal();
+      await herdrSidetabPortal.refreshRows();
+      herdrSidetabRows = [...herdrSidetabPortal.rows()];
+      refreshSidetabRows();
+    } catch { /* Herdr is optional; TUI rows remain available. */ }
+    finally { herdrSidetabRefreshPending = false; }
+  };
   const switchSidetabSession = async (requestedSessionId?: string): Promise<void> => {
     const selected = sidetabRows[sidetabSelected];
     const targetId = requestedSessionId ?? (selected?.kind === 'tui' ? selected.sessionId : undefined);
@@ -667,9 +688,11 @@ export async function showNextTui(options: NextTuiOptions = {}): Promise<void> {
   if (sidetabOpen) {
     sidetabApi = await import('./sidetab/list.js');
     sidetabRows = sidetabApi.loadSidetabRows(sidetabAll);
+    void refreshHerdrSidetabRows();
     sidetabRefreshTimer = setInterval(() => {
       if (!sidetabApi || !sidetabOpen) return;
       refreshSidetabRows();
+      void refreshHerdrSidetabRows();
       render();
     }, 1_000);
   }

package/src/tui/sidetab/attach.ts

@@ -7,9 +7,10 @@ import { createTerminalModalRouter } from '../../terminal/terminal-modal-router.
 import { getSessionCwd } from '../../session/working-dir.js';
 import { TerminalSessionRegistry, type TerminalSession } from '../../terminal/session-registry.js';
 import { requestRemotePtyControl } from '../../pty-shell/pty-control-ipc.js';
-import { runVisibleAgentMission } from '../../sidetab-core/visible-agent-mission.js';
+import { runVisibleAgentMission, type VisibleMissionPty, type VisibleMissionResult } from '../../sidetab-core/visible-agent-mission.js';
 import type { Key } from '../../tui.js';
 import type { SidetabRow } from './list.js';
+import { createHerdrSidetabPortal, herdrPaneIdFromSidetabRow, type HerdrSidetabPortal } from './herdr-portal.js';
 
 export type SidetabCharacter = 'shell' | 'elanous' | 'codex' | 'claude';
 
@@ -35,13 +36,35 @@ export interface AgentCliDetection {
   message: string;
 }
 
+export function sidetabMissionFailureLog(agent: 'codex' | 'claude', result: VisibleMissionResult): {
+  event: 'startup-screen-failed' | 'mission-failed';
+  data: Record<string, unknown>;
+} | undefined {
+  if (result.ok) return undefined;
+  const startupBlocked = !result.promptReady;
+  return {
+    event: startupBlocked ? 'startup-screen-failed' : 'mission-failed',
+    data: {
+      agent,
+      screen: startupBlocked ? result.startupScreen ?? 'unclassified' : 'none',
+      error: result.startupScreen && startupBlocked ? 'known-startup-screen-blocked' : startupBlocked ? 'startup-unclassified' : 'mission-or-result-failed',
+    },
+  };
+}
+
 export function createSidetabAttachmentController(deps: {
   drawBase(): void;
   termSize(): { cols: number; rows: number };
   setStatus(message: string): void;
   drawRemoteFrame(frame: string): void;
+  logEvent?(category: string, event: string, data: Record<string, unknown>): void;
+  herdrPortal?: HerdrSidetabPortal;
   /** Owned by OPT; a missing detector keeps the hook inert until its API lands. */
   detectAgentCli?(agent: 'codex' | 'claude'): Promise<AgentCliDetection>;
+  /** Test seam for exercising the visible mission path without launching an external CLI. */
+  createVisibleMissionPty?(agent: 'codex' | 'claude'): { pty: VisibleMissionPty; cwd: string };
+  /** Runner seam keeps the controller path testable with short deterministic mission timeouts. */
+  visibleMissionRunner?: typeof runVisibleAgentMission;
 }): SidetabAttachmentController {
   const eventBus = createDisplayEventBus();
   const coordinator = new DisplayCoordinator({
@@ -58,6 +81,23 @@ export function createSidetabAttachmentController(deps: {
   let remoteFrameTimer: ReturnType<typeof setInterval> | null = null;
   let remoteFramePending = false;
   let remoteHasFrame = false;
+  const herdrPortal = deps.herdrPortal ?? createHerdrSidetabPortal();
+  let herdrPaneId: string | null = null;
+  let herdrTakenOver = false;
+  let herdrFrameTimer: ReturnType<typeof setInterval> | null = null;
+  let herdrFramePending = false;
+  const herdrInputQueues = new Map<string, Promise<void>>();
+
+  const enqueueHerdrInput = (paneId: string, send: () => Promise<void>): void => {
+    const previous = herdrInputQueues.get(paneId) ?? Promise.resolve();
+    let current: Promise<void>;
+    current = previous.catch(() => {}).then(send).catch((error: unknown) => {
+      if (herdrPaneId === paneId) deps.setStatus(`Herdr 입력 실패 · ${error instanceof Error ? error.message : String(error)}`);
+    }).finally(() => {
+      if (herdrInputQueues.get(paneId) === current) herdrInputQueues.delete(paneId);
+    });
+    herdrInputQueues.set(paneId, current);
+  };
   let lastSpawnedSession: TerminalSession | null = null;
 
   const stopRemote = (): void => {
@@ -71,8 +111,42 @@ export function createSidetabAttachmentController(deps: {
     deps.drawRemoteFrame('');
   };
 
+  const stopHerdr = (): void => {
+    if (herdrFrameTimer !== null) clearInterval(herdrFrameTimer);
+    herdrFrameTimer = null;
+    herdrPaneId = null;
+    herdrTakenOver = false;
+    deps.drawRemoteFrame('');
+  };
+
+  const startHerdr = (row: SidetabRow): boolean => {
+    const paneId = herdrPaneIdFromSidetabRow(row);
+    if (!paneId || !herdrPortal.enabled()) {
+      deps.setStatus('Herdr 연결은 HERDR_ENV=1인 관리 세션에서만 사용할 수 있습니다');
+      return false;
+    }
+    stopRemote();
+    stopHerdr();
+    herdrPaneId = paneId;
+    const refresh = async (): Promise<void> => {
+      if (herdrFramePending || herdrPaneId !== paneId) return;
+      herdrFramePending = true;
+      try {
+        const frame = await herdrPortal.readPane(paneId);
+        if (herdrPaneId === paneId) deps.drawRemoteFrame(frame);
+      } catch (error) {
+        if (herdrPaneId === paneId) deps.setStatus(`Herdr pane 읽기 실패 · ${error instanceof Error ? error.message : String(error)}`);
+      } finally { herdrFramePending = false; }
+    };
+    void refresh();
+    herdrFrameTimer = setInterval(() => { void refresh(); }, 250);
+    deps.setStatus('Herdr pane 관측 · t takeover · Esc / Ctrl+\\ 복귀 · Ctrl+Q 전체 종료 (Ctrl+[는 Esc로 읽힐 수 있음)');
+    return true;
+  };
+
   const startRemote = (row: SidetabRow): boolean => {
     if (!row.ptyId) return false;
+    stopHerdr();
     stopRemote();
     remotePtyId = row.ptyId;
     const id = row.ptyId;
@@ -192,6 +266,7 @@ export function createSidetabAttachmentController(deps: {
   return {
     attach(row) {
       stopRemote();
+      if (row.kind === 'herdr') return startHerdr(row);
       if (row.currentProcess) {
         showMain();
         return true;
@@ -210,6 +285,7 @@ export function createSidetabAttachmentController(deps: {
       return attached ? setModal(attached) : false;
     },
     select(row) {
+      if (row.kind === 'herdr') return startHerdr(row);
       if (row.ptyId && !row.currentProcess && !sessionForRow(row)) return startRemote(row);
       if (row.currentProcess) {
         showMain();
@@ -226,29 +302,44 @@ export function createSidetabAttachmentController(deps: {
         catch (error) {
           const message = `${agent} CLI 확인에 실패했습니다: ${error instanceof Error ? error.message : String(error)}`;
           deps.setStatus(message);
-          return { ok: false, path: '', promptReady: false, missionVisible: false, completionMarker: false, error: message };
+          return { ok: false, path: '', promptReady: false, missionVisible: false, promptReturned: false, completionMarker: false, error: message };
         }
         if (!detection.installed) {
           const message = `${detection.message} · 설치 확인 후 미션을 다시 요청하세요`;
           deps.setStatus(message);
-          return { ok: false, path: '', promptReady: false, missionVisible: false, completionMarker: false, error: message };
+          return { ok: false, path: '', promptReady: false, missionVisible: false, promptReturned: false, completionMarker: false, error: message };
         }
       }
       lastSpawnedSession = null;
-      if (!spawn(agent) || !lastSpawnedSession?.modal) {
-        return { ok: false, path: '', promptReady: false, missionVisible: false, completionMarker: false, error: `${agent} side-tab PTY could not start` };
+      const injectedMissionPty = deps.createVisibleMissionPty?.(agent);
+      let modal: VisibleMissionPty;
+      let cwd: string;
+      if (injectedMissionPty) {
+        modal = injectedMissionPty.pty;
+        cwd = injectedMissionPty.cwd;
+      } else {
+        const spawned = spawn(agent);
+        const session = lastSpawnedSession as TerminalSession | null;
+        if (!spawned || !session?.modal) {
+          return { ok: false, path: '', promptReady: false, missionVisible: false, promptReturned: false, completionMarker: false, error: `${agent} side-tab PTY could not start` };
+        }
+        modal = session.modal;
+        cwd = session.cwd;
       }
-      const session = lastSpawnedSession;
-      const outputPath = join(session.cwd, '.elanous', 'mission-results', `sidetab-${Date.now()}.md`);
+      const outputPath = join(cwd, '.elanous', 'mission-results', `sidetab-${Date.now()}.md`);
       const backend = agent === 'codex' ? codexBackend : claudeBackend;
-      const result = await runVisibleAgentMission({
-        pty: session.modal,
+      const result = await (deps.visibleMissionRunner ?? runVisibleAgentMission)({
+        pty: modal,
+        agent,
         mission,
         outputPath,
+        onStartupScreen: (screen) => deps.logEvent?.('agent-mission.sidetab', 'startup-screen', { agent, screen }),
         handleTrust: (screen, write) => backend.handleTrust?.(screen, write) ?? false,
       });
+      const failureLog = sidetabMissionFailureLog(agent, result);
+      if (failureLog) deps.logEvent?.('agent-mission.sidetab', failureLog.event, failureLog.data);
       showMain();
-      deps.setStatus(result.ok ? `미션 결과 확인 · ${result.path}` : `미션 확인 실패 · ${result.error}`);
+      deps.setStatus(result.ok ? `미션 결과 확인 · ${result.path}` : `미션 확인 실패 · ${result.promptReady ? agent : result.startupScreen ?? agent} · ${result.error}`);
       return result;
     },
     kill(row) {
@@ -276,6 +367,42 @@ export function createSidetabAttachmentController(deps: {
       return true;
     },
     handleKey(key) {
+      if (herdrPaneId) {
+        if (key.name.toLowerCase() === 'escape') {
+          stopHerdr();
+          deps.setStatus('Herdr pane에서 복귀');
+          return true;
+        }
+        if (key.ctrl && key.name.toLowerCase() === 'q') {
+          stopHerdr();
+          deps.setStatus('Herdr pane에서 복귀');
+          return false;
+        }
+        if (key.ctrl && (key.name === '\\' || key.raw === '\x1c')) {
+          stopHerdr();
+          deps.setStatus('Herdr pane에서 복귀');
+          return false;
+        }
+        if (key.name.toLowerCase() === 't' && !herdrTakenOver) {
+          herdrTakenOver = true;
+          deps.setStatus('Herdr pane takeover · Esc로 복귀');
+          return true;
+        }
+        const raw = key.raw;
+        if (herdrTakenOver && raw) {
+          const paneId = herdrPaneId;
+          if (raw.includes('\x00')) {
+            deps.setStatus('NUL 입력은 Herdr pane에 보낼 수 없습니다');
+            return true;
+          }
+          const send = (raw.length === 1 && (raw.charCodeAt(0) < 32 || raw.charCodeAt(0) === 0x7f)) || raw.startsWith('\x1b')
+            ? () => herdrPortal.sendKey(paneId, raw)
+            : () => herdrPortal.sendText(paneId, raw);
+          enqueueHerdrInput(paneId, send);
+          return true;
+        }
+        return true;
+      }
       if (remotePtyId) {
         // Keep global TUI controls reachable while a remote snapshot is displayed.
         if (key.ctrl && key.name.toLowerCase() === 'q') return false;
@@ -329,10 +456,11 @@ export function createSidetabAttachmentController(deps: {
       return routed !== 'passthrough';
     },
     hasModal: () => modalRouter.current() !== null,
-    hasRemoteView: () => remotePtyId !== null,
+    hasRemoteView: () => remotePtyId !== null || herdrPaneId !== null,
     refresh: () => coordinator.requestRenderNow({ force: true }),
     close() {
       stopRemote();
+      stopHerdr();
       modalRouter.close();
       for (const session of registry.list()) registry.kill(session.id);
     },
@@ -340,6 +468,7 @@ export function createSidetabAttachmentController(deps: {
 
   function showMain(): void {
     stopRemote();
+    stopHerdr();
     if (attachedSessionId === null) return;
     modalRouter.close();
     coordinator.requestRenderNow({ force: true });