elanous 0.2.36 → 0.2.37

package/scripts/release-loop/notes-repair.ts

@@ -0,0 +1,216 @@
+import { readFileSync, writeFileSync, renameSync, unlinkSync, existsSync, statSync, chmodSync, realpathSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { SPAWN_SYNC_MAX_BUFFER } from '../../src/util/spawn-sync-output.js';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { effectiveInstanceRoot } from '../../src/instance/resolve.js';
+import { getProviderForConfig, type LLMMessage } from '../../src/llm.js';
+import { getUserConfig } from '../../src/user-config.js';
+import type { GraphContext } from './node-verdict.js';
+
+export const REPAIR_MODEL = 'openrouter/z-ai/glm-5.3';
+export type Translator = (line: string, model: string) => Promise<string>;
+export type RepairResult = { text: string; translatedLines: number[]; error?: string };
+
+function koreanProseLines(text: string): Array<{ index: number; line: string }> {
+  let fence: { char: string; length: number } | undefined;
+  return text.split(/\r?\n/).flatMap((line, index) => {
+    const marker = /^ {0,3}(`{3,}|~{3,})/.exec(line)?.[1];
+    if (marker) {
+      if (!fence) fence = { char: marker[0]!, length: marker.length };
+      else if (marker[0] === fence.char && marker.length >= fence.length) fence = undefined;
+      return [];
+    }
+    if (fence || !/[가-힣]/.test(line.replace(/(`+)[^`]*?\1/g, ''))) return [];
+    return [{ index, line }];
+  });
+}
+
+export async function repairKoreanMarkdown(text: string, translate: Translator, onlyLines?: ReadonlySet<number>): Promise<RepairResult> {
+  const lines = text.split(/\r?\n/);
+  const translatedLines: number[] = [];
+  for (const item of koreanProseLines(text).filter(({ index }) => !onlyLines || onlyLines.has(index + 1))) {
+    try {
+      // Keep inline code out of the model's editable surface and restore it byte-for-byte.
+      const code: string[] = [];
+      const protectedLine = item.line.replace(/(`+)[^`]*?\1/g, (match) => `⟦CODE${code.push(match) - 1}⟧`);
+      const value = (await translate(protectedLine, REPAIR_MODEL)).trim();
+      if (!value) throw new Error('translator returned empty text');
+      for (const [index] of code.entries()) {
+        const token = `⟦CODE${index}⟧`;
+        if (value.split(token).length !== 2) throw new Error('translator changed protected inline code');
+      }
+      const restored = value.replace(/⟦CODE(\d+)⟧/g, (_match, rawIndex: string) => {
+        const original = code[Number(rawIndex)];
+        if (original === undefined) throw new Error('translator changed protected inline code');
+        return original;
+      });
+      if (/[가-힣]/.test(restored.replace(/(`+)[^`]*?\1/g, ''))) throw new Error('translation still contains Korean prose');
+      lines[item.index] = restored;
+      translatedLines.push(item.index + 1);
+    } catch (error) {
+      return { text, translatedLines: [], error: `line ${item.index + 1}: ${error instanceof Error ? error.message : String(error)}` };
+    }
+  }
+  return { text: lines.join('\n'), translatedLines };
+}
+
+export const glmTranslator: Translator = async (line, model) => {
+  if (model !== REPAIR_MODEL) throw new Error(`unexpected translator model: ${model}`);
+  const config = getUserConfig();
+  const llmConfig = { ...config, llm: { ...config.llm, provider: 'openrouter' as const, model } };
+  const provider = getProviderForConfig(llmConfig, model);
+  if (provider.name !== 'openrouter' || !provider.available()) throw new Error('OpenRouter credentials unavailable for openrouter/z-ai/glm-5.3');
+  const messages: LLMMessage[] = [
+    { role: 'system', content: 'Translate the supplied single public release-note line into concise idiomatic English. Return only the translation. Preserve markdown structure, meaning, punctuation, and every placeholder exactly.' },
+    { role: 'user', content: line },
+  ];
+  let result = '';
+  for await (const chunk of provider.chat(messages, { model, temperature: 0, maxTokens: 512, remainingFallbacks: 0, promptCache: false })) result += chunk;
+  return result;
+};
+
+export function atomicallyRepairFiles(targets: Array<{ path: string; lines: number[] }>, translate: Translator = glmTranslator): Promise<{ files: string[]; translatedLines: number[]; error?: string }> {
+  return (async () => {
+    const changed: string[] = [];
+    const translatedLines: number[] = [];
+    const staged: Array<{ path: string; text: string }> = [];
+    for (const { path, lines: selectedLines } of targets) {
+      const original = readFileSync(path, 'utf8');
+      const result = await repairKoreanMarkdown(original, translate, new Set(selectedLines));
+      if (result.error) return { files: changed, translatedLines, error: `${path}: ${result.error}` };
+      if (result.text !== original) {
+        staged.push({ path, text: result.text });
+        changed.push(path);
+        translatedLines.push(...result.translatedLines);
+      }
+    }
+    for (const { path, text } of staged) {
+      const temp = join(dirname(path), `.${basename(path)}.${randomUUID()}.tmp`);
+      try { writeFileSync(temp, text); chmodSync(temp, statSync(path).mode); renameSync(temp, path); }
+      finally { if (existsSync(temp)) unlinkSync(temp); }
+    }
+    return { files: changed, translatedLines };
+  })();
+}
+
+type DocsReceipt = {
+  owner: { runId: string; attempt: number };
+  branch: string;
+  worktree: string;
+  outcome: 'pushed';
+  head: string;
+  result: Record<string, unknown>;
+};
+
+function git(tree: string, ...args: string[]): string {
+  const result = spawnSync('git', args, { cwd: tree, encoding: 'utf8', timeout: 30_000, maxBuffer: SPAWN_SYNC_MAX_BUFFER });
+  if (result.status !== 0) throw new Error(`docs repair git ${args[0]} failed: ${(result.stderr || result.error || '').toString().trim()}`);
+  return result.stdout.trim();
+}
+
+function remoteHead(tree: string, branch: string): string {
+  const line = git(tree, 'ls-remote', '--heads', 'origin', `refs/heads/${branch}`);
+  const match = /^([0-9a-f]{40})\s+refs\/heads\/[^\s]+$/i.exec(line);
+  if (!match) throw new Error(`docs repair remote head missing or invalid: ${branch}`);
+  return match[1]!;
+}
+
+function publishReceipt(path: string, receipt: DocsReceipt): void {
+  const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+  try { writeFileSync(temp, JSON.stringify(receipt) + '\n'); renameSync(temp, path); }
+  finally { if (existsSync(temp)) unlinkSync(temp); }
+}
+
+function ownedDocsReceipt(context: GraphContext, docs: Record<string, unknown>, tree: string, stateRoot: string,
+  approvedPaths: string[]): { path: string; receipt: DocsReceipt } {
+  const runId = context.runId;
+  const owner = docs.artifactOwner as { runId?: unknown; attempt?: unknown } | undefined;
+  const branch = `release-docs/${context.input.version}`;
+  if (!runId || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(runId)
+    || !owner || owner.runId !== runId || !Number.isSafeInteger(owner.attempt) || docs.branch !== branch)
+    throw new Error('docs repair requires same-run docs branch ownership');
+  const path = join(stateRoot, 'release', context.input.version, 'docs-branch-owner.json');
+  let receipt = JSON.parse(readFileSync(path, 'utf8')) as DocsReceipt;
+  if (receipt?.outcome !== 'pushed' || receipt.owner?.runId !== runId || receipt.owner.attempt !== owner.attempt
+    || receipt.branch !== branch || realpathSync(receipt.worktree) !== tree || !/^[0-9a-f]{40}$/i.test(receipt.head)
+    || receipt.result?.outcome !== 'ok') throw new Error('docs repair ownership receipt does not match this run and attempt');
+  if (git(tree, 'branch', '--show-current') !== branch) throw new Error('docs repair branch differs from ownership receipt');
+  if (git(tree, 'status', '--porcelain')) throw new Error('docs repair worktree is not clean');
+  const local = git(tree, 'rev-parse', 'HEAD');
+  const remote = remoteHead(tree, branch);
+  if (local !== receipt.head) {
+    const parents = git(tree, 'rev-list', '--parents', '-n', '1', 'HEAD').split(' ');
+    const message = git(tree, 'log', '-1', '--format=%B', 'HEAD');
+    const changed = git(tree, 'diff-tree', '--no-commit-id', '--name-only', '-r', 'HEAD').split('\n').filter(Boolean);
+    const approved = approvedPaths.map((file) => relative(tree, realpathSync(file)));
+    if (parents.length !== 2 || parents[0] !== local || parents[1] !== receipt.head
+      || !message.split('\n').includes(`Release-Notes-Repair-Run: ${runId}`)
+      || !message.split('\n').includes(`Release-Notes-Repair-Attempt: ${owner.attempt}`)
+      || !changed.length || changed.some((name) => !approved.includes(name))
+      || (remote !== receipt.head && remote !== local))
+      throw new Error('docs repair local/remote head differs from ownership receipt');
+    if (remote === receipt.head) git(tree, 'push', 'origin', `HEAD:refs/heads/${branch}`);
+    if (remoteHead(tree, branch) !== local) throw new Error('docs repair recovery remote head verification failed');
+    receipt = { ...receipt, head: local };
+    publishReceipt(path, receipt);
+  } else if (remote !== receipt.head) throw new Error('docs repair local/remote head differs from ownership receipt');
+  return { path, receipt };
+}
+
+function publishDocsRepair(tree: string, files: string[], path: string, receipt: DocsReceipt): string {
+  const names = files.map((file) => relative(tree, realpathSync(file)));
+  git(tree, 'add', '--', ...names);
+  const staged = git(tree, 'diff', '--cached', '--name-only').split('\n').filter(Boolean);
+  if (staged.some((name) => !names.includes(name))) throw new Error('docs repair staged a file outside approved B11 targets');
+  if (!staged.length) return receipt.head;
+  git(tree, 'commit', '-m', `docs: repair release ${receipt.branch.split('/').at(-1)} notes`,
+    '-m', `Release-Notes-Repair-Run: ${receipt.owner.runId}\nRelease-Notes-Repair-Attempt: ${receipt.owner.attempt}`);
+  const head = git(tree, 'rev-parse', 'HEAD');
+  git(tree, 'push', 'origin', `HEAD:refs/heads/${receipt.branch}`);
+  if (remoteHead(tree, receipt.branch) !== head) throw new Error('docs repair remote head verification failed');
+  publishReceipt(path, { ...receipt, head });
+  return head;
+}
+
+export async function runNotesRepair(context: GraphContext, translate: Translator = glmTranslator,
+  deps: { stateRoot?: string } = {}): Promise<{
+  outcome: 'ok' | 'fail'; version: string; summary: string; files?: string[]; translatedLines?: number[]; head?: string; error?: string;
+}> {
+  try {
+    if (context.outputs['notes-repair']) throw new Error('B11 remains after the single permitted translation attempt');
+    const docs = context.outputs.docs;
+    if (docs?.outcome !== 'ok' || typeof docs.notes !== 'string' || typeof docs.worktree !== 'string') throw new Error('docs output required');
+    const findings = context.outputs['notes-check']?.findings;
+    if (!Array.isArray(findings)) throw new Error('notes-check findings required');
+    const allowed = new Set([docs.notes, ...(Array.isArray(docs.flipped) ? docs.flipped : [])]
+      .filter((path): path is string => typeof path === 'string').map((path) => realpathSync(resolve(path))));
+    const worktree = realpathSync(resolve(docs.worktree));
+    const targets = new Map<string, Set<number>>();
+    for (const raw of findings) {
+      if (!raw || typeof raw !== 'object') continue;
+      const finding = raw as { rule?: unknown; file?: unknown; line?: unknown };
+      if (finding.rule !== 'B11' || typeof finding.file !== 'string' || typeof finding.line !== 'number'
+        || !Number.isSafeInteger(finding.line) || finding.line < 1) continue;
+      const file = realpathSync(resolve(finding.file));
+      if (!file.startsWith(`${worktree}${sep}`) || !allowed.has(file)) throw new Error(`B11 target outside docs output: ${finding.file}`);
+      const lines = targets.get(finding.file) ?? new Set<number>();
+      lines.add(finding.line);
+      targets.set(finding.file, lines);
+    }
+    if (findings.some((finding) => !finding || typeof finding !== 'object' || (finding as { rule?: string }).rule !== 'B11'))
+      throw new Error('notes-check has non-B11 findings; translation cannot repair them');
+    if (!targets.size) throw new Error('notes-check failed without repairable B11 findings');
+    const files = [...targets].map(([path, lines]) => ({ path, lines: [...lines] }));
+    const { path: receiptPath, receipt } = ownedDocsReceipt(context, docs, worktree,
+      deps.stateRoot ?? effectiveInstanceRoot(), files.map((file) => file.path));
+    const result = await atomicallyRepairFiles(files, translate);
+    if (result.error) return { outcome: 'fail', version: context.input.version, summary: result.error, ...result };
+    const head = result.files.length ? publishDocsRepair(worktree, result.files, receiptPath, receipt) : receipt.head;
+    return { outcome: 'ok', version: context.input.version,
+      summary: `translated ${result.translatedLines.length} line(s)`, ...result, head };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { outcome: 'fail', version: context.input.version, summary: message, error: message };
+  }
+}

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

@@ -21,13 +21,43 @@ function readRegularManifest(path: string): Buffer {
   } finally { closeSync(fd); }
 }
 
+function releaseAttempt(root: string, version: string, runId: string): number {
+  const path = join(root, 'release', version, 'resume-attempts', `${runId}.json`);
+  if (!existsSync(path)) return 0;
+  let value: { version?: unknown; runId?: unknown; attempts?: unknown };
+  try { value = JSON.parse(readFileSync(path, 'utf8')) as typeof value; }
+  catch { throw new Error(`invalid release resume attempts: ${path}`); }
+  if (value.version !== version || value.runId !== runId || !Array.isArray(value.attempts)
+    || value.attempts.some((at) => typeof at !== 'string' || !Number.isFinite(Date.parse(at))))
+    throw new Error(`invalid release resume attempts: ${path}`);
+  return value.attempts.length;
+}
+
+/** Old releases predate the owner receipt; their own graph ledger can still prove the prepared output. */
+function preparedByRun(root: string, runId: string, out: string, commit: string): boolean {
+  try {
+    const ledger = JSON.parse(readFileSync(join(root, 'graph-runs', 'release-loop', `${runId}.json`), 'utf8')) as
+      { runId?: string; graphId?: string; nodes?: Array<{ nodeId?: string; ok?: boolean; output?: string }> };
+    if (ledger.runId !== runId || ledger.graphId !== 'release-loop') return false;
+    return ledger.nodes?.some((node) => {
+      if (node.nodeId !== 'prepare' || !node.ok || typeof node.output !== 'string') return false;
+      try {
+        const output = JSON.parse(node.output.trim().split('\n').at(-1) ?? '') as { out?: string; commit?: string; outcome?: string };
+        return output.outcome === 'ok' && output.out === out && output.commit === commit;
+      } catch { return false; }
+    }) ?? false;
+  } catch { return false; }
+}
+
 export function runPrepare(run: CommandRunner = runCommand, move: typeof renameSync = renameSync) {
   const context = readGraphContext();
   const { version, previousVersion } = context.input;
   if (!isReleaseVersion(version)) throw new Error(`invalid release version: ${version}`);
+  if (context.runId && !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(context.runId)) throw new Error('invalid release runId');
   const commit = nodeOutput(context, 'version-release', 'commit');
   for (const node of ['gate', 'pwa']) if (context.outputs[node]?.outcome !== 'ok') throw new Error(`${node} did not pass`);
   const root = effectiveInstanceRoot();
+  const attempt = context.runId ? releaseAttempt(root, version, context.runId) : undefined;
   const out = join(root, 'release', version, 'prepared');
   if ([join(root, 'release'), join(root, 'release', version)]
     .some((path) => lstatSync(path, { throwIfNoEntry: false })?.isSymbolicLink()))
@@ -41,22 +71,44 @@ export function runPrepare(run: CommandRunner = runCommand, move: typeof renameS
     // archive is left untouched for investigation; never erase it merely because the path is occupied.
     const old = context.outputs['version-release']?.refreshedFrom;
     const manifestPath = join(out, 'release.json');
-    if (typeof old !== 'string' || !/^[0-9a-f]{40}$/i.test(old) || old === commit
-      || !occupied.isDirectory() || !existsSync(manifestPath) || !lstatSync(manifestPath).isFile())
+    if (!occupied.isDirectory() || !existsSync(manifestPath) || !lstatSync(manifestPath).isFile())
       throw new Error(`prepare output already exists with unverified source: ${out}`);
     if (realpathSync(out) !== join(realpathSync(root), 'release', version, 'prepared'))
       throw new Error(`prepare output escapes release root: ${out}`);
     let manifest: { version?: unknown; sourceCommit?: unknown };
     try { staleManifestBytes = readRegularManifest(manifestPath); manifest = JSON.parse(staleManifestBytes.toString('utf8')) as typeof manifest; }
     catch { throw new Error(`prepare output already exists with unreadable manifest: ${out}`); }
-    if (manifest.version !== version || manifest.sourceCommit !== old)
+    const manifestSource = manifest.sourceCommit;
+    if (manifest.version !== version || typeof manifestSource !== 'string' || !/^[0-9a-f]{40}$/i.test(manifestSource)
+      || (manifestSource !== commit && manifestSource !== old))
       throw new Error(`prepare output already exists for another source: ${out}`);
+    const ownerPath = join(out, '.release-node-owner.json');
+    let owner: { runId?: string; commit?: string } | undefined;
+    if (existsSync(ownerPath)) {
+      try { owner = JSON.parse(readRegularManifest(ownerPath).toString('utf8')) as typeof owner; }
+      catch { throw new Error(`prepare output owner unreadable: ${out}`); }
+    }
+    const sameRun = !!context.runId && (owner?.runId === context.runId && owner.commit === manifestSource
+      || !owner && preparedByRun(root, context.runId, out, manifestSource));
+    if (manifestSource === commit && sameRun) {
+      const candidate = join(out, 'dist', 'elanous.tgz');
+      if (!existsSync(candidate)) throw new Error(`prepare output incomplete for same run: ${out}`);
+      return { outcome: 'ok' as const, verdict: 'pass' as const,
+        summary: `prepare ${version} · ${commit.slice(0, 12)} reused`, out, candidate, commit,
+        artifactOwner: { runId: context.runId, attempt, reused: true } };
+    }
+    // A different run's complete archive is never consumed. Without a verified owner, an archive at the
+    // current tip remains untouched; a refreshed old tip can still follow the existing guarded quarantine.
+    if (manifestSource === commit && !owner?.runId)
+      throw new Error(`prepare output already exists with unverified owner: ${out}`);
+    if (manifestSource !== commit && (typeof old !== 'string' || !/^[0-9a-f]{40}$/i.test(old) || old === commit))
+      throw new Error(`prepare output already exists with unverified source: ${out}`);
     staleParents = [join(root, 'release'), join(root, 'release', version)].map((path) => {
       const stat = lstatSync(path);
       if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error(`prepare output escapes release root: ${out}`);
       return { path, dev: stat.dev, ino: stat.ino, real: realpathSync(path) };
     });
-    staleSource = old;
+    staleSource = manifestSource;
   }
   const ref = `v${previousVersion}^{commit}`;
   const prev = run('git', ['rev-parse', '--verify', ref]);
@@ -119,7 +171,11 @@ export function runPrepare(run: CommandRunner = runCommand, move: typeof renameS
   if (command.status !== 0 || manifest?.version !== version || manifest.sourceCommit !== commit || manifest.distDir !== join(out, 'dist')) {
     throw new Error(`prepare incomplete (rc=${command.status}): ${lastResult(command)?.error ?? command.stderr.trim()}`);
   }
-  return { outcome: 'ok' as const, verdict: 'pass' as const, summary: `prepare ${version} · ${commit.slice(0, 12)}`, out, candidate: join(out, 'dist', 'elanous.tgz'), commit };
+  const artifactOwner = context.runId ? { runId: context.runId, attempt, commit } : undefined;
+  if (artifactOwner && existsSync(join(out, 'release.json')))
+    writeFileSync(join(out, '.release-node-owner.json'), JSON.stringify(artifactOwner) + '\n', { flag: 'wx', mode: 0o600 });
+  return { outcome: 'ok' as const, verdict: 'pass' as const, summary: `prepare ${version} · ${commit.slice(0, 12)}`, out, candidate: join(out, 'dist', 'elanous.tgz'), commit,
+    ...(artifactOwner ? { artifactOwner } : {}) };
 }
 
 if (import.meta.main) {

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

@@ -3,8 +3,8 @@
 // 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 { constants, copyFileSync, existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { accessSync, closeSync, constants, copyFileSync, existsSync, fstatSync, openSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import { 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';
@@ -15,6 +15,8 @@ import { changedFilesBetween, clearPartialPlan, planPartialRegate, planStalledSh
 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 { releaseLoopConfig } from './unattended-release.js';
+import { trafficOptionsFromConfig } from './traffic-transition.js';
 
 const GRAPH = join(import.meta.dir, '../../graphs/release/release-loop.yaml');
 
@@ -37,6 +39,8 @@ export interface ResumeReleaseDeps {
   closureTree?: (commit: string) => ClosureTree;
   /** Source observation before the first resumed node. */
   onSource?: (line: string) => void;
+  /** Test seam; production resolves this from ELANOUS_RELEASE_TRAFFIC_FILE / release.loop.trafficFile. */
+  trafficFile?: string;
 }
 
 export interface ResumeReleaseOptions {
@@ -80,7 +84,7 @@ function safeRunId(runId: string): string {
   return runId;
 }
 
-/** Point the saved version-release output at the current release/<v> tip (fast-forward of the recorded commit only). */
+/** Lower-level maintenance primitive; the resume entrypoints run verifyResumePreflight before calling it. */
 export function refreshReleaseBranchTip(runId: string, deps: ResumeReleaseDeps = {}, from?: string, waiverCommit?: string): TipRefresh {
   return refreshReleaseBranchTipInternal(runId, deps, from, waiverCommit, false);
 }
@@ -128,7 +132,7 @@ function refreshReleaseBranchTipInternal(runId: string, deps: ResumeReleaseDeps,
   }
   // 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`);
+    throw new Error(`${branch} tip ${to} does not descend from the recorded release commit ${recorded} — refusing to resume; remedy: inspect both commits and create a new release run from the intended pinned tip`);
   }
   // 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.
@@ -174,6 +178,110 @@ function verifyResumeRecipePin(commandRoot: string, snapshot: GraphRunState['gra
   }
 }
 
+/** Common read-only gate for dry-run and actual resume. Every rejection includes an operator action. */
+function verifyResumePreflight(run: GraphRunState, opts: ResumeReleaseOptions, deps: ResumeReleaseDeps,
+  version: string, recordedCommit: string, currentTip: string, commandRoot: string): void {
+  let trafficFile = deps.trafficFile;
+  if (trafficFile === undefined) {
+    try { trafficFile = trafficOptionsFromConfig(process.env, releaseLoopConfig()).trafficFile; }
+    catch (error) { throw new Error(`cannot read release traffic configuration — remedy: repair release.loop.trafficFile in the active config before resuming`, { cause: error }); }
+  }
+  if (!trafficFile) throw new Error('release.loop.trafficFile is not configured — remedy: set release.loop.trafficFile or ELANOUS_RELEASE_TRAFFIC_FILE before resuming');
+  let fd: number | undefined;
+  try {
+    const path = resolve(trafficFile);
+    const info = statSync(path);
+    if (!info.isFile() || (info.mode & 0o222) === 0) throw new Error('not a writable regular file');
+    fd = openSync(path, constants.O_WRONLY);
+    if (!fstatSync(fd).isFile()) throw new Error('not a regular file');
+    accessSync(path, constants.R_OK | constants.W_OK);
+  } catch (error) {
+    throw new Error(`release traffic file is missing or not writable: ${trafficFile} (${error instanceof Error ? error.message : String(error)}) — remedy: create a regular writable traffic file and set release.loop.trafficFile`, { cause: error });
+  } finally { if (fd !== undefined) closeSync(fd); }
+
+  for (const path of [join(commandRoot, 'node_modules'), join(commandRoot, 'apps', 'pwa', 'node_modules')]) {
+    try { if (!statSync(path).isDirectory()) throw new Error('not a directory'); }
+    catch (error) { throw new Error(`release resume dependencies missing: ${path} — remedy: run bun install --frozen-lockfile at repository root and apps/pwa`, { cause: error }); }
+  }
+
+  const nodeOutput = (nodeId: string): Record<string, unknown> | undefined => {
+    const node = run.nodes.find((entry) => entry.nodeId === nodeId);
+    if (!node?.ok || typeof node.output !== 'string') return undefined;
+    try { return lastJsonObject(node.output) as Record<string, unknown> | undefined; } catch { return undefined; }
+  };
+  const recordedNodeOutput = (nodeId: string): Record<string, unknown> | undefined => {
+    const node = run.nodes.find((entry) => entry.nodeId === nodeId);
+    if (typeof node?.output !== 'string') return undefined;
+    try { return lastJsonObject(node.output) as Record<string, unknown> | undefined; } catch { return undefined; }
+  };
+  const roots = [...new Set([deps.root ?? effectiveInstanceRoot(), deps.ledgerRoot ?? releaseLedgerRoot()])];
+  for (const root of roots) {
+    const prepared = join(root, 'release', version, 'prepared');
+    if (existsSync(prepared)) {
+      const record = nodeOutput('prepare');
+      const output = record && typeof record.out === 'string' ? record : undefined;
+      const manifestPath = join(prepared, 'release.json');
+      let manifest: { version?: unknown; sourceCommit?: unknown } | undefined;
+      try { manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as typeof manifest; } catch { /* fail closed below */ }
+      const ownerPath = join(prepared, '.release-node-owner.json');
+      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 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`);
+      }
+    }
+
+    const receiptPath = join(root, 'release', version, 'docs-branch-owner.json');
+    const docsBranch = `release-docs/${version}`;
+    let receipt: { owner?: { runId?: unknown; attempt?: unknown }; branch?: unknown; worktree?: unknown; outcome?: unknown; head?: unknown } | undefined;
+    try { receipt = JSON.parse(readFileSync(receiptPath, 'utf8')) as typeof receipt; } catch { /* no/invalid receipt is rejected if an artifact exists */ }
+    const docsRecord = recordedNodeOutput('docs');
+    const worktree = typeof docsRecord?.worktree === 'string' ? docsRecord.worktree : undefined;
+    let localBranch: string | undefined;
+    try { localBranch = (deps.git ?? gitRunner(deps.repo ?? process.cwd()))(['show-ref', '--verify', '--hash', `refs/heads/${docsBranch}`]).trim(); } catch { /* absent */ }
+    let docsWorktrees: string[] = [];
+    try {
+      const listing = (deps.git ?? gitRunner(deps.repo ?? process.cwd()))(['worktree', 'list', '--porcelain']);
+      docsWorktrees = listing.split(/\n\n+/).filter(Boolean).flatMap((entry) => {
+        const branch = /^branch (.+)$/m.exec(entry)?.[1];
+        const path = /^worktree (.+)$/m.exec(entry)?.[1];
+        return branch === `refs/heads/${docsBranch}` && path ? [path] : [];
+      });
+    } catch (error) {
+      throw new Error(`cannot inspect release worktrees for ${docsBranch} — remedy: restore read-only git access and retry resume`, { cause: error });
+    }
+    let remoteHead: string | undefined;
+    try {
+      const response = (deps.git ?? gitRunner(deps.repo ?? process.cwd()))(['ls-remote', '--heads', 'origin', `refs/heads/${docsBranch}`]);
+      const line = response.split(/\r?\n/).find((candidate) => candidate.trim().endsWith(`refs/heads/${docsBranch}`));
+      remoteHead = line?.trim().split(/\s+/)[0];
+    } catch (error) {
+      throw new Error(`cannot inspect docs branch ${docsBranch} — remedy: restore read-only git access and retry resume`, { cause: error });
+    }
+    const hasDocsArtifact = existsSync(receiptPath) || !!localBranch || !!remoteHead || docsWorktrees.length > 0;
+    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);
+    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`);
+    }
+    if (receipt?.outcome === 'pushed' && (!/^[0-9a-f]{40}$/i.test(String(receipt.head ?? ''))
+      || remoteHead?.toLowerCase() !== String(receipt.head).toLowerCase())) {
+      throw new Error(`docs branch tip differs from the saved ownership receipt: ${docsBranch} — remedy: preserve the branch and worktree, compare the remote tip with ${receiptPath} and the saved docs node output, then resolve ownership before resume`);
+    }
+  }
+
+  const recorded = nodeOutput('version-release');
+  if (recorded?.branch !== `release/${version}` || recorded.commit !== recordedCommit || !/^[0-9a-f]{40}$/i.test(currentTip)) {
+    throw new Error(`release branch tip does not match the saved version-release ledger for ${version} — remedy: inspect the branch and saved run ${opts.runId}, then resume from a node before gate only after resolving the mismatch`);
+  }
+}
+
 /** GATE-PARTIAL outcome of a resume — applied (plan written) or the reason it fell back to a full gate. `auto` marks the
  *  default plan of `--from gate` (GATE-REUSE-BY-DIFF); `closure` is set when code changes were followed. */
 export type PartialOutcome = { requested: false }
@@ -355,6 +463,7 @@ async function planResumeReleaseRunLocked(opts: ResumeReleaseOptions, deps: Resu
   const tip = refreshReleaseBranchTipInternal(opts.runId, deps, opts.from, waiverCommit, true);
   verifyResumeRecipePin(opts.commandRoot ?? process.cwd(), savedRun.graphSnapshot, tip.version);
   const commandRoot = verifyReleaseCommandRoot(opts.commandRoot ?? process.cwd(), tip.to, deps.git);
+  verifyResumePreflight(savedRun, opts, deps, tip.version, tip.from, tip.to, commandRoot);
   const partial = preparePartial(tip, opts, deps, true);
   const fromIndex = savedRun.path.indexOf(opts.from);
   const gateIndex = savedRun.path.indexOf('gate');
@@ -410,6 +519,7 @@ async function resumeReleaseRunLocked(opts: ResumeReleaseOptions, deps: ResumeRe
   const previewTip = refreshReleaseBranchTipInternal(opts.runId, deps, opts.from, waiverCommit, true);
   verifyResumeRecipePin(opts.commandRoot ?? process.cwd(), savedRun.graphSnapshot, previewTip.version);
   const commandRoot = verifyReleaseCommandRoot(opts.commandRoot ?? process.cwd(), previewTip.to, deps.git);
+  verifyResumePreflight(savedRun, opts, deps, previewTip.version, previewTip.from, previewTip.to, commandRoot);
   const tip = refreshReleaseBranchTipInternal(opts.runId, deps, opts.from, waiverCommit, false, previewTip.to);
   const partial = preparePartial(tip, opts, deps);
   // A failed preflight does not consume an observed release resume attempt.

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

@@ -0,0 +1,10 @@
+// Resume tests need the same writable traffic-file prerequisite as the installed release configuration.
+// This module is imported only by test files; the gate process owns and discards this environment.
+import { rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const trafficFile = join(tmpdir(), `elanous-resume-test-traffic-${process.pid}.json`);
+writeFileSync(trafficFile, '{}\n');
+process.env.ELANOUS_RELEASE_TRAFFIC_FILE = trafficFile;
+process.once('exit', () => rmSync(trafficFile, { force: true }));