elanous 0.2.17 → 0.2.18

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

@@ -54,6 +54,8 @@ export interface GateResult {
   knownEnvCleared: string[];
   stalledEnv: Array<{ file: string; reason: 'no-output' | 'isolated-timeout'; local: 'passed' | 'failed' | 'timeout' }>;
   baselineSource?: 'ledger' | 'instance' | 'cut-logs' | 'swept';
+  /** GATE-BASELINE-CACHE — isolated baseline files answered from the ledger (hits) or run now (misses). */
+  baselineCache?: { hits: number; misses: number };
   durationMs: number;
   error?: string;
   stalledShards?: Array<{ shard: number; files: string[]; reason: 'incomplete' | 'no-output' | 'job-failed' | 'unattributed'; lastFile?: string; summaryFailures?: number; namedFailures?: number; detail?: string }>;
@@ -583,6 +585,61 @@ function fileOf(id: string): string {
   return file;
 }
 
+/**
+ * GATE-BASELINE-CACHE (0.2.18) — the isolated `bun run test:deterministic <file>` result of one test file at one commit,
+ * kept in the machine ledger so a later gate does not run it again (0.2.17: the failing files were re-run on the previous
+ * release commit although that release had already measured them). Cache format harvested from draft #24500.
+ * `host` is where the result was measured (`local` or the ssh host) — a result from another host is a miss.
+ * Timeouts are never stored: an environment stall is measured again, not remembered.
+ */
+export interface BaselineFileResult { commit: string; file: string; host: string; failures: string[]; errors: string[]; missing: boolean }
+export const baselineCachePath = (ledger: string, commit: string) => join(ledger, 'gate-baseline-cache', `${commit}.jsonl`);
+function validFileResult(value: unknown, commit: string): value is BaselineFileResult {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const row = value as Partial<BaselineFileResult>;
+  if (row.commit !== commit || typeof row.file !== 'string' || typeof row.host !== 'string' || !row.host.trim()
+    || typeof row.missing !== 'boolean' || !Array.isArray(row.failures) || !Array.isArray(row.errors)
+    || (row.missing && (row.failures.length || row.errors.length))) return false;
+  try {
+    fileOf(`${row.file} > case`);
+    return [...row.failures, ...row.errors].every((id) => typeof id === 'string' && fileOf(id) === row.file);
+  } catch { return false; }
+}
+/** A missing cache file is empty; any unreadable or invalid row discards the whole file — it is never read as a pass. */
+export function readBaselineFileCache(ledger: string, commit: string): Map<string, BaselineFileResult> {
+  const entries = new Map<string, BaselineFileResult>();
+  if (!sha.test(commit)) return entries;
+  const path = baselineCachePath(ledger, commit);
+  if (!existsSync(path)) return entries;
+  try {
+    // The writer always ends with one newline and never writes an empty line — anything else is a damaged file.
+    const text = readFileSync(path, 'utf8');
+    if (!text.endsWith('\n')) throw new Error('missing final newline');
+    for (const line of text.slice(0, -1).split('\n')) {
+      if (!line.trim()) throw new Error('empty line');
+      const row: unknown = JSON.parse(line);
+      if (!validFileResult(row, commit)) throw new Error('invalid row');
+      entries.set(`${row.file}\0${row.host}`, row);
+    }
+  } catch (error) {
+    debug.log('release.gate', 'baseline-cache-corrupt', { path, error: String(error) });
+    entries.clear();
+  }
+  return entries;
+}
+export function saveBaselineFileCache(ledger: string, commit: string, rows: BaselineFileResult[]): void {
+  if (!rows.length || !sha.test(commit)) return;
+  const entries = readBaselineFileCache(ledger, commit);
+  for (const row of rows) entries.set(`${row.file}\0${row.host}`, row);
+  const path = baselineCachePath(ledger, commit);
+  mkdirSync(dirname(path), { recursive: true });
+  const temp = join(dirname(path), `.gate-baseline-${process.pid}-${randomUUID()}.tmp`);
+  try {
+    writeFileSync(temp, [...entries.values()].map((row) => JSON.stringify(row)).join('\n') + '\n', { mode: 0o600 });
+    renameSync(temp, path);
+  } finally { if (existsSync(temp)) rmSync(temp); }
+}
+
 export async function judgeGate(opts: GateOptions, runner: GateRunner = createGateRunner(opts.repo ?? process.cwd(), opts.remote)): Promise<GateResult> {
   const start = Date.now();
   const explicitConfig = getElanousConfigDirOverride();
@@ -743,7 +800,23 @@ export async function judgeGate(opts: GateOptions, runner: GateRunner = createGa
     const diff = diffFailures(countedCut.counted, countedBaseline.counted);
     result.fixed = diff.fixed.length;
     result.preexisting = diff.common.length;
-    for (const file of new Set(diff.newFailures.map(fileOf))) {
+    // GATE-BASELINE-CACHE — only the files whose new failures reproduce in isolation reach the baseline, and each
+    // (commit, file, host) is run at most once across gates: this gate's cut results also seed the next gate's baseline.
+    const cacheHost = opts.remote ?? 'local';
+    const newFailureFiles = new Set(diff.newFailures.map(fileOf));
+    const baseCache = newFailureFiles.size ? readBaselineFileCache(ledger, baseSha) : new Map<string, BaselineFileResult>();
+    const cacheStats = { hits: 0, misses: 0 };
+    const remember = (row: BaselineFileResult) => {
+      // Only a row the reader would accept is stored; an unstorable result skips the cache and leaves the verdict alone.
+      const { commit, file } = row;
+      if (!validFileResult(row, commit)) {
+        debug.log('release.gate', 'baseline-cache-skip', { commit, file });
+        return;
+      }
+      try { saveBaselineFileCache(ledger, row.commit, [row]); }
+      catch (error) { debug.log('release.gate', 'baseline-cache-write-failed', { commit: row.commit, file: row.file, error: String(error) }); }
+    };
+    for (const file of newFailureFiles) {
       // 0.2.15: the cut re-check of a new-failure file (InsidePage.test.tsx · headless Chrome) hung for good — limit it like the host re-run.
       const cutCheck = cutHostFailed.has(file) ? undefined : await runner.command('bun', ['run', 'test:deterministic', asPath(file)], cutTree, GATE_ISOLATED_TIMEOUT_MS);
       if (cutCheck?.timedOut) {
@@ -754,30 +827,42 @@ export async function judgeGate(opts: GateOptions, runner: GateRunner = createGa
       const isolatedCut = cutCheck === undefined
         ? { failures: cut.failures.filter((id) => fileOf(id) === file), errors: cut.errors.filter((id) => fileOf(id) === file) }
         : failuresOf(cutCheck, `cut isolated ${file}`);
+      if (cutCheck !== undefined) remember({ commit: opts.commit, file, host: cacheHost, failures: isolatedCut.failures, errors: isolatedCut.errors, missing: false });
       const reproduced = new Set([...isolatedCut.failures, ...isolatedCut.errors]);
       const candidates = diff.newFailures.filter((id) => fileOf(id) === file && reproduced.has(id));
       if (candidates.length === 0) continue;
-      const baselineTree = await getBaseTree();
-      const previous = await runner.command('bun', ['run', 'test:deterministic', asPath(file)], baselineTree, GATE_ISOLATED_TIMEOUT_MS);
-      if (previous.timedOut) {
-        debug.log('release-loop.gate', 'isolated-timeout', { file, label: 'baseline isolated', limitMs: GATE_ISOLATED_TIMEOUT_MS });
-        result.stalledEnv.push({ file, reason: 'isolated-timeout', local: 'timeout' });
-        continue;
-      }
       let oldFailures: Set<string>;
-      if (/No tests found|had no matches/i.test(previous.output) && previous.rc === 1) {
-        const lookup = await runner.command('git', ['ls-tree', '--name-only', baseSha, '--', file], opts.remote ? baselineTree : repo);
-        if (lookup.rc !== 0 || lookup.output.trim()) throw new Error(`baseline isolated run incomplete: ${file}`);
-        oldFailures = new Set();
+      const hit = baseCache.get(`${file}\0${cacheHost}`);
+      if (hit) {
+        cacheStats.hits++;
+        oldFailures = new Set([...hit.failures, ...hit.errors]);
       } else {
-        const prior = failuresOf(previous, `baseline isolated ${file}`);
-        oldFailures = new Set([...prior.failures, ...prior.errors]);
+        cacheStats.misses++;
+        const baselineTree = await getBaseTree();
+        const previous = await runner.command('bun', ['run', 'test:deterministic', asPath(file)], baselineTree, GATE_ISOLATED_TIMEOUT_MS);
+        if (previous.timedOut) {
+          debug.log('release-loop.gate', 'isolated-timeout', { file, label: 'baseline isolated', limitMs: GATE_ISOLATED_TIMEOUT_MS });
+          result.stalledEnv.push({ file, reason: 'isolated-timeout', local: 'timeout' });
+          continue;
+        }
+        if (/No tests found|had no matches/i.test(previous.output) && previous.rc === 1) {
+          const lookup = await runner.command('git', ['ls-tree', '--name-only', baseSha, '--', file], opts.remote ? baselineTree : repo);
+          if (lookup.rc !== 0 || lookup.output.trim()) throw new Error(`baseline isolated run incomplete: ${file}`);
+          oldFailures = new Set();
+          remember({ commit: baseSha, file, host: cacheHost, failures: [], errors: [], missing: true });
+        } else {
+          const prior = failuresOf(previous, `baseline isolated ${file}`);
+          oldFailures = new Set([...prior.failures, ...prior.errors]);
+          remember({ commit: baseSha, file, host: cacheHost, failures: prior.failures, errors: prior.errors, missing: false });
+        }
       }
       for (const id of candidates) {
         if (oldFailures.has(id)) result.preexisting++;
         else result.introduced.push(id);
       }
     }
+    result.baselineCache = cacheStats;
+    debug.log('release.gate', 'baseline-cache', { hits: cacheStats.hits, misses: cacheStats.misses, commit: baseSha });
     result.outcome = result.introduced.length ? 'regression' : 'ok';
   } catch (error) {
     result.error = error instanceof Error ? error.message : String(error);

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

@@ -1,5 +1,6 @@
 #!/usr/bin/env bun
 import { spawnSync } from 'node:child_process';
+import { isReleaseVersion } from './release-version.js';
 import { readFileSync } from 'node:fs';
 import { debug } from '../../src/debug/log.js';
 
@@ -17,7 +18,7 @@ export function readGraphContext(env: NodeJS.ProcessEnv = process.env): GraphCon
   if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('invalid graph context');
   const context = value as Record<string, unknown>;
   const input = context.input as Record<string, unknown> | undefined;
-  if (!input || typeof input.version !== 'string' || !/^\d+\.\d+\.\d+$/.test(input.version)
+  if (!input || typeof input.version !== 'string' || !isReleaseVersion(input.version)
     || typeof input.previousVersion !== 'string' || !/^\d+\.\d+\.\d+$/.test(input.previousVersion)) throw new Error('version and previousVersion required');
   return { input: input as GraphContext['input'], outputs: context.outputs && typeof context.outputs === 'object' ? context.outputs as GraphContext['outputs'] : {} };
 }

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

@@ -7,6 +7,7 @@ import { debug } from '../../src/debug/log.js';
 import { sendOutbound } from '../../src/domains/outbound-alert.js';
 import { effectiveInstanceRoot, prodInstanceRoot } from '../../src/instance/resolve.js';
 import { emitNodeResult, readGraphContext, type GraphContext } from './node-verdict.js';
+import { prereleaseKind } from './release-version.js';
 
 type Result = { outcome: 'ok' | 'fail'; verdict: 'pass' | 'fail'; summary: string; npm?: 'published' | 'already-published' | 'staged-not-visible'; humanAction?: 'npm-support' };
 type Exec = (command: string, args: string[], env?: NodeJS.ProcessEnv) => { status: number | null; stdout: string; stderr: string };
@@ -47,8 +48,11 @@ function metadata(value: unknown): { name?: string; version?: string } {
 export async function runNpmPublish(context: GraphContext = readGraphContext(), deps: NpmPublishDeps = {}): Promise<Result> {
   const version = context.input.version;
   let token = '';
+  // RELEASE-REHEARSAL-RC: a prerelease goes to `next` so `npm i elanous` never resolves to a rehearsal build.
+  let distTag = 'latest';
   try {
     if (context.outputs.publish?.outcome !== 'ok') throw new Error('publish must succeed before npm publish');
+    distTag = prereleaseKind(version) === null ? 'latest' : 'next';
     const stateDir = deps.stateDir ?? effectiveInstanceRoot();
     // REL3 — the archive prepare actually built (its output) wins over this process's universe: a resumed run can
     // resolve another universe (10-01 0.2.7: prepared in the pilot test universe, resumed in production).
@@ -67,14 +71,14 @@ export async function runNpmPublish(context: GraphContext = readGraphContext(),
       const [manifest, tags] = await Promise.all([readRegistry(`${PACKAGE_URL}/${version}`), readRegistry(PACKAGE_URL)]);
       if (manifest.status !== 200 && manifest.status !== 404) throw new Error(`npm registry version lookup failed (${manifest.status})`);
       if (tags.status !== 200) throw new Error(`npm registry tags lookup failed (${tags.status})`);
-      const latest = tags.body && typeof tags.body === 'object' && 'dist-tags' in tags.body
-        ? (tags.body as { 'dist-tags'?: { latest?: unknown } })['dist-tags']?.latest : undefined;
+      const tagged = tags.body && typeof tags.body === 'object' && 'dist-tags' in tags.body
+        ? (tags.body as { 'dist-tags'?: Record<string, unknown> })['dist-tags']?.[distTag] : undefined;
       if (manifest.status === 200 && (metadata(manifest.body).name !== 'elanous' || metadata(manifest.body).version !== version))
         throw new Error('npm registry version metadata mismatch');
-      return { visible: manifest.status === 200, tagged: manifest.status === 200 && latest === version };
+      return { visible: manifest.status === 200, tagged: manifest.status === 200 && tagged === version };
     };
     const before = await inspect();
-    if (before.tagged) return { outcome: 'ok', verdict: 'pass', npm: 'already-published', summary: `npm ${version} already published with latest tag` };
+    if (before.tagged) return { outcome: 'ok', verdict: 'pass', npm: 'already-published', summary: `npm ${version} already published with ${distTag} tag` };
     if (!before.visible) {
       // The npm token is a machine secret (like the GitHub App key): input → this universe → the production root.
       const tokenFile = context.input.npmTokenFile ?? [join(stateDir, 'secrets', 'npm-token'), join(deps.productionRoot ?? prodInstanceRoot(), 'secrets', 'npm-token')].find((p) => existsSync(p)) ?? join(stateDir, 'secrets', 'npm-token');
@@ -86,7 +90,7 @@ export async function runNpmPublish(context: GraphContext = readGraphContext(),
       try {
         const npmrc = join(dir, 'npmrc');
         writeFileSync(npmrc, `//registry.npmjs.org/:_authToken=${token}\n`, { mode: 0o600, flag: 'wx' });
-        published = run('npm', ['publish', candidate, '--ignore-scripts', '--tag', 'latest', '--access', 'public'], { ...process.env, NPM_CONFIG_USERCONFIG: npmrc });
+        published = run('npm', ['publish', candidate, '--ignore-scripts', '--tag', distTag, '--access', 'public'], { ...process.env, NPM_CONFIG_USERCONFIG: npmrc });
       } finally { rmSync(dir, { recursive: true, force: true }); }
       const output = `${published.stdout}\n${published.stderr}`;
       const staged = published.status !== 0 && /\bE409\b/i.test(output) && /previously staged/i.test(output);
@@ -96,10 +100,10 @@ export async function runNpmPublish(context: GraphContext = readGraphContext(),
     let last = before;
     for (let i = 0; i <= polls; i++) {
       last = await inspect();
-      if (last.tagged) return { outcome: 'ok', verdict: 'pass', npm: before.visible ? 'already-published' : 'published', summary: `npm ${version} visible with latest tag` };
+      if (last.tagged) return { outcome: 'ok', verdict: 'pass', npm: before.visible ? 'already-published' : 'published', summary: `npm ${version} visible with ${distTag} tag` };
       if (i < polls) await wait(Math.min(30_000, waitMinutes * 60_000 - i * 30_000));
     }
-    if (last.visible) throw new Error(`npm ${version} visible but dist-tags.latest did not reach ${version} within ${waitMinutes} minutes`);
+    if (last.visible) throw new Error(`npm ${version} visible but dist-tags.${distTag} did not reach ${version} within ${waitMinutes} minutes`);
     try { (deps.log ?? ((v, minutes) => debug.log('release-loop.npm', 'staged-not-visible', { version: v, waitedMinutes: minutes })))(version, waitMinutes); } catch { /* observation must not mask npm's staged state */ }
     try { (deps.alert ?? sendOutbound)(`npm ${version} 가 스테이징에 멈춤 — 계정 소유자 확인 필요`, 'alert'); } catch { /* alert failure must not block docs */ }
     return { outcome: 'ok', verdict: 'pass', npm: 'staged-not-visible', humanAction: 'npm-support', summary: 'npm 스테이징 — 레지스트리에 아직 없음' };

package/scripts/release-loop/ops-upgrade-node.ts

@@ -4,6 +4,7 @@ import { homedir, tmpdir } from 'node:os';
 import { join, isAbsolute } from 'node:path';
 import { debug } from '../../src/debug/log.js';
 import { errorResult, finishNode, lastResult, nodeOutput, readGraphContext, runCommand, type CommandResult, type CommandRunner } from './node-verdict.js';
+import { prereleaseKind } from './release-version.js';
 
 interface HostResult { host: string; ok: boolean; before: string; after: string; error?: string; skipped?: string; hooks?: string; restart?: 'no-service' }
 /** Where the internal feed is packed from: a checkout of the release tag, never the run's working tree. */
@@ -199,6 +200,12 @@ export function runOpsUpgrade(run: CommandRunner = runCommand, deps: OpsUpgradeD
 
 if (import.meta.main) {
   let version = '';
-  try { version = readGraphContext().input.version; process.exitCode = finishNode('ops-upgrade', version, runOpsUpgrade()); }
+  try {
+    version = readGraphContext().input.version;
+    // RELEASE-REHEARSAL-RC: a prerelease never lands docs on main or upgrades the operating hosts.
+    process.exitCode = finishNode('ops-upgrade', version, prereleaseKind(version) !== null
+      ? { outcome: 'ok', verdict: 'pass', summary: `ops-upgrade skipped — ${version} is a prerelease`, skipped: 'prerelease' }
+      : runOpsUpgrade());
+  }
   catch (error) { process.exitCode = finishNode('ops-upgrade', version, errorResult(error)); }
 }

package/scripts/release-loop/preflight.ts

@@ -0,0 +1,246 @@
+// `elanous release preflight` — 컷 30분 전 사전 점검(RELEASE-PREFLIGHT · 10-06).
+//
+// 🩸 계기(10-06 실측): 0.2.17 릴리스 런이 첫 노드(checklist-gate)에서 멎었다 — «발행 뒤» 칸(POSTPUB-VERIFY)이 그 판에
+//    남아 있었고 게이트가 그것을 미완으로 셌다. 컷이 올 때까지 아무도 몰랐다. 새 규칙 = 착지 마감 = 컷 − 30분, 그 30분에 이 점검.
+// ⛔ 읽기 전용 — 칸을 옮기지도, 동결을 바꾸지도, push 하지도 않는다. 옮길 것은 «명령»으로 제안만 한다.
+// ⛔ 게이트 규칙을 다시 쓰지 않는다 — checklist-gate 노드 · release run 진입 검사 · 예약 시작 준비 검사(releaseReadiness, #24557)가
+//    함께 쓰는 단 하나의 판정 cutChecklistGate 를 그대로 부르고, 예약 시작 경로는 releaseReadiness 를 CLI 와 같은 인자로 부른다.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { cutChecklistGate, listChecklist, type ChecklistItem } from '../../src/release-loop/checklist.js';
+import { getSchedule, formatKst, type ReleaseSchedule } from '../../src/release-loop/release-schedule.js';
+import { readLandingFreeze, landingFreezeMessage, type LandingFreeze } from '../../src/release-loop/landing-freeze.js';
+import { effectiveInstanceRoot } from '../../src/instance/resolve.js';
+import { debug } from '../../src/debug/log.js';
+import { releaseReadiness } from './release-readiness.js';
+import { latestPublishedPreviousVersion, runUnattendedRelease, type UnattendedReleaseDeps } from './unattended-release.js';
+
+export type PreflightLevel = 'ok' | 'warn' | 'block';
+export type PreflightCheck = 'checklist' | 'postpub' | 'run-input' | 'freeze' | 'schedule';
+export interface PreflightFinding { level: PreflightLevel; check: PreflightCheck; id?: string; message: string; suggestion?: string }
+export interface GateMeasure { version: string; runId: string; gateSeconds: number; toPublishSeconds?: number }
+const compareStable = (a: string, b: string) => { const x = a.split('.').map(Number), y = b.split('.').map(Number); return x[0]! - y[0]! || x[1]! - y[1]! || x[2]! - y[2]!; };
+export interface PreflightResult {
+  version: string;
+  next: string;
+  verdict: PreflightLevel;
+  blockers: number;
+  warnings: number;
+  findings: PreflightFinding[];
+  schedule: { cutAt: string; landBy: string | null; publishAt: string | null; publishAtSource: 'option' | 'cadence' | null } | null;
+  /** The immediately previous release (by version order) whose gate is compared. */
+  previousVersion: string | null;
+  gateMeasure: GateMeasure | null;
+  /** When the previous release has no record: the newest measured older release, labelled with its version. */
+  fallbackGateMeasure: GateMeasure | null;
+}
+
+export interface PreflightDeps {
+  now?: Date;
+  /** Planned publish time (ISO). Without it, the October cadence (07:00 · 18:00 KST) after the cut is assumed. */
+  publishAt?: string;
+  runInput?: (version: string) => Promise<{ input: unknown }>;
+  freeze?: () => LandingFreeze | null;
+  schedule?: (version: string) => ReleaseSchedule | null;
+  graphRunsRoot?: string;
+  releaseRunDeps?: UnattendedReleaseDeps;
+  /** The immediately previous release; default = the run input's previousVersion (release ledger). */
+  previousVersion?: string;
+}
+
+const POSTPUB_ID = /^POSTPUB-/i;
+// Only a title that «starts» with the marker: a pre-publish cell often mentions «발행 뒤» in its body (a slot, a plan).
+const POSTPUB_TITLE = /^[«"'(]?\s*(발행\s*(뒤|후)|post-?publish)/i;
+const STABLE = /^\d+\.\d+\.\d+$/;
+
+export function isPostPublishCell(item: Pick<ChecklistItem, 'id' | 'title'> & { kind?: string }): boolean {
+  return POSTPUB_ID.test(item.id) || POSTPUB_TITLE.test(item.title) || (item as { kind?: string }).kind === 'postpub';
+}
+
+export function nextPatch(version: string): string {
+  const [major, minor, patch] = version.split('.').map(Number);
+  return `${major}.${minor}.${patch! + 1}`;
+}
+
+const kstHour = (ms: number) => Number(new Intl.DateTimeFormat('en-GB', { timeZone: 'Asia/Seoul', hour: '2-digit', hourCycle: 'h23' }).format(new Date(ms)));
+
+/** October cadence: the first 07:00 or 18:00 KST strictly after the cut (a cut at 07:00 publishes at 18:00). */
+export function cadencePublishAt(cutAt: string): string {
+  const cut = Date.parse(cutAt);
+  const startOfHour = Math.floor(cut / 3_600_000) * 3_600_000 + 3_600_000;
+  for (let t = startOfHour; t < cut + 48 * 3_600_000; t += 3_600_000) {
+    const h = kstHour(t);
+    if (h === 7 || h === 18) return new Date(t).toISOString();
+  }
+  return new Date(cut).toISOString();
+}
+
+/**
+ * A release's measured gate: the newest finished release-loop run of «that» version (`{ version }`) or, with
+ * `{ below }`, the most recently measured run of any version under it. Node timings are not stored in the run state, so the gate time is the start of the gate node's context file to
+ * the start of the next node's (contexts/<n>.json is written when node n starts). Null when nothing was measured.
+ */
+export function releaseGateMeasure(which: { version: string } | { below: string }, root = join(effectiveInstanceRoot(), 'graph-runs', 'release-loop')): GateMeasure | null {
+  if (!existsSync(root)) return null;
+  const runs: Array<{ runId: string; version: string; startedAt: string; path: string[]; file: string }> = [];
+  for (const file of readdirSync(root)) {
+    if (!file.endsWith('.json') || file.includes('.decision')) continue;
+    try {
+      const state = JSON.parse(readFileSync(join(root, file), 'utf8')) as { runId?: string; status?: string; startedAt?: string; path?: string[]; input?: { version?: string } };
+      const v = state.input?.version;
+      if (state.status !== 'done' || typeof v !== 'string' || !STABLE.test(v) || !Array.isArray(state.path) || typeof state.startedAt !== 'string') continue;
+      if ('version' in which ? v !== which.version : compareStable(v, which.below) >= 0) continue;
+      runs.push({ runId: state.runId ?? file.slice(0, -5), version: v, startedAt: state.startedAt, path: state.path, file });
+    } catch { /* an unreadable run is skipped — the measure is best-effort */ }
+  }
+  // `{ version }`: the newest run of that release. `{ below }` (only a labelled reference when the previous release has
+  // no record): the most recently measured run, not the highest version.
+  runs.sort((a, b) => Date.parse(b.startedAt) - Date.parse(a.startedAt));
+  for (const run of runs) {
+    const contexts = join(root, `${run.file}.contexts`);
+    const index = run.path.indexOf('gate');
+    if (index < 0 || !existsSync(contexts)) continue;
+    const at = (i: number): number | null => {
+      const path = join(contexts, `${i + 1}.json`);
+      try {
+        const ctx = JSON.parse(readFileSync(path, 'utf8')) as { nodeId?: string };
+        return ctx.nodeId === run.path[i] ? statSync(path).mtimeMs : null;
+      } catch { return null; }
+    };
+    const gateStart = at(index), gateEnd = at(index + 1);
+    if (gateStart === null || gateEnd === null || gateEnd < gateStart) continue;
+    const publishIndex = run.path.indexOf('publish');
+    const publishStart = publishIndex >= 0 ? at(publishIndex) : null;
+    return {
+      version: run.version, runId: run.runId, gateSeconds: Math.round((gateEnd - gateStart) / 1000),
+      ...(publishStart !== null ? { toPublishSeconds: Math.round((publishStart - Date.parse(run.startedAt)) / 1000) } : {}),
+    };
+  }
+  return null;
+}
+
+const minutes = (seconds: number) => `${Math.round(seconds / 60)}분`;
+const short = (title: string) => (title.length > 60 ? `${title.slice(0, 60)}…` : title);
+
+export async function releasePreflight(version: string, deps: PreflightDeps = {}): Promise<PreflightResult> {
+  if (!STABLE.test(version)) throw new Error(`release preflight takes a stable version x.y.z: ${version}`);
+  const now = deps.now ?? new Date();
+  const next = nextPatch(version);
+  const findings: PreflightFinding[] = [];
+  const moveHint = (id: string) => `elanous release checklist move ${id} --from ${version} --to ${next} --reason "발행 뒤 칸 — 다음 판에서 확인"`;
+
+  // 1·2. Checklist gate simulation «at the cut» (the node and the run entry both judge after land-by) ⊕ post-publish cells.
+  const schedule = (deps.schedule ?? ((v: string) => getSchedule(v, deps.releaseRunDeps?.ledgerRoot)))(version);
+  // Always the stored cut (before or after it): the preflight simulates «the cut», not the moment it is run.
+  const judgeAt = schedule ? new Date(Date.parse(schedule.cutAt)) : now;
+  const data = listChecklist(version);
+  const { autoMoved, ...gate } = cutChecklistGate(version, schedule?.landBy, judgeAt);
+  const p0 = data.items.filter((item) => item.status === 'yellow' && item.priority === 'P0').map((item) => item.id);
+  const byId = new Map(data.items.map((item) => [item.id, item]));
+  const blockReason = new Map<string, string>();
+  for (const id of gate.red) blockReason.set(id, '빨강');
+  for (const id of gate.undecided) blockReason.set(id, '노랑 · 처분 없음(판정 없음)');
+  for (const id of gate.blocked) blockReason.set(id, p0.includes(id) ? 'P0 노랑' : '노랑 · 처분 block');
+  // The scheduled start (`release run --if-ready` · `auto-start`) first asks releaseReadiness — the same call the CLI
+  // makes, judged at the cut. It shares cutChecklistGate (#24557); an injected deps.checklist may still differ, so any
+  // cell it refuses that the cut judgement did not is reported too (report, don't re-rule).
+  try {
+    const readiness = releaseReadiness(version, { ledgerRoot: deps.releaseRunDeps?.ledgerRoot, checklist: deps.releaseRunDeps?.checklist, now: () => judgeAt });
+    if (readiness.reason === 'checklist-blocked') {
+      for (const id of [...readiness.details.red, ...readiness.details.undecided, ...readiness.details.blocked]) {
+        if (!blockReason.has(id)) blockReason.set(id, '예약 시작(release run --if-ready · auto-start)의 준비 검사(releaseReadiness)가 런을 거부한다');
+      }
+    } else if (readiness.reason === 'already-published' || readiness.reason === 'already-running') {
+      // Both refuse the scheduled start — a running release (live run.lock) or a published one.
+      findings.push({ level: 'block', check: 'run-input', message: `준비 검사(releaseReadiness)가 예약 시작을 거부한다: ${readiness.reason} (${readiness.details})` });
+    }
+  } catch (error) {
+    findings.push({ level: 'block', check: 'run-input', message: `준비 검사(releaseReadiness) 오류 — ${error instanceof Error ? error.message : String(error)}` });
+  }
+  for (const [id, reason] of blockReason) {
+    const item = byId.get(id);
+    const postpub = item ? isPostPublishCell(item) : false;
+    findings.push({
+      level: 'block', check: postpub ? 'postpub' : 'checklist', id,
+      message: `${id} — ${reason}${postpub ? ' · 발행 뒤 칸이 이 판에 남아 있다' : ''}${item ? ` · «${short(item.title)}»` : ''}`,
+      ...(postpub ? { suggestion: moveHint(id) } : {}),
+    });
+  }
+  for (const item of data.items) {
+    if (blockReason.has(item.id) || !isPostPublishCell(item)) continue;
+    findings.push({ level: 'warn', check: 'postpub', id: item.id, message: `${item.id} — 발행 뒤 칸이 이 판에 남아 있다(지금은 막지 않음 · 상태 ${item.status} · 처분 ${item.disposition ?? '-'})`, suggestion: moveHint(item.id) });
+  }
+  for (const id of autoMoved) {
+    if (!blockReason.has(id)) findings.push({ level: 'warn', check: 'checklist', id, message: `${id} — 처분 없는 노랑 · 컷(착지 마감 뒤)에서 노드가 ${next} 로 자동 이월한다` });
+  }
+  for (const p of gate.parity ?? []) findings.push({ level: 'warn', check: 'checklist', id: p.id, message: `${p.id} — 화면 짝 경고: ${p.why}` });
+  if (!blockReason.size) findings.push({ level: 'ok', check: 'checklist', message: `체크리스트 게이트 모의 통과 — ${data.items.length}칸 · 이월 ${gate.moved.length} · 알려진 문제 ${gate.knownIssues.length}` });
+
+  // 3. The same input check `release run --dry-run` makes.
+  let runPrevious: string | undefined;
+  try {
+    const result = await (deps.runInput ?? ((v: string) => runUnattendedRelease({ version: v, dryRun: true }, deps.releaseRunDeps ?? {})))(version);
+    const input = result.input as { previousVersion?: string; gatePodPool?: string };
+    runPrevious = input.previousVersion;
+    findings.push({ level: 'ok', check: 'run-input', message: `release run --dry-run 입력 OK — 직전 판 ${input.previousVersion ?? '-'} · 게이트 풀 ${input.gatePodPool ?? '-'}` });
+  } catch (error) {
+    findings.push({ level: 'block', check: 'run-input', message: `release run --dry-run 입력 오류 — ${error instanceof Error ? error.message : String(error)}` });
+  }
+
+  // 4. Landing freeze (emergency switch since RELEASE-BRANCH): when on, `release run` refuses.
+  try {
+    const frozen = (deps.freeze ?? (() => readLandingFreeze(deps.releaseRunDeps?.freezeRoot)))();
+    if (frozen) findings.push({ level: 'block', check: 'freeze', message: `${landingFreezeMessage(frozen)} — release run 이 거부한다`, suggestion: 'elanous freeze off (또는 의도한 강행이면 release run --force-freeze)' });
+    else findings.push({ level: 'ok', check: 'freeze', message: '착지 동결 꺼짐' });
+  } catch (error) {
+    findings.push({ level: 'block', check: 'freeze', message: `동결 상태를 못 읽었다 — ${error instanceof Error ? error.message : String(error)}` });
+  }
+
+  // 5. Schedule sanity: land-by = cut − 30 min · cut→publish window vs the previous measured gate.
+  let scheduleOut: PreflightResult['schedule'] = null;
+  let gateMeasure: GateMeasure | null = null;
+  let fallbackGateMeasure: GateMeasure | null = null;
+  let previousVersion: string | null = deps.previousVersion ?? runPrevious ?? null;
+  if (!previousVersion) { try { previousVersion = latestPublishedPreviousVersion(version, deps.releaseRunDeps?.ledgerRoot); } catch { previousVersion = null; } }
+  if (!schedule) {
+    findings.push({ level: 'warn', check: 'schedule', message: `판 일정 없음 — elanous release schedule set --version ${version} --cut-at <iso> --land-by <iso>` });
+  } else {
+    const cut = Date.parse(schedule.cutAt);
+    const publishAt = deps.publishAt ? new Date(deps.publishAt).toISOString() : cadencePublishAt(schedule.cutAt);
+    scheduleOut = { cutAt: schedule.cutAt, landBy: schedule.landBy, publishAt, publishAtSource: deps.publishAt ? 'option' : 'cadence' };
+    if (!schedule.landBy) findings.push({ level: 'warn', check: 'schedule', message: `착지 마감 없음 — 컷 ${formatKst(schedule.cutAt)} · 규칙은 컷 − 30분` });
+    else if (cut - Date.parse(schedule.landBy) < 30 * 60_000) findings.push({ level: 'warn', check: 'schedule', message: `착지 마감 ${formatKst(schedule.landBy)} 이 컷 − 30분보다 늦다(컷 ${formatKst(schedule.cutAt)})` });
+    else findings.push({ level: 'ok', check: 'schedule', message: `일정 — 착지 마감 ${formatKst(schedule.landBy)} · 컷 ${formatKst(schedule.cutAt)}` });
+    gateMeasure = previousVersion ? releaseGateMeasure({ version: previousVersion }, deps.graphRunsRoot) : null;
+    if (!gateMeasure) fallbackGateMeasure = releaseGateMeasure({ below: version }, deps.graphRunsRoot);
+    const windowSeconds = Math.round((Date.parse(publishAt) - cut) / 1000);
+    const publishLabel = `발행 ${formatKst(publishAt)}${deps.publishAt ? '' : '(기본: 판 주기 07·18시 · --publish-at 로 바꾼다)'}`;
+    if (!gateMeasure) {
+      const fallback = fallbackGateMeasure ? ` · 참고: 가장 최근 실측은 ${fallbackGateMeasure.version} 게이트 ${minutes(fallbackGateMeasure.gateSeconds)}(직전 판 아님)` : ' · 게이트 실측 없음';
+      findings.push({ level: 'warn', check: 'schedule', message: `직전 판${previousVersion ? `(${previousVersion})` : ''} 실측 없음 — 컷→${publishLabel} 창 ${minutes(windowSeconds)}${fallback}` });
+    }
+    else {
+      const measured = `직전 실측 ${gateMeasure.version} 게이트 ${minutes(gateMeasure.gateSeconds)}${gateMeasure.toPublishSeconds !== undefined ? ` · 런 시작→발행 노드 ${minutes(gateMeasure.toPublishSeconds)}` : ''}`;
+      const need = Math.max(gateMeasure.gateSeconds, gateMeasure.toPublishSeconds ?? 0);
+      findings.push(windowSeconds < need
+        ? { level: 'warn', check: 'schedule', message: `컷→${publishLabel} 창 ${minutes(windowSeconds)} < ${measured} — 발행이 늦어진다` }
+        : { level: 'ok', check: 'schedule', message: `컷→${publishLabel} 창 ${minutes(windowSeconds)} ≥ ${measured}` });
+    }
+  }
+
+  const blockers = findings.filter((f) => f.level === 'block').length;
+  const warnings = findings.filter((f) => f.level === 'warn').length;
+  debug.log('release.preflight', 'checked', { version, blockers, warnings });
+  return { version, next, verdict: blockers ? 'block' : warnings ? 'warn' : 'ok', blockers, warnings, findings, schedule: scheduleOut, previousVersion, gateMeasure, fallbackGateMeasure };
+}
+
+const ICON: Record<PreflightLevel, string> = { ok: '✅', warn: '⚠️', block: '⛔' };
+
+export function formatPreflight(result: PreflightResult): string[] {
+  const order: PreflightLevel[] = ['block', 'warn', 'ok'];
+  const lines = [...result.findings].sort((a, b) => order.indexOf(a.level) - order.indexOf(b.level))
+    .flatMap((f) => [`${ICON[f.level]} ${f.message}`, ...(f.suggestion ? [`    → ${f.suggestion}`] : [])]);
+  const verdict = result.verdict === 'block' ? `⛔ 판정: 막힘 — ⛔${result.blockers} ⚠️${result.warnings} · 컷 전에 고친다`
+    : result.verdict === 'warn' ? `⚠️ 판정: 통과(경고 ${result.warnings})` : '✅ 판정: 통과';
+  return [`release preflight ${result.version} (다음 판 ${result.next})`, ...lines, verdict];
+}

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

@@ -5,6 +5,7 @@ import { join } from 'node:path';
 import { WARNING_ONLY } from './auto-approve-node.js';
 import { beginLandingMerge, landingFreezeMessage } from '../../src/release-loop/landing-freeze.js';
 import { debug } from '../../src/debug/log.js';
+import { prereleaseKind } from './release-version.js';
 import { errorResult, finishNode, lastResult, nodeOutput, readGraphContext, runCommand, type CommandRunner } from './node-verdict.js';
 
 export function publicNotes(markdown: string, pages: { pages: Array<{ id: string; slug?: string; source?: string }> }): string {
@@ -20,6 +21,12 @@ export function publicNotes(markdown: string, pages: { pages: Array<{ id: string
   });
 }
 
+/** RELEASE-REHEARSAL-RC: prerelease notes open with a label, so nobody mistakes a rehearsal for the stable release. */
+export function labelPrerelease(version: string, body: string): string {
+  if (prereleaseKind(version) === null) return body;
+  return `> **Pre-release** — ${version} is a pre-release, not the latest version. Install it with \`npm i -g elanous@next\`; \`latest\` stays on the current stable release.\n\n${body}`;
+}
+
 /** Polls each release asset until it answers 200 (following redirects). Returns the names still missing. */
 export function waitForAssets(run: CommandRunner, repo: string, tag: string, names: readonly string[], waitSeconds: unknown = 600,
   sleep: (ms: number) => void = (ms) => Bun.sleepSync(ms)): string[] {
@@ -61,7 +68,7 @@ export function runPublish(run: CommandRunner = runCommand, prodFreezeRoot?: str
   const registry = run('git', ['show', `${branch}:website/pages.json`]);
   if (doc.status !== 0 || registry.status !== 0) throw new Error(`docs branch missing notes or pages: ${branch}`);
   if (!doc.stdout.startsWith(`# ${version}\n`)) throw new Error('release notes version mismatch');
-  const body = publicNotes(doc.stdout, JSON.parse(registry.stdout));
+  const body = labelPrerelease(version, publicNotes(doc.stdout, JSON.parse(registry.stdout)));
   const dir = mkdtempSync(join(tmpdir(), 'release-publish-notes-'));
   try {
     const file = join(dir, 'notes.md');

package/scripts/release-loop/release-readiness.ts

@@ -1,7 +1,10 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { releaseLedgerRoot } from '../../src/instance/resolve.js';
-import { checklistGate, type ChecklistGate } from '../../src/release-loop/checklist.js';
+import { cutChecklistGate, type ChecklistGate } from '../../src/release-loop/checklist.js';
+
+/** Only the verdict fields are read — so a `release run` deps checklist (`Pick<…>`) fits as well. */
+export type ReadinessChecklist = Pick<ChecklistGate, 'ok' | 'red' | 'undecided' | 'blocked'>;
 import { getSchedule, formatKst } from '../../src/release-loop/release-schedule.js';
 import { debug } from '../../src/debug/log.js';
 
@@ -9,12 +12,12 @@ export type ReleaseReadiness =
   | { ready: false; reason: 'already-published'; details: string }
   | { ready: false; reason: 'already-running'; details: string }
   | { ready: false; reason: 'before-cut'; details: string }
-  | { ready: false; reason: 'checklist-blocked'; details: ChecklistGate }
-  | { ready: true; reason: 'ready'; details: ChecklistGate };
+  | { ready: false; reason: 'checklist-blocked'; details: ReadinessChecklist }
+  | { ready: true; reason: 'ready'; details: ReadinessChecklist };
 
 export interface ReleaseReadinessDeps {
   ledgerRoot?: string;
-  checklist?: typeof checklistGate;
+  checklist?: (version: string) => ReadinessChecklist;
   isPidAlive?: (pid: number) => boolean;
   now?: () => Date;
 }
@@ -57,11 +60,13 @@ export function releaseReadiness(version: string, deps: ReleaseReadinessDeps = {
     }
   }
   const schedule = getSchedule(version, deps.ledgerRoot);
-  if (schedule && (deps.now ?? (() => new Date()))().getTime() < Date.parse(schedule.cutAt)) {
+  const now = (deps.now ?? (() => new Date()))();
+  if (schedule && now.getTime() < Date.parse(schedule.cutAt)) {
     debug.log('release.schedule', 'before-cut', { version, cutAt: schedule.cutAt, landBy: schedule.landBy });
     return { ready: false, reason: 'before-cut', details: `before-cut (${formatKst(schedule.cutAt)})` };
   }
-  const gate = (deps.checklist ?? checklistGate)(version);
+  // GATE-ENTRY-ALIGN: the same cut judgement as `release run`'s entry check and the checklist-gate node.
+  const gate = (deps.checklist ?? ((v: string) => cutChecklistGate(v, schedule?.landBy, now)))(version);
   if (!gate.ok) return { ready: false, reason: 'checklist-blocked', details: gate };
   return { ready: true, reason: 'ready', details: gate };
 }

package/scripts/release-loop/release-version.ts

@@ -0,0 +1,48 @@
+// Release version shapes for the release loop: a stable x.y.z or a prerelease x.y.z-(rc|alpha|beta).N.
+// RELEASE-BRANCH ⊕ RELEASE-REHEARSAL-RC (10-06): prerelease runs publish to npm `next` and skip the
+// post-publish nodes that touch main or the operating hosts.
+
+export const PRERELEASE_KINDS = ['rc', 'alpha', 'beta'] as const;
+export type PrereleaseKind = (typeof PRERELEASE_KINDS)[number];
+
+const RELEASE_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-(rc|alpha|beta)\.(0|[1-9]\d*))?$/;
+const STABLE_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+
+export function isStableVersion(version: string): boolean { return STABLE_VERSION.test(version); }
+
+export function isReleaseVersion(version: string): boolean { return RELEASE_VERSION.test(version); }
+
+/** `0.2.18-rc.0` → `0.2.18`; a stable version is returned as is. Throws on anything else. */
+export function baseVersion(version: string): string {
+  const match = RELEASE_VERSION.exec(version);
+  if (!match) throw new Error(`invalid release version: ${version}`);
+  return `${match[1]}.${match[2]}.${match[3]}`;
+}
+
+/** The prerelease kind of `0.2.18-rc.0` (`rc`), or null for a stable version. */
+export function prereleaseKind(version: string): PrereleaseKind | null {
+  const match = RELEASE_VERSION.exec(version);
+  if (!match) throw new Error(`invalid release version: ${version}`);
+  return (match[4] as PrereleaseKind | undefined) ?? null;
+}
+
+export function isPrereleaseKind(value: unknown): value is PrereleaseKind {
+  return typeof value === 'string' && (PRERELEASE_KINDS as readonly string[]).includes(value);
+}
+
+/**
+ * The next free prerelease number for `base` and `kind`, given the names already taken
+ * (release branches `release/<v>` and tags `v<v>`, with or without those prefixes).
+ */
+export function nextPrereleaseVersion(base: string, kind: PrereleaseKind, taken: readonly string[]): string {
+  if (!STABLE_VERSION.test(base)) throw new Error(`prerelease base must be x.y.z: ${base}`);
+  const prefix = `${base}-${kind}.`;
+  let next = 0;
+  for (const raw of taken) {
+    const name = raw.replace(/^refs\/heads\//, '').replace(/^refs\/tags\//, '').replace(/^release\//, '').replace(/^v(?=\d)/, '').replace(/\^\{\}$/, '');
+    if (!name.startsWith(prefix)) continue;
+    const n = name.slice(prefix.length);
+    if (/^(0|[1-9]\d*)$/.test(n)) next = Math.max(next, Number(n) + 1);
+  }
+  return `${prefix}${next}`;
+}