elanous 0.2.42 → 0.2.44

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

@@ -1,9 +1,9 @@
 #!/usr/bin/env bun
 import { spawn, spawnSync } from 'node:child_process';
-import { appendFileSync, chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { appendFileSync, chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { hostname, tmpdir } from 'node:os';
 import { createHash, randomUUID } from 'node:crypto';
-import { basename, dirname, join, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { debug, redactSecretText } from '../../src/debug/log.js';
 import { registerStandaloneLogSink } from '../../src/domains/standalone-log-sink.js';
 import { landingFreezeMessage, readLandingFreeze } from '../../src/release-loop/landing-freeze.js';
@@ -20,7 +20,8 @@ import { planGateRadiusShadow, shadowActual, writeGateRadiusShadow, type GateRad
 import { planHardRehearsalRadius, partialGateImagesMatch, preflightGateExecutionIdentity, preflightGateImageDigest } from './gate-radius-live';
 import { actualGatePodImageDigest, gateBaselineReceipt, gateEnvFingerprint, gateGraphPins, gateSourcePins, parseGatePodRuntimeIdentity,
   POD_SWEEP_INTEGRATION_ONLY } from './gate-baseline-receipt';
-import { gateImagePinPath, readGateImagePin, resolveGateImagePin, writeGateImagePin } from './gate-image-pin.js';
+import { gateImagePinPath, normalizeGateImageDigest, pinnedGateImageSync as buildPinnedGateImageSync, readGateImagePin,
+  readGateImagePinForRun, replaceGateImagePin, resolveGateImagePin, writeGateImagePin } from './gate-image-pin.js';
 import { gateReceiptRegistryPath, planGateTrainReceiptCarry } from './gate-train-receipts.js';
 import { gateEnvFingerprint as gateReceiptEnvFingerprint, gateLockfileHash } from '../../src/self-implement/gate-receipt-registry.js';
 import { SPAWN_SYNC_MAX_BUFFER } from '../../src/util/spawn-sync-output.js';
@@ -36,13 +37,15 @@ import { emitNodeResult, readGraphContext } from './node-verdict.js';
 import { isGateExecutor, type GateExecutor } from './gate-executor.js';
 import { runPodCommand, parsePodCpu, podCpuMillis, resolvePodCpu, podCommandImageFor, type RunPodCommandOptions, type PodCommandResult, type PodCpu } from '../../src/task-orchestrator/surfaces/pod-command-job.js';
 import { POD_BUN_CACHE_HOST_PATH, parseInstallSeconds, podBunCacheVolume } from '../../src/task-orchestrator/surfaces/pod-bun-cache.js';
-import { PodPoolScheduler, parsePodPool, checkPodPool, defaultRemoteRun, snapshotWarmPoolMembers, type PodPoolMember } from '../../src/task-orchestrator/surfaces/pod-pool.js';
+import { NODE_REGISTRY, PodPoolScheduler, parsePodPool, checkPodPool, defaultRemoteRun, snapshotWarmPoolMembers, syncPoolImages, type PodPoolMember } from '../../src/task-orchestrator/surfaces/pod-pool.js';
 import { POD_INSTALL_SLOTS_DEFAULT, POD_INSTALL_SLOTS_HOST_PATH, installSlotScript } from '../../src/task-orchestrator/surfaces/pod-install-slots.js';
 import { gateDepsInstallScript, parseGateDeps } from '../../src/task-orchestrator/surfaces/pod-gate-deps.js';
 import { warmReferenceFromJobArtifacts, writeWarmJobManifest } from './gate-warm-artifacts.js';
 import { assessWarmWorkerShadow, parseWarmWorkerReply, type WarmWorkerCommand, type WarmWorkerFileResult, type WarmWorkerKey } from '../../src/task-orchestrator/surfaces/pod-warm-worker-protocol.js';
 import type { WarmPodTransportResult } from '../../src/task-orchestrator/surfaces/pod-warm-worker-pod.js';
-import { requestWarmPodReplay, finalizeWarmPodReplay, quarantineWarmPodReplay, type WarmReplayResult } from '../../src/task-orchestrator/surfaces/pod-warm-worker-provider.js';
+import { configureWarmPodProvider, loadWarmPodProvider, requestWarmPodReplay, finalizeWarmPodReplay, quarantineWarmPodReplay, type WarmReplayInput, type WarmReplayResult } from '../../src/task-orchestrator/surfaces/pod-warm-worker-provider.js';
+import { DEFAULT_CONTROL_PORT } from '../../src/control-plane/server.js';
+import { createRunScopedWarmControlForward, startWarmControlPortForward } from './warm-control-forward.js';
 import { resolveWarmPoolProfile } from '../../src/self-implement/pod-warm-pool-profile.js';
 import { decideWarmReuse, type WarmReuseSwitchConfig, type WarmReuseEvidence } from '../../src/task-orchestrator/surfaces/pod-warm-switch.js';
 import { getUserConfig } from '../../src/user-config.js';
@@ -52,7 +55,7 @@ import { markGateShardUnmeasured, nextGateShardAttempt, readGateShardManifest, r
 import { planGateShardDispatch, summarizeGateProgress, type GateProgressGroup, type GateShardReceipt } from './gate-shard-dispatch.js';
 import { defaultKubectl } from '../../src/task-orchestrator/surfaces/self-implement-pod.js';
 import { executeTuiNodeCheck, type ExecutedTuiCheck } from './tui-node-checks.js';
-import { runWithReleaseGateTraffic } from './gate-traffic-mode.js';
+import { runWithReleaseGateTraffic, runWithReleasePwaTraffic } from './gate-traffic-mode.js';
 import { emitPodLifecycle, gatePodLifecycleEvent, gatePodOutcome } from '../../src/task-orchestrator/surfaces/pod-lifecycle-stages.js';
 import { gateHostReservationRoot, reserveReleaseGateHosts } from '../../src/release-loop/gate-host-reservation.js';
 import { normRoot } from '../../src/instance/resolve.js';
@@ -111,6 +114,8 @@ function redactedGateLogTail(input: string): string {
  * Every field falls back to the real tool, so an absent seam is today's behaviour byte for byte.
  */
 export interface GateTools {
+  /** Graph run identity passed to pool admission for shadow observations. */
+  graphRunId?: string | null;
   /** Wall clock the gate measures with; absent = `Date.now`. */
   now?: () => number;
   /** The Pod Job runner (the fake Pod stage of a scenario); absent = the positional `podCommand`, else `runPodCommand`. */
@@ -227,6 +232,10 @@ export function reconcileStaleGateShardBoard(input: {
 }
 export interface GateOptions {
   commit: string;
+  /** Explicit pre-cut warm↔fresh comparison, persisted before the ordinary gate reads warmHistory. */
+  warmPrecutCanary?: { file: string };
+  /** RELEASE-POLICY-PACK — the gate Pod image is tied to this resolved cut commit. */
+  imagePin?: 'cut-commit';
   /** The graph run that launched this gate; direct hard rehearsal instead pins source bytes explicitly. */
   graphRunId?: string;
   /** Only a direct hard rehearsal may pin graph bytes from its measured Git commit. */
@@ -250,6 +259,7 @@ export interface GateOptions {
   recheckFileLimit?: number;
   /** freshShards — GATE-SHARD-RESUME off: every shard starts a Pod even when this logDir already holds its result. */
   pod?: { pool: string; shards?: number; shardTimeoutSeconds?: number; durationSource?: string; bunCache?: string; freshShards?: boolean;
+    imagePin?: 'cut-commit';
     /** One immutable container image identity for this gate graph run and all its resumes. */
     pinnedImageDigest?: string;
     pinnedRunId?: string;
@@ -335,14 +345,64 @@ export interface GateOptions {
 }
 
 /** Gate-profile opt-in wires the producer only for the process entry, never a test runner seam. */
-export function withWarmGateHooks(opts: GateOptions, config: unknown, injectedRunner = false): GateOptions {
+export function withWarmGateHooks(opts: GateOptions, config: unknown, injectedRunner = false,
+  onWarmCleanup?: (cleanup: () => Promise<void>) => void): GateOptions {
   if (injectedRunner || !opts.pod || resolveWarmPoolProfile(config) !== 'gate') return opts;
   const warmReuseConfig = config && typeof config === 'object' && 'pod' in config
     && config.pod && typeof config.pod === 'object' && 'warmReuse' in config.pod
     ? config.pod.warmReuse as WarmReuseSwitchConfig : undefined;
-  return { ...opts, pod: { ...opts.pod, warmReplay: requestWarmPodReplay,
+  const lifecycle = createRunScopedWarmControlForward(async () => {
+    const configPath = process.env.ELANOUS_WARM_POD_PROVIDER_CONFIG;
+    if (!configPath) throw new Error('warm provider config unavailable');
+    const target = warmProviderTarget(configPath);
+    const forward = await startWarmControlPortForward({ context: target.context, namespace: target.namespace,
+      service: 'elanous-control', remotePort: DEFAULT_CONTROL_PORT });
+    try {
+      const provider = loadWarmPodProvider(configPath, { runtimeOverrides: { controlUrl: forward.url } });
+      configureWarmPodProvider(provider);
+      return forward;
+    } catch (error) {
+      await forward.stop();
+      throw error;
+    }
+  });
+  const replay: NonNullable<GateOptions['pod']>['warmReplay'] = async (input) => {
+    try { await lifecycle.ensure(); }
+    catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      debug.log('pod.warm.control-forward', 'unavailable', { reason, fallback: 'fresh-job' }, { level: 'error' });
+      return { command: null, transport: { status: 'fallback', reason: 'control-unavailable', reply: null } };
+    }
+    return requestWarmPodReplay(input);
+  };
+  const cleanup = async () => {
+    try { await lifecycle.stop(); }
+    finally { configureWarmPodProvider(null); }
+  };
+  onWarmCleanup?.(cleanup);
+  return { ...opts, pod: { ...opts.pod, warmReplay: replay,
     warmFinalize: finalizeWarmPodReplay, warmQuarantine: quarantineWarmPodReplay, warmProducerEnabled: true, warmReuseConfig } };
 }
+
+function warmProviderTarget(path: string): { context: string; namespace: string } {
+  if (!isAbsolute(path) || (statSync(path).mode & 0o077) !== 0) throw new Error('warm provider config must be private');
+  const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'));
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) throw new Error('invalid warm provider config');
+  const data = parsed as { candidates?: Array<{ spec?: { kubectlContext?: string; namespace?: string } }>;
+    poolTemplates?: Array<{ spec?: { kubectlContext?: string; namespace?: string } }> };
+  const rows = [...(data.candidates ?? []), ...(data.poolTemplates ?? [])];
+  const targets = new Map<string, { context: string; namespace: string }>();
+  for (const row of rows) {
+    const context = row.spec?.kubectlContext;
+    const namespace = row.spec?.namespace;
+    if (typeof context !== 'string' || !context || typeof namespace !== 'string' || !namespace)
+      throw new Error('warm provider target is incomplete');
+    targets.set(`${context}/${namespace}`, { context, namespace });
+  }
+  if (targets.size !== 1) throw new Error('warm control forward requires one cluster and namespace per gate run');
+  return [...targets.values()][0]!;
+}
+
 export interface GateResult {
   outcome: 'ok' | 'regression' | 'error';
   commit: string;
@@ -409,29 +469,151 @@ const WARM_REPLAY_BUDGET = 3;
 interface WarmVerdictSample { version: string; commit: string; baselineCommit: string; warmShadow: WarmShadowObservation[] }
 const recordValue = (value: unknown): Record<string, unknown> | null =>
   value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : null;
+function validWarmShadowObservation(value: unknown): value is WarmShadowObservation {
+  const row = recordValue(value);
+  if (!row || !Array.isArray(row.files) || row.files.length !== 1 || typeof row.files[0] !== 'string'
+    || !/^(?:[\w.-]+\/)*[\w.-]+\.test\.[cm]?[jt]sx?$/.test(row.files[0])
+    || row.files[0].split('/').some((part) => part === '.' || part === '..')
+    || typeof row.attemptId !== 'string' || !row.attemptId || typeof row.reason !== 'string'
+    || !['observed', 'fallback', 'unmeasured'].includes(String(row.status))
+    || !['yes', 'no', 'failed', 'unavailable'].includes(String(row.quarantined))) return false;
+  if (row.finalized !== undefined && typeof row.finalized !== 'boolean') return false;
+  if (row.cutSha !== undefined && typeof row.cutSha !== 'string') return false;
+  if (row.baselineSha !== undefined && typeof row.baselineSha !== 'string') return false;
+  if (row.workerKey !== undefined) {
+    const key = recordValue(row.workerKey);
+    if (!key || typeof key.context !== 'string' || !key.context || typeof key.imageDigest !== 'string' || !key.imageDigest
+      || typeof key.lockHash !== 'string' || !key.lockHash || typeof key.architecture !== 'string' || !key.architecture) return false;
+  }
+  return true;
+}
+function validWarmVerdictSample(value: unknown): value is WarmVerdictSample {
+  const row = recordValue(value);
+  return !!row && typeof row.version === 'string' && typeof row.commit === 'string'
+    && typeof row.baselineCommit === 'string' && Array.isArray(row.warmShadow)
+    && row.warmShadow.every(validWarmShadowObservation);
+}
 /** The verdict is atomically replaced; carry a bounded prior-verdict window in that same SSOT. */
 function readWarmVerdictHistory(path: string): WarmVerdictSample[] | undefined {
   if (!existsSync(path)) return [];
   try {
     const current = recordValue(JSON.parse(readFileSync(path, 'utf8')));
     if (!current || !Array.isArray(current.warmHistory)) return undefined;
-    const history = [...current.warmHistory, { version: current.version, commit: current.commit,
-      baselineCommit: current.baselineCommit, warmShadow: current.warmShadow }].slice(-WARM_VERDICT_HISTORY_LIMIT);
-    if (history.some((entry) => { const row = recordValue(entry);
-      return !row || typeof row.version !== 'string' || typeof row.commit !== 'string'
-        || typeof row.baselineCommit !== 'string' || !Array.isArray(row.warmShadow); })) return undefined;
-    return history as WarmVerdictSample[];
+    if (current.warmHistory.some((entry) => !validWarmVerdictSample(entry))) return undefined;
+    const hasCurrentSample = ['version', 'commit', 'baselineCommit', 'warmShadow'].some((key) => key in current);
+    const history = [...current.warmHistory];
+    if (current.warmHistoryOnly !== true || hasCurrentSample) {
+      const currentSample = { version: current.version, commit: current.commit,
+        baselineCommit: current.baselineCommit, warmShadow: current.warmShadow };
+      if (!validWarmVerdictSample(currentSample)) return undefined;
+      if (current.warmHistoryOnly !== true) history.push(currentSample);
+    }
+    return history.slice(-WARM_VERDICT_HISTORY_LIMIT) as WarmVerdictSample[];
   } catch { return undefined; }
 }
+
+/** Append one actual pre-cut replay observation to the gate verdict's bounded history, preserving its gate result. */
+function recordWarmPrecutCanarySample(path: string, sample: WarmVerdictSample): void {
+  if (!sample.version || !/^[0-9a-f]{7,40}$/i.test(sample.commit) || !/^[0-9a-f]{7,40}$/i.test(sample.baselineCommit)
+    || !Array.isArray(sample.warmShadow) || sample.warmShadow.length !== 1 || !sample.warmShadow.every(validWarmShadowObservation))
+    throw new Error('invalid pre-cut canary sample');
+  let current: Record<string, unknown> = {};
+  if (existsSync(path)) {
+    let decoded: unknown;
+    try { decoded = JSON.parse(readFileSync(path, 'utf8')); }
+    catch (error) { throw new Error(`gate verdict JSON is malformed: ${String(error)}`); }
+    const parsed = recordValue(decoded);
+    if (!parsed) throw new Error('gate verdict is not an object');
+    current = parsed;
+    if (current.warmHistory !== undefined && !Array.isArray(current.warmHistory)) throw new Error('gate verdict warmHistory is invalid');
+  }
+  const storedHistory = Array.isArray(current.warmHistory) ? [...current.warmHistory] : [];
+  if (storedHistory.some((entry) => !validWarmVerdictSample(entry))) throw new Error('gate verdict warmHistory contains an invalid row');
+  const history = storedHistory;
+  const hasCurrentSample = ['version', 'commit', 'baselineCommit', 'warmShadow'].some((key) => key in current);
+  if (current.warmHistoryOnly === true && hasCurrentSample) {
+    const previous = { version: current.version, commit: current.commit, baselineCommit: current.baselineCommit, warmShadow: current.warmShadow };
+    if (!validWarmVerdictSample(previous)) throw new Error('gate verdict current warm sample is invalid');
+  } else if (current.warmHistoryOnly !== true) {
+    const previous = { version: current.version, commit: current.commit, baselineCommit: current.baselineCommit, warmShadow: current.warmShadow };
+    if (!validWarmVerdictSample(previous)) throw new Error('gate verdict current warm sample is invalid');
+    history.push(previous);
+  }
+  history.push(sample);
+  const body = JSON.stringify({ ...current, warmHistory: history.slice(-WARM_VERDICT_HISTORY_LIMIT), warmHistoryOnly: true }, null, 2) + '\n';
+  mkdirSync(dirname(path), { recursive: true });
+  const temp = join(dirname(path), `.gate-verdict-${process.pid}-${randomUUID()}.tmp`);
+  try { writeFileSync(temp, body, { mode: 0o600, flag: 'wx' }); chmodSync(temp, 0o600); renameSync(temp, path); }
+  finally { if (existsSync(temp)) rmSync(temp); }
+}
+
+/** Run a bounded set of real fresh-Job ↔ warm-worker comparisons before the release gate. */
+export async function runWarmPrecutCanary(input: { opts: GateOptions; runner: GateRunner; file: string;
+  config: unknown; historyPath: string; timeoutMs?: number }): Promise<{ samples: WarmShadowObservation[]; decision: ReturnType<typeof decideWarmReuse> }> {
+  const { opts, runner } = input;
+  if (!opts.pod || !runner.recheckPod || !opts.baselineCommit || !opts.pod.warmReplay || !opts.pod.warmFinalize || !opts.pod.warmQuarantine)
+    throw new Error('pre-cut canary requires a Pod pool, baseline commit, and warm worker hooks');
+  if (!/^(?:[\w.-]+\/)*[\w.-]+\.test\.[cm]?[jt]sx?$/.test(input.file)
+    || input.file.split('/').some((part) => part === '.' || part === '..')) throw new Error('pre-cut canary requires one repository test file');
+  if (readWarmVerdictHistory(input.historyPath) === undefined)
+    throw new Error('gate verdict contains malformed warm history or current sample; refusing canary without writing');
+  const samples = 2;
+  if (samples > WARM_REPLAY_BUDGET) throw new Error(`pre-cut canary sample count exceeds replay budget (${WARM_REPLAY_BUDGET})`);
+  const lock = await runner.localCommand('git', ['show', `${opts.commit}:bun.lock`], opts.repo ?? process.cwd());
+  if (lock.rc !== 0 || !lock.output) throw new Error('pre-cut canary cut lock is unmeasured');
+  if (!/^[0-9a-f]{40}$/i.test(opts.baselineCommit)) throw new Error('pre-cut canary baseline commit is invalid');
+  const baseline = await runner.localCommand('git', ['cat-file', '-e', `${opts.baselineCommit}^{commit}`], opts.repo ?? process.cwd());
+  if (baseline.rc !== 0) throw new Error(`pre-cut canary baseline commit is absent: ${opts.baselineCommit.slice(0, 12)}`);
+  const trackedFile = await runner.localCommand('git', ['cat-file', '-e', `${opts.commit}:${input.file}`], opts.repo ?? process.cwd());
+  if (trackedFile.rc !== 0) throw new Error(`pre-cut canary test file is absent from cut ${opts.commit.slice(0, 12)}`);
+  const lockHash = createHash('sha256').update(lock.output).digest('hex');
+  const pod = { ...opts.pod, warmProducerEnabled: false, warmCutSha: opts.commit, warmBaselineSha: opts.baselineCommit,
+    warmEligible: true, warmReplayOwner: true, warmShadowScope: { requested: false, attempts: 0 } };
+  const observations: WarmShadowObservation[] = [];
+  const attemptIds = new Set<string>();
+  for (let index = 0; index < samples; index++) {
+    let observation: WarmShadowObservation;
+    let failure: Error | undefined;
+    try {
+      const result = await runner.recheckPod(input.file, opts.commit, pod, input.timeoutMs ?? GATE_ISOLATED_TIMEOUT_MS);
+      observation = result.warmShadow ?? { files: [input.file], attemptId: `precut-unmeasured-${index + 1}-${randomUUID()}`,
+        status: 'unmeasured', reason: result.rc === 0 ? 'warm-shadow-missing' : `fresh-job-rc-${result.rc}`, quarantined: 'no' };
+      if (result.rc !== 0) { observation = { ...observation, status: 'unmeasured', reason: `fresh-job-rc-${result.rc}` };
+        failure = new Error(`pre-cut fresh Job failed on attempt ${index + 1}: rc=${result.rc}`); }
+      else if (observation.status !== 'observed' || !observation.workerKey
+        || observation.files.length !== 1 || observation.files[0] !== input.file
+        || observation.cutSha !== opts.commit || observation.baselineSha !== opts.baselineCommit
+        || observation.workerKey.lockHash !== lockHash || !['match', 'result'].includes(observation.reason)
+        || attemptIds.has(observation.attemptId)
+        || (observation.reason === 'match' && (observation.finalized !== true || observation.quarantined !== 'no'))) {
+        failure = new Error(`pre-cut warm comparison was not measured on attempt ${index + 1}: ${observation.reason}`);
+      }
+    } catch (error) {
+      observation = { files: [input.file], attemptId: `precut-error-${index + 1}-${randomUUID()}`,
+        status: 'unmeasured', reason: String(error), quarantined: 'unavailable' };
+      failure = error instanceof Error ? error : new Error(String(error));
+    }
+    attemptIds.add(observation.attemptId);
+    observations.push(observation);
+    recordWarmPrecutCanarySample(input.historyPath, { version: opts.version, commit: opts.commit,
+      baselineCommit: opts.baselineCommit, warmShadow: [observation] });
+    if (failure) throw failure;
+  }
+  const history = readWarmVerdictHistory(input.historyPath);
+  const evidence = warmEvidenceFromVerdicts(history, opts.version, opts.commit, opts.baselineCommit, lockHash);
+  const warmReuseConfig = (input.config && typeof input.config === 'object' && 'pod' in input.config
+    && recordValue((input.config as Record<string, unknown>).pod)?.warmReuse) as WarmReuseSwitchConfig | undefined;
+  return { samples: observations, decision: decideWarmReuse('gate-recheck', warmReuseConfig,
+    evidence ? { 'gate-recheck': evidence } : undefined) };
+}
 /** Every counted match has a measured, finalized worker with this exact cut, baseline and lock. */
 export function warmEvidenceFromVerdicts(history: readonly WarmVerdictSample[] | undefined,
   version: string, head: string, baseline: string, lock: string): WarmReuseEvidence | undefined {
   if (!history?.length || !lock) return undefined;
-  const rows = history.flatMap((verdict) => {
-    if (verdict.version !== version || verdict.commit !== head || verdict.baselineCommit !== baseline
-      || !Array.isArray(verdict.warmShadow)) return [null];
-    return verdict.warmShadow.length ? verdict.warmShadow : [null];
-  });
+  const matchingHistory = history.filter((verdict) => verdict.version === version && verdict.commit === head
+    && verdict.baselineCommit === baseline);
+  const rows = matchingHistory.flatMap((verdict) => verdict.warmShadow.length ? verdict.warmShadow : [null]);
+  if (!rows.length) return undefined;
   const attempts = new Set<string>();
   const key = rows.at(-1)?.workerKey;
   if (rows.some((entry) => {
@@ -1575,7 +1757,45 @@ export interface GateAdmission {
   acquire(signal: AbortSignal): Promise<() => void>;
   /** The pool-wide reading admission waits on (recommended · limitedBy · memorySlots); null before any reading. */
   waitReason(): string | null;
+  /** Optional deterministic-test observation override; production uses poolGateAdmission's unknown-only provider. */
+  priorityShadowObservation?(gateWaiting: boolean): GatePriorityShadowObservation;
+}
+
+export type GatePriorityImageState = 'verified' | 'mismatch' | 'unknown';
+export interface GatePriorityShadowObservation {
+  gateRunId: string | null;
+  host: string | null;
+  competingRunId: string | null;
+  competingHost: string | null;
+  gateImageState: GatePriorityImageState;
+  competingImageState: GatePriorityImageState;
+  gateWaiting: boolean;
+  lowerPriorityWaiting: boolean | null;
+}
+export interface GatePriorityShadowDecision extends GatePriorityShadowObservation {
+  event: 'gate-priority-shadow-decision';
+  decision: 'gate-first' | 'no-contention' | 'insufficient-evidence';
+  selectionRationale: string;
 }
+
+/** A shadow-only policy decision; it has no pool or Pod handle and cannot change runtime state. */
+export function gatePriorityShadowDecision(input: GatePriorityShadowObservation): GatePriorityShadowDecision {
+  const base = { event: 'gate-priority-shadow-decision' as const, ...input };
+  if (!input.gateWaiting || input.lowerPriorityWaiting === false) {
+    return { ...base, decision: 'no-contention', selectionRationale: !input.gateWaiting ? 'gate-not-waiting' : 'no-lower-priority-waiter-observed' };
+  }
+  if (input.lowerPriorityWaiting !== true) {
+    return { ...base, decision: 'insufficient-evidence', selectionRationale: 'lower-priority-wait-state-unknown' };
+  }
+  if (!input.gateRunId || !input.competingRunId || !input.host || input.host !== input.competingHost) {
+    return { ...base, decision: 'insufficient-evidence', selectionRationale: 'same-host-run-identities-unavailable' };
+  }
+  if (input.gateImageState !== 'verified' || input.competingImageState !== 'verified') {
+    return { ...base, decision: 'insufficient-evidence', selectionRationale: 'image-state-not-verified' };
+  }
+  return { ...base, decision: 'gate-first', selectionRationale: 'same-host-contention-and-verified-gate-image; gate-policy-priority' };
+}
+
 export const GATE_ADMISSION_WAIT_SECONDS_DEFAULT = 1800;
 /** Queue pressure scales the default wait but never creates an unbounded admission timer. */
 export function gateAdmissionWaitSeconds(shards: number, slots: number): number {
@@ -1625,17 +1845,38 @@ export function defaultGateMemberProbe(member: PodPoolMember, tools: GateTools =
   return !member.sshHost || (tools.remoteRun ?? defaultRemoteRun)(member.sshHost, 'true').status === 0;
 }
 
-export function poolGateAdmission(pool: PodPoolScheduler): GateAdmission {
-  return { acquire: (signal) => pool.acquireAdmission(signal, undefined, { gate: true }), waitReason: () => pool.waitReason() };
+export function poolGateAdmission(pool: PodPoolScheduler, gateRunId: string | null = null,
+  priorityShadowObservation?: (gateWaiting: boolean) => GatePriorityShadowObservation): GateAdmission {
+  const singleHost = pool.members.length === 1 ? (pool.members[0]!.sshHost ?? hostname()) : null;
+  // The optional provider is a deterministic test seam only. Production never fabricates a competitor or image fact.
+  return {
+    acquire: (signal) => pool.acquireAdmission(signal, undefined, { gate: true }),
+    waitReason: () => pool.waitReason(),
+    // At admission time a multi-host pool has not selected a host yet. Existing measurements do not expose
+    // competing run ids or image states, so keep those unknown rather than deriving them from Job names.
+    priorityShadowObservation: priorityShadowObservation ?? ((gateWaiting) => ({ gateRunId, host: singleHost, competingRunId: null, competingHost: null,
+      gateImageState: 'unknown', competingImageState: 'unknown', gateWaiting, lowerPriorityWaiting: null })),
+  };
 }
-export async function admitGateShard(admission: GateAdmission | undefined, o: { waitMs: number; onWait: (reason: string) => void; reasonPollMs?: number; firstReasonMs?: number }): Promise<GateAdmissionResult> {
+export async function admitGateShard(admission: GateAdmission | undefined, o: { waitMs: number; onWait: (reason: string) => void; reasonPollMs?: number; firstReasonMs?: number;
+  onPriorityShadow?: (decision: GatePriorityShadowDecision) => void }): Promise<GateAdmissionResult> {
   const noop = () => {};
   if (!admission || !(o.waitMs > 0)) return { outcome: 'off', waitedMs: 0, release: noop };
   const started = Date.now();
   const controller = new AbortController();
   let timedOut = false;
   let lastReason: string | undefined;
-  const tell = () => { lastReason = gateAdmissionWaitText(admission.waitReason()); o.onWait(lastReason); };
+  let priorityShadowLogged = false;
+  const tell = () => {
+    lastReason = gateAdmissionWaitText(admission.waitReason());
+    if (!priorityShadowLogged && admission.priorityShadowObservation) {
+      priorityShadowLogged = true;
+      const decision = gatePriorityShadowDecision(admission.priorityShadowObservation(true));
+      if (o.onPriorityShadow) o.onPriorityShadow(decision);
+      else debug.log('release-loop.gate', 'gate-priority-shadow-decision', decision);
+    }
+    o.onWait(lastReason);
+  };
   const deadline = setTimeout(() => { timedOut = true; controller.abort(); }, o.waitMs);
   // A grant inside the first moment never touches the shard row (no flapping in shards.json).
   let ticker: ReturnType<typeof setInterval> | undefined;
@@ -1678,6 +1919,27 @@ export function createGateRunner(repo: string, remote?: string, commandOverride?
   const ssh = tools.ssh ?? defaultSshCommand;
   const remoteRun = tools.remoteRun ?? defaultRemoteRun;
   const runPod = tools.podCommand ?? podCommand;
+  const pinnedGateImageSync = (pod: NonNullable<GateOptions['pod']>, commit: string): RunPodCommandOptions['syncImages'] | undefined => {
+    const hasDigest = Boolean(pod.pinnedImageDigest?.trim());
+    const hasRunId = Boolean(pod.pinnedRunId?.trim());
+    if (hasDigest !== hasRunId) throw new Error('gate pinned image: both pinnedImageDigest and pinnedRunId are required');
+    if (!hasDigest) return undefined;
+    return async (members, image, localCommit) => {
+      if (localCommit !== commit) throw new Error('gate pinned image: requested source commit changed');
+      const probe = preflightGateImageDigest;
+      const poolSpecFor = (member: PodPoolMember) => `${member.context}${member.sshHost ? `@${member.sshHost}` : ''}:${member.capacity}#${member.registry ?? NODE_REGISTRY}`;
+      const result = buildPinnedGateImageSync({ runId: pod.pinnedRunId!, commit, digest: pod.pinnedImageDigest!, image,
+        members: members.map((member) => ({ context: member.context, registry: member.registry ?? NODE_REGISTRY })),
+        probeTagDigest: (member) => {
+          const candidate = members.find((row) => row.context === member.context && (row.registry ?? NODE_REGISTRY) === member.registry);
+          return candidate ? probe(poolSpecFor(candidate), commit) : null;
+        } });
+      for (const drift of result.tagDrifts) debug.log('release-loop.gate', 'image-tag-drift', {
+        ...drift, action: 'skip-push-use-pinned-digest',
+      }, { level: 'warn' });
+      return result.images;
+    };
+  };
   // GATE-HOSTMIRROR-EXPLICIT: resolved once per runner and handed to every podCommand (shard · retry · recheck).
   let gateMirror: GateHostMirror | undefined;
   const gateHostMirror = (pod: NonNullable<GateOptions['pod']>): { hostMirror?: string } => {
@@ -1720,6 +1982,9 @@ export function createGateRunner(repo: string, remote?: string, commandOverride?
     if (!pod.pool || !Number.isSafeInteger(shardCount) || shardCount < 1
       || !Number.isSafeInteger(deadlineSeconds) || deadlineSeconds < 1
       || !Number.isSafeInteger(isolationConcurrency) || isolationConcurrency < 1) throw new Error('invalid pod sweep options');
+    const hasPinnedDigest = Boolean(pod.pinnedImageDigest?.trim());
+    const hasPinnedRunId = Boolean(pod.pinnedRunId?.trim());
+    if (hasPinnedDigest !== hasPinnedRunId) throw new Error('gate pinned image: both pinnedImageDigest and pinnedRunId are required');
     const head = await command('git', ['rev-parse', 'HEAD'], tree);
     check(head, 'cut tree HEAD');
     const commit = head.output.trim();
@@ -1848,7 +2113,7 @@ export function createGateRunner(repo: string, remote?: string, commandOverride?
     const admissionWaitSeconds = pod.admissionWaitSeconds ?? gateAdmissionWaitSeconds(shards.length, rootSlots);
     if (!Number.isSafeInteger(admissionWaitSeconds) || admissionWaitSeconds < 0) throw new Error('invalid pod sweep options');
     // An injected pool (tests) runs without admission unless `pod.admission` is passed; the gate's own pool asks it.
-    const gateAdmission = pod.admission ?? tools.admission ?? (poolOverride ? undefined : poolGateAdmission(poolScheduler));
+    const gateAdmission = pod.admission ?? tools.admission ?? (poolOverride ? undefined : poolGateAdmission(poolScheduler, tools.graphRunId ?? null));
     debug.log('release-loop.gate', 'pod-admission', { waitSeconds: admissionWaitSeconds, source: pod.admissionWaitSeconds !== undefined ? 'config' : 'default', enabled: !!gateAdmission && admissionWaitSeconds > 0,
       rootSlots, shards: shards.length });
     // GATE-POD-STALL-FAILFAST: a shard with no test output within the stall window is stopped and recorded unmeasured.
@@ -2227,7 +2492,9 @@ export function createGateRunner(repo: string, remote?: string, commandOverride?
           pool: pod.pool, poolScheduler: trackedPool(shard, branch, jobName, resultFile, attemptId, (member) => {
             stamp('poolPlaced'); jobContext = member.context; jobContextForCapture = member.context; placedOn = member.context; placed();
             if (branch === '-tail') tailPlacedHost = member.context;
-          }, skipMembers, depth === 0 && branch === '' && hostRetries === 0 && !retriedNoOutput && !batchIsolation && skipMembers.size === 0), clone: true, source: { kind: 'commit', sha: commit }, deadlineSeconds: shardDeadline,
+          }, skipMembers, depth === 0 && branch === '' && hostRetries === 0 && !retriedNoOutput && !batchIsolation && skipMembers.size === 0), clone: true, source: { kind: 'commit', sha: commit },
+          ...(pod.imagePin === 'cut-commit' || pod.pinnedImageDigest || pod.pinnedRunId ? { imageCommit: commit } : {}),
+          ...(pod.pinnedImageDigest || pod.pinnedRunId ? { syncImages: pinnedGateImageSync(pod, commit)! } : {}), deadlineSeconds: shardDeadline,
           ...gateHostMirror(pod),
           ...(multiHost ? { statusUnreadableMs: memberUnreadableSeconds * 1000 } : {}),
           ...(bunCache ? { bunCache } : {}),
@@ -2854,7 +3121,9 @@ export function createGateRunner(repo: string, remote?: string, commandOverride?
     let producer: RunPodCommandOptions['warmProducer'];
     if (leased && replay?.transport.status === 'observed' && replay.transport.reason === 'complete') {
       if (warmCommandMatchesRequest(leased, warmRequest!) && leased.podName && leased.podUid
-        && leased.podContext && leased.image?.endsWith(`@${leased.key.imageDigest}`)) {
+        && leased.podContext && leased.image?.endsWith(`@${leased.key.imageDigest}`)
+        && (!pod.pinnedImageDigest || (normalizeGateImageDigest(pod.pinnedImageDigest) !== null
+          && normalizeGateImageDigest(leased.key.imageDigest) === normalizeGateImageDigest(pod.pinnedImageDigest)))) {
         producer = { pod: leased.podName, podUid: leased.podUid, context: leased.podContext, image: leased.image,
           commit, files: ['package.json', 'bun.lock'] };
       } else await quarantine('gate-producer-identity');
@@ -2868,7 +3137,9 @@ export function createGateRunner(repo: string, remote?: string, commandOverride?
         run: process.env.ELANOUS_RUN_ID || attemptId, phase: 'release-gate', requestedAt: new Date().toISOString(),
         graphNode: 'gate-triage', commit, reason: `release gate recheck ${files.length} files`, pool: pod.pool,
         memReq: POD_ISOLATION_MEMORY_LIMIT, warmReused: !!producer },
-      source: { kind: 'commit', sha: commit }, deadlineSeconds, ...(producer ? { warmProducer: producer, image: producer.image, imageCommit: commit } : {}),
+      source: { kind: 'commit', sha: commit }, deadlineSeconds, ...(producer ? { warmProducer: producer, image: producer.image } : {}),
+      ...(producer || pod.pinnedImageDigest || pod.pinnedRunId ? { imageCommit: commit } : {}),
+      ...(pod.pinnedImageDigest || pod.pinnedRunId ? { syncImages: pinnedGateImageSync(pod, commit)! } : {}),
       ...(bunCache ? { bunCache } : {}), ...gateHostMirror(pod),
       ...(installSlots > 0 ? { installSlots: POD_INSTALL_SLOTS_HOST_PATH } : {}), ...(pod.cpu ? { cpu: pod.cpu } : {}),
       memoryLimit: POD_ISOLATION_MEMORY_LIMIT, name: `gate-recheck-${randomUUID()}`, command: ['bash', '-lc', shell] });
@@ -3221,9 +3492,10 @@ export function saveBaselineFileCache(ledger: string, commit: string, rows: Base
   } finally { if (existsSync(temp)) rmSync(temp); }
 }
 
-export async function judgeGate(opts: GateOptions, runner: GateRunner = createGateRunner(opts.repo ?? process.cwd(), opts.remote),
+export async function judgeGate(opts: GateOptions, runner: GateRunner = createGateRunner(opts.repo ?? process.cwd(), opts.remote, undefined, undefined, undefined, undefined, { graphRunId: opts.graphRunId ?? null }),
   imageProbe: typeof preflightGateImageDigest = preflightGateImageDigest,
-  identityProbe: typeof preflightGateExecutionIdentity = preflightGateExecutionIdentity): Promise<GateResult> {
+  identityProbe: typeof preflightGateExecutionIdentity = preflightGateExecutionIdentity,
+  syncImages: typeof syncPoolImages = syncPoolImages): Promise<GateResult> {
   if (opts.pod?.warmReplay) opts = { ...opts, pod: { ...opts.pod,
     warmShadowScope: { requested: false, attempts: 0 } } };
   const explicitConfig = getElanousConfigDirOverride();
@@ -3266,11 +3538,11 @@ export async function judgeGate(opts: GateOptions, runner: GateRunner = createGa
   let cutSweepRc: number | null = null;
   let radiusShadow: GateRadiusShadowPlan | undefined;
   const trees: string[] = [];
+  const baselineVersion = opts.baselineVersion;
   try {
     if (!sha.test(opts.commit) || !versionPattern.test(opts.version)
       || (opts.baselineVersion && !versionPattern.test(opts.baselineVersion))
       || (opts.baselineCommit && !sha.test(opts.baselineCommit))) throw new Error('invalid commit or version');
-    const baselineVersion = opts.baselineVersion;
     if (!baselineVersion) throw new Error('previous release version required (--baseline-version)');
     if (opts.rehearsalBaseline && (opts.graphRunId || !opts.pod || !/-rc\.\d+$/.test(opts.version)))
       throw new Error('rehearsal baseline requires a direct Pod gate with an isolated rc version');
@@ -3302,11 +3574,22 @@ export async function judgeGate(opts: GateOptions, runner: GateRunner = createGa
       const pinPath = gateImagePinPath(root, opts.version, pinRunId);
       const gateImageTag = `${podCommandImageFor([], true).split(':')[0]}:${opts.commit.slice(0, 12)}`;
       let savedPin: ReturnType<typeof readGateImagePin>;
+      let supersededPin: ReturnType<typeof readGateImagePinForRun> = null;
+      let stalePinNeedsSuperseding = false;
       try { savedPin = existsSync(pinPath) ? readGateImagePin(pinPath, pinRunId, gateImageTag, opts.commit) : null; }
       catch (error) {
-        debug.log('release-loop.gate', 'image-pin', { runId: pinRunId, currentImages, decision: 'fail-closed',
-          reason: 'saved-image-pin-invalid', error: String(error).slice(0, 300) }, { level: 'error' });
-        throw new Error('gate resume refused: saved image digest pin is invalid');
+        let prior: ReturnType<typeof readGateImagePinForRun> = null;
+        try { prior = readGateImagePinForRun(pinPath, pinRunId, gateImageTag); } catch { /* Keep invalid or corrupt pins fail-closed. */ }
+        if (!prior || prior.commit === opts.commit.toLowerCase()) {
+          debug.log('release-loop.gate', 'image-pin', { runId: pinRunId, currentImages, decision: 'fail-closed',
+            reason: 'saved-image-pin-invalid', error: String(error).slice(0, 300) }, { level: 'error' });
+          throw new Error('gate resume refused: saved image digest pin is invalid');
+        }
+        supersededPin = prior;
+        stalePinNeedsSuperseding = true;
+        savedPin = null;
+        debug.log('release-loop.gate', 'image-pin', { runId: pinRunId, currentImages, decision: 'stale-tip-detected',
+          priorCommit: supersededPin.commit, nextCommit: opts.commit.toLowerCase() });
       }
       const savedDigest = savedPin?.digest ?? null;
       let previouslyExecuted = false;
@@ -3321,11 +3604,34 @@ export async function judgeGate(opts: GateOptions, runner: GateRunner = createGa
           } catch { previouslyExecuted = true; }
         }
       }
-      if (!savedDigest && previouslyExecuted) {
+      if (!savedDigest && previouslyExecuted && !supersededPin) {
         debug.log('release-loop.gate', 'image-pin', { runId: opts.graphRunId, savedDigest: null, currentImages,
           decision: 'fail-closed', reason: 'resume-pin-missing' }, { level: 'error' });
         throw new Error('gate resume refused: saved image digest pin is missing');
       }
+      const hasPoolImage = [...poolImages.values()].some((images) => images.some((image) => normalizeGateImageDigest(image) !== null));
+      if (!savedDigest && !hasPoolImage) {
+        let syncResults: Awaited<ReturnType<typeof syncPoolImages>>;
+        try { syncResults = await syncImages(members, podCommandImageFor([], true), opts.commit); }
+        catch (error) {
+          debug.log('release-loop.gate', 'image-pin', { runId: pinRunId, decision: 'fail-closed',
+            reason: 'initial-image-sync-failed', error: String(error).slice(0, 300) }, { level: 'error' });
+          throw new Error('gate image pin refused: initial image sync failed');
+        }
+        const failedSyncs = memberSpecs.filter((member) => !syncResults.get(member.context)?.ok);
+        if (failedSyncs.length) {
+          debug.log('release-loop.gate', 'image-pin', { runId: pinRunId, decision: 'fail-closed', reason: 'initial-image-sync-failed',
+            failed: failedSyncs.map((member) => ({ context: member.context, result: syncResults.get(member.context) ?? null })) }, { level: 'error' });
+          throw new Error('gate image pin refused: initial image sync failed');
+        }
+        for (const member of memberSpecs) {
+          const digest = imageProbe(member.spec, opts.commit);
+          currentImages[member.context] = digest;
+          poolImages.set(member.context, digest ? [digest] : []);
+        }
+        debug.log('release-loop.gate', 'image-pin', { runId: pinRunId, decision: 'initial-image-sync',
+          outcomes: [...syncResults].map(([context, result]) => ({ context, ok: result.ok, action: result.action })), currentImages });
+      }
       const resolution = resolveGateImagePin({ ...(savedDigest ? { savedDigest } : {}),
         ...(!savedDigest ? { initialDigest: [...poolImages.values()].flat().find(Boolean) ?? null } : {}), poolImages });
       if (!resolution.ok) {
@@ -3336,7 +3642,11 @@ export async function judgeGate(opts: GateOptions, runner: GateRunner = createGa
       const selected = memberSpecs.filter((member) => resolution.eligiblePools.includes(member.context));
       if (!selected.length) throw new Error('gate image pin refused: no eligible pool');
       if (!savedDigest) {
-        try { writeGateImagePin(pinPath, pinRunId, resolution.digest, gateImageTag, opts.commit); }
+        try {
+          if (stalePinNeedsSuperseding) {
+            replaceGateImagePin(pinPath, pinRunId, resolution.digest, gateImageTag, opts.commit, gateImageTag, supersededPin!.commit);
+          } else writeGateImagePin(pinPath, pinRunId, resolution.digest, gateImageTag, opts.commit);
+        }
         catch (error) {
           debug.log('release-loop.gate', 'image-pin', { runId: pinRunId, pinnedDigest: resolution.digest,
             currentImages, decision: 'fail-closed', reason: 'pin-write-failed', error: String(error).slice(0, 300) }, { level: 'error' });
@@ -3506,7 +3816,7 @@ export async function judgeGate(opts: GateOptions, runner: GateRunner = createGa
       try {
         const sweepResult = await runner.sweep(cutTree,
       join(root, 'release', opts.version, 'gate-logs', selected ? 'cut-partial' : 'cut'),
-      opts.pod ? { ...opts.pod, durationSource, ...(knownFailures.length ? { knownFailures } : {}), onSelectionTimed: ({ ms }) => { result.selectionMs = ms; },
+      opts.pod ? { ...opts.pod, ...(opts.imagePin ? { imagePin: opts.imagePin } : {}), durationSource, ...(knownFailures.length ? { knownFailures } : {}), onSelectionTimed: ({ ms }) => { result.selectionMs = ms; },
         // GATE-RISK-LANE — the watch list is read from this gate's own ledgers (the instance root ⊕ the machine ledger);
         // the cut sweep puts those files first, the baseline sweep keeps its plan.
         riskWatch: { instanceRoots: roots, ledgerRoots: roots },
@@ -3608,7 +3918,7 @@ export async function judgeGate(opts: GateOptions, runner: GateRunner = createGa
           check(await runner.command('bun', ['install'], dir), `bun install ${dir}`);
         const rechecked = await runner.sweep(recheckTree,
           join(root, 'release', opts.version, 'gate-logs', 'baseline-attribution-recheck'),
-          opts.pod ? { ...opts.pod, durationSource } : undefined,
+          opts.pod ? { ...opts.pod, ...(opts.imagePin ? { imagePin: opts.imagePin } : {}), durationSource } : undefined,
           targetFiles);
         if (rechecked.timedOut || rechecked.abortedShards || rechecked.stalledEnv?.length) {
           attribution.baselineResult = 'timeout';
@@ -3723,7 +4033,7 @@ export async function judgeGate(opts: GateOptions, runner: GateRunner = createGa
         // K9b — the baseline is swept on the same Pod pool as the cut, not on this host (0.2.6: an hour of local baseline
         // after a 23-minute Pod cut).
         const baseRun = await runner.sweep(baseTree!, join(root, 'release', opts.version, 'gate-logs', 'baseline'),
-          opts.pod ? { ...opts.pod, durationSource } : undefined,
+          opts.pod ? { ...opts.pod, ...(opts.imagePin ? { imagePin: opts.imagePin } : {}), durationSource } : undefined,
           present);
         baseline = await localStalled(baseRun, baseTree!, baseSha, 'baseline');
       } else baseline = { failures: [], errors: [] };
@@ -4174,6 +4484,14 @@ export function parseOptions(args: string[], env: NodeJS.ProcessEnv): GateOption
   const fromGraph: Record<string, unknown> = context?.input ?? {};
   const graphCommit = context?.outputs['version-release']?.commit;
   if (typeof graphCommit === 'string') fromGraph.commit = graphCommit;
+  if (fromGraph.gateImagePin !== undefined && fromGraph.gateImagePin !== 'cut-commit') {
+    throw new Error(`unsupported gate image pin: ${String(fromGraph.gateImagePin)}`);
+  }
+  // Policy-selected Pod gates must pin their container to the resolved cut commit. Host sweeps do
+  // not consume a container image pin, and the legacy no-executor path retains its old behavior.
+  if (fromGraph.gateExecutor === 'pod' && fromGraph.gateImagePin !== 'cut-commit') {
+    throw new Error('gateImagePin cut-commit is required for a policy-selected release gate');
+  }
   const baselineCommit = context?.outputs.cutoff?.baseline as { sha?: unknown } | undefined;
   if (typeof baselineCommit?.sha === 'string') fromGraph.previousCommit = baselineCommit.sha;
   if (fromGraph.gateExecutor !== undefined && !isGateExecutor(fromGraph.gateExecutor)) throw new Error(`gateExecutor must be pod or host: ${String(fromGraph.gateExecutor)}`);
@@ -4186,6 +4504,7 @@ export function parseOptions(args: string[], env: NodeJS.ProcessEnv): GateOption
       || !['darwin', 'linux'].includes((value as { os?: string }).os ?? ''))))
     throw new Error('gateShardCapabilities must map pod-N to {os: darwin|linux}');
   const opts: GateOptions = {
+    ...(fromGraph.gateImagePin === 'cut-commit' ? { imagePin: 'cut-commit' as const } : {}),
     rehearsalTui: fromGraph.rehearsalTui === true,
     recheckFileLimit: fromGraph.gateRecheckFileLimit !== undefined ? Number(fromGraph.gateRecheckFileLimit) : undefined,
     commit: typeof fromGraph.commit === 'string' ? fromGraph.commit : '',
@@ -4214,12 +4533,19 @@ export function parseOptions(args: string[], env: NodeJS.ProcessEnv): GateOption
   };
   if (isGateExecutor(fromGraph.gateExecutor)) opts.executor = fromGraph.gateExecutor;
   let freshShards = false;
+  let warmPrecutCanaryFile: string | undefined;
   let rerouteShard: string | undefined;
   let shardHost: string | undefined;
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === '--help') return 'help';
     if (arg === '--json') continue;
+    if (arg === '--precut-canary-file') {
+      const value = args[++i];
+      if (!value || value.startsWith('--')) throw new Error('--precut-canary-file requires one test file');
+      warmPrecutCanaryFile = value;
+      continue;
+    }
     if (arg === '--full') { opts.full = true; continue; }
     if (arg === '--rehearsal-baseline') { opts.rehearsalBaseline = true; continue; }
     // Applied after the loop and only to a Pod gate — on its own it must not turn a local gate into a Pod one (review r5).
@@ -4264,6 +4590,7 @@ export function parseOptions(args: string[], env: NodeJS.ProcessEnv): GateOption
     else if (key === 'remoteMirror') opts.remoteMirror = value;
   }
   if (freshShards && opts.pod) opts.pod = { ...opts.pod, freshShards: true };
+  if (warmPrecutCanaryFile) opts.warmPrecutCanary = { file: warmPrecutCanaryFile };
   if ((rerouteShard || shardHost) && !opts.pod?.pool) throw new Error('shard reroute requires a Pod pool');
   if (shardHost && !rerouteShard) throw new Error('--shard-host requires --reroute-shard');
   if (opts.pod && rerouteShard) opts.pod = { ...opts.pod, rerouteShard, ...(shardHost ? { shardHost } : {}) };
@@ -4286,11 +4613,12 @@ export async function runGateNode(argv: string[], env: NodeJS.ProcessEnv, runner
   judge: (opts: GateOptions, runner?: GateRunner, imageProbe?: typeof preflightGateImageDigest) => Promise<GateResult> = judgeGate,
   imageProbe: typeof preflightGateImageDigest = preflightGateImageDigest): Promise<number> {
   const start = Date.now();
-  let result: GateResult;
+  let result: GateResult | undefined;
   let version = '';
   let graphRunId: string | null = null;
   let autohealStoreRoot = '';
   let placement: { executor: string | null; host: string | null } | undefined;
+  let warmControlCleanup: (() => Promise<void>) | undefined;
   try {
     const parsed = parseOptions(argv, env);
     let config: unknown = null;
@@ -4298,13 +4626,28 @@ export async function runGateNode(argv: string[], env: NodeJS.ProcessEnv, runner
       try { config = getUserConfig(); }
       catch (error) { debug.log('release-loop.gate', 'warm-profile-unavailable', { error: String(error) }); }
     }
-    const opts = parsed === 'help' ? parsed : withWarmGateHooks(parsed, config, !!runner);
+    const opts = parsed === 'help' ? parsed : withWarmGateHooks(parsed, config, !!runner,
+      cleanup => { warmControlCleanup = cleanup; });
+    if (opts !== 'help' && opts.warmPrecutCanary) {
+      const canaryRunner = runner ?? createGateRunner(opts.repo ?? process.cwd(), opts.remote, undefined, undefined, undefined, undefined, { graphRunId: opts.graphRunId ?? null });
+      const warmPrecutTestSeam = (runner as (GateRunner & { warmPrecutCanaryTestSeam?: {
+        config: unknown; hooks: Pick<NonNullable<GateOptions['pod']>, 'warmReplay' | 'warmFinalize' | 'warmQuarantine' | 'warmReuseConfig'>;
+      } }) | undefined)?.warmPrecutCanaryTestSeam;
+      const canaryOpts = warmPrecutTestSeam && opts.pod ? { ...opts, pod: { ...opts.pod, ...warmPrecutTestSeam.hooks } } : opts;
+      const canary = await runWarmPrecutCanary({ opts: canaryOpts, runner: canaryRunner, file: opts.warmPrecutCanary.file,
+        config: warmPrecutTestSeam?.config ?? config,
+        historyPath: verdictFile(opts.ledgerRoot ?? releaseLedgerRoot(), opts.version) });
+      const output = { version: opts.version, commit: opts.commit, samples: canary.samples, decision: canary.decision };
+      console.log(JSON.stringify(output));
+      return 0;
+    }
     if (opts !== 'help') {
       placement = gateExecutorOf(opts);
-      debug.log('release-loop.gate', 'executor', { version: opts.version, ...placement, requested: opts.executor ?? null });
+      debug.log('release-loop.gate', 'executor', { version: opts.version, ...placement, requested: opts.executor ?? null,
+        imagePin: opts.imagePin ?? null, imageCommit: opts.imagePin === 'cut-commit' ? opts.commit : null });
     }
     if (opts === 'help') {
-      console.log('Usage: bun scripts/release-loop/gate-node.ts --commit <sha> --version <v> [--baseline-version <prev>] [--baseline-commit <sha>] [--remote <ssh-host>] [--remote-mirror <path>] [--pod-pool <pool>] [--pod-shards <n>] [--pod-shard-timeout-seconds <n>] [--recheck-file-limit <n>] [--fresh-shards] [--reroute-shard <pod-N|auto>] [--shard-host <pool-context>] [--executor <pod|host>] [--rehearsal-baseline] [--full] [--json]\nWithout flags, input.commit, input.version and input.previousVersion come from the JSON file at ELANOUS_GRAPH_CONTEXT.\n--executor host (input.gateExecutor) ignores every pod option and sweeps on --remote (input.gateRemote, required).\n--rehearsal-baseline pins source graph bytes only for a direct Pod gate on an isolated rc version.\n--full disables receipt and partial reuse and runs the complete test inventory.');
+      console.log('Usage: bun scripts/release-loop/gate-node.ts --commit <sha> --version <v> [--baseline-version <prev>] [--baseline-commit <sha>] [--remote <ssh-host>] [--remote-mirror <path>] [--pod-pool <pool>] [--precut-canary-file <test-file>] [--pod-shards <n>] [--pod-shard-timeout-seconds <n>] [--recheck-file-limit <n>] [--fresh-shards] [--reroute-shard <pod-N|auto>] [--shard-host <pool-context>] [--executor <pod|host>] [--rehearsal-baseline] [--full] [--json]\n--precut-canary-file runs exactly two one-file warm↔fresh comparisons and stores them in this version\'s gate-verdict warmHistory before the standard gate consumes it; decideWarmReuse applies minMatchSamples.\nWithout flags, input.commit, input.version and input.previousVersion come from the JSON file at ELANOUS_GRAPH_CONTEXT.\n--executor host (input.gateExecutor) ignores every pod option and sweeps on --remote (input.gateRemote, required).\n--rehearsal-baseline pins source graph bytes only for a direct Pod gate on an isolated rc version.\n--full disables receipt and partial reuse and runs the complete test inventory.');
       return 0;
     }
     version = opts.version;
@@ -4324,7 +4667,15 @@ export async function runGateNode(argv: string[], env: NodeJS.ProcessEnv, runner
   } catch (error) {
     result = { outcome: 'error', commit: '', introduced: [], preexisting: 0, fixed: 0, knownEnv: 0, knownEnvCleared: [], stalledEnv: [], rcNonzeroNoFailures: [], durationMs: Date.now() - start, error: String(error) };
     placement ??= requestedGateExecutor(argv, env);
+  } finally {
+    try { await warmControlCleanup?.(); }
+    catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      debug.log('pod.warm.control-forward', 'cleanup-failed', { version, reason }, { level: 'error' });
+      if (typeof result !== 'undefined') result = { ...result, outcome: 'error', error: [result.error, reason].filter(Boolean).join('; ') };
+    }
   }
+  if (!result) throw new Error('release gate returned without a result');
   if (versionPattern.test(version) && result.stalledShards?.length) {
     result.autoheals = result.stalledShards.map((shard, index) => {
       const shardKey = `pod-${shard.shard}`;
@@ -4363,5 +4714,6 @@ if (import.meta.main) {
   // The graph spawns this file as its own process, which inherits no daemon sink — without this every
   // `release-loop.gate`/`release.gate`/`pod.pool` event stayed in the file trail and `elanous logs` read 0 rows.
   await registerStandaloneLogSink('release-loop');
-  process.exitCode = await runWithReleaseGateTraffic(process.env, () => runGateNode(process.argv.slice(2), process.env));
+  process.exitCode = await runWithReleaseGateTraffic(process.env,
+    () => runWithReleasePwaTraffic(process.env, () => runGateNode(process.argv.slice(2), process.env)));
 }