elanous 0.2.42 → 0.2.44

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,107 @@
+import { spawn } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export type GrokProbeStage = 'spawn' | 'first-byte' | 'auth' | 'connect' | 'response' | 'exit';
+export interface GrokLoginProbeResult { ok: boolean; reason?: string; stage?: GrokProbeStage; durationMs?: number }
+export interface GrokAuthProbeResult { status: number | null; stdout?: string; stderr?: string; error?: Error; stage?: GrokProbeStage; durationMs?: number }
+export type GrokAuthProbe = (timeoutMs: number) => Promise<GrokAuthProbeResult> | GrokAuthProbeResult;
+
+type ProbeChild = ReturnType<typeof spawn>;
+type ProbeSpawner = typeof spawn;
+
+export const runAuthProbe: (timeoutMs: number, spawnProcess?: ProbeSpawner) => Promise<GrokAuthProbeResult> = (timeoutMs, spawnProcess = spawn) => new Promise((resolve) => {
+  const startedAt = Date.now();
+  let stage: GrokProbeStage = 'spawn';
+  let stdout = '';
+  let stderr = '';
+  let pendingStderrLine = '';
+  let discardStderrLine = false;
+  let settled = false;
+  const capturedStderr = () => sanitizeStderr(`${stderr}${pendingStderrLine}`).slice(-8_000);
+  const appendStderr = (chunk: string) => {
+    let remaining = chunk;
+    if (discardStderrLine) {
+      const newline = remaining.indexOf('\n');
+      if (newline < 0) return;
+      remaining = remaining.slice(newline + 1);
+      discardStderrLine = false;
+    }
+    const lines = `${pendingStderrLine}${remaining}`.split('\n');
+    pendingStderrLine = lines.pop() ?? '';
+    if (lines.length) stderr = sanitizeStderr(`${stderr}${lines.join('\n')}`).slice(-8_000);
+    if (pendingStderrLine.length > 64_000) {
+      if (/(?:authorization\s*:\s*(?:basic|bearer|token|apikey|api[- ]key)|(?:api[_-]?key|api[_-]?token|access[_-]?key|secret|password|credential|auth[_-]?token|refresh[_-]?token))\s*[:=]/i.test(pendingStderrLine)) {
+        pendingStderrLine = '';
+        discardStderrLine = true;
+      } else {
+        pendingStderrLine = pendingStderrLine.slice(-8_000);
+      }
+    }
+  };
+  const finish = (result: GrokAuthProbeResult) => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    resolve({ ...result, stderr: capturedStderr(), stage: result.stage ?? stage, durationMs: Date.now() - startedAt });
+  };
+  const child: ProbeChild = spawnProcess(join(homedir(), '.grok', 'bin', 'grok'), ['-p', 'reply with just OK'], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  child.once('spawn', () => { stage = 'first-byte'; });
+  const timer = setTimeout(() => {
+    child.kill('SIGTERM');
+    finish({ status: null, stdout, stderr: capturedStderr(), stage: classifyStage(capturedStderr(), stdout, stage), error: new Error('Grok subscribed-access probe timed out') });
+  }, Math.max(1, timeoutMs));
+  child.stdout?.setEncoding('utf8').on('data', (chunk: string) => { stage = 'response'; stdout = `${stdout}${chunk}`.slice(-8_000); });
+  child.stderr?.setEncoding('utf8').on('data', (chunk: string) => { appendStderr(chunk); stage = classifyStage(capturedStderr(), stdout, stage); });
+  child.once('error', (error) => finish({ status: null, stdout, stderr, stage, error }));
+  child.once('close', (status) => finish({ status, stdout, stderr, stage: classifyStage(stderr, stdout, 'exit') }));
+});
+
+/** 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);
+  const stage = result.stage ?? classifyStage(result.stderr ?? '', result.stdout ?? '', result.error ? 'first-byte' : 'exit');
+  const duration = result.durationMs === undefined ? {} : { durationMs: result.durationMs };
+  const details = formatDiagnostics(stage, result.durationMs, result.stderr);
+  if (result.error?.name === 'TimeoutError' || /timed out|ETIMEDOUT/i.test(result.error?.message ?? '')) {
+    return { ok: false, stage, ...duration, reason: `Grok subscribed-access probe timed out ${details}` };
+  }
+  if (result.error) return { ok: false, stage, ...duration, reason: `grok CLI could not be started ${details}` };
+  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 ${formatDiagnostics('auth', result.durationMs, result.stderr)}`
+      : `Grok subscribed-access probe exited ${result.status ?? 'without a status'} ${details}`;
+    return { ok: false, stage: /login required|not authenticated|unauthori[sz]ed|authentication failed/i.test(output) ? 'auth' : stage, ...duration, reason };
+  }
+  if (!/^OK\s*$/i.test((result.stdout ?? '').trim())) return { ok: false, stage, ...duration, reason: `Grok subscribed-access probe did not return the expected OK reply ${details}` };
+  return { ok: true, stage, ...duration };
+}
+
+function classifyStage(stderr: string, stdout: string, fallback: GrokProbeStage): GrokProbeStage {
+  if (/login required|not authenticated|unauthori[sz]ed|authentication failed/i.test(stderr)) return 'auth';
+  if (/ECONN|ENOTFOUND|EHOST|network|connect(?:ion)? (?:refused|failed|timeout)|TLS|certificate/i.test(stderr)) return 'connect';
+  // Stderr can contain pre-response warnings; only stdout proves that a reply
+  // byte reached the caller.
+  if (stdout) return 'response';
+  return fallback;
+}
+
+function formatDiagnostics(stage: GrokProbeStage, durationMs?: number, stderr?: string): string {
+  const safeStderr = sanitizeStderr(stderr);
+  return `(${stage}${durationMs === undefined ? '' : ` after ${durationMs}ms`}${safeStderr ? `; stderr: ${safeStderr}` : '; stderr: <empty>'})`;
+}
+
+function sanitizeStderr(stderr?: string): string {
+  return (stderr ?? '')
+    .replace(/(authorization\s*:\s*(?:basic|bearer|token|apikey|api[- ]key)\s+)\S+/gi, '$1[redacted]')
+    .replace(/(?:[A-Z0-9_]*(?:api[_-]?key|access[_-]?key|secret|password|credential|auth[_-]?token|refresh[_-]?token))\s*[:=]\s*(?:"[^"\r\n]*"|'[^'\r\n]*'|[^\r\n]*)/gi, '[redacted credential]')
+    .replace(/Bearer\s+\S+/gi, 'Bearer [redacted]')
+    .replace(/(?:sk|xai|gsk|gh[pousr])-[A-Za-z0-9_-]{8,}/g, '[redacted-token]')
+    .replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, '[redacted-email]')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(-500);
+}

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