elanous 0.2.41 → 0.2.43

package/src/self-implement/run-stop.ts

@@ -10,13 +10,19 @@
  * ⭐ 이 스키마(`RunStopRecord`·`RUN_STOP_CLASSES`)는 STOP-AUTOHEAL 이 읽는다 — 칸 이름·닫힌 목록을 바꾸지 않는다(더하기만).
  */
 import { debug } from '../debug/log.js';
-import { appendRunLedgerEntry, type RunLedgerEntry, type RunLedgerWriter, type RunShardIdentity } from './run-ledger.js';
+import { createHash } from 'node:crypto';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { appendRunLedgerEntry, runLedgerDir, runLedgerPath, type RunLedgerEntry, type RunLedgerWriter, type RunShardIdentity } from './run-ledger.js';
 import type { PodChildEvidence } from '../task-orchestrator/surfaces/self-implement.js';
+import { defaultOverlaysDir, loadGraphOverlays } from './graph-overlay-yaml.js';
 
 /** 닫힌 목록 — 못 고르면 `unclassified`. */
 export const RUN_STOP_CLASSES = [
   'env-unrelated', 'main-sync', 'pod-died', 'pod-vanished', 'review-repeat',
-  'review-out-of-scope', 'review-budget-exhausted', 'scope-escape', 'evidence-uncovered', 'fabric', 'launch-failed', 'gate-failed', 'unclassified',
+  'review-out-of-scope', 'review-budget-exhausted', 'scope-escape', 'evidence-uncovered', 'fabric', 'launch-failed', 'gate-failed',
+  'implement-aborted', 'out-of-scope-held', 'provider-auth-missing', 'provider-unavailable',
+  'merge-held-release-path', 'pr-guard-failed', 'gate-unmeasured', 'unclassified',
 ] as const;
 export type RunStopClass = typeof RUN_STOP_CLASSES[number];
 
@@ -35,6 +41,32 @@ export interface RunStopRecord {
   childEvidence?: PodChildEvidence;
   /** Exact structured Pod error code, when the host received one. */
   terminationReason?: 'pod-job-failed';
+  /** Safe terminal-attempt facts and a digest-addressed artifact; raw provider/child text is excluded. */
+  terminalEvidence?: RunStopTerminalEvidence;
+}
+
+export type RunStopReasonCode = 'tdd-evidence-missing' | 'goal-only-same-cell' | 'decomposition-401-invalid-api-key' | 'provider-credential-failure' | 'unknown';
+export type RunStopFact = string | number | boolean | 'unknown';
+export interface RunStopChildAttempt {
+  childRunId: RunStopFact;
+  job: RunStopFact;
+  attempt: RunStopFact;
+  stage: RunStopFact;
+  outcome: RunStopFact;
+  exitCode: RunStopFact;
+  reasonCode: RunStopReasonCode;
+}
+export interface RunStopTerminalEvidence {
+  childRunId: RunStopFact;
+  job: RunStopFact;
+  attempt: RunStopFact;
+  stage: RunStopFact;
+  node: RunStopFact;
+  outcome: RunStopFact;
+  exitCode: RunStopFact;
+  reasonCode: RunStopReasonCode;
+  childAttempts: RunStopChildAttempt[];
+  detailArtifact: { path: RunStopFact; byteLength: RunStopFact; sha256: RunStopFact };
 }
 
 export const RUN_STOP_EVENT = 'stop';
@@ -62,6 +94,127 @@ export interface RunStopInput {
   site?: string;
   childEvidence?: PodChildEvidence;
   terminationReason?: 'pod-job-failed';
+  terminalEvidence?: Omit<RunStopTerminalEvidence, 'detailArtifact'>;
+  /** Test seam; production persists only the sanitized structured artifact. */
+  writeEvidenceArtifact?: (path: string, bytes: Buffer) => void;
+}
+
+const UNKNOWN: RunStopFact = 'unknown';
+const SAFE_TOKEN = /^[a-zA-Z0-9][a-zA-Z0-9._:/-]{0,159}$/u;
+const RUN_STOP_REASON_CODES: readonly RunStopReasonCode[] = ['tdd-evidence-missing', 'goal-only-same-cell', 'decomposition-401-invalid-api-key', 'provider-credential-failure', 'unknown'];
+
+function safeRunStopFact(value: unknown): RunStopFact {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'number') return Number.isSafeInteger(value) ? value : UNKNOWN;
+  if (typeof value !== 'string' || !value.trim() || !SAFE_TOKEN.test(value.trim())) return UNKNOWN;
+  return value.trim();
+}
+
+function safeRunStopReasonCode(value: unknown): RunStopReasonCode {
+  return typeof value === 'string' && (RUN_STOP_REASON_CODES as readonly string[]).includes(value) ? value as RunStopReasonCode : 'unknown';
+}
+
+function writeTerminalEvidenceArtifact(input: RunStopInput, record: Omit<RunStopRecord, 'terminalEvidence'>): RunStopTerminalEvidence | undefined {
+  if (!input.terminalEvidence) return undefined;
+  const facts = input.terminalEvidence;
+  const safeEvidence = {
+    childRunId: safeRunStopFact(facts.childRunId), job: safeRunStopFact(facts.job), attempt: safeRunStopFact(facts.attempt),
+    stage: safeRunStopFact(facts.stage), node: safeRunStopFact(facts.node), outcome: safeRunStopFact(facts.outcome),
+    exitCode: safeRunStopFact(facts.exitCode), reasonCode: safeRunStopReasonCode(facts.reasonCode),
+    childAttempts: facts.childAttempts.slice(-8).map((item) => ({
+      childRunId: safeRunStopFact(item.childRunId), job: safeRunStopFact(item.job), attempt: safeRunStopFact(item.attempt),
+      stage: safeRunStopFact(item.stage), outcome: safeRunStopFact(item.outcome), exitCode: safeRunStopFact(item.exitCode),
+      reasonCode: safeRunStopReasonCode(item.reasonCode),
+    })),
+  };
+  const bytes = Buffer.from(`${JSON.stringify({ runId: input.runId, site: safeRunStopFact(input.site), class: record.class, terminalEvidence: safeEvidence }, null, 2)}\n`, 'utf8');
+  try {
+    // Validate the run id through the canonical ledger contract before using it in a path.
+    runLedgerPath(input.runId);
+    const path = join(runLedgerDir(), 'stop-cause-evidence', `${input.runId}.json`);
+    if (input.writeEvidenceArtifact) input.writeEvidenceArtifact(path, bytes);
+    else {
+      mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+      writeFileSync(path, bytes, { mode: 0o600 });
+    }
+    return { ...safeEvidence, detailArtifact: { path, byteLength: bytes.byteLength, sha256: createHash('sha256').update(bytes).digest('hex') } };
+  } catch {
+    return { ...safeEvidence, detailArtifact: { path: UNKNOWN, byteLength: UNKNOWN, sha256: UNKNOWN } };
+  }
+}
+
+/** Classify only named failure markers. Free-form strings are inspected, never copied to durable evidence. */
+export function classifyRunStopReason(input: { detail?: unknown; terminationReason?: unknown; providerErrorCategory?: unknown; observedText?: readonly unknown[] }): RunStopReasonCode {
+  const text = [input.detail, ...(input.observedText ?? [])].filter((value): value is string => typeof value === 'string').join('\n').toLowerCase();
+  if (input.terminationReason === 'goal-only-rework-exhausted') return 'goal-only-same-cell';
+  if (/goal-only-rework-exhausted/u.test(text)) return 'goal-only-same-cell';
+  if (/tdd-evidence-missing/u.test(text)) return 'tdd-evidence-missing';
+  // Require a decomposition context as well as both credential markers; generic 401s are not this diagnosis.
+  if (/decompos.{0,256}\b401\b.{0,256}invalid api key|decompos.{0,256}invalid api key.{0,256}\b401\b|decomposition-401-invalid-api-key/u.test(text)) return 'decomposition-401-invalid-api-key';
+  if (input.providerErrorCategory === 'credential') return 'provider-credential-failure';
+  return 'unknown';
+}
+
+/** Extract child attempt metadata without carrying untrusted child/provider text into the stop artifact. */
+export function runStopChildAttempts(entries: readonly RunLedgerEntry[], classify: (values: readonly unknown[]) => RunStopReasonCode = () => 'unknown'): RunStopChildAttempt[] {
+  const attempts: RunStopChildAttempt[] = [];
+  const attemptByJob = new Map<string, number>();
+  for (const entry of entries) {
+    const data = entry.data;
+    if (entry.event === 'pod-oom-retry-intent') {
+      if (typeof data.job === 'string' && Number.isSafeInteger(data.attempt) && typeof data.attempt === 'number') attemptByJob.set(data.job, data.attempt);
+      continue;
+    }
+    if (entry.event !== 'pod-child-evidence') continue;
+    const childRunId = safeRunStopFact(data.childRunId);
+    const childResult = data.childResult && typeof data.childResult === 'object' && !Array.isArray(data.childResult) ? data.childResult as Record<string, unknown> : {};
+    const pod = data.podTermination && typeof data.podTermination === 'object' && !Array.isArray(data.podTermination) ? data.podTermination as Record<string, unknown> : {};
+    const text = [childResult.error, data.childEvidence, entry.data].filter((value) => value !== undefined);
+    const stage = safeRunStopFact(childResult.stage);
+    const exitCode = safeRunStopFact(pod.exitCode);
+    const childOutcome = typeof childResult.ok === 'boolean' ? (childResult.ok ? 'completed' : 'failed')
+      : typeof exitCode === 'number' ? (exitCode === 0 ? 'completed' : 'failed') : UNKNOWN;
+    const job = safeRunStopFact(data.job);
+    attempts.push({ childRunId, job, attempt: typeof job === 'string' ? attemptByJob.get(job) ?? UNKNOWN : UNKNOWN,
+      stage, outcome: childOutcome, exitCode, reasonCode: classify(text) });
+  }
+  return attempts.slice(-8);
+}
+
+/** Join the final outcome to the latest recorded child attempt; missing fields stay explicit unknowns. */
+export function buildRunStopTerminalEvidence(input: {
+  stage: unknown;
+  node: unknown;
+  outcome: unknown;
+  detail?: unknown;
+  terminationReason?: unknown;
+  providerErrorCategory?: unknown;
+  entries: readonly RunLedgerEntry[];
+}): Omit<RunStopTerminalEvidence, 'detailArtifact'> {
+  const observedText = input.entries
+    .filter((entry) => entry.event === 'pod-child-evidence' || entry.event.includes('decomposition'))
+    .map((entry) => {
+      try { return `${entry.event} ${JSON.stringify(entry.data)}`.slice(0, 24_000); } catch { return ''; }
+    }).filter(Boolean);
+  const classify = (values: readonly unknown[]) => classifyRunStopReason({
+    observedText: values.map((value) => typeof value === 'string' ? value : (() => { try { return JSON.stringify(value); } catch { return ''; } })()),
+  });
+  const childAttempts = runStopChildAttempts(input.entries, classify);
+  const current = childAttempts.at(-1);
+  const classified = classifyRunStopReason({ detail: input.detail, terminationReason: input.terminationReason,
+    providerErrorCategory: input.providerErrorCategory, observedText: observedText.slice(-1) });
+  const reasonCode = classified !== 'unknown' ? classified : current?.reasonCode ?? 'unknown';
+  return {
+    childRunId: current?.childRunId ?? UNKNOWN,
+    job: current?.job ?? UNKNOWN,
+    attempt: current?.attempt ?? UNKNOWN,
+    stage: safeRunStopFact(input.stage),
+    node: safeRunStopFact(input.node),
+    outcome: safeRunStopFact(input.outcome),
+    exitCode: current?.exitCode ?? UNKNOWN,
+    reasonCode,
+    childAttempts,
+  };
 }
 
 export function isRunStopClass(value: unknown): value is RunStopClass {
@@ -79,6 +232,8 @@ export function boundRunStopCause(raw: string): string {
 /** 병합 보류 사유 → 닫힌 목록. 모르면 `unclassified`. */
 export function classifyMergeHoldStop(mergeReason: string | undefined): RunStopClass {
   const reason = mergeReason ?? '';
+  const graphClass = classifyStopReasonFromGraph(reason);
+  if (graphClass) return graphClass;
   if (reason.startsWith('main-sync') || reason === 'default-branch-unresolved') return 'main-sync';
   if (reason === 'required-evidence-uncovered') return 'evidence-uncovered';
   if (reason.startsWith('review-budget')) return 'review-budget-exhausted';
@@ -100,11 +255,21 @@ export function classifyPodExitStop(reason: string | undefined, stage?: string):
 /** Terminal implementation failures are classified only after the inner repair/round budget has ended. */
 export function classifyTerminalHarnessFailure(input: {
   stage: string;
+  cause?: string;
   mergeReason?: string;
   abandonedClassification?: string;
   providerErrorCategory?: string;
   supervisorVerdict?: string;
 }): RunStopClass {
+  const graphClass = classifyStopReasonFromGraph(input.cause ?? input.mergeReason ?? '');
+  if (graphClass) return graphClass;
+  if (input.abandonedClassification === 'implement-aborted') return 'implement-aborted';
+  if (input.abandonedClassification === 'out-of-scope-held') return 'out-of-scope-held';
+  if (input.providerErrorCategory === 'credential' || input.providerErrorCategory === 'provider-auth-missing') return 'provider-auth-missing';
+  if (input.providerErrorCategory === 'provider-unavailable') return 'provider-unavailable';
+  if (input.mergeReason === 'release-path-hold') return 'merge-held-release-path';
+  if (input.mergeReason === 'pr-guard-failed') return 'pr-guard-failed';
+  if (input.mergeReason === 'gate-unmeasured') return 'gate-unmeasured';
   if (input.mergeReason) return classifyMergeHoldStop(input.mergeReason);
   if (input.providerErrorCategory === 'credential' || input.abandonedClassification === 'credential-failure') return 'launch-failed';
   if (input.abandonedClassification === 'report-deficit') return 'pod-died';
@@ -115,6 +280,21 @@ export function classifyTerminalHarnessFailure(input: {
   return 'unclassified';
 }
 
+/** Exact reason vocabulary declared by heal graph overlays; unknown phrases remain unclassified. */
+export function classifyStopReasonFromGraph(reason: string): RunStopClass | undefined {
+  const normalized = reason.trim().toLowerCase();
+  if (!normalized) return undefined;
+  try {
+    for (const overlay of loadGraphOverlays(defaultOverlaysDir()).overlays) {
+      for (const [phrase, cls] of Object.entries(overlay.reasonMap ?? {})) {
+        const escaped = phrase.toLowerCase().replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        if (new RegExp(`(^|[^a-z0-9])${escaped}([^a-z0-9]|$)`).test(normalized) && isRunStopClass(cls)) return cls;
+      }
+    }
+  } catch { /* malformed or unavailable graph declarations are not classifier evidence */ }
+  return undefined;
+}
+
 /** 이 프로세스에서 stop 을 이미 쓴 런 — 한 런이 두 자리(예: draft PR 실패 ⊕ aborted)에서 두 줄을 쓰지 않게. */
 const recordedThisProcess = new Set<string>();
 const RECORDED_MAX = 4096;
@@ -131,7 +311,7 @@ export function forgetRunStop(runId: string): void {
 
 /** 멈춘 런에 stop 한 줄을 더한다 — 기존 관측은 바꾸지 않는다. 쓴 줄을 돌려준다. */
 export function recordRunStop(input: RunStopInput, write: RunLedgerWriter = appendRunLedgerEntry): RunLedgerEntry {
-  const record: RunStopRecord = {
+  const base: Omit<RunStopRecord, 'terminalEvidence'> = {
     class: isRunStopClass(input.class) ? input.class : 'unclassified',
     ...(input.site ? { site: input.site } : {}),
     cause: boundRunStopCause(input.cause),
@@ -140,6 +320,8 @@ export function recordRunStop(input: RunStopInput, write: RunLedgerWriter = appe
     ...(input.childEvidence ? { childEvidence: input.childEvidence } : {}),
     ...(input.terminationReason ? { terminationReason: input.terminationReason } : {}),
   };
+  const terminalEvidence = writeTerminalEvidenceArtifact(input, base);
+  const record: RunStopRecord = { ...base, ...(terminalEvidence ? { terminalEvidence } : {}) };
   const entry: RunLedgerEntry = {
     timestamp: new Date().toISOString(), runId: input.runId, event: RUN_STOP_EVENT,
     data: { ...record },
@@ -153,6 +335,7 @@ export function recordRunStop(input: RunStopInput, write: RunLedgerWriter = appe
     try { listener(entry); } catch { /* wake consumers cannot change run outcome */ }
   }
   try {
+    debug.log('self-implement.run-stop', 'cause-classified', { runId: input.runId, terminalEvidence });
     debug.log('self-implement.run-stop', 'recorded', { runId: input.runId, site: input.site ?? null, ...record, requestedClass: input.class ?? null });
   } catch { /* observation is fail-soft */ }
   return entry;
@@ -166,5 +349,6 @@ export function readRunStopRecord(entry: RunLedgerEntry): RunStopRecord | undefi
   return { class: isRunStopClass(data.class) ? data.class : 'unclassified', cause: data.cause, evidenceRef: data.evidenceRef, nextMove: data.nextMove,
     ...(typeof data.site === 'string' ? { site: data.site } : {}),
     ...(data.childEvidence ? { childEvidence: data.childEvidence } : {}),
-    ...(data.terminationReason === 'pod-job-failed' ? { terminationReason: data.terminationReason } : {}) };
+    ...(data.terminationReason === 'pod-job-failed' ? { terminationReason: data.terminationReason } : {}),
+    ...(data.terminalEvidence && typeof data.terminalEvidence === 'object' ? { terminalEvidence: data.terminalEvidence as RunStopTerminalEvidence } : {}) };
 }

package/src/self-implement/runtime-overlay-run-steps.ts

@@ -0,0 +1,95 @@
+import type { GraphTemplate } from './graph-templates.js';
+import type { GraphTemplateSpec } from './graph-yaml.js';
+import type { RunLedgerEntry } from './run-ledger.js';
+
+type RuntimeOverlayGraph = Pick<GraphTemplate, 'nodes' | 'edges'> | Pick<GraphTemplateSpec, 'nodes' | 'edges'>;
+
+const DEFAULT_OUTCOME = '$default';
+const ABSENT_ROUTE = '$absent';
+
+export interface RuntimeOverlayRunStepsInput {
+  readonly runId: string;
+  readonly timestamp: string;
+  readonly before: RuntimeOverlayGraph;
+  readonly after: RuntimeOverlayGraph;
+  readonly overlayIds: readonly string[];
+  readonly round: number;
+}
+
+interface GraphRoute {
+  readonly from: string;
+  readonly outcome: string;
+  readonly to: string;
+}
+
+function routesOf(graph: RuntimeOverlayGraph): Map<string, GraphRoute> {
+  const routes = new Map<string, GraphRoute>();
+  if (!Array.isArray(graph.edges)) {
+    const compiledEdges = graph.edges as Readonly<Record<string, readonly string[]>>;
+    for (const [from, destinations] of Object.entries(compiledEdges)) {
+      for (const [index, to] of destinations.entries()) {
+        routes.set(`${from}\u0000${index}`, { from, outcome: String(index), to: String(to) });
+      }
+    }
+    return routes;
+  }
+  for (const edge of graph.edges) {
+    if (edge.to !== undefined) {
+      routes.set(`${edge.from}\u0000${DEFAULT_OUTCOME}`, { from: edge.from, outcome: DEFAULT_OUTCOME, to: edge.to });
+      continue;
+    }
+    for (const [outcome, to] of Object.entries(edge.map ?? {})) {
+      routes.set(`${edge.from}\u0000${outcome}`, { from: edge.from, outcome, to: String(to) });
+    }
+  }
+  return routes;
+}
+
+function reason(input: RuntimeOverlayRunStepsInput): string {
+  return `runtime overlay ${input.overlayIds.join(', ')} applied at round ${input.round}`;
+}
+
+/** Convert an already accepted runtime overlay into the existing structural ledger vocabulary. */
+export function runtimeOverlayRunSteps(input: RuntimeOverlayRunStepsInput): RunLedgerEntry[] {
+  if (input.overlayIds.length === 0) return [];
+  const detail = reason(input);
+  const beforeNodes = new Set(input.before.nodes.map((node) => node.nodeId));
+  const entries: RunLedgerEntry[] = input.after.nodes
+    .filter((node) => !beforeNodes.has(node.nodeId))
+    .map((node) => ({
+      timestamp: input.timestamp,
+      runId: input.runId,
+      event: 'node-added',
+      data: {
+        node: node.nodeId,
+        kind: node.kind,
+        decider: 'runtime-overlay',
+        reason: detail,
+        trigger: { overlayIds: input.overlayIds, round: input.round },
+      },
+    }));
+
+  const beforeRoutes = routesOf(input.before);
+  const afterRoutes = routesOf(input.after);
+  const changedRoutes = [...afterRoutes.entries()]
+    .filter(([key, route]) => beforeRoutes.get(key)?.to !== route.to)
+    .sort(([left], [right]) => left.localeCompare(right));
+  for (const [key, route] of changedRoutes) {
+    entries.push({
+      timestamp: input.timestamp,
+      runId: input.runId,
+      event: 'edge-rerouted',
+      data: {
+        from: route.from,
+        outcome: route.outcome,
+        to: route.to,
+        was: beforeRoutes.get(key)?.to ?? ABSENT_ROUTE,
+        decider: 'runtime-overlay',
+        reason: detail,
+      },
+    });
+  }
+  return entries;
+}
+
+export { ABSENT_ROUTE, DEFAULT_OUTCOME };

package/src/self-implement/stop-autoheal.ts

@@ -46,6 +46,11 @@ export type AutohealAction =
   | 'resume-from-salvage'
   | 'derive-evidence-rejudge'
   | 'review-round-reauthor'
+  | 'reauthor-from-materialized'
+  | 'switch-provider'
+  | 'retry-provider'
+  | 'wait-release'
+  | 'remeasure-gate'
   | 'needs-owner';
 
 /** 닫힌 목록 전체를 덮는다 — 새 class 가 생기면 여기서 타입 오류가 난다. */
@@ -64,11 +69,19 @@ export const AUTOHEAL_ACTION_BY_CLASS: Readonly<Record<RunStopClass, AutohealAct
   'launch-failed': 'needs-owner',
   'gate-failed': 'needs-owner',
   unclassified: 'needs-owner',
+  'implement-aborted': 'reauthor-from-materialized',
+  'out-of-scope-held': 'reauthor-from-materialized',
+  'provider-auth-missing': 'switch-provider',
+  'provider-unavailable': 'retry-provider',
+  'merge-held-release-path': 'wait-release',
+  'pr-guard-failed': 'reauthor-from-materialized',
+  'gate-unmeasured': 'remeasure-gate',
 };
 
 /** 처방 노드 id 로 인정하는 이름 — 오버레이가 더한 노드 중 이 넷만 처방으로 읽는다. */
 const HEAL_ACTION_NODE_IDS: ReadonlySet<string> = new Set<Exclude<AutohealAction, 'needs-owner'>>([
   'clean-workspace-regate', 'rebase-regate', 'resume-from-salvage', 'derive-evidence-rejudge', 'review-round-reauthor',
+  'reauthor-from-materialized', 'switch-provider', 'retry-provider', 'wait-release', 'remeasure-gate',
 ]);
 
 /** 처방이 «어디서» 왔나 — `graph` = 그 갈래에 얹힌 오버레이가 더한 노드 · `code-default` = 위 표. */

package/src/self-implement/tdd-evidence-tags.ts

@@ -0,0 +1,9 @@
+/** Stable TDD terminal-evidence tags shared by the producer and Pod result mapper. */
+export const TDD_RED_TAG = 'tdd-red' as const;
+export const TDD_GREEN_TAG = 'tdd-green' as const;
+export const TDD_RECORD_TAGS = [TDD_RED_TAG, TDD_GREEN_TAG] as const;
+export type TddRecordTag = typeof TDD_RECORD_TAGS[number];
+
+export function isTddRecordTag(value: unknown): value is TddRecordTag {
+  return value === TDD_RED_TAG || value === TDD_GREEN_TAG;
+}

package/src/self-implement/train-gate-receipt.ts

@@ -0,0 +1,166 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { SPAWN_SYNC_MAX_BUFFER } from '../util/spawn-sync-output.js';
+import {
+  computeReceiptKey,
+  gateEnvFingerprint,
+  gateLockfileHash,
+  GATE_RECEIPT_SCHEMA,
+  loadGateReceipts,
+  saveGateReceipt,
+  type GateReceipt,
+  type GateReceiptIdentity,
+} from './gate-receipt-registry.js';
+
+export interface TrainGateReceiptInput {
+  repo: string;
+  commit: string;
+  baseSha: string;
+  changedFiles: readonly string[];
+  deletedFiles?: readonly string[];
+  scenarioTests?: readonly string[];
+}
+
+export interface PassedSelfGateReceiptInput extends TrainGateReceiptInput {
+  /** Exact artifact emitted by `self gate --artifact-dir`; its pass and typecheck binding are revalidated here. */
+  summaryPath: string;
+}
+
+type Execute = (script: string, cwd: string) => { status: number | null; stdout: string; stderr: string };
+
+const SHA40 = /^[0-9a-f]{40}$/i;
+const TEST_FILE = /\.test\.[cm]?[jt]sx?$/;
+const quote = (value: string) => `'${value.replaceAll("'", `'\\''`)}'`;
+
+function registryPath(repo: string): string | undefined {
+  const result = spawnSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], { cwd: repo, encoding: 'utf8', timeout: 10_000, maxBuffer: SPAWN_SYNC_MAX_BUFFER });
+  const commonDir = (result.stdout ?? '').trim();
+  return result.status === 0 && commonDir ? join(commonDir, 'elanous-host-regate', 'gate-receipts.json') : undefined;
+}
+
+function identityFor(input: TrainGateReceiptInput, checks?: readonly string[]): GateReceiptIdentity | undefined {
+  if (!SHA40.test(input.commit) || !SHA40.test(input.baseSha)) return undefined;
+  const bun = spawnSync('bun', ['--version'], { cwd: input.repo, encoding: 'utf8', timeout: 10_000, maxBuffer: SPAWN_SYNC_MAX_BUFFER });
+  const bunVersion = (bun.stdout ?? '').trim();
+  if (bun.status !== 0 || !bunVersion) return undefined;
+  return {
+    headCommit: input.commit,
+    baseCommit: input.baseSha,
+    bunVersion,
+    lockfileHash: gateLockfileHash(input.repo),
+    radiusFiles: [...new Set(input.changedFiles)].sort(),
+    checks: checks ? [...checks] : [
+      'train:changed-file-typecheck',
+      ...(input.scenarioTests?.length || input.changedFiles.some((file) => TEST_FILE.test(file) && !input.deletedFiles?.includes(file)) ? ['train:deterministic-tests'] : []),
+      ...(input.scenarioTests ?? []).map((file) => `train:scenario-test:${file}`),
+      'train:pwa-build',
+    ],
+    envFingerprint: gateEnvFingerprint(process.env),
+  };
+}
+
+/** Record only after revalidating the exact self-gate summary, then independently measure changed-only interference. */
+export async function recordPassedSelfGateReceipt(
+  input: PassedSelfGateReceiptInput,
+  detect: (files: readonly string[]) => Promise<{ status: 'no-interference' | 'interference' | 'unmeasurable' }> = async (files) => {
+    const { detectTestInterference } = await import('../../scripts/detect-test-interference.js');
+    return detectTestInterference(files);
+  },
+): Promise<GateReceipt | undefined> {
+  let summary: Record<string, unknown>;
+  try { summary = JSON.parse(readFileSync(input.summaryPath, 'utf8')) as Record<string, unknown>; }
+  catch { return undefined; }
+  const typecheck = summary.typecheck as Record<string, unknown> | undefined;
+  const cohort = Array.isArray(summary.cohort) ? summary.cohort.filter((file): file is string => typeof file === 'string') : [];
+  const changedTestFiles = [...new Set(input.changedFiles.filter((file) => TEST_FILE.test(file)
+    && !input.deletedFiles?.includes(file)))].sort();
+  if (summary.head40 !== input.commit || summary.base40 !== input.baseSha || summary.exitCode !== 0
+    || !['passed', 'pass'].includes(String(summary.verdict)) || summary.introduced !== 0
+    || summary.unknown !== 0 || summary.unrunImporters !== 0
+    || typecheck?.status !== 'passed' || typecheck.base40 !== input.baseSha
+    || typecheck.head40 !== input.commit || typecheck.exitCode !== 0 || typecheck.newErrors !== 0
+    || changedTestFiles.some((file) => !cohort.includes(file))) return undefined;
+  const testFiles = [...new Set(input.changedFiles.filter((file) => TEST_FILE.test(file)
+    && !input.deletedFiles?.includes(file)))].sort();
+  if (!testFiles.length) return undefined;
+  const interference = await detect(testFiles);
+  if (interference.status !== 'no-interference') return undefined;
+  const identity = identityFor(input, ['test-interference:changed-only']);
+  const path = process.env.ELANOUS_GATE_RECEIPT_REGISTRY_PATH || registryPath(input.repo);
+  if (!identity || !path) return undefined;
+  const receipt = passedEvidenceReceipt(identity, input.changedFiles);
+  try { saveGateReceipt(path, receipt); }
+  catch { return undefined; }
+  return receipt;
+}
+
+function scriptFor(input: TrainGateReceiptInput, files: readonly string[]): string {
+  const tests = [...new Set([
+    ...files.filter((file) => TEST_FILE.test(file) && !input.deletedFiles?.includes(file)),
+    ...(input.scenarioTests ?? []),
+  ])];
+  return [
+    `TSC_BASE_REF=${quote(input.baseSha)} bun scripts/ci-typecheck-changed.ts --local`,
+    ...(tests.length ? [`bun run test:deterministic ${tests.map(quote).join(' ')}`] : []),
+    `bun scripts/ci-pwa-build-gate.ts --changed-files ${files.map(quote).join(' ')}`,
+  ].join(' && ');
+}
+
+function passedEvidenceReceipt(identity: GateReceiptIdentity, files: readonly string[]): GateReceipt {
+  const receiptIdentity: GateReceiptIdentity = { ...identity, radiusFiles: [...new Set(files)].sort() };
+  return {
+    ...receiptIdentity,
+    schema: GATE_RECEIPT_SCHEMA,
+    key: computeReceiptKey(receiptIdentity, 'passed'),
+    verdict: 'passed',
+    savedAt: new Date().toISOString(),
+  };
+}
+
+export function runTrainGateWithReceipts(input: TrainGateReceiptInput, execute: Execute = (script, cwd) => {
+  const result = spawnSync('sh', ['-c', script], { cwd, encoding: 'utf8', timeout: 120 * 60_000, maxBuffer: 32 * 1024 * 1024 });
+  return { status: result.status, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+}): { status: number | null; stdout: string; stderr: string } {
+  const context = identityFor(input);
+  const path = process.env.ELANOUS_GATE_RECEIPT_REGISTRY_PATH || registryPath(input.repo);
+  if (!context || !path) return execute(scriptFor(input, input.changedFiles), input.repo);
+
+  const changedFiles = [...new Set(input.changedFiles)].sort();
+  const result = execute(scriptFor(input, changedFiles), input.repo);
+  if (result.status === 0 && changedFiles.length) {
+    try { saveGateReceipt(path, passedEvidenceReceipt(context, changedFiles)); }
+    catch { /* A receipt is an optimization; a passed gate remains passed if persistence fails. */ }
+  }
+  return result;
+}
+
+if (import.meta.main) {
+  const raw = process.argv[2];
+  try {
+    if (!raw) throw new Error('train gate receipt input is required');
+    const input = JSON.parse(raw) as TrainGateReceiptInput & Partial<PassedSelfGateReceiptInput>;
+    if (input.summaryPath) {
+      const receipt = await recordPassedSelfGateReceipt(input as PassedSelfGateReceiptInput);
+      const registryFile = process.env.ELANOUS_GATE_RECEIPT_REGISTRY_PATH;
+      if (registryFile) {
+        const registry = loadGateReceipts(registryFile);
+        process.stdout.write(`${String.fromCharCode(10)}__GATE_RECEIPTS__${Buffer.from(JSON.stringify(registry)).toString('base64')}${String.fromCharCode(10)}`);
+      }
+      if (!receipt) process.exitCode = 1;
+    } else {
+      const result = runTrainGateWithReceipts({ ...input, repo: process.cwd() });
+      process.stdout.write(result.stdout);
+      process.stderr.write(result.stderr);
+      const registryFile = process.env.ELANOUS_GATE_RECEIPT_REGISTRY_PATH;
+      if (registryFile) {
+        const registry = loadGateReceipts(registryFile);
+        process.stdout.write(`${String.fromCharCode(10)}__GATE_RECEIPTS__${Buffer.from(JSON.stringify(registry)).toString('base64')}${String.fromCharCode(10)}`);
+      }
+      process.exitCode = result.status ?? 1;
+    }
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+}