@moretea-labs/forge 1.7.2 → 1.8.1

package/src/runtime/recovery/quarantine-retention.ts

@@ -0,0 +1,256 @@
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, renameSync, rmSync } from 'fs';
+import { basename, dirname, join } from 'path';
+import { repositoryControllerRoot } from '../../cli/repositories/controller-home';
+import { assertStorageHeadroom } from '../shared/storage-capacity';
+import { measureReclaimablePath } from '../control-plane/lifecycle-retention-metrics';
+
+export const RUNTIME_QUARANTINE_RETENTION_POLICY_VERSION = 'runtime-quarantine-retention-v1';
+export const DEFAULT_RUNTIME_QUARANTINE_RETENTION_MS = 30 * 24 * 60 * 60_000;
+export const DEFAULT_RUNTIME_QUARANTINE_MAX_ENTRIES = 200;
+export const DEFAULT_RUNTIME_QUARANTINE_MAX_BYTES = 256 * 1024 * 1024;
+const DEFAULT_RUNTIME_QUARANTINE_SCAN_BUDGET = 1_000;
+const DEFAULT_RUNTIME_QUARANTINE_REMOVAL_BUDGET = 50;
+
+export interface RuntimeQuarantineRetentionOptions {
+  nowMs?: number;
+  retentionMs?: number;
+  maxRetainedEntries?: number;
+  maxRetainedBytes?: number;
+  maxEntries?: number;
+  maxRemovals?: number;
+  /** Additional Controller-Home quarantine namespaces sharing this GC budget. */
+  additionalRoots?: readonly string[];
+}
+
+export interface RuntimeQuarantineRetentionReport {
+  schemaVersion: 1;
+  policyVersion: typeof RUNTIME_QUARANTINE_RETENTION_POLICY_VERSION;
+  root: string;
+  roots: string[];
+  inspected: number;
+  migratedLegacyCount: number;
+  eligible: number;
+  removedCount: number;
+  reclaimedBytes: number;
+  unknownReclaimedByteCount: number;
+  retained: number;
+  protectedActiveCount: 0;
+  blockerReasons: Record<string, number>;
+  errors: string[];
+  budgetExhausted: boolean;
+}
+
+export function runtimeQuarantineRoot(controllerHome: string, repoId: string): string {
+  return join(repositoryControllerRoot(controllerHome, repoId), 'quarantine', 'local-jobs');
+}
+
+export function runtimeLegacyCheckQuarantineRoot(controllerHome: string, repoId: string): string {
+  return join(repositoryControllerRoot(controllerHome, repoId), 'quarantine', 'legacy-checks');
+}
+
+export function runtimeQuarantinePath(controllerHome: string, repoId: string, id: string, at = new Date()): string {
+  const safeId = id.replace(/[^A-Za-z0-9_.-]/g, '_').slice(0, 120) || 'unknown';
+  const stamp = at.toISOString().replace(/[:.]/g, '-');
+  return join(runtimeQuarantineRoot(controllerHome, repoId), `${stamp}-${safeId}`);
+}
+
+function legacyQuarantineRoots(repoRoot: string): string[] {
+  return [
+    join(repoRoot, '.ai', 'harness', 'local-jobs-quarantine'),
+    join(repoRoot, '.ai', 'harness', 'quarantine', 'local-jobs'),
+  ];
+}
+
+function nextAvailablePath(root: string, name: string): string {
+  const base = join(root, name);
+  if (!existsSync(base)) return base;
+  for (let index = 1; index <= 1_000; index += 1) {
+    const candidate = join(root, `${name}-${index}`);
+    if (!existsSync(candidate)) return candidate;
+  }
+  throw new Error(`RUNTIME_QUARANTINE_DESTINATION_EXHAUSTED: ${name}`);
+}
+
+function movePreservingEvidence(source: string, destination: string): void {
+  mkdirSync(dirname(destination), { recursive: true, mode: 0o700 });
+  try {
+    renameSync(source, destination);
+    return;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EXDEV') throw error;
+  }
+  const measurement = measureReclaimablePath(source);
+  assertStorageHeadroom(destination, {
+    operation: 'runtime_quarantine_cross_device_relocation',
+    requiredBytes: measurement.complete ? measurement.bytes : undefined,
+    reserveBytes: 16 * 1024 * 1024,
+  });
+  cpSync(source, destination, {
+    recursive: true,
+    dereference: false,
+    preserveTimestamps: true,
+    force: false,
+    errorOnExist: true,
+  });
+  rmSync(source, { recursive: true, force: true });
+}
+
+
+export function quarantineRuntimePath(controllerHome: string, repoId: string, source: string, id: string): string {
+  const root = runtimeQuarantineRoot(controllerHome, repoId);
+  const proposed = runtimeQuarantinePath(controllerHome, repoId, id);
+  const destination = nextAvailablePath(root, basename(proposed));
+  movePreservingEvidence(source, destination);
+  return destination;
+}
+
+function removeEmptyLegacyRoot(root: string): void {
+  if (!existsSync(root)) return;
+  try {
+    if (readdirSync(root).length === 0) rmSync(root, { recursive: true, force: true });
+  } catch {
+    // A concurrent writer or unreadable legacy directory is preserved fail-closed.
+  }
+}
+
+export function cleanupRuntimeQuarantine(
+  controllerHome: string,
+  repoId: string,
+  repoRoot: string,
+  options: RuntimeQuarantineRetentionOptions = {},
+): RuntimeQuarantineRetentionReport {
+  const nowMs = options.nowMs ?? Date.now();
+  const retentionMs = Math.max(60_000, Math.floor(options.retentionMs ?? DEFAULT_RUNTIME_QUARANTINE_RETENTION_MS));
+  const maxRetainedEntries = Math.max(1, Math.floor(options.maxRetainedEntries ?? DEFAULT_RUNTIME_QUARANTINE_MAX_ENTRIES));
+  const maxRetainedBytes = Math.max(1, Math.floor(options.maxRetainedBytes ?? DEFAULT_RUNTIME_QUARANTINE_MAX_BYTES));
+  const maxEntries = Math.max(1, Math.floor(options.maxEntries ?? DEFAULT_RUNTIME_QUARANTINE_SCAN_BUDGET));
+  let remainingRemovals = Math.max(1, Math.floor(options.maxRemovals ?? DEFAULT_RUNTIME_QUARANTINE_REMOVAL_BUDGET));
+  const root = runtimeQuarantineRoot(controllerHome, repoId);
+  const roots = [...new Set([root, ...(options.additionalRoots ?? [])])];
+  const report: RuntimeQuarantineRetentionReport = {
+    schemaVersion: 1,
+    policyVersion: RUNTIME_QUARANTINE_RETENTION_POLICY_VERSION,
+    root,
+    roots,
+    inspected: 0,
+    migratedLegacyCount: 0,
+    eligible: 0,
+    removedCount: 0,
+    reclaimedBytes: 0,
+    unknownReclaimedByteCount: 0,
+    retained: 0,
+    protectedActiveCount: 0,
+    blockerReasons: {},
+    errors: [],
+    budgetExhausted: false,
+  };
+  const block = (reason: string): void => { report.blockerReasons[reason] = (report.blockerReasons[reason] ?? 0) + 1; };
+  mkdirSync(root, { recursive: true, mode: 0o700 });
+
+  let migrationBudget = maxEntries;
+  for (const legacyRoot of legacyQuarantineRoots(repoRoot)) {
+    if (!existsSync(legacyRoot)) continue;
+    try {
+      const legacyStat = lstatSync(legacyRoot);
+      if (!legacyStat.isDirectory() || legacyStat.isSymbolicLink()) {
+        if (migrationBudget <= 0) {
+          report.budgetExhausted = true;
+          block('legacy_migration_scan_budget_exhausted');
+          continue;
+        }
+        migrationBudget -= 1;
+        movePreservingEvidence(legacyRoot, nextAvailablePath(root, `legacy-root-${basename(legacyRoot)}`));
+        report.migratedLegacyCount += 1;
+        continue;
+      }
+    } catch (error) {
+      report.errors.push(`legacy quarantine inspect ${legacyRoot}: ${error instanceof Error ? error.message : String(error)}`);
+      continue;
+    }
+    let entries;
+    try {
+      entries = readdirSync(legacyRoot, { withFileTypes: true });
+    } catch (error) {
+      report.errors.push(`legacy quarantine read ${legacyRoot}: ${error instanceof Error ? error.message : String(error)}`);
+      continue;
+    }
+    for (const entry of entries) {
+      if (migrationBudget <= 0) {
+        report.budgetExhausted = true;
+        block('legacy_migration_scan_budget_exhausted');
+        break;
+      }
+      migrationBudget -= 1;
+      const source = join(legacyRoot, entry.name);
+      try {
+        movePreservingEvidence(source, nextAvailablePath(root, `legacy-${entry.name}`));
+        report.migratedLegacyCount += 1;
+      } catch (error) {
+        report.errors.push(`legacy quarantine migrate ${source}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    removeEmptyLegacyRoot(legacyRoot);
+  }
+
+  const entries: Array<{ name: string; path: string; mtimeMs: number }> = [];
+  for (const currentRoot of roots) {
+    if (currentRoot !== root && !existsSync(currentRoot)) continue;
+    try {
+      for (const entry of readdirSync(currentRoot, { withFileTypes: true })) {
+        const path = join(currentRoot, entry.name);
+        let mtimeMs = nowMs;
+        try { mtimeMs = lstatSync(path).mtimeMs; } catch { /* concurrent removal is handled during the scan */ }
+        entries.push({ name: `${basename(currentRoot)}:${entry.name}`, path, mtimeMs });
+      }
+    } catch (error) {
+      report.errors.push(`quarantine root read ${currentRoot}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  entries.sort((left, right) => right.mtimeMs - left.mtimeMs || left.name.localeCompare(right.name));
+
+  let retainedBytes = 0;
+  const scanned = entries.slice(0, maxEntries);
+  if (entries.length > scanned.length) {
+    report.budgetExhausted = true;
+    block('scan_budget_exhausted');
+  }
+  for (let index = 0; index < scanned.length; index += 1) {
+    const entry = scanned[index];
+    report.inspected += 1;
+    let stat;
+    try {
+      stat = lstatSync(entry.path);
+    } catch {
+      block('entry_disappeared');
+      continue;
+    }
+    const measurement = measureReclaimablePath(entry.path);
+    const expired = nowMs - stat.mtimeMs > retentionMs;
+    const overCount = index >= maxRetainedEntries;
+    const overBytes = measurement.complete && retainedBytes + measurement.bytes > maxRetainedBytes;
+    const eligible = expired || overCount || overBytes;
+    if (!eligible) {
+      report.retained += 1;
+      if (measurement.complete) retainedBytes += measurement.bytes;
+      else block('retained_size_unknown');
+      continue;
+    }
+    report.eligible += 1;
+    if (remainingRemovals <= 0) {
+      report.budgetExhausted = true;
+      block('removal_budget_exhausted');
+      report.retained += 1;
+      continue;
+    }
+    try {
+      remainingRemovals -= 1;
+      rmSync(entry.path, { recursive: true, force: true });
+      report.removedCount += 1;
+      if (measurement.complete) report.reclaimedBytes += measurement.bytes;
+      else report.unknownReclaimedByteCount += 1;
+    } catch (error) {
+      report.errors.push(`quarantine remove ${entry.name}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return report;
+}

package/src/runtime/recovery/store.ts

@@ -1,35 +1,53 @@
 import { mkdirSync, readdirSync } from 'fs';
 import { join } from 'path';
-import { repositoryControllerRoot } from '../../cli/repositories/controller-home';
+import { controllerSystemRoot, repositoryControllerRoot } from '../../cli/repositories/controller-home';
 import { readJsonFile, sanitizeFileComponent, writeJsonAtomic } from '../shared/json-files';
 import type { RecoveryAuditRecord } from './types';
 
-function recoveryRoot(controllerHome: string, repoId: string): string {
+function repositoryRecoveryRoot(controllerHome: string, repoId: string): string {
   const root = join(repositoryControllerRoot(controllerHome, repoId), 'recovery');
   mkdirSync(root, { recursive: true });
   return root;
 }
 
-function auditRoot(controllerHome: string, repoId: string): string {
-  const root = join(recoveryRoot(controllerHome, repoId), 'audit');
+function instanceRecoveryRoot(controllerHome: string): string {
+  const root = join(controllerSystemRoot(controllerHome), 'recovery');
   mkdirSync(root, { recursive: true });
   return root;
 }
 
-export function writeRecoveryAuditRecord(controllerHome: string, repoId: string, record: RecoveryAuditRecord): RecoveryAuditRecord {
-  writeJsonAtomic(join(auditRoot(controllerHome, repoId), `${sanitizeFileComponent(record.id)}.json`), record);
-  return record;
+function auditRoot(root: string): string {
+  const value = join(root, 'audit');
+  mkdirSync(value, { recursive: true });
+  return value;
 }
 
-export function listRecoveryAuditRecords(controllerHome: string, repoId: string, limit = 20): RecoveryAuditRecord[] {
-  const root = auditRoot(controllerHome, repoId);
-  return readdirSync(root)
+function listAuditRecords(root: string, limit: number): RecoveryAuditRecord[] {
+  return readdirSync(auditRoot(root))
     .filter((name) => name.endsWith('.json'))
     .sort()
     .reverse()
     .slice(0, Math.max(1, Math.min(Math.trunc(limit), 100)))
     .flatMap((name) => {
-      try { return [readJsonFile<RecoveryAuditRecord>(join(root, name))]; }
+      try { return [readJsonFile<RecoveryAuditRecord>(join(auditRoot(root), name))]; }
       catch { return []; }
     });
 }
+
+export function writeRecoveryAuditRecord(controllerHome: string, repoId: string, record: RecoveryAuditRecord): RecoveryAuditRecord {
+  writeJsonAtomic(join(auditRoot(repositoryRecoveryRoot(controllerHome, repoId)), `${sanitizeFileComponent(record.id)}.json`), record);
+  return record;
+}
+
+export function listRecoveryAuditRecords(controllerHome: string, repoId: string, limit = 20): RecoveryAuditRecord[] {
+  return listAuditRecords(repositoryRecoveryRoot(controllerHome, repoId), limit);
+}
+
+export function writeInstanceRecoveryAuditRecord(controllerHome: string, record: RecoveryAuditRecord): RecoveryAuditRecord {
+  writeJsonAtomic(join(auditRoot(instanceRecoveryRoot(controllerHome)), `${sanitizeFileComponent(record.id)}.json`), record);
+  return record;
+}
+
+export function listInstanceRecoveryAuditRecords(controllerHome: string, limit = 20): RecoveryAuditRecord[] {
+  return listAuditRecords(instanceRecoveryRoot(controllerHome), limit);
+}

package/src/runtime/release/identity.ts

@@ -8,6 +8,7 @@ export interface ReleaseIdentityBinding {
   releaseId?: string;
   releaseRevision?: string;
   sourceCommit?: string;
+  sourceRepositoryId?: string;
   cleanWorkspace: boolean;
 }
 
@@ -15,6 +16,7 @@ interface ReleaseManifestIdentity {
   releaseId?: string;
   releaseRevision?: string;
   sourceCommit?: string;
+  sourceRepositoryId?: string;
   cleanWorkspace?: boolean;
 }
 
@@ -31,6 +33,7 @@ function readManifest(releasePath: string): ReleaseManifestIdentity | undefined
       releaseId: text(manifest.releaseId),
       releaseRevision: text(manifest.releaseRevision),
       sourceCommit: text(manifest.sourceCommit),
+      sourceRepositoryId: text(manifest.sourceRepositoryId),
       cleanWorkspace: typeof manifest.cleanWorkspace === 'boolean' ? manifest.cleanWorkspace : undefined,
     };
   } catch {
@@ -48,6 +51,7 @@ export function readReleaseIdentityBindingFromEnv(env: NodeJS.ProcessEnv = proce
     releaseId: env.FORGE_RELEASE_ID?.trim() || manifest?.releaseId,
     releaseRevision: env.FORGE_RELEASE_REVISION?.trim() || manifest?.releaseRevision || env.FORGE_RELEASE_ID?.trim(),
     sourceCommit: env.FORGE_RELEASE_SOURCE_COMMIT?.trim() || manifest?.sourceCommit,
+    sourceRepositoryId: manifest?.sourceRepositoryId,
     cleanWorkspace: env.FORGE_RELEASE_CLEAN_WORKSPACE
       ? env.FORGE_RELEASE_CLEAN_WORKSPACE !== 'false'
       : manifest?.cleanWorkspace !== false,
@@ -65,6 +69,7 @@ export function resolveManagedRuntimeSourceIdentity(options: {
   branch: null;
   commit?: string;
   releaseRevision?: string;
+  sourceRepositoryId?: string;
   defaultBranch: string;
   defaultBranchCommit?: string;
   dirty: boolean;
@@ -93,6 +98,7 @@ export function resolveManagedRuntimeSourceIdentity(options: {
     branch: null,
     commit: binding.sourceCommit,
     releaseRevision: binding.releaseRevision,
+    ...(binding.sourceRepositoryId ? { sourceRepositoryId: binding.sourceRepositoryId } : {}),
     defaultBranch: 'main',
     defaultBranchCommit: binding.sourceCommit,
     dirty: !binding.cleanWorkspace,

package/src/runtime/release/release-coordinator.ts

@@ -0,0 +1,296 @@
+import {
+  advanceReleaseSession,
+  listCompleteReleaseSessions,
+  readReleaseSession,
+  releaseSessionIsSoakingPredecessorOfStable,
+  releaseSessionIsTerminal,
+  type ReleaseSession,
+} from './release-session';
+
+export interface RuntimeReleaseContext {
+  controllerHome: string;
+}
+
+export type RuntimeReleaseRunBoundary =
+  | 'terminal'
+  | 'provider_boundary'
+  | 'provider_failure'
+  | 'advance_budget_exhausted';
+
+export interface RuntimeReleaseRunEvidence {
+  actions: RuntimeReleaseCoordinatorAction[];
+  boundary: RuntimeReleaseRunBoundary;
+}
+
+export interface RuntimeReleaseProgressResult {
+  ok: boolean;
+  attempted: boolean;
+  noOp?: boolean;
+  detail: string;
+  releaseSession?: ReleaseSession;
+  releaseRun?: RuntimeReleaseRunEvidence;
+}
+
+/**
+ * Port implemented by the standalone Recovery boundary. The release domain
+ * decides semantic progression; the provider executes the physical operation
+ * for the already-selected durable ReleaseSession phase.
+ */
+export interface RuntimeReleaseProvider<C extends RuntimeReleaseContext = RuntimeReleaseContext> {
+  prepare(config: C, requestId?: string): Promise<RuntimeReleaseProgressResult>;
+  verifyStatic(config: C, sessionId: string, requestId?: string): Promise<RuntimeReleaseProgressResult>;
+  verifyCandidate(config: C, sessionId: string, requestId?: string): Promise<RuntimeReleaseProgressResult>;
+  cutover(config: C, sessionId: string, requestId?: string): Promise<RuntimeReleaseProgressResult>;
+  promoteKnownGood(config: C, sessionId: string, requestId?: string): Promise<RuntimeReleaseProgressResult>;
+}
+
+export type RuntimeReleaseCoordinatorAction =
+  | 'prepare'
+  | 'verify_static'
+  | 'verify_candidate'
+  | 'mark_cutover_eligible'
+  | 'cutover'
+  | 'promote_known_good';
+
+export interface RuntimeReleaseCoordinatorDecision {
+  action: RuntimeReleaseCoordinatorAction;
+  session?: ReleaseSession;
+}
+
+export type RuntimeReleaseReconciliationReason =
+  | 'active_session'
+  | 'source_mismatch'
+  | 'source_not_configured'
+  | 'source_current'
+  | 'source_already_attempted';
+
+export interface RuntimeReleaseSourceState {
+  configured: boolean;
+  sourceRevision?: string;
+  activeSourceCommit?: string;
+}
+
+export type RuntimeReleaseSourceObserver = () => RuntimeReleaseSourceState;
+
+export interface RuntimeReleaseReconciliationDecision {
+  required: boolean;
+  reason: RuntimeReleaseReconciliationReason;
+  action?: RuntimeReleaseCoordinatorAction;
+  session?: ReleaseSession;
+}
+
+const MAX_AUTONOMOUS_RELEASE_ADVANCES = 8;
+
+function completeRuntimeReleaseSessions(controllerHome: string): ReleaseSession[] {
+  const inventory = listCompleteReleaseSessions(controllerHome);
+  if (inventory.invalidSessionFiles.length > 0) {
+    throw new Error(`RELEASE_SESSION_INVENTORY_INCOMPLETE: invalid=${inventory.invalidSessionFiles.join(',') || 'none'}`);
+  }
+  return inventory.sessions;
+}
+
+export function activeRuntimeReleaseSessions(controllerHome: string): ReleaseSession[] {
+  return completeRuntimeReleaseSessions(controllerHome)
+    .filter((session) => !releaseSessionIsTerminal(session));
+}
+
+function coordinatorSession(active: ReleaseSession[]): ReleaseSession | undefined {
+  if (active.length <= 1) return active[0];
+  if (active.length === 2) {
+    const successors = active.filter((successor) => active.some((predecessor) =>
+      predecessor.sessionId !== successor.sessionId
+      && predecessor.sourceRevision !== successor.sourceRevision
+      && releaseSessionIsSoakingPredecessorOfStable(predecessor, successor.stableRelease)));
+    if (successors.length === 1) return successors[0];
+  }
+  throw new Error(`RELEASE_SESSION_MULTIPLE_ACTIVE: ${active.map((session) => `${session.sessionId}:${session.phase}`).join(',')}`);
+}
+
+function runtimeReleaseActionForSession(session: ReleaseSession): RuntimeReleaseCoordinatorAction {
+  switch (session.phase) {
+    case 'source_frozen': return 'prepare';
+    case 'built': return 'verify_static';
+    case 'static_verified':
+    case 'candidate_booted': return 'verify_candidate';
+    case 'candidate_verified': return 'mark_cutover_eligible';
+    case 'cutover_eligible':
+    case 'cutover_attempting':
+    case 'cutover_committed': return 'cutover';
+    case 'soaking': return 'promote_known_good';
+    case 'known_good':
+    case 'rolled_back':
+    case 'failed':
+      throw new Error(`RELEASE_SESSION_TERMINAL_NOT_ACTIVE: ${session.sessionId}:${session.phase}`);
+  }
+}
+
+export function decideConfiguredRuntimeReleaseAction(controllerHome: string): RuntimeReleaseCoordinatorDecision {
+  const active = activeRuntimeReleaseSessions(controllerHome);
+  const session = coordinatorSession(active);
+  if (!session) return { action: 'prepare' };
+  return { action: runtimeReleaseActionForSession(session), session };
+}
+
+/**
+ * Decide whether the Recovery-hosted automatic trigger should invoke one
+ * ReleaseCoordinator step. ReleaseSession remains the only durable progression
+ * authority; source comparison merely decides whether an absent session should
+ * be created. Unknown active source identity fails closed rather than implying
+ * a source mismatch.
+ */
+export function decideConfiguredRuntimeReleaseReconciliation(
+  controllerHome: string,
+  observeSource: RuntimeReleaseSourceObserver,
+): RuntimeReleaseReconciliationDecision {
+  const sessions = completeRuntimeReleaseSessions(controllerHome);
+  const active = sessions.filter((session) => !releaseSessionIsTerminal(session));
+  const session = coordinatorSession(active);
+  if (session) {
+    return { required: true, reason: 'active_session', action: runtimeReleaseActionForSession(session), session };
+  }
+
+  // Source observation may spawn Git. Keep it lazy so an already-active
+  // ReleaseSession can progress entirely from its durable authority without
+  // periodic repository/process churn in the Recovery daemon.
+  const source = observeSource();
+  if (!source.configured) return { required: false, reason: 'source_not_configured' };
+  const sourceRevision = source.sourceRevision?.trim();
+  const activeSourceCommit = source.activeSourceCommit?.trim();
+  if (!sourceRevision) throw new Error('RELEASE_AUTOMATION_SOURCE_REVISION_UNKNOWN');
+  if (!activeSourceCommit) throw new Error('RELEASE_AUTOMATION_ACTIVE_SOURCE_COMMIT_UNKNOWN');
+  if (sourceRevision === activeSourceCommit) return { required: false, reason: 'source_current' };
+
+  // An autonomous release is one attempt per immutable source revision.
+  // A terminal ReleaseSession is durable evidence that this exact commit was
+  // already accepted, failed, or deliberately rolled back. Replaying it every
+  // watchdog interval would turn a safety failure into a release/fork storm.
+  // A human can still start an explicit release; automatic retry resumes when
+  // HEAD changes and therefore produces a new source revision.
+  const priorAttempt = sessions
+    .filter((candidate) => releaseSessionIsTerminal(candidate) && candidate.sourceRevision === sourceRevision)
+    .sort((left, right) => Date.parse(right.updatedAt) - Date.parse(left.updatedAt))[0];
+  if (priorAttempt) {
+    return { required: false, reason: 'source_already_attempted', session: priorAttempt };
+  }
+
+  return { required: true, reason: 'source_mismatch', action: 'prepare' };
+}
+
+function decisionFingerprint(decision: RuntimeReleaseCoordinatorDecision): string {
+  const session = decision.session;
+  return session
+    ? `${decision.action}:${session.sessionId}:${session.phase}:${session.revision}`
+    : `${decision.action}:none`;
+}
+
+export async function advanceConfiguredRuntimeReleaseStep<C extends RuntimeReleaseContext>(
+  config: C,
+  provider: RuntimeReleaseProvider<C>,
+  requestId?: string,
+): Promise<RuntimeReleaseProgressResult> {
+  const decision = decideConfiguredRuntimeReleaseAction(config.controllerHome);
+  const request = requestId?.trim();
+  switch (decision.action) {
+    case 'prepare':
+      return provider.prepare(config, request);
+    case 'verify_static':
+      return provider.verifyStatic(config, decision.session!.sessionId, request);
+    case 'verify_candidate':
+      return provider.verifyCandidate(config, decision.session!.sessionId, request);
+    case 'mark_cutover_eligible': {
+      const session = decision.session!;
+      const advanced = advanceReleaseSession({
+        controllerHome: config.controllerHome,
+        sessionId: session.sessionId,
+        expectedRevision: session.revision,
+        phase: 'cutover_eligible',
+      });
+      return {
+        ok: true,
+        attempted: false,
+        noOp: true,
+        detail: 'Durable Candidate B evidence already exists; advanced the same ReleaseSession to cutover_eligible without replaying canaries.',
+        releaseSession: advanced,
+      };
+    }
+    case 'cutover':
+      return provider.cutover(config, decision.session!.sessionId, request);
+    case 'promote_known_good':
+      return provider.promoteKnownGood(config, decision.session!.sessionId, request);
+  }
+}
+
+/**
+ * Stateless run-to-boundary normal-release engine. ReleaseSession remains the
+ * only durable progression authority: every iteration re-derives the next
+ * action from persisted state, and no coordinator-local checkpoint is created.
+ *
+ * One invocation drains immediately executable phases. It stops only when the
+ * session terminalizes, a provider reports failure, a provider deliberately
+ * makes no durable progress (a genuine wait/safety boundary), or the fixed
+ * advance budget is exhausted. The budget/no-progress fences make accidental
+ * in-process loops fail closed while preserving crash-safe retry semantics.
+ */
+export async function advanceConfiguredRuntimeRelease<C extends RuntimeReleaseContext>(
+  config: C,
+  provider: RuntimeReleaseProvider<C>,
+  requestId?: string,
+): Promise<RuntimeReleaseProgressResult> {
+  const actions: RuntimeReleaseCoordinatorAction[] = [];
+  let attempted = false;
+  let allNoOp = true;
+  let lastResult: RuntimeReleaseProgressResult | undefined;
+
+  for (let index = 0; index < MAX_AUTONOMOUS_RELEASE_ADVANCES; index += 1) {
+    const before = decideConfiguredRuntimeReleaseAction(config.controllerHome);
+    const beforeFingerprint = decisionFingerprint(before);
+    const result = await advanceConfiguredRuntimeReleaseStep(config, provider, requestId);
+    actions.push(before.action);
+    attempted ||= result.attempted;
+    allNoOp &&= result.noOp === true;
+    lastResult = result;
+
+    const observedSession = result.releaseSession
+      ?? (before.session ? readReleaseSession(config.controllerHome, before.session.sessionId) : undefined);
+
+    if (!result.ok) {
+      return {
+        ...result,
+        attempted,
+        ...(allNoOp ? { noOp: true } : { noOp: false }),
+        releaseSession: observedSession ?? result.releaseSession,
+        releaseRun: { actions, boundary: 'provider_failure' },
+      };
+    }
+
+    if (observedSession && releaseSessionIsTerminal(observedSession)) {
+      return {
+        ...result,
+        attempted,
+        ...(allNoOp ? { noOp: true } : { noOp: false }),
+        releaseSession: observedSession,
+        releaseRun: { actions, boundary: 'terminal' },
+      };
+    }
+
+    const after = decideConfiguredRuntimeReleaseAction(config.controllerHome);
+    if (decisionFingerprint(after) === beforeFingerprint) {
+      return {
+        ...result,
+        attempted,
+        ...(allNoOp ? { noOp: true } : { noOp: false }),
+        releaseSession: observedSession ?? result.releaseSession,
+        releaseRun: { actions, boundary: 'provider_boundary' },
+      };
+    }
+  }
+
+  return {
+    ok: false,
+    attempted,
+    ...(allNoOp ? { noOp: true } : { noOp: false }),
+    detail: `RELEASE_SESSION_AUTONOMOUS_ADVANCE_BUDGET_EXHAUSTED: ${MAX_AUTONOMOUS_RELEASE_ADVANCES} durable advances without reaching a boundary`,
+    releaseSession: lastResult?.releaseSession,
+    releaseRun: { actions, boundary: 'advance_budget_exhausted' },
+  };
+}