elanous 0.2.6 → 0.2.8

package/scripts/release-loop/gate-node.ts

@@ -8,7 +8,9 @@ import { debug } from '../../src/debug/log.js';
 import { effectiveInstanceRoot, releaseLedgerRoot } from '../../src/instance/resolve.js';
 import { getElanousConfigDirOverride } from '../../src/elanous-config-dir.js';
 import { diffFailures, junitFailures, parseFailures } from './gate-diff';
-import { planShards, readFileDurations } from './shard-plan';
+import { loadEnvKnownFailures, splitKnownEnv } from './env-known-failures';
+import { baselineFromCutLogs } from './baseline-from-logs';
+import { planShards, readFileDurations, readFileMemory } from './shard-plan';
 import { deriveCdpTestPatterns } from '../test-deterministic';
 import { emitNodeResult, readGraphContext } from './node-verdict.js';
 import { runPodCommand, type RunPodCommandOptions, type PodCommandResult } from '../../src/task-orchestrator/surfaces/pod-command-job.js';
@@ -16,7 +18,7 @@ import { POD_BUN_CACHE_HOST_PATH, parseInstallSeconds, podBunCacheVolume } from
 import { PodPoolScheduler, parsePodPool, checkPodPool } from '../../src/task-orchestrator/surfaces/pod-pool.js';
 import { defaultKubectl } from '../../src/task-orchestrator/surfaces/self-implement-pod.js';
 
-interface CommandResult { rc: number; output: string }
+interface CommandResult { rc: number; output: string; passedIds?: string[] }
 export interface GateRunner {
   command(cmd: string, args: string[], cwd: string): Promise<CommandResult>;
   localCommand(cmd: string, args: string[], cwd: string): Promise<CommandResult>;
@@ -38,7 +40,7 @@ export interface GateOptions {
   instanceRoot?: string;
   ledgerRoot?: string;
   repo?: string;
-  pod?: { pool: string; shards?: number; shardTimeoutSeconds?: number; durationSource?: string };
+  pod?: { pool: string; shards?: number; shardTimeoutSeconds?: number; durationSource?: string; bunCache?: string };
 }
 export interface GateResult {
   outcome: 'ok' | 'regression' | 'error';
@@ -46,7 +48,9 @@ export interface GateResult {
   introduced: string[];
   preexisting: number;
   fixed: number;
-  baselineSource?: 'ledger' | 'instance' | 'swept';
+  knownEnv: number;
+  knownEnvCleared: string[];
+  baselineSource?: 'ledger' | 'instance' | 'cut-logs' | 'swept';
   durationMs: number;
   error?: string;
   stalledShards?: Array<{ shard: number; files: string[]; reason: 'incomplete' | 'no-output' | 'job-failed' | 'unattributed'; lastFile?: string; summaryFailures?: number; namedFailures?: number; detail?: string }>;
@@ -64,6 +68,38 @@ function check(result: CommandResult, label: string): void {
 }
 
 type SweepFailures = { failures: string[]; errors: string[] };
+
+/** Only named, completed JUnit cases can prove a listed failure passed in this cut. */
+function junitPassedIds(xml: string): string[] {
+  const passed = new Set<string>();
+  const suites: string[] = [];
+  let file: string | undefined;
+  let open: { id: string; passed: boolean } | undefined;
+  const decode = (value: string) => value.replace(/&(?:quot|apos|lt|gt|amp|#\d+|#x[\da-fA-F]+);/g, (entity) => {
+    const named: Record<string, string> = { '&quot;': '"', '&apos;': "'", '&lt;': '<', '&gt;': '>', '&amp;': '&' };
+    if (entity in named) return named[entity]!;
+    const code = entity.startsWith('&#x') ? Number.parseInt(entity.slice(3, -1), 16) : Number(entity.slice(2, -1));
+    return code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : entity;
+  });
+  for (const match of xml.matchAll(/<(\/?)\s*(testsuite|testcase|failure|error|skipped)\b([^>]*?)(\/?)>/g)) {
+    const [, closing, tag, attrs, selfClosing] = match;
+    const attr = (name: string) => { const found = new RegExp(`\\b${name}="([^"]*)"`).exec(attrs!); return found ? decode(found[1]!) : undefined; };
+    if (tag === 'testsuite') {
+      if (closing) { suites.pop(); if (!suites.length) file = undefined; }
+      else if (!selfClosing) { suites.push(attr('name') ?? ''); if (suites.length === 1) file = attr('file') ?? attr('name'); }
+    } else if (tag === 'testcase') {
+      if (closing) { if (open?.passed) passed.add(open.id); open = undefined; }
+      else {
+        const name = [...suites.slice(1), attr('name') ?? ''].join(' > ');
+        const path = attr('file') ?? file;
+        const id = path && name ? `${path} > ${name}` : undefined;
+        if (selfClosing) { if (id) passed.add(id); }
+        else open = id ? { id, passed: true } : undefined;
+      }
+    } else if (!closing && open) open.passed = false;
+  }
+  return [...passed].sort();
+}
 // A test may spawn a nested `bun test` whose own summary lines land earlier in the same output
 // (09-29 0.2.4 gate: «0 fail · Ran 2 tests across 1 file» at line 6765 of a 60064-test sweep) —
 // the sweep's own summary is always the «last» one, so read the last match, never the first.
@@ -76,6 +112,19 @@ const summaryCount = (output: string, label: string) => Number(lastMatch(output,
 /** bun reads a bare positional as a substring filter (`test` matches every *.test.ts); `./` makes it a path. */
 const asPath = (path: string) => path.startsWith('./') || path.startsWith('/') ? path : `./${path}`;
 export const POD_ISOLATION_MEMORY_LIMIT = '32Gi';
+/** GT1b — a file whose measured peak is at least this runs alone at the isolation limit from the start: one such file
+ *  sank a whole 203-file root shard at 16Gi (0.2.6 shard 12 · `unwired-exports` 9.9 GB) and cost two halving rounds. */
+export const POD_HEAVY_FILE_MB = 4096;
+/** Per-file peak memory, read from the cut tree (absent → no heavy files; the halving path still catches OOM). */
+export const POD_MEMORY_SOURCE = 'docs/measurements/td1-whole-gate-mechanical-2026-10-01.tsv';
+/** Integration tests that the Pod sweep does not run — each is judged by a real run elsewhere at the cut.
+ *  0.2.7 run 5 (10-01): `scripts/install.test.ts` (real `bun pm pack` → `bun add` installs, 301 s alone on node-b)
+ *  sat in a shard of its own past the 1200 s deadline with no output and stopped the whole gate. Judged on the
+ *  mbp at the cut instead (TD1 moves it to the integration line). Keep this list short and explained. */
+/** GT1 — files per retry chunk when a root shard fails (0.2.7: bundles of 54+ files OOMed at 16Gi, smaller passed). */
+export const POD_SHARD_FILE_CAP = 27;
+
+export const POD_SWEEP_INTEGRATION_ONLY: readonly string[] = ['scripts/install.test.ts'];
 const tail40 = (output: string) => output.trimEnd().split(/\r?\n/).slice(-40).join('\n');
 const lastStartedTestFile = (output: string, paths: string[]): string | undefined => {
   let last: string | undefined;
@@ -92,10 +141,15 @@ function failuresOf(run: CommandResult, label: string): SweepFailures {
   const reportedErrors = summaryCount(output, 'error');
   const errorCount = Number.isNaN(reportedErrors) ? 0 : reportedErrors;
   const incomplete = (reason: string) => new Error(`${label} incomplete (rc=${run.rc}; Ran=${ran ? ran[0] : 'missing'}; errors=${Number.isNaN(reportedErrors) ? 'missing' : errorCount}; ${reason})\n${tail40(output)}`);
-  if (!ran || (Number(ran[1]) === 0 && errorCount === 0) || (run.rc !== 0 && run.rc !== 1)) throw incomplete('summary/exit');
   const count = summaryCount(output, 'fail');
   const failures = parseFailures(output);
   const occurrences = [...output.matchAll(/\(fail\)\s+.+?(?:\s+\[[\d.]+(?:ms|s)\])?\s*$/gm)].length;
+  // A test that leaves process.exitCode set leaks a non-zero exit into a run whose own summary is complete and clean
+  // (0.2.7 gate: agent-cli at v0.2.6 · 12 pass · 0 fail · rc 2). The summary is the verdict; read that exit as clean.
+  const leakedExit = !!ran && run.rc !== 0 && run.rc !== 1 && count === 0 && errorCount === 0 && occurrences === 0
+    && !/^# Unhandled error between tests/m.test(output);
+  const rc = leakedExit ? 0 : run.rc;
+  if (!ran || (Number(ran[1]) === 0 && errorCount === 0) || (rc !== 0 && rc !== 1)) throw incomplete('summary/exit');
   // Bun reports file-level unhandled errors separately from test failures.
   const errors: string[] = [];
   let file: string | undefined;
@@ -110,7 +164,7 @@ function failuresOf(run: CommandResult, label: string): SweepFailures {
   }
   if (errors.length !== errorCount) throw incomplete(`error attribution identified=${errors.length}`);
   if (!Number.isFinite(count) || count !== occurrences || (count > 0 && failures.length === 0)
-    || (run.rc === 1 && count === 0 && errorCount === 0) || (run.rc === 0 && count + errorCount > 0)) {
+    || (rc === 1 && count === 0 && errorCount === 0) || (rc === 0 && count + errorCount > 0)) {
     throw incomplete(`failure attribution incomplete: summary=${count}, identified=${failures.length}`);
   }
   return { failures, errors: [...new Set(errors)].sort() };
@@ -156,10 +210,20 @@ export function createGateRunner(repo: string, remote?: string, commandOverride?
     const cdpPatterns = cdp.output.split(/\r?\n/).filter((path) => path.endsWith('.test.ts'));
     // CDP 시험은 `test:deterministic` 이 스스로 뺀다 — 조각에 그것만 남으면 bun «시험 없음» exit 1 을 «불완전»으로 읽었다(09-30 G1d 실측 둘).
     // bun 의 탐색은 숨은 디렉터리(`.x/`)를 안 연다 — 사람의 `bun test` 가 한 번도 안 돌리는 빈 픽스처가 조각에 혼자 남아 «Ran 0 tests» 를 «불완전»으로 읽었다(09-30 G1e 5번 조각).
-    const assignable = files.filter((file) => !cdpPatterns.includes(file) && !file.split('/').some((part) => part.startsWith('.')));
+    const assignable = files.filter((file) => !cdpPatterns.includes(file) && !POD_SWEEP_INTEGRATION_ONLY.includes(file)
+      && !file.split('/').some((part) => part.startsWith('.')));
+    const integrationOnly = files.filter((file) => POD_SWEEP_INTEGRATION_ONLY.includes(file));
+    if (integrationOnly.length) debug.log('release-loop.gate', 'pod-sweep-integration-only', { files: integrationOnly });
     if (!assignable.length) throw new Error('sweep incomplete: no tests ran');
     const durations = pod.durationSource ? readFileDurations(pod.durationSource) : new Map<string, number>();
-    const shards = planShards(assignable, durations, shardCount);
+    const memory = readFileMemory(join(tree, POD_MEMORY_SOURCE));
+    const heavy = new Set(assignable.filter((file) => (memory.get(file) ?? 0) >= POD_HEAVY_FILE_MB));
+    const light = assignable.filter((file) => !heavy.has(file));
+    const shards = [
+      ...(light.length ? planShards(light, durations, shardCount) : []),
+      ...[...heavy].map((file) => ({ files: [file], plannedSeconds: durations.get(file) ?? 0 })),
+    ];
+    if (heavy.size) debug.log('release-loop.gate', 'pod-heavy-alone', { files: [...heavy], thresholdMb: POD_HEAVY_FILE_MB, memoryLimit: POD_ISOLATION_MEMORY_LIMIT });
     const known = assignable.filter((file) => durations.has(file)).length;
     debug.log('release-loop.gate', 'pod-shard-plan', {
       shards: shards.length, known, unknown: assignable.length - known,
@@ -169,7 +233,10 @@ export function createGateRunner(repo: string, remote?: string, commandOverride?
     const ready = poolOverride ? undefined : checkPodPool(parsePodPool(pod.pool), defaultKubectl);
     if (ready && !ready.ok) throw new Error('pod command: 풀의 노드가 하나도 준비되지 않았다');
     const poolScheduler = poolOverride ?? new PodPoolScheduler(ready!.ready);
-    const bunCache = process.env[POD_BUN_CACHE_HOST_PATH]?.trim() || undefined;
+    const configCache = typeof pod.bunCache === 'string' ? pod.bunCache.trim() : '';
+    const envCache = process.env[POD_BUN_CACHE_HOST_PATH]?.trim();
+    const bunCache = configCache || envCache || undefined;
+    debug.log('release-loop.gate', 'pod-bun-cache', { source: configCache ? 'config' : envCache ? 'env' : 'none' });
     const cachePrefix = bunCache ? `${podBunCacheVolume(bunCache).shellPrefix} ` : '';
     const jobLogTail = (job: PodCommandResult): string => {
       if (podLogTail) return podLogTail(job);
@@ -179,7 +246,7 @@ export function createGateRunner(repo: string, remote?: string, commandOverride?
       }
       return '';
     };
-    type ShardRun = { output: string; rc: number; pass: number; fail: number; errors: number; ran: number; files: number };
+    type ShardRun = { output: string; rc: number; pass: number; fail: number; errors: number; ran: number; files: number; passedIds: string[] };
     type ShardReason = NonNullable<GateResult['stalledShards']>[number]['reason'];
     // 깊이 끝 OOM 조각은 «조각 전체»를 파일 하나씩 격리한다 — 상한 40 이면 나머지가 못 잰 채 남았다(09-30 ① 7번 조각 110 파일).
     const isolationRemaining = shards.map((item) => item.files.length);
@@ -207,7 +274,7 @@ export function createGateRunner(repo: string, remote?: string, commandOverride?
           pool: pod.pool, poolScheduler, clone: true, source: { kind: 'commit', sha: commit }, deadlineSeconds,
           ...(bunCache ? { bunCache } : {}),
           // 실패 뒤 다시 도는 파일 하나짜리 Job 은 메모리 한도를 올린다 — 16Gi 에선 무거운 한 파일이 혼자서도 OOM 이었다(09-30 `unwired-exports`).
-          ...(paths.length === 1 && depth >= 1 ? { memoryLimit: POD_ISOLATION_MEMORY_LIMIT } : {}),
+          ...(paths.length === 1 && (depth >= 1 || heavy.has(paths[0]!)) ? { memoryLimit: POD_ISOLATION_MEMORY_LIMIT } : {}),
           name: `gate-${randomUUID()}`,
           command: ['bash', '-lc', `mkdir -p "$HOME/outbox"; ${cachePrefix}(cd .. && cd repo && bun install && (cd apps/pwa && bun install) && ${args}) 2>&1 | tee "$HOME/outbox/shard.log"; echo \${PIPESTATUS[0]} > "$HOME/outbox/shard.rc"`],
         });
@@ -233,7 +300,7 @@ export function createGateRunner(repo: string, remote?: string, commandOverride?
         const destination = join(logDir, `pod-${shard}${branch}.log`);
         if (output !== undefined) writeFileSync(destination, output, { mode: 0o600 });
         else rmSync(destination, { force: true });
-        writeFileSync(join(logDir, `pod-${shard}${branch}.json`), JSON.stringify({ durationMs, rc: rc ?? null, files: paths, plannedSeconds: estimated(paths) }) + '\n', { mode: 0o600 });
+        writeFileSync(join(logDir, `pod-${shard}${branch}.json`), JSON.stringify({ durationMs, rc: rc ?? null, files: paths, plannedSeconds: estimated(paths), shardCount: shards.length, commit }) + '\n', { mode: 0o600 });
         const junitDestination = join(logDir, `pod-${shard}${branch}.junit.xml`);
         if (junit !== undefined) writeFileSync(junitDestination, junit, { mode: 0o600 });
         else rmSync(junitDestination, { force: true });
@@ -298,6 +365,15 @@ export function createGateRunner(repo: string, remote?: string, commandOverride?
           ...(lastFile ? { lastFile } : {}),
           ...(reason === 'unattributed' ? { summaryFailures: fails, namedFailures, ...(unattributedDetail ? { detail: unattributedDetail } : {}) } : {}),
         }] };
+        // GT1 — a big shard that failed at the root goes straight to cap-sized chunks instead of halving twice: memory
+        // piles up when one bun process runs many files (0.2.7: only bundles of 54+ OOMed), and each halving round costs
+        // a Pod start, an install and a rerun. A failing chunk then isolates its files (depth 2), as before.
+        if (depth === 0 && paths.length > POD_SHARD_FILE_CAP) {
+          const chunks = Array.from({ length: Math.ceil(paths.length / POD_SHARD_FILE_CAP) }, (_, i) => paths.slice(i * POD_SHARD_FILE_CAP, (i + 1) * POD_SHARD_FILE_CAP));
+          debug.log('release-loop.gate', 'pod-shard-cap-split', { shard, files: paths.length, chunks: chunks.length, cap: POD_SHARD_FILE_CAP, reason });
+          const children = await Promise.all(chunks.map((chunk, i) => runShard(chunk, shard, 2, `${branch}-c${i}`)));
+          return { runs: children.flatMap((child) => child.runs), stalled: children.flatMap((child) => child.stalled) };
+        }
         debug.log('release-loop.gate', 'pod-shard-split', { shard, depth, files: paths, reason });
         const middle = Math.ceil(paths.length / 2);
         const children = await Promise.all([
@@ -308,7 +384,7 @@ export function createGateRunner(repo: string, remote?: string, commandOverride?
       }
       return { runs: [{ output: clean!, rc: rc!, pass: passes, fail: fails,
         errors: Number.isNaN(summaryCount(clean!, 'error')) ? 0 : summaryCount(clean!, 'error'),
-        ran: Number(ran![1]), files: Number(ran![2]) }], stalled: [] };
+        ran: Number(ran![1]), files: Number(ran![2]), passedIds: junit ? junitPassedIds(junit) : [] }], stalled: [] };
     };
     // 모든 조각이 끝난 뒤 판정한다 — 한 조각의 예외로 먼저 돌아가면 다른 Pod 가 도는 채로 정리가 시작된다(#22002 리뷰 R3).
     const settled = await Promise.allSettled(shards.map((item, shard) => runShard(item.files, shard)));
@@ -323,7 +399,8 @@ export function createGateRunner(repo: string, remote?: string, commandOverride?
     if (stalledShards.length) throw new StalledPodShards(stalledShards, total);
     if (total.ran === 0 && total.errors === 0) throw new Error('sweep incomplete: no tests ran');
     const outputs = measured.map((run) => run.output.replace(/(?:^|\n)\s*\d+ (?:pass|fail|errors?)\s*(?=\n|$)/g, '\n').replace(/Ran \d+ tests? across \d+ files?\.?/g, ''));
-    return { rc: total.fail + total.errors ? 1 : 0, output: outputs.join('\n') + `\n${total.pass} pass\n${total.fail} fail\n${total.errors} errors\nRan ${total.ran} tests across ${total.files} files.\n` };
+    return { rc: total.fail + total.errors ? 1 : 0, output: outputs.join('\n') + `\n${total.pass} pass\n${total.fail} fail\n${total.errors} errors\nRan ${total.ran} tests across ${total.files} files.\n`,
+      passedIds: [...new Set(measured.flatMap((run) => run.passedIds))].sort() };
   };
   return {
     command,
@@ -455,7 +532,7 @@ export async function judgeGate(opts: GateOptions, runner: GateRunner = createGa
     return baselineCommit(root, version);
   };
   const repo = resolve(opts.repo ?? process.cwd());
-  const result: GateResult = { outcome: 'error', commit: opts.commit, introduced: [], preexisting: 0, fixed: 0, durationMs: 0 };
+  const result: GateResult = { outcome: 'error', commit: opts.commit, introduced: [], preexisting: 0, fixed: 0, knownEnv: 0, knownEnvCleared: [], durationMs: 0 };
   let work: string | undefined;
   let baseSnapshot = false;
   let cutFailures: SweepFailures | undefined;
@@ -510,8 +587,9 @@ export async function judgeGate(opts: GateOptions, runner: GateRunner = createGa
     cutFailures = cut;
     const baseSha = opts.baselineCommit ?? baselineReleaseCommit(opts.baselineVersion);
     const cached = cachedBaseline(opts.baselineVersion, baseSha);
-    const trusted = cached?.saved;
-    result.baselineSource = trusted ? cached!.source : 'swept';
+    const recorded = cached ? undefined : baselineFromCutLogs(join(ledger, 'release', opts.baselineVersion, 'gate-logs', 'cut'), baseSha);
+    const trusted = cached?.saved ?? (recorded?.complete ? recorded : undefined);
+    result.baselineSource = cached ? cached.source : recorded?.complete ? 'cut-logs' : 'swept';
     debug.log('release-loop.gate', 'baseline', { version: opts.baselineVersion, source: result.baselineSource, commit: baseSha });
     let baseTree: string | undefined;
     const getBaseTree = async () => {
@@ -534,7 +612,14 @@ export async function judgeGate(opts: GateOptions, runner: GateRunner = createGa
       baseline = failuresOf(baseRun, 'baseline sweep');
     }
     for (const id of [...baseline.failures, ...baseline.errors, ...cut.failures, ...cut.errors]) fileOf(id);
-    const diff = diffFailures([...cut.failures, ...cut.errors], [...baseline.failures, ...baseline.errors]);
+    const known = opts.pod ? loadEnvKnownFailures(repo) : new Set<string>();
+    const cutIds = [...cut.failures, ...cut.errors];
+    const baselineIds = [...baseline.failures, ...baseline.errors];
+    const countedCut = splitKnownEnv(cutIds, known);
+    const countedBaseline = splitKnownEnv(baselineIds, known);
+    result.knownEnv = countedCut.knownEnv.length;
+    result.knownEnvCleared = [...new Set(cutRun.passedIds ?? [])].filter((id) => known.has(id) && !cutIds.includes(id)).sort();
+    const diff = diffFailures(countedCut.counted, countedBaseline.counted);
     result.fixed = diff.fixed.length;
     result.preexisting = diff.common.length;
     for (const file of new Set(diff.newFailures.map(fileOf))) {
@@ -584,7 +669,7 @@ export async function judgeGate(opts: GateOptions, runner: GateRunner = createGa
     if (opts.remote) runner.remoteMirror = undefined;
     result.durationMs = Date.now() - start;
   }
-  if (result.outcome !== 'error' && cutFailures) {
+  if (cutFailures && !result.stalledShards?.length) {
     try {
       for (const location of roots) {
         const path = failureFile(location, opts.version);
@@ -608,10 +693,10 @@ export async function judgeGate(opts: GateOptions, runner: GateRunner = createGa
 export function graphGateResult(result: GateResult, graph: boolean) {
   return { ...result, ...(graph && result.outcome === 'regression' ? { outcome: 'fail' as const } : {}),
     verdict: result.outcome === 'ok' ? 'pass' as const : 'fail' as const,
-    summary: result.outcome === 'ok' ? `새 회귀 ${result.introduced.length} · 기존 ${result.preexisting} · 고침 ${result.fixed}` : `게이트 ${result.outcome}: ${result.error ?? result.introduced.length + ' new regressions'}` };
+    summary: (result.outcome === 'ok' ? `새 회귀 ${result.introduced.length} · 기존 ${result.preexisting} · 고침 ${result.fixed}` : `게이트 ${result.outcome}: ${result.error ?? result.introduced.length + ' new regressions'}`) + ` · 환경 알려진 실패 ${result.knownEnv}` };
 }
 
-function parseOptions(args: string[], env: NodeJS.ProcessEnv): GateOptions | 'help' {
+export function parseOptions(args: string[], env: NodeJS.ProcessEnv): GateOptions | 'help' {
   const context = env.ELANOUS_GRAPH_CONTEXT && args.every((arg) => arg === '--json') ? readGraphContext(env) : undefined;
   const fromGraph: Record<string, unknown> = context?.input ?? {};
   const graphCommit = context?.outputs['version-release']?.commit;
@@ -629,6 +714,7 @@ function parseOptions(args: string[], env: NodeJS.ProcessEnv): GateOptions | 'he
       pool: fromGraph.gatePodPool,
       ...(fromGraph.gatePodShards !== undefined ? { shards: Number(fromGraph.gatePodShards) } : {}),
       ...(fromGraph.gatePodShardTimeoutSeconds !== undefined ? { shardTimeoutSeconds: Number(fromGraph.gatePodShardTimeoutSeconds) } : {}),
+      ...(typeof fromGraph.gatePodBunCache === 'string' && fromGraph.gatePodBunCache.trim() ? { bunCache: fromGraph.gatePodBunCache } : {}),
     } : undefined,
   };
   for (let i = 0; i < args.length; i++) {
@@ -665,7 +751,7 @@ if (import.meta.main) {
     version = opts.version;
     result = await judgeGate(opts);
   } catch (error) {
-    result = { outcome: 'error', commit: '', introduced: [], preexisting: 0, fixed: 0, durationMs: Date.now() - start, error: String(error) };
+    result = { outcome: 'error', commit: '', introduced: [], preexisting: 0, fixed: 0, knownEnv: 0, knownEnvCleared: [], durationMs: Date.now() - start, error: String(error) };
   }
   if (result.error) console.error(result.error);
   debug.log('release-loop.gate', 'result', { version, outcome: result.outcome });

package/scripts/release-loop/known-issues-node.ts

@@ -0,0 +1,159 @@
+#!/usr/bin/env bun
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { emitNodeResult, readGraphContext, runCommand, type CommandRunner, type GraphContext } from './node-verdict.js';
+
+const FALLBACK = 'Known issues have been reported for this release.';
+// No fix schedule is promised here — the inputs do not carry one (review R2).
+const INTRO = 'The following issues are known in this release.';
+// A known-issues bullet describes a problem that is still there; «fixed / resolved» wording turns it into a false claim.
+const resolved = /\b(?:fixed|resolved|no longer|has been addressed|is addressed|was addressed)\b/i;
+const unsafe = /[^\x20-\x7e]|#\d+|\/Users\/|\.test\.ts\b|\[(?:TC|MK|OP|UX|S|T|F|O)\]|\b(?:TC|MK|OP|UX)\s+track\b|\b(?:PR|pull request)\s*\d+\b|\b(?:scripts|src|test)\/\S+|\bfile:\/\/|(?<![\w:/])\/(?!\/)[\w.-]+(?:\/[\w.-]+)*|\b[A-Z]:\\(?:[^\s\\]+\\)*[^\s\\]+|\b(?:RFC|HANDOFF|MANUAL)-/i;
+
+type Issue = { id: string; title?: string; evidence?: string; note?: string };
+
+function issues(value: unknown, kind: 'checklist' | 'accepted'): Issue[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || !value.every((item) => item && typeof item === 'object'
+    && typeof item.id === 'string' && item.id.trim()
+    && (kind === 'checklist' ? typeof item.title === 'string' && typeof item.evidence === 'string' : typeof item.note === 'string'))) {
+    throw new Error(`invalid ${kind} known issues`);
+  }
+  return value as Issue[];
+}
+
+function generatedBullets(raw: string, sourceIds: string[]): string[] {
+  const envelope: unknown = JSON.parse(raw.trim());
+  const reply = envelope && typeof envelope === 'object' && !Array.isArray(envelope) && 'reply' in envelope
+    ? envelope.reply : envelope;
+  if (typeof reply !== 'string') throw new Error('empty ask reply');
+  const entries: unknown = JSON.parse(reply.replace(/^```(?:json)?\s*\n|\n```\s*$/g, '').trim());
+  if (!Array.isArray(entries) || entries.length !== sourceIds.length || new Set(sourceIds).size !== sourceIds.length) {
+    throw new Error('known issues response does not cover every input ID');
+  }
+  const byId = new Map<string, string>();
+  for (const entry of entries) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)
+      || typeof entry.id !== 'string' || typeof entry.bullet !== 'string'
+      || byId.has(entry.id) || !sourceIds.includes(entry.id)) {
+      throw new Error('known issues response does not cover every input ID');
+    }
+    byId.set(entry.id, entry.bullet);
+  }
+  if (sourceIds.some((id) => !byId.has(id))) throw new Error('known issues response does not cover every input ID');
+  return sourceIds.map((id) => byId.get(id)!);
+}
+
+function coversIssue(bullet: string, issue: Issue, others: Issue[]): boolean {
+  const source = issue.title ?? issue.note ?? '';
+  const words = source.toLowerCase().match(/[a-z]{5,}/g) ?? [];
+  const otherWords = new Set(others.flatMap((other) => ((other.title ?? other.note ?? '').toLowerCase().match(/[a-z]{5,}/g) ?? []).map((word) => word.slice(0, 5))));
+  const publicWords = new Set((bullet.toLowerCase().match(/[a-z]{5,}/g) ?? []).map((word) => word.slice(0, 5)));
+  const distinctive = [...new Set(words.map((word) => word.slice(0, 5)))].filter((word) => !otherWords.has(word));
+  const negative = /\b(?:not|never|no|cannot|can't|doesn't|don't|won't|fails? to|isn't|aren't)\b/i;
+  if (negative.test(source) && !negative.test(bullet)) return false;
+  // A source with no English words to compare (e.g. a Korean checklist title) is covered structurally —
+  // one bullet per input ID — instead of blocking the release (review R2).
+  if (words.length === 0) return true;
+  return distinctive.length > 0 && distinctive.filter((word) => publicWords.has(word)).length >= Math.min(issue.note === undefined ? 1 : 2, distinctive.length);
+}
+
+function cleanBullet(text: string): string | null {
+  const line = text.trim();
+  if (!line || /^[-*]\s/.test(line) || unsafe.test(line) || /[{}<>\[\]`]/.test(line) || (line.match(/[.!?](?:\s|$)/g) ?? []).length > 2) return null;
+  return line;
+}
+
+function command(run: CommandRunner, program: string, args: string[], cwd?: string): string {
+  const result = run(program, args, cwd);
+  if (result.status !== 0) throw new Error(`${program} ${args[0]} failed: ${result.stderr || result.stdout}`);
+  return result.stdout;
+}
+
+export function runKnownIssues(context: GraphContext = readGraphContext(), run: CommandRunner = runCommand) {
+  const version = context.input.version;
+  const worktree = context.outputs.docs?.worktree;
+  if (typeof worktree !== 'string' || !worktree || !existsSync(worktree)) throw new Error('docs 워크트리 없음');
+  if (context.outputs.docs?.branch !== `release-docs/${version}`) throw new Error('docs branch/version mismatch');
+  const notes = join(worktree, 'release/public/docs/releases', `${version}.md`);
+  if (!existsSync(notes)) throw new Error(`release notes missing: ${notes}`);
+  const checklist = issues(context.outputs['checklist-gate']?.knownIssues, 'checklist');
+  const accepted = issues(context.input.acceptedRegressions, 'accepted');
+  const sources = { checklist: checklist.length, accepted: accepted.length };
+  if (!checklist.length && !accepted.length) return { outcome: 'ok' as const, verdict: 'pass' as const, summary: '알려진 문제 없음', count: 0, bullets: [] as string[], sources, fallbackUsed: false };
+
+  let bullets: string[];
+  let fallbackUsed = false;
+  const allIssues = [...checklist, ...accepted];
+  const sourceIds = allIssues.map((issue) => issue.id);
+  const prompt = `Write public English release-note bullets for these known issues. Describe only user-visible impact; include a one-line workaround when available. No internal names, test paths, track names, PR numbers, or people. Each bullet must have at most two sentences. Return ONLY a JSON array with exactly one object {"id":"input ID","bullet":"English public sentence"} for each input, using each input ID exactly once. Do not include IDs in bullet text. Input: ${JSON.stringify({ checklist, acceptedRegressions: accepted })}`;
+  let response: ReturnType<CommandRunner>;
+  try {
+    response = run('elanous', ['--test', 'ask', '--json', prompt]);
+  } catch {
+    response = { status: 1, stdout: '', stderr: '' };
+  }
+  if (response.status !== 0) {
+    bullets = [FALLBACK];
+    fallbackUsed = true;
+  } else {
+    try {
+      bullets = generatedBullets(response.stdout, sourceIds).map((line, index) => {
+        const safe = cleanBullet(line);
+        if (!safe) {
+          fallbackUsed = true;
+          return FALLBACK;
+        }
+        if (resolved.test(safe)) throw new Error(`bullet for ${sourceIds[index]} claims the issue is resolved`);
+        if (!coversIssue(safe, allIssues[index]!, allIssues.filter((_, otherIndex) => otherIndex !== index))) {
+          throw new Error(`bullet does not identify input ${sourceIds[index]}`);
+        }
+        return safe;
+      });
+      if (new Set(bullets).size !== bullets.length && bullets.some((bullet) => bullet !== FALLBACK)) {
+        throw new Error('known issues response repeats an issue instead of covering each input');
+      }
+      bullets = [...new Set(bullets)];
+    } catch (error) {
+      throw new Error(`known issues coverage not verified: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  const original = readFileSync(notes, 'utf8');
+  const heading = /^## Known issues\s*$/m;
+  const match = heading.exec(original);
+  let updated: string;
+  if (match) {
+    const start = match.index + match[0].length;
+    const next = /^## /gm;
+    next.lastIndex = start;
+    const end = next.exec(original)?.index ?? original.length;
+    const section = original.slice(start, end);
+    const additions = bullets.filter((bullet) => !section.split(/\r?\n/).some((line) => line.trim() === `- ${bullet}`));
+    const before = original.slice(0, end);
+    updated = additions.length ? `${before}${before.endsWith('\n') ? '' : '\n'}${additions.map((bullet) => `- ${bullet}`).join('\n')}\n\n${original.slice(end)}` : original;
+  } else {
+    updated = `${original.trimEnd()}\n\n## Known issues\n\n${INTRO}\n\n${bullets.map((bullet) => `- ${bullet}`).join('\n')}\n`;
+  }
+  if (updated !== original) {
+    writeFileSync(notes, updated);
+    command(run, 'git', ['add', '--', `release/public/docs/releases/${version}.md`], worktree);
+    command(run, 'git', ['commit', '-m', `docs: known issues for ${version}`], worktree);
+  }
+  // Push whenever the branch is ahead of its remote — a rerun after a failed push finds the bullets already in the file (review R2).
+  command(run, 'git', ['fetch', 'origin', `release-docs/${version}`], worktree);
+  const ahead = Number(command(run, 'git', ['rev-list', '--count', `origin/release-docs/${version}..HEAD`], worktree).trim());
+  if (!Number.isFinite(ahead)) throw new Error('could not compare release-docs branch with its remote');
+  if (ahead > 0) command(run, 'git', ['push', 'origin', `release-docs/${version}`], worktree);
+  return { outcome: 'ok' as const, verdict: 'pass' as const, summary: `known issues: ${bullets.length}`, count: bullets.length, bullets, sources, fallbackUsed };
+}
+
+if (import.meta.main) {
+  try {
+    const result = runKnownIssues();
+    emitNodeResult(result);
+    process.exitCode = 0;
+  } catch (error) {
+    emitNodeResult({ outcome: 'fail', verdict: 'fail', summary: error instanceof Error ? error.message : String(error), count: 0, bullets: [], sources: { checklist: 0, accepted: 0 }, fallbackUsed: false });
+    process.exitCode = 1;
+  }
+}

package/scripts/release-loop/npm-publish-node.ts

@@ -0,0 +1,124 @@
+#!/usr/bin/env bun
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { debug } from '../../src/debug/log.js';
+import { sendOutbound } from '../../src/domains/outbound-alert.js';
+import { effectiveInstanceRoot, prodInstanceRoot } from '../../src/instance/resolve.js';
+import { emitNodeResult, readGraphContext, type GraphContext } from './node-verdict.js';
+
+type Result = { outcome: 'ok' | 'fail'; verdict: 'pass' | 'fail'; summary: string; npm?: 'published' | 'already-published' | 'staged-not-visible'; humanAction?: 'npm-support' };
+type Exec = (command: string, args: string[], env?: NodeJS.ProcessEnv) => { status: number | null; stdout: string; stderr: string };
+type Registry = (url: string) => Promise<{ status: number; body: unknown }>;
+export interface NpmPublishDeps {
+  exec?: Exec;
+  registry?: Registry;
+  sleep?: (ms: number) => Promise<void>;
+  stateDir?: string;
+  /** Test seam — the production root whose secrets/npm-token is the last fallback. */
+  productionRoot?: string;
+  alert?: (text: string, kind: string) => boolean;
+  log?: (version: string, waitedMinutes: number) => void;
+}
+
+const exec: Exec = (command, args, env) => {
+  const result = spawnSync(command, args, { encoding: 'utf8', env: env ?? process.env, maxBuffer: 1024 * 1024, timeout: 300_000 });
+  return { status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? String(result.error ?? '') };
+};
+const registry: Registry = async (url) => {
+  const response = await fetch(url, { headers: { accept: 'application/json' }, signal: AbortSignal.timeout(15_000) });
+  return { status: response.status, body: response.ok ? await response.json() : null };
+};
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+const PACKAGE_URL = 'https://registry.npmjs.org/elanous';
+
+function redact(text: string, token: string): string {
+  return token ? text.replaceAll(token, '[REDACTED]') : text;
+}
+function reason(error: unknown, token: string): string {
+  return redact(error instanceof Error ? error.message : String(error), token).replace(/[\r\n]+/g, ' ').slice(0, 500);
+}
+function metadata(value: unknown): { name?: string; version?: string } {
+  if (!value || typeof value !== 'object') return {};
+  return value as { name?: string; version?: string };
+}
+
+export async function runNpmPublish(context: GraphContext = readGraphContext(), deps: NpmPublishDeps = {}): Promise<Result> {
+  const version = context.input.version;
+  let token = '';
+  try {
+    if (context.outputs.publish?.outcome !== 'ok') throw new Error('publish must succeed before npm publish');
+    const stateDir = deps.stateDir ?? effectiveInstanceRoot();
+    // REL3 — the archive prepare actually built (its output) wins over this process's universe: a resumed run can
+    // resolve another universe (10-01 0.2.7: prepared in the pilot test universe, resumed in production).
+    const prepared = context.outputs.prepare?.candidate;
+    const candidate = typeof prepared === 'string' && prepared.endsWith('.tgz') ? prepared : join(stateDir, 'release', version, 'prepared', 'dist', 'elanous.tgz');
+    const run = deps.exec ?? exec;
+    const readRegistry = deps.registry ?? registry;
+    const wait = deps.sleep ?? sleep;
+    const waitMinutes = context.input.npmWaitMinutes ?? 40;
+    if (typeof waitMinutes !== 'number' || !Number.isFinite(waitMinutes) || waitMinutes < 0 || waitMinutes > 40) throw new Error('input.npmWaitMinutes must be between 0 and 40');
+    const archive = run('tar', ['-xOzf', candidate, 'package/package.json']);
+    if (archive.status !== 0) throw new Error(`npm archive invalid: ${archive.stderr}`);
+    const pkg = metadata(JSON.parse(archive.stdout));
+    if (pkg.name !== 'elanous' || pkg.version !== version) throw new Error('npm archive package name/version mismatch');
+    const inspect = async (): Promise<{ visible: boolean; tagged: boolean }> => {
+      const [manifest, tags] = await Promise.all([readRegistry(`${PACKAGE_URL}/${version}`), readRegistry(PACKAGE_URL)]);
+      if (manifest.status !== 200 && manifest.status !== 404) throw new Error(`npm registry version lookup failed (${manifest.status})`);
+      if (tags.status !== 200) throw new Error(`npm registry tags lookup failed (${tags.status})`);
+      const latest = tags.body && typeof tags.body === 'object' && 'dist-tags' in tags.body
+        ? (tags.body as { 'dist-tags'?: { latest?: unknown } })['dist-tags']?.latest : undefined;
+      if (manifest.status === 200 && (metadata(manifest.body).name !== 'elanous' || metadata(manifest.body).version !== version))
+        throw new Error('npm registry version metadata mismatch');
+      return { visible: manifest.status === 200, tagged: manifest.status === 200 && latest === version };
+    };
+    const before = await inspect();
+    if (before.tagged) return { outcome: 'ok', verdict: 'pass', npm: 'already-published', summary: `npm ${version} already published with latest tag` };
+    if (!before.visible) {
+      // The npm token is a machine secret (like the GitHub App key): input → this universe → the production root.
+      const tokenFile = context.input.npmTokenFile ?? [join(stateDir, 'secrets', 'npm-token'), join(deps.productionRoot ?? prodInstanceRoot(), 'secrets', 'npm-token')].find((p) => existsSync(p)) ?? join(stateDir, 'secrets', 'npm-token');
+      if (typeof tokenFile !== 'string' || !tokenFile.trim()) throw new Error('input.npmTokenFile must be a path');
+      token = readFileSync(tokenFile, 'utf8').trim();
+      if (!token) throw new Error('npm token file empty');
+      const dir = mkdtempSync(join(tmpdir(), 'release-npmrc-'));
+      let published;
+      try {
+        const npmrc = join(dir, 'npmrc');
+        writeFileSync(npmrc, `//registry.npmjs.org/:_authToken=${token}\n`, { mode: 0o600, flag: 'wx' });
+        published = run('npm', ['publish', candidate, '--ignore-scripts', '--tag', 'latest', '--access', 'public'], { ...process.env, NPM_CONFIG_USERCONFIG: npmrc });
+      } finally { rmSync(dir, { recursive: true, force: true }); }
+      const output = `${published.stdout}\n${published.stderr}`;
+      const staged = published.status !== 0 && /\bE409\b/i.test(output) && /previously staged/i.test(output);
+      if (published.status !== 0 && !staged) throw new Error(`npm publish failed (rc=${published.status}): ${redact(output, token)}`);
+    }
+    const polls = Math.ceil(waitMinutes * 60 / 30);
+    let last = before;
+    for (let i = 0; i <= polls; i++) {
+      last = await inspect();
+      if (last.tagged) return { outcome: 'ok', verdict: 'pass', npm: before.visible ? 'already-published' : 'published', summary: `npm ${version} visible with latest tag` };
+      if (i < polls) await wait(Math.min(30_000, waitMinutes * 60_000 - i * 30_000));
+    }
+    if (last.visible) throw new Error(`npm ${version} visible but dist-tags.latest did not reach ${version} within ${waitMinutes} minutes`);
+    try { (deps.log ?? ((v, minutes) => debug.log('release-loop.npm', 'staged-not-visible', { version: v, waitedMinutes: minutes })))(version, waitMinutes); } catch { /* observation must not mask npm's staged state */ }
+    try { (deps.alert ?? sendOutbound)(`npm ${version} 가 스테이징에 멈춤 — 계정 소유자 확인 필요`, 'alert'); } catch { /* alert failure must not block docs */ }
+    return { outcome: 'ok', verdict: 'pass', npm: 'staged-not-visible', humanAction: 'npm-support', summary: 'npm 스테이징 — 레지스트리에 아직 없음' };
+  } catch (error) {
+    return { outcome: 'fail', verdict: 'fail', summary: `npm ${version} failed: ${reason(error, token)}` };
+  }
+}
+
+if (import.meta.main) {
+  let version = '';
+  try {
+    const context = readGraphContext();
+    version = context.input.version;
+    const result = await runNpmPublish(context);
+    debug.log('release-loop.npm', 'result', { version, outcome: result.outcome, npm: result.npm });
+    emitNodeResult(result);
+    process.exitCode = result.outcome === 'ok' ? 0 : 1;
+  } catch {
+    emitNodeResult({ outcome: 'fail', verdict: 'fail', summary: 'npm publish context unavailable' });
+    process.exitCode = 1;
+  }
+}