elanous 0.2.17 → 0.2.19

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

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

@@ -0,0 +1,174 @@
+// RELEASE-BRANCH (10-06): resume a failed release run after `release cut-branch --append --pick` moved release/<v>.
+// The saved version-release output is re-pointed at the new branch tip (fast-forward only, state backed up first), so
+// every later node reads the repaired commit without anyone hand-editing the run state.
+import { spawnSync } from 'node:child_process';
+import { constants, copyFileSync, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { debug } from '../../src/debug/log.js';
+import { effectiveInstanceRoot, releaseLedgerRoot } from '../../src/instance/resolve.js';
+import { lastJsonObject, runGraph, type GraphRunState } from '../../src/graph-runner/runner.js';
+import { isReleaseVersion } from './release-version.js';
+import { changedFilesBetween, clearPartialPlan, planPartialRegate, writePartialPlan } from './gate-partial.js';
+
+const GRAPH = join(import.meta.dir, '../../graphs/release/release-loop.yaml');
+
+export interface ResumeReleaseDeps {
+  root?: string;
+  repo?: string;
+  /** Runs git and returns stdout (throws on failure). */
+  git?: (args: string[]) => string;
+  /** `git merge-base --is-ancestor a b`. */
+  isAncestor?: (ancestor: string, descendant: string) => boolean;
+  graph?: typeof runGraph;
+  /** The release graph (tests point it at a probe graph with the same graph id). */
+  graphPath?: string;
+  /** Node command runner for the resumed graph (tests record each node's context instead of running it). */
+  runBash?: NonNullable<NonNullable<Parameters<typeof runGraph>[1]>['deps']>['runBash'];
+  now?: () => Date;
+  /** Machine release ledger (gate-failures.json of the prior gate) — default releaseLedgerRoot(). */
+  ledgerRoot?: string;
+}
+
+export interface TipRefresh { version: string; branch: string; from: string; to: string; changed: boolean; statePath: string; backup?: string }
+
+function gitRunner(repo: string) {
+  return (args: string[]): string => {
+    // git-spawn-allow: read-only fetch / ls-remote / rev-parse against release/<v>; nothing is pushed or checked out.
+    const result = spawnSync('git', args, { cwd: repo, encoding: 'utf8' });
+    if (result.status !== 0 || result.error) throw new Error(`git ${args[0]} failed: ${(result.stderr || result.error || 'no output').toString().trim()}`);
+    return result.stdout.trim();
+  };
+}
+
+function ancestorRunner(repo: string) {
+  return (ancestor: string, descendant: string): boolean => {
+    const result = spawnSync('git', ['merge-base', '--is-ancestor', ancestor, descendant], { cwd: repo });
+    if (result.status !== 0 && result.status !== 1) throw new Error(`git merge-base failed: ${result.error || result.stderr || 'unknown'}`);
+    return result.status === 0;
+  };
+}
+
+function safeRunId(runId: string): string {
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(runId) || runId === '.' || runId === '..') throw new Error(`invalid run id: ${runId}`);
+  return runId;
+}
+
+/** Point the saved version-release output at the current release/<v> tip (fast-forward of the recorded commit only). */
+export function refreshReleaseBranchTip(runId: string, deps: ResumeReleaseDeps = {}, from?: string): TipRefresh {
+  const root = deps.root ?? effectiveInstanceRoot();
+  const statePath = join(root, 'graph-runs', 'release-loop', `${safeRunId(runId)}.json`);
+  const state = JSON.parse(readFileSync(statePath, 'utf8')) as GraphRunState;
+  if (state.graphId !== 'release-loop' || state.runId !== runId) throw new Error(`run identity mismatch: ${statePath}`);
+  if (state.status !== 'failed') throw new Error(`release run ${runId} is ${state.status} — only a failed run is resumed`);
+  const restartAt = from === undefined ? -1 : state.path.indexOf(from);
+  if (from !== undefined && (restartAt < 0 || state.path.lastIndexOf(from) !== restartAt)) throw new Error(`--from ${from} is not a node on the saved path of ${runId}`);
+  const index = state.nodes.findIndex((node) => node.nodeId === 'version-release');
+  const record = index >= 0 ? state.nodes[index]! : undefined;
+  const output = record ? lastJsonObject(record.output) : undefined;
+  if (!record?.ok || !output) throw new Error(`release run ${runId} has no successful version-release record`);
+  const version = typeof output.version === 'string' ? output.version : '';
+  const recorded = typeof output.commit === 'string' ? output.commit : '';
+  if (!isReleaseVersion(version) || !/^[0-9a-f]{40}$/i.test(recorded)) throw new Error(`release run ${runId} version-release output is not a release commit`);
+  const branch = `release/${version}`;
+  // Only a run that cut release/<v> itself is re-pointed — a main-cut or --cut-commit run has no branch of its own.
+  const input = (state.input ?? {}) as { branchCut?: unknown; version?: unknown };
+  if (input.branchCut !== true || input.version !== version || output.branch !== branch) {
+    throw new Error(`release run ${runId} was not cut as ${branch} (input.branchCut/version or version-release branch differ) — refusing to resume`);
+  }
+  const git = deps.git ?? gitRunner(deps.repo ?? process.cwd());
+  const advertised = git(['ls-remote', '--heads', 'origin', `refs/heads/${branch}`]).split(/\s+/)[0] ?? '';
+  if (!/^[0-9a-f]{40}$/i.test(advertised)) throw new Error(`${branch} is not on origin — this run was not cut as a release branch`);
+  git(['fetch', 'origin', `+refs/heads/${branch}:refs/remotes/origin/${branch}`]);
+  const to = git(['rev-parse', '--verify', `refs/remotes/origin/${branch}^{commit}`]);
+  if (to !== advertised) throw new Error(`${branch} moved while it was read (${advertised} → ${to})`);
+  if (to === recorded) {
+    debug.log('release-loop.resume', 'tip-unchanged', { runId, version, commit: to });
+    return { version, branch, from: recorded, to, changed: false, statePath };
+  }
+  // A repair only appends (`cut-branch --append`): anything but a fast-forward is a different release.
+  if (!(deps.isAncestor ?? ancestorRunner(deps.repo ?? process.cwd()))(recorded, to)) {
+    throw new Error(`${branch} tip ${to} does not descend from the recorded release commit ${recorded} — refusing to resume`);
+  }
+  // A new tip invalidates everything built from the old one (gate verdict, prepared archive, …): restart no later
+  // than the first node that consumed the commit, so each of them runs again on the new tip.
+  const firstConsumer = state.path.indexOf('gate');
+  if (restartAt >= 0 && firstConsumer >= 0 && restartAt > firstConsumer) {
+    throw new Error(`${branch} moved (${recorded.slice(0, 12)} → ${to.slice(0, 12)}): resume at gate or earlier — later nodes were built from the old tip`);
+  }
+  const stamp = (deps.now?.() ?? new Date()).toISOString().replace(/[:.]/g, '-');
+  const backup = `${statePath}.before-tip-${stamp}-${process.pid}-${to.slice(0, 12)}.bak`;
+  // Exclusive: a retry never overwrites an earlier backup.
+  copyFileSync(statePath, backup, constants.COPYFILE_EXCL);
+  const refreshed = { ...output, commit: to, refreshedFrom: recorded };
+  const text = typeof record.output === 'string' ? record.output.replace(/\s*$/, '') : '';
+  state.nodes[index] = { ...record, output: `${text}\n${JSON.stringify(refreshed)}\n` };
+  const temporary = `${statePath}.${process.pid}.tip.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(state, null, 2)}\n`);
+  renameSync(temporary, statePath);
+  debug.log('release-loop.resume', 'tip-refreshed', { runId, version, branch, from: recorded, to, backup });
+  return { version, branch, from: recorded, to, changed: true, statePath, backup };
+}
+
+/** GATE-PARTIAL outcome of a resume — applied (plan written) or the reason it fell back to a full gate. */
+export type PartialOutcome = { requested: false } | { requested: true; applied: true; files: number; priorCommit: string } | { requested: true; applied: false; reason: string };
+
+/** Build (or clear) the partial re-gate plan for the new tip. Fail-closed: any doubt leaves a full gate. */
+function preparePartial(tip: TipRefresh, opts: { from: string; partial?: boolean }, deps: ResumeReleaseDeps): PartialOutcome {
+  const root = deps.root ?? effectiveInstanceRoot();
+  // Any resume starts from no plan: one without --partial (from whatever node) never inherits an older plan.
+  clearPartialPlan(root, tip.version);
+  if (!opts.partial) return { requested: false };
+  const fallback = (reason: string): PartialOutcome => {
+    debug.log('release-loop.resume', 'partial-fallback', { version: tip.version, reason });
+    return { requested: true, applied: false, reason };
+  };
+  if (opts.from !== 'gate') return fallback('--partial only applies to --from gate');
+  if (!tip.changed) return fallback('release branch tip unchanged — nothing new to re-check');
+  let prior: { commit?: unknown; failures?: unknown; errors?: unknown } | undefined;
+  for (const location of [...new Set([deps.ledgerRoot ?? releaseLedgerRoot(), root])]) {
+    const path = join(location, 'release', tip.version, 'gate-failures.json');
+    if (!existsSync(path)) continue;
+    let record: typeof prior;
+    try { record = JSON.parse(readFileSync(path, 'utf8')) as typeof prior; }
+    catch { return fallback(`unreadable gate record: ${path}`); }
+    if (record?.commit === tip.from) { prior = record; break; }
+  }
+  if (!prior || !Array.isArray(prior.failures) || !(prior.errors === undefined || Array.isArray(prior.errors))) {
+    return fallback(`no complete gate record for ${tip.from.slice(0, 12)} (a stalled or errored gate keeps none)`);
+  }
+  // Both sides of a rename count (`--no-renames`): a source moved to a test/Markdown name is still a source change.
+  let changed: string[];
+  try {
+    changed = deps.git
+      ? deps.git(['diff', '--name-only', '--no-renames', `${tip.from}..${tip.to}`]).split(/\r?\n/).filter(Boolean)
+      : changedFilesBetween(deps.repo ?? process.cwd(), tip.from, tip.to);
+  } catch (error) {
+    // The tip is already refreshed — a failed diff must not strand the resume: run the full gate and say why.
+    return fallback(`changed files unreadable: ${String(error instanceof Error ? error.message : error).slice(0, 200)}`);
+  }
+  const planned = planPartialRegate({ version: tip.version, priorCommit: tip.from, forCommit: tip.to, changedFiles: changed,
+    priorFailures: prior.failures as string[], priorErrors: (prior.errors ?? []) as string[] });
+  if (!planned.ok) return fallback(planned.reason);
+  const path = writePartialPlan(root, planned.plan);
+  debug.log('release-loop.resume', 'partial-planned', { version: tip.version, priorCommit: tip.from, commit: tip.to, files: planned.plan.files.length, path });
+  return { requested: true, applied: true, files: planned.plan.files.length, priorCommit: tip.from };
+}
+
+/** The graph file the run started from — a snapshot run refuses any other path (the installed CLI's own copy differs). */
+function savedGraphPath(statePath: string): string | undefined {
+  try {
+    const saved = JSON.parse(readFileSync(statePath, 'utf8')) as { graphPath?: unknown };
+    return typeof saved.graphPath === 'string' && saved.graphPath ? saved.graphPath : undefined;
+  } catch { return undefined; }
+}
+
+/** Refresh the branch tip, then restart the failed run at `from` with the saved graph snapshot. */
+export async function resumeReleaseRun(opts: { runId: string; from: string; partial?: boolean }, deps: ResumeReleaseDeps = {}): Promise<{ tip: TipRefresh; partial: PartialOutcome; state: GraphRunState }> {
+  if (opts.from === 'version-release') throw new Error('--from version-release would cut again — resume at a later node');
+  const tip = refreshReleaseBranchTip(opts.runId, deps, opts.from);
+  const partial = preparePartial(tip, opts, deps);
+  // Resume the graph at the path it was started from (its snapshot is used); only tests inject another path.
+  const graphPath = deps.graphPath ?? savedGraphPath(tip.statePath) ?? GRAPH;
+  const state = await (deps.graph ?? runGraph)(graphPath, { resumeRunId: opts.runId, fromNodeId: opts.from, ...(deps.root || deps.runBash ? { deps: { ...(deps.root ? { root: deps.root } : {}), ...(deps.runBash ? { runBash: deps.runBash } : {}) } } : {}) });
+  return { tip, partial, state };
+}

package/scripts/release-loop/shard-plan.ts

@@ -1,5 +1,21 @@
 import { readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { debug } from '../../src/debug/log.js';
+
+/** Plan weights for a Pod sweep: wall-scaled when the previous cut recorded shard wall times, junit seconds otherwise. */
+export function planDurations(durationSource: string | undefined): { durations: Map<string, number>; wall?: { shards: number; scaledFiles: number } } {
+  if (!durationSource) return { durations: new Map() };
+  const junit = readFileDurations(durationSource);
+  const wall = readFileWallWeights(durationSource, junit);
+  return wall ? { durations: wall.weights, wall: { shards: wall.shards, scaledFiles: wall.scaledFiles } } : { durations: junit };
+}
+
+/** Observation for GATE-PLAN-WALLTIME, emitted once the shards are planned so `maxPlannedMin` is the heaviest shard. */
+export function logPlanWalltime(wall: { shards: number; scaledFiles: number } | undefined, shards: ReadonlyArray<{ plannedSeconds: number }>): void {
+  if (!wall) return;
+  const maxPlannedSeconds = Math.max(0, ...shards.map((shard) => shard.plannedSeconds));
+  debug.log('release-loop.gate', 'plan-walltime', { shards: wall.shards, scaledFiles: wall.scaledFiles, maxPlannedMin: Math.round(maxPlannedSeconds / 6) / 10 });
+}
 
 /** Read per-file seconds from previous cut Pod reports; missing or damaged reports are not estimates. */
 export function readFileDurations(dir: string): Map<string, number> {
@@ -62,3 +78,52 @@ export function planShards(files: string[], durations: Map<string, number>, coun
   }
   return shards.filter((shard) => shard.files.length > 0);
 }
+
+/**
+ * GATE-PLAN-WALLTIME: junit testsuite times run far below a shard's real wall time (0.2.18 pod-23: planned 2.7 min,
+ * measured 33.3 min), so LPT balanced the wrong quantity. When the previous cut left `pod-*.json` records
+ * (`durationMs` ⊕ `files`), each file's junit seconds are scaled so its shard's planned total equals the measured wall
+ * time; files without junit take that shard's average per-file wall time. A file measured in several records takes
+ * its first-pass shard (`pod-<n>.json` — the shape the next cut plans) over descent/retry children, whose per-Pod
+ * install overhead lands on one or two files; among equals, the record with the fewest files.
+ * Returns undefined when no usable record exists, so callers keep the junit-only behaviour.
+ */
+export function readFileWallWeights(dir: string, junit: Map<string, number>): { weights: Map<string, number>; shards: number; scaledFiles: number } | undefined {
+  let names: string[];
+  try { names = readdirSync(dir).filter((name) => /^pod-.*\.json$/.test(name)).sort(); }
+  catch { return undefined; }
+  const records: Array<{ wallSeconds: number; files: string[]; firstPass: boolean }> = [];
+  for (const name of names) {
+    try {
+      const meta = JSON.parse(readFileSync(join(dir, name), 'utf8')) as { durationMs?: unknown; files?: unknown };
+      if (typeof meta.durationMs !== 'number' || !Number.isFinite(meta.durationMs) || meta.durationMs <= 0) continue;
+      if (!Array.isArray(meta.files) || !meta.files.length || !meta.files.every((file) => typeof file === 'string')) continue;
+      records.push({ wallSeconds: meta.durationMs / 1000, files: [...new Set(meta.files as string[])], firstPass: /^pod-\d+\.json$/.test(name) });
+    } catch { /* One damaged record must not discard the others. */ }
+  }
+  if (!records.length) return undefined;
+  const valid = (value: number | undefined): value is number => value !== undefined && Number.isFinite(value) && value >= 0;
+  const best = new Map<string, { rank: number; seconds: number }>();
+  for (const record of records) {
+    const unknownCount = record.files.filter((file) => !valid(junit.get(file))).length;
+    const junitSum = record.files.reduce((sum, file) => { const value = junit.get(file); return sum + (valid(value) ? value : 0); }, 0);
+    const average = record.wallSeconds / record.files.length;
+    const remaining = record.wallSeconds - unknownCount * average;
+    for (const file of record.files) {
+      const seconds = junit.get(file);
+      const weight = valid(seconds) && junitSum > 0 && remaining > 0 ? seconds * (remaining / junitSum) : average;
+      const prior = best.get(file);
+      const rank = (record.firstPass ? 0 : 1_000_000) + record.files.length;
+      if (!prior || rank < prior.rank) best.set(file, { rank, seconds: weight });
+    }
+  }
+  // Files timed by junit but absent from every record (new or renamed since the cut) take the overall scale, so the
+  // plan never mixes wall seconds with raw junit seconds.
+  let scaledSum = 0;
+  let junitSum = 0;
+  for (const [file, { seconds }] of best) { const value = junit.get(file); if (valid(value) && value > 0) { scaledSum += seconds; junitSum += value; } }
+  const overall = junitSum > 0 ? scaledSum / junitSum : 1;
+  const weights = new Map([...junit].map(([file, seconds]) => [file, seconds * overall] as [string, number]));
+  for (const [file, { seconds }] of best) weights.set(file, seconds);
+  return { weights, shards: records.length, scaledFiles: best.size };
+}

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

@@ -1,12 +1,15 @@
+import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { getElanousConfigDirOverride } from '../../src/elanous-config-dir.js';
 import { effectiveInstanceRoot, releaseLedgerRoot } from '../../src/instance/resolve.js';
 import { userConfigPath } from '../../src/user-config.js';
-import { checklistGate } from '../../src/release-loop/checklist.js';
+import { cutChecklistGate } from '../../src/release-loop/checklist.js';
+import { getSchedule } from '../../src/release-loop/release-schedule.js';
 import { isLandingFreezeRefusal, readLandingFreeze, LandingFrozenError } from '../../src/release-loop/landing-freeze.js';
 import { debug } from '../../src/debug/log.js';
 import { runGraph, type GraphRunState } from '../../src/graph-runner/runner.js';
+import { baseVersion, isStableVersion, nextPrereleaseVersion, type PrereleaseKind } from './release-version.js';
 
 const VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
 const GRAPH = join(import.meta.dir, '../../graphs/release/release-loop.yaml');
@@ -16,6 +19,8 @@ export interface ReleaseLoopConfig {
   gatePodBunCache?: string;
   gatePodShards?: number;
   gatePodShardTimeoutSeconds?: number;
+  /** GATE-SPEED A3①: gate shard Pod CPU — `2` (request = limit) or `{ request, limit }`. Omitted = request 1 / limit 4. */
+  gatePodCpu?: number | string | { request?: number | string; limit?: number | string };
   gateRemote?: string;
   gateRemoteMirror?: string;
   opsHosts?: string[];
@@ -29,6 +34,8 @@ export interface ReleaseRunInput extends ReleaseLoopConfig {
   cutCommit?: string;
   gatePodPool: string;
   forceFreeze?: boolean;
+  /** RELEASE-BRANCH: version-release cuts release/<v> from main HEAD and bumps only the branch. */
+  branchCut?: boolean;
 }
 
 export interface UnattendedReleaseDeps {
@@ -36,8 +43,25 @@ export interface UnattendedReleaseDeps {
   config?: ReleaseLoopConfig;
   configPath?: string;
   graph?: (path: string, options: { input: ReleaseRunInput }) => Promise<GraphRunState>;
-  checklist?: typeof checklistGate;
+  checklist?: (version: string) => Pick<ReturnType<typeof cutChecklistGate>, 'ok' | 'red' | 'undecided' | 'blocked'>;
   freezeRoot?: string;
+  /** Names already taken for prerelease numbering (remote release branches and tags). */
+  releaseRefs?: (base: string, kind: PrereleaseKind) => string[];
+}
+
+/** Remote `release/<base>-<kind>.*` branches and `v<base>-<kind>.*` tags — read-only. */
+export function remoteReleaseRefs(base: string, kind: PrereleaseKind, repo = process.cwd()): string[] {
+  // git-spawn-allow: read-only ls-remote to number a prerelease.
+  const result = spawnSync('git', ['ls-remote', 'origin', `refs/heads/release/${base}-${kind}.*`, `refs/tags/v${base}-${kind}.*`], { cwd: repo, encoding: 'utf8' });
+  if (result.status !== 0 || result.error) throw new Error(`git ls-remote failed: ${(result.stderr || result.error || 'no output').toString().trim()}`);
+  return result.stdout.split('\n').map((line) => line.split(/\s+/)[1] ?? '').filter(Boolean);
+}
+
+/** `0.2.18` + `rc` → the next free `0.2.18-rc.<n>`; a stable run keeps its version. */
+export function resolveRunVersion(version: string, prerelease: PrereleaseKind | undefined, deps: UnattendedReleaseDeps = {}): string {
+  if (!prerelease) return version;
+  if (!isStableVersion(version)) throw new Error(`--prerelease takes the base version x.y.z: ${version}`);
+  return nextPrereleaseVersion(version, prerelease, (deps.releaseRefs ?? remoteReleaseRefs)(version, prerelease));
 }
 
 function compareVersions(a: string, b: string): number {
@@ -76,7 +100,7 @@ export function buildReleaseRunInput(version: string, deps: UnattendedReleaseDep
   const config = deps.config ?? releaseLoopConfig(deps.configPath);
   const pool = config.gatePodPool;
   if (typeof pool !== 'string' || !pool.trim()) throw new Error('release.loop.gatePodPool is required before graph execution');
-  const previousVersion = latestPublishedPreviousVersion(version, deps.ledgerRoot);
+  const previousVersion = latestPublishedPreviousVersion(baseVersion(version), deps.ledgerRoot);
   return {
     ...config,
     version, previousVersion,
@@ -87,9 +111,14 @@ export function buildReleaseRunInput(version: string, deps: UnattendedReleaseDep
 
 /** Fail closed at the entry boundary, before any graph node can change a release. */
 export async function runUnattendedRelease(
-  opts: { version: string; dryRun?: boolean; cutCommit?: string; forceFreeze?: boolean },
+  opts: { version: string; dryRun?: boolean; cutCommit?: string; forceFreeze?: boolean; mainCut?: boolean; prerelease?: PrereleaseKind },
   deps: UnattendedReleaseDeps = {},
 ): Promise<{ input: ReleaseRunInput; dryRun: boolean; state?: GraphRunState }> {
+  // RELEASE-BRANCH (10-06): the default cut is a release branch, so main keeps landing and the run no longer needs a
+  // landing freeze. A freeze stays the emergency switch: when one is on, it still stops the run (`--force-freeze` overrides).
+  // `--cut-commit` (an already-cut branch) and `--main-cut` keep the old main-bump path.
+  const branchCut = opts.cutCommit === undefined && !opts.mainCut;
+  if (opts.prerelease && !branchCut) throw new Error('--prerelease needs the release-branch cut (no --cut-commit / --main-cut): a rehearsal must never bump main');
   if (!opts.dryRun) {
     const frozen = readLandingFreeze(deps.freezeRoot);
     if (frozen) {
@@ -97,11 +126,20 @@ export async function runUnattendedRelease(
       if (!opts.forceFreeze) throw new LandingFrozenError(frozen);
     }
   }
-  const input = buildReleaseRunInput(opts.version, deps, opts.cutCommit);
+  const version = resolveRunVersion(opts.version, opts.prerelease, deps);
+  const input = buildReleaseRunInput(version, deps, opts.cutCommit);
   if (opts.forceFreeze) input.forceFreeze = true;
+  if (branchCut) input.branchCut = true;
+  debug.log('release.run', 'input', { version, requested: opts.version, branchCut, prerelease: opts.prerelease ?? null, dryRun: opts.dryRun === true });
   if (opts.dryRun) return { input, dryRun: true };
-  const gate = (deps.checklist ?? checklistGate)(opts.version);
-  if (!gate.ok) throw new Error(`release checklist blocked: ${[...gate.red, ...gate.undecided, ...gate.blocked].join(', ')}`);
+  if (opts.prerelease) {
+    // A rehearsal neither judges nor carries the stable version's checklist cells.
+    debug.log('release.run', 'checklist-skipped', { version, reason: 'prerelease' });
+  } else {
+    // Same judgement as the checklist-gate node: past the landing deadline non-P0 yellows carry; P0 yellows block.
+    const gate = (deps.checklist ?? ((v: string) => cutChecklistGate(v, getSchedule(v)?.landBy)))(version);
+    if (!gate.ok) throw new Error(`release checklist blocked: ${[...gate.red, ...gate.undecided, ...gate.blocked].join(', ')}`);
+  }
   const beforeGraph = readLandingFreeze(deps.freezeRoot);
   if (beforeGraph && !opts.forceFreeze) throw new LandingFrozenError(beforeGraph);
   const state = await (deps.graph ?? runGraph)(GRAPH, { input });