elanous 0.2.21 → 0.2.23

package/scripts/lib/typecheck-ratchet.ts

@@ -0,0 +1,51 @@
+import { resolve } from 'node:path';
+import ts from 'typescript';
+
+/** Select root files affected by changed TypeScript files through the resolved reverse-import graph.
+ * Paths in rootNames are preserved for the compiler; changed paths may be relative to cwd.
+ * This is selection only: the caller owns project scope, hub policy and compiler execution.
+ */
+export function selectAffectedRootNames(
+  rootNames: readonly string[],
+  changedFiles: ReadonlySet<string>,
+  compilerOptions: ts.CompilerOptions,
+  host: ts.ModuleResolutionHost = ts.sys,
+  cwd = process.cwd(),
+): string[] {
+  const absolute = (file: string) => resolve(cwd, file);
+  const roots = new Set(rootNames.map(absolute));
+  const queue = [...changedFiles].filter((file) => /\.[cm]?tsx?$/.test(file)).map(absolute);
+  // No changed TypeScript file: nothing can be affected, so the dependency graph is never read.
+  if (queue.length === 0) return [];
+  const reverse = new Map<string, Set<string>>();
+  const pending = [...roots];
+  const visited = new Set<string>();
+
+  while (pending.length > 0) {
+    const file = pending.pop()!;
+    if (visited.has(file)) continue;
+    visited.add(file);
+    const source = host.readFile?.(file);
+    if (source === undefined) throw new Error(`Cannot read typecheck root dependency: ${file}`);
+    for (const imported of ts.preProcessFile(source, true, true).importedFiles) {
+      const dependency = ts.resolveModuleName(imported.fileName, file, compilerOptions, host).resolvedModule?.resolvedFileName;
+      if (!dependency) continue;
+      const path = absolute(dependency);
+      if (!reverse.has(path)) reverse.set(path, new Set());
+      reverse.get(path)!.add(file);
+      if (!visited.has(path)) pending.push(path);
+    }
+  }
+
+  // A deleted module cannot be resolved from the current tree. Without a previous
+  // dependency graph, an empty reverse edge is not evidence that no root imports it.
+  if (queue.some((file) => !host.fileExists(file))) return [...rootNames];
+  const affected = new Set<string>();
+  while (queue.length > 0) {
+    const file = queue.pop()!;
+    if (affected.has(file)) continue;
+    affected.add(file);
+    for (const importer of reverse.get(file) ?? []) queue.push(importer);
+  }
+  return rootNames.filter((file) => affected.has(absolute(file)));
+}

package/scripts/nightly-docops.ts

@@ -16,6 +16,7 @@ import { createGitHubIssueCommentFetchStatus, lintDocLinks, lintGitHubIssueComme
 import { proposeWikiClaimsFromHandoff, type Claim } from '../src/autopilot/discovery/wiki-claim-proposer.js';
 import { runNightlyDocOpsCycle, assertLoopbackModelUrl } from '../src/autopilot/discovery/nightly-docops-runner.js';
 import { assessDocsStaleness, defaultStalenessRevisions } from '../src/autopilot/discovery/doc-staleness.js';
+import { defaultManualFiles, scanDocRot } from './docs/doc-rot.js';
 import { debug } from '../src/debug/log.js';
 import { registerStandaloneLogSink } from '../src/domains/standalone-log-sink.js';
 import {
@@ -51,13 +52,27 @@ const githubHeaders: Record<string, string> = { Accept: 'application/vnd.github+
 if (process.env.GITHUB_TOKEN) githubHeaders.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
 const issueCommentFetchStatus = createGitHubIssueCommentFetchStatus(fetch, githubHeaders);
 
-export function formatNightlyDocOpsCompletion(metrics: Awaited<ReturnType<typeof runNightlyDocOpsCycle>>): string {
+export type DocRotStageResult =
+  | { status: 'measured'; totals: ReturnType<typeof scanDocRot>['totals']; staleFiles: Array<{
+      file: string;
+      missingPaths: ReturnType<typeof scanDocRot>['files'][number]['missingPaths'];
+      badCommands: ReturnType<typeof scanDocRot>['files'][number]['commands'];
+    }> }
+  | { status: 'failed'; error: string };
+
+export function formatNightlyDocOpsCompletion(
+  metrics: Awaited<ReturnType<typeof runNightlyDocOpsCycle>>,
+  docRot?: DocRotStageResult,
+): string {
   const stalenessLine = metrics.staleness?.status === 'measured'
     ? `늙음 검사 ${metrics.staleness.checked}·사라진 식별자 ${metrics.staleness.byAxis.removedIdentifiers}·깨진 링크 ${metrics.staleness.byAxis.brokenLinks}·superseded ${metrics.staleness.byAxis.supersededMarked}·staleScore ${metrics.staleness.byAxis.staleScoreOverThreshold}·문서목록 ${metrics.staleness.removedIdentifierDocuments.length}${metrics.staleness.removedIdentifierDocumentsTruncated ? '+' : ''}`
     : metrics.staleness?.status === 'failed'
       ? `늙음 측정 실패(${metrics.staleness.error})`
       : '늙음 측정 미지정';
-  return `[nightly-docops] 완료 — 처리 ${metrics.processed}·후보 ${metrics.candidates}·제안 ${metrics.proposals}·억제 ${metrics.suppressed}·에러 ${metrics.errors}·${stalenessLine}·${metrics.durationMs}ms → ${outDir} (HITL 승인 대기)`;
+  const docRotLine = docRot?.status === 'measured'
+    ? `·doc-rot 낡은 파일 ${docRot.totals.staleFiles}·없는 경로 ${docRot.totals.missingPaths}·깨진 명령 ${docRot.totals.badCommands}·못 잰 명령 ${docRot.totals.unmeasured}`
+    : docRot?.status === 'failed' ? `·doc-rot 측정 실패(${docRot.error})` : '';
+  return `[nightly-docops] 완료 — 처리 ${metrics.processed}·후보 ${metrics.candidates}·제안 ${metrics.proposals}·억제 ${metrics.suppressed}·에러 ${metrics.errors}·${stalenessLine}${docRotLine}·${metrics.durationMs}ms → ${outDir} (HITL 승인 대기)`;
 }
 
 /**
@@ -102,6 +117,76 @@ export function stalenessEventName(staleness: { status: string } | undefined): s
   return staleness.status === 'failed' ? 'staleness-failed' : 'staleness-measured';
 }
 
+export function buildDocRotStage(
+  repoRoot: string,
+  deps: { scan?: typeof scanDocRot; files?: () => string[] } = {},
+): () => DocRotStageResult {
+  const scan = deps.scan ?? scanDocRot;
+  const files = deps.files ?? (() => defaultManualFiles(repoRoot));
+  return () => {
+    try {
+      const report = scan({ repoRoot, files: files() });
+      return {
+        status: 'measured',
+        totals: report.totals,
+        staleFiles: report.files.flatMap((entry) => {
+          const badCommands = entry.commands.filter((finding) =>
+            finding.kind === 'unknown-command' || finding.kind === 'unknown-subcommand' || finding.kind === 'unknown-flag');
+          return entry.missingPaths.length || badCommands.length
+            ? [{ file: entry.file, missingPaths: entry.missingPaths, badCommands }]
+            : [];
+        }),
+      };
+    } catch (error) {
+      return { status: 'failed', error: error instanceof Error ? error.message : String(error) };
+    }
+  };
+}
+
+export interface DocRotRecordDeps {
+  outDir: string;
+  nowDate: string;
+  mkdir?: (dir: string) => void;
+  write?: (path: string, body: string) => void;
+  log?: (category: string, event: string, data: Record<string, unknown>) => void;
+}
+
+/**
+ * doc-rot 단계 결과를 ⑴ `doc-rot-<날짜>.json` 보고서 ⑵ `docs.rot` 관측 이벤트로 남긴다.
+ * 보고서·관측 어느 쪽이 실패해도 던지지 않는다 — 야간 사이클의 종료 코드를 바꾸지 않는다.
+ */
+export function recordDocRotStage(
+  docRot: DocRotStageResult,
+  deps: DocRotRecordDeps,
+): { reportPath: string | null; writeError: string | null } {
+  const mkdir = deps.mkdir ?? ((dir: string) => { mkdirSync(dir, { recursive: true }); });
+  const write = deps.write ?? ((path: string, body: string) => { writeFileSync(path, body); });
+  const log = deps.log ?? ((category: string, event: string, data: Record<string, unknown>) => { debug.log(category, event, data); });
+  const reportPath = join(deps.outDir, `doc-rot-${deps.nowDate}.json`);
+  let writeError: string | null = null;
+  try {
+    mkdir(deps.outDir);
+    write(reportPath, JSON.stringify(docRot, null, 2));
+  } catch (error) {
+    // 보고서 파일을 못 써도 측정 결과는 버리지 않는다 — 원인은 관측 이벤트에 따로 싣는다.
+    writeError = error instanceof Error ? error.message : String(error);
+  }
+  try {
+    const totals = docRot.status === 'measured' ? docRot.totals : null;
+    log('docs.rot', docRot.status === 'measured' ? 'nightly-scanned' : 'nightly-failed', {
+      files: totals?.files ?? null,
+      staleFiles: totals?.staleFiles ?? null,
+      missingPaths: totals?.missingPaths ?? null,
+      badCommands: totals?.badCommands ?? null,
+      unmeasured: totals?.unmeasured ?? null,
+      error: docRot.status === 'failed' ? docRot.error : null,
+      reportPath: writeError ? null : reportPath,
+      writeError,
+    });
+  } catch { /* 관측 실패가 야간 사이클의 종료 코드를 바꾸지 않는다 */ }
+  return { reportPath: writeError ? null : reportPath, writeError };
+}
+
 if (import.meta.main) {
 await registerStandaloneLogSink('scheduler');
 mkdirSync(ckDir, { recursive: true });
@@ -156,7 +241,9 @@ const metrics = await runNightlyDocOpsCycle({
   },
 }, { batchLimit: 15, maxRetryPerItem: 1 });
 
-console.log(formatNightlyDocOpsCompletion(metrics));
+const docRot = buildDocRotStage(repoRoot)();
+recordDocRotStage(docRot, { outDir, nowDate });
+console.log(formatNightlyDocOpsCompletion(metrics, docRot));
 }
 
 // ── arc2 되살리기 · 의미 supersede 계층 (gemma-4 · 제목/토픽 클러스터 bounded · 미션 668871) ──

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

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