elanous 0.2.42 → 0.2.43

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: 손 전달 실패가 훅 호출자를 막지 않는다.
+}

package/src/agent-mission/mission-cli.ts

@@ -6,7 +6,8 @@
 
 import { readFileSync } from 'node:fs';
 import type { AgentBackend, AgentMissionResult, EvidenceMode } from './driver.js';
-import type { AgentCliDetection } from './tool-install.js';
+import { runAgentMissionDuo, type DuoDeps, type DuoResult } from './duo.js';
+import type { AgentCli, AgentCliDetection, AgentCliPreparation } from './tool-install.js';
 import { buildAgentMissionDevSpec, executeAgentMissionReroute, type runDevPipeline } from '../self-dev/dev-pipeline.js';
 import { parsePositiveInt } from '../self-dev/dev-cli.js';
 import { parsePluginRef } from './in-agent-plugin.js';
@@ -17,7 +18,9 @@ export interface MissionCliOpts {
   base?: string;
   backend?: string;
   chain?: string;
+  duo?: boolean;
   headless?: boolean;
+  followUp?: string;
   plugin?: string;
   resources?: 'on' | 'off';
   evidence?: string; // 'doc' | 'tsc' | 'test'
@@ -35,15 +38,17 @@ export interface MissionCliOpts {
 export interface MissionCliDeps {
   resolveBackend: (name?: string) => AgentBackend;
   detectAgentCli?: (agent: 'claude' | 'codex') => AgentCliDetection;
+  prepareAgentCli?: (agent: AgentCli) => Promise<AgentCliPreparation>;
   onStatus?: (line: string) => void;
   signal?: AbortSignal;
   readFile?: (path: string) => string;
   runDevPipeline?: typeof runDevPipeline;
+  duoDeps?: DuoDeps;
 }
 
 export type MissionCliOutcome =
   | { ok: false; message: string; exitCode: number }
-  | { ok: true; result: AgentMissionResult; exitCode: number };
+  | { ok: true; result: AgentMissionResult; duo?: DuoResult; exitCode: number };
 
 /** mission CLI 글루 — 검증/구성/실행. process.exit·console 없음(호출부가 I/O). */
 export async function runAgentMissionCliCommand(
@@ -53,8 +58,11 @@ export async function runAgentMissionCliCommand(
 ): Promise<MissionCliOutcome> {
   // ── backend 검증(fail-fast·단일 resolve) ──
   const chain = opts.chain?.split(',').map((item) => item.trim());
-  if (chain && (opts.commit === false || !['codex,claude,elanous', 'codex,claude,codex,elanous'].includes(chain.join(',')) || (opts.backend && opts.backend !== 'codex') || opts.headless)) {
-    return { ok: false, message: '--chain 은 codex,claude[,codex],elanous 형식이며 --backend 는 첫 backend 와 같아야 하고 --headless/--no-commit 은 함께 쓸 수 없습니다', exitCode: 1 };
+  if (chain && (opts.commit === false || !['codex,claude,elanous', 'codex,claude,codex,elanous'].includes(chain.join(',')) || (opts.backend && opts.backend !== 'codex') || opts.headless || opts.followUp !== undefined)) {
+    return { ok: false, message: '--chain 은 codex,claude[,codex],elanous 형식이며 --backend 는 첫 backend 와 같아야 하고 --headless/--follow-up/--no-commit 은 함께 쓸 수 없습니다', exitCode: 1 };
+  }
+  if (opts.duo && (chain || opts.backend || opts.headless || opts.followUp !== undefined || opts.plugin || opts.enhance === false)) {
+    return { ok: false, message: '--duo 는 Codex·Claude 병렬 기본값만 지원하며 --chain/--backend/--headless/--follow-up/--plugin/--no-enhance 와 함께 쓸 수 없습니다', exitCode: 1 };
   }
   let agentBackend: AgentBackend;
   try { agentBackend = deps.resolveBackend(chain?.[0] ?? opts.backend); }
@@ -62,8 +70,14 @@ export async function runAgentMissionCliCommand(
   if (opts.headless && agentBackend.name !== 'claude') {
     return { ok: false, message: '--headless 는 --backend claude 전용입니다', exitCode: 1 };
   }
+  if (opts.followUp !== undefined && !opts.followUp.trim()) {
+    return { ok: false, message: '--follow-up 은 비어 있지 않은 후속 프롬프트가 필요합니다', exitCode: 1 };
+  }
+  if (opts.followUp !== undefined && !['claude', 'codex'].includes(agentBackend.name)) {
+    return { ok: false, message: '--follow-up 은 Claude 또는 Codex backend 전용입니다', exitCode: 1 };
+  }
   const plugin = opts.plugin ? parsePluginRef(opts.plugin) : null;
-  if (opts.plugin !== undefined && (!plugin || !['codex', 'claude'].includes(agentBackend.name) || opts.headless)) {
+  if (opts.plugin !== undefined && (!plugin || !['codex', 'claude'].includes(agentBackend.name) || opts.headless || opts.followUp !== undefined)) {
     return { ok: false, message: '--plugin 은 codex/claude 대화형 backend 에서 <name>@<market> 형식이어야 합니다', exitCode: 1 };
   }
   if (opts.resources !== undefined && opts.resources !== 'on' && opts.resources !== 'off') {
@@ -108,6 +122,7 @@ export async function runAgentMissionCliCommand(
     resources: opts.resources ?? 'on',
     ...(opts.backend ? { backendExplicit: opts.backend } : {}),
     ...(opts.headless ? { headless: true } : {}),
+    ...(opts.followUp !== undefined ? { followUp: opts.followUp } : {}),
     branch: opts.branch,
     ...(opts.base ? { base: opts.base } : {}),
     ...(opts.enhance === false ? { enhanceOff: true } : {}),
@@ -119,24 +134,44 @@ export async function runAgentMissionCliCommand(
   });
   // The production CLI injects the host probe; injected tests can assert this preflight
   // without spawning an agent CLI. For a chain, inspect each external CLI before any launch.
-  const externalAgents = [...new Set((chain ?? [agentBackend.name]).filter(
+  const externalAgents: Array<'claude' | 'codex'> = opts.duo ? ['codex', 'claude'] : [...new Set((chain ?? [agentBackend.name]).filter(
     (name): name is 'claude' | 'codex' => name === 'claude' || name === 'codex',
   ))];
-  const detections = deps.detectAgentCli ? externalAgents.map((agent) => deps.detectAgentCli!(agent)) : [];
-  const statusLine = detections.map(({ message }) => message).join(' · ');
-  if (statusLine) deps.onStatus?.(statusLine);
-  const notReady = detections.find(({ installed, login }) => installed !== true || login !== 'ready');
-  if (notReady) {
-    const message = notReady.installed === false
-      ? `${notReady.message}; 공식 설치 후 다시 실행`
-      : notReady.installed === null
-        ? `${notReady.message}; 설치 상태를 확인한 뒤 다시 실행`
-        : notReady.login === 'api-key'
-          ? `${notReady.message}; API 키 요금 고지와 동의 화면이 아직 없어 미션을 시작하지 않습니다 — Codex 구독 로그인(codex login) 후 다시 실행`
-        : notReady.login === 'needed'
-          ? `${notReady.message}; ${notReady.agent} login 후 다시 실행`
-          : `${notReady.message}; 로그인 상태를 확인한 뒤 다시 실행`;
-    return { ok: false, message, exitCode: 1 };
+  if (deps.prepareAgentCli) {
+    for (const agent of externalAgents) {
+      const prepared = await deps.prepareAgentCli(agent);
+      if (!prepared.ready) return { ok: false, message: prepared.message, exitCode: 1 };
+    }
+  } else {
+    const detections = deps.detectAgentCli ? externalAgents.map((agent) => deps.detectAgentCli!(agent)) : [];
+    const statusLine = detections.map(({ message }) => message).join(' · ');
+    if (statusLine) deps.onStatus?.(statusLine);
+    const notReady = detections.find(({ installed, login }) => installed !== true || login !== 'ready');
+    if (notReady) {
+      const message = notReady.installed === false
+        ? `${notReady.message}; 공식 설치 후 다시 실행`
+        : notReady.installed === null
+          ? `${notReady.message}; 설치 상태를 확인한 뒤 다시 실행`
+          : notReady.login === 'api-key'
+            ? `${notReady.message}; API 키 요금 고지와 동의 화면이 아직 없어 미션을 시작하지 않습니다 — Codex 구독 로그인(codex login) 후 다시 실행`
+            : notReady.login === 'needed'
+              ? `${notReady.message}; ${notReady.agent} login 후 다시 실행`
+              : `${notReady.message}; 로그인 상태를 확인한 뒤 다시 실행`;
+      return { ok: false, message, exitCode: 1 };
+    }
+  }
+  if (opts.duo) {
+    const duo = await runAgentMissionDuo([mission], {
+      left: 'codex', right: 'claude', branch: opts.branch, ...(opts.base ? { base: opts.base } : {}),
+      evidence: opts.evidence, ...(opts.docDir ? { docDir: opts.docDir } : {}), ...(opts.docGlob ? { docGlob: opts.docGlob } : {}),
+      ...(opts.testPath ? { testPath: opts.testPath } : {}), ...(opts.file ? { file: opts.file } : {}),
+      maxRounds: opts.maxRounds, commit: opts.commit,
+    }, { ...deps.duoDeps, resolveBackend: deps.duoDeps?.resolveBackend ?? deps.resolveBackend });
+    const result = duo.sides.find((side) => side.result)?.result ?? {
+      ok: false, worktree: '', branch: null, rounds: 0, evidencePath: null, committed: false,
+      usedOmniCrawl: false, detail: duo.lines.join('\n'),
+    };
+    return { ok: true, result, duo, exitCode: duo.exitCode };
   }
   const { result, exitCode } = await executeAgentMissionReroute(
     spec, agentBackend,