elanous 0.2.22 → 0.2.23

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

@@ -1,15 +1,15 @@
 #!/usr/bin/env bun
-import { chmodSync, existsSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
-import { randomUUID } from 'node:crypto';
-import { spawnSync } from 'node:child_process';
-import { mkdtempSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { spawn, spawnSync } from 'node:child_process';
+import { isAbsolute, basename, dirname, join, resolve } from 'node:path';
 import { tmpdir } from 'node:os';
-import { basename, dirname, join, resolve } from 'node:path';
 import { debug } from '../../src/debug/log.js';
 import { effectiveInstanceRoot } from '../../src/instance/resolve.js';
 import type { ReleaseManifest } from '../../src/release-loop/manifest.js';
 import { flipNextReleaseMarkers, foldPreLandedNotes, renderReleaseNotes } from './release-docs.js';
-import { emitNodeResult, readGraphContext } from './node-verdict.js';
+import { emitNodeResult, lastResult, nodeOutput, readGraphContext, type GraphContext } from './node-verdict.js';
+import { reusableTui, withTuiOutcome } from './tui-node-checks.js';
 
 interface DocsResult {
   outcome: 'ok' | 'error';
@@ -126,47 +126,262 @@ export function runDocs(
   }
 }
 
-if (import.meta.main) {
-  let result: DocsResult | undefined;
-  const graphContext = process.env.ELANOUS_GRAPH_CONTEXT;
-  let isReleaseGraph = false;
+// Prefetch artifacts live alongside THIS graph run's numbered context files, never in a global version cache.
+const SHA = /^[0-9a-f]{40}$/i;
+const PREFETCH_DEADLINE_MS = 15 * 60_000;
+type Cut = { version: string; commit: string; manifestHash: string };
+type PrefetchCache = Cut & { main: string; tree: string; docs: DocsResult; tui: Record<string, unknown> | null };
+type Runner = (command: string, args: string[], cwd?: string, timeout?: number, env?: NodeJS.ProcessEnv) => string;
+export const commandRunner: Runner = (command, args, cwd, timeout, env) => {
+  const output = spawnSync(command, args, { cwd, env: env ?? process.env, timeout: timeout ?? 15 * 60_000, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
+  if (output.status !== 0 || output.error) throw new Error(`${command} ${args[0]} failed: ${output.error ?? output.stderr ?? output.stdout}`);
+  return output.stdout.trim();
+};
+
+function runCacheDir(env: NodeJS.ProcessEnv): string {
+  const path = env.ELANOUS_GRAPH_CONTEXT;
+  if (!path || !isAbsolute(path) || !/^\d+\.json$/.test(basename(path)) || !dirname(path).endsWith('.json.contexts')) {
+    throw new Error('prefetch requires an absolute graph run context file');
+  }
+  return join(dirname(path), 'docs-prefetch');
+}
+function cutFor(context: GraphContext, stateRoot: string): Cut {
+  const version = context.input.version;
+  const commit = nodeOutput(context, 'version-release', 'commit');
+  if (context.outputs['version-release']?.outcome !== 'ok' || !SHA.test(commit)) throw new Error('invalid release commit');
+  const raw = readFileSync(join(stateRoot, 'release', version, 'manifest.json'));
+  const manifest = JSON.parse(raw.toString()) as ReleaseManifest;
+  if (manifest.version !== version || manifest.cutoff?.sha !== commit || !Array.isArray(manifest.in)) throw new Error('manifest cutoff differs from release commit');
+  return { version, commit, manifestHash: createHash('sha256').update(raw).digest('hex') };
+}
+/** Exclusive create — true iff this caller is the first to claim the run's prefetch slot. */
+function claimPrefetch(dir: string, owner: 'worker' | 'docs'): boolean {
+  try { writeFileSync(join(dir, 'claim'), owner, { flag: 'wx' }); return true; }
+  catch (error) { if ((error as NodeJS.ErrnoException).code === 'EEXIST') return false; throw error; }
+}
+function cacheFile(dir: string, cut: Cut): string {
+  return join(dir, `${cut.commit}-${cut.manifestHash}.json`);
+}
+function loadCache(dir: string, cut: Cut): PrefetchCache | null {
+  try {
+    const value = JSON.parse(readFileSync(cacheFile(dir, cut), 'utf8')) as PrefetchCache;
+    if (value.version !== cut.version || value.commit !== cut.commit || value.manifestHash !== cut.manifestHash
+      || !SHA.test(value.main) || value.tree !== join(dir, 'tree') || !existsSync(value.tree)
+      || value.docs?.outcome !== 'ok' || value.docs.version !== cut.version
+      || value.docs.notes !== join(value.tree, 'release/public/docs/releases', `${cut.version}.md`)
+      || value.docs.pages !== join(value.tree, 'website/pages.json')
+      || !existsSync(value.docs.notes) || !existsSync(value.docs.pages)) return null;
+    return value;
+  } catch { return null; }
+}
+
+/** Worker performs ONLY local reads and temporary worktree writes; failure is a cache miss, not a gate failure. */
+export function stagePrefetch(context: GraphContext, env: NodeJS.ProcessEnv = process.env, repo = process.cwd(),
+  runner: Runner = commandRunner, deps: { stateRoot?: string; tui?: (commit: string) => Record<string, unknown> | null; deadline?: number } = {}): PrefetchCache {
+  // One whole-worker deadline: every step gets at most the time left, and no step starts after it.
+  const deadline = deps.deadline ?? Date.now() + PREFETCH_DEADLINE_MS;
+  const left = () => {
+    const ms = deadline - Date.now();
+    if (ms <= 0) throw new Error('prefetch worker deadline exceeded');
+    return ms;
+  };
+  const run: Runner = (command, args, cwd, timeout, childEnv) => runner(command, args, cwd, Math.min(timeout ?? 15 * 60_000, left()), childEnv);
+  const dir = runCacheDir(env);
+  const stateRoot = deps.stateRoot ?? effectiveInstanceRoot();
+  const cut = cutFor(context, stateRoot);
+  mkdirSync(dir, { recursive: true });
+  const already = loadCache(dir, cut);
+  if (already) return already;
+  const tree = join(dir, 'tree');
+  let added = false;
   try {
-    if (graphContext) {
-      const value = JSON.parse(graphContext.trimStart().startsWith('{') ? graphContext : readFileSync(graphContext, 'utf8')) as { input?: { previousVersion?: unknown }; outputs?: unknown };
-      isReleaseGraph = value?.input?.previousVersion !== undefined || value?.outputs !== undefined;
+    const main = run('git', ['rev-parse', '--verify', 'origin/main^{commit}'], repo);
+    if (!SHA.test(main)) throw new Error('invalid origin/main commit');
+    // TUI runs against the cut, on its own isolated worktree, before touching the docs checkout.
+    // tui-sim-node.ts prints the RAW result (no `outcome`); judge it the way node-verdict.ts tui would before reuse.
+    const tuiData = deps.tui ? deps.tui(cut.commit) : (() => {
+      const tuiRun = spawnSync('bun', ['scripts/release-loop/tui-sim-node.ts', '--commit', cut.commit, '--json'], {
+        cwd: repo, timeout: Math.min(6 * 60_000, left()), encoding: 'utf8', maxBuffer: 16 * 1024 * 1024,
+      });
+      return tuiRun.status === 0 ? lastResult({ status: tuiRun.status, stdout: tuiRun.stdout ?? '', stderr: tuiRun.stderr ?? '' }) ?? null : null;
+    })();
+    const tui = reusableTui(withTuiOutcome(0, tuiData), cut.commit);
+    run('git', ['worktree', 'add', '--detach', tree, main], repo);
+    added = true;
+    run('bun', ['install', '--frozen-lockfile'], tree);
+    // Docs staging runs as its own process so the whole-worker deadline can stop it (an in-process call could not be).
+    const docsOut = run(process.execPath, [resolve(import.meta.filename), '--version', cut.version, '--base', tree, '--json'], repo, undefined,
+      { ...process.env, ELANOUS_GRAPH_CONTEXT: '', ELANOUS_STATE_DIR: stateRoot });
+    const docs = JSON.parse(docsOut.trim().split('\n').at(-1) ?? 'null') as DocsResult;
+    if (!docs || typeof docs !== 'object') throw new Error('docs staging returned no result');
+    if (docs.outcome !== 'ok') throw new Error(docs.error ?? 'docs staging failed');
+    // Recheck the cut before publishing an atomic result; stale results are never reused.
+    left();
+    const finalCut = cutFor(context, stateRoot);
+    if (finalCut.manifestHash !== cut.manifestHash) throw new Error('manifest changed during prefetch');
+    const result: PrefetchCache = { ...cut, main, tree, docs, tui };
+    const final = cacheFile(dir, cut);
+    const staged = `${final}.${process.pid}.${randomUUID()}.tmp`;
+    writeFileSync(staged, JSON.stringify(result) + '\n');
+    // Publication handshake: whoever creates `claim` first (O_EXCL) wins. The docs node claims before it reads,
+    // so a worker that loses can never publish a cache that a docs attempt would consume.
+    if (!claimPrefetch(dir, 'worker')) {
+      rmSync(staged, { force: true });
+      throw new Error('docs node already ran; late prefetch is discarded');
     }
+    renameSync(staged, final);
+    return result;
   } catch (error) {
-    result = { outcome: 'error', version: null, error: error instanceof Error ? error.message : String(error) };
+    if (added) { try { runner('git', ['worktree', 'remove', '--force', tree], repo, 60_000); } catch { /* preserve original failure */ } }
+    throw error;
   }
-  if (!result && isReleaseGraph) {
-    let version: string | null = null;
-    let tree: string | undefined;
-    try {
+}
+
+/** TUI is measured against the cut commit, so reuse keys on commit ⊕ manifest hash only — origin/main is a docs-tree input, not a TUI input. */
+export function joinTui(context: GraphContext, env: NodeJS.ProcessEnv, repo: string,
+  fallback: (commit: string) => { status: number | null; stdout: string; stderr: string } = (commit) => {
+    const output = spawnSync('bun', ['scripts/release-loop/node-verdict.ts', 'tui'], {
+      cwd: repo, env, encoding: 'utf8', timeout: 7 * 60_000, maxBuffer: 16 * 1024 * 1024,
+    });
+    return { status: output.status, stdout: output.stdout ?? '', stderr: output.stderr ?? '' };
+  }, stateRoot = effectiveInstanceRoot()): Record<string, unknown> {
+  if (context.outputs.upgrade?.outcome !== 'ok') throw new Error('upgrade did not pass');
+  // Any failure to key the cache (no manifest, cutoff mismatch, no run dir) is a cache miss → original TUI path.
+  let cut: Cut | null = null;
+  let cached: PrefetchCache | null = null;
+  try { cut = cutFor(context, stateRoot); cached = loadCache(runCacheDir(env), cut); } catch { /* cache miss */ }
+  const reused = cut && cached?.tui && reusableTui(cached.tui, cut.commit);
+  if (reused) return { ...reused, outcome: 'ok', summary: `tui ${reused.verdict}` };
+  // Preserve node-verdict.ts's exit convention and last-JSON output on a cache miss.
+  const output = fallback(cut?.commit ?? String(context.outputs['version-release']?.commit ?? ''));
+  const data = lastResult(output);
+  if (!data) throw new Error(`tui fallback returned no verdict: ${output.stderr}`);
+  // A timed-out or crashed fallback never passes on an earlier success line: exit status, outcome and verdict must agree.
+  // node-verdict.ts convention: ok ↔ exit 0 with pass|flaky · fail ↔ exit 1 with fail · error ↔ exit 2.
+  const agrees = output.status === 0 ? data.outcome === 'ok' && (data.verdict === 'pass' || data.verdict === 'flaky')
+    : output.status === 1 ? data.outcome === 'fail' && data.verdict === 'fail'
+      : output.status === 2 ? data.outcome === 'error' && data.verdict === 'fail' : false;
+  if (!agrees) {
+    throw new Error(`tui fallback exited ${output.status} with outcome ${String(data.outcome)} / verdict ${String(data.verdict)}`);
+  }
+  return data;
+}
+
+export function graphDocs(context: GraphContext, env: NodeJS.ProcessEnv, repo: string, run: Runner = commandRunner,
+  stateRoot = effectiveInstanceRoot()): DocsResult {
+  const version = context.input.version;
+  let tree: string | undefined;
+  // Before ANY check (and so also on every failure path): only the first docs attempt may consume a staged cache,
+  // and only when the worker won the claim; otherwise this attempt claims the slot so a late worker cannot publish.
+  let mayConsume = false;
+  let cacheDir: string | undefined;
+  try {
+    cacheDir = runCacheDir(env);
+    mkdirSync(cacheDir, { recursive: true });
+    const closed = join(cacheDir, 'docs-closed');
+    const firstAttempt = !existsSync(closed);
+    writeFileSync(closed, `${new Date().toISOString()}\n`);
+    const docsWon = claimPrefetch(cacheDir, 'docs');
+    mayConsume = firstAttempt && !docsWon && readFileSync(join(cacheDir, 'claim'), 'utf8') === 'worker';
+  } catch { /* standalone/legacy graph — no prefetch */ }
+  try {
+    // No fetch (nor any write to remote) until every gate is verified.
+    for (const node of ['gate', 'prepare', 'upgrade', 'tui']) if (context.outputs[node]?.outcome !== 'ok') throw new Error(`${node} did not pass`);
+    let cached: PrefetchCache | null = null;
+    // A cache key that cannot be computed is a miss — the original fresh-worktree path runs.
+    if (mayConsume && cacheDir) { try { const cut = cutFor(context, stateRoot); cached = loadCache(cacheDir, cut); } catch { cached = null; } }
+    const branch = `release-docs/${version}`;
+    run('git', ['fetch', 'origin', 'main'], repo);
+    const main = run('git', ['rev-parse', '--verify', 'origin/main^{commit}'], repo);
+    if (cached && cached.main === main && SHA.test(main)) {
+      tree = cached.tree;
+      // Attach the staged detached checkout to the branch only at the late docs node.
+      run('git', ['-C', tree, 'switch', '-c', branch], repo);
+      // Consumed: a resumed run must not reuse a tree that is now on the branch (fresh path instead).
+      rmSync(cacheFile(cacheDir!, cached), { force: true });
+    } else {
+      const root = mkdtempSync(join(tmpdir(), 'release-docs-'));
+      tree = join(root, 'tree');
+      run('git', ['worktree', 'add', '-b', branch, tree, 'origin/main'], repo);
+      run('bun', ['install', '--frozen-lockfile'], tree);
+    }
+    const result = cached && cached.main === main ? cached.docs : runDocs(['--version', version, '--base', tree, '--json'], repo, env, { stateRoot });
+    if (result.outcome !== 'ok') throw new Error(result.error ?? 'docs generation failed');
+    run('git', ['add', 'release/public/docs', 'website/pages.json'], tree);
+    run('git', ['commit', '-m', `docs: release ${version}`], tree);
+    run('git', ['push', '-u', 'origin', branch], tree);
+    return { ...result, branch, worktree: tree };
+  } catch (error) {
+    return { outcome: 'error', version, error: error instanceof Error ? error.message : String(error), ...(tree ? { worktree: tree } : {}) };
+  }
+}
+
+/** Detached prefetch worker; an asynchronous spawn failure is logged as a cache miss and never escapes the node. */
+export function startPrefetchWorker(version: string, commit: string,
+  spawnWorker: () => ReturnType<typeof spawn> = () => spawn(process.execPath, [resolve(import.meta.filename), '--prefetch-worker'], {
+    cwd: process.cwd(), env: process.env, detached: true, stdio: ['ignore', 'ignore', 'ignore'],
+  })): number {
+  const child = spawnWorker();
+  child.on('error', (error) => debug.log('release-loop.docs', 'prefetch-skipped', { version, commit, reason: `worker spawn error: ${error.message}` }));
+  if (!child.pid) throw new Error('prefetch worker did not start');
+  child.unref();
+  return child.pid;
+}
+
+function graphNodeId(env: NodeJS.ProcessEnv): string | null {
+  const location = env.ELANOUS_GRAPH_CONTEXT;
+  if (!location) return null;
+  const context = JSON.parse(location.trimStart().startsWith('{') ? location : readFileSync(location, 'utf8')) as { nodeId?: unknown; input?: { previousVersion?: unknown }; outputs?: unknown };
+  return typeof context.nodeId === 'string' ? context.nodeId : context.input?.previousVersion !== undefined || context.outputs !== undefined ? 'docs' : null;
+}
+
+if (import.meta.main) {
+  let result: DocsResult | (Record<string, unknown> & { outcome: 'ok' | 'error' | 'fail'; version?: string | null; error?: string });
+  let node: string | null = null;
+  try {
+    node = graphNodeId(process.env);
+    if (process.argv.includes('--prefetch-worker')) {
+      if (node !== 'prefetch') throw new Error('prefetch worker requires prefetch node');
       const context = readGraphContext();
-      version = context.input.version;
-      for (const node of ['upgrade', 'tui', 'prepare', 'gate']) if (context.outputs[node]?.outcome !== 'ok') throw new Error(`${node} did not pass`);
-      const branch = `release-docs/${version}`;
-      const run = (command: string, args: string[], cwd = process.cwd()) => {
-        const output = spawnSync(command, args, { cwd, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 });
-        if (output.status !== 0) throw new Error(`${command} ${args[0]} failed: ${output.stderr || output.stdout}`);
-        return output.stdout.trim();
-      };
-      run('git', ['fetch', 'origin', 'main']);
-      tree = mkdtempSync(join(tmpdir(), 'release-docs-'));
-      const worktree = join(tree, 'tree');
-      run('git', ['worktree', 'add', '-b', branch, worktree, 'origin/main']);
-      run('bun', ['install', '--frozen-lockfile'], worktree);
-      result = runDocs(['--version', version, '--base', worktree, '--json']);
-      if (result.outcome !== 'ok') throw new Error(result.error ?? 'docs generation failed');
-      run('git', ['add', 'release/public/docs', 'website/pages.json'], worktree);
-      run('git', ['commit', '-m', `docs: release ${version}`], worktree);
-      run('git', ['push', '-u', 'origin', branch], worktree);
-      result = { ...result, branch, worktree };
-    } catch (error) {
-      result = { outcome: 'error', version, error: error instanceof Error ? error.message : String(error), ...(tree ? { worktree: join(tree, 'tree') } : {}) };
+      stagePrefetch(context);
+      // Worker stdout is not a graph verdict; the initiating node has already returned.
+      process.exit(0);
     }
-  } else if (!result) result = runDocs(process.argv.slice(2));
-  debug.log('release-loop.docs', 'result', { version: result.version, outcome: result.outcome });
-  emitNodeResult({ ...result, verdict: result.outcome === 'ok' ? 'pass' : 'fail', summary: result.outcome === 'ok' ? `docs v${result.version} · ${result.flipped?.length ?? 0} pages` : `docs: ${result.error ?? 'failed'}` });
-  if (result.outcome === 'error') process.exitCode = 1;
+    if (node === 'prefetch') {
+      let version: string | null = null;
+      try {
+        const context = readGraphContext();
+        version = context.input.version;
+        const cut = cutFor(context, effectiveInstanceRoot());
+        const dir = runCacheDir(process.env);
+        mkdirSync(dir, { recursive: true });
+        if (!loadCache(dir, cut)) {
+          const pid = startPrefetchWorker(cut.version, cut.commit);
+          // This is not a gate: the late nodes validate the atomic artifact or run their original path.
+          debug.log('release-loop.docs', 'prefetch-start', { version: cut.version, commit: cut.commit, pid });
+        }
+        result = { outcome: 'ok', version: cut.version, summary: `prefetch v${cut.version} started` };
+      } catch (error) {
+        // Any pre-worker failure is a cache miss — the gate and the late nodes' original paths still run.
+        const reason = error instanceof Error ? error.message : String(error);
+        debug.log('release-loop.docs', 'prefetch-skipped', { version, reason });
+        result = { outcome: 'ok', version, summary: `prefetch skipped (cache miss): ${reason}` };
+      }
+    } else if (node === 'tui') {
+      const context = readGraphContext();
+      result = { ...joinTui(context, process.env, process.cwd()), version: context.input.version } as typeof result;
+    } else if (node === 'docs') {
+      result = graphDocs(readGraphContext(), process.env, process.cwd(), commandRunner);
+    } else if (node === null) result = runDocs(process.argv.slice(2));
+    else throw new Error(`unknown release docs node: ${node}`);
+  } catch (error) {
+    result = { outcome: 'error', version: null, error: error instanceof Error ? error.message : String(error) };
+  }
+  debug.log('release-loop.docs', 'result', { node, version: result.version, outcome: result.outcome });
+  const details = result as Record<string, unknown>;
+  const verdict = details.verdict;
+  emitNodeResult({ ...details, outcome: result.outcome, verdict: verdict === 'pass' || verdict === 'flaky' || verdict === 'fail' ? verdict : result.outcome === 'ok' ? 'pass' : 'fail',
+    summary: typeof details.summary === 'string' ? details.summary : result.outcome === 'ok'
+      ? `docs v${result.version} · ${(details.flipped as string[] | undefined)?.length ?? 0} pages` : `docs: ${result.error ?? 'failed'}` });
+  if (result.outcome !== 'ok') process.exitCode = result.outcome === 'fail' ? 1 : node === 'tui' ? 2 : 1;
 }

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

@@ -0,0 +1,59 @@
+/** File seconds are recorded on the outer testsuite of each JUnit file, not its nested describe suites. */
+export function readJunitFileSeconds(xml: string): Map<string, number> {
+  const secondsByFile = new Map<string, number>();
+  const entities: Record<string, string> = { '&amp;': '&', '&quot;': '"', '&apos;': "'", '&lt;': '<', '&gt;': '>' };
+  let depth = 0;
+  let cursor = 0;
+  while (cursor < xml.length) {
+    const start = xml.indexOf('<', cursor);
+    if (start < 0) break;
+    if (xml.startsWith('<![CDATA[', start)) {
+      const end = xml.indexOf(']]>', start + 9);
+      if (end < 0) break;
+      cursor = end + 3;
+      continue;
+    }
+    if (xml.startsWith('<!--', start)) {
+      const end = xml.indexOf('-->', start + 4);
+      if (end < 0) break;
+      cursor = end + 3;
+      continue;
+    }
+    if (xml.startsWith('<?', start)) {
+      const end = xml.indexOf('?>', start + 2);
+      if (end < 0) break;
+      cursor = end + 2;
+      continue;
+    }
+    let quote = '';
+    let brackets = 0;
+    let end = start + 1;
+    for (; end < xml.length; end++) {
+      const char = xml[end]!;
+      if (quote) { if (char === quote) quote = ''; }
+      else if (char === '"' || char === "'") quote = char;
+      else if (char === '[' && xml.startsWith('<!', start)) brackets++;
+      else if (char === ']' && brackets) brackets--;
+      else if (char === '>' && !brackets) break;
+    }
+    if (end === xml.length) break;
+    cursor = end + 1;
+    const tag = xml.slice(start + 1, end);
+    const suite = /^(\/?)testsuite(?=[\s/]|$)/.exec(tag);
+    if (!suite) continue;
+    if (suite[1]) { depth = Math.max(0, depth - 1); continue; }
+    if (depth === 0) {
+      const file = /\bfile="([^"]+)"/.exec(tag)?.[1];
+      const rawTime = /\btime="([^"]+)"/.exec(tag)?.[1];
+      if (file && rawTime !== undefined) {
+        const seconds = Number(rawTime);
+        if (Number.isFinite(seconds) && seconds >= 0) {
+          const path = file.replace(/&(?:amp|quot|apos|lt|gt);/g, (entity) => entities[entity]!);
+          secondsByFile.set(path, Math.max(secondsByFile.get(path) ?? 0, seconds));
+        }
+      }
+    }
+    if (!/\/\s*$/.test(tag)) depth++;
+  }
+  return secondsByFile;
+}

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

@@ -21,7 +21,7 @@ import { POD_BUN_CACHE_HOST_PATH, parseInstallSeconds, podBunCacheVolume } from
 import { PodPoolScheduler, parsePodPool, checkPodPool } from '../../src/task-orchestrator/surfaces/pod-pool.js';
 import { POD_INSTALL_SLOTS_DEFAULT, POD_INSTALL_SLOTS_HOST_PATH, installSlotScript } from '../../src/task-orchestrator/surfaces/pod-install-slots.js';
 import { gateDepsInstallScript, parseGateDeps } from '../../src/task-orchestrator/surfaces/pod-gate-deps.js';
-import { gateShardsPath, writeGateShards, type GateShard } from '../../src/release-loop/gate-shards.js';
+import { gateShardsPath, recordGateShardsVerdict, writeGateShards, type GateShard } from '../../src/release-loop/gate-shards.js';
 import { defaultKubectl } from '../../src/task-orchestrator/surfaces/self-implement-pod.js';
 
 interface CommandResult { rc: number; output: string; passedIds?: string[]; stalledEnv?: Array<{ file: string; reason: 'no-output' }>; timedOut?: boolean }
@@ -75,6 +75,7 @@ export interface GateResult {
   knownEnv: number;
   knownEnvCleared: string[];
   stalledEnv: Array<{ file: string; reason: 'no-output' | 'isolated-timeout'; local: 'passed' | 'failed' | 'timeout' }>;
+  rcNonzeroNoFailures: Array<{ file: string; rc: number; pass: number; baseline: 'same' | 'clean' | 'missing' }>;
   baselineSource?: 'ledger' | 'instance' | 'cut-logs' | 'swept';
   /** GATE-BASELINE-CACHE — isolated baseline files answered from the ledger (hits) or run now (misses). */
   baselineCache?: { hits: number; misses: number };
@@ -460,6 +461,47 @@ function failuresOf(run: CommandResult, label: string): SweepFailures {
   return { failures, errors: [...new Set(errors)].sort() };
 }
 
+/**
+ * «N pass · 0 fail · rc=1» from an isolated run is read as `rc-nonzero-no-failures` only when the summary is a complete,
+ * clean, single-file summary for the requested file (`Ran N≥1 tests across 1 file` · 0 fail · 0 error · no `(fail)` ·
+ * no unhandled error · pass = N · no other test-file header). Every other run is read exactly as before (`failuresOf`,
+ * which throws on the incomplete shapes, plus a failure-count/identified-name check).
+ */
+export function readIsolatedRun(run: CommandResult, label: string, file: string):
+  | { kind: 'read'; failures: string[]; errors: string[] }
+  | { kind: 'rc-nonzero-no-failures'; rc: number; pass: number } {
+  const output = stripPodRepoRoot(run.output.replace(/\x1b\[[0-9;]*[A-Za-z]/g, ''));
+  const ran = lastMatch(output, /Ran (\d+) tests? across (\d+) files?/);
+  // rc 1 only: other non-zero exits with a clean summary keep the established leaked-exit reading (clean) in failuresOf.
+  const cleanNonzero = run.rc === 1 && !!ran && Number(ran[1]) >= 1 && Number(ran[2]) === 1
+    && summaryCount(output, 'fail') === 0
+    && (Number.isNaN(summaryCount(output, 'error')) || summaryCount(output, 'error') === 0)
+    && parseFailures(output).length === 0 && !/\(fail\)/.test(output)
+    && !/Unhandled error between tests/.test(output);
+  if (!cleanNonzero) {
+    const read = failuresOf(run, label);
+    // Two (fail) lines folding into one id would undercount the file's failures: unreadable, not fewer.
+    const failCount = summaryCount(output, 'fail');
+    if (Number.isFinite(failCount) && read.failures.length !== failCount)
+      throw new Error(`${label} incomplete (rc=${run.rc}; failure attribution summary=${failCount}, identified=${read.failures.length})`);
+    return { kind: 'read', ...read };
+  }
+  // Bun's file headers, when present, must identify the requested file before the result is recorded or cached.
+  // Any test-file path counts: root-level (`other.test.ts:`), nested, or absolute (outside the stripped Pod root).
+  for (const raw of output.split(/\r?\n/)) {
+    // Any characters but `:` (unicode, spaces, @, +, …) — a header is `<path ending in .test/.spec.ts>:`.
+    const header = /^(?:\.\/)?([^\s:][^:]*?\.(?:test|spec)\.[cm]?[jt]sx?):/.exec(raw.trim());
+    if (header && header[1] !== file)
+      throw new Error(`${label} incomplete (rc=${run.rc}; isolated run attributed to another file: ${header[1]})`);
+  }
+  const pass = summaryCount(output, 'pass');
+  if (pass !== Number(ran![1]))
+    throw new Error(`${label} incomplete (rc=${run.rc}; pass=${Number.isNaN(pass) ? 'missing' : pass}; Ran=${ran![1]})`);
+  // Validate the requested file as well as the summary; only this one file can own the synthetic id.
+  fileOf(`${file} > [rc-nonzero]`);
+  return { kind: 'rc-nonzero-no-failures', rc: run.rc, pass };
+}
+
 class StalledPodShards extends Error {
   constructor(readonly stalledShards: NonNullable<GateResult['stalledShards']>, readonly partialSummary: NonNullable<GateResult['partialSummary']>) {
     super(`pod sweep incomplete: stalled shards ${stalledShards.map(({ shard }) => shard).join(', ')}`);
@@ -1149,7 +1191,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, knownEnv: 0, knownEnvCleared: [], stalledEnv: [], durationMs: 0 };
+  const result: GateResult = { outcome: 'error', commit: opts.commit, introduced: [], preexisting: 0, fixed: 0, knownEnv: 0, knownEnvCleared: [], stalledEnv: [], rcNonzeroNoFailures: [], durationMs: 0 };
   let work: string | undefined;
   let baseSnapshot = false;
   let cutFailures: SweepFailures | undefined;
@@ -1345,12 +1387,15 @@ export async function judgeGate(opts: GateOptions, runner: GateRunner = createGa
         result.stalledEnv.push({ file, reason: 'isolated-timeout', local: 'timeout' });
         continue;
       }
-      const isolatedCut = cutCheck === undefined
+      const cutReading = cutCheck === undefined ? undefined : readIsolatedRun(cutCheck, `cut isolated ${file}`, file);
+      const rcOnly = cutReading?.kind === 'rc-nonzero-no-failures' ? cutReading : undefined;
+      const rcOnlyId = `${file} > [rc-nonzero]`;
+      const isolatedCut: SweepFailures = cutReading === undefined
         ? { failures: cut.failures.filter((id) => fileOf(id) === file), errors: cut.errors.filter((id) => fileOf(id) === file) }
-        : failuresOf(cutCheck, `cut isolated ${file}`);
+        : cutReading.kind === 'read' ? cutReading : { failures: [], errors: [rcOnlyId] };
       if (cutCheck !== undefined) remember({ commit: opts.commit, file, host: cacheHost, failures: isolatedCut.failures, errors: isolatedCut.errors, missing: false });
       const reproduced = new Set([...isolatedCut.failures, ...isolatedCut.errors]);
-      let candidates = diff.newFailures.filter((id) => fileOf(id) === file && reproduced.has(id));
+      let candidates = rcOnly ? [rcOnlyId] : diff.newFailures.filter((id) => fileOf(id) === file && reproduced.has(id));
       // GATE-INTRO-RECHECK — a new failure that is only bun's «timed out» shape gets one more isolated run with a generous
       // per-test limit, on the same runner (node-b when the gate is remote). Passing there = flaky under load (warning);
       // an assertion failure, a failure again, or a run that cannot be read stays introduced.
@@ -1382,7 +1427,9 @@ export async function judgeGate(opts: GateOptions, runner: GateRunner = createGa
       }
       if (candidates.length === 0) continue;
       let oldFailures: Set<string>;
+      let baselineMissing = false;
       const hit = baseCache.get(`${file}\0${cacheHost}`);
+      if (hit?.missing) baselineMissing = true;
       if (hit) {
         cacheStats.hits++;
         oldFailures = new Set([...hit.failures, ...hit.errors]);
@@ -1399,13 +1446,22 @@ export async function judgeGate(opts: GateOptions, runner: GateRunner = createGa
           const lookup = await runner.command('git', ['ls-tree', '--name-only', baseSha, '--', file], opts.remote ? baselineTree : repo);
           if (lookup.rc !== 0 || lookup.output.trim()) throw new Error(`baseline isolated run incomplete: ${file}`);
           oldFailures = new Set();
+          baselineMissing = true;
           remember({ commit: baseSha, file, host: cacheHost, failures: [], errors: [], missing: true });
         } else {
-          const prior = failuresOf(previous, `baseline isolated ${file}`);
+          const reading = readIsolatedRun(previous, `baseline isolated ${file}`, file);
+          const prior: SweepFailures = reading.kind === 'read' ? reading : { failures: [], errors: [rcOnlyId] };
+          if (reading.kind === 'rc-nonzero-no-failures') debug.log('release-loop.gate', 'isolated-rc-nonzero-no-failures',
+            { file, label: 'baseline isolated', rc: reading.rc, pass: reading.pass, baseline: 'same' });
           oldFailures = new Set([...prior.failures, ...prior.errors]);
           remember({ commit: baseSha, file, host: cacheHost, failures: prior.failures, errors: prior.errors, missing: false });
         }
       }
+      if (rcOnly) {
+        const baseline = oldFailures.has(rcOnlyId) ? 'same' : baselineMissing ? 'missing' : 'clean';
+        result.rcNonzeroNoFailures.push({ file, rc: rcOnly.rc, pass: rcOnly.pass, baseline });
+        debug.log('release-loop.gate', 'isolated-rc-nonzero-no-failures', { file, label: 'cut isolated', rc: rcOnly.rc, pass: rcOnly.pass, baseline });
+      }
       for (const id of candidates) {
         if (oldFailures.has(id)) result.preexisting++;
         else result.introduced.push(id);
@@ -1456,6 +1512,15 @@ export async function judgeGate(opts: GateOptions, runner: GateRunner = createGa
     }
   }
   if (result.outcome !== 'error') debug.log('release-loop.gate', 'judged', { version: opts.version, commit: opts.commit, introduced: result.introduced.length, preexisting: result.preexisting });
+  // GATE-LIVE-OBS-RC-WORDING ⓒ — the shards board says «판정 전» until this lands; then «새 실패 N» only (UX · gate-shards.ts).
+  // Same ledger as the board's own writes (sweep's shardsFile). A write failure is logged and never changes the verdict.
+  if (result.outcome !== 'error' && opts.pod) {
+    const path = opts.ledgerRoot ? gateShardsPath(opts.version, opts.ledgerRoot) : gateShardsPath(opts.version);
+    try {
+      const written = recordGateShardsVerdict(path, { introduced: result.introduced.length, preexisting: result.preexisting });
+      debug.log('release-loop.gate', 'shards-verdict', { version: opts.version, path, written, introduced: result.introduced.length, preexisting: result.preexisting });
+    } catch (error) { debug.log('release-loop.gate', 'shards-verdict-write-failed', { path, error: String(error) }); }
+  }
   return result;
 }
 
@@ -1464,6 +1529,7 @@ export function graphGateResult(result: GateResult, graph: boolean) {
     verdict: result.outcome === 'ok' ? 'pass' as const : 'fail' as const,
     summary: (result.partial ? `부분 재검 ${result.partial.files}파일(앞 게이트 ${result.partial.priorCommit.slice(0, 9)} 결과 이음) · ` : '')
       + (result.outcome === 'ok' ? `새 회귀 ${result.introduced.length} · 기존 ${result.preexisting} · 고침 ${result.fixed ?? '못 셈(기준선 미루기)'}` : `게이트 ${result.outcome}: ${result.error ?? result.introduced.length + ' new regressions'}`) + ` · 환경 알려진 실패 ${result.knownEnv}`
+      + (result.rcNonzeroNoFailures.length ? ` · ⚠ 종료코드만 비영 ${result.rcNonzeroNoFailures.length}` : '')
       + (result.loadFlaky?.length ? ` · ⚠ 부하 흔들림 ${result.loadFlaky.length}(시간 초과 꼴 · ${GATE_TIMEOUT_RECHECK_MS / 1000}s 재실행 통과 · 막지 않음)` : '')
       + (result.stalledEnv.length ? ` · 환경 멈춤 ${result.stalledEnv.length} (Pod 밖 통과 ${result.stalledEnv.filter((item) => item.local === 'passed').length})` : '') };
 }
@@ -1535,7 +1601,7 @@ if (import.meta.main) {
     version = opts.version;
     result = await judgeGate(opts);
   } catch (error) {
-    result = { outcome: 'error', commit: '', introduced: [], preexisting: 0, fixed: 0, knownEnv: 0, knownEnvCleared: [], stalledEnv: [], durationMs: Date.now() - start, error: String(error) };
+    result = { outcome: 'error', commit: '', introduced: [], preexisting: 0, fixed: 0, knownEnv: 0, knownEnvCleared: [], stalledEnv: [], rcNonzeroNoFailures: [], durationMs: Date.now() - start, error: String(error) };
   }
   if (result.error) console.error(result.error);
   debug.log('release-loop.gate', 'result', { version, outcome: result.outcome });