elanous 0.2.16 → 0.2.18

package/src/cli/self-update.ts

@@ -5,6 +5,10 @@ import { spawnSync } from 'node:child_process';
 import { decideRestartNeeded, type RestartNeededResult } from './nexus-restart-needed.js';
 import { debug } from '../debug/log.js';
 import { envLiteral } from '../platform/env-literal.js';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+import { getUserConfig } from '../user-config.js';
+import { planEdgeRail, type EdgeRailInput, type EdgeRailPlan } from './self-update-canary.js';
+import { loadRunLedger } from '../self-implement/run-ledger.js';
 
 export interface SelfUpdateOptions {
   from?: string;
@@ -22,6 +26,14 @@ export interface SelfUpdateOptions {
   dev?: boolean;
   /** install.json 의 이전 versionDir 로 current 를 되돌린다. 이전이 없으면 거부. */
   rollback?: boolean;
+  /** Canary rollout action; legacy --auto on|off|status is handled by the CLI scheduler. */
+  auto?: boolean;
+  dryRun?: boolean;
+  seat?: string;
+  quietWindow?: boolean;
+  failureRate?: EdgeRailInput['failureRate'];
+  /** Unique ID of an independently successful canary run; no id means no new run. */
+  canaryRunId?: string;
 }
 
 export interface SelfUpdateDeps {
@@ -30,6 +42,8 @@ export interface SelfUpdateDeps {
   decide?: (opts: { to: string; cwd: string; out: { log: (s: string) => void; error: (s: string) => void } }) => Promise<RestartNeededResult>;
   run?: (command: string, args: string[], cwd: string, options?: { timeout?: number }) => { status: number | null; stderr: string; stdout?: string };
   installedVersion?: () => string;
+  /** 캐너리 시작 «뒤»에 시작해 `completed` 로 끝난 런인가(주입 안 하면 런 원장 `canaryRunSucceededInLedger`). */
+  canaryRunSucceeded?: (runId: string, sinceIso: string) => boolean;
   /** 재시작 뒤 데몬이 이 커밋으로 떴나(주입 안 하면 `/v1/health` 를 최대 90초 폴링). */
   verifyRestart?: (expectedCommit: string) => Promise<VerifyRestartResult>;
   /** 판 목록(이름) — 되돌릴 판 찾기. */
@@ -58,6 +72,13 @@ export interface SelfUpdateDeps {
   packageVersion?: (checkout: string) => string;
   /** 재시작을 실제로 호출해도 되는지. NODE_ENV=test · ELANOUS_TEST_HOME 이면 기본 false. */
   allowLiveRestart?: boolean;
+  /** Automatic edge-rail inputs; injected in tests, never a service registration. */
+  now?: () => Date;
+  stateDir?: string;
+  edgeRailConfig?: () => Pick<EdgeRailInput, 'canaryOkRuns' | 'failureMultiplier' | 'minSamples'>;
+  installEdgeRail?: (options: SelfUpdateOptions, deps: SelfUpdateDeps) => Promise<SelfUpdateResult>;
+  rollbackEdgeRail?: (deps: Pick<SelfUpdateDeps, 'installRoot'>) => ReturnType<typeof rollbackDevInstall>;
+  restartEdgeRail?: () => Promise<boolean>;
 }
 
 export interface SelfUpdateResult {
@@ -87,6 +108,10 @@ export interface SelfUpdateResult {
   relay?: RelayUpdateOutcome;
   /** 텔레그램 러너(`com.elanous.telegram` · `elanous-telegram.service`) 판정 — 🆕 2026-09-25. */
   telegramRunner?: RelayUpdateOutcome;
+  edgeRail?: EdgeRailPlan;
+  missingFixes?: string;
+  /** 실패율 측정 원천이 없으면 자동 되돌림이 판단되지 않는다 — 측정 원천은 다음 조각(EDGE-RAIL2 범위 밖). */
+  autoRollback?: 'active' | 'inactive-no-failure-rate';
 }
 
 export interface RelayUpdateOutcome {
@@ -628,12 +653,186 @@ function readInstallSource(cliRoot: string, exists: (path: string) => boolean, r
   }
 }
 
+/** Output only; never uses a title to decide whether to install. */
+export function missingFixCommitTitles(checkout: string, installed: string, main: string, git: NonNullable<SelfUpdateDeps['git']>): string {
+  if (!/^[a-f0-9]{12,40}$/i.test(installed) || !/^[a-f0-9]{12,40}$/i.test(main)) return 'main 엔 있고 운영엔 없는 수리: 판정 불가';
+  const result = git(checkout, ['log', '--format=%s', '--no-merges', `${installed}..${main}`]);
+  if (result.status !== 0) return 'main 엔 있고 운영엔 없는 수리: 판정 불가';
+  const titles = result.stdout.split(/\r?\n/).map((line) => line.trim()).filter((line) => /\bfix(?:es|ed)?\b|(?:^|[(:])fix[:)]/i.test(line))
+    .map((line) => line.replace(/[\r\n\t]+/g, ' ').slice(0, 160)).slice(0, 10);
+  return `main 엔 있고 운영엔 없는 수리: ${titles.length ? titles.join(' · ') : '없음'}`;
+}
+
+interface EdgeRailState { canary: NonNullable<EdgeRailInput['canary']>; mainCommit: string; lastRunId?: string; countedRunIds?: string[]; failureRate?: NonNullable<EdgeRailInput['failureRate']>; promoted?: boolean; rolledBack?: boolean }
+
+function saveEdgeRailState(file: string, state: EdgeRailState): void {
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
+  renameSync(tmp, file);
+}
+
+/** 런 원장에서: `start` 가 캐너리 시작 이후이고 마지막 `run-status` 가 `completed` 인 런만 참. 못 읽으면 거짓. */
+export function canaryRunSucceededInLedger(runId: string, sinceIso: string, dir?: string): boolean {
+  try {
+    const entries = (dir ? loadRunLedger(runId, dir) : loadRunLedger(runId)) ?? [];
+    const started = Date.parse(entries.find((entry) => entry.event === 'start')?.timestamp ?? '');
+    const last = entries.filter((entry) => entry.event === 'run-status').at(-1);
+    return Number.isFinite(started) && started >= Date.parse(sinceIso) && last?.data.runStatus === 'completed';
+  } catch { return false; }
+}
+
+async function restartEdgeRail(deps: SelfUpdateDeps, checkout: string): Promise<boolean> {
+  if (deps.restartEdgeRail) return deps.restartEdgeRail();
+  if (deps.allowLiveRestart === false || (deps.allowLiveRestart !== true && liveRestartBlocked())) return false;
+  const os = deps.os ?? platform();
+  const command = os === 'darwin' ? 'launchctl' : os === 'linux' ? 'systemctl' : null;
+  if (!command) return false;
+  const args = os === 'darwin' ? ['kickstart', '-k', `gui/${deps.uid ?? process.getuid?.() ?? userInfo().uid}/com.elanous.nexus`] : ['--user', 'restart', 'elanous-nexus'];
+  return (deps.run ?? execute)(command, args, checkout).status === 0;
+}
+
+export async function runEdgeRailUpdate(options: SelfUpdateOptions, deps: SelfUpdateDeps = {}): Promise<SelfUpdateResult> {
+  const out = deps.out ?? console;
+  const root = deps.installRoot ?? defaultInstallRoot();
+  const record = readInstallRecord(root);
+  const checkout = resolve(options.from ?? record?.source ?? deps.cliRoot ?? resolve(import.meta.dir, '../..'));
+  const stateFile = join(deps.stateDir ?? elanousStateRoot(), 'self-update-edge-rail.json');
+  const git = deps.git ?? ((cwd: string, args: string[]) => execute('git', args, cwd));
+  const fail = (reason: string): SelfUpdateResult => {
+    const result: SelfUpdateResult = { exitCode: 2, installedVersion: null, decision: null, restarted: false, reason };
+    out.log(options.json ? JSON.stringify(result) : `self-update --auto: hold — ${reason}`);
+    return result;
+  };
+  if (options.dev || options.rollback || options.version || options.restart) return fail('--auto cannot combine with --dev, --rollback, --version or --restart');
+  if (options.seat !== 'OP' && options.seat !== 'TC' && options.seat !== 'MK' && options.seat !== 'UX') return fail('--auto requires a known --seat (OP|TC|MK|UX)');
+  if (!record?.commit) return fail('installed commit unknown');
+  const currentName = versionDirName(record.versionDir);
+  if (!currentName || !installEntryExists(root, currentName)) return fail('installed entry missing');
+  try {
+    if (readlinkSync(join(root, 'current')) !== record.versionDir) return fail('current does not match installed record');
+  } catch { return fail('current is not a version link'); }
+  if (!options.from && (!record.source || /^(?:https?:|file:)/.test(record.source))) return fail('local checkout source unknown — use --from');
+  if (!existsSync(join(checkout, 'scripts', 'install.sh'))) return fail('checkout installer missing');
+  const verifiedRoot = git(checkout, ['rev-parse', '--show-toplevel']);
+  try {
+    if (verifiedRoot.status !== 0 || !verifiedRoot.stdout.trim() || realpathSync(verifiedRoot.stdout.trim()) !== realpathSync(checkout)) return fail('checkout git root mismatch');
+  } catch { return fail('checkout git root mismatch'); }
+  const head = git(checkout, ['rev-parse', '--verify', 'main']);
+  if (head.status !== 0 || !/^[a-f0-9]{12,40}$/i.test(head.stdout.trim())) return fail('main commit unknown');
+  if (!options.dryRun) {
+    const tracked = git(checkout, ['diff', '--quiet', 'HEAD', '--']);
+    const working = git(checkout, ['rev-parse', '--verify', 'HEAD']);
+    if (tracked.status !== 0 || working.status !== 0 || working.stdout.trim() !== head.stdout.trim()) return fail('main is not the clean checkout HEAD');
+    const untracked = git(checkout, ['ls-files', '--others', '--exclude-standard']);
+    if (untracked.status !== 0 || untracked.stdout.trim()) return fail('checkout contains untracked files');
+  }
+  let state: EdgeRailState | null = null;
+  if (existsSync(stateFile)) {
+    try {
+      const value: unknown = JSON.parse(readFileSync(stateFile, 'utf8'));
+      if (value && typeof value === 'object' && 'canary' in value && 'mainCommit' in value) state = value as EdgeRailState;
+      else return fail('invalid edge-rail state');
+    } catch { return fail('invalid edge-rail state'); }
+  }
+  const mainCommit = head.stdout.trim();
+  const config = deps.edgeRailConfig?.() ?? getUserConfig().harness?.edgeRail ?? {};
+  const canary = state?.mainCommit === mainCommit ? state.canary : null;
+  const observed = (deps.now ?? (() => new Date()))();
+  if (!options.dryRun && canary && canary.okRuns < (config.canaryOkRuns ?? 3) && options.seat === 'OP' && (record.commit.startsWith(mainCommit) || mainCommit.startsWith(record.commit))
+    && !options.failureRate && options.canaryRunId?.trim() && options.canaryRunId !== state?.lastRunId
+    // 같은 런을 두 번 세지 않고, 캐너리 시작 뒤 «성공으로 끝난» 런만 센다(임의·과거·실패 id 로 승격을 열지 못하게).
+    && !(state?.countedRunIds ?? []).includes(options.canaryRunId.trim())
+    && (deps.canaryRunSucceeded ?? canaryRunSucceededInLedger)(options.canaryRunId.trim(), canary.startedAt)
+    && Number.isFinite(observed.getTime()) && observed.getTime() >= Date.parse(canary.startedAt)) {
+    const health = await (deps.verifyRestart ?? defaultVerifyRestart)(mainCommit);
+    if (health.ok && health.daemonSha && (health.daemonSha.startsWith(mainCommit) || mainCommit.startsWith(health.daemonSha)) && state) {
+      state = { ...state, canary: { ...canary, okRuns: canary.okRuns + 1 }, lastRunId: options.canaryRunId, countedRunIds: [...(state.countedRunIds ?? []), options.canaryRunId.trim()] };
+      saveEdgeRailState(stateFile, state);
+    }
+  }
+  const input: EdgeRailInput = {
+    // 설정에서는 세 수치만 받는다 — 여분 키가 판단 입력(seat·failureRate·canary…)을 덮지 못하게.
+    ...(config.canaryOkRuns !== undefined ? { canaryOkRuns: config.canaryOkRuns } : {}),
+    ...(config.failureMultiplier !== undefined ? { failureMultiplier: config.failureMultiplier } : {}),
+    ...(config.minSamples !== undefined ? { minSamples: config.minSamples } : {}),
+    now: observed, mainCommit, installed: record.commit, seat: options.seat,
+    canary: state?.mainCommit === mainCommit ? state.canary : null,
+    failureRate: options.failureRate ?? (state?.mainCommit === mainCommit ? state.failureRate : null) ?? null,
+    quietWindow: options.quietWindow === true, promoted: state?.mainCommit === mainCommit ? state.promoted : false,
+  };
+  // 이 main 은 이미 되돌렸다 — 새 main 이 올 때까지 다시 깔거나 승격하지 않는다.
+  const plan = state?.mainCommit === mainCommit && state.rolledBack
+    ? { decision: 'hold' as const, reason: 'this main was rolled back; waiting for a new main' }
+    : planEdgeRail(input);
+  const fixes = missingFixCommitTitles(checkout, record.commit, mainCommit, git);
+  if (!options.dryRun) try { debug.log('self-update.edge-rail', 'plan', { decision: plan.decision, reason: plan.reason, seat: options.seat, mainCommit, installed: record.commit, fixes }); } catch { /* log sink optional */ }
+  const emit = (result: SelfUpdateResult): SelfUpdateResult => {
+    const autoRollback = input.failureRate ? 'active' as const : 'inactive-no-failure-rate' as const;
+    const merged = { ...result, edgeRail: plan, missingFixes: fixes, autoRollback };
+    out.log(options.json ? JSON.stringify(merged) : `self-update --auto: ${plan.decision} — ${plan.reason} · ${fixes}${autoRollback === 'active' ? '' : ' · 자동 되돌림 비활성 — 실패율 측정 원천 없음'}`);
+    return merged;
+  };
+  if (options.dryRun || plan.decision === 'hold' || plan.decision === 'wait-quiet') return emit({ exitCode: 0, installedVersion: null, decision: null, restarted: false, reason: plan.reason });
+  if (plan.decision === 'rollback' && (!record.previous || !versionDirName(record.previous))) return emit({ exitCode: 2, installedVersion: null, decision: null, restarted: false, reason: 'no previous version for rollback' });
+  if (plan.decision === 'rollback' && !deps.restartEdgeRail && liveRestartBlocked()) return emit({ exitCode: 2, installedVersion: null, decision: null, restarted: false, reason: 'live restart blocked' });
+  if (plan.decision === 'rollback') {
+    const rolled = (deps.rollbackEdgeRail ?? rollbackDevInstall)(deps);
+    if (!rolled.ok) return emit({ exitCode: 2, installedVersion: null, decision: null, restarted: false, reason: rolled.reason });
+    // 되돌린 main 은 표시해 둔다 — 캐너리 OK 수가 남아 있어도 다음 실행이 다시 승격하지 못하게.
+    if (state?.mainCommit === mainCommit) saveEdgeRailState(stateFile, { ...state, promoted: false, rolledBack: true });
+    else saveEdgeRailState(stateFile, { mainCommit, canary: { seat: 'OP', okRuns: 0, startedAt: input.now.toISOString() }, rolledBack: true });
+    const restarted = await restartEdgeRail(deps, checkout);
+    const health = restarted ? await (deps.verifyRestart ?? defaultVerifyRestart)(rolled.record.commit ?? '') : null;
+    const confirmed = !!(health?.ok && health.daemonSha && rolled.record.commit
+      && (health.daemonSha.startsWith(rolled.record.commit) || rolled.record.commit.startsWith(health.daemonSha)));
+    return emit({ exitCode: confirmed ? 0 : 1, installedVersion: rolled.versionName, decision: null, restarted, current: `versions/${rolled.versionName}`, reason: confirmed ? plan.reason : `${plan.reason}; rollback health not confirmed` });
+  }
+  if (!deps.restartEdgeRail && liveRestartBlocked()) return emit({ exitCode: 2, installedVersion: null, decision: null, restarted: false, reason: 'live restart blocked' });
+  const installer = deps.installEdgeRail ?? ((next: SelfUpdateOptions, injected: SelfUpdateDeps) => runUpdateForInstallation(next, { cliRoot: injected.cliRoot, checkout: injected }));
+  // The existing --from dev installer checks entry existence and restores current even when install.sh fails after relinking.
+  const installed = await installer({ from: checkout, dev: true, restart: false }, { ...deps, notice: () => {}, out: { log: () => {}, error: () => {} } });
+  if (installed.exitCode !== 0) return emit(installed);
+  const nextRecord = readInstallRecord(root);
+  const nextName = versionDirName(nextRecord?.versionDir);
+  let currentLink = '';
+  try { currentLink = readlinkSync(join(root, 'current')); } catch { /* no valid installed current */ }
+  if (!nextName || !installEntryExists(root, nextName) || nextRecord?.commit !== mainCommit || currentLink !== nextRecord.versionDir) {
+    const rolled = record.versionDir && nextRecord?.previous === record.versionDir ? (deps.rollbackEdgeRail ?? rollbackDevInstall)(deps) : null;
+    return emit({ ...installed, exitCode: 1, reason: `installed entry/commit not confirmed${rolled?.ok ? '; previous build restored' : '; rollback not confirmed'}` });
+  }
+  const restarted = await restartEdgeRail(deps, checkout);
+  // 설치한 판이 재시작·건강에서 실패해 되돌렸으면 같은 main 을 다시 깔지 않게 표시한다.
+  const markRolledBack = (): void => saveEdgeRailState(stateFile, { mainCommit, canary: { seat: 'OP', okRuns: 0, startedAt: input.now.toISOString() }, rolledBack: true });
+  if (!restarted) {
+    const rolled = record.versionDir && readInstallRecord(root)?.previous === record.versionDir
+      ? (deps.rollbackEdgeRail ?? rollbackDevInstall)(deps) : null;
+    if (rolled?.ok) markRolledBack();
+    return emit({ ...installed, exitCode: 1, restarted: false, reason: `${plan.reason}; restart not confirmed${rolled?.ok ? '; previous build restored' : '; rollback not confirmed'}` });
+  }
+  const verified = await (deps.verifyRestart ?? defaultVerifyRestart)(mainCommit);
+  if (!verified.ok || !verified.daemonSha || !(verified.daemonSha.startsWith(mainCommit) || mainCommit.startsWith(verified.daemonSha))) {
+    const rolled = record.versionDir && readInstallRecord(root)?.previous === record.versionDir
+      ? (deps.rollbackEdgeRail ?? rollbackDevInstall)(deps) : null;
+    if (rolled?.ok) { markRolledBack(); await restartEdgeRail(deps, checkout); }
+    return emit({ ...installed, exitCode: 1, restarted: true, reason: `${plan.reason}; restarted build health not confirmed${rolled?.ok ? '; previous build restored' : '; rollback not confirmed'}` });
+  }
+  if (plan.decision === 'canary-install') {
+    const next: EdgeRailState = { mainCommit, canary: { seat: 'OP', okRuns: 0, startedAt: input.now.toISOString() }, ...(options.failureRate ? { failureRate: options.failureRate } : {}) };
+    saveEdgeRailState(stateFile, next);
+  } else if (state?.mainCommit === mainCommit && plan.decision === 'promote-all') {
+    saveEdgeRailState(stateFile, { ...state, promoted: true });
+  }
+  return emit({ ...installed, restarted: true });
+}
+
 /** Route an installed CLI by where it was installed from: a release URL → release installer, a local checkout → git update. */
 export async function runUpdateForInstallation(
   options: SelfUpdateOptions = {},
   deps: { cliRoot?: string; exists?: (path: string) => boolean; readText?: (path: string) => string; release?: ReleaseUpdateDeps; checkout?: SelfUpdateDeps } = {},
 ): Promise<SelfUpdateResult> {
   const cliRoot = resolve(deps.cliRoot ?? resolve(import.meta.dir, '../..'));
+  if (options.auto) return runEdgeRailUpdate(options, { cliRoot, ...deps.checkout });
   const exists = deps.exists ?? existsSync;
   const holder = resolve(cliRoot, '..', '..');
   const parent = resolve(holder, '..');
@@ -726,7 +925,7 @@ export async function runSelfUpdate(options: SelfUpdateOptions = {}, deps: SelfU
 
     if (options.dev) {
       try {
-        const installed = installDevBuild(checkout, head.stdout.trim(), { ...deps, runInstaller: () => run('bash', [join(checkout, 'scripts/install.sh'), '--no-modify-path'], checkout) });
+        const installed = installDevBuild(checkout, head.stdout.trim(), { ...deps, runInstaller: () => run('bash', [join(checkout, 'scripts/install.sh'), '--no-modify-path', ...(deps.installRoot ? ['--prefix', deps.installRoot] : [])], checkout) });
         return emit({
           exitCode: 0,
           installedVersion: installed.versionName,

package/src/cli/tasks-cli.ts

@@ -1,9 +1,12 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import type { Command } from 'commander';
+import { InvalidArgumentError, Option, type Command } from 'commander';
+import { debug } from '../debug/log.js';
 import { getElanousConfigDir } from '../elanous-config-dir.js';
 import { readNexusRuntime } from '../nexus/runtime.js';
 import type { Task } from '../task-orchestrator/types.js';
+import { handTask, nextMoveFor, readTaskAgentState, readTaskCard, taskAgentStatePath as taskStatePathDefault, shellQuote, TASK_CARD_PREFIX, TASK_SEATS, type TaskCard, type TaskLauncher, type TaskSeat } from '../task-agent/task-hand.js';
+import { advanceMission, handMission, MissionAdvanceError, openMissionIds, recordPieceRef, type AdvanceMissionResult, type MissionDecompose, type PieceEvidenceReader } from '../task-agent/mission.js';
 
 type TaskRow = Pick<Task, 'id' | 'title' | 'priority' | 'status' | 'createdAt' | 'approval' | 'generatedBy'>;
 
@@ -12,6 +15,130 @@ export interface TasksCliDeps {
   bearerToken?: string;
   fetch?: typeof fetch;
   output?: (line: string) => void;
+  /** `task hand --live` 의 발사기(시험 주입). 기본은 운영 config-dir 로 `harness say` 를 떼어 띄운다. */
+  taskLauncher?: TaskLauncher;
+  /** 과제 카드 상태 파일(시험 주입). 기본 = `effectiveInstanceRoot()/task-agent-actions.json`. */
+  taskStatePath?: string;
+  /** logs.db 싱크 등록(시험 주입). 기본 = `registerStandaloneLogSink`. `hand`·`show` 가 부른다. */
+  registerSink?: (surface: string) => Promise<unknown>;
+  /** `task hand --mission` 의 분해기(시험 주입). 기본 = 나열형은 결정론 · 아니면 `decomposeSelfDevGoal`. */
+  missionDecompose?: MissionDecompose;
+  /** `task advance` 의 착지 근거 읽기(시험 주입). 기본 = `predecessorState`(gh · 런 원장). */
+  pieceEvidence?: PieceEvidenceReader;
+}
+
+/** `<조각id>=<값>` 반복 인자. */
+function collectPair(value: string, previous: Array<[string, string]> = []): Array<[string, string]> {
+  const at = value.indexOf('=');
+  if (at <= 0 || at === value.length - 1) throw new InvalidArgumentError(`<조각id>=<값> 모양이 아니다: ${value}`);
+  return [...previous, [value.slice(0, at), value.slice(at + 1)]];
+}
+
+function advanceLines(result: AdvanceMissionResult): string[] {
+  // 제안이 끝난 미션은 다시 조회하지 않는다 — «착지 0»으로 보이지 않게 따로 적는다.
+  if (result.green === 'already-proposed' && Object.keys(result.evidence).length === 0) return [`${result.missionId}\tadvance\t${result.mode}\tgreen already-proposed — 다시 조회·넘기지 않는다`];
+  return [
+    `${result.missionId}\tadvance\t${result.mode}\t착지 ${result.landed.length} · 준비 ${result.ready.length} · 넘김 ${result.handed.length} · green ${result.green}`,
+    ...Object.entries(result.evidence).map(([id, state]) => `  근거: ${id}\t${state}${result.landed.includes(id) ? '\t착지' : ''}`),
+    ...result.handed.map((piece) => `  넘김: ${piece.pieceId}\t${piece.launched ? 'launched' : piece.error ? 'failed' : 'not launched'}${piece.error ? `\t${piece.error}` : ''}`),
+    ...(result.green === 'proposed' ? ['  green 제안을 미션 카드에 적었다 — 체크리스트는 바꾸지 않는다(OP/주인이 뒤집는다)'] : []),
+  ];
+}
+
+/** `tasks hand`·`show` 가 남기는 `task-agent` 관측의 logs.db surface 라벨. */
+export const TASK_AGENT_SINK_SURFACE = 'task-agent';
+
+/**
+ * 독립 CLI 프로세스는 데몬의 logs.db 싱크를 상속하지 않는다 — 등록하지 않으면 `debug.log('task-agent', …)` 가
+ * 파일 트레일에만 남고 `elanous logs --category task-agent` 에 0건으로 보인다(10-06 실측: 카드 3장 · 이벤트 0).
+ * fail-open — 등록 실패가 과제 넘기기를 막지 않는다.
+ */
+export async function registerTaskAgentSink(register?: (surface: string) => Promise<unknown>): Promise<void> {
+  try {
+    const fn = register ?? (await import('../domains/standalone-log-sink.js')).registerStandaloneLogSink;
+    await fn(TASK_AGENT_SINK_SURFACE);
+  } catch { /* fail-open — 파일 트레일이 진실원 */ }
+}
+
+/**
+ * 기본 발사기 — 지금 도는 진입점으로 `--config-dir <운영 config>` 를 붙여 떼어 띄운다.
+ * config-dir 은 명시(`--config-dir`/`--test`)가 있으면 그것, 없으면 운영 루트(`prodInstanceRoot()`)다.
+ * (작업 트리에서 그냥 띄우면 test 우주로 가서 동결·몫·풀 상한 밖에서 돈다.)
+ */
+export async function defaultTaskLauncher(args: string[]): Promise<void> {
+  const { spawn } = await import('node:child_process');
+  const { getElanousConfigDirOverride } = await import('../elanous-config-dir.js');
+  const { prodInstanceRoot } = await import('../instance/resolve.js');
+  const configDir = getElanousConfigDirOverride() ?? prodInstanceRoot();
+  await spawnDetachedConfirmed(spawn as unknown as DetachedSpawn, process.execPath, [process.argv[1]!, '--config-dir', configDir, ...args]);
+}
+
+/** `spawn` 의 필요한 면만(시험 주입). */
+export type DetachedSpawn = (command: string, args: string[], options: { detached: true; stdio: 'ignore' }) => {
+  pid?: number;
+  once(event: 'spawn', listener: () => void): unknown;
+  once(event: 'error', listener: (error: Error) => void): unknown;
+  removeListener(event: string, listener: (...args: never[]) => void): unknown;
+  unref(): void;
+};
+
+/** 발사 확인 대기 상한 — 'spawn'·'error' 어느 쪽도 이 안에 안 오면 pid 유무로 판정한다. */
+export const SPAWN_CONFIRM_TIMEOUT_MS = 2_000;
+
+/**
+ * 떼어 띄우고 «떴는지» 확인한다 — 'spawn' 이면 성공, 'error'(ENOENT·EACCES 등)면 던진다.
+ * 확인 없이 돌려주면 비동기 error 가 처리되지 않고 카드가 `launched` 로 남는다(사후 리뷰 must-fix).
+ */
+export function spawnDetachedConfirmed(spawnFn: DetachedSpawn, command: string, args: string[], timeoutMs = SPAWN_CONFIRM_TIMEOUT_MS): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    let child: ReturnType<DetachedSpawn>;
+    try { child = spawnFn(command, args, { detached: true, stdio: 'ignore' }); } catch (error) { reject(error); return; }
+    let settled = false;
+    const finish = (error?: Error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.removeListener('spawn', onSpawn);
+      // error 리스너는 남겨 둔다 — 확인 뒤 늦게 오는 error 도 처리되지 않은 예외가 되지 않게.
+      if (error) { reject(error); return; }
+      child.unref();
+      resolve();
+    };
+    const onSpawn = () => finish();
+    const onError = (error: Error) => finish(error);
+    child.once('spawn', onSpawn);
+    child.once('error', onError);
+    const timer = setTimeout(() => finish(child.pid ? undefined : new Error(`발사 확인 시간 초과(${timeoutMs}ms) · pid 없음`)), timeoutMs);
+  });
+}
+
+function moveLine(card: TaskCard): string {
+  const move = nextMoveFor(card);
+  return `${move.kind}${move.command ? ` — elanous ${move.command.map(shellQuote).join(' ')}` : ''} (${move.reason})`;
+}
+
+function headLine(text: string): string {
+  const first = text.split('\n')[0]!.trim();
+  return first.length > 100 ? `${first.slice(0, 100)}…` : first;
+}
+
+function taskCardLines(card: TaskCard): string[] {
+  return [
+    [card.id, card.status, card.seat ?? '-', card.checklistId ?? '-', card.createdAt, card.text].join('\t'),
+    ...(card.mission ? [`미션: ${card.mission} · after: ${card.after?.length ? card.after.join(', ') : '-'}`] : []),
+    `다음 수: ${moveLine(card)}`,
+  ];
+}
+
+/** 미션 카드 — 머리 한 줄 ⊕ 조각 한 줄씩(상태·다음 수·선행) ⊕ 간선 한 줄씩. */
+function missionLines(mission: TaskCard, pieces: TaskCard[]): string[] {
+  const edges = pieces.flatMap((piece) => (piece.after ?? []).map((before) => `간선: ${before} -> ${piece.id}`));
+  return [
+    [mission.id, 'mission', mission.seat ?? '-', mission.checklistId ?? '-', mission.createdAt, `조각 ${pieces.length} · 간선 ${edges.length} · 출처 ${mission.splitSource ?? '-'}`, headLine(mission.text)].join('\t'),
+    ...pieces.map((piece) => [`조각: ${piece.id}`, piece.status, nextMoveFor(piece).kind, `after: ${piece.after?.length ? piece.after.join(',') : '-'}`, headLine(piece.text)].join('\t')),
+    ...edges,
+    ...(mission.greenProposal ? [`green 제안: ${mission.greenProposal.at} · 칸 ${mission.greenProposal.checklistId ?? '-'} · 근거 ${Object.entries(mission.greenProposal.evidence).map(([id, ref]) => `${id}=${ref}`).join(', ')}`] : []),
+  ];
 }
 
 const PRIORITY_RANK: Record<Task['priority'], number> = { urgent: 0, high: 1, medium: 2, low: 3 };
@@ -89,7 +216,7 @@ export function registerTasksCommands(program: Command, deps: TasksCliDeps = {})
     if (!auth) throw new NexusUnavailable();
     return auth;
   };
-  const tasks = program.command('tasks').alias('task').description('TOX 태스크 조회 및 승인');
+  const tasks = program.command('tasks').alias('task').description('TOX 태스크 조회 및 승인 · TASK-AGENT 과제 넘기기(hand)');
 
   tasks.command('list')
     .description('우선순위와 생성 시각 순으로 태스크 보기')
@@ -124,10 +251,189 @@ export function registerTasksCommands(program: Command, deps: TasksCliDeps = {})
       } catch (error) { handleError(error, out); }
     });
 
+  tasks.command('hand [text]')
+    .description('TASK-AGENT 에 과제 한 줄을 넘긴다 — 카드를 적고 첫 수(harness say --substrate pod --merge-by-host)를 고른다 · 기본 shadow(발사 0) · `--mission` 이면 조각 카드 ⊕ 선후로 쪼개 선행 없는 조각만 넘긴다')
+    .addOption(new Option('--seat <seat>', `과제 자리 (${TASK_SEATS.join('|')})`).choices([...TASK_SEATS]))
+    .option('--checklist <cellId>', '릴리스 체크리스트 칸 id')
+    .option('--mission <text>', '미션 문면 — 조각(`- …`·`① …`·`1. …` ⊕ `after: 1`)으로 나열돼 있으면 결정론, 아니면 분해기로 쪼갠다')
+    .option('--live', '실제로 발사한다(기본은 shadow — 명령만 출력)')
+    .option('--json', 'JSON 출력')
+    .action(async (text: string | undefined, opts: { seat?: TaskSeat; checklist?: string; mission?: string; live?: boolean; json?: boolean }) => {
+      await registerTaskAgentSink(deps.registerSink);
+      if ((text === undefined) === (opts.mission === undefined)) {
+        out('과제 한 줄 «또는» --mission <문면> 중 하나만 준다');
+        process.exitCode = 1;
+        return;
+      }
+      if (opts.mission !== undefined) {
+        try {
+          const result = await handMission({
+            text: opts.mission,
+            ...(opts.seat ? { seat: opts.seat } : {}),
+            ...(opts.checklist ? { checklistId: opts.checklist } : {}),
+            live: opts.live === true,
+            ...(deps.taskStatePath ? { statePath: deps.taskStatePath } : {}),
+            launcher: deps.taskLauncher ?? defaultTaskLauncher,
+            ...(deps.missionDecompose ? { decompose: deps.missionDecompose } : {}),
+          });
+          if (opts.json) out(JSON.stringify(result));
+          else {
+            out(`${result.mission.id}\tmission\t${result.mode}\t조각 ${result.pieces.length} · 간선 ${result.edges.length} · 출처 ${result.source}`);
+            for (const piece of result.pieces) {
+              out([piece.card.id, piece.launched ? 'launched' : piece.error ? 'failed' : 'not launched', `${piece.move.kind} (${piece.move.reason})`, headLine(piece.card.text)].join('\t'));
+              if (piece.move.command) out(`  elanous ${piece.move.command.map(shellQuote).join(' ')}`);
+              if (piece.error) out(`  ${piece.error}`);
+            }
+            for (const [before, after] of result.edges) out(`간선: ${before} -> ${after}`);
+            if (result.mode === 'shadow') out('(shadow — 띄우지 않았다 · 띄우려면 --live)');
+          }
+          if (result.pieces.some((piece) => piece.error)) process.exitCode = 1;
+        } catch (error) {
+          out(error instanceof Error ? error.message : '미션 넘기기 실패');
+          process.exitCode = 1;
+        }
+        return;
+      }
+      try {
+        const result = await handTask({
+          text: text!,
+          ...(opts.seat ? { seat: opts.seat } : {}),
+          ...(opts.checklist ? { checklistId: opts.checklist } : {}),
+          live: opts.live === true,
+          ...(deps.taskStatePath ? { statePath: deps.taskStatePath } : {}),
+          launcher: deps.taskLauncher ?? defaultTaskLauncher,
+        });
+        if (opts.json) out(JSON.stringify(result));
+        else {
+          out(`${result.card.id}\t${result.mode}\t${result.launched ? 'launched' : 'not launched'}`);
+          out(`elanous ${result.move.command!.map(shellQuote).join(' ')}`);
+          if (!result.launched) out('(shadow — 띄우지 않았다 · 띄우려면 --live)');
+        }
+      } catch (error) {
+        out(error instanceof Error ? error.message : '과제 넘기기 실패');
+        process.exitCode = 1;
+      }
+    });
+
+  tasks.command('advance [missionId]')
+    .description('TASK-AGENT 미션 ② — 조각의 PR 병합(근거: `--pr`/`--goal` 로 카드에 적은 PR 번호·골 id)으로 착지를 가르고 새로 준비된 조각만 한 번 넘긴다 · 모두 착지면 green «제안»만 적는다 · 기본 shadow(발사 0)')
+    .option('--all', 'green 제안이 아직 없는 미션 전부')
+    .option('--pr <pieceId=N>', '조각 카드에 그 런의 PR 번호를 적는다(반복 가능)', collectPair)
+    .option('--goal <pieceId=goalId>', '조각 카드에 골 id(16자)를 적는다 — 런 원장 pr-opened 로 PR 을 찾는다(반복 가능)', collectPair)
+    .option('--live', '준비된 조각을 실제로 발사한다(기본은 shadow)')
+    .option('--json', 'JSON 출력')
+    .action(async (missionId: string | undefined, opts: { all?: boolean; pr?: Array<[string, string]>; goal?: Array<[string, string]>; live?: boolean; json?: boolean }) => {
+      await registerTaskAgentSink(deps.registerSink);
+      const started = Date.now();
+      if ((missionId === undefined) === (opts.all !== true)) {
+        const reason = '미션 id «또는» --all 중 하나만 준다';
+        try { debug.log('task-agent', 'mission-advance', { missionId: missionId ?? null, all: opts.all === true, mode: opts.live ? 'live' : 'shadow', stage: 'cli-args', error: reason, ms: Date.now() - started }); } catch { /* fail-soft */ }
+        out(reason);
+        process.exitCode = 1;
+        return;
+      }
+      const statePath = deps.taskStatePath;
+      try {
+        // 근거 인자는 운영자 입력이다 — 모양을 «먼저» 전부 검사해 하나라도 틀리면 아무것도 적지 않고 진행도 안 한다.
+        const refs: Array<[string, { pr: number } | { goalId: string }]> = [
+          ...(opts.pr ?? []).map(([pieceId, value]): [string, { pr: number }] => {
+            if (!/^#?[1-9]\d*$/.test(value)) throw new Error(`PR 번호가 아니다: ${value}`);
+            return [pieceId, { pr: Number(value.replace(/^#/, '')) }];
+          }),
+          ...(opts.goal ?? []).map(([pieceId, value]): [string, { goalId: string }] => {
+            if (!/^[a-f0-9]{16}$/.test(value)) throw new Error(`골 id 는 16자 hex 다: ${value}`);
+            return [pieceId, { goalId: value }];
+          }),
+        ];
+        const twice = refs.map(([pieceId]) => pieceId).filter((pieceId, at, all) => all.indexOf(pieceId) !== at);
+        if (twice.length) throw new Error(`한 조각에 근거를 두 번 줬다(--pr·--goal 은 조각마다 하나): ${[...new Set(twice)].join(', ')}`);
+        // 기록 실패(없는 조각 · 제안된 미션)는 그 근거만 실패로 적고 계속 — `--all` 의 나머지 미션을 막지 않는다.
+        const refFailures: string[] = [];
+        for (const [pieceId, ref] of refs) {
+          try { recordPieceRef(pieceId, ref, statePath, missionId); } catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            if (missionId !== undefined) throw error;
+            refFailures.push(reason);
+          }
+        }
+        const ids = missionId !== undefined ? [missionId] : openMissionIds(statePath);
+        const results: AdvanceMissionResult[] = [];
+        const failures: Array<{ missionId: string; error: string }> = [];
+        for (const id of ids) {
+          try {
+            results.push(await advanceMission(id, {
+              live: opts.live === true,
+              ...(statePath ? { statePath } : {}),
+              launcher: deps.taskLauncher ?? defaultTaskLauncher,
+              ...(deps.pieceEvidence ? { readEvidence: deps.pieceEvidence } : {}),
+            }));
+          } catch (error) {
+            // 미션 id 하나면 그대로 실패 · --all 이면 그 미션만 실패로 적고 다음 미션으로 간다(크론이 한 미션에 막히지 않게).
+            if (missionId !== undefined) throw error;
+            failures.push({ missionId: id, error: error instanceof Error ? error.message : String(error) });
+          }
+        }
+        if (missionId === undefined) {
+          // --all 은 호출마다 요약 한 줄 — 대상 0·근거 기록 실패뿐인 호출도 관측에 남는다(미션별 줄은 advanceMission 이 남긴다).
+          try { debug.log('task-agent', 'mission-advance', { missionId: null, all: true, mode: opts.live ? 'live' : 'shadow', stage: 'all-summary', missions: ids.length, advanced: results.length, failures: failures.map((failure) => failure.missionId), refFailures: refFailures.length, ms: Date.now() - started }); } catch { /* fail-soft */ }
+        }
+        if (opts.json) out(JSON.stringify(missionId !== undefined ? results[0] : failures.length || refFailures.length ? { results, failures, refFailures } : results));
+        else {
+          if (results.length === 0 && failures.length === 0) out('넘길 미션이 없다 (green 제안 전 미션 0)');
+          for (const failure of failures) out(`${failure.missionId}\tadvance\tfailed\t${failure.error}`);
+          for (const reason of refFailures) out(`근거 기록 실패: ${reason}`);
+          for (const result of results) for (const line of advanceLines(result)) out(line);
+          if (!opts.live && results.some((result) => result.handed.length > 0)) out('(shadow — 띄우지 않았다 · 띄우려면 --live)');
+        }
+        if (failures.length || refFailures.length || results.some((result) => result.handed.some((piece) => piece.error))) process.exitCode = 1;
+      } catch (error) {
+        const reason = error instanceof Error ? error.message : '미션 진행 실패';
+        // advanceMission 에 닿기 전(근거 인자 검사·기록)에 멈춘 호출도 한 줄 — 관측이 «호출마다» 남는다.
+        // advanceMission 안에서 던진 것은 거기서 이미 남겼다(같은 오류를 두 번 적지 않는다).
+        if (!(error instanceof MissionAdvanceError)) {
+          try { debug.log('task-agent', 'mission-advance', { missionId: missionId ?? null, all: opts.all === true, mode: opts.live ? 'live' : 'shadow', stage: 'cli-args', error: reason, ms: Date.now() - started }); } catch { /* fail-soft */ }
+        }
+        out(reason);
+        process.exitCode = 1;
+      }
+    });
+
   tasks.command('show <id>')
-    .description('태스크 상세 보기')
+    .description(`태스크 상세 보기 (id 가 \`${TASK_CARD_PREFIX}\` 로 시작하면 TASK-AGENT 과제 카드 ⊕ 다음 수)`)
     .option('--json', 'JSON 출력')
     .action(async (id: string, opts: { json?: boolean }) => {
+      if (id.startsWith(TASK_CARD_PREFIX)) {
+        await registerTaskAgentSink(deps.registerSink);
+        let card: TaskCard | undefined;
+        try { card = readTaskCard(id, deps.taskStatePath); } catch (error) {
+          out(error instanceof Error ? error.message : '과제 카드 읽기 실패');
+          process.exitCode = 1;
+          return;
+        }
+        if (!card) { out(`과제 카드 없음: ${id}`); process.exitCode = 1; return; }
+        if (card.pieces) {
+          let all: Record<string, TaskCard>;
+          try { all = readTaskAgentState<{ tasks?: Record<string, TaskCard> }>(deps.taskStatePath ?? taskStatePathDefault()).tasks ?? {}; } catch (error) {
+            out(error instanceof Error ? error.message : '과제 카드 읽기 실패');
+            process.exitCode = 1;
+            return;
+          }
+          const pieces = card.pieces.map((pieceId) => all[pieceId]).filter((piece): piece is TaskCard => piece !== undefined);
+          const missingPieces = card.pieces.filter((pieceId) => !all[pieceId]);
+          if (opts.json) {
+            out(JSON.stringify({ card, nextMove: nextMoveFor(card), pieces: pieces.map((piece) => ({ card: piece, nextMove: nextMoveFor(piece) })), missingPieces }));
+            if (missingPieces.length) process.exitCode = 1;
+          }
+          else {
+            for (const line of missionLines(card, pieces)) out(line);
+            for (const missing of missingPieces) { out(`조각 카드 없음: ${missing} — 선후 기록이 불완전하다`); process.exitCode = 1; }
+          }
+          return;
+        }
+        if (opts.json) out(JSON.stringify({ card, nextMove: nextMoveFor(card) }));
+        else for (const line of taskCardLines(card)) out(line);
+        return;
+      }
       try {
         activeToken = undefined;
         const auth = authenticate();