elanous 0.2.42 → 0.2.43

package/scripts/graph-units/land-enqueue.ts

@@ -2,6 +2,7 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { isAbsolute } from 'node:path';
 import { debug } from '../../src/debug/log.js';
+import { parseGraphTemplateYaml, type LandUnitTrainPolicySpec } from '../../src/self-implement/graph-yaml.js';
 
 type RecordValue = Record<string, unknown>;
 type EnqueueResult = {
@@ -10,6 +11,93 @@ type EnqueueResult = {
   evidence: RecordValue;
 };
 
+/** Facts collected by the train runner for one landing batch. Keep this input explicit:
+ * the graph unit enqueues one PR and cannot infer batch/theme/scenario facts itself. */
+export type LandTrainObservation = {
+  readonly express: boolean;
+  readonly waitedForBatch: boolean;
+  readonly batchSize: number;
+  readonly groupBy: readonly string[];
+  readonly waitMinutes: number;
+  readonly scenarioSource: string;
+  readonly mockUsed: boolean;
+  readonly gateRuns: number;
+  readonly land: {
+    readonly perPr: string;
+    readonly pinnedHead: boolean;
+    readonly ejectOnFail: boolean;
+    readonly integrationPr: boolean;
+  };
+};
+
+export type LandPolicyDrift = {
+  readonly field: string;
+  readonly expected: unknown;
+  readonly observed: unknown;
+};
+
+function sameMembers(actual: readonly string[], expected: readonly string[]): boolean {
+  return actual.length === expected.length && expected.every((value) => actual.includes(value));
+}
+
+/** Compare runner-measured facts with the declared policy. Missing/invalid facts are drift,
+ * never an implicit pass. Express work bypasses batch size/theme waiting as declared. */
+export function compareLandTrainPolicy(
+  policy: LandUnitTrainPolicySpec,
+  observed: LandTrainObservation,
+): LandPolicyDrift[] {
+  const drift: LandPolicyDrift[] = [];
+  const check = (field: string, expected: unknown, actual: unknown, matches: boolean): void => {
+    if (!matches) drift.push({ field, expected, observed: actual ?? null });
+  };
+  if (typeof observed.express !== 'boolean') {
+    check('/express', 'boolean', observed.express, false);
+  } else if (observed.express) {
+    check('/express/waitsForBatch', policy.express.waitsForBatch, observed.waitedForBatch, observed.waitedForBatch === policy.express.waitsForBatch);
+  } else {
+    const validSize = Number.isSafeInteger(observed.batchSize)
+      && observed.batchSize >= policy.batch.min && observed.batchSize <= policy.batch.max;
+    check('/batch/size', `${policy.batch.min}..${policy.batch.max}`, observed.batchSize, validSize);
+    check('/batch/groupBy', policy.batch.groupBy, observed.groupBy,
+      Array.isArray(observed.groupBy) && sameMembers(observed.groupBy, policy.batch.groupBy));
+    check('/batch/waitMinutes', `<=${policy.batch.maxWaitMin}`, observed.waitMinutes,
+      Number.isFinite(observed.waitMinutes) && observed.waitMinutes >= 0 && observed.waitMinutes <= policy.batch.maxWaitMin);
+  }
+  check('/scenarioPrebuild/source', policy.scenarioPrebuild.source, observed.scenarioSource,
+    policy.scenarioPrebuild.source.includes(observed.scenarioSource as typeof policy.scenarioPrebuild.source[number]));
+  check('/scenarioPrebuild/mock', policy.scenarioPrebuild.mock, observed.mockUsed,
+    observed.mockUsed === (policy.scenarioPrebuild.mock === 'required'));
+  check('/gate/runs', policy.gate.oncePerBatch ? 1 : 'unspecified', observed.gateRuns,
+    !policy.gate.oncePerBatch || observed.gateRuns === 1);
+  check('/land/perPr', policy.land.perPr, observed.land?.perPr, observed.land?.perPr === policy.land.perPr);
+  check('/land/pinnedHead', policy.land.pinnedHead, observed.land?.pinnedHead, observed.land?.pinnedHead === policy.land.pinnedHead);
+  check('/land/ejectOnFail', policy.land.ejectOnFail, observed.land?.ejectOnFail, observed.land?.ejectOnFail === policy.land.ejectOnFail);
+  check('/land/integrationPr', policy.land.integrationPr, observed.land?.integrationPr, observed.land?.integrationPr === policy.land.integrationPr);
+  return drift;
+}
+
+/** Runtime contract for the OP train runner: emit only on measured drift; tests inject the sink. */
+export function observeLandPolicyDrift(
+  policy: LandUnitTrainPolicySpec,
+  observed: LandTrainObservation,
+  emit: (event: 'land.policy-drift', payload: { drift: readonly LandPolicyDrift[] }) => void = (_event, payload) => {
+    debug.log('land', 'policy-drift', payload, { level: 'warn' });
+  },
+): LandPolicyDrift[] {
+  const drift = compareLandTrainPolicy(policy, observed);
+  if (drift.length > 0) emit('land.policy-drift', { drift });
+  return drift;
+}
+
+function observeEnvelopePolicy(context: RecordValue, emit?: Parameters<typeof observeLandPolicyDrift>[2]): void {
+  if (context.landTrainObservation === undefined) return;
+  const parsed = parseGraphTemplateYaml(readFileSync(new URL('../../graphs/units/land/land.yaml', import.meta.url), 'utf8'), 'land.yaml');
+  const policy = parsed.template?.policy;
+  if (!policy) throw new Error(`land policy unavailable: ${parsed.errors.map((issue) => issue.message).join('; ')}`);
+  // Runtime envelopes are untrusted; the comparator treats absent fields as drift evidence.
+  observeLandPolicyDrift(policy, record(context.landTrainObservation) as unknown as LandTrainObservation, emit);
+}
+
 function record(value: unknown): RecordValue {
   return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as RecordValue : {};
 }
@@ -29,8 +117,10 @@ export function runLandEnqueue(
   envelope: unknown,
   executable = process.env.ELANOUS_LAND_ENQUEUE,
   spawn: typeof spawnSync = spawnSync,
+  emitPolicyDrift?: Parameters<typeof observeLandPolicyDrift>[2],
 ): EnqueueResult {
   const context = record(record(envelope).context);
+  observeEnvelopePolicy(context, emitPolicyDrift);
   const rawPr = context.pr;
   const pr = typeof rawPr === 'number' ? rawPr : typeof rawPr === 'string' && /^\d+$/.test(rawPr) ? Number(rawPr) : NaN;
   const expectedHead = text(context.expectedHead);

package/scripts/hooks/codex-notify.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# ── Codex CLI notify hook — 손(hand) progress 전달 (HAND-HOOKS-NEXUS-STATUS · 2026-10-30) ──
+#
+# OP #54582 승인 · TC #54571 계약 기반. Codex notify 실행 시 알림 JSON 을 기존 계약
+# `POST /v1/missions/{missionId}/line`(src/agent-mission/mission-line.ts · postMissionLineEvent)로
+# **type:progress** 한 건만 보낸다. final 은 명시적 `mission reply --done` 전용,
+# ask/answer/correct 는 예약 — 이 훅은 progress 만 보낸다.
+#
+# 인증: missionId+attemptId+손별 Bearer. token 은 child env 에만 둔다:
+#   ELANOUS_HAND_TOKEN  — 손별 Bearer token(인자·파일 저장 금지)
+#   ELANOUS_MISSION_ID · ELANOUS_ATTEMPT_ID — 현재 미션/시도
+#   ELANOUS_NEXUS_URL — (선택) 계약 endpoint base
+# 자격이 없으면 조용히 exit 0(fail-soft — 훅이 Codex 를 막지 않는다).
+# PWA 손 카드 제외(TC graphEvents node-added kind=hand · DEMO1104-ARG-ADAPTIVE-VIEW가 렌더).
+# OSC 는 폴백이며 화면 scraping 은 하지 않는다. 병렬 송신 없음(Pod concurrency=1).
+#
+# 인자/stdin: Codex 가 주는 notify JSON {tool_name, cwd, ...} — Codex 는 notify JSON 을
+# 인자 하나(argv[1])로 넘기고, stdin 은 폴백이다.
+
+set -uo pipefail
+# Codex notify 프로그램 규약: JSON 을 argv[1] 로 받는다 — 인자가 없으면 stdin 을 읽는다.
+if [ "$#" -gt 0 ]; then INPUT="$1"; else INPUT="$(cat)"; fi
+
+HAND_CLI="$(cd "$(dirname "$0")/../.." && pwd)/src/agent-mission/hand-hooks.ts"
+
+if [ -n "${ELANOUS_HAND_TOKEN:-}" ] && [ -n "${ELANOUS_MISSION_ID:-}" ] && [ -n "${ELANOUS_ATTEMPT_ID:-}" ] \
+  && command -v bun >/dev/null 2>&1 && [ -f "$HAND_CLI" ]; then
+  # 논블로킹(백그라운드 &)·출력 버림 — notify 경로를 지연시키지 않는다.
+  printf '%s' "$INPUT" | bun "$HAND_CLI" codex-notify >/dev/null 2>&1 &
+fi
+
+exit 0

package/scripts/install.sh

@@ -154,7 +154,6 @@ missing_prerequisites() {
     command -v curl >/dev/null 2>&1 || MISSING+=(curl)
     command -v unzip >/dev/null 2>&1 || MISSING+=(unzip)   # bun 공식 설치기가 쓴다
   fi
-  command -v git >/dev/null 2>&1 || MISSING+=(git)
 }
 missing_prerequisites
 INSTALLED_DEPS=''
@@ -192,8 +191,9 @@ if ! command -v bun >/dev/null 2>&1 && [ "$BOOTSTRAP_BUN" -eq 1 ]; then
   fi
 fi
 
-# Keep this explicit set aligned with catalog/external-commands.yaml required entries.
-REQUIRED_COMMANDS=(git bun)
+# Git enables repository/worktree features but is not needed to boot the installed TUI.
+# Keep this set aligned with the runtime-required entries in catalog/external-commands.yaml.
+REQUIRED_COMMANDS=(bun)
 HARNESS_COMMANDS=(gh rg codex)
 for command in "${REQUIRED_COMMANDS[@]}"; do
   if ! command -v "$command" >/dev/null 2>&1; then
@@ -379,27 +379,23 @@ if [ ! -f "$VERSION_DIR/package.json" ]; then
 fi
 # 🩸 2026-09-24 빈 GCP VM 실측: `--offline` 만 쓰면 bun 캐시가 빈 새 기계에서 의존성이 «전부» failed to resolve — 어떤
 #    새 기계에서도 설치가 안 됐다(이 맥은 캐시가 차 있어 가려졌다). ⇒ 캐시로 먼저(빠르고 네트워크 없음) ⊕ 실패하면 레지스트리.
-# 🩸 2026-09-24 빈 VM 실측: apt `nodejs npm` 이 있으면 PATH 의 node(v18)·node-gyp(9.3.0)가 node-pty 를 빌드해
-#    bun 이 불러오는 순간 panic(uv_version_string)으로 죽었다. ⇒ 빌드 동안만 node=bun · node-gyp=최신 심을 PATH 앞에
-#    (src/native/native-build-env.ts 와 같은 심).
-NATIVE_SHIM="$(mktemp -d "${TMPDIR:-/tmp}/elanous-native-build.XXXXXX")"
-ln -s "$BUN_EXEC" "$NATIVE_SHIM/node"
-printf '#!/bin/sh\nexec "%s" x node-gyp@latest "$@"\n' "$BUN_EXEC" > "$NATIVE_SHIM/node-gyp"
-chmod +x "$NATIVE_SHIM/node-gyp"
-if ! (cd "$VERSION_DIR" && PATH="$NATIVE_SHIM:$PATH" bun add --no-save --offline "$INSTALL_TARBALL" >/dev/null 2>&1); then
+# Bun is the only runtime prerequisite. Skip lifecycle scripts: Bun otherwise runs optional
+# utf-8-validate native builds on bare Ubuntu and fails without Python/compiler. Optional prebuilt
+# packages (for example sharp) remain in the dependency graph.
+if ! (cd "$VERSION_DIR" && bun add --no-save --ignore-scripts --offline "$INSTALL_TARBALL" >/dev/null 2>&1); then
   echo "dependencies not in the local bun cache — fetching them from the npm registry" >&2
   # bun prints «Blocked N postinstalls» and progress noise here — keep it out of the screen unless this step fails.
   ADD_LOG="$(mktemp "${TMPDIR:-/tmp}/elanous-bun-add.XXXXXX")"
   ADD_RC=0
-  (cd "$VERSION_DIR" && PATH="$NATIVE_SHIM:$PATH" bun add --no-save "$INSTALL_TARBALL") >"$ADD_LOG" 2>&1 || ADD_RC=$?
+  (cd "$VERSION_DIR" && bun add --no-save --ignore-scripts "$INSTALL_TARBALL") >"$ADD_LOG" 2>&1 || ADD_RC=$?
   if [ "$ADD_RC" -ne 0 ]; then
     tail -n 20 "$ADD_LOG" >&2
-    rm -f "$ADD_LOG"; rm -rf "$NATIVE_SHIM"
+    rm -f "$ADD_LOG"
     exit "$ADD_RC"
   fi
   rm -f "$ADD_LOG"
 fi
-rm -rf "$NATIVE_SHIM"
+echo "If an optional native feature is unavailable, run 'elanous doctor --fix --yes' for repair guidance. The Bun TUI needs no system Node.js, Python, or compiler." >&2
 ln -sfn "versions/$VERSION_NAME" "$PREFIX/current"
 mkdir -p "$PREFIX/bin"
 # 절대 bun 경로를 설치 때 박고 엔트리는 current 를 거친다 — cron/systemd 의 짧은 PATH 와 판 전환 모두 지원.
@@ -478,30 +474,6 @@ if [ "$START_SETUP" -eq 0 ]; then
 fi
 # 🆕 2026-09-24 빈 VM 실측: 하니스(codex 백엔드)는 Codex CLI 를 자식으로 띄우는데 빈 기계엔 codex·node 가 «둘 다» 없었다.
 #    ⚠️ 아래 설치 줄은 빈 기계에서 아직 «안 쟀다» — `elanous doctor` 의 codex 줄이 판정한다.
-# C++20 toolchain must precede node-pty's rebuild; only suggest missing prerequisites.
-if ! command -v make >/dev/null 2>&1 || ! command -v c++ >/dev/null 2>&1; then
-  case "$(uname -s)" in
-    Darwin) BUILD_HINT='xcode-select --install' ;;
-    Linux)
-      OS_ID='' OS_LIKE=''
-      if [ -r "${ELANOUS_INSTALL_OS_RELEASE_FILE:-/etc/os-release}" ]; then
-        while IFS='=' read -r key value; do
-          value="${value#\"}"; value="${value%\"}"
-          case "$key" in ID) OS_ID="$value" ;; ID_LIKE) OS_LIKE="$value" ;; esac
-        done < "${ELANOUS_INSTALL_OS_RELEASE_FILE:-/etc/os-release}"
-      fi
-      BUILD_HINT=''
-      case " $OS_ID $OS_LIKE " in
-        *' debian '*|*' ubuntu '*) BUILD_HINT='sudo apt-get install -y build-essential' ;;
-        *' fedora '*) BUILD_HINT='sudo dnf groupinstall -y "Development Tools"' ;;
-      esac ;;
-    *) BUILD_HINT='' ;;
-  esac
-  if [ -n "$BUILD_HINT" ]; then
-    echo "  $STEP) $BUILD_HINT"; STEP=$((STEP + 1))
-  fi
-  echo "  $STEP) elanous doctor --fix --yes       # $(t 'rebuild node-pty after installing build tools' '빌드 도구를 깐 뒤 node-pty 다시 빌드')"; STEP=$((STEP + 1))
-fi
 if ! command -v rg >/dev/null 2>&1; then
   if [ -z "${OS_ID:-}" ] && [ -r "${ELANOUS_INSTALL_OS_RELEASE_FILE:-/etc/os-release}" ]; then
     while IFS='=' read -r key value; do

package/scripts/landing-heal/land-plan.ts

@@ -0,0 +1,57 @@
+#!/usr/bin/env bun
+import { existsSync, readFileSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { planTrain, type TrainCandidate, type TrainDeferred } from '../../src/self-implement/merge-train.js';
+import type { L8ShadowQueueState } from '../../src/self-implement/l8-merge-queue.js';
+
+export const LAND_PLAN_MAX_BATCH = 8;
+
+type LandPlan = { batch: TrainCandidate[]; deferred: TrainDeferred[] };
+
+function inputPath(args: readonly string[]): string {
+  if (args.length !== 2 || args[0] !== '--input') throw new Error('usage: land-plan.ts --input <absolute-json-path>');
+  const path = args[1];
+  if (!path || !isAbsolute(path)) throw new Error('--input requires an absolute path');
+  if (!existsSync(path)) throw new Error('input file missing');
+  return path;
+}
+
+function isQueueState(value: unknown): value is L8ShadowQueueState {
+  if (!value || typeof value !== 'object' || !('pending' in value) || !Array.isArray(value.pending)
+    || !value.pending.every((item) => item && typeof item === 'object'
+      && Number.isSafeInteger(item.number) && item.number > 0
+      && typeof item.head === 'string' && /^[0-9a-f]{40}$/i.test(item.head)
+      && (item.files === undefined || Array.isArray(item.files) && item.files.every((file: unknown) => typeof file === 'string'))
+      && (item.filesUnmeasured === undefined || item.filesUnmeasured === true))
+    || !('verdicts' in value) || !Array.isArray(value.verdicts)
+    || !('deferred' in value ? Array.isArray(value.deferred) : true)) return false;
+  return true;
+}
+
+function candidates(state: L8ShadowQueueState): TrainCandidate[] {
+  return state.pending.map(({ number, head, files, filesUnmeasured }) => ({
+    number,
+    head,
+    ...(files === undefined ? {} : { files }),
+    ...(filesUnmeasured === undefined ? {} : { filesUnmeasured }),
+  }));
+}
+
+export function planLandQueue(state: unknown): LandPlan {
+  if (!isQueueState(state)) throw new Error('invalid shadow queue ledger');
+  return planTrain(candidates(state), { maxBatch: LAND_PLAN_MAX_BATCH });
+}
+
+export function runLandPlan(args: readonly string[]): LandPlan {
+  const state: unknown = JSON.parse(readFileSync(inputPath(args), 'utf8'));
+  return planLandQueue(state);
+}
+
+if (import.meta.main) {
+  try {
+    process.stdout.write(`${JSON.stringify(runLandPlan(process.argv.slice(2)))}\n`);
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+}

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-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>();