elanous 0.2.36 → 0.2.38

package/src/cli/release-cli.ts

@@ -8,9 +8,11 @@
 //   elanous release run     --version <x.y.z> [--prerelease rc] [--main-cut | --cut-commit <sha>] [--publish-at <iso>] [--gate-executor <pod|host> [--gate-host <ssh-host>]] [--dry-run] [--json] [--if-ready] [--force-new]
 //   elanous release resume  --run <runId> --from <node> [--waive <node> --reason <text>] [--accepted-regressions <json>] [--gate-executor <pod|host> [--gate-host <ssh-host>]] [--gate-pod-pool <pool>] [--json]
 //   elanous release auto-start [--window-minutes <n>] [--apply] [--json]
+//   elanous release recover --run <runId> --pick <sha...> [--from export-check] [--command-root <path>] [--repo-root <path>] [--no-partial] [--json]
 //   elanous release rehearsal tick [--apply] [--checkout <dir>] [--shards <n>] [--remote <host>] [--recovery-run <id>] [--json]
 //   elanous release preflight --version <x.y.z> [--publish-at <iso>] [--json]   (컷 − 60분 main export 포함 사전 점검 · 읽기 전용 · ⛔ 있으면 exit 1)
-//   elanous release cut-branch --version <x.y.z> --base <sha> --pick <sha>... [--dry-run]
+//   elanous release cut-branch --version <x.y.z> [--base <sha>] --pick <sha>... [--append] [--dry-run]
+//     (--append 에서 --base 생략: 런 원장 version-release 기록 또는 release/<v> 끝의 첫 부모에서 스스로 찾는다)
 //
 // 🩸 계기(2026-09-25 v0.1.0 첫 공개): 손으로 밟은 절차에서 둘을 빠뜨릴 뻔했다 — 공개본 git 커밋(판 커밋이 공개본 커밋이 된다) ·
 //    PWA 빌드(빌드 산출은 공개본에 안 실린다 → 빠뜨리면 «웹 화면 없는 판»). 절차를 명령으로 굳힌다.
@@ -43,7 +45,7 @@ import { isIsolatedLedgerWriteRoot } from '../hq/ledger-write-target.js';
 import { runUnattendedRelease, type UnattendedReleaseDeps } from '../../scripts/release-loop/unattended-release.js';
 import { publishAtError } from '../../scripts/release-loop/publish-at.js';
 import { cutReleaseBranch } from '../../scripts/release-loop/cut-branch.js';
-import { planResumeReleaseRun, resumeReleaseRun, type ResumeReleaseDeps } from '../../scripts/release-loop/resume-release.js';
+import { planResumeReleaseRun, recoverReleaseRun, resumeReleaseRun, ReleaseRecoverStopped, type RecoverReleaseDeps } from '../../scripts/release-loop/resume-release.js';
 import type { AcceptedRegression } from '../../scripts/release-loop/resume.js';
 import type { PrereleaseKind } from '../../scripts/release-loop/release-version.js';
 import { releaseReadiness } from '../../scripts/release-loop/release-readiness.js';
@@ -57,7 +59,7 @@ import { landingFreezeMessage, LandingFrozenError, readLandingFreeze } from '../
 import { formatLightRc, runLightRc, type LightRcDeps } from '../release-loop/light-rc.js';
 import { applyWatchList, formatGateHistory, gateHistory, ghMergedPrs } from '../../scripts/release-loop/gate-history.js';
 import { registerRfcCommands } from './rfc-cli.js';
-import { checklistCodenames, checklistVersion, isReleaseVersion, readChecklistContext, registerChecklistReadCommands } from './release-checklist-read-cli.js';
+import { checklistCodenames, checklistVersion, isReleaseVersion, readChecklistContext, registerChecklistReadCommands, type ChecklistEvidenceReader } from './release-checklist-read-cli.js';
 
 export { isReleaseVersion } from './release-checklist-read-cli.js';
 
@@ -547,19 +549,35 @@ export interface LandedButYellowDeps {
   evidenceAdd?: typeof features.evidenceAdd;
   schedules?: typeof features.readSchedules;
   released?: typeof features.releasedVersion;
+  /** Isolated cache location for tests; production defaults to the installation release ledger. */
+  mergedPrCacheFile?: () => string;
 }
 
 /** A spawn failure (gh missing from PATH) resolves `status: null` with the error text — the shape the sync runner gave. */
-const defaultMergedPrRunner: MergedPrRunner = (command, args, cwd) => new Promise((resolve) => {
+const defaultMergedPrRunner: MergedPrRunner = (command, args, cwd, timeoutMs) => new Promise((resolve) => {
   const out: Buffer[] = [], err: Buffer[] = [];
   const failed = (error: unknown) => resolve({ status: null, stdout: Buffer.concat(out).toString('utf8'), stderr: String(error) });
   let child: ReturnType<typeof spawn>;
+  let timedOut = false;
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  let killTimeout: ReturnType<typeof setTimeout> | undefined;
   try { child = spawn(command, [...args], { cwd, env: process.env, stdio: ['ignore', 'pipe', 'pipe'] }); }
   catch (error) { failed(error); return; }
+  if (timeoutMs !== undefined) timeout = setTimeout(() => {
+    timedOut = true;
+    child.kill('SIGTERM');
+    // The caller has already reached its explicit limit. Give gh a short cleanup window, then
+    // force-close it so an ignoring child cannot keep the CLI alive for the former 5s grace.
+    killTimeout = setTimeout(() => child.kill('SIGKILL'), 100);
+  }, timeoutMs);
   child.stdout?.on('data', (chunk: Buffer) => out.push(chunk));
   child.stderr?.on('data', (chunk: Buffer) => err.push(chunk));
   child.on('error', failed);
-  child.on('close', (code) => resolve({ status: code, stdout: Buffer.concat(out).toString('utf8'), stderr: Buffer.concat(err).toString('utf8') }));
+  child.on('close', (code) => {
+    if (timeout !== undefined) clearTimeout(timeout);
+    if (killTimeout !== undefined) clearTimeout(killTimeout);
+    resolve({ status: code, stdout: Buffer.concat(out).toString('utf8'), stderr: Buffer.concat(err).toString('utf8'), ...(timedOut ? { timedOut: true } : {}) });
+  });
 });
 
 function printLandedRows(rows: ReturnType<typeof landedButYellow>, items: ReturnType<typeof listChecklist>['items']): void {
@@ -588,7 +606,7 @@ function compareReleaseVersions(a: string, b: string): number {
   return 0;
 }
 
-export function registerReleaseCommands(program: Command, releaseRunDeps: UnattendedReleaseDeps = {}, landedDeps: LandedButYellowDeps = {}, hqDeps: HqDeps = {}, lightRcDeps: LightRcDeps = {}, rehearsalDeps: RehearsalDeps = {}, resumeDeps: ResumeReleaseDeps = {}): void {
+export function registerReleaseCommands(program: Command, releaseRunDeps: UnattendedReleaseDeps = {}, landedDeps: LandedButYellowDeps = {}, hqDeps: HqDeps = {}, lightRcDeps: LightRcDeps = {}, rehearsalDeps: RehearsalDeps = {}, resumeDeps: RecoverReleaseDeps = {}, checklistEvidenceReader?: ChecklistEvidenceReader): void {
   registerRfcCommands(program);
   const release = program.command('release').description('공개 배포 한 판 — prepare(로컬) → publish(--yes) → verify (docs/manual/MANUAL-versioning-and-release-2026-09-25.md)');
   const schedule = release.command('schedule').description('판별 컷·착지 마감 조회·갱신');
@@ -780,13 +798,15 @@ export function registerReleaseCommands(program: Command, releaseRunDeps: Unatte
       console.log(renderRefsStatus(rows));
       console.log(`칸 ${rows.length} · 🟢 ${byStatus.green} · 🟡 ${byStatus.yellow} · 🔴 ${byStatus.red} · ✅ ${byStatus.done}`);
     });
-  registerChecklistReadCommands(checklist);
+  registerChecklistReadCommands(checklist, checklistEvidenceReader);
   withContext(checklist.command('landed-but-yellow').description('병합 PR 이 있지만 노랑·빨강인 칸(기본 읽기 전용)'))
     .option('--owner <owner>', '자리 또는 하위 자리로 거르기')
     .option('--open', '미발행 일정 판 중 칸이 있는 판 전부')
     .option('--apply-evidence', '확실한 PR 짝의 근거를 붙인다(상태는 그대로)')
     .option('--dry-run', '근거 추가 없이 계획만 출력')
-    .action(async (opts: { owner?: string; open?: boolean; applyEvidence?: boolean; dryRun?: boolean }, cmd: Command) => {
+    .option('--limit <ms>', '병합 PR 창 조회 시간 상한(밀리초) — 기본 무제한, 명시하면 초과 시 부분 결과와 stopReason·남은 칸 판 목록을 낸다')
+    .option('--time-budget <ms>', 'deprecated alias of --limit')
+    .action(async (opts: { owner?: string; open?: boolean; applyEvidence?: boolean; dryRun?: boolean; limit?: string; timeBudget?: string }, cmd: Command) => {
       // Stage timings (LANDED-YELLOW-FAST): which step ate the time — `elanous logs --category release.landed-yellow`.
       let stageAt = performance.now();
       const stage = (name: string, data: Record<string, unknown>) => {
@@ -835,10 +855,20 @@ export function registerReleaseCommands(program: Command, releaseRunDeps: Unatte
           .map((item) => Date.parse(item.updatedAt)).filter((at) => Number.isFinite(at)));
         const since = updated.length ? new Date(updated.reduce((earliest, at) => Math.min(earliest, at))).toISOString().slice(0, 10)
           : new Date(now.getTime() - 7 * 86_400_000).toISOString().slice(0, 10);
+        if (opts.limit !== undefined && opts.timeBudget !== undefined) throw new CliUserError('--limit 과 --time-budget 중 하나만 지정할 수 있다');
+        const timeBudget = opts.limit ?? opts.timeBudget;
+        const timeBudgetMs = timeBudget === undefined ? undefined : Number(timeBudget);
+        if (timeBudgetMs !== undefined && (!Number.isFinite(timeBudgetMs) || timeBudgetMs <= 0)) {
+          throw new CliUserError(`잘못된 시간 상한: ${timeBudget}`, '--limit <ms> — 양의 밀리초 수치');
+        }
         const syncRun = landedDeps.run;
         const runAsync: MergedPrRunner = landedDeps.runAsync ?? (syncRun ? async (command, args, cwd) => syncRun(command, args, cwd) : defaultMergedPrRunner);
-        const { prs, truncated, calls } = await fetchMergedChecklistPrs(since, now, runAsync, process.cwd());
-        stage('merged-prs', { n: prs.length, calls, since, truncated });
+        const cacheFile = landedDeps.mergedPrCacheFile?.() ?? ((landedDeps.run || landedDeps.runAsync) ? undefined : join(releaseLedgerRoot(), 'release', 'landed-but-yellow-cache.json'));
+        const { prs, truncated, calls, stopReason, remainingWindows } = await fetchMergedChecklistPrs(since, now, runAsync, process.cwd(), {
+          ...(cacheFile ? { cacheFile } : {}),
+          timeBudgetMs,
+        });
+        stage('merged-prs', { n: prs.length, calls, since, truncated, ...(stopReason !== undefined ? { stopReason, remainingWindows: remainingWindows.length } : {}) });
         const results: Array<{ version: string; rows?: ReturnType<typeof landedButYellow>; plan?: ReturnType<typeof evidencePlan> }> = [];
         let totalAdded = 0, totalSkipped = 0;
         for (const snapshot of snapshots) {
@@ -869,9 +899,14 @@ export function registerReleaseCommands(program: Command, releaseRunDeps: Unatte
         if (opts.open) {
           if (opts.applyEvidence && !opts.dryRun) debug.log('release.checklist', 'evidence-synced', { versions: snapshots.map(({ version }) => version), added: totalAdded, skippedMention: totalSkipped });
           if (!json) console.log(`판 ${snapshots.length} · 붙임 합 ${totalAdded} · 건너뜀(언급만) 합 ${totalSkipped}`);
+          else if (stopReason !== undefined) await writeStdoutJson(`${JSON.stringify({ results, stopReason, remainingVersions: snapshots.map(({ version }) => version), remainingWindows })}\n`);
           else await writeStdoutJson(`${JSON.stringify(results)}\n`);
-        } else if (json) await writeStdoutJson(`${JSON.stringify(opts.applyEvidence || opts.dryRun ? results[0]!.plan : results[0]!.rows)}\n`);
+        } else if (json) {
+          const output = opts.applyEvidence || opts.dryRun ? results[0]!.plan : results[0]!.rows;
+          await writeStdoutJson(`${JSON.stringify(stopReason === undefined ? output : { results, stopReason, remainingVersions: snapshots.map(({ version }) => version), remainingWindows })}\n`);
+        }
         if (truncated) console.error('⚠ 병합 PR 400개 상한: 목록이 잘렸을 수 있다');
+        if (stopReason !== undefined) console.error(`⚠ 병합 PR 조회 시간 상한 도달: 부분 결과 ${prs.length} · 남은 판 ${snapshots.map(({ version }) => version).join(' · ')} · 미조회 UTC 창 ${remainingWindows.length}(${remainingWindows.slice(0, 3).join(' · ')}${remainingWindows.length > 3 ? ' …' : ''})`);
       } catch (error) {
         console.error(`⛔ ${error instanceof Error ? error.message : String(error)}`);
         process.exitCode = 1;
@@ -884,9 +919,14 @@ export function registerReleaseCommands(program: Command, releaseRunDeps: Unatte
     .option('--allow-duplicate-id', '다른 판에 같은 id 가 있어도 경고 후 추가')
     .option('--strict', '대상 경로·완료 경계 경고가 있으면 저장 전 거부')
     .option('--ref <path...>', '근거 문서 — 저장소 상대 경로[#절] (반복 가능)')
-    .action((id: string, title: string, opts: { ref?: string[]; owner?: string; kind?: string; priority?: string; deadlineVersion?: string; predecessor?: string[]; ceoMinutes?: string; ceoDate?: string; accelerator?: boolean; allowDuplicateId?: boolean; strict?: boolean }, cmd: Command) => {
+    .action(async (id: string, title: string, opts: { ref?: string[]; owner?: string; kind?: string; priority?: string; deadlineVersion?: string; predecessor?: string[]; ceoMinutes?: string; ceoDate?: string; accelerator?: boolean; allowDuplicateId?: boolean; strict?: boolean }, cmd: Command) => {
     const { version, json } = context(cmd);
     if (!mayWrite(cmd)) return;
+    const { normalizeEvidenceCommandLines } = await import('../task-agent/evidence-command-normalize.js');
+    const normalized = normalizeEvidenceCommandLines(title);
+    if (opts.strict && normalized.unrecognized.length) throw new CliUserError(`완료 경계 증거 명령 정규화 불가: ${normalized.unrecognized.join(' · ')}`);
+    title = normalized.text;
+    for (const warning of normalized.warnings) console.error(`⚠ ${warning}`);
     const dispatchKind = opts.kind && !['screen', 'postpub'].includes(opts.kind) ? opts.kind as ChecklistDispatchKind : undefined;
     warnChecklistTargetPaths({ title, refs: opts.ref, dispatchKind }, opts.strict);
     const data = addItem(version, { id, title, ...(opts.ref !== undefined ? { refs: opts.ref } : {}), ...(opts.owner !== undefined ? { owner: opts.owner } : {}), ...(opts.kind !== undefined && !dispatchKind ? { kind: opts.kind as ChecklistKind } : {}), ...(dispatchKind ? { dispatchKind } : {}), ...(opts.priority !== undefined ? { priority: opts.priority as PlacementPriority } : {}), ...(opts.deadlineVersion !== undefined ? { deadlineVersion: opts.deadlineVersion } : {}), ...(opts.predecessor !== undefined ? { predecessors: opts.predecessor } : {}), ...(opts.ceoMinutes !== undefined ? { ceoMinutes: ceoMinutes(opts.ceoMinutes) } : {}), ...(opts.ceoDate !== undefined ? { ceoDate: opts.ceoDate } : {}), ...(opts.accelerator ? { accelerator: true } : {}) }, { allowDuplicateId: opts.allowDuplicateId });
@@ -952,9 +992,14 @@ export function registerReleaseCommands(program: Command, releaseRunDeps: Unatte
       else features.move(id, from, to, actor(), undefined, undefined, opts.reason);
       if (json) console.log(JSON.stringify(listChecklist(to))); else console.log(`✅ ${id} ${from} → ${to}`);
     });
-  withContext(checklist.command('retitle <id> <title>').description('칸 제목 수정')).option('--strict', '대상 경로·완료 경계 경고가 있으면 저장 전 거부').action((id: string, title: string, opts: { strict?: boolean }, cmd: Command) => {
+  withContext(checklist.command('retitle <id> <title>').description('칸 제목 수정')).option('--strict', '대상 경로·완료 경계 경고가 있으면 저장 전 거부').action(async (id: string, title: string, opts: { strict?: boolean }, cmd: Command) => {
     const { version, json } = context(cmd);
     if (!mayWrite(cmd)) return;
+    const { normalizeEvidenceCommandLines } = await import('../task-agent/evidence-command-normalize.js');
+    const normalized = normalizeEvidenceCommandLines(title);
+    if (opts.strict && normalized.unrecognized.length) throw new CliUserError(`완료 경계 증거 명령 정규화 불가: ${normalized.unrecognized.join(' · ')}`);
+    title = normalized.text;
+    for (const warning of normalized.warnings) console.error(`⚠ ${warning}`);
     const snapshot = listChecklist(version);
     const item = snapshot.items.find((entry) => entry.id === id);
     if (!opts.strict) warnChecklistTargetPaths({ title, evidence: item?.evidence, refs: item?.refs, dispatchKind: item?.dispatchKind });
@@ -972,7 +1017,7 @@ export function registerReleaseCommands(program: Command, releaseRunDeps: Unatte
       const data = noteDispatchSkip(version, id, reason, opts.expectedTitle, opts.by);
       if (json) console.log(JSON.stringify(data)); else console.log(`✅ ${id} 건너뜀 근거 확인`);
     });
-  const evidence = checklist.command('evidence').description('칸의 PR·커밋 근거');
+  const evidence = checklist.commands.find((command) => command.name() === 'evidence')!;
   withContext(evidence.command('add <id> <ref>').description('근거 참조 추가')).action((id: string, ref: string, _opts: unknown, cmd: Command) => {
       const { version, json } = context(cmd);
       if (!mayWrite(cmd)) return;
@@ -1060,12 +1105,12 @@ export function registerReleaseCommands(program: Command, releaseRunDeps: Unatte
   release.command('cut-branch')
     .description('원래 컷에 main 의 수리 커밋만 얹은 release/<v> 가지를 만들고 push. --append 는 이미 있는 가지에 fast-forward 로만 더 얹는다')
     .requiredOption('--version <v>', '릴리스 판(x.y.z)')
-    .requiredOption('--base <sha>', '원래 컷 SHA')
+    .option('--base <sha>', '원래 컷 SHA(--append 에서 생략하면 런 원장 version-release 기록이나 release/<v> 끝의 첫 부모에서 스스로 찾는다)')
     .requiredOption('--pick <sha...>', '차례로 얹을 main 커밋 SHA')
     .option('--append', '이미 있는 release/<v> 를 출발점으로 fast-forward push(강제 push 없음)')
     .option('--dry-run', '가지·worktree·push 없이 계획만 출력')
     .option('--json', '결과 한 줄 JSON(stdout)')
-    .action(async (o: { version: string; base: string; pick: string[]; append?: boolean; dryRun?: boolean; json?: boolean }) => {
+    .action(async (o: { version: string; base?: string; pick: string[]; append?: boolean; dryRun?: boolean; json?: boolean }) => {
       await jsonAction(o.json, async (log) => cutReleaseBranch({ ...o, log }), () => true);
     });
   const runAction = async (o: { version: string; cutCommit?: string; mainCut?: boolean; prerelease?: string; dryRun?: boolean; ifReady?: boolean; publishAt?: string; forceFreeze?: boolean; forceNew?: boolean; gateExecutor?: string; gateHost?: string; json?: boolean }, logRun = console.log): Promise<boolean | AutoStartDeferral | undefined> => {
@@ -1226,16 +1271,17 @@ export function registerReleaseCommands(program: Command, releaseRunDeps: Unatte
     .option('--remote <host>', '게이트 호스트(기본 config gateRemote.host)')
     .option('--local', '원격 대신 이 기계에서 돌린다(원격 자식이 이것으로 다시 불린다)')
     .option('--shards <n>', '시험 분할 수', '4')
+    .option('--shard-concurrency <n>', '동시에 실행할 조각 묶음 수 (1–4, 기본 3)')
     .option('--fixed-shard-distribution', 'self gate 에 그대로 전달 — RSS 사전 측정 없이 --shards N 조각에 정렬 라운드로빈 고정 배정(opt-in · 원격 자식 전달)')
     .option('--rehearsal-tui', '리허설 전용 TUI 화면 점검(원격 자식 전달)')
     .option('--json', '결과 한 줄 JSON(stdout) · 사람 줄은 stderr')
-    .action(async (o: { version: string; base?: string; head?: string; remote?: string; local?: boolean; shards: string; fixedShardDistribution?: boolean; rehearsalTui?: boolean; json?: boolean }) => {
+    .action(async (o: { version: string; base?: string; head?: string; remote?: string; local?: boolean; shards: string; shardConcurrency?: string; fixedShardDistribution?: boolean; rehearsalTui?: boolean; json?: boolean }) => {
       // The root strips `--local` from argv (remote-bookmark attach) before Commander sees it — same read as `self gate`.
       const local = !!o.local || process.argv.slice(2).includes('--local');
       await jsonAction(o.json, async (log) => {
         if (o.remote !== undefined && local) throw new Error('release light-rc: --remote and --local cannot be combined');
         const shards = Number(o.shards);
-        const result = await runLightRc(o.version, { base: o.base, head: o.head, remote: o.remote, local, shards, ...(o.fixedShardDistribution ? { fixedShardDistribution: true } : {}), rehearsalTui: o.rehearsalTui, ledgerRoot: releaseRunDeps.ledgerRoot, log: (l) => console.error(l) }, lightRcDeps);
+        const result = await runLightRc(o.version, { base: o.base, head: o.head, remote: o.remote, local, shards, ...(o.shardConcurrency !== undefined ? { shardConcurrency: Number(o.shardConcurrency) } : {}), ...(o.fixedShardDistribution ? { fixedShardDistribution: true } : {}), rehearsalTui: o.rehearsalTui, ledgerRoot: releaseRunDeps.ledgerRoot, log: (l) => console.error(l) }, lightRcDeps);
         for (const line of formatLightRc(result)) log(line);
         return result;
       }, (r) => r.ok);
@@ -1295,6 +1341,31 @@ export function registerReleaseCommands(program: Command, releaseRunDeps: Unatte
           ...(o.gatePodPool !== undefined && poolOverride?.kind === 'gate-pod-pool' ? { gatePodPool: poolOverride } : {}) };
       }, (r) => 'preflight' in r || r.status === 'done' || r.status === 'awaiting-approval');
     });
+  // RELEASE-RECOVER-ONE-CMD (0.2.36): the three repair steps RUNBOOK-release-recover chained by hand, in one command.
+  release.command('recover')
+    .description('발행 실패 복구를 한 명령으로 — release/<v> 에 수리 커밋을 fast-forward 로 얹는 append dry-run → append → resume --from export-check. resume이 거부할 런(상태 · --from 배치 · 컷 정체 · 시도 원장)은 append 전에 읽기 전용으로 먼저 가려 가지를 먼저 움직이지 않는다 · 원장의 append-ok가 가지 끝에 살아 있으면 append 없이 resume부터 재진입한다 · 한 단계라도 실패하면 그 자리에서 멈추고 다음 단계는 실행하지 않는다(사람 판단) · 단계 결과는 resume-attempts 원장에 남는다')
+    .requiredOption('--run <runId>', '실패한 release-loop 런 ID')
+    .requiredOption('--pick <sha...>', 'release/<v> 에 fast-forward 로 얹을 main 수리 커밋 SHA')
+    .option('--from <node>', '재개 시작 노드 — 기본 export-check(컷을 쓰는 첫 노드)')
+    .option('--command-root <path>', '노드 명령을 실행할 컷 tip checkout — 생략 시 recover가 append tip 의 임시 checkout 을 직접 마련한다(운영자 checkout 은 그대로) · 직접 지정하면 사람 판단 경계다: 계획 단계에서 tip 과 대조해 다르면 멈춘다')
+    .option('--repo-root <path>', 'append(cut-branch)를 실행할 checkout — git remote origin 이 있는 곳(생략 시 현재 폴더)')
+    .option('--no-partial', 'GATE-REUSE-BY-DIFF 기본 부분 재검을 끄고 전체 게이트')
+    .option('--json', '결과 한 줄 JSON(stdout) · 사람 줄은 stderr')
+    .action(async (o: { run: string; pick: string[]; from?: string; commandRoot?: string; repoRoot?: string; partial?: boolean; json?: boolean }) => {
+      await jsonAction(o.json, async (log) => {
+        try {
+          return await recoverReleaseRun({ runId: o.run, pick: o.pick,
+            ...(o.from === undefined ? {} : { from: o.from }),
+            ...(o.commandRoot === undefined ? {} : { commandRoot: o.commandRoot }),
+            ...(o.repoRoot === undefined ? {} : { repoRoot: o.repoRoot }),
+            ...(o.partial === undefined ? {} : { partial: o.partial }) },
+          { ...resumeDeps, onSource: log });
+        } catch (caught) {
+          if (!(caught instanceof ReleaseRecoverStopped)) throw caught;
+          return { ok: false as const, error: caught.message, stages: [...caught.stages], notRun: [...caught.notRun] };
+        }
+      }, (r) => r.stages.every((stage) => stage.outcome === 'ok'));
+    });
   release.command('gate-history')
     .description('GATE-FAIL-HISTORY (0.2.29) — 판을 넘는 게이트 실패 표 — 모든 release-loop·light-rc 런 원장 ⊕ gate-verdict 에서 시험 파일별 introduced·preexisting·env·flaky 횟수 · 마지막 실패 판 · 원인 PR(수리 PR 본문 «원인 #N»)')
     .option('--since <판|일>', '이 판(x.y.z)부터 · 또는 그 날(YYYY-MM-DD) 이후 시작된 런부터')

package/src/cli/review-carry.ts

@@ -0,0 +1,77 @@
+/** Prove that a PR's new head is exactly a clean merge of main into its reviewed head. */
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { delimiter, join, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const SHA = /^[0-9a-f]{40}$/i;
+const MAX = 32 * 1024 * 1024;
+
+export type ReviewCarryProof = { ok: true; oldBase: string; newBase: string; patchId: string; pathsModesHash: string }
+  | { ok: false; reason: string };
+
+/** No refs, index, or worktree are changed. merge-tree objects live in a disposable directory. */
+export function proveReviewCarry(cwd: string, oldHead: string, newHead: string, remote = 'origin', branch = 'main'): ReviewCarryProof {
+  if (!SHA.test(oldHead) || !SHA.test(newHead) || oldHead === newHead) return { ok: false, reason: 'carry-invalid-head' };
+  const run = (args: string[], env?: NodeJS.ProcessEnv, input?: string) => spawnSync('git', args,
+    { cwd, env, input, encoding: 'utf8', maxBuffer: MAX });
+  const read = (args: string[], env?: NodeJS.ProcessEnv): string | null => {
+    const result = run(args, env);
+    return result.status === 0 && !result.error ? result.stdout.trim() : null;
+  };
+  const parents = read(['rev-list', '--parents', '-n', '1', newHead])?.split(/\s+/);
+  if (!parents || parents.length !== 3 || parents[0]?.toLowerCase() !== newHead.toLowerCase()
+    || parents[1]?.toLowerCase() !== oldHead.toLowerCase() || !SHA.test(parents[2] ?? '')) {
+    return { ok: false, reason: 'carry-not-direct-main-merge' };
+  }
+  const newBase = parents[2]!.toLowerCase();
+  const main = read(['rev-parse', '--verify', `refs/remotes/${remote}/${branch}`]);
+  if (!main || !SHA.test(main) || run(['merge-base', '--is-ancestor', newBase, main]).status !== 0) {
+    return { ok: false, reason: 'carry-main-parent-unmeasured' };
+  }
+  const oldBase = read(['merge-base', oldHead, newBase]);
+  if (!oldBase || !SHA.test(oldBase)) return { ok: false, reason: 'carry-old-base-unmeasured' };
+  if (oldBase.toLowerCase() === oldHead.toLowerCase()) return { ok: false, reason: 'carry-no-pr-patch' };
+  const objects = read(['rev-parse', '--git-path', 'objects']);
+  if (!objects) return { ok: false, reason: 'carry-object-directory-unmeasured' };
+  let temporary: string;
+  try { temporary = mkdtempSync(join(tmpdir(), 'elanous-review-carry-')); }
+  catch { return { ok: false, reason: 'carry-temp-directory-unmeasured' }; }
+  const env = { ...process.env, GIT_OBJECT_DIRECTORY: temporary,
+    GIT_ALTERNATE_OBJECT_DIRECTORIES: [resolve(cwd, objects), process.env.GIT_ALTERNATE_OBJECT_DIRECTORIES].filter(Boolean).join(delimiter) };
+  try {
+    const mergedTree = read(['merge-tree', '--write-tree', oldHead, newBase], env);
+    if (!mergedTree || !SHA.test(mergedTree)) return { ok: false, reason: 'carry-merge-conflict-or-unmeasured' };
+    const actualTree = read(['rev-parse', '--verify', `${newHead}^{tree}`]);
+    if (!actualTree || actualTree.toLowerCase() !== mergedTree.toLowerCase()) {
+      return { ok: false, reason: 'carry-merge-tree-changed' };
+    }
+    const changed = (from: string, to: string, objectEnv?: NodeJS.ProcessEnv) => {
+      const raw = run(['diff', '--raw', '--no-renames', '--no-abbrev', '-z', from, to], objectEnv);
+      const numstat = read(['diff', '--numstat', from, to], objectEnv);
+      const diff = read(['diff', '--no-ext-diff', '--no-renames', '--binary', from, to], objectEnv);
+      if (raw.status !== 0 || raw.error || numstat === null || !diff) return null;
+      if (numstat.split('\n').some((line) => /^-\t-\t/.test(line))) return null;
+      const fields = raw.stdout.split('\0').filter(Boolean);
+      if (!fields.length || fields.length % 2 !== 0) return null;
+      const pathsModes: string[] = [];
+      for (let i = 0; i < fields.length; i += 2) {
+        const match = /^:([0-7]{6}) ([0-7]{6}) [0-9a-f]{40,64} [0-9a-f]{40,64} ([A-Z])$/i.exec(fields[i]!);
+        if (!match || !fields[i + 1] || !['A', 'M', 'D', 'T'].includes(match[3]!)) return null;
+        pathsModes.push(`${match[3]}\0${match[1]}\0${match[2]}\0${fields[i + 1]}`);
+      }
+      const patched = run(['patch-id', '--stable'], objectEnv, `${diff}\n`);
+      const patchId = patched.status === 0 && !patched.error ? patched.stdout.trim().split(/\s+/)[0] : null;
+      return patchId && SHA.test(patchId) ? { patchId: patchId.toLowerCase(), pathsModes: pathsModes.sort() } : null;
+    };
+    const before = changed(oldBase, oldHead);
+    const after = changed(newBase, newHead);
+    if (!before || !after) return { ok: false, reason: 'carry-patch-unmeasured' };
+    if (before.patchId !== after.patchId || JSON.stringify(before.pathsModes) !== JSON.stringify(after.pathsModes)) {
+      return { ok: false, reason: 'carry-patch-or-path-mode-changed' };
+    }
+    return { ok: true, oldBase: oldBase.toLowerCase(), newBase, patchId: before.patchId,
+      pathsModesHash: createHash('sha256').update(JSON.stringify(before.pathsModes)).digest('hex') };
+  } finally { rmSync(temporary, { recursive: true, force: true }); }
+}

package/src/cli/self-update.ts

@@ -10,6 +10,15 @@ 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';
 
+function selfUpdateOutputTail(output: string): string {
+  const lines = output.split(/\r?\n/).filter((line) => line.trim()).slice(-40);
+  return Array.from(lines.join('\n')).slice(-20_000).join('');
+}
+
+function selfUpdateReasonTail(tail: string): string {
+  return Array.from(tail).slice(-4_000).join('');
+}
+
 export interface SelfUpdateOptions {
   from?: string;
   restart?: boolean;
@@ -487,7 +496,7 @@ export function assessRailSafe(input: AssessRailSafeInput): {
   const heldVersions = plan.removed.filter((name) => {
     const path = join(input.versionsDir, name);
     try {
-      return listedProcessCommands(listProcesses(pgrepPathPattern(path)), readCommand).some((argv) => argv.includes(path));
+      return listedProcessCommands(listProcesses(pgrepPathPattern(path)), readCommand).some((argv) => argvReferencesVersion(argv, path));
     } catch { return false; }
   });
   let releaseRunActive = false;
@@ -1241,25 +1250,34 @@ export async function runSelfUpdate(options: SelfUpdateOptions = {}, deps: SelfU
       try {
         const build = run('bun', ['bin/elanous.mjs', 'nexus', 'build'], checkout, { timeout: 15 * 60_000 });
         ok = build.status === 0;
-        tail = (build.stderr?.trim() || build.stdout?.trim() || '').split(/\r?\n/).filter((line) => line.trim()).at(-1)?.trim().slice(0, 500) ?? '';
+        const output = build.stderr?.trim() || build.stdout?.trim() || '';
+        tail = ok ? output.split(/\r?\n/).filter((line) => line.trim()).at(-1)?.trim().slice(0, 500) ?? '' : selfUpdateOutputTail(output);
       } catch (error) {
-        tail = String(error).split(/\r?\n/).at(-1)?.trim().slice(0, 500) ?? '';
+        tail = selfUpdateOutputTail(String(error));
       }
       const ms = Date.now() - started;
       try {
         debug.log('self-update', 'pwa-build', { ok, commit, ms });
         debug.log('self-update', 'pwa-build-tail', { commit, tail: tail || '출력 없음' });
+        if (!ok) debug.log('self-update', 'build-failed', { stage: 'pwa-build', commit, tail: tail || '출력 없음' });
       } catch { /* 관측 실패가 갱신을 막지 않는다 */ }
-      if (!ok) return emit({ exitCode: 1, installedVersion: null, decision, restarted: false, reason: `PWA 빌드 실패: ${tail || '출력 없음'}` });
+      if (!ok) return emit({ exitCode: 1, installedVersion: null, decision, restarted: false, reason: `PWA 빌드 실패: ${selfUpdateReasonTail(tail) || '출력 없음'}` });
       pwaBuild = { pwaBuiltCommit: commit, pwaBuiltAt: new Date().toISOString() };
     }
     let install: ReturnType<NonNullable<SelfUpdateDeps['run']>>;
+    let installTail = '';
     try {
       install = run('bash', [join(checkout, 'scripts/install.sh'), '--no-modify-path'], checkout);
+      if (install.status !== 0) installTail = selfUpdateOutputTail(install.stderr?.trim() || install.stdout?.trim() || '');
     } catch (error) {
-      return emit({ exitCode: 1, installedVersion: null, decision, restarted: false, reason: `설치 실패: ${String(error)}` });
+      installTail = selfUpdateOutputTail(String(error));
+      try { debug.log('self-update', 'build-failed', { stage: 'install', commit: head.stdout.trim().slice(0, 12), tail: installTail || '출력 없음' }); } catch { /* 관측 실패가 갱신을 막지 않는다 */ }
+      return emit({ exitCode: 1, installedVersion: null, decision, restarted: false, reason: `설치 실패: ${selfUpdateReasonTail(installTail) || '출력 없음'}` });
+    }
+    if (install.status !== 0) {
+      try { debug.log('self-update', 'build-failed', { stage: 'install', commit: head.stdout.trim().slice(0, 12), tail: installTail || '출력 없음' }); } catch { /* 관측 실패가 갱신을 막지 않는다 */ }
+      return emit({ exitCode: 1, installedVersion: null, decision, restarted: false, reason: `설치 실패: ${selfUpdateReasonTail(installTail) || '출력 없음'}` });
     }
-    if (install.status !== 0) return emit({ exitCode: 1, installedVersion: null, decision, restarted: false, reason: `설치 실패: ${install.stderr}` });
     let installedVersion: string;
     try {
       installedVersion = (deps.installedVersion ?? (() => basename(readlinkSync(join(homedir(), '.local/share/elanous/current')))))();

package/src/cli/self-utterances-cli.ts

@@ -1,12 +1,12 @@
 import type { Command } from 'commander';
 import { Database } from 'bun:sqlite';
 import { redactSecretText } from '../debug/log.js';
-import { openSurfaceEventsDb, querySurfaceUtterances, surfaceEventsDbPath, type SurfaceEventRow } from '../domains/surface-events.js';
+import { classifySurfaceUtteranceOrigin, countSurfaceUtterancesByOrigin, openSurfaceEventsDb, querySurfaceUtterances, surfaceEventsDbPath, type SurfaceEventRow } from '../domains/surface-events.js';
 import { injectUtterance, type UtteranceInput } from '../domains/self-awareness.js';
 import { writeStdoutJson } from './stdout-json.js';
 
 const PAGE_SIZE = 50;
-type UtteranceOrigin = 'human' | 'agent' | 'unknown';
+type UtteranceOrigin = 'human' | 'agent' | 'test-fixture' | 'unknown';
 
 function refsOf(raw: string | null): Record<string, unknown> {
   if (!raw) return {};
@@ -33,21 +33,15 @@ function isAutomatic(row: SurfaceEventRow): boolean {
   return false;
 }
 
+/** 도메인 원천 분류(사람/시험 fixture/외부 CLI agent/elanous 자기)를 CLI 표기로 접는다.
+ *  시험 fixture 는 사람과 같은 서피스에 기록되지만 사람 표본이 아니다 — 별도 값으로 노출한다. */
 function originOf(row: SurfaceEventRow): UtteranceOrigin {
-  if (row.direction !== 'inbound') return 'unknown';
-  const refs = refsOf(row.refs);
-  if (refs.utteranceOrigin === 'human' || refs.utteranceOrigin === 'agent') return refs.utteranceOrigin;
-  const explicit = refs.origin;
-  if (typeof explicit === 'string') {
-    if (/^(?:human|user|tui|pwa|telegram|discord|cli)$/i.test(explicit)) return 'human';
-    if (/^(?:claude-code|codex|gemini|agent|external:)/i.test(explicit)) return 'agent';
+  switch (classifySurfaceUtteranceOrigin(row)) {
+    case 'human': return 'human';
+    case 'test-fixture': return 'test-fixture';
+    case 'external-cli-agent': case 'elanous-self': return 'agent';
+    default: return 'unknown';
   }
-  // recordInboundTurn marks its recorder as elanous-self; on chat Q&A the speaker is the human.
-  if (row.kind === 'qna' && /^(?:telegram|discord)$/i.test(row.surface)) return 'human';
-  if (explicit === 'elanous-self') return 'agent';
-  if (/^ext:/i.test(row.surface)) return 'agent';
-  if (/^(?:cli|tui|pwa|telegram|discord|ipad|watch)$/i.test(row.surface)) return 'human';
-  return 'unknown';
 }
 
 function utteranceText(row: SurfaceEventRow): { text: string; extract: 'direct' | 'qna' | 'ambiguous' | 'summary'; truncated: boolean; truncationEvidence: 'cap-reached' | 'over-cap' | null; possibleLoss: boolean } {
@@ -101,7 +95,9 @@ export function collectSelfUtterances(opts: SelfUtterancesOptions, db: ReturnTyp
   });
   const total = utterances.length;
   const start = (page - 1) * PAGE_SIZE;
-  return { source: 'surface_events.events (read-only)', filters: { from, to, surface: opts.surface ?? null, origin: opts.origin ?? null, automatic: 'excluded' }, counts: { matched: total, excludedAutomatic, excludedByOrigin, excludedUnextractable, ambiguous, truncated, capReached, possibleLoss }, page: { number: page, size: PAGE_SIZE, total, hasNext: start + PAGE_SIZE < total }, utterances: utterances.slice(start, start + PAGE_SIZE) };
+  // ⭐ 원천별 수를 «명시»한다 — 사람 원천 0 을 사람 표본으로 오인하지 않게(시험 fixture·외부 CLI agent 분리).
+  const originCounts = countSurfaceUtterancesByOrigin(db, { from, to, ...(opts.surface ? { surface: opts.surface } : {}) });
+  return { source: 'surface_events.events (read-only)', filters: { from, to, surface: opts.surface ?? null, origin: opts.origin ?? null, automatic: 'excluded' }, originCounts, humanSample: originCounts.human === 0 ? 'absent' : 'present', counts: { matched: total, excludedAutomatic, excludedByOrigin, excludedUnextractable, ambiguous, truncated, capReached, possibleLoss }, page: { number: page, size: PAGE_SIZE, total, hasNext: start + PAGE_SIZE < total }, utterances: utterances.slice(start, start + PAGE_SIZE) };
 }
 
 export function recordSelfUtterance(input: UtteranceInput & { utteranceOrigin?: 'human' | 'agent' }, db?: Database): { eventId: string } {
@@ -131,6 +127,7 @@ export function registerSelfUtterancesCommand(selfCmd: Command): void {
         if (opts.json) { await writeStdoutJson(JSON.stringify(result, null, 2) + '\n'); return; }
         console.log(`source=${result.source} matched=${result.counts.matched} excludedAutomatic=${result.counts.excludedAutomatic} excludedByOrigin=${result.counts.excludedByOrigin} excludedUnextractable=${result.counts.excludedUnextractable} page=${result.page.number} size=${result.page.size} hasNext=${result.page.hasNext}`);
         console.log(`filters=${JSON.stringify(result.filters)}`);
+        console.log(`origin-counts human=${result.originCounts.human} test-fixture=${result.originCounts.testFixture} external-cli-agent=${result.originCounts.externalCliAgent} elanous-self=${result.originCounts.elanousSelf} unknown=${result.originCounts.unknown} human-sample=${result.humanSample}`);
         for (const item of result.utterances) console.log(JSON.stringify(item));
         console.log(`ambiguous=${result.counts.ambiguous} truncated=${result.counts.truncated} cap-reached=${result.counts.capReached} possibleLoss=${result.counts.possibleLoss}`);
       } finally { db.close(); }

package/src/cli/tasks-card-show.ts

@@ -5,6 +5,8 @@ import { readCardSalvageBranch, refreshCardRunBinding } from '../task-agent/card
 import { captureReviewResults } from '../task-agent/review-result-capture.js';
 import type { TasksCliDeps } from './tasks-cli.js';
 import { registerTaskAgentSink } from './tasks-read-cli.js';
+import { readFileSync } from 'node:fs';
+import { loadGoalAskRecords } from '../self-implement/goal-ask-store.js';
 
 /**
  * CLI-ENTRY-LAZY — `tasks show ta-…`(TASK-AGENT 과제 카드) 상세. `tasks-read-cli.ts` 가 카드 id 일 때만 싣는다.
@@ -30,6 +32,34 @@ function moveLine(card: TaskCard): string {
   return `${move.kind}${move.command ? ` — elanous ${move.command.map(shellQuote).join(' ')}` : ''} (${move.reason})`;
 }
 
+const GOAL_BODY_SUMMARY_LIMIT = 8_000;
+
+function cardGoalEvidence(card: TaskCard, deps: TasksCliDeps): {
+  goalFile: string | null; goalBody: string | null; hasTddPlan: boolean | null;
+  hasBoundary: boolean | null; knowhowInjected: boolean | null;
+} {
+  let document: { goalFile: string; goalBody: string } | null = null;
+  try {
+    if (card.goalId && deps.cardGoalDocument) document = deps.cardGoalDocument(card.goalId);
+    else if (card.goalId) {
+      const record = loadGoalAskRecords({ goalId: card.goalId, limit: 1 })[0];
+      if (record) document = { goalFile: record.goalFile, goalBody: readFileSync(record.goalFile, 'utf8') };
+    }
+  } catch (error) {
+    try { debug.log('task-agent', 'card-goal-read-failed', { cardId: card.id, goalId: card.goalId, error: error instanceof Error ? error.message : String(error) }); } catch { /* fail-soft */ }
+  }
+  if (!document) return { goalFile: null, goalBody: null, hasTddPlan: null, hasBoundary: null, knowhowInjected: null };
+  const body = document.goalBody;
+  const hasTddPlan = /^#{1,6}\s+.*(?:TDD|test[- ]driven|테스트 주도).*$/im.test(body);
+  const hasBoundary = /(?:완료 경계|완료 조건|acceptance criteria|completion boundary)/i.test(body);
+  const knowhowInjected = /\[KNOWHOW-PACK\b[^\]]*\]/i.test(body);
+  return {
+    goalFile: document.goalFile,
+    goalBody: body.length <= GOAL_BODY_SUMMARY_LIMIT ? body : `${body.slice(0, GOAL_BODY_SUMMARY_LIMIT)}… [truncated]`,
+    hasTddPlan, hasBoundary, knowhowInjected,
+  };
+}
+
 export function headLine(text: string): string {
   const first = text.split('\n')[0]!.trim();
   return first.length > 100 ? `${first.slice(0, 100)}…` : first;
@@ -152,7 +182,7 @@ export async function showTaskCard(id: string, opts: { json?: boolean }, deps: T
   try { salvage = await readCardSalvageBranch(card, deps.cardRunEvidence ?? {}); }
   catch (error) { salvage = { salvageBranch: null, readErrors: [error instanceof Error ? error.message : String(error)] }; }
   const salvageUnread = !salvage.salvageBranch && !!salvage.readErrors?.length;
-  if (opts.json) out(JSON.stringify({ card, nextMove: nextMoveFor(card), salvageBranch: salvage.salvageBranch, ...(salvageUnread ? { salvageBranchUnread: true } : {}) }));
+  if (opts.json) out(JSON.stringify({ card, nextMove: nextMoveFor(card), ...cardGoalEvidence(card, deps), salvageBranch: salvage.salvageBranch, ...(salvageUnread ? { salvageBranchUnread: true } : {}) }));
   else {
     for (const line of taskCardLines(card)) out(line);
     if (card.parentHost) out(`부모 호스트: ${card.parentHost.host}${card.parentHost.pid ? ` (pid ${card.parentHost.pid})` : ''} · PR 까지만 — 병합은 HQ${card.parentHost.log ? ` · 로그 ${card.parentHost.host}:${card.parentHost.log}` : ''}`);