elanous 0.2.36 → 0.2.38

package/scripts/ratchets/next-tui-entry-budget.ts

@@ -0,0 +1,124 @@
+import ts from 'typescript';
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+
+export const ENTRY_LINE_LIMIT = 4_000;
+export const ENTRY_MODULE_LIMIT = 1_188;
+export const INDEX_MODULE_LIMIT = 1_264;
+const DASHBOARD_BASELINE = 'src/dashboard/loop-scheduler.ts';
+
+export interface AuditResult { errors: string[]; notes: string[]; entryModules: number; indexModules: number; oversized: Array<{ file: string; lines: number }> }
+
+function walkTs(root: string): string[] {
+  return readdirSync(root).flatMap((name) => {
+    const path = join(root, name);
+    return statSync(path).isDirectory() ? walkTs(path) : /\.(?:[cm]?ts|tsx)$/.test(path) ? [path] : [];
+  });
+}
+
+function isInside(root: string, path: string): boolean {
+  const rel = relative(root, path);
+  return rel === '' || (!rel.startsWith(`..${sep}`) && rel !== '..' && !resolve(path).startsWith(`${resolve(root, 'node_modules')}${sep}`));
+}
+
+function staticClosure(repo: string, entry: string): Set<string> {
+  const configPath = join(repo, 'tsconfig.json');
+  const config = ts.readConfigFile(configPath, ts.sys.readFile);
+  if (config.error) throw new Error(ts.flattenDiagnosticMessageText(config.error.messageText, '\n'));
+  const parsed = ts.parseJsonConfigFileContent(config.config, ts.sys, repo);
+  if (parsed.errors.length) throw new Error(parsed.errors.map((diagnostic) => ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n')).join('; '));
+  const options = parsed.options;
+  const seen = new Set<string>();
+  const visit = (file: string): void => {
+    const abs = resolve(file);
+    if (seen.has(abs)) return;
+    seen.add(abs);
+    const source = ts.createSourceFile(abs, readFileSync(abs, 'utf8'), ts.ScriptTarget.Latest, true);
+    for (const node of source.statements) {
+      if (ts.isImportDeclaration(node)) {
+        if (node.importClause?.isTypeOnly || !ts.isStringLiteral(node.moduleSpecifier)) continue;
+        const specifier = node.moduleSpecifier.text;
+        const result = ts.resolveModuleName(specifier, abs, options, ts.sys).resolvedModule;
+        if (!result) {
+          if (specifier.startsWith('.') || specifier.startsWith('/')) throw new Error(`unresolved static import ${relative(repo, abs)} -> ${specifier}`);
+          continue;
+        }
+        if (isInside(repo, result.resolvedFileName)) visit(result.resolvedFileName);
+      } else if (ts.isExportDeclaration(node) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+        if (node.isTypeOnly) continue;
+        const specifier = node.moduleSpecifier.text;
+        const result = ts.resolveModuleName(specifier, abs, options, ts.sys).resolvedModule;
+        if (!result) {
+          if (specifier.startsWith('.') || specifier.startsWith('/')) throw new Error(`unresolved static re-export ${relative(repo, abs)} -> ${specifier}`);
+          continue;
+        }
+        if (isInside(repo, result.resolvedFileName)) visit(result.resolvedFileName);
+      }
+    }
+  };
+  visit(entry);
+  return seen;
+}
+
+export function entryBudgetAffected(changedFiles: readonly string[]): boolean {
+  if (changedFiles.some((file) => file === 'bin/elanous.mjs' || file === 'tsconfig.json' || file === 'scripts/ratchets/next-tui-entry-budget.ts')) return true;
+  // Any source edit can add/remove an importer or delete a module from a base
+  // closure. The changed tree alone cannot prove non-membership in the base graph.
+  return changedFiles.some((file) => /^src\/.+\.[cm]?[jt]sx?$/.test(file));
+}
+
+export function audit(repo: string): AuditResult {
+  const errors: string[] = [];
+  const notes: string[] = [];
+  const tuiFiles = [join(repo, 'src/tui.ts'), ...walkTs(join(repo, 'src/tui'))];
+  const oversized = tuiFiles.map((file) => {
+    const contents = readFileSync(file, 'utf8');
+    const lines = contents.length === 0 ? 0 : contents.split(/\r?\n/).length - (contents.endsWith('\n') ? 1 : 0);
+    return { file: relative(repo, file), lines };
+  })
+    .filter(({ lines }) => lines > ENTRY_LINE_LIMIT);
+  for (const item of oversized) errors.push(`${item.file}: ${item.lines} lines exceeds ${ENTRY_LINE_LIMIT}`);
+
+  const entryClosure = staticClosure(repo, join(repo, 'src/tui/entry.ts'));
+  const entryPaths = [...entryClosure].map((file) => relative(repo, file).replaceAll('\\', '/'));
+  if (entryClosure.size > ENTRY_MODULE_LIMIT) errors.push(`Next entry static module count ${entryClosure.size} exceeds ${ENTRY_MODULE_LIMIT}`);
+  else if (entryClosure.size < ENTRY_MODULE_LIMIT) notes.push(`tighten entry module cap ${ENTRY_MODULE_LIMIT} -> ${entryClosure.size}`);
+  const forbiddenIndex = entryPaths.filter((p) => p === 'src/index.ts');
+  if (forbiddenIndex.length) errors.push('Next entry statically imports forbidden src/index.ts');
+  const dashboard = entryPaths.filter((p) => p.startsWith('src/dashboard/'));
+  const unexpectedDashboard = dashboard.filter((p) => p !== DASHBOARD_BASELINE);
+  if (unexpectedDashboard.length) errors.push(`forbidden dashboard static imports: ${unexpectedDashboard.join(', ')}`);
+  if (dashboard.includes(DASHBOARD_BASELINE)) notes.push(`${DASHBOARD_BASELINE} is temporary baseline; remove at NEXT-TUI-EXTRACT-FROM-INDEX`);
+
+  const binPath = join(repo, 'bin/elanous.mjs');
+  const bin = readFileSync(binPath, 'utf8');
+  // The deployment entry sends every unrecognized route to src/index.ts. The current
+  // light router does not claim --tui next, so measure that fallback's static closure.
+  const binSource = ts.createSourceFile(binPath, bin, ts.ScriptTarget.Latest, true, ts.ScriptKind.JS);
+  let importsIndex = false;
+  const visitBin = (node: ts.Node): void => {
+    if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword
+      && node.arguments[0] && ts.isStringLiteral(node.arguments[0])
+      && /(?:^|\/)src\/index\.ts$/.test(node.arguments[0].text.replaceAll('\\', '/'))) importsIndex = true;
+    ts.forEachChild(node, visitBin);
+  };
+  visitBin(binSource);
+  const indexClosure = importsIndex ? staticClosure(repo, join(repo, 'src/index.ts')) : new Set<string>();
+  if (importsIndex && indexClosure.size > INDEX_MODULE_LIMIT) errors.push(`bin --tui next index static module count ${indexClosure.size} exceeds ${INDEX_MODULE_LIMIT}`);
+  else if (importsIndex && indexClosure.size < INDEX_MODULE_LIMIT) notes.push(`tighten index module cap ${INDEX_MODULE_LIMIT} -> ${indexClosure.size} after entry extraction`);
+  else if (!importsIndex) notes.push('bin has no dynamic import of src/index.ts; index fallback budget no longer applies');
+  return { errors, notes, entryModules: entryClosure.size, indexModules: indexClosure.size, oversized };
+}
+
+if (import.meta.main) {
+  try {
+    const result = audit(resolve(dirname(new URL(import.meta.url).pathname), '../..'));
+    console.log(`NEXT_TUI_ENTRY_BUDGET entryModules=${result.entryModules} indexModules=${result.indexModules} oversized=${result.oversized.length}`);
+    for (const note of result.notes) console.log(`NOTE ${note}`);
+    for (const error of result.errors) console.error(`FAIL ${error}`);
+    process.exitCode = result.errors.length ? 1 : 0;
+  } catch (error) {
+    console.error(`UNMEASURED ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 2;
+  }
+}

package/scripts/ratchets/train-side-invariants.sh

@@ -1,11 +1,12 @@
 #!/usr/bin/env bash
-# Train-side sentinel for the eight real HARD 0.2.32 regressions. Run on the
+# Train-side sentinel for the HARD regressions and release-critical invariants. Run on the
 # merged side tree before the changed-file gate; never interpret a missing test
 # or an incomplete run as a pass.
 set -u
 
 files=(
   scripts/ratchets/test-interference-patterns.test.ts
+  scripts/ratchets/next-tui-entry-budget.test.ts
   src/domains/finance-cli.test.ts
   src/instance/state-dir-provenance-ratchet.test.ts
   src/self-implement/graph-yaml.test.ts
@@ -13,6 +14,11 @@ files=(
   test/identity-env.test.ts
   test/no-absolute-path-imports.test.ts
   test/scenarios/integration.test.ts
+  test/rules-contract.test.ts
+  test/hook-order-sweep.test.ts
+  src/cli/g6a-commands.test.ts
+  test/spawn-sync-max-buffer.test.ts
+  test/telegram-coding-model-terra.test.ts
 )
 
 if [[ ${1:-} == --list ]]; then

package/scripts/release-loop/cut-branch.ts

@@ -6,7 +6,18 @@ import { join, resolve } from 'node:path';
 import { debug } from '../../src/debug/log.js';
 import { isReleaseVersion } from './release-version.js';
 
-export interface CutBranchOptions { version: string; base: string; pick: string[]; append?: boolean; dryRun?: boolean; repoRoot?: string; log?: (line: string) => void }
+export interface CutBranchOptions {
+  version: string;
+  /** Optional only on the --append path (RELEASE-APPEND-BASE-AUTO); required without --append. */
+  base?: string;
+  pick: string[];
+  append?: boolean;
+  dryRun?: boolean;
+  repoRoot?: string;
+  log?: (line: string) => void;
+  /** Run ledger's version-release record ({ commit, branch, base? }) — consulted when --append omits --base. */
+  ledger?: () => { commit?: unknown; base?: unknown; branch?: unknown } | undefined;
+}
 
 // git-spawn-allow: release branch operations happen only in an isolated temporary worktree; main is never checked out or changed.
 function git(repo: string, args: string[]): string {
@@ -21,24 +32,35 @@ function ancestor(repo: string, sha: string, ref: string): boolean {
   return result.status === 0;
 }
 
+/** RELEASE-APPEND-BASE-AUTO: the first parent of a release-branch tip — the commit main was cut from when the branch carries only release-side commits. */
+function firstParent(repo: string, sha: string): string | undefined {
+  const parts = git(repo, ['rev-list', '--parents', '-n', '1', sha]).split(/\s+/);
+  const parent = parts[1];
+  return parent !== undefined && /^[0-9a-f]{40}$/i.test(parent) ? parent : undefined;
+}
+
+/** RELEASE-APPEND-BASE-AUTO: the main cut recorded by the run ledger's version-release node — its base field when present, else the first parent of its commit. Unresolvable records degrade to undefined so the caller keeps its refusal. */
+function ledgerCut(repo: string, recorded: { commit?: unknown; base?: unknown; branch?: unknown } | undefined): string | undefined {
+  if (!recorded) return undefined;
+  try {
+    if (typeof recorded.base === 'string' && /^[0-9a-f]{7,40}$/i.test(recorded.base)) return git(repo, ['rev-parse', '--verify', `${recorded.base}^{commit}`]);
+    if (typeof recorded.commit === 'string' && /^[0-9a-f]{7,40}$/i.test(recorded.commit)) return firstParent(repo, git(repo, ['rev-parse', '--verify', `${recorded.commit}^{commit}`]));
+  } catch { return undefined; }
+  return undefined;
+}
+
 export function cutReleaseBranch(opts: CutBranchOptions): { branch: string; commit: string | null; dryRun: boolean } {
   const repo = resolve(opts.repoRoot ?? process.cwd());
   const branch = `release/${opts.version}`;
   const log = opts.log ?? console.log;
-  const report = (event: 'created' | 'refused' | 'conflict' | 'appended', reason?: string, commit?: string, extra?: Record<string, string | string[]>) =>
+  const report = (event: 'created' | 'refused' | 'conflict' | 'appended' | 'base-resolved' | 'base-corrected', reason?: string, commit?: string, extra?: Record<string, string | string[]>) =>
     debug.log('release-loop.cut-branch', event, { version: opts.version, branch, ...(commit ? { commit } : {}), ...(reason ? { reason } : {}), ...extra });
   try {
     if (!isReleaseVersion(opts.version)) throw new Error(`invalid release version: ${opts.version}`);
     if (!opts.pick.length) throw new Error('at least one --pick commit is required');
-    for (const sha of [opts.base, ...opts.pick]) if (!/^[0-9a-f]{7,40}$/i.test(sha)) throw new Error(`invalid commit SHA: ${sha}`);
+    if (opts.base === undefined && !opts.append) throw new Error('--base is required without --append');
+    for (const sha of [opts.base, ...opts.pick]) if (sha !== undefined && !/^[0-9a-f]{7,40}$/i.test(sha)) throw new Error(`invalid commit SHA: ${sha}`);
     git(repo, ['fetch', 'origin', 'main']);
-    const base = git(repo, ['rev-parse', '--verify', `${opts.base}^{commit}`]);
-    if (!ancestor(repo, base, 'origin/main')) throw new Error(`base ${base} is not an ancestor of origin/main`);
-    const picks = opts.pick.map((sha) => git(repo, ['rev-parse', '--verify', `${sha}^{commit}`]));
-    for (const sha of picks) if (!ancestor(repo, sha, 'origin/main')) throw new Error(`pick ${sha} is not an ancestor of origin/main`);
-    for (const sha of picks) if (ancestor(repo, sha, base)) throw new Error(`pick ${sha} is already in base ${base}`);
-    if (new Set(picks).size !== picks.length) throw new Error('duplicate --pick commit');
-    for (const sha of picks) if (git(repo, ['rev-list', '--parents', '-n', '1', sha]).split(' ').length !== 2) throw new Error(`pick ${sha} must have exactly one parent`);
     const remoteLine = git(repo, ['ls-remote', '--heads', 'origin', `refs/heads/${branch}`]);
     if (remoteLine && !opts.append) throw new Error(`${branch} already exists on origin — use --append to fast-forward more picks onto it`);
     if (!remoteLine && opts.append) throw new Error(`${branch} does not exist on origin — omit --append to create it`);
@@ -50,13 +72,40 @@ export function cutReleaseBranch(opts: CutBranchOptions): { branch: string; comm
       git(repo, ['fetch', 'origin', `refs/heads/${branch}:refs/remotes/origin/${branch}`]);
       remoteTip = git(repo, ['rev-parse', '--verify', `refs/remotes/origin/${branch}^{commit}`]);
       if (advertised !== remoteTip) throw new Error(`${branch} remote tip moved — fast-forward refused (no force push)`);
-      for (const sha of picks) if (ancestor(repo, sha, remoteTip)) throw new Error(`pick ${sha} is already in ${branch}`);
     }
+    // RELEASE-APPEND-BASE-AUTO (OP 0.2.38): a cut commit lives only on the release branch, so the main cut is resolved
+    // before the ancestor refusal — from the run ledger's version-release record, else the release tip's first parent.
+    let base: string;
+    if (opts.base !== undefined) {
+      base = git(repo, ['rev-parse', '--verify', `${opts.base}^{commit}`]);
+    } else {
+      const fromLedger = ledgerCut(repo, opts.ledger?.());
+      const ledgerCandidate = fromLedger !== undefined && ancestor(repo, fromLedger, 'origin/main') ? fromLedger : undefined;
+      const candidate = ledgerCandidate ?? (remoteTip !== undefined ? firstParent(repo, remoteTip) : undefined);
+      if (candidate === undefined || !ancestor(repo, candidate, 'origin/main'))
+        throw new Error(`base ${candidate ?? remoteTip ?? branch} is not an ancestor of origin/main`);
+      base = candidate;
+      report('base-resolved', undefined, base, { source: ledgerCandidate !== undefined ? 'ledger' : 'first-parent' });
+    }
+    if (!ancestor(repo, base, 'origin/main')) {
+      if (!opts.append) throw new Error(`base ${base} is not an ancestor of origin/main`);
+      const parent = firstParent(repo, base);
+      if (parent === undefined || !ancestor(repo, parent, 'origin/main')) throw new Error(`base ${base} is not an ancestor of origin/main`);
+      log(`base ${base} 는 origin/main 에 없다 — 그 부모 ${parent} 를 쓰라 (auto-corrected)`);
+      report('base-corrected', `그 부모 ${parent} 를 쓰라 — ${base} 는 origin/main 에 없다`, base, { parent });
+      base = parent;
+    }
+    const picks = opts.pick.map((sha) => git(repo, ['rev-parse', '--verify', `${sha}^{commit}`]));
+    for (const sha of picks) if (!ancestor(repo, sha, 'origin/main')) throw new Error(`pick ${sha} is not an ancestor of origin/main`);
+    for (const sha of picks) if (ancestor(repo, sha, base)) throw new Error(`pick ${sha} is already in base ${base}`);
+    if (new Set(picks).size !== picks.length) throw new Error('duplicate --pick commit');
+    for (const sha of picks) if (git(repo, ['rev-list', '--parents', '-n', '1', sha]).split(' ').length !== 2) throw new Error(`pick ${sha} must have exactly one parent`);
+    if (opts.append) for (const sha of picks) if (ancestor(repo, sha, remoteTip!)) throw new Error(`pick ${sha} is already in ${branch}`);
     const versionAt = remoteTip ?? base;
     const pkg = JSON.parse(git(repo, ['show', `${versionAt}:package.json`])) as { version?: unknown };
     if (pkg.version !== opts.version) throw new Error(`${opts.append ? 'release branch' : 'base'} package.json version ${pkg.version} is not ${opts.version}`);
     const start = remoteTip ?? base;
-    log(`${branch}: ${start} + ${picks.join(' + ')}${opts.append ? ' (append)' : ''}${opts.dryRun ? ' (dry-run)' : ''}`);
+    log(`${branch}: ${start} + ${picks.join(' + ')}${opts.append ? ' (append)' : ''}${opts.dryRun ? ' (dry-run)' : ''}${base !== start ? ` · base ${base}` : ''}`);
     if (opts.dryRun) return { branch, commit: null, dryRun: true };
     const temp = mkdtempSync(join(tmpdir(), 'release-cut-branch-'));
     const tree = join(temp, 'tree');

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

@@ -22,6 +22,7 @@ interface DocsResult {
   branch?: string;
   worktree?: string;
   translationFallbacks?: number;
+  artifactOwner?: { runId: string; attempt: number; localBackup?: string; remoteBackup?: string; remoteHead?: string };
 }
 
 type TranslationRunner = (line: string) => string;
@@ -495,6 +496,11 @@ export function joinTui(context: GraphContext, env: NodeJS.ProcessEnv, repo: str
 export function graphDocs(context: GraphContext, env: NodeJS.ProcessEnv, repo: string, run: Runner = commandRunner,
   stateRoot = effectiveInstanceRoot()): DocsResult {
   const version = context.input.version;
+  if (context.runId) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(context.runId))
+      return { outcome: 'error', version, error: 'invalid release runId' };
+    return graphDocsOwned(context, env, repo, run, stateRoot);
+  }
   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.
@@ -541,6 +547,137 @@ export function graphDocs(context: GraphContext, env: NodeJS.ProcessEnv, repo: s
   }
 }
 
+type DocsOwner = NonNullable<DocsResult['artifactOwner']>;
+type DocsReceipt = { owner: DocsOwner; branch: string; worktree: string; outcome: 'staged' | 'pushed'; result?: DocsResult; head?: string };
+
+/** The resume count is part of the artifact key; the first run has attempt zero. */
+function docsAttempt(stateRoot: string, version: string, runId: string): number {
+  const path = join(stateRoot, 'release', version, 'resume-attempts', `${runId}.json`);
+  if (!existsSync(path)) return 0;
+  const value = JSON.parse(readFileSync(path, 'utf8')) as { version?: unknown; runId?: unknown; attempts?: unknown };
+  if (value.version !== version || value.runId !== runId || !Array.isArray(value.attempts)
+    || value.attempts.some((at) => typeof at !== 'string' || !Number.isFinite(Date.parse(at))))
+    throw new Error(`invalid release resume attempts ledger: ${path}`);
+  return value.attempts.length;
+}
+
+function docsReceipt(path: string): DocsReceipt | null {
+  if (!existsSync(path)) return null;
+  const value = JSON.parse(readFileSync(path, 'utf8')) as DocsReceipt;
+  if (!value || typeof value !== 'object' || !value.owner || typeof value.owner.runId !== 'string'
+    || !Number.isSafeInteger(value.owner.attempt) || typeof value.worktree !== 'string'
+    || typeof value.branch !== 'string' || !['staged', 'pushed'].includes(value.outcome))
+    throw new Error(`invalid docs ownership receipt: ${path}`);
+  return value;
+}
+
+function remoteBranchHead(run: Runner, repo: string, branch: string): string | null {
+  const line = run('git', ['ls-remote', '--heads', 'origin', `refs/heads/${branch}`], repo).trim();
+  if (!line) return null;
+  const match = /^([0-9a-f]{40})\s+refs\/heads\/[^\s]+$/i.exec(line);
+  if (!match) throw new Error(`invalid remote docs branch response: ${line}`);
+  return match[1]!;
+}
+
+function graphDocsOwned(context: GraphContext, env: NodeJS.ProcessEnv, repo: string, run: Runner, stateRoot: string): DocsResult {
+  const version = context.input.version;
+  const runId = context.runId!;
+  let tree: string | undefined;
+  let owner: DocsOwner | undefined;
+  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 graph: no prefetch slot */ }
+  try {
+    for (const node of ['gate', 'prepare', 'upgrade', 'tui']) if (context.outputs[node]?.outcome !== 'ok') throw new Error(`${node} did not pass`);
+    const attempt = docsAttempt(stateRoot, version, runId);
+    const branch = `release-docs/${version}`;
+    const receiptPath = join(stateRoot, 'release', version, 'docs-branch-owner.json');
+    const previous = docsReceipt(receiptPath);
+    const sameOwner = previous?.owner.runId === runId && previous.owner.attempt === attempt && previous.branch === branch;
+    let cached: DocsCache | null = null;
+    if (mayConsume && cacheDir) { try { cached = loadCache(cacheDir, cutFor(context, stateRoot)); } catch { cached = null; } }
+    run('git', ['fetch', 'origin', 'main'], repo);
+    const main = run('git', ['rev-parse', '--verify', 'origin/main^{commit}'], repo);
+    if (!SHA.test(main)) throw new Error('invalid origin/main commit');
+    let local = '';
+    try { local = run('git', ['show-ref', '--verify', '--hash', `refs/heads/${branch}`], repo).trim(); }
+    catch { /* No local branch is the normal first-run case. */ }
+    const remote = remoteBranchHead(run, repo, branch);
+    owner = { runId, attempt };
+    if (sameOwner && local && existsSync(previous!.worktree)) {
+      tree = previous!.worktree;
+      if (run('git', ['rev-parse', '--abbrev-ref', 'HEAD'], tree) !== branch) throw new Error('docs owner worktree changed branch');
+      if (previous!.outcome === 'pushed' && previous!.head === local && remote === local && previous!.result?.outcome === 'ok')
+        return { ...previous!.result, artifactOwner: previous!.owner };
+      if (remote && run('git', ['merge-base', remote, local], repo) !== remote)
+        throw new Error(`same-run docs remote diverged: ${branch}`);
+    } else {
+      const suffix = `${runId}-${attempt}-${randomUUID()}`;
+      if (local) {
+        const localBackup = `release-docs-backup/${version}/${suffix}`;
+        run('git', ['branch', '-m', branch, localBackup], repo);
+        owner.localBackup = localBackup;
+      }
+      if (remote) {
+        const remoteBackup = `release-docs-backup/${version}/${suffix}`;
+        run('git', ['fetch', 'origin', `refs/heads/${branch}`], repo);
+        if (run('git', ['rev-parse', '--verify', 'FETCH_HEAD^{commit}'], repo) !== remote)
+          throw new Error(`remote docs branch changed while backing up: ${branch}`);
+        const changed = run('git', ['diff', '--name-only', `${main}...${remote}`], repo).split('\n').filter(Boolean);
+        if (changed.some((path) => !path.startsWith('release/public/docs/') && path !== 'website/pages.json'))
+          throw new Error(`foreign docs branch changes outside public docs: ${changed.join(', ')}`);
+        run('git', ['push', 'origin', `${remote}:refs/heads/${remoteBackup}`], repo);
+        if (remoteBranchHead(run, repo, remoteBackup) !== remote) throw new Error('remote docs backup not verified');
+        owner.remoteBackup = remoteBackup;
+        owner.remoteHead = remote;
+      }
+      const useCache = !remote && cached?.main === main && SHA.test(main);
+      if (useCache) {
+        tree = cached!.tree;
+        run('git', ['-C', tree, 'switch', '-c', branch], repo);
+        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, main], repo);
+      }
+      // A foreign ref is incorporated by a normal merge, keeping the original branch fast-forwardable.
+      // Restore the docs inputs from main before generating this run's notes: old output is history, not input.
+      if (remote) {
+        run('git', ['merge', '--no-ff', '--no-edit', remote], tree);
+        run('git', ['restore', '--source', main, '--staged', '--worktree', '--', 'release/public/docs', 'website/pages.json'], tree);
+      }
+      const receipt: DocsReceipt = { owner, branch, worktree: tree, outcome: 'staged' };
+      mkdirSync(dirname(receiptPath), { recursive: true });
+      publish(receiptPath, receipt);
+      if (!useCache) run('bun', ['install', '--frozen-lockfile'], tree);
+    }
+    const result = cached?.tree === tree && 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);
+    const changes = run('git', ['diff', '--cached', '--name-only'], tree).trim();
+    if (changes) run('git', ['commit', '-m', `docs: release ${version}`], tree);
+    // No force: a concurrent remote update fails and leaves both branch and backup intact.
+    run('git', ['push', '-u', 'origin', branch], tree);
+    const head = run('git', ['rev-parse', '--verify', 'HEAD'], tree);
+    const output: DocsResult = { ...result, branch, worktree: tree, artifactOwner: owner };
+    publish(receiptPath, { owner, branch, worktree: tree, outcome: 'pushed', head, result: output } satisfies DocsReceipt);
+    return output;
+  } catch (error) {
+    return { outcome: 'error', version, error: error instanceof Error ? error.message : String(error),
+      ...(tree ? { worktree: tree } : {}), ...(owner ? { artifactOwner: owner } : {}) };
+  }
+}
+
 /** 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'], {
@@ -597,6 +734,9 @@ if (import.meta.main) {
       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 === 'notes-repair') {
+      const { runNotesRepair } = await import('./notes-repair.js');
+      result = await runNotesRepair(readGraphContext()) as typeof result;
     } else if (node === null) result = runDocs(process.argv.slice(2));
     else throw new Error(`unknown release docs node: ${node}`);
   } catch (error) {

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

@@ -5,6 +5,7 @@
 //
 // Read from the tip commit's git objects, never from the working tree (the resume can run from any checkout).
 import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { dirname, join, normalize } from 'node:path/posix';
 import ts from 'typescript';
 import { sourceCandidates } from '../../src/self-implement/importer-test-index.js';
@@ -230,6 +231,53 @@ export function testsReachingChanged(tree: ClosureTree, changed: readonly string
     opaqueFiles: [...opaque].filter(([file]) => !preloadClosure.has(file)).map(([file, why]) => `${file}: ${why}`).sort() };
 }
 
+// TRAIN-REACH-GROUPING — two PRs whose reach sets share a test ride the same release train (their gates
+// cannot be reused independently); disjoint reach sets stay separate trains. Pure and deterministic: the
+// ledger is derived from content alone — no file, clock, or network effects.
+
+/** One PR's reach set for train grouping — the `tests` of a `testsReachingChanged` verdict (`ok: true`). */
+export interface TrainReach {
+  /** The PR that owns this reach set (number or url). */
+  readonly pr: string;
+  /** 도달 시험 집합 — tests reaching the PR's changed files. */
+  readonly tests: readonly string[];
+}
+
+/** 묶음 원장 — train grouping ledger returned by `defineTrainGrouping`. */
+export interface TrainGrouping {
+  /** Train id per PR — both PRs share one id when their reach sets intersect. */
+  readonly trainIds: ReadonlyMap<string, string>;
+  /** The tests both reach sets share (sorted, deduped) — empty when they stay separate trains. */
+  readonly intersection: readonly string[];
+  /** True when the reach sets intersect and the two PRs ride the same train. */
+  readonly sameTrain: boolean;
+}
+
+/** Train id derived from content — same parts give the same id; a sha256 slice keeps the ledger readable. */
+const trainIdOf = (parts: readonly string[]): string =>
+  `train-${createHash('sha256').update(parts.join('\u0000')).digest('hex').slice(0, 12)}`;
+
+/** Bundle two PRs' reach sets into trains: intersecting reach sets get one shared train id, disjoint reach
+ * sets keep separate per-PR ids. Deterministic and side-effect free — same inputs, same ledger. */
+export function defineTrainGrouping(left: TrainReach, right: TrainReach): TrainGrouping {
+  const reachOf = (reach: TrainReach): string[] => [...new Set(reach.tests)].sort();
+  const leftTests = reachOf(left);
+  const rightTests = reachOf(right);
+  const rightSet = new Set(rightTests);
+  const shared = leftTests.filter((test) => rightSet.has(test));
+  const trainIds = new Map<string, string>();
+  if (shared.length > 0) {
+    const sharedId = trainIdOf(shared);
+    trainIds.set(left.pr, sharedId);
+    trainIds.set(right.pr, sharedId);
+  } else {
+    // Disjoint reach sets: mix the PR key into each id so even two empty reach sets stay separate trains.
+    trainIds.set(left.pr, trainIdOf([left.pr, ...leftTests]));
+    trainIds.set(right.pr, trainIdOf([right.pr, ...rightTests]));
+  }
+  return { trainIds, intersection: shared, sameTrain: shared.length > 0 };
+}
+
 /** `[test].preload` of a bunfig.toml text (repo-relative). Null when the file has a preload we cannot parse. */
 export function bunfigPreload(text: string | undefined): string[] | null {
   if (text === undefined) return [];

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

@@ -12,7 +12,8 @@ export function parseFailures(output: string): string[] {
     const line = raw.trim();
     const header = /^(?:\.\/)?((?:[\w.-]+\/)+[\w.-]+\.test\.tsx?):(?:\s|$)/.exec(line);
     if (header) { file = header[1]; continue; }
-    const failed = /^\(fail\)[ \t]+(.+?)(?:[ \t]+\[[\d.]+(?:ms|s)\])?[ \t]*$/.exec(raw);
+    // Line-start only: a title/body `(fail)` is not a reporter row. Trailing CR is still a real Bun fail row.
+    const failed = /^\(fail\)[ \t]+(.+?)(?:[ \t]+\[[\d.]+(?:ms|s)\])?[ \t]*\r?$/.exec(raw);
     if (failed && file) failures.add(`${file} > ${failed[1]!.trim()}`);
   }
   return [...failures].sort();