elanous 0.2.41 → 0.2.43

package/src/agent-mission/codex-exec.ts

@@ -0,0 +1,105 @@
+import { spawn as nodeSpawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
+
+export type CodexExecResult = {
+  ok: boolean;
+  reason: 'success' | 'no-session' | 'no-result' | 'cli-error' | 'timeout' | 'spawn-error';
+  exitCode: number | null;
+  sessionId: string | null;
+  result: string | null;
+  numTurns: number;
+  malformedLines: number;
+};
+
+type Spawn = (command: string, args: string[], options: {
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  stdio: ['pipe', 'pipe', 'pipe'];
+}) => ChildProcessWithoutNullStreams;
+
+type JsonObject = Record<string, unknown>;
+const object = (value: unknown): value is JsonObject => typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/** Run one non-interactive Codex exec turn, optionally resuming the exact thread from a prior turn. */
+export async function runCodexExec({ cwd, prompt, env, resumeSessionId, spawn = nodeSpawn, timeoutMs = 1_800_000, onSpawn }: {
+  cwd: string;
+  prompt: string;
+  env: NodeJS.ProcessEnv;
+  resumeSessionId?: string;
+  spawn?: Spawn;
+  timeoutMs?: number;
+  onSpawn?: (pid: number, kill: () => void) => void;
+}): Promise<CodexExecResult> {
+  if (resumeSessionId !== undefined && !resumeSessionId.trim()) throw new Error('Codex resume session id must not be empty');
+  const args = resumeSessionId === undefined
+    ? ['exec', '--json', '--approve-for-me', '-']
+    : ['exec', 'resume', '--json', '-c', 'sandbox_mode="workspace-write"', '-c', 'approval_policy="never"', resumeSessionId, '-'];
+  const base: CodexExecResult = {
+    ok: false, reason: 'no-result', exitCode: null, sessionId: null, result: null, numTurns: 0, malformedLines: 0,
+  };
+  let child: ChildProcessWithoutNullStreams;
+  try { child = spawn('codex', args, { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] }); }
+  catch { return { ...base, reason: 'spawn-error' }; }
+  if (typeof child.pid === 'number' && child.pid > 0) onSpawn?.(child.pid, () => { try { child.kill(); } catch { /* Already exited. */ } });
+
+  return new Promise((resolve) => {
+    const state = { ...base };
+    let pending = '';
+    let sawCompletedTurn = false;
+    let failedTurn = false;
+    let timedOut = false;
+    let spawnError = false;
+    let settled = false;
+    const parseLine = (line: string): void => {
+      if (!line.trim()) return;
+      let event: unknown;
+      try { event = JSON.parse(line); }
+      catch { state.malformedLines++; return; }
+      if (!object(event) || typeof event.type !== 'string') { state.malformedLines++; return; }
+      if (event.type === 'thread.started' && typeof event.thread_id === 'string') state.sessionId = event.thread_id;
+      else if (event.type === 'item.completed' && object(event.item) && event.item.type === 'agent_message' && typeof event.item.text === 'string') {
+        state.result = event.item.text;
+      } else if (event.type === 'turn.completed') {
+        sawCompletedTurn = true;
+        state.numTurns++;
+      } else if (event.type === 'turn.failed') failedTurn = true;
+    };
+    const finish = (exitCode: number | null): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.stdout.off('data', onData);
+      const finalLine = pending;
+      pending = '';
+      parseLine(finalLine);
+      state.exitCode = exitCode;
+      state.reason = timedOut ? 'timeout' : spawnError ? 'spawn-error'
+        : exitCode !== 0 || failedTurn ? 'cli-error'
+          : !sawCompletedTurn || !state.result ? 'no-result'
+            : !state.sessionId ? 'no-session' : 'success';
+      state.ok = state.reason === 'success';
+      resolve(state);
+    };
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try { child.kill('SIGKILL'); } catch { /* Report timeout even when the process cannot be killed. */ }
+      finish(null);
+    }, timeoutMs);
+    child.stdout.setEncoding('utf8');
+    const onData = (chunk: string): void => {
+      if (settled) return;
+      pending += chunk;
+      let end: number;
+      while ((end = pending.indexOf('\n')) !== -1) {
+        parseLine(pending.slice(0, end));
+        pending = pending.slice(end + 1);
+      }
+    };
+    child.stdout.on('data', onData);
+    child.stderr.resume();
+    child.on('error', () => { spawnError = true; finish(null); });
+    child.on('close', (code) => finish(code));
+    child.stdin.on('error', () => { /* A child that exits before reading stdin is classified on close. */ });
+    try { child.stdin.end(prompt); }
+    catch { spawnError = true; try { child.kill('SIGKILL'); } catch { /* Already exited. */ } finish(null); }
+  });
+}

package/src/agent-mission/driver.ts

@@ -21,7 +21,7 @@ import { createWorktree, resolveMainRepoRoot, type CreateWorktreeOpts } from '..
 import { configuredWorktreeRoot, getUserConfig } from '../user-config.js';
 import { worktreeHasChanges, commitWorktree, changedFiles } from '../self-implement/seams.js';
 import { streamLLM, type LLMMessage } from '../llm.js';
-import { debug } from '../debug/log.js';
+import { debug, redactSecretText } from '../debug/log.js';
 import { emitPtyDecision, type DecisionInput } from './pty-decision.js';
 import { observeExternalEvent } from '../context-bus/external-events.js';
 import { emitSessionEvent, type SessionEventInput } from '../context-bus/session-events.js';
@@ -42,8 +42,10 @@ import { checkClaudeSubscription } from './claude-subscription.js';
 import { handoffMission, waitForHumanLogin, type HandoffOperations } from './handoff.js';
 import { dispatchOpenPullRequest } from '../tool-runtime/git-pr-runtime.js';
 import { runClaudeHeadless } from './claude-headless.js';
+import { runCodexExec } from './codex-exec.js';
 import { installPluginInsideAgent, type PluginRequest, type PluginDeps } from './in-agent-plugin.js';
 import { planMissionResources, type ResourceLadderDeps, type ResourcePlan } from './resource-ladder.js';
+import type { InProcessHandler, InProcessHandlerContext } from '../graph-runner/in-process-registry.js';
 import { ensureRunId } from '../harness/harness-space.js';
 import { recordHarnessWorktreeProvenance } from '../harness/harness-worktree-add.js';
 import { resolveInstanceName } from '../instance-identity.js';
@@ -190,6 +192,9 @@ export const codexBackend: AgentBackend = {
   args: ['--yolo', '-c', 'check_for_update_on_startup=false'],
   scrubEnv: ['OPENAI_API_KEY'],
   handleTrust: (screen, write) => {
+    // Compatibility for non-sidetab callers; runVisibleAgentMission handles
+    // this screen with a one-shot Escape when agent='codex' is supplied.
+    if (/update available/i.test(screen) && /\besc(?:ape)?\s+(?:to\s+)?skip\b/i.test(screen)) { write('\u001b'); return true; }
     if (screenNeedsTrust(screen)) { write('1\r'); return true; }
     return false;
   },
@@ -217,6 +222,7 @@ export const claudeBackend: AgentBackend = {
   name: 'claude',
   cmd: 'claude',
   args: ['--dangerously-skip-permissions'],
+  env: { DISABLE_AUTOUPDATER: '1' },
   // CLAUDE_CODE_OAUTH_TOKEN: a launching Claude Code session exports its own token; the child must use the
   //   machine's stored login, never the parent session's (09-29 🅞: status read `oauth_token` → «api-key» · 대표 R2).
   scrubEnv: ['ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'CLAUDE_CODE_OAUTH_TOKEN', 'CLAUDE_CODE_USE_BEDROCK', 'CLAUDE_CODE_USE_VERTEX', 'CLAUDE_CODE_USE_FOUNDRY'],
@@ -298,6 +304,13 @@ export const grokBackend: AgentBackend = {
   cmd: 'grok',
   args: ['--always-approve'],
   scrubEnv: ['XAI_API_KEY', 'GROK_API_KEY', 'GROK_CODE_XAI_API_KEY'],
+  // Grok Build's first-run data-use dialog can cover its composer. Keep the
+  // product's default privacy setting: move to Opt out, then confirm.
+  handleTrust: (screen, write) => {
+    if (!/Help improve Grok/i.test(screen) || !/\[?Opt out\]?/i.test(screen) || !/\[?Opt in\]?/i.test(screen)) return false;
+    write('\u001b[D\r');
+    return true;
+  },
 };
 
 /** Aside Browser agent backend — `aside exec --help` confirms `--effort low`; `ultrabrowse` enables the highest thinking level and proactive mode. */
@@ -452,9 +465,18 @@ export function agentBackendNames(): string[] {
  */
 export function resolveDefaultBackend(
   /** ⛔ 테스트 심 — 실 스토어·실 자격 없이 판정을 주입한다. */
-  deps: { readonly decide?: () => { action: string; backend?: string } } = {},
+  deps: { readonly decide?: () => { action: string; backend?: string }; readonly configuredProvider?: string } = {},
 ): AgentBackend {
   try {
+    const { getUserConfig } = require('../user-config.js') as typeof import('../user-config.js');
+    const provider = deps.configuredProvider ?? getUserConfig().llm.provider;
+    if (provider === 'grok') {
+      debug.log('agent-mission.backend', 'configured-provider', { provider: 'grok', reason: 'user-configured' });
+      return grokBackend;
+    }
+    if (provider === 'openrouter' || provider === 'glm') {
+      throw new Error(`Codex required: agent mission uses a Codex/PTY backend; configured LLM provider '${provider}' is API-only`);
+    }
     const decide = deps.decide
       ?? (() => {
         // ⛔ 지연 로드 — 이 모듈은 부팅 초기에 읽히는데 oauth 축은 스토어·config 를 건드린다.
@@ -467,11 +489,15 @@ export function resolveDefaultBackend(
       debug.log('agent-mission.backend', 'fallback-switch', { from: 'codex', to: decision.backend, reason: 'codex-exhausted' });
       return decision.backend === 'claude' ? claudeBackend : grokBackend;
     }
+    if (decision.action === 'switch-backend' && (decision.backend === 'openrouter' || decision.backend === 'zai')) {
+      throw new Error(`Codex required: agent mission CLI cannot run API provider '${decision.backend}' as a PTY backend`);
+    }
     if (decision.action === 'codex-credits') {
       // CODEX-CREDITS-STEP — 체인 마지막 칸: codex 로 «돌아와» 선불 크레딧으로 계속(판정 쪽이 이미 관측을 남겼다).
       debug.log('agent-mission.backend', 'fallback-codex-credits', { from: 'codex', to: 'codex', reason: 'chain-last-step' });
     }
   } catch (err) {
+    if (err instanceof Error && err.message.startsWith('Codex required:')) throw err;
     debug.log('agent-mission.backend', 'fallback-failed', { message: (err as Error)?.message }, { level: 'warn' });
   }
   return codexBackend;
@@ -541,6 +567,12 @@ export function decideRuntimeFallback(
     return home ? { ...codexBackend, env: { CODEX_HOME: home } } : codexBackend;
   }
   if (decision.action !== 'switch-backend') return null;
+  if (decision.backend === 'openrouter' || decision.backend === 'zai') {
+    debug.log('agent-mission.backend', 'runtime-fallback-unsupported-api-backend', {
+      currentStep, backend: decision.backend, attemptedChainSteps: [...state.attemptedSteps],
+    }, { level: 'warn' });
+    return null;
+  }
   const nextStep = decision.backend === 'grok' ? 'grok' : decision.backend === 'claude' ? 'claude-pty' : null;
   if (!nextStep || state.attemptedSteps.has(nextStep)) return null;
   return nextStep === 'claude-pty' ? claudeBackend : grokBackend;
@@ -575,6 +607,8 @@ export interface AgentMissionSpec {
   agent?: AgentBackend;
   /** Claude CLI 비대화형 stream-json 실행. 다른 backend 에서는 거부. */
   headless?: boolean;
+  /** Optional second user turn sent by resuming the same Claude/Codex CLI session. */
+  followUp?: string;
   /** Install in the agent's own UI before sending the mission. */
   plugin?: Pick<PluginRequest, 'plugin' | 'marketplace'>;
   /** Pre-mission resource judgment; off skips it. */
@@ -662,6 +696,7 @@ export interface AgentMissionDeps {
   reemitPtyUsage?: typeof reemitPtyUsage;
   checkClaudeSubscription?: typeof checkClaudeSubscription;
   runClaudeHeadless?: typeof runClaudeHeadless;
+  runCodexExec?: typeof runCodexExec;
   checkEvidence?: typeof checkEvidence;
   commitWorktree?: typeof commitWorktree;
   dispatchOpenPullRequest?: typeof dispatchOpenPullRequest;
@@ -1626,10 +1661,13 @@ async function runAgentMissionBody(spec: AgentMissionSpec, deps: AgentMissionDep
   if (spec.chain && spec.commit === false && spec.chain.includes('elanous')) throw new Error('elanous PR handoff requires commit authorization');
   if (spec.headless && spec.chain) throw new Error('--headless cannot run a PTY handoff chain');
   if (spec.headless && backend.name !== 'claude') throw new Error('--headless 는 --backend claude 전용입니다');
-  if (spec.plugin && (spec.headless || (backend.name !== 'codex' && backend.name !== 'claude'))) throw new Error('--plugin 은 codex/claude PTY 전용입니다');
+  if (spec.followUp !== undefined && (!spec.followUp.trim() || (backend.name !== 'claude' && backend.name !== 'codex'))) throw new Error('--follow-up 은 비어 있지 않은 Claude/Codex 후속 프롬프트여야 합니다');
+  if (spec.followUp !== undefined && spec.chain) throw new Error('--follow-up cannot run a PTY handoff chain');
+  if (spec.plugin && (spec.headless || spec.followUp !== undefined || (backend.name !== 'codex' && backend.name !== 'claude'))) throw new Error('--plugin 은 codex/claude 대화형 backend 전용입니다');
   if (spec.workdir && spec.chain) throw new Error('workdir 모드는 넘기기 사슬을 쓰지 않는다');
+  const llmConfig = getUserConfig().llm;
   const runtimeFallback = deps.runtimeFallback ?? {
-    ...initialRuntimeFallback(backend, normalizeFallbackChain(getUserConfig().llm?.fallbackChain).chain),
+    ...initialRuntimeFallback(backend, normalizeFallbackChain(llmConfig?.fallbackChain, llmConfig?.provider).chain),
     fallbackEligible: spec.agent === undefined && !spec.chain,
   };
   const spawnPty = deps.startPty ?? startPty;
@@ -1717,7 +1755,7 @@ async function runAgentMissionBody(spec: AgentMissionSpec, deps: AgentMissionDep
   if (deps.isMissionAborted?.()) throw new Error('MISSION_ABORTED');
   const runId = ensureRunId();
   env.ELANOUS_RUN_ID = runId;
-  if (spec.headless === true) {
+  if (spec.headless === true || spec.followUp !== undefined) {
     // The non-interactive child receives the mission on stdin, never via a PTY or argv.
     // Keep the same enhancement and additive memory policy as the interactive mission.
     let prompt = spec.mission;
@@ -1741,17 +1779,52 @@ async function runAgentMissionBody(spec: AgentMissionSpec, deps: AgentMissionDep
       else debug.log('agent-mission', 'memory', { injected: false });
     }
     if (deps.isMissionAborted?.()) throw new Error('MISSION_ABORTED');
-    const headlessRun = (deps.runClaudeHeadless ?? runClaudeHeadless)({ cwd: wt.path, prompt, env: envLiteral(env), maxTurns: maxRounds, onSpawn: deps.onHeadlessStarted });
-    const result = await (deps.awaitMission ? deps.awaitMission(headlessRun) : headlessRun);
+    type SessionRunResult = {
+      ok: boolean; reason: string; exitCode: number | null; sessionId: string | null; numTurns: number | null;
+      toolEvents?: number; malformedLines?: number; durationMs?: number | null;
+    };
+    const firstRun: Promise<SessionRunResult> = backend.name === 'claude'
+      ? (deps.runClaudeHeadless ?? runClaudeHeadless)({ cwd: wt.path, prompt, env: envLiteral(env), maxTurns: maxRounds, onSpawn: deps.onHeadlessStarted })
+      : (deps.runCodexExec ?? runCodexExec)({ cwd: wt.path, prompt, env: envLiteral(env), onSpawn: deps.onHeadlessStarted });
+    let result: SessionRunResult = await (deps.awaitMission ? deps.awaitMission(firstRun) : firstRun);
+    const sessionId = result.sessionId;
+    if (spec.followUp !== undefined) debug.log('agent-mission', 'session-turn', {
+      backend: backend.name, turn: 'initial', ok: result.ok, reason: result.reason, sessionId: result.sessionId, numTurns: result.numTurns,
+    });
+    if (result.ok && spec.followUp !== undefined) {
+      if (!sessionId) {
+        result = { ...result, ok: false, reason: 'no-session', exitCode: result.exitCode };
+      } else if (deps.isMissionAborted?.()) {
+        return { ok: false, reason: 'aborted', worktree: wt.path, branch: wt.branch,
+          rounds: result.numTurns ?? 0, evidencePath: null, committed: false, usedOmniCrawl: false, detail: 'aborted' };
+      } else {
+        debug.log('agent-mission', 'session-resume-start', { backend: backend.name, resumeSessionId: sessionId });
+        const followRun: Promise<SessionRunResult> = backend.name === 'claude'
+          ? (deps.runClaudeHeadless ?? runClaudeHeadless)({ cwd: wt.path, prompt: spec.followUp, resumeSessionId: sessionId, env: envLiteral(env), maxTurns: maxRounds, onSpawn: deps.onHeadlessStarted })
+          : (deps.runCodexExec ?? runCodexExec)({ cwd: wt.path, prompt: spec.followUp, resumeSessionId: sessionId, env: envLiteral(env), onSpawn: deps.onHeadlessStarted });
+        const resumed: SessionRunResult = await (deps.awaitMission ? deps.awaitMission(followRun) : followRun);
+        debug.log('agent-mission', 'session-resume-result', {
+          backend: backend.name, ok: resumed.ok, reason: resumed.reason, expectedSessionId: sessionId,
+          returnedSessionId: resumed.sessionId, numTurns: resumed.numTurns,
+        });
+        if (!resumed.ok || resumed.sessionId !== sessionId) {
+          const missingResumedSession = resumed.reason === 'no-session';
+          result = { ...resumed, ok: false,
+            reason: resumed.ok || missingResumedSession ? 'session-mismatch' : resumed.reason, sessionId };
+        } else {
+          result = { ...resumed, sessionId, numTurns: (result.numTurns ?? 0) + (resumed.numTurns ?? 0) };
+        }
+      }
+    }
     debug.log('agent-mission', 'headless-result', {
       ok: result.ok, reason: result.reason, exitCode: result.exitCode,
-      sessionId: result.sessionId, numTurns: result.numTurns, toolEvents: result.toolEvents,
-      malformedLines: result.malformedLines, durationMs: result.durationMs,
+      sessionId: result.sessionId, numTurns: result.numTurns, malformedLines: result.malformedLines,
+      ...(backend.name === 'claude' ? { toolEvents: result.toolEvents, durationMs: result.durationMs } : {}),
     });
     if (!result.ok) return {
       ok: false, worktree: wt.path, branch: wt.branch, rounds: result.numTurns ?? 0,
       evidencePath: null, committed: false, usedOmniCrawl: false,
-      detail: `Claude headless failed (${result.reason}; exit ${result.exitCode ?? 'unknown'}). Check the Claude CLI and retry.`,
+      detail: `${backend.name} session failed (${result.reason}; exit ${result.exitCode ?? 'unknown'}). Check the CLI and retry.`,
     };
     if (deps.isMissionAborted?.()) return { ok: false, reason: 'aborted', worktree: wt.path, branch: wt.branch,
       rounds: result.numTurns ?? 0, evidencePath: null, committed: false, usedOmniCrawl: false, detail: 'aborted' };
@@ -1770,7 +1843,7 @@ async function runAgentMissionBody(spec: AgentMissionSpec, deps: AgentMissionDep
     }
     let committed = false;
     if (!deps.isMissionAborted?.() && !spec.workdir && (spec.commit ?? true)) {
-      const c = (deps.commitWorktree ?? commitWorktree)(wt.path, `chore(agent-mission): ${spec.branch} — claude-in-elanous headless 산출`);
+      const c = (deps.commitWorktree ?? commitWorktree)(wt.path, `chore(agent-mission): ${spec.branch} — ${backend.name} resumable session 산출`);
       committed = c.ok;
       debug.log('agent-mission', 'commit', { ok: c.ok, out: c.out.slice(0, 120) });
       if (!c.ok) {
@@ -2406,3 +2479,111 @@ async function runAgentMissionBody(spec: AgentMissionSpec, deps: AgentMissionDep
 
 /** @deprecated codex 특정 이름 — runAgentMission 을 쓰라(codex 는 기본 backend). */
 export const runCodexMission = runAgentMission;
+
+export interface ResearchGraphHandNodeInput {
+  question: string;
+  /** Optional focused task for this hand; otherwise the question is paired with the agent's default role. */
+  codexMission?: string;
+  claudeMission?: string;
+}
+
+export interface ResearchGraphHandNodeOptions {
+  agent: 'codex' | 'claude';
+  /** Small role-specific focus added when the graph input does not provide an explicit mission. */
+  focus?: string;
+  maxRounds?: number;
+}
+
+export interface ResearchGraphHandNodeDeps {
+  runMission?: typeof runAgentMission;
+  resolveBackend?: typeof resolveBackend;
+  readResultFile?: (path: string) => string;
+}
+
+const RESEARCH_HAND_REPORT = '.elanous/mission-results/hand-result.md';
+const RESEARCH_HAND_REPORT_MAX_CHARS = 12_000;
+
+function graphSegment(value: string): string {
+  const safe = value.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48);
+  return safe || 'run';
+}
+
+function researchHandInput(input: unknown, agent: 'codex' | 'claude'): { question: string; mission?: string } | undefined {
+  if (typeof input === 'string' && input.trim()) return { question: input.trim() };
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return undefined;
+  const record = input as Record<string, unknown>;
+  const question = typeof record.question === 'string' ? record.question.trim() : '';
+  if (!question) return undefined;
+  const requestedMission = record[`${agent}Mission`];
+  return { question, ...(typeof requestedMission === 'string' && requestedMission.trim() ? { mission: requestedMission.trim() } : {}) };
+}
+
+/**
+ * Build one graph hand node around the existing PTY mission driver. Register one handler per agent
+ * (`handler:research-hand`) in the graph's run-scoped in-process registry; the next node receives a
+ * bounded, redacted report plus the durable report path in `outputs[handNodeId].evidence`.
+ */
+export function createResearchGraphHandNodeHandler(
+  options: ResearchGraphHandNodeOptions,
+  deps: ResearchGraphHandNodeDeps = {},
+): InProcessHandler {
+  if (options.agent !== 'codex' && options.agent !== 'claude') throw new Error('research hand agent must be codex or claude');
+  const maxRounds = options.maxRounds ?? 16;
+  if (!Number.isSafeInteger(maxRounds) || maxRounds <= 0) throw new Error('research hand maxRounds must be a positive integer');
+  const focus = options.focus?.trim() || (options.agent === 'codex'
+    ? '데이터를 수집하고 필요한 계산 코드를 작성·실행해 핵심 근거를 정리하라.'
+    : '주장에 대한 반대 근거와 누락된 전제를 검토하고 검토 보고서를 작성하라.');
+  const runMission = deps.runMission ?? runAgentMission;
+  const backend = (deps.resolveBackend ?? resolveBackend)(options.agent);
+
+  return async (context: InProcessHandlerContext) => {
+    const request = researchHandInput(context.input, options.agent);
+    if (!request) return { ok: false, outcome: 'fail', error: 'research hand node requires a non-empty question in graph input' };
+    const branch = `research-hand-${graphSegment(context.graphId)}-${graphSegment(context.runId)}-${graphSegment(context.nodeId)}-${options.agent}`;
+    const decisionMissionId = `research:${graphSegment(context.graphId)}:${graphSegment(context.runId)}`;
+    const reportPath = join(RESEARCH_HAND_REPORT);
+    const mission = [
+      `연구 질문: ${request.question}`,
+      request.mission ? `이 손의 과제: ${request.mission}` : `역할: ${focus}`,
+      `결과 보고서를 ${reportPath} 에 작성하라. 핵심 결과, 근거와 출처, 불확실성, 다음 취합자가 알아야 할 제한을 간결하게 담고 파일을 비우지 마라.`,
+    ].join('\n\n');
+    const result = await runMission({
+      mission,
+      branch,
+      agent: backend,
+      decisionMissionId,
+      evidence: { kind: 'doc', dirRel: '.elanous/mission-results', glob: /^hand-result[.]md$/i },
+      maxRounds,
+      commit: true,
+      enhance: false,
+      memory: false,
+      resources: 'off',
+      entry: 'external-verbatim',
+    });
+    const absoluteReportPath = join(result.worktree, reportPath);
+    let report = '';
+    if (result.ok) {
+      try { report = (deps.readResultFile ?? ((path) => readFileSync(path, 'utf8')))(absoluteReportPath).trim(); }
+      catch { report = ''; }
+    }
+    const ok = result.ok && report.length > 0;
+    return {
+      ok,
+      outcome: ok ? 'ok' : 'fail',
+      ...(ok ? {} : { error: redactSecretText(result.detail || 'research hand report was missing or empty').slice(0, 500) }),
+      evidence: {
+        hand: options.agent,
+        missionId: decisionMissionId,
+        nodeId: context.nodeId,
+        branch,
+        question: request.question,
+        status: ok ? 'completed' : 'failed',
+        worktree: result.worktree,
+        reportPath: absoluteReportPath,
+        report: ok ? redactSecretText(report).slice(0, RESEARCH_HAND_REPORT_MAX_CHARS) : null,
+        evidencePath: result.evidencePath,
+        detail: redactSecretText(result.detail).slice(0, 500),
+      },
+    };
+  };
+}

package/src/agent-mission/grok-auth-status.ts

@@ -0,0 +1,47 @@
+import { spawn } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export interface GrokLoginProbeResult { ok: boolean; reason?: string }
+export type GrokAuthProbe = (timeoutMs: number) => Promise<{ status: number | null; stdout?: string; stderr?: string; error?: Error }> | { status: number | null; stdout?: string; stderr?: string; error?: Error };
+
+const runAuthProbe: GrokAuthProbe = (timeoutMs) => new Promise((resolve) => {
+  let stdout = '';
+  let stderr = '';
+  let settled = false;
+  const finish = (result: { status: number | null; stdout?: string; stderr?: string; error?: Error }) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    resolve(result);
+  };
+  const child = spawn(join(homedir(), '.grok', 'bin', 'grok'), ['-p', 'reply with just OK'], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  const timer = setTimeout(() => {
+    child.kill('SIGTERM');
+    finish({ status: null, stdout, stderr, error: new Error('Grok subscribed-access probe timed out') });
+  }, Math.max(1, timeoutMs));
+  child.stdout?.setEncoding('utf8').on('data', (chunk: string) => { stdout = `${stdout}${chunk}`.slice(-8_000); });
+  child.stderr?.setEncoding('utf8').on('data', (chunk: string) => { stderr = `${stderr}${chunk}`.slice(-8_000); });
+  child.once('error', (error) => finish({ status: null, stdout, stderr, error }));
+  child.once('close', (status) => finish({ status, stdout, stderr }));
+});
+
+/** Quick, credential-safe subscribed-access probe; whoami needs an interactive TTY in this CLI. */
+export async function probeGrokLogin(run: GrokAuthProbe = runAuthProbe, timeoutMs = 45_000): Promise<GrokLoginProbeResult> {
+  const result = await run(timeoutMs);
+  if (result.error?.name === 'TimeoutError' || /timed out|ETIMEDOUT/i.test(result.error?.message ?? '')) {
+    return { ok: false, reason: 'Grok subscribed-access probe timed out' };
+  }
+  if (result.error) return { ok: false, reason: 'grok CLI could not be started' };
+  const output = `${result.stdout ?? ''}\n${result.stderr ?? ''}`.trim();
+  if (result.status !== 0 || /login required|not authenticated|unauthori[sz]ed|authentication failed/i.test(output)) {
+    const reason = /login required|not authenticated|unauthori[sz]ed|authentication failed/i.test(output)
+      ? 'Grok login unavailable; run grok login'
+      : `Grok subscribed-access probe exited ${result.status ?? 'without a status'}`;
+    return { ok: false, reason };
+  }
+  if (!/^OK\s*$/i.test((result.stdout ?? '').trim())) return { ok: false, reason: 'Grok subscribed-access probe did not return the expected OK reply' };
+  return { ok: true };
+}

package/src/agent-mission/hand-hooks.ts

@@ -0,0 +1,101 @@
+import { randomUUID } from 'node:crypto';
+import { MissionLineEvent, MissionLineInput, postMissionLineEvent } from './mission-line.js';
+
+/**
+ * HAND-HOOKS-NEXUS-STATUS 재수리 — OP #54582 승인 · TC #54571 계약 (2026-10-30).
+ *
+ * 손(hook) 클라이언트: TC 소유 수신기·서버·별도 endpoint는 여기에 없다. 기존 계약
+ * `POST /v1/missions/{missionId}/line`(`src/agent-mission/mission-line.ts` 의
+ * `postMissionLineEvent`)만 지나간다. Claude Code 훅(SessionStart·UserPromptSubmit·Stop·
+ * StopFailure·PreToolUse)과 Codex notify 는 **progress 만** 보낸다. final 은 명시적
+ * `mission reply --done` 전용이며 ask/answer/correct 는 예약(구현하지 않는다).
+ * 인증: missionId+attemptId+손별 Bearer. token(ELANOUS_HAND_TOKEN)은 child env 에만
+ * 둔다 — 인자·파일·다른 저장 위치를 쓰지 않는다. 각 훅 호출은 한 건의 progress 만
+ * 보내고 병렬 송신 경로를 만들지 않는다(Pod concurrency=1).
+ */
+
+/** Claude Code 훅 이벤트 중 progress 를 보낼 때 허용되는 목록. */
+export const CLAUDE_CODE_PROGRESS_EVENTS = ['SessionStart', 'UserPromptSubmit', 'Stop', 'StopFailure', 'PreToolUse'] as const;
+
+export interface HandProgressInput {
+  missionId: string;
+  attemptId: string;
+  agent: 'codex' | 'claude';
+  source: string;
+  text: string;
+  state?: string;
+}
+
+export function renderClaudeHandSource(event: string): string {
+  return `claude-code:${event}`;
+}
+
+export function renderCodexHandSource(tool: string): string {
+  return `codex-notify:${tool}`;
+}
+
+/**
+ * 손(hook) 발화 한 건을 progress 로 기존 mission-line 계약에 싣는다.
+ * lineId 는 이 계약이 새로 발급하고, token 은 env(deps.env ?? process.env)에서만 읽는다.
+ */
+export async function postHandProgress(
+  input: HandProgressInput,
+  deps: { fetch?: typeof fetch; env?: NodeJS.ProcessEnv } = {},
+): Promise<MissionLineEvent> {
+  const payload: MissionLineInput = {
+    lineId: randomUUID(),
+    missionId: input.missionId,
+    attemptId: input.attemptId,
+    agent: input.agent,
+    type: 'progress',
+    source: input.source,
+    text: input.text,
+    ...(input.state === undefined ? {} : { state: input.state }),
+  };
+  return postMissionLineEvent(payload, deps);
+}
+
+function readJsonField(raw: string, field: string): string | null {
+  try {
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    return typeof parsed[field] === 'string' && (parsed[field] as string).trim() ? (parsed[field] as string).trim() : null;
+  } catch { return null; }
+}
+
+/** child env 접근자 — 자격(missionId·attemptId)은 child env 에만 있다(파일·인자 저장 금지). */
+function missionId(env: NodeJS.ProcessEnv): string {
+  return env.ELANOUS_MISSION_ID?.trim() ?? '';
+}
+function attemptId(env: NodeJS.ProcessEnv): string {
+  return env.ELANOUS_ATTEMPT_ID?.trim() ?? '';
+}
+
+/** CLI: `bun src/agent-mission/hand-hooks.ts claude-code|codex-notify` — stdin JSON 훅 본문. fail-soft(exit 0). */
+async function main(): Promise<number> {
+  const mode = process.argv[2] ?? '';
+  const env = process.env;
+  const mission = missionId(env);
+  const attempt = attemptId(env);
+  const token = env.ELANOUS_HAND_TOKEN?.trim();
+  // 자격은 child env 에만 존재한다 — 없으면 조용히 넘어간다(훅이 Claude Code/Codex 를 막지 않는다).
+  if (!mission || !attempt || !token) return 0;
+  const raw = await new Response(Bun.stdin.stream()).text();
+  const text = raw.slice(0, 200);
+  // 계약상 text 는 비어 있으면 안 된다 — 빈 훅 본문은 계약 위반 요청을 만들지 않고 조용히 넘어간다.
+  if (!text.trim()) return 0;
+  if (mode === 'claude-code') {
+    const event = readJsonField(raw, 'hook_event_name');
+    // 허용 이벤트만 progress — 그 외(예약 ask/answer/correct·final)는 여기서 만들지 않는다.
+    if (!event || !(CLAUDE_CODE_PROGRESS_EVENTS as readonly string[]).includes(event)) return 0;
+    await postHandProgress({ missionId: mission, attemptId: attempt, agent: 'claude', source: renderClaudeHandSource(event), text });
+  } else if (mode === 'codex-notify') {
+    const tool = readJsonField(raw, 'tool_name') ?? 'notify';
+    await postHandProgress({ missionId: mission, attemptId: attempt, agent: 'codex', source: renderCodexHandSource(tool), text });
+  }
+  return 0;
+}
+
+if (import.meta.main) {
+  try { process.exit(await main()); }
+  catch { process.exit(0); } // fail-soft: 손 전달 실패가 훅 호출자를 막지 않는다.
+}