elanous 0.2.22 → 0.2.24

package/scripts/measure-tsc-affected-roots.ts

@@ -0,0 +1,289 @@
+import { spawn } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { debug } from '../src/debug/log.js';
+import { parseTypecheckErrors, tscEnv } from '../src/typecheck-ratchet.js';
+import { compareDiagnostics, normalizeDiagnostics, type NormalizedDiagnostic } from './tsc-baseline-comparison.js';
+
+export interface CommandResult {
+  status: number | null;
+  signal?: NodeJS.Signals | null;
+  stdout: string;
+  stderr: string;
+  error?: Error;
+  durationMs: number;
+}
+export type Runner = (command: string, args: string[], cwd: string, env?: NodeJS.ProcessEnv) => Promise<CommandResult>;
+export interface Metrics { durationMs: number | null; rssMb: number | null; }
+export interface PrMeasurement {
+  pr: number;
+  head: string;
+  base: string;
+  verdict: 'missed' | 'same' | 'stricter' | 'unmeasured';
+  missedDiagnostics: NormalizedDiagnostic[];
+  addedDiagnostics: NormalizedDiagnostic[];
+  fullBase: Metrics;
+  fullHead: Metrics;
+  narrowed: Metrics;
+  gateExitCode: number | null;
+  reason?: string;
+  worktree: string;
+}
+export interface MeasurementReport {
+  prs: PrMeasurement[];
+  summary: { missed: number; same: number; stricter: number; unmeasured: number; of: number };
+  exitCode: number;
+}
+export interface Options { run?: Runner; platform?: NodeJS.Platform; makeTemp?: () => string; removeTemp?: (path: string) => void; }
+interface Pr { number: number; mergeCommit: { oid: string } | null; files: { path: string }[]; mergedAt?: string; changedFiles?: number; }
+const emptyMetrics = (): Metrics => ({ durationMs: null, rssMb: null });
+const hash = (text: string): boolean => /^[0-9a-f]{40}$/i.test(text);
+const reason = (result: CommandResult): string => result.error?.message ?? (result.stderr.trim() || result.stdout.trim() || `exit ${result.status}`);
+
+export const spawnRunner: Runner = (command, args, cwd, extraEnv) => new Promise((done) => {
+  const started = performance.now();
+  const env = tscEnv({ ...process.env, ...extraEnv });
+  delete env.GIT_DIR;
+  delete env.GIT_WORK_TREE;
+  delete env.GIT_COMMON_DIR;
+  let child;
+  try { child = spawn(command, args, { cwd, env, stdio: ['ignore', 'pipe', 'pipe'] }); }
+  catch (cause) {
+    done({ status: null, stdout: '', stderr: '', error: cause instanceof Error ? cause : new Error(String(cause)), durationMs: performance.now() - started });
+    return;
+  }
+  const stdout: Buffer[] = [];
+  const stderr: Buffer[] = [];
+  child.stdout.on('data', (chunk: Buffer) => stdout.push(chunk));
+  child.stderr.on('data', (chunk: Buffer) => stderr.push(chunk));
+  let error: Error | undefined;
+  child.on('error', (cause: Error) => { error = cause; });
+  child.on('close', (status, signal) => done({ status, signal, stdout: Buffer.concat(stdout).toString(), stderr: Buffer.concat(stderr).toString(), error, durationMs: performance.now() - started }));
+});
+
+export function parseRss(output: string, platform: NodeJS.Platform): number | null {
+  const mac = output.match(/^\s*(\d+)\s+maximum resident set size\s*$/im);
+  const linux = output.match(/^\s*Maximum resident set size \(kbytes\):\s*(\d+)\s*$/im);
+  const value = platform === 'darwin' ? mac : platform === 'linux' ? linux : null;
+  if (!value) return null;
+  const bytes = Number(value[1]) * (platform === 'linux' ? 1024 : 1);
+  return Number.isSafeInteger(bytes) ? bytes / 1048576 : null;
+}
+
+function optionsFromArgs(argv: readonly string[]): { numbers: number[] | null; recent: number; keep: boolean } {
+  let numbers: number[] | null = null;
+  let recent = 10;
+  let explicitRecent = false;
+  let keep = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--prs' || arg === '--recent') {
+      const value = argv[++i];
+      if (!value) throw new Error(`${arg} requires a value`);
+      if (arg === '--prs') {
+        if (numbers || explicitRecent || !/^\d+(,\d+)*$/.test(value)) throw new Error('invalid --prs list');
+        numbers = value.split(',').map(Number);
+        if (numbers.some((n) => !Number.isSafeInteger(n) || n < 1) || new Set(numbers).size !== numbers.length) throw new Error('invalid --prs list');
+      } else {
+        if (numbers || explicitRecent || !/^\d+$/.test(value)) throw new Error('invalid --recent count');
+        recent = Number(value);
+        if (!Number.isSafeInteger(recent) || recent < 1) throw new Error('invalid --recent count');
+        explicitRecent = true;
+      }
+    } else if (arg === '--json') continue;
+    else if (arg === '--keep') keep = true;
+    else throw new Error(`unknown option: ${arg}`);
+  }
+  return { numbers, recent, keep };
+}
+
+async function required(run: Runner, command: string, args: string[], cwd: string, env?: NodeJS.ProcessEnv): Promise<CommandResult> {
+  const result = await run(command, args, cwd, env);
+  if (result.error || result.signal || result.status !== 0) throw new Error(`${command} ${args.join(' ')}: ${reason(result)}`);
+  return result;
+}
+function parsePr(value: unknown): Pr {
+  if (!value || typeof value !== 'object') throw new Error('invalid PR response');
+  const pr = value as Pr;
+  if (!Number.isSafeInteger(pr.number) || pr.number < 1 || !pr.mergeCommit || !hash(pr.mergeCommit.oid) || !Array.isArray(pr.files) || !pr.files.every((file) => typeof file?.path === 'string')) throw new Error(`invalid merged PR response: ${JSON.stringify(value)}`);
+  return pr;
+}
+const typeScriptFile = (path: string): boolean => /\.[cm]?tsx?$/.test(path);
+/** The list API truncates `files`; when the listed files are fewer than `changedFiles`, read the full paginated list. */
+async function touchesTypeScript(run: Runner, repo: string, pr: Pr): Promise<boolean> {
+  if (pr.files.some((file) => typeScriptFile(file.path))) return true;
+  if (typeof pr.changedFiles === 'number' && pr.changedFiles <= pr.files.length) return false;
+  const all = (await required(run, 'gh', ['api', '--paginate', `repos/{owner}/{repo}/pulls/${pr.number}/files`, '--jq', '.[].filename'], repo)).stdout.split('\n').map((line) => line.trim()).filter(Boolean);
+  if (typeof pr.changedFiles === 'number' && all.length < pr.changedFiles) throw new Error(`PR #${pr.number}: file list incomplete (${all.length} of ${pr.changedFiles})`);
+  return all.some(typeScriptFile);
+}
+async function selectPrs(repo: string, opts: ReturnType<typeof optionsFromArgs>, run: Runner): Promise<Pr[]> {
+  if (opts.numbers) {
+    const prs: Pr[] = [];
+    for (const n of opts.numbers) {
+      const pr = parsePr(JSON.parse((await required(run, 'gh', ['pr', 'view', String(n), '--json', 'number,mergeCommit,files'], repo)).stdout));
+      if (pr.number !== n) throw new Error(`requested PR #${n} but received #${pr.number}`);
+      prs.push(pr);
+    }
+    return prs;
+  }
+  let limit = Math.max(100, opts.recent);
+  let previousCount = -1;
+  for (;;) {
+    const result = await required(run, 'gh', ['pr', 'list', '--state', 'merged', '--base', 'main', '--search', 'sort:merged-desc', '--limit', String(limit), '--json', 'number,mergeCommit,files,mergedAt,changedFiles'], repo);
+    const raw: unknown = JSON.parse(result.stdout);
+    if (!Array.isArray(raw)) throw new Error('invalid merged PR list');
+    if (raw.some((item) => typeof item?.mergedAt !== 'string')) throw new Error('merged PR list has no merge dates');
+    const prs: Pr[] = [];
+    for (const pr of raw.map(parsePr)) if (await touchesTypeScript(run, repo, pr)) prs.push(pr);
+    if (prs.length >= opts.recent || raw.length < limit || raw.length === previousCount) return prs.sort((a, b) => b.mergedAt!.localeCompare(a.mergedAt!)).slice(0, opts.recent);
+    previousCount = raw.length;
+    limit += 100;
+  }
+}
+
+function elapsed(result: CommandResult, platform: NodeJS.Platform): Metrics {
+  return { durationMs: Number.isFinite(result.durationMs) ? result.durationMs : null, rssMb: parseRss(result.stderr, platform) };
+}
+function checked(result: CommandResult, label: string, output: string): void {
+  if (result.error || result.signal || ![0, 1, 2].includes(result.status ?? -1) || /error TS(?:2688|5083|6053)\b|heap out of memory|Ineffective mark-compacts near heap limit/i.test(output)) throw new Error(`${label}: tsc not measured: ${reason(result)}`);
+  const diagnostics = parseTypecheckErrors(output);
+  if (result.status !== 0 && diagnostics.length === 0) throw new Error(`${label}: nonzero exit without parseable diagnostics: ${reason(result)}`);
+  if ((/error TS\d+/.test(output) && diagnostics.length === 0) || (result.status === 0 && diagnostics.length > 0 && label === 'full')) throw new Error(`${label}: inconsistent tsc diagnostics and exit status`);
+}
+function fullDiagnostics(result: CommandResult, root: string): NormalizedDiagnostic[] {
+  const output = `${result.stdout}\n${result.stderr}`;
+  checked(result, 'full', output);
+  return normalizeDiagnostics(parseTypecheckErrors(output), root);
+}
+function gateDiagnostics(result: CommandResult, root: string): NormalizedDiagnostic[] {
+  const output = `${result.stdout}\n${result.stderr}`;
+  const diagnosticOutput = output.split('\n').map((line) => line.replace(/^  /, '')).join('\n');
+  checked(result, 'narrowed', diagnosticOutput);
+  if (/tsc 를 «못 쟀다»|tsc 가 정상 실행됐음을 확인할 수 없다|변경 파일 없음|변경 파일 수집 실패/i.test(output)
+    || (result.status === 0 && !/\[tsc-gate\] PASS —/.test(output))
+    || (result.status !== 0 && !/\[tsc-gate\] FAIL —/.test(output))) throw new Error('narrowed gate did not measure tsc');
+  return normalizeDiagnostics(parseTypecheckErrors(diagnosticOutput), root);
+}
+async function timed(run: Runner, platform: NodeJS.Platform, command: string, args: string[], cwd: string, env?: NodeJS.ProcessEnv): Promise<CommandResult> {
+  if (platform === 'darwin' || platform === 'linux') return run('/usr/bin/time', [platform === 'darwin' ? '-l' : '-v', command, ...args], cwd, env);
+  return run(command, args, cwd, env);
+}
+
+/**
+ * The pre-merge base of the whole PR. Merge commit → first parent. Single-parent merge commit: the PR's complete
+ * commit count comes from REST (`pulls/N .commits`) for every PR — never from the possibly truncated listed commits.
+ * One commit → `head^1`. k > 1 commits → squash (one commit on main) or rebase-merge (k rewritten commits); the
+ * method is decided by GitHub's commit↔PR association of `head~1 … head~(k-1)` (all ours → rebase → `head~k`,
+ * none ours → squash → `head^1`), never by commit subjects. Anything else is ambiguous and the PR is unmeasured,
+ * so an error introduced by an earlier rebased commit is never hidden behind a wrong baseline.
+ */
+async function preMergeRevision(run: Runner, repo: string, pr: Pr, head: string): Promise<string> {
+  const parents = (await required(run, 'git', ['rev-list', '--parents', '-n', '1', head], repo)).stdout.trim().split(/\s+/).filter(Boolean);
+  if (parents.length > 2) return `${head}^1`;
+  const totalText = (await required(run, 'gh', ['api', `repos/{owner}/{repo}/pulls/${pr.number}`, '--jq', '.commits'], repo)).stdout.trim();
+  const total = Number(totalText);
+  if (!/^\d+$/.test(totalText) || !Number.isSafeInteger(total) || total < 1) throw new Error(`PR #${pr.number}: commit count unreadable (${totalText || 'empty'}) — pre-merge base not determinable`);
+  if (total === 1) return `${head}^1`;
+  const ours: boolean[] = [];
+  for (let back = 1; back < total; back += 1) {
+    const sha = (await required(run, 'git', ['rev-parse', `${head}~${back}`], repo)).stdout.trim();
+    if (!hash(sha)) throw new Error(`PR #${pr.number}: ${head}~${back} unresolvable — pre-merge base not determinable`);
+    const numbers = (await required(run, 'gh', ['api', `repos/{owner}/{repo}/commits/${sha}/pulls`, '--jq', '.[].number'], repo)).stdout.split(/\s+/).filter(Boolean);
+    ours.push(numbers.includes(String(pr.number)));
+  }
+  if (ours.every(Boolean)) return `${head}~${total}`;
+  if (ours.every((owned) => !owned)) return `${head}^1`;
+  throw new Error(`PR #${pr.number}: merge method ambiguous (${ours.filter(Boolean).length}/${ours.length} of the preceding commits belong to the PR) — pre-merge base not determinable`);
+}
+
+async function measurePr(repo: string, pr: Pr, run: Runner, platform: NodeJS.Platform, keep: boolean, makeTemp: () => string, removeTemp: (path: string) => void): Promise<PrMeasurement> {
+  const head = pr.mergeCommit!.oid;
+  const workspace = makeTemp();
+  const worktree = join(workspace, 'pr');
+  const result: PrMeasurement = { pr: pr.number, head, base: '', worktree, verdict: 'unmeasured', missedDiagnostics: [], addedDiagnostics: [], fullBase: emptyMetrics(), fullHead: emptyMetrics(), narrowed: emptyMetrics(), gateExitCode: null };
+  let attempted = false;
+  try {
+    const base = (await required(run, 'git', ['rev-parse', await preMergeRevision(run, repo, pr, head)], repo)).stdout.trim();
+    if (!hash(base)) throw new Error(`invalid first parent of ${head}: ${base}`);
+    result.base = base;
+    attempted = true;
+    await required(run, 'git', ['worktree', 'add', '--detach', worktree, head], repo);
+    await required(run, 'git', ['checkout', '--detach', base], worktree);
+    await required(run, 'bun', ['install', '--frozen-lockfile'], worktree);
+    const baseRun = await timed(run, platform, './node_modules/.bin/tsc', ['--noEmit', '-p', 'tsconfig.gate.json'], worktree);
+    result.fullBase = elapsed(baseRun, platform);
+    const baseline = fullDiagnostics(baseRun, worktree);
+    await required(run, 'git', ['checkout', '--detach', head], worktree);
+    await required(run, 'bun', ['install', '--frozen-lockfile'], worktree);
+    const headRun = await timed(run, platform, './node_modules/.bin/tsc', ['--noEmit', '-p', 'tsconfig.gate.json'], worktree);
+    result.fullHead = elapsed(headRun, platform);
+    const current = fullDiagnostics(headRun, worktree);
+    const added = compareDiagnostics(current, baseline);
+    if (added.kind === 'unavailable') throw new Error(added.reason);
+    result.addedDiagnostics = added.added;
+    const gateRun = await timed(run, platform, 'bun', ['scripts/ci-typecheck-changed.ts', '--local'], worktree, { ...process.env, TSC_BASE_REF: base });
+    result.narrowed = elapsed(gateRun, platform);
+    result.gateExitCode = gateRun.status;
+    const seen = gateDiagnostics(gateRun, worktree);
+    const unseen = compareDiagnostics(added.added, seen);
+    result.missedDiagnostics = unseen.kind === 'added' ? unseen.added : [];
+    result.verdict = added.added.length > 0
+      ? gateRun.status === 0 || result.missedDiagnostics.length > 0 ? 'missed' : 'same'
+      : gateRun.status === 0 ? 'same' : 'stricter';
+  } catch (error) {
+    result.reason = error instanceof Error ? error.message : String(error);
+    result.verdict = 'unmeasured';
+  } finally {
+    if (!keep) {
+      try {
+        if (attempted) {
+          const removed = await run('git', ['worktree', 'remove', '--force', worktree], repo);
+          if (removed.error || removed.signal || (removed.status !== 0 && !/is not a working tree|is not a worktree/i.test(removed.stderr))) throw new Error(`git worktree remove: ${reason(removed)}`);
+        }
+      } catch (error) {
+        if (result.verdict !== 'missed') result.verdict = 'unmeasured';
+        result.reason = `${result.reason ? `${result.reason}; ` : ''}cleanup failed: ${error instanceof Error ? error.message : String(error)}`;
+      }
+      try { removeTemp(workspace); }
+      catch (error) {
+        if (result.verdict !== 'missed') result.verdict = 'unmeasured';
+        result.reason = `${result.reason ? `${result.reason}; ` : ''}workspace cleanup failed: ${error instanceof Error ? error.message : String(error)}`;
+      }
+    }
+    debug.log('tsc.affected-roots', 'measure-pr', { pr: result.pr, head, base: result.base, verdict: result.verdict, missedDiagnostics: result.missedDiagnostics.length, fullBase: result.fullBase, fullHead: result.fullHead, narrowed: result.narrowed, reason: result.reason });
+  }
+  return result;
+}
+
+export async function measureAffectedRoots(repo: string, argv: readonly string[] = [], options: Options = {}): Promise<MeasurementReport> {
+  const opts = optionsFromArgs(argv);
+  const run = options.run ?? spawnRunner;
+  const prs = await selectPrs(repo, opts, run);
+  if (prs.length === 0) throw new Error('no merged TypeScript PRs to measure');
+  const rows: PrMeasurement[] = [];
+  for (const pr of prs) rows.push(await measurePr(repo, pr, run, options.platform ?? process.platform, opts.keep, options.makeTemp ?? (() => mkdtempSync(join(tmpdir(), 'tsc-affected-roots-'))), options.removeTemp ?? ((path) => rmSync(path, { recursive: true, force: true }))));
+  const summary = { missed: rows.filter((row) => row.verdict === 'missed').length, same: rows.filter((row) => row.verdict === 'same').length, stricter: rows.filter((row) => row.verdict === 'stricter').length, unmeasured: rows.filter((row) => row.verdict === 'unmeasured').length, of: rows.length };
+  return { prs: rows, summary, exitCode: summary.missed ? 1 : summary.unmeasured ? 2 : 0 };
+}
+export function formatReport(report: MeasurementReport, json = false): string {
+  if (json) return JSON.stringify(report);
+  const metric = (m: Metrics) => `${m.durationMs === null ? '—' : Math.round(m.durationMs)} / ${m.rssMb === null ? '—' : m.rssMb}`;
+  return [
+    'PR | verdict | missed diagnostics | full base ms/RSS MB | full head ms/RSS MB | narrowed ms/RSS MB',
+    ...report.prs.map((row) => `#${row.pr} | ${row.verdict} | ${row.missedDiagnostics.length} | ${metric(row.fullBase)} | ${metric(row.fullHead)} | ${metric(row.narrowed)}${row.reason ? ` | ${row.reason}` : ''}`),
+    `missed=${report.summary.missed} same=${report.summary.same} stricter=${report.summary.stricter} unmeasured=${report.summary.unmeasured} of ${report.summary.of}`,
+  ].join('\n');
+}
+if (import.meta.main) {
+  try {
+    const argv = process.argv.slice(2);
+    const report = await measureAffectedRoots(resolve(process.cwd()), argv);
+    console.log(formatReport(report, argv.includes('--json')));
+    process.exitCode = report.exitCode;
+  } catch (error) {
+    console.error(`tsc affected roots measurement unavailable: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 2;
+  }
+}

package/scripts/openai-relay-server.ts

@@ -17,11 +17,15 @@ import { resolveGrokCredential } from '../src/grok/credential.js';
 import { debug } from '../src/debug/log.js';
 import { getOpenAiRelaySharedSecret, hydrateEnvFromKeyCache } from '../src/config.js';
 import { registerLogStoreSink } from '../src/mss/logging/log-store.js';
+import { getUserConfig } from '../src/user-config.js';
 
 // ⛔ 독립 프로세스라 데몬의 부팅 배선을 안 탄다 — 스토어 싱크를 «직접» 단다.
 //    이걸 안 달면 debug.log 가 화면에만 남고 `elanous logs` 조회에 «영영 안 닿는다»
 //    (2026-08-23 실측: nexus.openai-relay 는 닿았고 이 프로세스 자기 로그는 0건이었다).
-registerLogStoreSink(debug.registerSink.bind(debug), 'openai-relay');
+// 🩸 10-09 22:2x: 보존 설정 없이 등록하면 기본 상한 500MB 로 시작 보존이 돈다 — 운영 config 는 4000MB 인데
+//    레일 설치마다 재기동되는 이 프로세스가 1.1GB logs.db 의 행을 최대 50% 지웠다(«지운 주체가 안 보이는» 소실).
+//    다른 독립 스크립트처럼 config 의 보존 값을 넘긴다.
+registerLogStoreSink(debug.registerSink.bind(debug), 'openai-relay', getUserConfig().logs.retention);
 
 const MODELS_PATH = '/v1/models';
 const HEALTH_PATH = '/healthz';

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;
 }