elanous 0.2.42 → 0.2.43

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

@@ -6,8 +6,14 @@ import type { Command } from 'commander';
 import { debug, redactSecretText } from '../debug/log.js';
 import type { AsyncLockHandle } from '../storage/file-lock.js';
 import { stateDirSourceForChild } from '../agent/identity-env.js';
+import { createMissionLineStore, MissionLineHttpError, postMissionLineEvent, type MissionLineType } from './mission-line.js';
+import type { LinearMissionLink } from '../intake-plane/linear-mission-sync.js';
 
 const MISSION_CONTEXT_ENV = 'ELANOUS_MISSION_CONTEXT';
+const HAND_CHILD_ENV_KEYS = [
+  'ELANOUS_MISSION_ID', 'ELANOUS_ATTEMPT_ID', 'ELANOUS_HAND_TOKEN', 'ELANOUS_HAND_ATTEMPT_ID',
+  'ELANOUS_HAND_FINAL_LINE_ID', 'ELANOUS_HAND_AGENT', 'ELANOUS_HAND_RUN_ID', 'ELANOUS_HAND_PTY_ID',
+] as const;
 
 interface MissionContext { missionId: string; storeRoot: string }
 
@@ -21,17 +27,27 @@ function missionContextForEnv(env: NodeJS.ProcessEnv, missionId: string): Missio
   } catch { return undefined; }
 }
 
-function missionChildEnv(root: string, missionId: string, base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+export function missionChildEnv(root: string, missionId: string, base: NodeJS.ProcessEnv = process.env, line?: { token: string; attemptId: string; finalLineId: string; agent: 'codex' | 'claude'; nexusUrl?: string; runId?: string; ptyId?: string }): NodeJS.ProcessEnv {
   const storeRoot = resolve(root);
+  const childBase = { ...base };
+  for (const key of HAND_CHILD_ENV_KEYS) delete childBase[key];
   return {
-    ...base,
+    ...childBase,
     ELANOUS_STATE_DIR: storeRoot,
     ELANOUS_STATE_DIR_SOURCE: stateDirSourceForChild(storeRoot, base),
+    ...(line ? { ELANOUS_MISSION_ID: missionId, ELANOUS_ATTEMPT_ID: line.attemptId,
+      ELANOUS_HAND_TOKEN: line.token, ELANOUS_HAND_ATTEMPT_ID: line.attemptId,
+      ELANOUS_HAND_FINAL_LINE_ID: line.finalLineId, ELANOUS_HAND_AGENT: line.agent,
+      ...(line.runId ? { ELANOUS_HAND_RUN_ID: line.runId, ELANOUS_RUN_ID: line.runId } : {}),
+      ...(line.ptyId ? { ELANOUS_HAND_PTY_ID: line.ptyId } : {}), ...(line.nexusUrl ? { ELANOUS_NEXUS_URL: line.nexusUrl } : {}) } : {}),
     [MISSION_CONTEXT_ENV]: JSON.stringify({ missionId, storeRoot }),
   };
 }
 
 export type MissionOutStatus = 'running' | 'completed' | 'cancelled' | 'failed' | 'timeout';
+export class MissionReplyStateError extends Error {
+  constructor(readonly status: 404 | 409, message: string) { super(message); this.name = 'MissionReplyStateError'; }
+}
 export interface MissionReplyEvent {
   type: 'mission.reply';
   missionId: string;
@@ -45,6 +61,18 @@ export interface MissionReplyEvent {
   scope?: string;
   stop?: boolean;
   priority?: string;
+  lineId?: string;
+  attemptId?: string;
+  runId?: string;
+  ptyId?: string;
+  replyTo?: number;
+  agent?: 'codex' | 'claude';
+  lineType?: 'progress' | 'final' | 'ask' | 'answer' | 'correct';
+  source?: string;
+  state?: string;
+  who?: string;
+  what?: string;
+  graphEvents?: Array<{ seq: number; ts: string; type: 'node-added'; node: string; kind: 'hand'; decider: 'mission-line'; reason: string; who: string; what: string; missionId: string }>;
 }
 export interface MissionReplyMessageFields {
   kind?: string;
@@ -53,6 +81,17 @@ export interface MissionReplyMessageFields {
   scope?: string;
   stop?: boolean;
   priority?: string;
+  lineId?: string;
+  attemptId?: string;
+  runId?: string;
+  ptyId?: string;
+  replyTo?: number;
+  agent?: 'codex' | 'claude';
+  lineType?: 'progress' | 'final' | 'ask' | 'answer' | 'correct';
+  source?: string;
+  state?: string;
+  who?: string;
+  what?: string;
 }
 export interface MissionOutRecord {
   missionId: string;
@@ -70,6 +109,8 @@ export interface MissionOutRecord {
   pendingFinalReply?: string;
   workerPid?: number;
   agentPid?: number;
+  /** Server-validated DEMO child issue; never populated from a reply payload. */
+  linearLink?: LinearMissionLink;
 }
 export interface MissionOutStoreDeps {
   now?: () => Date;
@@ -151,12 +192,22 @@ function validateReplyMessageFields(fields: MissionReplyMessageFields): MissionR
     const value = fields[key];
     if (value !== undefined && (typeof value !== 'string' || !value.trim())) throw new Error(`reply ${key} 는 비어 있지 않은 문자열이어야 합니다`);
   }
+  for (const key of ['attemptId', 'runId', 'ptyId', 'source', 'state', 'who', 'what', 'lineId'] as const) {
+    const value = fields[key];
+    if (value !== undefined && (typeof value !== 'string' || !value.trim())) throw new Error(`reply ${key} 는 비어 있지 않은 문자열이어야 합니다`);
+  }
+  if (fields.replyTo !== undefined && (!Number.isInteger(fields.replyTo) || fields.replyTo < 1)) throw new Error('reply replyTo 는 양의 정수여야 합니다');
+  if (fields.lineId !== undefined && !/^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/i.test(fields.lineId)) {
+    throw new Error('reply lineId 는 UUID 형식이어야 합니다');
+  }
+  if (fields.agent !== undefined && fields.agent !== 'codex' && fields.agent !== 'claude') throw new Error('reply agent 값이 올바르지 않습니다');
+  if (fields.lineType !== undefined && !['progress', 'final', 'ask', 'answer', 'correct'].includes(fields.lineType)) throw new Error('reply lineType 값이 올바르지 않습니다');
   if (fields.stop !== undefined && typeof fields.stop !== 'boolean') throw new Error('reply stop 은 boolean 이어야 합니다');
   if (fields.kind === 'correct' && (!fields.scope || fields.stop === undefined || !fields.priority)) {
     throw new Error('reply kind=correct 에는 scope, stop, priority 가 필요합니다');
   }
   // ask / answer / correct are reserved names. Unknown names remain accepted
-  // as extension kinds; their behavior is intentionally deferred to 0.2.43.
+  // as extension kinds.
   return fields;
 }
 
@@ -166,6 +217,19 @@ function atomicJson(path: string, value: unknown): void {
   renameSync(temp, path);
 }
 
+export async function waitForMissionAnswer(store: ReturnType<typeof createMissionOutStore>, missionId: string, ask: Pick<MissionReplyEvent, 'sequence' | 'deadline'>, defaults: string, deps: { now?: () => number; sleep?: (ms: number) => Promise<void> } = {}): Promise<{ text: string; usedDefault: boolean }> {
+  const now = deps.now ?? Date.now;
+  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((resolveDelay) => setTimeout(resolveDelay, ms)));
+  const parsedDeadline = ask.deadline ? Date.parse(ask.deadline) : Number.NaN;
+  const deadline = Number.isFinite(parsedDeadline) ? parsedDeadline : now() + 2 * 60_000;
+  while (now() < deadline) {
+    const answer = store.replies(missionId).find((event) => event.kind === 'answer' && event.replyTo === ask.sequence);
+    if (answer) return { text: answer.text, usedDefault: false };
+    await sleep(Math.min(250, Math.max(1, deadline - now())));
+  }
+  return { text: defaults, usedDefault: true };
+}
+
 export function createMissionOutStore(root: string, deps: MissionOutStoreDeps = {}) {
   const now = deps.now ?? (() => new Date());
   const withLock = async <T>(missionId: string, action: (lock: AsyncLockHandle) => T): Promise<T> => {
@@ -196,7 +260,7 @@ export function createMissionOutStore(root: string, deps: MissionOutStoreDeps =
     } catch { return []; }
   };
   return {
-    create(input: { missionId?: string; agent: 'codex' | 'claude'; prompt: string; cwd: string; outputPath: string; targetOutputPath: string }): MissionOutRecord {
+    create(input: { missionId?: string; agent: 'codex' | 'claude'; prompt: string; cwd: string; outputPath: string; targetOutputPath: string; linearLink?: LinearMissionLink }): MissionOutRecord {
       const dir = join(root, 'agent-missions');
       mkdirSync(dir, { recursive: true, mode: 0o700 });
       const createdAt = now().toISOString();
@@ -218,13 +282,27 @@ export function createMissionOutStore(root: string, deps: MissionOutStoreDeps =
       if (!text.trim()) throw new Error('reply 본문이 비었습니다');
       const messageFields = validateReplyMessageFields(fields);
       return withLock(missionId, (lock) => {
+        const priorLine = messageFields.lineId
+          ? replies(missionId).find((event) => event.lineId === messageFields.lineId)
+          : undefined;
+        if (priorLine) return priorLine;
         const current = read(missionId);
-        if (!current) throw new Error(`미션을 찾을 수 없습니다: ${missionId}`);
-        if (current.status !== 'running') throw new Error(`미션이 실행 중이 아닙니다: ${current.status}`);
-        if (current.doneReceived || replies(missionId).some((event) => event.done)) throw new Error('최종 답변이 이미 제출됐습니다');
+        if (!current) throw new MissionReplyStateError(404, `미션을 찾을 수 없습니다: ${missionId}`);
+        if (current.status !== 'running') throw new MissionReplyStateError(409, `미션이 실행 중이 아닙니다: ${current.status}`);
+        if (current.doneReceived || replies(missionId).some((event) => event.done)) throw new MissionReplyStateError(409, '최종 답변이 이미 제출됐습니다');
+        if (messageFields.kind === 'ask' && replies(missionId).filter((event) => event.kind === 'ask').length >= 3) {
+          throw new MissionReplyStateError(409, '미션당 ask 는 최대 3회입니다; 남은 정보로 진행하거나 다시 작성하세요');
+        }
+        const askDeadline = messageFields.kind === 'ask'
+          ? (messageFields.deadline ?? new Date(now().getTime() + 2 * 60_000).toISOString())
+          : undefined;
         const event: MissionReplyEvent = {
           type: 'mission.reply', missionId, sequence: replies(missionId).length + 1,
           text, done, createdAt: now().toISOString(), ...messageFields,
+          ...(askDeadline ? { deadline: askDeadline } : {}),
+          ...(replies(missionId).length === 0 && messageFields.who && messageFields.what ? {
+            graphEvents: [{ seq: 1, ts: now().toISOString(), type: 'node-added', node: `hand-${missionId}`, kind: 'hand', decider: 'mission-line', reason: 'hand mission line opened', who: messageFields.who, what: messageFields.what, missionId }],
+          } : {}),
         };
         if (!lock.stillHeld()) throw new Error('미션 상태 잠금을 잃어 reply 기록을 중단했습니다');
         appendFileSync(replyPath(root, missionId), `${JSON.stringify(event)}\n`, { encoding: 'utf8', mode: 0o600 });
@@ -339,7 +417,34 @@ export async function runMissionOutWorker(root: string, missionId: string, runAg
     if (!existsSync(record.outputPath) || statSync(record.outputPath).size === 0) throw new Error('결과 파일이 없어 미션을 실패 처리했습니다');
     const latest = store.read(missionId);
     if (!latest || latest.status !== 'running') return;
-    if (!latest.doneReceived) await store.reply(missionId, readFileSync(record.outputPath, 'utf8'), true);
+    if (!latest.doneReceived) {
+      const finalText = readFileSync(record.outputPath, 'utf8');
+      const lineToken = process.env.ELANOUS_HAND_TOKEN?.trim();
+      const lineAttemptId = process.env.ELANOUS_HAND_ATTEMPT_ID?.trim();
+      const lineId = process.env.ELANOUS_HAND_FINAL_LINE_ID?.trim() || randomUUID();
+      const persistedFinal = lineAttemptId
+        ? store.replies(missionId).find((event) => event.done && event.attemptId === lineAttemptId)
+        : undefined;
+      if (persistedFinal) {
+        // NEXUS may have durably appended the final row but lost its HTTP
+        // response. Reuse that row; never append a second terminal event.
+      } else if (lineToken && lineAttemptId) {
+        try {
+          await postMissionLineEvent({ lineId, missionId, attemptId: lineAttemptId, agent: record.agent, type: 'final', source: 'mission-worker', text: finalText, state: 'completed' });
+        } catch (error) {
+          if (error instanceof MissionLineHttpError && error.status < 500) throw error;
+          // The local mission ledger is the durability boundary. NEXUS is an
+          // observation/transport edge; an unavailable daemon must not turn a
+          // valid output file into a lost final reply.
+          debug.log('agent-mission', 'line-ingress-fallback', { missionId, error: redactSecretText(String(error)) });
+          const racedFinal = store.replies(missionId).find((event) => event.lineId === lineId);
+          if (!racedFinal) await store.reply(missionId, finalText, true, {
+            lineId, attemptId: lineAttemptId, agent: record.agent, lineType: 'final', source: 'mission-worker', state: 'completed',
+            ...(store.replies(missionId).length === 0 ? { who: record.agent === 'claude' ? 'Claude' : 'Codex', what: record.prompt.replace(/\s+/g, ' ').trim().slice(0, 180) || 'hand mission' } : {}),
+          });
+        }
+      } else await store.reply(missionId, finalText, true);
+    }
     await store.complete(missionId);
   } catch (e) {
     const latest = store.read(missionId);
@@ -353,6 +458,11 @@ export async function runMissionOutWorker(root: string, missionId: string, runAg
         debug.log('agent-mission', 'terminal-write-failed', { missionId, error: redactSecretText(String(stateError)) }, { level: 'error' });
       }
     }
+  } finally {
+    // The attempt credential belongs to this worker job, including failure and
+    // cancellation paths. Revocation is idempotent when a final line already
+    // closed the token at the NEXUS ingress.
+    createMissionLineStore(root).revoke(missionId);
   }
 }
 
@@ -402,7 +512,7 @@ const missionUsage = {
   command: 'eln mission',
   commands: {
     run: {
-      args: [], flags: ['--agent codex|claude', '--prompt <text>|--prompt-file <path>', '--out <path>', '--dry-run', '--output-format json'],
+      args: [], flags: ['--agent codex|claude', '--prompt <text>|--prompt-file <path>', '--out <path>', '--linear-issue-id <id>', '--dry-run', '--output-format json'],
       responseSchema: { type: 'object', required: ['id', 'missionId', 'status'], properties: { id: { type: 'string', format: 'uuid' }, missionId: { type: 'string', format: 'uuid' }, status: { const: 'running' }, artifacts: { type: 'array', items: { type: 'string' } } } },
     },
     status: {
@@ -410,7 +520,7 @@ const missionUsage = {
       responseSchema: { type: 'object', required: ['id', 'missionId', 'status', 'artifacts', 'replies'], properties: { id: { type: 'string', format: 'uuid' }, missionId: { type: 'string', format: 'uuid' }, status: { enum: ['running', 'done', 'cancelled', 'failed', 'timeout'] }, body: { type: 'string' }, artifacts: { type: 'array', items: { type: 'string' } }, replies: { type: 'array', items: { $ref: '#/events/mission.reply' } }, result: { type: 'string' }, lockStale: { type: 'boolean' }, error: { type: 'string' } } },
     },
     reply: {
-      args: ['[missionId]', '[text|stdin]'], flags: ['--mission <missionId>', '--done', '--kind <kind>', '--defaults <text>', '--deadline <value>', '--scope <text>', '--[no-]stop', '--priority <value>'],
+      args: ['[missionId]', '[text|stdin]'], flags: ['--mission <missionId>', '--done', '--kind <kind>', '--defaults <text>', '--deadline <value>', '--reply-to <sequence>', '--scope <text>', '--[no-]stop', '--priority <value>'],
       responseSchema: { type: 'object', required: ['missionId', 'accepted', 'sequence', 'done'], properties: { missionId: { type: 'string', format: 'uuid' }, accepted: { const: true }, sequence: { type: 'integer', minimum: 1 }, done: { type: 'boolean' } } },
     },
     cancel: {
@@ -418,12 +528,14 @@ const missionUsage = {
       responseSchema: { type: 'object', required: ['missionId', 'status', 'cancelled'], properties: { missionId: { type: 'string', format: 'uuid' }, status: { enum: ['running', 'completed', 'cancelled', 'failed'] }, cancelled: { type: 'boolean' } } },
     },
   },
-  events: { 'mission.reply': { type: 'object', required: ['type', 'missionId', 'sequence', 'text', 'done', 'createdAt'], properties: { type: { const: 'mission.reply' }, missionId: { type: 'string', format: 'uuid' }, sequence: { type: 'integer' }, text: { type: 'string' }, done: { type: 'boolean' }, createdAt: { type: 'string', format: 'date-time' }, kind: { type: 'string', description: 'Reserved kinds: ask, answer, correct. Unknown kinds are accepted as no-op extensions.' }, defaults: { type: 'string' }, deadline: { type: 'string' }, scope: { type: 'string' }, stop: { type: 'boolean' }, priority: { type: 'string' } } } },
+  events: { 'mission.reply': { type: 'object', required: ['type', 'missionId', 'sequence', 'text', 'done', 'createdAt'], properties: { type: { const: 'mission.reply' }, missionId: { type: 'string', format: 'uuid' }, sequence: { type: 'integer' }, replyTo: { type: 'integer', minimum: 1 }, runId: { type: 'string' }, ptyId: { type: 'string' }, text: { type: 'string' }, done: { type: 'boolean' }, createdAt: { type: 'string', format: 'date-time' }, kind: { type: 'string', description: 'Reserved kinds: ask, answer, correct.' }, defaults: { type: 'string' }, deadline: { type: 'string' }, scope: { type: 'string' }, stop: { type: 'boolean' }, priority: { type: 'string' } } } },
   replyContract: 'Use `eln --config-dir <storeRoot> mission reply --mission <missionId> <text> [--kind ask|answer|correct]` for replies and `eln --config-dir <storeRoot> mission reply --mission <missionId> --done <text>` for the final answer.',
   agentInstructionBlock: [
     'You can send durable progress and final answers to Elanous with `eln mission reply`.',
     'Use `eln --config-dir <storeRoot> mission reply --mission <missionId> "<message>"` for progress/questions.',
-    'Reserved message kinds: ask, answer, correct. Unknown kinds are accepted but have no special behavior.',
+    'Ask for a decision with `--kind ask --defaults <fallback>`; include question and options in the text. An unanswered ask defaults after two minutes. Ask at most three times, then continue with available information or rewrite the task.',
+    'Example: `eln --config-dir <storeRoot> mission reply --mission <missionId> --kind ask --defaults main "Which base should I use? Options: main or release/2.4."` blocks until HandReply or the deadline.',
+    'For a correction, include --scope, --stop, and --priority; corrections require a bound child run and PTY.',
     'Finish with `eln --config-dir <storeRoot> mission reply --mission <missionId> --done "<final answer>"`.',
     'Use `eln --config-dir <storeRoot> mission status <missionId>` to inspect the interaction; do not return output file paths.',
   ].join('\n'),
@@ -436,6 +548,8 @@ export function registerMissionOutCommand(program: Command, deps: {
   write?: (text: string) => void;
   error?: (text: string) => void;
   startWorker?: (root: string, missionId: string) => number;
+  /** Test seam; production resolves the registered current NEXUS endpoint. */
+  resolveNexusUrl?: () => string | null;
 } = {}): Command {
   const write = deps.write ?? ((text) => process.stdout.write(text));
   const error = deps.error ?? ((text) => process.stderr.write(text));
@@ -452,6 +566,26 @@ export function registerMissionOutCommand(program: Command, deps: {
     const missionContext = missionContextForEnv(process.env, missionId);
     return missionContext ? observingStoreAt(missionContext.storeRoot) : storeAt(true);
   };
+  const syncAcceptedLinearReply = async (store: ReturnType<typeof createMissionOutStore>, missionId: string, event: MissionReplyEvent): Promise<void> => {
+    try {
+      const linkedMission = store.read(missionId);
+      if (!linkedMission?.linearLink) return;
+      const latestLine = (): { lineType: string; sequence: number } | undefined => store.replies(missionId)
+        .filter(reply => reply.lineType === 'progress' || reply.lineType === 'final')
+        .sort((a, b) => b.sequence - a.sequence)
+        .map(reply => ({ lineType: reply.lineType!, sequence: reply.sequence }))[0];
+      const missionContext = missionContextForEnv(process.env, missionId);
+      const lockRoot = missionContext?.storeRoot ?? await root();
+      const { syncLinearMissionProgress } = await import('../intake-plane/linear-mission-sync.js');
+      await syncLinearMissionProgress({
+        link: linkedMission.linearLink, lineType: event.lineType, sequence: event.sequence, latestLine: latestLine(),
+      }, { lockRoot, getLatestLine: async () => latestLine() });
+    } catch (error) {
+      debug.log('agent-mission', 'linear-progress-sync-setup-failed', {
+        missionId, error: redactSecretText(String(error)),
+      }, { level: 'warn' });
+    }
+  };
   const out = (opts: { json?: boolean; outputFormat?: string }, value: unknown): void => {
     write(opts.json || opts.outputFormat === 'json' ? `${JSON.stringify(value)}\n` : `${JSON.stringify(value, null, 2)}\n`);
   };
@@ -466,10 +600,11 @@ export function registerMissionOutCommand(program: Command, deps: {
     .option('--prompt <text>', 'Mission prompt')
     .option('--prompt-file <path>', 'Read the prompt from a UTF-8 file')
     .option('--out <path>', 'Internal result file required for fail-closed completion')
+    .option('--linear-issue-id <id>', 'Bind this mission to a verified DEMO subtask')
     .option('--dry-run', 'Resolve and print request without creating a job')
     .option('--json', 'Emit JSON')
     .option('--output-format <format>', 'text or json', 'text')
-    .action(async (opts: { agent?: string; prompt?: string; promptFile?: string; out?: string; dryRun?: boolean; json?: boolean; outputFormat?: string; usage?: boolean }, command: Command) => {
+    .action(async (opts: { agent?: string; prompt?: string; promptFile?: string; out?: string; linearIssueId?: string; dryRun?: boolean; json?: boolean; outputFormat?: string; usage?: boolean }, command: Command) => {
       if (opts.usage || command.optsWithGlobals().usage) { out({ json: true }, missionUsage.commands.run); return; }
       if (!opts.agent) { error('--agent 는 필수입니다\n'); process.exitCode = 2; return; }
       if (!opts.out) { error('--out 은 필수입니다\n'); process.exitCode = 2; return; }
@@ -485,9 +620,29 @@ export function registerMissionOutCommand(program: Command, deps: {
       const store = await storeAt();
       let record: MissionOutRecord | undefined;
       try {
+        const linearLink = opts.linearIssueId
+          ? await (await import('../intake-plane/linear-mission-sync.js')).resolveDemoLinearMissionLink(opts.linearIssueId)
+          : undefined;
         const missionId = randomUUID();
         const outputPath = `${targetOutputPath}.eln-mission-${missionId}.tmp`;
-        record = store.create({ missionId, agent: opts.agent as 'codex' | 'claude', prompt, cwd: process.cwd(), outputPath, targetOutputPath });
+        record = store.create({ missionId, agent: opts.agent as 'codex' | 'claude', prompt, cwd: process.cwd(), outputPath, targetOutputPath, ...(linearLink ? { linearLink } : {}) });
+        // Injected state roots are test fixtures: avoid discovering a global
+        // daemon whose state belongs to another instance. Production callers
+        // use effectiveInstanceRoot and resolve their registered NEXUS here.
+        const candidateNexusUrl = process.env.ELANOUS_NEXUS_URL?.trim() || deps.resolveNexusUrl?.()
+          || (deps.stateRoot ? null : (await import('../nexus/daemon-endpoint.js')).resolveDaemonEndpoint()?.baseUrl);
+        let nexusUrl: string | null = null;
+        if (candidateNexusUrl) {
+          try {
+            const parsed = new URL(candidateNexusUrl);
+            if (parsed.protocol === 'http:' || parsed.protocol === 'https:') nexusUrl = parsed.origin;
+          } catch { /* invalid NEXUS configuration cannot receive a mission token */ }
+        }
+        const handLine = nexusUrl ? createMissionLineStore(await root()).issue({
+          missionId, attemptId: randomUUID(), agent: record.agent,
+          who: record.agent === 'claude' ? 'Claude' : 'Codex',
+          what: prompt.replace(/\s+/g, ' ').trim().slice(0, 180) || 'hand mission',
+        }) : undefined;
         const { mkdirSync } = await import('node:fs');
         mkdirSync(dirname(targetOutputPath), { recursive: true });
         let workerPid: number;
@@ -498,7 +653,7 @@ export function registerMissionOutCommand(program: Command, deps: {
           if (!entry) throw new Error('CLI 엔트리 경로를 확인할 수 없습니다');
           const stateRoot = await root();
           const child = spawn(process.execPath, [entry, 'mission', '__worker', record.missionId], {
-            cwd: record.cwd, detached: true, stdio: 'ignore', env: missionChildEnv(stateRoot, record.missionId),
+            cwd: record.cwd, detached: true, stdio: 'ignore', env: missionChildEnv(stateRoot, record.missionId, process.env, handLine && nexusUrl ? { ...handLine, agent: record.agent, nexusUrl } : undefined),
           });
           if (!child.pid) throw new Error('미션 워커 PID 생성 실패');
           child.unref();
@@ -553,8 +708,9 @@ export function registerMissionOutCommand(program: Command, deps: {
     .option('--scope <text>', 'Correction scope')
     .option('--[no-]stop', 'Correction stop request')
     .option('--priority <value>', 'Correction priority')
+    .option('--reply-to <sequence>', 'Ask sequence being answered/corrected')
     .option('--json', 'Emit JSON').option('--output-format <format>', 'text or json', 'text')
-    .action(async (rawArgs: string[], opts: { mission?: string; done?: boolean; kind?: string; defaults?: string; deadline?: string; scope?: string; stop?: boolean; priority?: string; json?: boolean; outputFormat?: string; usage?: boolean }, command: Command) => {
+    .action(async (rawArgs: string[], opts: { mission?: string; done?: boolean; kind?: string; defaults?: string; deadline?: string; scope?: string; stop?: boolean; priority?: string; replyTo?: string; json?: boolean; outputFormat?: string; usage?: boolean }, command: Command) => {
       if (opts.usage || command.optsWithGlobals().usage) { out({ json: true }, missionUsage.commands.reply); return; }
       const args = [...rawArgs];
       const missionId = opts.mission?.trim() || args.shift();
@@ -562,7 +718,85 @@ export function registerMissionOutCommand(program: Command, deps: {
       let text = args.join(' ');
       if (!text.trim()) text = await (deps.readStdin ?? (async () => (await import('../cli/piped-stdin.js')).readPipedStdin()))();
       try {
-        const event = await (await replyStoreAt(missionId)).reply(missionId, text, opts.done, {
+        if (opts.kind === 'ask' && !opts.defaults?.trim()) throw new Error('reply kind=ask 에는 --defaults 가 필요합니다');
+        const lineToken = process.env.ELANOUS_HAND_TOKEN?.trim();
+        const lineAttemptId = process.env.ELANOUS_HAND_ATTEMPT_ID?.trim();
+        const lineAgent = process.env.ELANOUS_HAND_AGENT === 'claude' ? 'claude' : process.env.ELANOUS_HAND_AGENT === 'codex' ? 'codex' : undefined;
+        if (lineToken && lineAttemptId && lineAgent) {
+          const replyTo = opts.replyTo === undefined ? undefined : Number(opts.replyTo);
+          if (opts.replyTo !== undefined && (!Number.isInteger(replyTo) || (replyTo ?? 0) < 1)) throw new Error('--reply-to 는 양의 정수여야 합니다');
+          if (opts.kind === 'correct' && (!opts.scope || opts.stop === undefined || !opts.priority)) {
+            throw new Error('reply kind=correct 에는 scope, stop, priority 가 필요합니다');
+          }
+          const lineId = randomUUID();
+          const lineType: NonNullable<MissionReplyMessageFields['lineType']> = opts.done
+            ? 'final'
+            : opts.kind === 'ask' || opts.kind === 'answer' || opts.kind === 'correct' ? opts.kind : 'progress';
+          const fields: MissionReplyMessageFields & { lineId: string; attemptId: string; agent: 'codex' | 'claude'; lineType: MissionLineType; source: string } = {
+            lineId,
+            attemptId: lineAttemptId, agent: lineAgent,
+            ...(process.env.ELANOUS_HAND_RUN_ID ? { runId: process.env.ELANOUS_HAND_RUN_ID } : {}),
+            ...(process.env.ELANOUS_HAND_PTY_ID ? { ptyId: process.env.ELANOUS_HAND_PTY_ID } : {}),
+            ...(replyTo ? { replyTo } : {}),
+            lineType,
+            source: 'mission-reply', ...(opts.done ? { state: 'completed' } : {}),
+            ...(opts.kind !== undefined ? { kind: opts.kind } : {}),
+            ...(opts.defaults !== undefined ? { defaults: opts.defaults } : {}),
+            ...(opts.deadline !== undefined ? { deadline: opts.deadline } : {}),
+            ...(opts.scope !== undefined ? { scope: opts.scope } : {}),
+            ...(opts.stop !== undefined ? { stop: opts.stop } : {}),
+            ...(opts.priority !== undefined ? { priority: opts.priority } : {}),
+          };
+          let event: MissionReplyEvent;
+          try {
+            const lineEvent = await postMissionLineEvent({
+              lineId, missionId, attemptId: lineAttemptId, agent: lineAgent,
+              ...(process.env.ELANOUS_HAND_RUN_ID ? { runId: process.env.ELANOUS_HAND_RUN_ID } : {}),
+              ...(process.env.ELANOUS_HAND_PTY_ID ? { ptyId: process.env.ELANOUS_HAND_PTY_ID } : {}),
+              ...(replyTo ? { replyTo } : {}),
+              type: lineType, source: 'mission-reply', text, ...(opts.done ? { state: 'completed' } : {}),
+              ...(opts.kind !== undefined ? { kind: opts.kind } : {}),
+              ...(opts.defaults !== undefined ? { defaults: opts.defaults } : {}),
+              ...(opts.deadline !== undefined ? { deadline: opts.deadline } : {}),
+              ...(opts.scope !== undefined ? { scope: opts.scope } : {}),
+              ...(opts.stop !== undefined ? { stop: opts.stop } : {}),
+              ...(opts.priority !== undefined ? { priority: opts.priority } : {}),
+            });
+            event = {
+              type: 'mission.reply', missionId, sequence: lineEvent.sequence,
+              text: lineEvent.text, done: lineEvent.done, createdAt: lineEvent.createdAt,
+              ...fields,
+              ...(lineEvent.deadline ? { deadline: lineEvent.deadline } : {}),
+            };
+          } catch (error) {
+            if (error instanceof MissionLineHttpError && error.status < 500) throw error;
+            debug.log('agent-mission', 'line-ingress-fallback', { missionId, error: redactSecretText(String(error)) });
+            const replyStore = await replyStoreAt(missionId);
+            const persistedLine = replyStore.replies(missionId).find((reply) => reply.lineId === lineId);
+            if (persistedLine) event = persistedLine;
+            else {
+              const existingReplies = replyStore.replies(missionId);
+              const mission = replyStore.read(missionId);
+              event = await replyStore.reply(missionId, text, opts.done ?? false, {
+                ...fields,
+                ...(existingReplies.length === 0 && mission ? {
+                  who: lineAgent === 'claude' ? 'Claude' : 'Codex',
+                  what: mission.prompt.replace(/\s+/g, ' ').trim().slice(0, 180) || 'hand mission',
+                } : {}),
+              });
+            }
+          }
+          const linkedStore = await replyStoreAt(missionId);
+          await syncAcceptedLinearReply(linkedStore, missionId, event);
+          if (opts.kind === 'ask') {
+            const answerStore = await replyStoreAt(missionId);
+            const answer = await waitForMissionAnswer(answerStore, missionId, event, opts.defaults!);
+            out(opts, { missionId, accepted: true, sequence: event.sequence, done: event.done, answer: answer.text, usedDefault: answer.usedDefault });
+          } else out(opts, { missionId, accepted: true, sequence: event.sequence, done: event.done });
+          return;
+        }
+        const replyStore = await replyStoreAt(missionId);
+        const event = await replyStore.reply(missionId, text, opts.done ?? false, {
           ...(opts.kind !== undefined ? { kind: opts.kind } : {}),
           ...(opts.defaults !== undefined ? { defaults: opts.defaults } : {}),
           ...(opts.deadline !== undefined ? { deadline: opts.deadline } : {}),
@@ -570,7 +804,11 @@ export function registerMissionOutCommand(program: Command, deps: {
           ...(opts.stop !== undefined ? { stop: opts.stop } : {}),
           ...(opts.priority !== undefined ? { priority: opts.priority } : {}),
         });
-        out(opts, { missionId, accepted: true, sequence: event.sequence, done: event.done });
+        await syncAcceptedLinearReply(replyStore, missionId, event);
+        if (opts.kind === 'ask') {
+          const answer = await waitForMissionAnswer(replyStore, missionId, event, opts.defaults!);
+          out(opts, { missionId, accepted: true, sequence: event.sequence, done: event.done, answer: answer.text, usedDefault: answer.usedDefault });
+        } else out(opts, { missionId, accepted: true, sequence: event.sequence, done: event.done });
       } catch (e) { error(`${String(e)}\n`); process.exitCode = 1; }
     });
 

package/src/agent-mission/tool-install.ts

@@ -1,4 +1,4 @@
-import { spawnSync } from 'node:child_process';
+import { spawn, spawnSync, type ChildProcess } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { existsSync, mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -33,20 +33,131 @@ export type AgentCliDetection = {
   agent: AgentCli;
   /** null means the executable/version probe could not establish installation state. */
   installed: boolean | null;
+  /** Sanitized semantic version only; raw CLI output is never exposed. */
+  version?: string;
   executable: 'present' | 'missing' | 'unknown';
   login: 'ready' | 'needed' | 'api-key' | 'unknown';
   message: string;
 };
 
+/** The supported, non-privileged installer for each visible coding CLI. */
+export const AGENT_CLI_INSTALLERS: Record<AgentCli, { command: string; args: string[]; display: string }> = {
+  codex: { command: 'npm', args: ['install', '-g', '@openai/codex@latest'], display: 'npm install -g @openai/codex@latest' },
+  claude: { command: 'npm', args: ['install', '-g', '@anthropic-ai/claude-code'], display: 'npm install -g @anthropic-ai/claude-code' },
+};
+
+export type AgentCliPreparation = {
+  ready: boolean;
+  detection: AgentCliDetection;
+  installation: 'not-needed' | 'declined' | 'installed' | 'failed';
+  message: string;
+};
+
 type AgentCliRunner = (command: string, args: string[], options: {
   encoding: 'utf8'; timeout: number; env: Record<string, string>;
 }) => ReturnType<typeof spawnSync>;
 
-function verifiedAgentVersion(agent: AgentCli, raw: string): boolean {
+export interface AgentCliPreparationDeps {
+  env?: Record<string, string | undefined>;
+  detect?: (agent: AgentCli, options: { env: Record<string, string | undefined>; runCli?: AgentCliRunner }) => AgentCliDetection;
+  runCli?: AgentCliRunner;
+  /** Must be an explicit user confirmation; no installer runs when it is absent or declines. */
+  confirmInstall?: (prompt: string) => boolean | Promise<boolean>;
+  /** Injection seam for tests. Production runs npm only after confirmInstall returns true. */
+  install?: (command: string, args: string[], options: { env: Record<string, string>; timeoutMs: number }) => { status: number | null; error?: { code?: string } | null } | Promise<{ status: number | null; error?: { code?: string } | null }>;
+  onStatus?: (line: string) => void;
+}
+
+function runAgentCliInstaller(command: string, args: string[], options: { env: Record<string, string>; timeoutMs: number }): Promise<{ status: number | null; error?: { code?: string } | null }> {
+  return new Promise((resolve) => {
+    const spawnInstaller = spawn as unknown as (file: string, args: string[], options: { env: Record<string, string>; stdio: 'ignore'; windowsHide: true }) => ChildProcess;
+    const child = spawnInstaller(command, args, { env: options.env, stdio: 'ignore', windowsHide: true });
+    let settled = false;
+    let timedOut = false;
+    let forceKill: ReturnType<typeof setTimeout> | undefined;
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGTERM');
+      forceKill = setTimeout(() => child.kill('SIGKILL'), 2_000);
+    }, options.timeoutMs);
+    const finish = (result: { status: number | null; error?: { code?: string } | null }): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      if (forceKill) clearTimeout(forceKill);
+      resolve(result);
+    };
+    child.once('error', (error: Error & { code?: string }) => finish({ status: null, error }));
+    child.once('close', (status: number | null) => finish(timedOut
+      ? { status: null, error: { code: 'ETIMEDOUT' } }
+      : { status }));
+  });
+}
+
+function agentCliNotReadyMessage(detection: AgentCliDetection): string {
+  if (detection.installed === false) return `${detection.agent}: 설치되지 않음`;
+  if (detection.installed === null) return `${detection.agent}: 설치 상태 확인 불가`;
+  if (detection.login === 'api-key') return `${detection.agent}: API 키 인증은 감지했지만 구독 로그인이 필요합니다. ${detection.agent} login을 실행해 주세요`;
+  if (detection.login === 'needed') return `${detection.agent}: 로그인이 필요합니다. ${detection.agent} login을 실행해 주세요`;
+  return `${detection.agent}: 로그인 상태를 확인할 수 없습니다`;
+}
+
+/** Detect first, ask once before an official install, then re-detect before the caller launches. */
+export async function prepareAgentCli(
+  agent: AgentCli,
+  deps: AgentCliPreparationDeps = {},
+): Promise<AgentCliPreparation> {
+  const env = deps.env ?? process.env;
+  const detect = deps.detect ?? detectAgentCli;
+  const detectOptions = { env, ...(deps.runCli ? { runCli: deps.runCli } : {}) };
+  const installer = AGENT_CLI_INSTALLERS[agent];
+  let detection = detect(agent, detectOptions);
+  deps.onStatus?.(detection.message);
+  if (detection.installed === true && detection.login === 'ready') {
+    return { ready: true, detection, installation: 'not-needed', message: detection.message };
+  }
+  if (detection.installed !== false) {
+    return { ready: false, detection, installation: 'not-needed', message: agentCliNotReadyMessage(detection) };
+  }
+  if (!deps.confirmInstall || !await deps.confirmInstall(`설치할까요? ${installer.display}`)) {
+    return { ready: false, detection, installation: 'declined', message: `${agent}: 설치를 건너뛰었습니다` };
+  }
+
+  const install = deps.install ?? runAgentCliInstaller;
+  let result: { status: number | null; error?: { code?: string } | null };
+  try {
+    const backend = agent === 'codex' ? codexBackend : claudeBackend;
+    result = await install(installer.command, [...installer.args], {
+      env: resolveBackendSpawn(backend, env).env,
+      timeoutMs: 300_000,
+    });
+  } catch {
+    return { ready: false, detection, installation: 'failed', message: `${agent}: 설치 명령을 실행하지 못했습니다` };
+  }
+  if (result.status !== 0) {
+    const detail = result.error?.code === 'ENOENT' ? 'npm을 찾을 수 없습니다' : '설치 명령이 성공하지 않았습니다';
+    return { ready: false, detection, installation: 'failed', message: `${agent}: ${detail}` };
+  }
+
+  detection = detect(agent, detectOptions);
+  deps.onStatus?.(detection.message);
+  if (detection.installed !== true) {
+    return { ready: false, detection, installation: 'failed', message: `${agent}: 설치 뒤 버전 확인에 실패했습니다` };
+  }
+  if (detection.login !== 'ready') {
+    return { ready: false, detection, installation: 'installed', message: agentCliNotReadyMessage(detection) };
+  }
+  return { ready: true, detection, installation: 'installed', message: detection.message };
+}
+
+function agentVersion(agent: AgentCli, raw: string): { version?: string } | undefined {
   const prefix = agent === 'claude' ? /^(?:Claude(?: Code)?\s+)?v?/i : /^(?:Codex(?:-CLI)?\s+)?v?/i;
   const versioned = raw.replace(prefix, '');
-  // Probe output is untrusted: validate its shape but never return any part of it.
-  return /^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?(?: \(Claude Code\))?$/i.test(versioned);
+  // Probe output is untrusted: validate the semver shape but expose only a bounded numeric core.
+  const match = /^(\d+\.\d+\.\d+)(?:[-+][A-Za-z0-9.-]{1,40})?(?: \(Claude Code\))?$/i.exec(versioned);
+  if (!match) return undefined;
+  const parts = match[1]!.split('.');
+  return parts.every((part) => part.length <= 6) ? { version: match[1]! } : undefined;
 }
 
 function agentExecutableExists(command: string, env: Record<string, string>): boolean {
@@ -79,8 +190,8 @@ export function detectAgentCli(
     return { agent, installed: present ? null : false, executable: present ? 'unknown' : 'missing', login: 'unknown', message: present ? `${agent}: 실행 파일을 실행할 수 없어 상태 확인 불가` : `${agent}: 설치되지 않음` };
   }
   const rawVersion = `${versionResult.stdout ?? ''}\n${versionResult.stderr ?? ''}`.trim().split(/\r?\n/, 1)[0] ?? '';
-  const versionVerified = versionResult.status === 0 && verifiedAgentVersion(agent, rawVersion);
-  if (!versionVerified) {
+  const verifiedVersion = versionResult.status === 0 ? agentVersion(agent, rawVersion) : undefined;
+  if (!verifiedVersion) {
     const executable = versionResult.status === null || versionResult.error ? 'unknown' : 'present';
     return {
       agent, installed: null, executable, login: 'unknown',
@@ -103,13 +214,13 @@ export function detectAgentCli(
     } catch { /* Keep authentication unknown when the probe itself fails. */ }
   }
   const message = login === 'ready'
-    ? `${agent}: 설치됨, 로그인 확인됨`
+    ? `${agent}: 설치됨${verifiedVersion.version ? ` v${verifiedVersion.version}` : ''} · 로그인 확인됨`
     : login === 'api-key'
-      ? `${agent}: API 키 로그인됨 (구독 로그인 아님)`
+      ? `${agent}: 설치됨${verifiedVersion.version ? ` v${verifiedVersion.version}` : ''} · API 키 로그인됨 (구독 로그인 아님)`
     : login === 'needed'
-      ? `${agent}: 설치됨, 로그인 필요`
-      : `${agent}: 설치됨, 로그인 상태 확인 불가`;
-  return { agent, installed: true, executable: 'present', login, message };
+      ? `${agent}: 설치됨${verifiedVersion.version ? ` v${verifiedVersion.version}` : ''} · 로그인 필요`
+      : `${agent}: 설치됨${verifiedVersion.version ? ` v${verifiedVersion.version}` : ''} · 로그인 상태 확인 불가`;
+  return { agent, installed: true, ...(verifiedVersion.version ? { version: verifiedVersion.version } : {}), executable: 'present', login, message };
 }
 
 function defaultExec(cmd: string[], opts: { stdin?: string; timeoutMs: number }): ExecResult {

package/src/agents/general-purpose.md

@@ -8,7 +8,7 @@ You are a sub-agent spawned by a parent task. The parent has delegated a focused
 
 ## What you have
 - A task description (the `prompt` argument the parent sent)
-- Full tool access: Bash, Read, Edit, Grep, WebFetch
+- Use the exact tool catalog supplied to this child. Standard CLI defaults are Bash, Read, Edit, Grep, and WebFetch; the TUI may provide a wider policy-filtered catalog.
 - Your own context window — what you read here does not pollute the parent's
 
 ## What you owe back