elanous 0.2.41 → 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/skill-exec-runtime.ts

@@ -3,6 +3,8 @@ import * as harnessSkillExec from '../harness/skill-exec.js';
 import { invokeResearch } from '../research-bridge/invoke.js';
 import * as skillIndex from '../skills/index.js';
 import type { SkillIndexEntry } from '../skills/index.js';
+import { dirname } from 'node:path';
+import { resolveSkillName } from '../skills/name-match.js';
 import { getUserConfig } from '../user-config.js';
 import type { LLMToolSpec } from '../llm.js';
 import type { ToolRuntime } from './types.js';
@@ -17,7 +19,7 @@ export interface SkillExecRunOptions {
 }
 
 export interface SkillExecArgs {
-  /** Exact name of the skill to execute. */
+  /** Installed skill name; spaces/punctuation may be omitted if the match is unique. */
   skill: string;
   /** Task text passed verbatim to the named skill. */
   task: string;
@@ -33,6 +35,8 @@ export interface SkillExecResult extends Record<string, unknown> {
 
 export interface SkillExecDiscoveryDeps {
   discoverPlugin?: (gap: string, deps?: { signal?: AbortSignal }) => Promise<{ card: string }>;
+  /** Test seam for the bounded plugin-discovery follow-up. */
+  discoveryTimeoutMs?: number;
 }
 
 export type SkillExecIndexProvider = () => readonly SkillIndexEntry[];
@@ -71,13 +75,13 @@ function obtainSkillIndex(): readonly SkillIndexEntry[] {
 export function buildSkillExecTool(): LLMToolSpec {
   return {
     name: 'skill_exec',
-    description: 'Execute one explicitly named allowlisted skill with the supplied task. If you do not know the exact skill name, call elanous_skills_list first. Does not infer a skill name.',
+    description: 'Execute one explicitly named allowlisted skill with the supplied task. Names may omit spaces or punctuation (for example, "krflow" resolves to "kr-flow") only when the installed match is unique. Call elanous_skills_list when uncertain.',
     parameters: {
       type: 'object',
       properties: {
         skill: {
           type: 'string',
-          description: 'Exact name of the skill to execute.',
+          description: 'Installed skill name; spaces and punctuation may be omitted when the match is unique.',
         },
         task: {
           type: 'string',
@@ -95,9 +99,19 @@ export async function dispatchSkillExec(
   deps: SkillExecDiscoveryDeps = {},
   options: SkillExecRunOptions = {},
 ): Promise<SkillExecResult> {
-  const { skill, task } = args;
+  const { skill: requestedSkill, task } = args;
+  if (requestedSkill !== requestedSkill.trim()) {
+    return { skill: requestedSkill, ok: false, output: REJECT_OUTPUT(requestedSkill) };
+  }
   const extra = getUserConfig().skillRouter.harnessExecAllowlist;
   const index = obtainSkillIndex();
+  const resolution = resolveSkillName(requestedSkill, index);
+  const skill = resolution.entry?.name ?? requestedSkill;
+  if (resolution.ambiguous.length > 0) {
+    const candidates = resolution.ambiguous.map((entry) => entry.name).sort().join(', ');
+    return { skill: requestedSkill, ok: false, output: `스킬 이름이 여러 항목과 일치합니다: ${candidates}. elanous_skills_list에서 정확한 이름을 골라 다시 호출하세요.` };
+  }
+  const selected = resolution.entry;
   const allowlist = harnessSkillExec.resolveHarnessExecAllowlist(
     extra,
     (rejected, reason) => observe('allowlist-reject', { skill: rejected, reason }),
@@ -163,13 +177,18 @@ export async function dispatchSkillExec(
   let interruption: 'skill-exec-timeout' | 'skill-exec-cancelled' | undefined;
   try {
     const outcome = await Promise.race([
-      invokeResearch(task, { skill, signal: child.signal, onProgress: (delta) => {
-        progressChunks += 1;
-        progressBytes += delta.length;
-        if (progressChunks === 1 || progressChunks % 32 === 0) {
-          observe('progress', { skill, progressChunks, progressBytes });
-        }
-      } }).then((value) => ({ result: value })),
+      invokeResearch(task, {
+        skill,
+        ...(selected ? { skillRootDir: dirname(selected.skillDir) } : {}),
+        signal: child.signal,
+        onProgress: (delta) => {
+          progressChunks += 1;
+          progressBytes += delta.length;
+          if (progressChunks === 1 || progressChunks % 32 === 0) {
+            observe('progress', { skill, progressChunks, progressBytes });
+          }
+        },
+      }).then((value) => ({ result: value })),
       interrupted.then((reason) => ({ interruption: reason })),
     ]);
     settled = true;
@@ -195,10 +214,11 @@ export async function dispatchSkillExec(
   // A low-quality research result is a capability gap. Keep the original failure,
   // and attach a bounded discovery card rather than silently switching tools.
   let discoveryCard: string | undefined;
-  if (!result.ok && /\b(?:no data|no evidence|missing|unavailable|not found|empty)\b|(?:자료가 없|데이터가 없|자료 부족|미확인|찾지 못)/i
+  const localSkillMissing = /not found under (?:~\/\.claude\/skills|\/)/i.test(result.error ?? '');
+  if (!result.ok && !localSkillMissing && /\b(?:no data|no evidence|missing|unavailable|not found|empty)\b|(?:자료가 없|데이터가 없|자료 부족|미확인|찾지 못)/i
     .test(`${result.output} ${result.error ?? ''}`)) {
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(new Error('plugin discovery time budget exhausted')), 10_000);
+    const timer = setTimeout(() => controller.abort(new Error('plugin discovery time budget exhausted')), deps.discoveryTimeoutMs ?? 10_000);
     try {
       const discovery = deps.discoverPlugin ?? (await import('../research/plugin-discovery.js')).discoverResearchPlugin;
       const found = await discovery(task, { signal: controller.signal });

package/src/tool-runtime/types.ts

@@ -56,6 +56,7 @@ export interface ToolRuntimeContext {
    *  supported (e.g. streaming fetch, long-running agent calls). */
   signal?: AbortSignal;
   /** Parent catalog and dispatcher inherited by an Agent runtime's child. */
+  parentSessionId?: string;
   agentHostTools?: LLMToolSpec[];
   /** Host-selected working directory for an Agent spawned through MCP. */
   agentCwd?: string;
@@ -65,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,13 +360,24 @@ 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;
+        login: 'ready' | 'needed' | 'unknown'; message: string;
+      }>;
+    };
     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; }
       },
       termSize: () => ({ cols: process.stdout.columns || 80, rows: process.stdout.rows || 24 }),
       setStatus: (message) => { status = safeStatusText(message); },
+      ...(installer.detectAgentCli ? { detectAgentCli: installer.detectAgentCli } : {}),
       drawRemoteFrame: (frame) => {
         sidetabRemoteFrame = frame || null;
         if (sidetabRemoteFrame !== null) {
@@ -396,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) {
@@ -410,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);
@@ -575,7 +603,7 @@ export async function showNextTui(options: NextTuiOptions = {}): Promise<void> {
       .then(({ runLocalChatTurn, onLocalChatBackgroundStatus, onLocalChatSelfHealthStatus }) => {
         observeSession(turnSessionId, onLocalChatBackgroundStatus, onLocalChatSelfHealthStatus);
         let firstResponseSeen = false;
-        return runLocalChatTurn(turnSessionId, turnText, abort.signal, undefined, undefined, (delta) => {
+        return runLocalChatTurn(turnSessionId, turnText, abort.signal, undefined, undefined, (delta, replace = false) => {
           // 스트림 텍스트 = 진전 신호 — 마지막 진전 시각을 올린다(녹음기 없으면 아무 일도 안 한다).
           reportTuiProgress();
           // 첫 응답 경계: 첫 스트림 델타에서 턴 시작 트레이스를 닫는다(endedBy=stream-open).
@@ -585,7 +613,7 @@ export async function showNextTui(options: NextTuiOptions = {}): Promise<void> {
           }
           // The first model token is visible before the final JSONL frame. Keep only
           // a bounded tail until session history becomes the canonical display.
-          streamingReply = (streamingReply + delta).slice(-32_768);
+          streamingReply = replace ? delta.slice(-32_768) : (streamingReply + delta).slice(-32_768);
           activity = streamReplyLines(streamingReply, process.stdout.columns || 80);
           const now = performance.now();
           if (streamRenderAt === 0 || now - streamRenderAt >= 33) {
@@ -660,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);
   }
@@ -692,8 +722,9 @@ export async function showNextTui(options: NextTuiOptions = {}): Promise<void> {
   try {
     {
       const { createNextTuiWakeup, setNextTuiWakeupTool } = await import('../tui-client/next-wakeup.js');
-      const { setNextSidetabHandler } = await import('../tui-client/local-chat-turn.js');
+      const { setNextSidetabHandler, setNextSidetabIpcEnabled } = await import('../tui-client/local-chat-turn.js');
       const { createNextSidetabHostHandler } = await import('./sidetab/nl-tool.js');
+      setNextSidetabIpcEnabled(true);
       wakeup = createNextTuiWakeup({
         isTurnRunning: () => busy,
         getBufferText: () => editor.text,
@@ -722,6 +753,7 @@ export async function showNextTui(options: NextTuiOptions = {}): Promise<void> {
         attach: async (row) => { await ensureSidetabAttachments(); const ok = sidetabAttachments!.select(row); render(); return { ok, action: 'attach', target: row.id }; },
         detach: () => { if (sidetabAttachments?.hasRemoteView()) sidetabAttachments.showMain(); else if (sidetabAttachments?.hasModal()) { sidetabAttachments.handleKey({ name: '\\', ctrl: true, shift: false, raw: '' }); sidetabAttachments.handleKey({ name: 'd', ctrl: false, shift: false, raw: 'd' }); } render(); return { ok: true, action: 'detach' }; },
         spawn: async (character) => { await ensureSidetabAttachments(); const ok = sidetabAttachments!.spawn(character); refreshSidetabRows(); render(); return { ok, action: 'new', character }; },
+        runMission: async (agent, mission) => { await ensureSidetabAttachments(); const result = await sidetabAttachments!.runMission(agent, mission); refreshSidetabRows(); render(); return result; },
         kill: async (row) => { await ensureSidetabAttachments(); const ok = sidetabAttachments!.kill(row); refreshSidetabRows(); render(); return { ok, action: 'kill', target: row.id }; },
       }));
       const gate = wakeup.gate;
@@ -1390,8 +1422,9 @@ export async function showNextTui(options: NextTuiOptions = {}): Promise<void> {
       const { setNextTuiWakeupTool } = await import('../tui-client/next-wakeup.js');
       setNextTuiWakeupTool(null);
     }
-    const { setNextSidetabHandler } = await import('../tui-client/local-chat-turn.js');
+    const { setNextSidetabHandler, setNextSidetabIpcEnabled } = await import('../tui-client/local-chat-turn.js');
     setNextSidetabHandler(null);
+    setNextSidetabIpcEnabled(false);
     turnAbort?.abort();
     await turnDone;
     backgroundSubscription.stop?.();