elanous 0.2.42 → 0.2.44

package/src/nexus/api/grokbot-trigger-bot.ts

@@ -0,0 +1,206 @@
+import { spawn } from 'node:child_process';
+import { debug } from '../../debug/log.js';
+import { receiveChannelEvent } from '../outbound/router.js';
+import { registerGrokbotAdapter } from '../outbound/grokbot-adapter.js';
+import { createSession, listSessions } from '../../session/index.js';
+import type { UserConfig } from '../../user-config.js';
+import type { runTurn } from '../../session/chat.js';
+import type { ChannelEnvelope } from '../outbound/router.js';
+
+const DEFAULT_AGENT = 'COO';
+const DEFAULT_POLL_INTERVAL_MS = 15_000;
+const MAX_MESSAGE_BYTES = 64 * 1024;
+
+export interface GrokbotPendingMessage {
+  id: string;
+}
+
+export interface GrokbotMailbox {
+  listPending(): Promise<GrokbotPendingMessage[]>;
+  /** Atomically move a pending request into processing; null means another consumer claimed it. */
+  claim(id: string): Promise<string | null>;
+  acknowledge(id: string, text: string): Promise<void>;
+  complete(id: string, text: string): Promise<void>;
+  sendPrompt(agent: string, prompt: string): Promise<{ preview?: string }>;
+}
+
+export interface NexusGrokbotTriggerBotOptions {
+  mailbox: GrokbotMailbox;
+  dispatch: (event: ChannelEnvelope) => Promise<string>;
+  pollIntervalMs?: number;
+  now?: () => string;
+  log?: (event: string, data: Record<string, unknown>) => void;
+}
+
+const GROKBOT_SESSION_CHAT_ID = -707151151;
+const GROKBOT_SESSION_BOT_ID = 'grokbot-coo';
+
+function grokbotMainSessionId(): string {
+  const existing = listSessions().find((session) => session.origin === 'grokbot' && session.personaId === 'grokbot-coo');
+  if (existing) return existing.id;
+  return createSession({
+    source: 'cli', sourceKind: 'telegram', origin: 'grokbot', personaId: 'grokbot-coo',
+    title: 'Grok Bot COO · 주 세션',
+  }).id;
+}
+
+/** Reuse one durable main-agent session for the bot's conversation across requests and restarts. */
+export function createGrokbotMainSessionDispatcher(
+  userConfig: UserConfig,
+  runTurnImpl: typeof runTurn,
+  getSessionId: () => string = grokbotMainSessionId,
+): (event: ChannelEnvelope) => Promise<string> {
+  const sessionId = getSessionId();
+  return async (event) => {
+    const result = await runTurnImpl({
+      userConfig,
+      sessionId,
+      userText: event.text,
+      utteranceSurface: 'telegram',
+      tgChat: { botId: GROKBOT_SESSION_BOT_ID, chatId: GROKBOT_SESSION_CHAT_ID },
+    });
+    return result.text;
+  };
+}
+
+export interface NexusGrokbotTriggerBotHandle {
+  pollOnce(): Promise<void>;
+  start(): void;
+  stop(): Promise<void>;
+}
+
+function safeReason(error: unknown): string {
+  const text = error instanceof Error ? error.message : String(error);
+  return text.replace(/Bearer\s+\S+/gi, 'Bearer [redacted]').slice(0, 240);
+}
+
+function validId(id: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/.test(id);
+}
+
+function runRemote(script: string, timeoutMs = 20_000): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = spawn('ssh', ['-o', 'BatchMode=yes', 'box@grbot-coo', 'bash -s'], { stdio: ['pipe', 'pipe', 'ignore'] });
+    let stdout = '';
+    const timeout = setTimeout(() => child.kill('SIGTERM'), timeoutMs);
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk: string) => { stdout += chunk; });
+    child.on('error', () => { clearTimeout(timeout); reject(new Error('grokbot transport unavailable')); });
+    child.on('close', (code) => {
+      clearTimeout(timeout);
+      if (code === 0) resolve(stdout.trimEnd());
+      else reject(new Error('grokbot transport failed'));
+    });
+    child.stdin.end(script);
+  });
+}
+
+function encoded(value: string): string {
+  const bytes = Buffer.from(value, 'utf8');
+  if (bytes.byteLength > MAX_MESSAGE_BYTES) throw new Error('grokbot message exceeds 64 KiB');
+  return bytes.toString('base64');
+}
+
+function remoteWrite(relativePath: string, value: string): string {
+  if (!/^[A-Za-z0-9_./-]+$/.test(relativePath)) throw new Error('invalid grokbot output path');
+  const body = encoded(value);
+  const target = `"$HOME/${relativePath}"`;
+  return `set -eu\nmkdir -p "$(dirname ${target})"\nprintf '%s' '${body}' | base64 -d > ${target}\n`;
+}
+
+/** SSH-only transport to the COO bot host. The gateway credential remains on that host. */
+export function createSshGrokbotMailbox(): GrokbotMailbox {
+  return {
+    async listPending() {
+      const output = await runRemote(`set -eu\nfor f in "$HOME"/elanous-inbox/*.txt; do\n  [ -f "$f" ] || continue\n  b=\${f##*/}; printf '%s\\n' "\${b%.txt}"\ndone\n`);
+      return output.split('\n').filter(validId).map((id) => ({ id }));
+    },
+    async claim(id) {
+      if (!validId(id)) throw new Error('invalid grokbot request id');
+      const output = await runRemote(`set -eu\nroot="$HOME/elanous-inbox"\nmkdir -p "$root/processing"\nsrc="$root/${id}.txt"\ndst="$root/processing/${id}.txt"\n[ -f "$src" ] || exit 3\n[ ! -e "$dst" ] || exit 4\nmv "$src" "$dst"\nbase64 "$dst" | tr -d '\\n'\n`);
+      return Buffer.from(output, 'base64').toString('utf8');
+    },
+    async acknowledge(id, text) {
+      if (!validId(id)) throw new Error('invalid grokbot request id');
+      await runRemote(`${remoteWrite(`elanous-outbox/${id}.ack`, text)}printf '%s\\n' "$(date -Is)" >> "$HOME/elanous-inbox/processing/${id}.accepted"\n`);
+    },
+    async complete(id, text) {
+      if (!validId(id)) throw new Error('invalid grokbot request id');
+      await runRemote(`${remoteWrite(`elanous-outbox/${id}.md`, text)}mkdir -p "$HOME/elanous-inbox/done"\nif [ -f "$HOME/elanous-inbox/processing/${id}.txt" ]; then mv "$HOME/elanous-inbox/processing/${id}.txt" "$HOME/elanous-inbox/done/${id}.txt"; fi\n`);
+    },
+    async sendPrompt(agent, prompt) {
+      if (agent !== DEFAULT_AGENT) throw new Error('grokbot agent is not allowlisted');
+      const body = encoded(prompt);
+      const script = `set -eu\ntoken=$(jq -er '.token | strings | select(length > 0)' "$HOME/sand-data/gateway.json")\nagent=$(curl -fsS -m 15 -X POST http://127.0.0.1:1340/api/listAgents -H 'Content-Type: application/json' -H "Authorization: Bearer $token" -d '{}' | jq -er '.[] | select(.name == "COO") | .id' | head -n 1)\n[ -n "$agent" ]\nprintf '%s' '${body}' | base64 -d | jq -Rs --arg agentId "$agent" '{agentId:$agentId,prompt:.}' | curl -fsS -m 30 -X POST http://127.0.0.1:1340/api/sendPrompt -H 'Content-Type: application/json' -H "Authorization: Bearer $token" --data-binary @- | jq -c '{preview:(.lastMessagePreview // .preview // "")}'\n`;
+      const response = await runRemote(script, 45_000);
+      const parsed = JSON.parse(response) as { preview?: unknown };
+      return { ...(typeof parsed.preview === 'string' && parsed.preview ? { preview: parsed.preview } : {}) };
+    },
+  };
+}
+
+export function createNexusGrokbotTriggerBot(options: NexusGrokbotTriggerBotOptions): NexusGrokbotTriggerBotHandle {
+  const now = options.now ?? (() => new Date().toISOString());
+  const log = options.log ?? ((event, data) => debug.log('channel.grokbot', event, data));
+  const unregister = registerGrokbotAdapter({
+    sendPrompt: (agent, prompt) => options.mailbox.sendPrompt(agent, prompt),
+    now,
+    log,
+  });
+  let stopped = false;
+  let polling = false;
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let currentPoll: Promise<void> | undefined;
+
+  const pollOnce = async (): Promise<void> => {
+    if (stopped || polling) return currentPoll;
+    polling = true;
+    currentPoll = (async () => {
+      try {
+        const messages = await options.mailbox.listPending();
+        for (const { id } of messages) {
+          if (stopped) break;
+          let text: string | null;
+          try { text = await options.mailbox.claim(id); }
+          catch (error) { log('failure', { id, failedAt: now(), reason: safeReason(error), stage: 'claim' }); continue; }
+          if (text === null) continue;
+          try {
+            const kind = /^(승인|보류|수정)(?:\s|[:：]|$)/.test(text.trim()) ? 'decision' : 'request';
+            const envelope = await receiveChannelEvent('grokbot', { id, text, kind });
+            if (!envelope || envelope instanceof Promise) throw new Error('grokbot request normalization failed');
+            await options.mailbox.acknowledge(id, 'OP 접수 — 답을 준비 중입니다.');
+            const reply = await options.dispatch(envelope);
+            if (!reply.trim()) throw new Error('main session returned an empty reply');
+            await options.mailbox.complete(id, reply);
+            log('reply', { id, repliedAt: now(), replyChars: reply.length });
+          } catch (error) {
+            const reason = safeReason(error);
+            log('failure', { id, failedAt: now(), reason, stage: 'dispatch-or-reply' });
+            try { await options.mailbox.complete(id, '요청을 처리하지 못했습니다. 주 세션 연결과 eln logs의 channel.grokbot 기록을 확인해 주세요.'); }
+            catch (replyError) { log('failure', { id, failedAt: now(), reason: safeReason(replyError), stage: 'failure-reply' }); }
+          }
+        }
+      } catch (error) {
+        log('failure', { failedAt: now(), reason: safeReason(error), stage: 'poll' });
+      }
+    })().finally(() => { polling = false; });
+    return currentPoll;
+  };
+
+  return {
+    pollOnce,
+    start() {
+      if (stopped || timer) return;
+      void pollOnce();
+      timer = setInterval(() => { void pollOnce(); }, options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS);
+      timer.unref?.();
+    },
+    async stop() {
+      stopped = true;
+      if (timer) clearInterval(timer);
+      timer = undefined;
+      await currentPoll;
+      unregister();
+    },
+  };
+}

package/src/nexus/api/http-server.ts

@@ -32,8 +32,10 @@ import { CARD_FOLLOWUP_PATH, createCardFollowupJobs, type CardFollowupJobs } fro
 import { SKILL_EXEC_PATH, createSkillExecJobs, type SkillExecJobs } from './skill-exec-route.js';
 import { compareTokenConstTime } from '../../acp/transport/auth.js';
 import { ensureAuthToken } from '../../auth/acp-token.js';
-import type { NexusState } from '../state/state.js';
+import { pushEvent, type NexusState } from '../state/state.js';
 import { DEFAULT_NEXUS_HTTP_PORT } from '../default-port.js';
+import { effectiveInstanceRoot } from '../../instance/resolve.js';
+import { handleMissionLineRequest, MissionLineHttpError } from '../../agent-mission/mission-line.js';
 
 export { DEFAULT_NEXUS_HTTP_PORT } from '../default-port.js';
 import type { TabRegistry } from '../state/tab-registry.js';
@@ -497,6 +499,8 @@ export interface NexusHttpServerOpts {
   projectFolderRoots?: string[];
   /** Optional installer state root for isolated API consumers and tests. */
   pluginStateRoot?: string;
+  /** Mission-addressed hand line storage; production uses the current instance state root. */
+  missionLineRoot?: string;
   outputs?: OutputsDeps;
   /** Read-only grid measurement seam; omitted in production for live HQ and Pod pool reads. */
   grid?: GridDeps;
@@ -1008,6 +1012,38 @@ export async function routeRequest(
   registerAuthPeerAddress(req, (server as BunServerLike & {
     requestIP?: (request: Request) => { address: string } | null;
   }).requestIP?.(req)?.address);
+  // Mission lines use a scoped per-mission bearer issued by the mission
+  // parent, not the owner/API bearer checked by the general scope guard.
+  if (new URL(req.url).pathname.startsWith('/v1/missions/')) {
+    // MissionOutStore uses effectiveInstanceRoot too; share the resolver
+    // directly so custom ELANOUS_STATE_DIR/config-dir cannot split the token
+    // authority from the reply ledger.
+    const root = opts.missionLineRoot ?? effectiveInstanceRoot();
+    const response = await handleMissionLineRequest(req, root, async (input, authority) => {
+      const { createMissionOutStore, MissionReplyStateError } = await import('../../agent-mission/mission-out.js');
+      const reply = await createMissionOutStore(root).reply(input.missionId, input.text, input.type === 'final', {
+          lineId: input.lineId,
+          ...(input.runId ? { runId: input.runId } : {}), ...(input.ptyId ? { ptyId: input.ptyId } : {}),
+          ...(input.replyTo ? { replyTo: input.replyTo } : {}),
+          attemptId: input.attemptId, agent: input.agent, lineType: input.type, source: input.source,
+          ...(input.kind ? { kind: input.kind } : {}),
+          ...(input.defaults ? { defaults: input.defaults } : {}),
+          ...(input.deadline ? { deadline: input.deadline } : {}),
+          ...(input.scope ? { scope: input.scope } : {}),
+          ...(input.stop !== undefined ? { stop: input.stop } : {}),
+          ...(input.priority ? { priority: input.priority } : {}),
+          ...(input.state ? { state: input.state } : {}), who: authority.who, what: authority.what,
+          ...(input.type === 'ask' || input.type === 'answer' || input.type === 'correct' ? { kind: input.type } : {}),
+        }).catch((error: unknown) => {
+        if (error instanceof MissionReplyStateError) throw new MissionLineHttpError(error.status);
+        throw error;
+      });
+      return { ...input, sequence: reply.sequence, createdAt: reply.createdAt, done: reply.done, ...(reply.deadline ? { deadline: reply.deadline } : {}), ...(reply.replyTo ? { replyTo: reply.replyTo } : {}), ...(reply.graphEvents ? { graphEvents: reply.graphEvents } : {}) };
+    }, (event) => {
+      pushEvent(opts.state, { kind: 'mission.line', detail: event as unknown as Record<string, unknown> });
+    });
+    if (response) return response;
+  }
   if (opts.metaApi && setupBearerScopeDenied(req, opts.metaApi)) {
     return jsonResponse({ error: 'forbidden' }, 403);
   }

package/src/nexus/api/mcp-public-allowlist.ts

@@ -14,6 +14,8 @@ export const MCP_PUBLIC_TOOLS = new Set([
   'elanous_obsidian_search',
   'agent_list',
   'agent_output',
+  'graph_compose',
+  'graph_run_status',
 ]);
 
 function catalogId(name: string): string | undefined {

package/src/nexus/api/telegram-trigger-bot.ts

@@ -123,9 +123,9 @@ export function createTelegramTriggerLogger(
  *  TelegramEvent shape. Congruent fields (`src/telegram.ts:166-180`
  *  comment) so the wire is a near-identity with `raw` carrying the
  *  full payload (messageId · isDm) for debugging. */
-export function toTelegramEvent(tap: TgTriggerEvent): TelegramEvent {
-  const envelope = receiveChannelEvent('telegram', tap);
-  if (!envelope || envelope instanceof Promise) throw new Error('telegram connector cannot normalize accepted tap');
+export async function toTelegramEvent(tap: TgTriggerEvent): Promise<TelegramEvent> {
+  const envelope = await receiveChannelEvent('telegram', tap);
+  if (!envelope) throw new Error('telegram connector cannot normalize accepted tap');
   return {
     kind: tap.kind,
     chat: envelope.channel ?? tap.chat,
@@ -149,10 +149,10 @@ export function buildTelegramTriggerTap(
   return (tap: TgTriggerEvent): void => {
     // Fire-and-forget — workflow dispatch errors surface via the
     // workflow daemon's lifecycle bus, not the polling loop. Any
-    // synchronous throw lands here so the chat reply (no-op in this
-    // bot) keeps flowing.
+    // normalization and dispatch rejections land here so the polling
+    // loop and other accepted taps keep flowing.
     void Promise.resolve()
-      .then(() => dispatch(toTelegramEvent(tap)))
+      .then(async () => dispatch(await toTelegramEvent(tap)))
       .catch((err: unknown) => {
         const reason = err instanceof Error ? err.message : String(err);
         log(`workflow dispatch failed: ${reason}`);

package/src/nexus/boot/register-mcp-clients.ts

@@ -28,7 +28,7 @@
 //     daemon exit.
 
 import type { McpServerSpec } from '../../user-config.js';
-import { McpClient, McpConnectionError, type McpTool, type McpToolCallResult } from '../../mcp/client.js';
+import { McpClient, McpConnectionError, type McpCallMeta, type McpTool, type McpToolCallResult } from '../../mcp/client.js';
 import {
   createMcpProxyRuntime,
   createMcpToolAuthorizer,
@@ -41,7 +41,8 @@ import { listNodeKinds } from '../../graph-kinds/registry.js';
 import { syncInstalledPluginNodes } from '../../graph-kinds/installed-plugin-nodes.js';
 import { listInstalledPlugins } from '../../plugins/install/plugin-install.js';
 import { pluginEnv, credentialStatus } from '../../plugins/install/plugin-credentials.js';
-import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { getHarnessRunId } from '../../harness/harness-space.js';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
 import { join, resolve, sep } from 'node:path';
 
 export interface McpClientsHandle {
@@ -143,6 +144,8 @@ export interface RegisterMcpClientsOpts {
   toolIndexStore?: McpToolIndexStore;
   /** `lazy` 자식의 SIGTERM→SIGKILL 유예(ms). 기본 2500 — 종료 3초 계약 안쪽. */
   lazyShutdownGraceMs?: number;
+  /** BROWSER-ROUNDTRIP-ASIDE test seam; production defaults to the state-root JSONL ledger. */
+  asideLedger?: AsideRoundtripLedger;
 }
 
 /** 한 서버가 지난 부팅에서 알린 툴 목록. `mcp-tool-index.json` 의 값. */
@@ -156,6 +159,77 @@ export interface McpToolIndexStore {
 
 export const MCP_TOOL_INDEX_FILENAME = 'mcp-tool-index.json';
 
+export interface AsideRoundtripEntry {
+  runId: string;
+  phase: 'call' | 'result';
+  toolName: string;
+  /** null means the caller did not provide a reason; do not invent one. */
+  reason: string | null;
+  at: string;
+  ok?: boolean;
+  classification?: string;
+  outputLength?: number;
+  errorClass?: string;
+}
+
+export interface AsideRoundtripLedger {
+  append(entry: AsideRoundtripEntry): void;
+  list(runId: string): AsideRoundtripEntry[];
+}
+
+const ASIDE_RUN_LEDGER_FILENAME = 'aside-run-roundtrip.jsonl';
+
+/** Persist only the run join and result receipt metadata, never prompt/result contents. */
+export function defaultAsideRoundtripLedger(root: string = elanousStateRoot()): AsideRoundtripLedger {
+  const file = join(root, ASIDE_RUN_LEDGER_FILENAME);
+  return {
+    append(entry) {
+      try {
+        mkdirSync(root, { recursive: true });
+        appendFileSync(file, `${JSON.stringify(entry)}\n`, 'utf8');
+      } catch (error) {
+        try { debug.log('mcp-client.aside', 'ledger-append-failed', { errorClass: error instanceof Error ? error.name : 'unknown' }); }
+        catch { /* a ledger failure must not block the MCP call */ }
+      }
+    },
+    list(runId) {
+      try {
+        return readFileSync(file, 'utf8').split('\n').flatMap((line) => {
+          if (!line.trim()) return [];
+          try {
+            const row = JSON.parse(line) as AsideRoundtripEntry;
+            return row && row.runId === runId && (row.phase === 'call' || row.phase === 'result') ? [row] : [];
+          } catch { return []; }
+        });
+      } catch { return []; }
+    },
+  };
+}
+
+function asideReason(args: Record<string, unknown>): string | null {
+  const raw = args.reason;
+  return typeof raw === 'string' && raw.trim().length > 0
+    ? redactSecretText(raw.trim()).slice(0, 240)
+    : null;
+}
+
+function asidePrompt(args: Record<string, unknown>, runId: string, reason: string | null): Record<string, unknown> {
+  if (typeof args.prompt !== 'string') return args;
+  const joinLine = `elanous 런 ${runId} · 결과는 elanous 도구로 돌려라.`;
+  if (args.prompt.includes(joinLine)) return args;
+  const instructions = [
+    joinLine,
+    ...(reason ? [`Delegation reason: ${reason}.`] : []),
+    'Use TaskGet to load this run’s task context, then return findings through Elanous MCP tools to the same runId. Keep browser credentials in the browser.',
+  ].join(' ');
+  return { ...args, prompt: `${instructions}\n\n${args.prompt}` };
+}
+
+function asideTextLength(result: McpToolCallResult): number {
+  return (result.content ?? []).reduce((length, block) =>
+    block.type === 'text' && typeof block.text === 'string' ? length + block.text.length : length, 0);
+}
+
 /** 지연 기동 자식의 정리 유예. `McpClient` 기본 5000ms 는 「SIGTERM 3초 안에
  *  안 끝남」이던 classic 종료 계약을 넘긴다 — 2500ms 면 SIGKILL 까지 3초 안쪽. */
 const DEFAULT_LAZY_SHUTDOWN_GRACE_MS = 2500;
@@ -209,11 +283,11 @@ class DeferredMcpClient implements DeferredInner {
     return this.inner.listTools();
   }
 
-  async callTool(name: string, args: Record<string, unknown>): Promise<McpToolCallResult> {
+  async callTool(name: string, args: Record<string, unknown>, meta?: McpCallMeta): Promise<McpToolCallResult> {
     await this.ensureStarted();
     // ⚠️ 기동 «뒤»의 inner.callTool 을 부른다 — 자격증명 마스킹 래퍼가
     //    createClient 직후 client.callTool 에 씌워지므로 그 래퍼를 탄다.
-    return this.inner.callTool(name, args);
+    return this.inner.callTool(name, args, meta);
   }
 
   async dispose(): Promise<void> {
@@ -259,6 +333,8 @@ export async function registerMcpClients(
   // A boot owns its ledger: same configured ids in concurrent/restarted boots
   // cannot inherit grants or revoke one another's authorization lifetime.
   const authorizer = createMcpToolAuthorizer();
+  let asideLedger = opts.asideLedger;
+  const asideLedgerFor = (): AsideRoundtripLedger => (asideLedger ??= defaultAsideRoundtripLedger());
   // FU3 (2026-05-13) — pipe McpClient lifecycle events into elanous's
   // keytrace logger so `mcp.client.spawn / .ready / .exit / .parse-error
   // / .stderr` all land in the daemon's debug log. Without this hook
@@ -420,14 +496,44 @@ export async function registerMcpClients(
     let client: McpClient | undefined;
     try {
       client = createClient(spec) as McpClient;
-      if (!opts.createClient && spec.transport === 'stdio') {
+      if (spec.transport === 'stdio' && (!opts.createClient || spec.id === 'aside')) {
         const originalCallTool = client.callTool.bind(client);
-        client.callTool = async (name: string, args: Record<string, unknown>): Promise<McpToolCallResult> => {
-          const values = injectedValuesByServer.get(spec.id) ?? [];
+        client.callTool = async (name: string, args: Record<string, unknown>, meta?: McpCallMeta): Promise<McpToolCallResult> => {
+          // Aside test clients use this same invocation boundary but bypass production credential injection.
+          const values = opts.createClient ? [] : injectedValuesByServer.get(spec.id) ?? [];
+          const isAsideExec = spec.id === 'aside' && name === 'exec';
+          const runId = isAsideExec ? (meta?.elanousRunId ?? getHarnessRunId()).trim() : '';
+          const reason = isAsideExec ? asideReason(args) : null;
+          const ledger = isAsideExec && runId ? asideLedgerFor() : undefined;
+          const now = () => new Date().toISOString();
+          const appendReceipt = (entry: AsideRoundtripEntry) => {
+            if (!ledger || !runId) return;
+            try { ledger.append(entry); } catch { /* bookkeeping must not block an MCP call */ }
+          };
+          const callArgs = isAsideExec && runId ? asidePrompt(args, runId, reason) : args;
+          if (isAsideExec && runId) {
+            try { debug.log('mcp-client.aside', 'exec-request', { runId, reason, toolName: name }); }
+            catch { /* observability is best-effort */ }
+            appendReceipt({ runId, phase: 'call', toolName: name, reason, at: now() });
+          }
           try {
-            const result = await originalCallTool(name, args);
+            const result = await originalCallTool(name, callArgs, meta);
+            if (isAsideExec && runId) {
+              const isError = result.isError === true;
+              const classification = isError ? 'mcp-server-error' : undefined;
+              const outputLength = asideTextLength(result);
+              appendReceipt({ runId, phase: 'result', toolName: name, reason, at: now(), ok: !isError, ...(classification ? { classification } : {}), outputLength });
+              try { debug.log('mcp-client.aside', 'exec-result', { runId, reason, toolName: name, ok: !isError, ...(classification ? { classification } : {}), isError, outputLength }); }
+              catch { /* observability is best-effort */ }
+            }
             return maskInjectedValues(result, values) as McpToolCallResult;
           } catch (err) {
+            if (isAsideExec && runId) {
+              const errorClass = err instanceof Error ? err.name : 'unknown';
+              appendReceipt({ runId, phase: 'result', toolName: name, reason, at: now(), ok: false, classification: 'mcp-transport-error', errorClass });
+              try { debug.log('mcp-client.aside', 'exec-error', { runId, reason, toolName: name, callToolRejected: true, errorClass }); }
+              catch { /* observability is best-effort */ }
+            }
             if (err instanceof Error) err.message = redactValues(err.message, values);
             else throw new Error(redactValues(String(err), values));
             throw err;

package/src/nexus/index.ts

@@ -252,7 +252,7 @@ import type { HealthProbeBackend } from './supervisor/health.js';
 import { gracefulExit, cleanExit } from './supervisor/graceful-exit.js';
 import { restoreFromPending } from './supervisor/restore-state.js';
 import { resolveHeadlessMode } from './headless-mode.js';
-import { checkSetupStatus, readNexusSetupMode, renderSetupStatus, setupBootMode, setupModeBootPlan } from './setup-status.js';
+import { checkSetupStatus, readNexusSetupMode, renderSetupStatus, setupBootMode, setupModeBootPlan, shouldCheckHeadlessSetup } from './setup-status.js';
 import { probeTailscale } from './onboarding/tailscale-probe.js';
 import {
   runPwaSharePrompt,
@@ -859,7 +859,12 @@ export async function runNexus(opts: RunNexusOptions = {}): Promise<RunNexusHand
   }
 
   const headless = resolveHeadlessMode({ ...(opts.headless !== undefined ? { headless: opts.headless } : {}) });
-  if (headless && !opts.detachForTesting && !opts.skipHeadlessSetupCheckForTesting) {
+  if (shouldCheckHeadlessSetup({
+    headless,
+    detachedForTesting: opts.detachForTesting === true,
+    skipForTesting: opts.skipHeadlessSetupCheckForTesting === true,
+    testInstance: resolveCurrentInstance().kind === 'test',
+  })) {
     const setup = checkSetupStatus({ argvBin: process.argv[1] ?? '' });
     const boot = setupBootMode(setup);
     if (boot.mode === 'refuse') {
@@ -1351,6 +1356,7 @@ export async function runNexus(opts: RunNexusOptions = {}): Promise<RunNexusHand
   // Wired below once the workflow daemon is constructed.
   let webPushDecisionTimer: ReturnType<typeof setInterval> | undefined;
   let workflowDiscordBot: NexusDiscordTriggerBotHandle | undefined;
+  let workflowGrokbotBot: { start(): void; stop(): Promise<void> } | undefined;
   // V2.2-4 (2026-05-12) — NEXUS-hosted Telegram workflow trigger bot.
   let workflowTelegramBot: NexusTelegramTriggerBotHandle | undefined;
   /** R1 — 토큰마다 뜬 Q&A 폴러 «전부»(재시작 때 함께 비운다 · `workflowTelegramBot` 은 주 토큰 하나뿐). */
@@ -2807,6 +2813,16 @@ export async function runNexus(opts: RunNexusOptions = {}): Promise<RunNexusHand
               for (const wired of handles) adopt(wired);
             }
           }
+          if (process.env.ELANOUS_GROKBOT_ENABLED === '1' && !isAutonomousRunContext()) {
+            const { createGrokbotMainSessionDispatcher, createNexusGrokbotTriggerBot, createSshGrokbotMailbox } = await import('./api/grokbot-trigger-bot.js');
+            const { makeElanousAgentRunTurn } = await import('../agent/monad-agent-turn.js');
+            workflowGrokbotBot = createNexusGrokbotTriggerBot({
+              mailbox: createSshGrokbotMailbox(),
+              dispatch: createGrokbotMainSessionDispatcher(cfg, makeElanousAgentRunTurn(cfg, 'telegram')),
+            });
+            workflowGrokbotBot.start();
+            debug.log('channel.grokbot', 'attached', { agent: 'COO', pollIntervalMs: 15_000 });
+          }
         } catch (err: unknown) {
           const msg = err instanceof Error ? err.message : String(err);
           console.warn(`[nexus] trigger bot boot skipped: ${msg}`);
@@ -3587,6 +3603,10 @@ export async function runNexus(opts: RunNexusOptions = {}): Promise<RunNexusHand
     await Promise.all([...handles].map(async (handle) => {
       try { await handle.stop(); } catch { /* 종료는 계속 */ }
     }));
+    if (workflowGrokbotBot) {
+      try { await workflowGrokbotBot.stop(); } catch { /* 종료는 계속 */ }
+      workflowGrokbotBot = undefined;
+    }
     await next();
   };
 

package/src/nexus/outbound/format.ts

@@ -14,6 +14,15 @@ export interface OutboundMsg {
   kind: string;
   /** Optional routing role; absent preserves per-kind fan-out. */
   role?: string;
+  /** Optional transport metadata. A router must not send these fields to a connector that does not declare support. */
+  threadId?: string;
+  topicId?: string;
+  persona?: { name: string; avatarUrl?: string };
+  attachments?: readonly { url: string; name?: string }[];
+  buttons?: readonly { label: string; value: string }[];
+  choices?: readonly { label: string; value: string }[];
+  /** Requested channel-side authorization; delivery fails closed when unsupported or denied. */
+  permissionAction?: string;
 }
 
 export interface FormattedMessage {

package/src/nexus/outbound/grokbot-adapter.ts

@@ -0,0 +1,71 @@
+import { debug } from '../../debug/log.js';
+import { registerOutboundAdapter } from './router.js';
+import type {
+  ChannelAdapter,
+  ChannelEnvelope,
+  ChannelResult,
+  OutboundChannelConfig,
+  RouterDeps,
+} from './router.js';
+import type { OutboundMsg } from './format.js';
+import type { UserConfig } from '../../user-config.js';
+
+export interface GrokbotAdapterOptions {
+  sendPrompt: (agent: string, prompt: string) => Promise<{ preview?: string }>;
+  now?: () => string;
+  log?: (event: string, data: Record<string, unknown>) => void;
+  agent?: string;
+}
+
+function safeError(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.replace(/Bearer\s+\S+/gi, 'Bearer [redacted]').slice(0, 240);
+}
+
+function inboundEnvelope(payload: unknown): Omit<ChannelEnvelope, 'text'> & { text: string } | null {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) return null;
+  const event = payload as Record<string, unknown>;
+  if (typeof event.text !== 'string' || event.text.length === 0) return null;
+  if (typeof event.id !== 'string' && typeof event.id !== 'number') return null;
+  const kind = typeof event.kind === 'string' && event.kind.trim() ? event.kind : 'request';
+  return { text: event.text, kind, channel: 'COO', senderId: 'COO', messageId: event.id };
+}
+
+export function createGrokbotAdapter(options: GrokbotAdapterOptions): ChannelAdapter {
+  const agent = options.agent ?? 'COO';
+  const now = options.now ?? (() => new Date().toISOString());
+  const log = options.log ?? ((event, data) => debug.log('channel.grokbot', event, data));
+  return {
+    type: 'grokbot',
+    capabilities: {
+      send: true, receive: true, thread: false, topic: false, persona: false,
+      channelLifecycle: false, permissions: false, commands: false, attachments: false,
+      buttons: false, choices: true, deliveryConfirmation: false, rateLimit: false,
+    },
+    parseConfig: (raw): OutboundChannelConfig | undefined => raw.type === 'grokbot' ? { type: 'grokbot' } : undefined,
+    receive: (payload): ChannelEnvelope | null => {
+      const envelope = inboundEnvelope(payload);
+      if (!envelope) return null;
+      log('received', { id: envelope.messageId, text: envelope.text, receivedAt: now() });
+      return envelope;
+    },
+    send: async (_config: OutboundChannelConfig, message: OutboundMsg, _cfg: UserConfig, _deps: RouterDeps): Promise<ChannelResult> => {
+      const requestedAt = now();
+      log('request', { agent, text: message.text, requestedAt, kind: message.kind });
+      try {
+        const prompt = `[엘라누스 알림 — 아래를 대표님께 그대로 전해 주세요. 덧붙이지 마세요]\n\n${message.text}`;
+        const result = await options.sendPrompt(agent, prompt);
+        log('reply', { agent, repliedAt: now(), ...(result.preview ? { preview: result.preview } : {}) });
+        return { type: 'grokbot', ok: true };
+      } catch (error) {
+        const reason = safeError(error);
+        log('failure', { agent, failedAt: now(), reason });
+        return { type: 'grokbot', ok: false, error: reason };
+      }
+    },
+  };
+}
+
+export function registerGrokbotAdapter(options: GrokbotAdapterOptions): () => void {
+  return registerOutboundAdapter(createGrokbotAdapter(options));
+}