elanous 0.2.37 → 0.2.38

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

@@ -3,23 +3,32 @@
 // every later node reads the repaired commit without anyone hand-editing the run state.
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { accessSync, closeSync, constants, copyFileSync, existsSync, fstatSync, openSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { accessSync, closeSync, constants, copyFileSync, existsSync, fstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, realpathSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
 import { debug } from '../../src/debug/log.js';
 import { effectiveInstanceRoot, releaseLedgerRoot } from '../../src/instance/resolve.js';
 import { lastJsonObject, runGraph, verifyReleaseCommandRoot, verifyReleaseRecipeSnapshot, type GraphRunState } from '../../src/graph-runner/runner.js';
 import { withOpSeatFlock } from '../../src/steward/resync-tick.js';
 import { releaseRunUniverse } from './release-universe.js';
 import { isReleaseVersion } from './release-version.js';
-import { changedFilesBetween, clearPartialPlan, planPartialRegate, planStalledShardRecheck, writePartialPlan, writeRecheckPlan } from './gate-partial.js';
+import { changedFilesBetween, clearPartialPlan, collectExecutedPodShardImages, planPartialRegate, planStalledShardRecheck, writePartialPlan, writeRecheckPlan } from './gate-partial.js';
 import { gitClosureTree, testsReachingChanged, TRACEABLE_RELEASE_JSON, type ClosureTree } from './gate-closure.js';
 import { releaseResumeAcceptedRegressions, releaseResumeGateExecutor, releaseResumeGatePodPool, releaseResumeWaiver, type AcceptedRegression } from './resume.js';
 import { reserveReleaseResumeAttempt } from './resume-cap.js';
+import { cutReleaseBranch } from './cut-branch.js';
 import { releaseLoopConfig } from './unattended-release.js';
 import { trafficOptionsFromConfig } from './traffic-transition.js';
 
 const GRAPH = join(import.meta.dir, '../../graphs/release/release-loop.yaml');
 
+/** Compare existing artifact paths by filesystem identity so macOS /var and /private/var aliases agree. */
+function sameRealPath(left: unknown, right: unknown): boolean {
+  if (typeof left !== 'string' || typeof right !== 'string') return false;
+  try { return realpathSync(left) === realpathSync(right); }
+  catch { return false; }
+}
+
 export interface ResumeReleaseDeps {
   root?: string;
   repo?: string;
@@ -227,7 +236,8 @@ function verifyResumePreflight(run: GraphRunState, opts: ResumeReleaseOptions, d
       let owner: { runId?: unknown; commit?: unknown } | undefined;
       let ownerReadable = !existsSync(ownerPath);
       try { owner = JSON.parse(readFileSync(ownerPath, 'utf8')) as typeof owner; ownerReadable = true; } catch { /* old artifacts can be owned by the run ledger */ }
-      const ledgerOwns = output?.out === prepared && output.commit === currentTip && output.outcome === 'ok';
+      const ledgerOwns = output !== undefined && sameRealPath(output.out, prepared)
+        && output.commit === currentTip && output.outcome === 'ok';
       const receiptOwns = owner ? owner.runId === opts.runId && owner.commit === currentTip : ownerReadable && ledgerOwns;
       if (!ledgerOwns || manifest?.version !== version || manifest.sourceCommit !== currentTip || !receiptOwns) {
         throw new Error(`prepared artifact is outside the current release run ledger: ${prepared} — remedy: preserve it, compare release.json and .release-node-owner.json with run ${opts.runId}, then resolve ownership before resume`);
@@ -265,8 +275,8 @@ function verifyResumePreflight(run: GraphRunState, opts: ResumeReleaseOptions, d
     const outputOwner = docsRecord?.artifactOwner as { runId?: unknown; attempt?: unknown } | undefined;
     const receiptMatches = receipt?.branch === docsBranch && receipt.owner?.runId === opts.runId
       && receipt.owner.attempt === outputOwner?.attempt && outputOwner?.runId === opts.runId
-      && typeof receipt.worktree === 'string' && worktree === receipt.worktree && docsWorktrees.includes(receipt.worktree)
-      && existsSync(receipt.worktree);
+      && typeof receipt.worktree === 'string' && sameRealPath(worktree, receipt.worktree)
+      && docsWorktrees.some((listedWorktree) => sameRealPath(listedWorktree, receipt.worktree));
     if (hasDocsArtifact && !receiptMatches) {
       throw new Error(`docs branch/worktree is outside the current release run ledger: ${docsBranch} — remedy: compare ${receiptPath} with the saved docs node output and resolve ownership before resume`);
     }
@@ -290,7 +300,7 @@ export type PartialOutcome = { requested: false }
 
 /** Build (or clear) the partial re-gate plan for the new tip. Fail-closed: any doubt leaves a full gate.
  *  GATE-REUSE-BY-DIFF: `--from gate` on a moved tip plans by default (`partial: undefined`); `partial: false` opts out. */
-function preparePartial(tip: TipRefresh, opts: { from: string; partial?: boolean }, deps: ResumeReleaseDeps, dryRun = false): PartialOutcome {
+function preparePartial(tip: TipRefresh, opts: { from: string; partial?: boolean; gateExecutor?: string }, deps: ResumeReleaseDeps, dryRun = false): PartialOutcome {
   const root = deps.root ?? effectiveInstanceRoot();
   // Any resume starts from no plan: one without a partial plan (from whatever node) never inherits an older plan.
   if (!dryRun) clearPartialPlan(root, tip.version);
@@ -328,7 +338,7 @@ function preparePartial(tip: TipRefresh, opts: { from: string; partial?: boolean
     for (const item of stalled) {
       if (!item || typeof item !== 'object' || !Array.isArray((item as { files?: unknown }).files)
         || !(item as { files: unknown[] }).files.every((file) => typeof file === 'string')
-        || !['incomplete', 'no-output', 'job-failed', 'exit-code', 'unattributed', 'timeout'].includes(String((item as { reason?: unknown }).reason)))
+        || !['incomplete', 'no-output', 'job-failed', 'exit-code', 'unattributed', 'timeout', 'admission-timeout', 'admission-error'].includes(String((item as { reason?: unknown }).reason)))
         return fallback('stalled-shard record is malformed');
       stalledFiles.push(...(item as { files: string[] }).files);
     }
@@ -387,9 +397,16 @@ function preparePartial(tip: TipRefresh, opts: { from: string; partial?: boolean
     const jsonClosure = testsReachingChanged(tree, [TRACEABLE_RELEASE_JSON], tests, { cliEntries: CLI_ENTRIES });
     if (!jsonClosure.ok || jsonClosure.reached === 0) return fallback('known-issues JSON reaches no verified test — full gate');
   }
+  const priorCutLogs = [...new Set([deps.ledgerRoot ?? releaseLedgerRoot(), root])]
+    .map((location) => join(location, 'release', tip.version, 'gate-logs', 'cut'))
+    .find((dir) => existsSync(dir));
+  const savedInput = saved.input as { gateExecutor?: unknown; gatePodPool?: unknown };
+  const podGate = (opts.gateExecutor ?? savedInput.gateExecutor ?? (savedInput.gatePodPool ? 'pod' : undefined)) === 'pod';
+  const priorShards = priorCutLogs ? collectExecutedPodShardImages(priorCutLogs, tip.from) : undefined;
   const planned = planPartialRegate({ version: tip.version, priorCommit: tip.from, forCommit: tip.to, changedFiles: changed,
     priorFailures: prior.failures as string[], priorErrors: (prior.errors ?? []) as string[],
     existsAtTip: (file) => tracked.has(file),
+    ...(podGate ? { priorShards: priorShards ?? [] } : {}),
     closure: (changedCode) => testsReachingChanged(tree, changedCode, tests, { cliEntries: CLI_ENTRIES }) });
   if (!planned.ok) return fallback(planned.reason);
   if (planned.plan.files.length >= tests.length) return fallback(`every test is re-run (${tests.length}) — full gate`);
@@ -539,3 +556,275 @@ async function resumeReleaseRunLocked(opts: ResumeReleaseOptions, deps: ResumeRe
     deps: { root: deps.root, ...(deps.runBash ? { runBash: deps.runBash } : {}) } });
   return { tip, partial, state };
 }
+
+// RELEASE-RECOVER-ONE-CMD (0.2.36): a failed release run is repaired by three commands that used to be chained by
+// hand (append dry-run → append → resume --from export-check). `release recover` runs them in that order, stops the
+// moment one fails, and leaves every stage's result in the resume-attempts ledger.
+export type RecoverStageName = 'append-dry-run' | 'append' | 'resume';
+const RECOVER_STAGES: readonly RecoverStageName[] = ['append-dry-run', 'append', 'resume'];
+/** The first node that consumes the cut — a moved tip must restart no later than here, so it is the default. */
+const RECOVER_FIRST_NODE = 'export-check';
+
+export interface RecoverReleaseOptions {
+  runId: string;
+  /** main commits that repair the cut — appended to release/<v> as a fast-forward only. */
+  pick: string[];
+  /** Node the resume restarts at — default `export-check`. */
+  from?: string;
+  commandRoot?: string;
+  partial?: boolean;
+  /** The checkout the append runs in (its `origin` remote); default the process cwd. */
+  repoRoot?: string;
+}
+
+export interface RecoverStageRecord {
+  stage: RecoverStageName; outcome: 'ok' | 'failed'; at: string; branch?: string; commit?: string | null;
+  from?: string; gatePlan?: 'not-run' | 'partial' | 'full'; status?: string; reason?: string;
+  /** The `--pick` list this recovery appended — a re-entry skips the append only for the same list. */
+  pick?: string[];
+}
+
+export interface RecoverReleaseResult {
+  runId: string; version: string; branch: string; fromNode: string; stages: RecoverStageRecord[];
+  resume?: { status: string; tip: TipRefresh; partial: PartialOutcome };
+}
+
+export interface RecoverReleaseDeps extends ResumeReleaseDeps {
+  /** `release cut-branch --append` — tests record the plan instead of pushing the branch. */
+  cutBranch?: typeof cutReleaseBranch;
+}
+
+/** A recovery that stopped at a stage: the stages after it never ran, and a human decides the next move. */
+export class ReleaseRecoverStopped extends Error {
+  constructor(readonly stage: RecoverStageName, readonly stages: readonly RecoverStageRecord[],
+    readonly notRun: readonly RecoverStageName[], reason: string) {
+    super(`release recover ${stage} 단계에서 멈췄다: ${reason} — ${notRun.length
+      ? `${notRun.join(' · ')} 단계는 실행하지 않았다` : '뒤에 실행할 단계가 없다'} · 사람이 판단한다(단계 원장: release/<v>/resume-attempts/<runId>.json)`);
+    this.name = 'ReleaseRecoverStopped';
+  }
+}
+
+/** Append one stage result to the resume-attempts ledger. `attempts[]` keeps its shape — the stage results are added. */
+function recordRecoverStage(entry: { root: string; runId: string; version: string; priorCountKnown: boolean; stage: RecoverStageRecord }): void {
+  const path = join(entry.root, 'release', entry.version, 'resume-attempts', `${entry.runId}.json`);
+  const saved = existsSync(path)
+    ? JSON.parse(readFileSync(path, 'utf8')) as { attempts?: unknown; recoveries?: unknown; priorCountKnown?: unknown }
+    : undefined;
+  if (saved !== undefined && (!saved || typeof saved !== 'object' || Array.isArray(saved) || !Array.isArray(saved.attempts)
+    || (saved.recoveries !== undefined && !Array.isArray(saved.recoveries)))) throw new Error('release resume attempts ledger invalid');
+  const next = { ...(saved ?? {}), version: entry.version, runId: entry.runId,
+    priorCountKnown: saved?.priorCountKnown ?? entry.priorCountKnown,
+    attempts: (saved?.attempts ?? []) as string[],
+    recoveries: [...((saved?.recoveries ?? []) as RecoverStageRecord[]), entry.stage] };
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = `${path}.${process.pid}.recover.tmp`;
+  writeFileSync(temporary, `${JSON.stringify(next)}\n`, { mode: 0o600 });
+  renameSync(temporary, path);
+}
+
+/**
+ * Repair a failed release run in one command: append dry-run (plan only) → append (fast-forward release/<v> onto the
+ * picked repairs) → resume --from export-check (preflight plan, then the graph). A failing stage stops the command:
+ * the later stages never run, and the stage results are already in the ledger for the human to read.
+ */
+export async function recoverReleaseRun(opts: RecoverReleaseOptions, deps: RecoverReleaseDeps = {}): Promise<RecoverReleaseResult> {
+  if (!Array.isArray(opts.pick) || !opts.pick.length) throw new Error('release recover requires at least one --pick commit');
+  const root = releaseRunUniverse({ root: deps.root });
+  const statePath = join(root, 'graph-runs', 'release-loop', `${safeRunId(opts.runId)}.json`);
+  const savedRun = JSON.parse(readFileSync(statePath, 'utf8')) as GraphRunState;
+  if (savedRun.graphId !== 'release-loop' || savedRun.runId !== opts.runId) throw new Error(`run identity mismatch: ${statePath}`);
+  // The saved version-release record names what to repair: the release branch and the commit the run cut.
+  const versionRecord = savedRun.nodes.find((node) => node.nodeId === 'version-release');
+  const recorded = lastJsonObject(versionRecord?.output);
+  const version = typeof recorded?.version === 'string' ? recorded.version : '';
+  // RELEASE-RECOVER-BASE: a first recover that reached the resume left refreshed-tip lines in the
+  // version-release output, and `lastJsonObject` names the CURRENT branch tip. The append builds on the
+  // commit the run CUT — an ancestor of the picked repairs on origin/main — so walk to the FIRST JSON
+  // object of the output for that original cut. Without this, a second recover with a different --pick
+  // fails append-dry-run with «base … is not an ancestor of origin/main» and strands the new repair
+  // unpushed while the run looks recovered.
+  const firstCutObject = (text: unknown): { version?: unknown; commit?: unknown } | undefined => {
+    if (typeof text !== 'string') return undefined;
+    for (const line of text.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith('{')) continue;
+      try {
+        const parsed: unknown = JSON.parse(trimmed);
+        if (parsed && typeof parsed === 'object' && typeof (parsed as { version?: unknown }).version === 'string') {
+          return parsed as { version?: unknown; commit?: unknown };
+        }
+      } catch { /* not a JSON line — keep walking */ }
+    }
+    return undefined;
+  };
+  const originalCut = firstCutObject(versionRecord?.output) ?? recorded;
+  const base = typeof originalCut?.commit === 'string' ? originalCut.commit : '';
+  if (!versionRecord?.ok || !isReleaseVersion(version) || !/^[0-9a-f]{40}$/i.test(base)) {
+    throw new Error(`release run ${opts.runId} has no successful version-release record — nothing to repair`);
+  }
+  const branch = `release/${version}`;
+  const fromNode = opts.from ?? RECOVER_FIRST_NODE;
+  // RELEASE-RECOVER-PREFLIGHT (MS-02 review): the append pushes release/<v> on origin, and the resume refuses a
+  // bad run only after that push. Every read-only resume rejection is checked here FIRST — a run the resume
+  // would refuse never moves the branch. command-root mismatch is gone by construction: recover prepares the
+  // tip checkout itself below, and a human-provided --command-root is verified by the plan before the graph.
+  if (savedRun.status !== 'failed') {
+    throw new Error(`release run ${opts.runId} is ${savedRun.status} — only a failed run is recovered; ${branch} was not moved`);
+  }
+  if (fromNode === 'version-release') {
+    throw new Error(`--from version-release would cut again — recover at a later node; ${branch} was not moved`);
+  }
+  const restartAt = savedRun.path.indexOf(fromNode);
+  if (restartAt < 0 || savedRun.path.lastIndexOf(fromNode) !== restartAt) {
+    throw new Error(`--from ${fromNode} is not a node on the saved path of ${opts.runId}; ${branch} was not moved`);
+  }
+  const consumers = ['export-check', 'gate'].map((node) => savedRun.path.indexOf(node)).filter((index) => index >= 0);
+  const firstConsumer = consumers.length ? Math.min(...consumers) : -1;
+  if (firstConsumer >= 0 && restartAt > firstConsumer) {
+    throw new Error(`--from ${fromNode} is later than ${savedRun.path[firstConsumer]!} — later nodes were built from the old tip; ${branch} was not moved`);
+  }
+  const savedInput = (savedRun.input ?? {}) as { branchCut?: unknown; version?: unknown };
+  if (savedInput.branchCut !== true || savedInput.version !== version || recorded?.branch !== branch) {
+    throw new Error(`release run ${opts.runId} was not cut as ${branch} (input.branchCut/version or version-release branch differ); ${branch} was not moved`);
+  }
+  // The attempt ledger is the resume's own read-only gate — a refused recover consumes no attempt.
+  reserveReleaseResumeAttempt(savedRun, root, { now: deps.now, checkOnly: true });
+  const now = (): string => (deps.now?.() ?? new Date()).toISOString();
+  const stages: RecoverStageRecord[] = [];
+  const record = (stage: RecoverStageRecord): void => {
+    stages.push(stage);
+    recordRecoverStage({ root, runId: opts.runId, version, priorCountKnown: !savedRun.resume, stage });
+  };
+  const stop = (stage: RecoverStageName, error: unknown): never => {
+    throw new ReleaseRecoverStopped(stage, stages, RECOVER_STAGES.slice(RECOVER_STAGES.indexOf(stage) + 1),
+      error instanceof Error ? error.message : String(error));
+  };
+  const reason = (error: unknown): string => error instanceof Error ? error.message : String(error);
+  const cutBranch = deps.cutBranch ?? cutReleaseBranch;
+  const cut = { version, base, pick: opts.pick, append: true, repoRoot: opts.repoRoot, log: deps.onSource };
+  const repoRoot = resolve(opts.repoRoot ?? deps.repo ?? process.cwd());
+  // RELEASE-RECOVER-REENTRY (MS-02 review): once the append pushed and the resume did not finish, re-running
+  // recover with the same --pick is refused by cut-branch with «pick … is already in release/<v>» and dies at
+  // stage 1 with no guidance. The ledger recoveries decide: when their append-ok commit is still inside the
+  // advertised branch tip AND its recorded pick list is this --pick (an entry with no pick record is «기록 없음»,
+  // not an empty list — it falls back to the safe side and appends again), the repair already landed and this
+  // recover continues from the resume — the append stages never re-run.
+  /** Same pick list, order-insensitive, full 40-hex object ids only — anything else is «no record». */
+  const samePickList = (recorded: unknown): boolean => {
+    if (!Array.isArray(recorded) || recorded.length !== opts.pick.length) return false;
+    const left = recorded.map((sha) => (typeof sha === 'string' ? sha.toLowerCase() : '')).sort();
+    const right = [...opts.pick].map((sha) => sha.toLowerCase()).sort();
+    return left.every((sha, index) => /^[0-9a-f]{40}$/.test(sha) && sha === right[index]);
+  };
+  const ledgerPath = join(root, 'release', version, 'resume-attempts', `${opts.runId}.json`);
+  const recoveries: RecoverStageRecord[] = existsSync(ledgerPath)
+    ? ((JSON.parse(readFileSync(ledgerPath, 'utf8')) as { recoveries?: unknown[] }).recoveries ?? []) as RecoverStageRecord[]
+    : [];
+  let appendedCommit: string | undefined;
+  for (let index = recoveries.length - 1; index >= 0; index -= 1) {
+    const entry = recoveries[index]!;
+    if (entry.stage === 'append' && entry.outcome === 'ok' && typeof entry.commit === 'string' && samePickList(entry.pick)) {
+      appendedCommit = entry.commit;
+      break;
+    }
+  }
+  let advertised = '';
+  try {
+    advertised = (deps.git ?? gitRunner(repoRoot))(['ls-remote', '--heads', 'origin', `refs/heads/${branch}`]).split(/\s+/)[0] ?? '';
+  } catch {
+    advertised = '';
+  }
+  const isAncestor = deps.isAncestor ?? ancestorRunner(repoRoot);
+  const humanResume = `release resume --run ${opts.runId} --from ${fromNode}`;
+  const alreadyInGuidance = (cause: string): string =>
+    `${cause} — ${branch}가 이미 고른 수선을 담고 있다: 이 recover는 append하지 않았다. 사람이 직접 이어 간다: ${humanResume}`;
+  let tip = '';
+  if (appendedCommit !== undefined && /^[0-9a-f]{40}$/i.test(advertised) && isAncestor(appendedCommit, advertised)) {
+    tip = advertised;
+    deps.onSource?.(`· recover 재진입 · 원장의 append-ok(${appendedCommit.slice(0, 12)})이 가지 끝에 그대로 있다 — append를 다시 하지 않고 ${fromNode} resume부터 이어 간다`);
+  } else {
+    if (/^[0-9a-f]{40}$/i.test(advertised) && opts.pick.every((sha) => isAncestor(sha, advertised))) {
+      // The repair is on the branch already (a hand-run append) and the ledger has no append-ok for it: there is
+      // nothing to append — the stop error and the ledger record both name the human's next step.
+      const guidance = alreadyInGuidance(`pick ${opts.pick.join(' + ')} is already in ${branch}`);
+      record({ stage: 'append-dry-run', outcome: 'failed', at: now(), branch, reason: guidance });
+      return stop('append-dry-run', new Error(guidance));
+    }
+    // 1/3 append dry-run — the fast-forward plan only: no worktree, no push, no run-state write.
+    try {
+      const planned = cutBranch({ ...cut, dryRun: true });
+      record({ stage: 'append-dry-run', outcome: 'ok', at: now(), branch: planned.branch, commit: planned.commit });
+      deps.onSource?.(`· recover 1/3 append dry-run · ${planned.branch} ← ${opts.pick.join(' + ')} · 가지·push·런 상태 변경 없음`);
+    } catch (error) {
+      const raw = reason(error);
+      if (!/is already in /.test(raw)) {
+        record({ stage: 'append-dry-run', outcome: 'failed', at: now(), branch, reason: raw });
+        return stop('append-dry-run', error);
+      }
+      const guided = alreadyInGuidance(raw);
+      record({ stage: 'append-dry-run', outcome: 'failed', at: now(), branch, reason: guided });
+      return stop('append-dry-run', new Error(guided));
+    }
+    // 2/3 append — cherry-pick the repairs onto release/<v> and push the fast-forward (never a force push).
+    try {
+      const appended = cutBranch(cut);
+      if (!appended.commit) throw new Error(`${appended.branch} append produced no commit`);
+      tip = appended.commit;
+      record({ stage: 'append', outcome: 'ok', at: now(), branch: appended.branch, commit: tip, pick: opts.pick });
+      deps.onSource?.(`↻ recover 2/3 append · ${appended.branch} ${base.slice(0, 12)} → ${tip.slice(0, 12)} (fast-forward)`);
+    } catch (error) {
+      const raw = reason(error);
+      if (!/is already in /.test(raw)) {
+        record({ stage: 'append', outcome: 'failed', at: now(), branch, reason: raw });
+        return stop('append', error);
+      }
+      const guided = alreadyInGuidance(raw);
+      record({ stage: 'append', outcome: 'failed', at: now(), branch, reason: guided });
+      return stop('append', new Error(guided));
+    }
+  }
+
+  // 3/3 resume --from export-check — the read-only preflight first (its plan is the record), then the graph run.
+  // The append moved only the origin branch tip: the operator checkout is still wherever it was, and the resume
+  // preflight (verifyReleaseCommandRoot) demands a checkout whose HEAD is the new tip. So recover prepares that
+  // checkout itself — a temporary worktree at the tip. A human-provided --command-root stays a judgment
+  // boundary: the plan verifies it against the tip and stops there on a mismatch.
+  const resumeOptions: ResumeReleaseOptions = { runId: opts.runId, from: fromNode,
+    ...(opts.partial === undefined ? {} : { partial: opts.partial }) };
+  let preparedRoot: { dir: string; git: (args: string[]) => string } | undefined;
+  if (opts.commandRoot !== undefined) resumeOptions.commandRoot = opts.commandRoot;
+  else {
+    const temp = mkdtempSync(join(tmpdir(), 'release-recover-'));
+    const dir = join(temp, 'command-root');
+    const worktreeGit = gitRunner(repoRoot);
+    try {
+      worktreeGit(['worktree', 'add', '--detach', dir, tip]);
+    } catch (error) {
+      rmSync(temp, { recursive: true, force: true });
+      throw error;
+    }
+    preparedRoot = { dir, git: worktreeGit };
+    resumeOptions.commandRoot = dir;
+  }
+  try {
+    const plan = await planResumeReleaseRun(resumeOptions, deps);
+    const resumed = await resumeReleaseRun(resumeOptions, deps);
+    record({ stage: 'resume', outcome: 'ok', at: now(), from: fromNode, branch: resumed.tip.branch,
+      commit: resumed.tip.to, gatePlan: plan.gatePlan.mode, status: resumed.state.status });
+    deps.onSource?.(`▶ recover 3/3 resume ${fromNode}부터 · tip ${resumed.tip.to.slice(0, 12)} · gate ${plan.gatePlan.mode} → ${resumed.state.status}`);
+    return { runId: opts.runId, version, branch: resumed.tip.branch, fromNode, stages,
+      resume: { status: resumed.state.status, tip: resumed.tip, partial: resumed.partial } };
+  } catch (error) {
+    record({ stage: 'resume', outcome: 'failed', at: now(), from: fromNode, branch, reason: reason(error) });
+    return stop('resume', error);
+  } finally {
+    if (preparedRoot) {
+      try {
+        preparedRoot.git(['worktree', 'remove', '--force', preparedRoot.dir]);
+      } catch {
+        try { preparedRoot.git(['worktree', 'prune']); } catch { /* the temp dir below is still removed */ }
+      }
+      rmSync(dirname(preparedRoot.dir), { recursive: true, force: true });
+    }
+  }
+}

package/scripts/release-loop/resume.ts

@@ -53,12 +53,20 @@ function printedVerdict(output: unknown): boolean {
   });
 }
 
-/** The only post-gate detour allowed before the terminal failure is the executed, release-only triage shadow. */
-function failedAfterGate(state: GraphRunState, index: number): boolean {
+/** A failed release may execute its warning-only traffic restore before the terminal failure. */
+function failedAfterTrafficRestore(state: GraphRunState, index: number): boolean {
   if (state.nodes.length !== state.path.length || state.path.at(-1) !== 'failed' || state.nodes.at(-1)?.nodeId !== 'failed') return false;
   if (index === state.path.length - 2) return true;
-  return index === state.path.length - 3 && state.path[index + 1] === 'gate-triage'
-    && state.nodes[index + 1]?.nodeId === 'gate-triage' && state.nodes[index + 1]?.executed === true;
+  return index === state.path.length - 3 && state.path[index + 1] === 'traffic-failed-restore'
+    && state.nodes[index + 1]?.nodeId === 'traffic-failed-restore' && state.nodes[index + 1]?.executed === true;
+}
+
+/** Gate may also pass through its executed triage shadow before the traffic restore. */
+function failedAfterGate(state: GraphRunState, index: number): boolean {
+  if (failedAfterTrafficRestore(state, index)) return true;
+  return state.path[index + 1] === 'gate-triage'
+    && state.nodes[index + 1]?.nodeId === 'gate-triage' && state.nodes[index + 1]?.executed === true
+    && failedAfterTrafficRestore(state, index + 1);
 }
 
 export function gateUnmeasuredDetail(state: GraphRunState, index: number): string | undefined {
@@ -113,7 +121,7 @@ export function releaseResumeWaiver(
   }
   if (!unique || state.path.lastIndexOf(opts.waive) !== index || state.nodes[index]?.nodeId !== opts.waive || state.nodes[index]?.ok !== false ||
     state.nodes[index]?.executed !== true || (opts.waive === 'gate' ? !failedAfterGate(state, index)
-      : state.path.at(-2) !== opts.waive || state.path.at(-1) !== 'failed' || state.nodes.at(-1)?.nodeId !== 'failed')) {
+      : !failedAfterTrafficRestore(state, index))) {
     throw new Error(`--waive ${opts.waive} requires the failed executable node on the saved path`);
   }
   // Only user-visible, non-publication checks can become accepted regressions; build, safety and approval gates stay blocking.

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

@@ -7,8 +7,11 @@ import { errorResult, finishNode, readGraphContext } from './node-verdict.js';
 import { applyReleaseTrafficEvent, trafficOptionsFromConfig, type ReleaseTrafficEvent, type TrafficTransitionOptions } from './traffic-transition.js';
 
 const EVENTS: Record<string, ReleaseTrafficEvent> = {
+  'traffic-cut-start': 'cut-start',
   'traffic-gate-passed': 'gate-passed',
+  'traffic-npm-published': 'npm-published',
   'traffic-verify-complete': 'verify-complete',
+  'traffic-failed-restore': 'failed',
 };
 
 export interface TrafficNodeDeps {
@@ -40,12 +43,17 @@ export async function runTrafficNode(node = process.argv[2], env: NodeJS.Process
     }
     const result = await applyReleaseTrafficEvent(context, event, options);
     if (!result.applied) {
-      const consequence = event === 'verify-complete'
-        ? '릴리스 검증은 성공했으나 트래픽 복귀가 적용되지 않았습니다.'
-        : 'gate는 성공했으나 트래픽 감속이 적용되지 않았습니다.';
+      const consequence = event === 'failed' && result.reason === 'published-keeps-full'
+        ? 'npm 발행은 완료됐으므로 전체 트래픽을 유지합니다. 후속 발행 단계 실패를 확인하세요.'
+        : event === 'verify-complete' || event === 'npm-published'
+          ? '발행은 성공했으나 전체 트래픽 전환이 적용되지 않았습니다.'
+          : event === 'failed' ? '컷 전 트래픽 복귀가 적용되지 않았습니다.'
+            : event === 'cut-start' ? '컷은 시작했으나 gate 모드 전환이 적용되지 않았습니다.'
+              : 'gate는 성공했으나 트래픽 감속이 적용되지 않았습니다.';
       (deps.report ?? reportFailure)(`RELEASE-POSTPUB-TRAFFIC ${version} ${runId || 'unknown'} ${node} 무시 — ${result.reason ?? 'traffic state unchanged'}. ${consequence}`);
     }
-    return finishNode(node!, version, { outcome: 'ok', verdict: 'pass', summary: `${event} ${result.applied ? 'applied' : result.reason ?? 'ignored'}` });
+    return finishNode(node!, version, { outcome: result.applied ? 'ok' : 'fail', verdict: result.applied ? 'pass' : 'fail',
+      summary: `${event} ${result.applied ? 'applied' : result.reason ?? 'ignored'}` });
   } catch (error) {
     const detail = errorResult(error).summary;
     const isLockTimeout = detail.startsWith('traffic lock timeout:');

package/scripts/release-loop/traffic-transition.ts

@@ -4,12 +4,17 @@ import { debug } from '../../src/debug/log.js';
 import type { GraphContext } from './node-verdict.js';
 import type { ReleaseLoopConfig } from './unattended-release.js';
 
-export type ReleaseTrafficEvent = 'gate-passed' | 'verify-complete';
+export type ReleaseTrafficEvent = 'cut-start' | 'gate-passed' | 'npm-published' | 'verify-complete' | 'failed';
+
+export interface TrafficBeforeCut {
+  global?: string;
+  perCycle: Record<string, unknown>;
+}
 
 export interface TrafficFile {
   global?: string;
   seats: Record<string, Record<string, unknown>>;
-  releaseLifecycle?: { runId: string; version: string; stage: 1 | 2; event: ReleaseTrafficEvent; startedAt?: string; updatedAt: string };
+  releaseLifecycle?: { runId: string; version: string; stage: 0 | 1 | 2 | 3; event: ReleaseTrafficEvent; startedAt?: string; updatedAt: string; beforeCut?: TrafficBeforeCut };
   [key: string]: unknown;
 }
 
@@ -18,7 +23,7 @@ type ReleaseTrafficConfig = ReleaseLoopConfig & {
 };
 
 const SEATS = ['OP', 'TC', 'MK', 'UX'] as const;
-const STAGE: Record<ReleaseTrafficEvent, 1 | 2> = { 'gate-passed': 1, 'verify-complete': 2 };
+const STAGE: Record<ReleaseTrafficEvent, 0 | 1 | 2 | 3> = { 'cut-start': 0, 'gate-passed': 1, 'npm-published': 2, 'verify-complete': 2, failed: 3 };
 const TRAFFIC_PER_CYCLE = { half: 3, full: 6 } as const;
 
 export interface TrafficTransitionOptions {
@@ -112,32 +117,65 @@ export async function applyReleaseTrafficEvent(
   const log = options.log ?? ((name, fields) => debug.log('release-loop.traffic', name, fields));
   const stage = STAGE[event];
   const stamp = (options.now ?? (() => new Date()))().toISOString();
-  const rate = event === 'gate-passed' ? TRAFFIC_PER_CYCLE.half : TRAFFIC_PER_CYCLE.full;
-  const releaseLifecycle = { runId, version, stage, event, ...(context.startedAt ? { startedAt: context.startedAt } : {}), updatedAt: stamp };
+  const rate = event === 'gate-passed' ? TRAFFIC_PER_CYCLE.half
+    : event === 'npm-published' || event === 'verify-complete' ? TRAFFIC_PER_CYCLE.full : undefined;
   const release = () => {
     const unlock = acquireTrafficLock(path, options.lockTimeoutMs);
     try {
       const before = readTrafficFile(path);
       const prior = before.releaseLifecycle;
+      if ((event === 'npm-published' || event === 'verify-complete') && context.outputs['npm-publish']?.outcome !== 'ok') {
+        return { file: before, applied: false, idempotent: false, reason: 'npm-publish-unconfirmed' };
+      }
       const sameRun = prior?.runId === runId;
       const newerVersion = !prior?.runId || compareReleaseVersions(version, prior.version) > 0;
       const sameVersionLaterRun = prior?.version === version && isLaterRun(context.startedAt, prior.startedAt);
-      if (sameRun && prior.stage >= stage) return { file: before, applied: true, idempotent: true };
-      const permitted = sameRun
-        ? prior.stage === stage - 1
-        : newerVersion || (event === 'gate-passed' && prior?.version === version && (prior.stage ?? 0) < 2 && sameVersionLaterRun)
-          || (event === 'verify-complete' && prior?.version === version && sameVersionLaterRun);
+      const resumedTrafficNode = sameRun && prior.stage === 3
+        && (event === 'cut-start' && context.nodeId === 'traffic-cut-start'
+          || event === 'gate-passed' && context.nodeId === 'traffic-gate-passed'
+          || event === 'npm-published' && context.nodeId === 'traffic-npm-published'
+          || event === 'verify-complete' && context.nodeId === 'traffic-verify-complete' && context.outputs['npm-publish']?.outcome === 'ok');
+      if (sameRun && prior.stage === 3 && event !== 'failed' && !resumedTrafficNode) {
+        return { file: before, applied: false, idempotent: false, reason: 'run-already-failed' };
+      }
+      if (sameRun && prior.stage >= stage && event !== 'failed' && !resumedTrafficNode) return { file: before, applied: true, idempotent: true };
+      if (event === 'failed' && (!sameRun || prior?.stage === 2 || prior?.stage === 3 || !prior?.beforeCut)) {
+        return { file: before, applied: false, idempotent: false,
+          reason: !sameRun ? prior?.runId ? 'different-run-is-current' : 'before-cut-unmeasured'
+            : prior?.stage === 2 ? 'published-keeps-full' : prior?.stage === 3 ? 'already-restored' : 'before-cut-unmeasured' };
+      }
+      const permitted = event === 'failed' ? sameRun
+        : sameRun ? resumedTrafficNode || (stage === 0 ? prior.stage === 0 : stage > prior.stage)
+        : newerVersion || (prior?.version === version && sameVersionLaterRun && (prior.stage < 2 || prior.stage === 3 || event === 'verify-complete'));
       if (!permitted) {
         return { file: before, applied: false, idempotent: false, reason: prior?.runId && prior.runId !== runId ? 'different-run-is-current' : 'event-out-of-order' };
       }
+      if (event === 'cut-start' && prior && prior.stage < 2 && !prior.beforeCut) {
+        return { file: before, applied: false, idempotent: false, reason: 'before-cut-unmeasured' };
+      }
+      const beforeCut = event === 'cut-start' ? {
+        ...(prior?.stage !== undefined && prior.stage < 2 && prior.beforeCut
+          ? prior.beforeCut
+          : { ...(before.global === undefined ? {} : { global: before.global }),
+            perCycle: Object.fromEntries(SEATS.map((seat) => [seat, before.seats[seat]?.perCycle])) }),
+      } : prior?.beforeCut;
+      const releaseLifecycle = { runId, version, stage, event, ...(context.startedAt ? { startedAt: context.startedAt } : {}),
+        updatedAt: stamp, ...(beforeCut ? { beforeCut } : {}) };
       const after: TrafficFile = {
         ...before,
-        ...(event === 'verify-complete' ? { global: 'green' } : {}),
+        ...(event === 'cut-start' ? { global: 'gate' }
+          : event === 'gate-passed' ? { global: 'yellow' }
+          : event === 'npm-published' || event === 'verify-complete' ? { global: 'green' }
+          : beforeCut?.global === undefined ? {} : { global: beforeCut.global }),
         seats: Object.fromEntries(Object.entries(before.seats).map(([seat, value]) => [
-          seat, SEATS.includes(seat as typeof SEATS[number]) ? { ...value, perCycle: rate } : value,
+          seat, SEATS.includes(seat as typeof SEATS[number])
+            ? { ...value, ...(event === 'failed' ? { perCycle: beforeCut?.perCycle[seat] } : rate === undefined ? {} : { perCycle: rate }) }
+            : value,
         ])),
         releaseLifecycle,
       };
+      if (event === 'failed' && beforeCut?.global === undefined) delete after.global;
+      if (event === 'failed') for (const seat of SEATS) if (beforeCut?.perCycle[seat] === undefined) delete after.seats[seat]?.perCycle;
       atomicWriteTrafficFile(path, after);
       return { file: after, applied: true, idempotent: false };
     } finally { unlock(); }
@@ -145,7 +183,9 @@ export async function applyReleaseTrafficEvent(
   const result = release();
   const reason = result.applied && result.idempotent ? 'already-applied' : result.reason;
   log(result.idempotent ? 'already-applied' : result.applied ? 'applied' : 'ignored', {
-    runId, version, event, stage, reason, perCycle: rate, ...(event === 'verify-complete' ? { global: 'green' } : {}),
+    runId, version, event, stage, reason, ...(rate === undefined ? {} : { perCycle: rate }),
+    ...(event === 'cut-start' ? { global: 'gate' } : event === 'gate-passed' ? { global: 'yellow' }
+      : event === 'npm-published' || event === 'verify-complete' ? { global: 'green' } : {}),
   });
   return { applied: result.applied, stage: result.file.releaseLifecycle?.stage ?? 0, ...(reason ? { reason } : {}) };
 }

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

@@ -8,6 +8,7 @@ import { debug } from '../../src/debug/log.js';
 import { effectiveInstanceRoot, prodInstanceRoot } from '../../src/instance/resolve.js';
 import { landingFreezeMessage, readLandingFreeze, type LandingFreeze } from '../../src/release-loop/landing-freeze.js';
 import { baseVersion, isReleaseVersion, isStableVersion, prereleaseKind } from './release-version.js';
+import { cutReleaseBranch } from './cut-branch.js';
 
 type Kind = 'release' | 'dev-bump';
 type Output = { outcome: 'ok' | 'error'; kind: Kind | null; version: string | null; commit: string | null; pr: number | null; files?: string[]; worktree?: string; error?: string;
@@ -441,19 +442,30 @@ export function main(args: string[] = process.argv.slice(2), repo = process.cwd(
   let branchCut = false;
   let runId: string | undefined;
   try {
-    if (args[0] !== 'release' && args[0] !== 'dev-bump') throw new Error('usage: version-node.ts <release|dev-bump> [--version <v>] [--cut <sha>] [--cut-commit <sha>] --json');
-    kind = args[0];
+    if (args[0] !== 'release' && args[0] !== 'dev-bump' && args[0] !== 'cut-branch')
+      throw new Error('usage: version-node.ts <release|dev-bump|cut-branch> [--version <v>] [--cut <sha>] [--cut-commit <sha>] [--pick <sha>] [--base <sha>] [--append] [--dry-run] --json');
+    kind = args[0] === 'cut-branch' ? 'release' : args[0];
+    const picks: string[] = [];
+    let base: string | undefined;
+    let append = false;
+    let dryRun = false;
+    let versionRelease: { commit?: unknown; base?: unknown; branch?: unknown } | undefined;
     for (let i = 1; i < args.length; i++) {
       if (args[i] === '--json') continue;
       if (args[i] === '--version' && args[i + 1]) { version = args[++i]!; continue; }
       if (args[i] === '--cut' && args[i + 1]) { cut = args[++i]!; continue; }
       if (args[i] === '--cut-commit' && args[i + 1]) { cutCommit = args[++i]!; continue; }
+      if (args[i] === '--pick' && args[i + 1]) { picks.push(args[++i]!); continue; }
+      if (args[i] === '--base' && args[i + 1]) { base = args[++i]!; continue; }
+      if (args[i] === '--append') { append = true; continue; }
+      if (args[i] === '--dry-run') { dryRun = true; continue; }
       throw new Error(`unknown or incomplete argument: ${args[i]}`);
     }
     if (process.env.ELANOUS_GRAPH_CONTEXT) {
       const location = process.env.ELANOUS_GRAPH_CONTEXT;
       const context = JSON.parse(location.trimStart().startsWith('{') ? location : readFileSync(location, 'utf8')) as {
-        runId?: unknown; input?: { version?: unknown; cutCommit?: unknown; forceFreeze?: unknown; branchCut?: unknown }; outputs?: Record<string, { commit?: unknown } | undefined> };
+        runId?: unknown; input?: { version?: unknown; cutCommit?: unknown; forceFreeze?: unknown; branchCut?: unknown };
+        outputs?: Record<string, { commit?: unknown; base?: unknown; branch?: unknown } | undefined> };
       if (context.runId !== undefined) {
         if (typeof context.runId !== 'string') throw new Error('runId must be a string');
         runId = context.runId;
@@ -466,11 +478,24 @@ export function main(args: string[] = process.argv.slice(2), repo = process.cwd(
         cutCommit = context.input.cutCommit;
       }
       // The cut = the commit version-release landed (what cutoff and the gate measured).
+      // RELEASE-APPEND-BASE-AUTO: cut-branch consumes that same record as its ledger seam
+      // (ledger: () => versionRelease), so it must not also see it injected as --cut.
       const releasedCommit = context.outputs?.['version-release']?.commit;
-      if (!cut && typeof releasedCommit === 'string' && releasedCommit) cut = releasedCommit;
+      if (args[0] !== 'cut-branch' && !cut && typeof releasedCommit === 'string' && releasedCommit) cut = releasedCommit;
+      // RELEASE-APPEND-BASE-AUTO: the version-release node's record is the ledger seam cut-branch consults.
+      versionRelease = context.outputs?.['version-release'];
     }
     if (!version) throw new Error('version required (--version or ELANOUS_GRAPH_CONTEXT.input.version)');
     nextDevVersion(version);
+    if (args[0] === 'cut-branch') {
+      if (cut !== undefined || cutCommit !== undefined) throw new Error('--cut/--cut-commit are not valid for cut-branch');
+      if (!picks.length) throw new Error('at least one --pick commit is required');
+      const result = cutReleaseBranch({
+        version, pick: picks, ...(base !== undefined ? { base } : {}), append, dryRun,
+        repoRoot: resolve(repo), ledger: () => versionRelease,
+      });
+      return { outcome: 'ok', kind: 'release', version, commit: result.commit, pr: null, branch: result.branch, ...(dryRun ? { skipped: 'dry-run' } : {}) };
+    }
     if (kind === 'dev-bump' && cutCommit !== undefined) throw new Error('--cut-commit is only valid for release');
     return landing(resolve(repo), kind, version, cut, cutCommit, forceFreeze, branchCut, undefined, runId);
   } catch (error) {