elanous 0.2.41 → 0.2.43

package/scripts/lib/fixtures/tui-regress/help-shifted-input.txt

@@ -0,0 +1,26 @@
+elanous 0.2.41 · owner · daemon: online
+┌─ Dashboard help ─────────────────────────────────────────────┐
+│ Commands                                                     │
+│ ▸ 대화                                                         │
+│   /help       이 명령들 목록                                       │
+│   /new        새 대화 시작                                        │
+│   /quit       종료                                             │
+│ ▸ 지시                                                         │
+│   /directive  대표 지시                                          │
+│   /decide     결정 요청                                          │
+│ ▸ 작업                                                         │
+│   /missions   미션 목록                                          │
+│   /tasks      작업 목록                                          │
+│   /review     리뷰 열기                                          │
+│   /publish    발행                                             │
+│ ▸ 시스템                                                        │
+│   /provider   LLM 공급자                                        │
+│   /model      모델                                             │
+│   /settings   설정                                             │
+│                                                              │
+│ Keys                                                         │
+│   Enter       메시지 보내기                                        │
+│   Ctrl+C      입력 지움 · 두 번 누르면 나갑니다                           │
+│   Esc         도움말 닫기                                         │
+│   PgUp/PgDn   스크롤                                            │
+└──────────────────────────────────────────────────────────────┘

package/scripts/lib/tui-regress-checks.ts

@@ -27,33 +27,46 @@ const HINT = /한 번 더 누르면 나갑니다/;
 const ok = (reason: string): Verdict => ({ ok: true, reason });
 const no = (reason: string): Verdict => ({ ok: false, reason });
 
-/** The input row: the last screen line that starts with the prompt marker. */
+/** The TUI draws panels with box/block borders (box drawing and block elements, U+2500–U+259F) — a judge must read
+ *  the same «content lines» whether a screen renders a plain list or a bordered panel (0.2.41 incident:
+ *  R6 warned on the healthy «│Keys …│» screen). Border characters become spaces, so a line keeps its
+ *  own indentation, and a line left with nothing but whitespace was the frame itself and is dropped. */
+export function contentLines(screen: string): string[] {
+  return screen
+    .split('\n')
+    .map((line) => line.replace(/[\u2500-\u259F]/g, ' '))
+    .filter((line) => line.trim().length > 0);
+}
+
+/** The input row: the last content line that starts with the prompt marker. */
 export function inputRow(screen: string): string | undefined {
-  return screen.split('\n').filter((line) => line.trimStart().startsWith('❯')).at(-1);
+  return contentLines(screen).filter((line) => line.trimStart().startsWith('❯')).at(-1);
 }
 
-/** Palette entries visible after typing a slash prefix (lines other than the input row that show `/name`). */
+/** Palette entries visible after typing a slash prefix (content lines other than the input row that show `/name`). */
 export function paletteHas(screen: string, name: string): boolean {
+  const lines = contentLines(screen);
   const row = inputRow(screen);
-  return screen.split('\n').some((line) => line !== row && line.includes(`/${name}`));
+  return lines.some((line) => line !== row && line.includes(`/${name}`));
 }
 
 export function judgeFirstScreen(screen: string): Verdict {
-  if (/Step 1/.test(screen)) return no('«Step 1» 마법사가 떴다');
+  const lines = contentLines(screen);
+  if (lines.some((line) => /Step 1/.test(line))) return no('«Step 1» 마법사가 떴다');
   if (!inputRow(screen)) return no('입력칸 «❯» 가 없다');
   return ok('입력칸이 보이고 «Step 1» 이 없다');
 }
 
 export function judgeHintAppearsThenClears(armed: string, later: string): Verdict {
-  if (!HINT.test(armed)) return no('빈 입력 Ctrl+C 뒤 안내가 안 보인다');
-  if (HINT.test(later)) return no('2.6초 뒤에도 안내가 남아 있다');
+  if (!contentLines(armed).some((line) => HINT.test(line))) return no('빈 입력 Ctrl+C 뒤 안내가 안 보인다');
+  if (contentLines(later).some((line) => HINT.test(line))) return no('2.6초 뒤에도 안내가 남아 있다');
   return ok('안내가 떴다가 2초 뒤 사라졌다');
 }
 
 export function judgeCtrlCClearsText(typed: string, after: string, text: string): Verdict {
   if (!(inputRow(typed) ?? '').includes(text)) return no('친 글이 입력칸에 안 보인다(준비 실패)');
   if ((inputRow(after) ?? '').includes(text)) return no('Ctrl+C 뒤에도 글이 남아 있다');
-  if (HINT.test(after)) return no('글을 지우는 Ctrl+C 에 나가기 안내가 떴다');
+  if (contentLines(after).some((line) => HINT.test(line))) return no('글을 지우는 Ctrl+C 에 나가기 안내가 떴다');
   return ok('글이 지워지고 안내는 없다');
 }
 
@@ -67,11 +80,18 @@ export function judgePalette(screens: Record<string, string>, expectations: Reco
 }
 
 /** U1b — the help is drawn (key section ⊕ a run of command rows) and the prompt survives below it.
- *  Not «the whole grid fits»: an owner sees 60+ commands, which exceed a 50-row screen and scroll (PgUp). */
+ *  Not «the whole grid fits»: an owner sees 60+ commands, which exceed a 50-row screen and scroll (PgUp).
+ *  Border-agnostic (0.2.41 R6 오탐): judged on content lines, so the bordered «│Keys …│» panel reads
+ *  like the plain list. */
 export function judgeHelpShown(screen: string): Verdict {
-  const lines = screen.split('\n');
-  const commandRows = lines.filter((line) => /^\s+\/[a-z][a-z-]*/.test(line)).length;
-  if (!lines.some((line) => /^\s*Keys\s*$/.test(line))) return no('/help 의 Keys 절이 안 보인다');
+  const lines = contentLines(screen);
+  const commandsAt = lines.findIndex((line) => /^\s*Commands\s*$/.test(line));
+  const keysAt = lines.findIndex((line) => /^\s*Keys\s*$/.test(line));
+  if (commandsAt < 0) return no('/help 의 Commands 절이 안 보인다');
+  if (keysAt <= commandsAt) return no('/help 의 Keys 절이 안 보인다');
+  // Count command-bearing rows only within the panel section; commands may be in either column.
+  const commandRows = lines.slice(commandsAt + 1, keysAt)
+    .filter((line) => /(?:^|\s)\/[a-z][a-z-]*(?=\s|$)/.test(line)).length;
   if (commandRows < 10) return no(`명령 줄이 ${commandRows}개뿐이다`);
   if (!inputRow(screen)) return no('도움말을 연 뒤 입력칸이 화면 밖으로 밀렸다');
   return ok(`도움말이 그려졌다(명령 줄 ${commandRows} · Keys 절 · 입력칸 유지)`);
@@ -79,7 +99,7 @@ export function judgeHelpShown(screen: string): Verdict {
 
 /** U1c2 — lines typed while a reply streams show up as «my» lines, in order, each above its own answer. */
 export function judgeQueuedEcho(screen: string): Verdict {
-  const lines = screen.split('\n');
+  const lines = contentLines(screen);
   const at = (re: RegExp, after = -1) => lines.findIndex((line, i) => i > after && re.test(line));
   const u2 = at(/Q2MARK 라고만/);
   if (u2 < 0) return no('줄 서 있던 «Q2MARK 라고만» 이 내 말로 안 보인다');

package/scripts/release-loop/auto-approve-node.ts

@@ -86,7 +86,7 @@ export function runAutoApprove(context: GraphContext = readGraphContext(), deps:
   writeFileSync(report, lines.join('\n'));
   const tuiSubcheck = { runId: context.runId ?? null, level: regressStatus.level,
     fail: failedCheckIds?.length ?? null, failedCheckIds, approvalRequired: regressNeedsApproval };
-  debug.log('release-loop.approve', 'auto-decision', { version, outcome, metrics, tuiSubcheck });
+  debug.log('release-loop.approve', 'auto-decision', { version, outcome, metrics, runId: context.runId ?? null, tuiSubcheck });
   return { outcome, verdict: outcome === 'ok' ? 'pass' as const : 'fail' as const,
     summary: `auto approval ${outcome}: ${metrics.filter((metric) => !WARNING_ONLY.has(metric.name) && metric.verdict === 'pass').length}/8${regressNeedsApproval ? ` · tui-regress ${regressStatus.level} failed ${failedLabel} → HITL` : ''}`,
     runId: context.runId ?? null, tuiSubcheck, ...(outcome === 'ok' ? { decidedBy: 'release-loop metrics' as const } : {}), metrics, report };

package/scripts/release-loop/gate-autoheal-sim-evidence.ts

@@ -0,0 +1,60 @@
+#!/usr/bin/env bun
+/**
+ * Isolated E4 evidence bridge: GATE-MOCK-EVENT-SCENARIOS fake devices plus the production
+ * runGateNode autoheal decision/log path. It never starts a release run or a real Pod.
+ */
+import { mkdirSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { debug } from '../../src/debug/log.js';
+import { setElanousConfigDir } from '../../src/elanous-config-dir.js';
+import { registerStandaloneLogSink } from '../../src/domains/standalone-log-sink.js';
+import { prodInstanceRoot } from '../../src/instance/resolve.js';
+import { runGateNode, type GateResult } from './gate-node.js';
+import { GATE_NODE_SIM_SCENARIOS, judgeInjectedGateEvent } from './gate-node-sim.js';
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
+const testRoot = join(repoRoot, '.elanous-test');
+const runId = `gate-autoheal-sim-${new Date().toISOString().replace(/[-:.TZ]/g, '')}`;
+
+if (realpathSync(repoRoot) === realpathSync(prodInstanceRoot())) {
+  throw new Error('refusing to run evidence simulation from the production state root');
+}
+if (process.env.ELANOUS_STATE_DIR && resolve(process.env.ELANOUS_STATE_DIR) !== resolve(testRoot)) {
+  throw new Error(`ELANOUS_STATE_DIR must be this worktree test root: ${testRoot}`);
+}
+
+const scenario = GATE_NODE_SIM_SCENARIOS.find((item) => item.id === 'host-down-reroute');
+if (!scenario) throw new Error('GATE-MOCK-EVENT-SCENARIOS is missing host-down-reroute');
+const simulated = await judgeInjectedGateEvent(scenario);
+if (simulated.outcome !== scenario.expectedOutcome || simulated.action !== scenario.action || simulated.podCommandCalls !== 0) {
+  throw new Error(`fake-device scenario did not match: ${JSON.stringify(simulated)}`);
+}
+
+mkdirSync(testRoot, { recursive: true });
+process.env.ELANOUS_STATE_DIR = testRoot;
+process.env.ELANOUS_RUN_ID = runId;
+process.env.ELANOUS_GRAPH_CONTEXT = JSON.stringify({
+  runId,
+  input: { version: '0.2.43', previousVersion: '0.2.42', commit: 'a'.repeat(40) },
+  outputs: {},
+});
+setElanousConfigDir(testRoot);
+
+if (!await registerStandaloneLogSink('release-loop')) throw new Error('could not register isolated release-loop logs.db sink');
+
+// Inject the same host-unreachable failure class through the production node's judge seam. runGateNode
+// performs the real cause classification, budgeted decision, ledger write, and debug.log emission.
+const injectedFailure: GateResult = {
+  outcome: 'error', commit: 'a'.repeat(40), introduced: [], preexisting: 0, fixed: 0,
+  knownEnv: 0, knownEnvCleared: [], stalledEnv: [], rcNonzeroNoFailures: [], durationMs: 1_000,
+  error: 'gate host unreachable (simulation injection)',
+};
+const exitCode = await runGateNode(['--json'], process.env, undefined, async () => injectedFailure);
+if (exitCode !== 2) throw new Error(`expected injected gate error exit=2, got ${exitCode}`);
+debug.flush();
+
+console.log(JSON.stringify({ label: 'simulation E4', runId, scenario: scenario.id,
+  scenarioOutcome: simulated.outcome, plannerAction: simulated.action, podCommandCalls: simulated.podCommandCalls,
+  injectedCause: 'host-down', expectedAutohealAction: 'host-switch', exitCode,
+  store: join(testRoot, 'logs/logs.db') }));

package/scripts/release-loop/gate-baseline-receipt.ts

@@ -24,7 +24,7 @@ export function gateAssignableTestsAtCommit(repo: string, commit: string): strin
 }
 
 export interface GateBaselineReceipt {
-  schema: 1;
+  schema: 2;
   valid: boolean;
   reason: string;
   version: string;
@@ -33,11 +33,37 @@ export interface GateBaselineReceipt {
   recipeSha: string | null;
   envFingerprint: string;
   imageDigest: string | null;
+  executionIdentity: GatePodRuntimeIdentity | null;
   files: number;
   shards: number;
   attributionRecheck?: { summary: number; observed: number; identified: number; baselineResult: string; targetFiles: string[] };
 }
 
+export interface GatePodRuntimeIdentity {
+  bunVersion: string;
+  platform: string;
+  architecture: string;
+  envFingerprint: string;
+}
+
+const validRuntimeIdentity = (value: unknown): value is GatePodRuntimeIdentity => {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const row = value as Partial<GatePodRuntimeIdentity>;
+  return Object.keys(value).sort().join(',') === 'architecture,bunVersion,envFingerprint,platform'
+    && typeof row.bunVersion === 'string' && /^\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/.test(row.bunVersion)
+    && typeof row.platform === 'string' && /^[a-z0-9_-]{1,32}$/.test(row.platform)
+    && typeof row.architecture === 'string' && /^[a-z0-9_-]{1,32}$/.test(row.architecture)
+    && typeof row.envFingerprint === 'string' && SHA256.test(row.envFingerprint);
+};
+
+/** Parse runtime facts written by the gate Pod before its tests start. */
+export function parseGatePodRuntimeIdentity(text: string): GatePodRuntimeIdentity | null {
+  try {
+    const value: unknown = JSON.parse(text);
+    return validRuntimeIdentity(value) ? value : null;
+  } catch { return null; }
+}
+
 /** A direct hard rehearsal has no graph run state. Pin the graph and recipe bytes at its Git SHA. */
 export function gateSourcePins(repo: string, commit: string): { graphSha: string; recipeSha: string } | null {
   if (!/^[0-9a-f]{40}$/i.test(commit)) return null;
@@ -87,8 +113,9 @@ export function gateBaselineReceipt(input: { root: string; version: string; comm
   graphPins: { graphSha: string; recipeSha: string } | null; envFingerprint: string;
   attributionRecheck?: { summary: number; observed: number; identified: number; baselineResult: string; targetFiles: string[] } }): GateBaselineReceipt {
   const { root, version, commit, graphPins, envFingerprint } = input;
-  const base = { schema: 1 as const, version, commit, graphSha: graphPins?.graphSha ?? null,
-    recipeSha: graphPins?.recipeSha ?? null, envFingerprint, imageDigest: null as string | null, files: 0, shards: 0 };
+  const base = { schema: 2 as const, version, commit, graphSha: graphPins?.graphSha ?? null,
+    recipeSha: graphPins?.recipeSha ?? null, envFingerprint, imageDigest: null as string | null,
+    executionIdentity: null as GatePodRuntimeIdentity | null, files: 0, shards: 0 };
   const invalid = (reason: string): GateBaselineReceipt => ({ ...base, valid: false, reason });
   if (input.attributionRecheck) {
     const evidence = input.attributionRecheck;
@@ -102,12 +129,14 @@ export function gateBaselineReceipt(input: { root: string; version: string; comm
     const dir = join(root, 'release', version, 'gate-logs', 'cut');
     if (!existsSync(dir)) return invalid('cut Pod logs absent');
     const names = readdirSync(dir).filter((name) => /^pod-\d+(?:-[\w-]+)?\.json$/.test(name));
-    const roots = new Map<number, { files: string[]; shardCount: number; sweepId: string; attemptId: string }>();
-    const descendants: Array<{ name: string; commit?: string; imageDigest?: string; sweepId?: string; parentAttempt?: string; attemptId?: string }> = [];
+    const roots = new Map<number, { files: string[]; shardCount: number; sweepId: string; attemptId: string; runtimeIdentity?: GatePodRuntimeIdentity }>();
+    const descendants: Array<{ name: string; commit?: string; imageDigest?: string; sweepId?: string; parentAttempt?: string; attemptId?: string; runtimeIdentity?: GatePodRuntimeIdentity }> = [];
     const images = new Set<string>();
+    const identities = new Map<string, GatePodRuntimeIdentity>();
     for (const name of names) {
       const row = JSON.parse(readFileSync(join(dir, name), 'utf8')) as
-        { commit?: string; files?: unknown; shardCount?: number; sweepId?: string; imageDigest?: string; parentAttempt?: string; attemptId?: string };
+        { commit?: string; files?: unknown; shardCount?: number; sweepId?: string; imageDigest?: string; parentAttempt?: string; attemptId?: string; runtimeIdentity?: unknown };
+      const runtimeIdentity = validRuntimeIdentity(row.runtimeIdentity) ? row.runtimeIdentity : undefined;
       const match = /^pod-(\d+)\.json$/.exec(name);
       if (match) {
         if (row.commit !== commit) return invalid(`root cut Pod ${name} belongs to another commit`);
@@ -115,12 +144,16 @@ export function gateBaselineReceipt(input: { root: string; version: string; comm
           return invalid(`root cut Pod ${name} has no file list`);
         if (!row.attemptId) return invalid(`root cut Pod ${name} has no attempt`);
         if (!row.sweepId) return invalid(`root cut Pod ${name} has no sweep identity`);
-        roots.set(Number(match[1]), { files: row.files as string[], shardCount: row.shardCount ?? 0, sweepId: row.sweepId, attemptId: row.attemptId });
+        roots.set(Number(match[1]), { files: row.files as string[], shardCount: row.shardCount ?? 0,
+          sweepId: row.sweepId, attemptId: row.attemptId, runtimeIdentity });
       } else descendants.push({ name, commit: row.commit, imageDigest: row.imageDigest, sweepId: row.sweepId,
-        parentAttempt: row.parentAttempt, attemptId: row.attemptId });
+        parentAttempt: row.parentAttempt, attemptId: row.attemptId, runtimeIdentity });
       if (match) {
         if (!row.imageDigest || !IMAGE_DIGEST.test(row.imageDigest)) return invalid(`actual Pod image digest absent: ${name}`);
+        if (!runtimeIdentity) return invalid(`actual Pod runtime identity absent: ${name}`);
+        if (runtimeIdentity.envFingerprint !== envFingerprint) return invalid(`actual Pod environment differs: ${name}`);
         images.add(row.imageDigest.toLowerCase());
+        identities.set(JSON.stringify(runtimeIdentity), runtimeIdentity);
       }
     }
     if (!roots.size) return invalid('root cut shards absent');
@@ -144,7 +177,10 @@ export function gateBaselineReceipt(input: { root: string; version: string; comm
         if (row.sweepId !== sweepId) return invalid(`cut Pod ${row.name} belongs to another sweep`);
         if (!row.imageDigest || !IMAGE_DIGEST.test(row.imageDigest)) return invalid(`actual Pod image digest absent: ${row.name}`);
         if (!row.attemptId) return invalid(`cut Pod ${row.name} has no attempt`);
+        if (!row.runtimeIdentity) return invalid(`actual Pod runtime identity absent: ${row.name}`);
+        if (row.runtimeIdentity.envFingerprint !== envFingerprint) return invalid(`actual Pod environment differs: ${row.name}`);
         images.add(row.imageDigest.toLowerCase());
+        identities.set(JSON.stringify(row.runtimeIdentity), row.runtimeIdentity);
         attempts.add(row.attemptId);
       }
       pending = next;
@@ -157,6 +193,8 @@ export function gateBaselineReceipt(input: { root: string; version: string; comm
       if (row.commit === commit && !row.sweepId) return invalid(`cut Pod ${row.name} has no sweep identity`);
     }
     if (images.size !== 1) return invalid('cut Pods used different image digests');
-    return { ...base, valid: true, reason: 'complete clean full sweep', imageDigest: [...images][0]!, files: files.length, shards: count };
+    if (identities.size !== 1) return invalid('cut Pods used different runtime identities');
+    return { ...base, valid: true, reason: 'complete clean full sweep', imageDigest: [...images][0]!,
+      executionIdentity: identities.values().next().value!, files: files.length, shards: count };
   } catch (error) { return invalid(`cut Pod evidence unreadable: ${String(error)}`); }
 }

package/scripts/release-loop/gate-image-pin.ts

@@ -0,0 +1,81 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+/** A gate run may execute only against one immutable image identity and its exact source tag. */
+export interface GateImagePin { runId: string; digest: string; image: string; commit: string }
+
+export type GateImagePinResolution =
+  | { ok: true; digest: string; eligiblePools: string[] }
+  | { ok: false; reason: 'saved-image-digest-invalid' | 'initial-image-digest-invalid' | 'initial-image-digest-missing' | 'pinned-image-unavailable' };
+
+export interface ResolveGateImagePinOptions {
+  /** Persisted at the run boundary; takes precedence over any newly probed default. */
+  savedDigest?: string | null;
+  /** Used only to create the pin for a new run. */
+  initialDigest?: string | null;
+  /** Exact immutable digest selected by the gate image probe in each pool. */
+  poolImages: ReadonlyMap<string, readonly string[]>;
+}
+
+function normalizeGateImageDigest(value: unknown): string | null {
+  if (typeof value !== 'string' || !/^sha256:[a-f0-9]{64}$/i.test(value.trim())) return null;
+  return value.trim().toLowerCase();
+}
+
+/**
+ * Resolve the durable run pin and fail closed unless at least one pool can prove it has that exact image.
+ * Callers must filter placement to `eligiblePools`; a mutable tag is never a substitute.
+ */
+export function resolveGateImagePin(options: ResolveGateImagePinOptions): GateImagePinResolution {
+  const hasSaved = options.savedDigest !== undefined && options.savedDigest !== null;
+  const rawDigest = hasSaved ? options.savedDigest : options.initialDigest;
+  if (!hasSaved && (rawDigest === undefined || rawDigest === null || rawDigest.trim() === '')) {
+    return { ok: false, reason: 'initial-image-digest-missing' };
+  }
+  const digest = normalizeGateImageDigest(rawDigest);
+  if (!digest) return { ok: false, reason: hasSaved ? 'saved-image-digest-invalid' : 'initial-image-digest-invalid' };
+  const eligiblePools = [...options.poolImages]
+    .filter(([, images]) => images.some((image) => normalizeGateImageDigest(image) === digest))
+    .map(([pool]) => pool);
+  if (!eligiblePools.length) return { ok: false, reason: 'pinned-image-unavailable' };
+  return { ok: true, digest, eligiblePools };
+}
+
+/** The pin is immutable for one graph gate run; absence on resume is a hard refusal. */
+export function readGateImagePin(path: string, expectedRunId: string, expectedImage: string, expectedCommit: string): GateImagePin | null {
+  if (!existsSync(path)) return null;
+  const parsed = JSON.parse(readFileSync(path, 'utf8')) as { version?: unknown; runId?: unknown; digest?: unknown; image?: unknown; commit?: unknown };
+  const normalizedCommit = expectedCommit.toLowerCase();
+  if (parsed.version !== 2 || parsed.runId !== expectedRunId || parsed.image !== expectedImage || parsed.commit !== normalizedCommit
+    || !normalizeGateImageDigest(parsed.digest))
+    throw new Error(`invalid gate image pin: ${path}`);
+  return { runId: expectedRunId, digest: normalizeGateImageDigest(parsed.digest)!, image: expectedImage, commit: normalizedCommit };
+}
+
+export function writeGateImagePin(path: string, runId: string, digest: string, image: string, commit: string): void {
+  const normalized = normalizeGateImageDigest(digest);
+  if (!runId || !normalized || !image.trim() || !/^[0-9a-f]{40}$/i.test(commit)) throw new Error('invalid gate image pin identity');
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const value = JSON.stringify({ version: 2, runId, digest: normalized, image, commit: commit.toLowerCase() });
+  if (existsSync(path)) {
+    const prior = JSON.parse(readFileSync(path, 'utf8')) as { runId?: unknown; digest?: unknown; image?: unknown; commit?: unknown };
+    if (prior.runId !== runId || normalizeGateImageDigest(prior.digest) !== normalized || prior.image !== image
+      || prior.commit !== commit.toLowerCase())
+      throw new Error(`gate image pin is immutable: ${path}`);
+    return;
+  }
+  try { writeFileSync(path, `${value}\n`, { mode: 0o600, flag: 'wx' }); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+    const prior = JSON.parse(readFileSync(path, 'utf8')) as { runId?: unknown; digest?: unknown; image?: unknown; commit?: unknown };
+    if (prior.runId === runId && normalizeGateImageDigest(prior.digest) === normalized && prior.image === image
+      && prior.commit === commit.toLowerCase()) return;
+    throw new Error(`gate image pin is immutable: ${path}`);
+  }
+}
+
+export function gateImagePinPath(root: string, version: string, runId: string): string {
+  if (!/^\d+\.\d+\.\d+(?:-rc\.\d+)?$/.test(version) || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(runId))
+    throw new Error('invalid gate image pin path identity');
+  return `${root.replace(/\/$/, '')}/release/${version}/gate-image-pin-${runId}.json`;
+}

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

@@ -1,3 +1,142 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+
+export type ReleaseGateExecutor = 'pod' | 'host';
+export interface ReleaseGateRehearsal {
+  version: string;
+  outcome: string;
+  executor?: string | null;
+  commit?: string;
+}
+
+export interface ReleaseOpsPolicy {
+  schemaVersion: 1;
+  gate: {
+    default: { executor: ReleaseGateExecutor; poolSource: 'config.release.loop.gatePodPool'; imagePin: 'cut-commit' };
+    rehearsalDecisions: Array<{
+      id: string;
+      when: { outcome: string; executor?: string };
+      executor: ReleaseGateExecutor;
+      poolSource: 'config.release.loop.gatePodPool';
+      imagePin: 'cut-commit';
+    }>;
+  };
+  knownInterferences: Array<{
+    id: string;
+    observedVersion: string;
+    issue: string;
+    workaround: { executor: ReleaseGateExecutor; expiresAfterVersion: string; clearCondition: string };
+  }>;
+}
+
+export interface ReleaseGateMethodDecision {
+  executor: ReleaseGateExecutor;
+  pool: string;
+  imagePin: 'cut-commit';
+  decision: string;
+  rehearsalVersion: string | null;
+  expiredWorkarounds: string[];
+}
+
+const DEFAULT_RELEASE_OPS_POLICY = join(import.meta.dir, '../../packs/release-ops/policy.yaml');
+const RELEASE_VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
+
+function compareReleaseVersions(a: string, b: string): number {
+  if (!RELEASE_VERSION.test(a) || !RELEASE_VERSION.test(b)) throw new Error(`release policy version must be x.y.z: ${a} / ${b}`);
+  const aa = a.split('.').map(BigInt), bb = b.split('.').map(BigInt);
+  for (let i = 0; i < 3; i++) {
+    if (aa[i]! < bb[i]!) return -1;
+    if (aa[i]! > bb[i]!) return 1;
+  }
+  return 0;
+}
+
+function object(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** Read and validate the checked-in release policy. A workaround without both a clear condition and expiry is invalid. */
+export function readReleaseOpsPolicy(path = DEFAULT_RELEASE_OPS_POLICY): ReleaseOpsPolicy {
+  const raw: unknown = parseYaml(readFileSync(path, 'utf8'));
+  if (!object(raw) || raw.schemaVersion !== 1 || !object(raw.gate) || !object(raw.gate.default)
+    || !Array.isArray(raw.gate.rehearsalDecisions) || !Array.isArray(raw.knownInterferences)) {
+    throw new Error('release ops policy has an unsupported or incomplete schema');
+  }
+  const validExecutor = (value: unknown): value is ReleaseGateExecutor => value === 'pod' || value === 'host';
+  const checkMethod = (method: unknown): boolean =>
+    object(method) && validExecutor(method.executor) && method.poolSource === 'config.release.loop.gatePodPool' && method.imagePin === 'cut-commit';
+  if (!checkMethod(raw.gate.default)) throw new Error('release ops policy default must pin executor, config pool, and cut commit image');
+  const defaultMethod = raw.gate.default as ReleaseOpsPolicy['gate']['default'];
+  const rehearsalDecisions: ReleaseOpsPolicy['gate']['rehearsalDecisions'] = [];
+  for (const decision of raw.gate.rehearsalDecisions) {
+    if (!object(decision) || typeof decision.id !== 'string' || !decision.id.trim() || !object(decision.when)
+      || typeof decision.when.outcome !== 'string' || (decision.when.executor !== undefined && !validExecutor(decision.when.executor))
+      || !checkMethod(decision)) throw new Error('release ops policy has an invalid rehearsal decision');
+    const valid = decision as ReleaseOpsPolicy['gate']['rehearsalDecisions'][number];
+    rehearsalDecisions.push({ id: valid.id, when: { outcome: valid.when.outcome,
+      ...(valid.when.executor !== undefined ? { executor: valid.when.executor } : {}) },
+    executor: valid.executor, poolSource: valid.poolSource, imagePin: valid.imagePin });
+  }
+  const knownInterferences: ReleaseOpsPolicy['knownInterferences'] = [];
+  for (const item of raw.knownInterferences) {
+    if (!object(item) || typeof item.id !== 'string' || !item.id.trim() || typeof item.observedVersion !== 'string'
+      || !RELEASE_VERSION.test(item.observedVersion) || typeof item.issue !== 'string' || !item.issue.trim() || !object(item.workaround)) {
+      throw new Error('release ops policy has an invalid known interference');
+    }
+    const workaround = item.workaround;
+    if (!validExecutor(workaround.executor) || typeof workaround.expiresAfterVersion !== 'string'
+      || !RELEASE_VERSION.test(workaround.expiresAfterVersion) || typeof workaround.clearCondition !== 'string' || !workaround.clearCondition.trim()) {
+      throw new Error('workaround must declare expiresAfterVersion and clearCondition');
+    }
+    knownInterferences.push({ id: item.id, observedVersion: item.observedVersion, issue: item.issue,
+      workaround: { executor: workaround.executor, expiresAfterVersion: workaround.expiresAfterVersion, clearCondition: workaround.clearCondition } });
+  }
+  return { schemaVersion: 1, gate: { default: defaultMethod, rehearsalDecisions }, knownInterferences };
+}
+
+/** Pick the executor from the release policy; the rehearsal can select a declared row but never create a new override. */
+export function selectReleaseGateMethod(input: { policy: ReleaseOpsPolicy; targetVersion: string; configuredPool?: string; rehearsal?: ReleaseGateRehearsal }): ReleaseGateMethodDecision {
+  const { policy, targetVersion, configuredPool, rehearsal } = input;
+  compareReleaseVersions(targetVersion, targetVersion);
+  const method = rehearsal
+    ? policy.gate.rehearsalDecisions.find((row) => row.when.outcome === rehearsal.outcome
+      && (row.when.executor === undefined || row.when.executor === rehearsal.executor))
+    : undefined;
+  const selected = method ?? policy.gate.default;
+  const expiredWorkarounds = policy.knownInterferences.filter((item) =>
+    compareReleaseVersions(targetVersion, item.workaround.expiresAfterVersion) > 0).map((item) => item.id);
+  return { executor: selected.executor, pool: selected.executor === 'pod' && typeof configuredPool === 'string' ? configuredPool.trim() : '',
+    imagePin: selected.imagePin, decision: method?.id ?? 'policy-default', rehearsalVersion: rehearsal?.version ?? null, expiredWorkarounds };
+}
+
+/** Read the latest hard rehearsal for a published version; malformed or mismatched stamps are not evidence. */
+export function readReleaseGateRehearsal(ledgerRoot: string, version: string): ReleaseGateRehearsal | undefined {
+  const dir = join(ledgerRoot, 'release', version, 'rehearsal');
+  let files: string[];
+  try { files = readdirSync(dir).filter((file) => /^hard-[a-z0-9-]+\.json$/.test(file)); }
+  catch { return undefined; }
+  const stamps: Array<{ endedAt: number; rehearsal?: ReleaseGateRehearsal }> = [];
+  for (const file of files) {
+    const path = join(dir, file);
+    const step = file.slice(0, -'.json'.length);
+    try {
+      const stamp = JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>;
+      const gate = stamp.hardGate as Record<string, unknown> | undefined;
+      const endedAt = typeof stamp.endedAt === 'string' ? Date.parse(stamp.endedAt) : NaN;
+      if (stamp.version !== version || stamp.step !== step || !Number.isFinite(endedAt)) return undefined;
+      const usable = ['ok', 'regression', 'error'].includes(String(gate?.outcome))
+        && typeof gate?.commit === 'string' && /^[a-f0-9]{40}$/i.test(gate.commit)
+        && (gate.executor === 'pod' || gate.executor === 'host');
+      stamps.push({ endedAt, ...(usable ? { rehearsal: { version, outcome: String(gate!.outcome), executor: gate!.executor as string, commit: gate!.commit as string } } : {}) });
+    } catch { return undefined; }
+  }
+  if (!stamps.length) return undefined;
+  stamps.sort((a, b) => b.endedAt - a.endedAt);
+  if (stamps.length > 1 && stamps[0]!.endedAt === stamps[1]!.endedAt) return undefined;
+  return stamps[0]!.rehearsal;
+}
+
 /** File seconds are recorded on the outer testsuite of each JUnit file, not its nested describe suites. */
 export function readJunitFileSeconds(xml: string): Map<string, number> {
   const secondsByFile = new Map<string, number>();