elanous 0.2.36 → 0.2.38

package/src/self-implement/gate-cli.ts

@@ -1,8 +1,10 @@
-import { existsSync, lstatSync, mkdtempSync, readFileSync, realpathSync } from 'node:fs';
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import { tmpdir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { join } from 'node:path/posix';
 import { prepareDeterministicChildEnvironment } from '../../scripts/lib/deterministic-env.js';
+import { audit as auditEntryBudget, entryBudgetAffected } from '../../scripts/ratchets/next-tui-entry-budget.js';
 import { withGateTestEnv } from '../../scripts/lib/gate-test-env.js';
 import { runIsolationHardcodeGate } from '../../scripts/ci-isolation-hardcode-gate.js';
 import { runModelHardcodeGate } from '../../scripts/ci-model-hardcode-gate.js';
@@ -12,13 +14,14 @@ import { runIosUnitTestGate } from '../../scripts/ci-ios-unit-tests.js';
 import { runPwaBuildGate } from '../../scripts/ci-pwa-build-gate.js';
 import { runMockModuleRestoreGate } from '../../scripts/ci-mock-module-restore-gate.js';
 import { parseReviewDepthFromFilesJson } from '../agent-mission/review-depth.js';
-import { buildGateBaselineReport, calculateGateTestCountChange, formatGateBaselineNote, formatGateTestCountNote, isGateTestFile, runGateBaseline, type BaselineProcessResult, type BaselineProcessStatus, type GateTestFailure } from './gate-baseline.js';
+import { buildGateBaselineReport, calculateGateTestCountChange, formatGateBaselineNote, formatGateTestCountNote, isGateTestFile, recheckTimeoutOnlyIntroducedFailures, runGateBaseline, type BaselineProcessResult, type BaselineProcessStatus, type GateTestFailure, type TimeoutRecheckRecord, type TimeoutRerunObservation } from './gate-baseline.js';
 import { resolveGateScope } from './gate-scope.js';
 import { publicExposureFiles, runExposeGate } from './expose-gate.js';
 import { getUserConfig } from '../user-config.js';
 import { debug, redactSecretText } from '../debug/log.js';
 import { buildDocumentGuardianIndex, formatDocumentGuardians } from './document-guardian-index.js';
 import { buildImporterTestIndex, importerTestsNotInRunSet, isTestPath, type ImporterTestIndex } from './importer-test-index.js';
+import { isCommentOnlySourceChange } from './comment-only-source.js';
 import { buildRouteConsumerTestIndex } from './route-consumer-test-index.js';
 import { gitChangedFiles, observeGateBaselineLocation } from './seams.js';
 import {
@@ -26,7 +29,8 @@ import {
   overlapWithCurrentChanges,
 } from '../cli/pr-granularity.js';
 import { listWorktrees } from '../git-fs/worktree.js';
-import { runShardedGateTests, writeShardFailureEvidence } from '../self-dev/shard-run.js';
+import { runShardedGateTests, runShardedGateTestsAsync, writeShardFailureEvidence, remoteShardArgv, type ShardRunProgress, type ShardRunResult } from '../self-dev/shard-run.js';
+import { planGateRemoteShards, shardPlanOrchestrationId, type GateRemoteShard } from '../self-dev/shard-plan.js';
 import { parseGateScenario, readGateScenarioFile } from './gate-scenario.js';
 import { isGateSpawnLaneFile } from '../self-dev/spawn-lane-files.js';
 import { defaultGateEnvKey, defaultRevResolver, resolveArtifactDir, writeGateArtifacts, type GateArtifactCounts, type GateArtifactsUnavailable, type RevResolver } from './gate-artifacts.js';
@@ -35,6 +39,8 @@ export interface SelfGateCliOptions {
   base?: string;
   pr?: string;
   shards?: number;
+  /** Live shard bundle concurrency; default three, bounded to one through four. */
+  shardConcurrency?: number;
   /** OP FU (LAND-TRAIN-LIVE side) — opt-in with `shards`: sorted round-robin into exactly that N, no RSS pre-measurement.
    *  Every other output (shardsDetail · baseline · artifacts · exit) keeps its shape; absent = measured planner unchanged. */
   fixedShardDistribution?: boolean;
@@ -99,7 +105,12 @@ interface SelfGateCliDeps {
   readFile?: (path: string) => string | undefined;
   runTests?: (cwd: string, files: readonly string[]) => ProcessResult;
   runBaseline?: (cwd: string, files: readonly string[], baseRef: string) => BaselineProcessResult;
+  runTimeoutRecheck?: (cwd: string, file: string, name: string, timeoutMs: number) => { observation?: TimeoutRerunObservation; elapsedMs: number; output: string };
   runShards?: typeof runShardedGateTests;
+  runShardsAsync?: typeof runShardedGateTestsAsync;
+  /** Test seam for the live progress line. */
+  writeProgressStderr?: (line: string) => void;
+  now?: () => number;
   runIsolationGate?: (out: GateOutput) => number;
   runMockModuleRestoreGate?: (out: GateOutput) => number;
   /** 모델 이름 하드코딩 래칫(🅕 #20521) — `pr land` 만 물고 하니스 무인 병합은 안 물면 위반이 main 에 들어가 남의 착지를 막는다(🅣 2026-09-25). */
@@ -111,6 +122,7 @@ interface SelfGateCliDeps {
   /** iOS 순수-로직 시험 게이트 심(시험 주입용). */
   runIosGate?: (out: GateOutput) => number;
   runPwaGate?: (out: GateOutput) => number;
+  runEntryBudgetGate?: (cwd: string, changedFiles: readonly string[]) => { affected: boolean; errors: string[] };
   listPrWorktrees?: (cwd: string) => PrWorktreeListEntry[] | { lookupFailed: string };
   inspectWorktreeDirtiness?: (path: string) => { dirty: boolean } | { lookupFailed: string };
   /** `--artifact-dir` 전용 심 — 커밋 sha 해석(실패 = null) · 환경 키. */
@@ -131,6 +143,7 @@ interface GateArtifactCapture {
   /** `unrun importer tests: N` 의 N — 색인 조회 실패면 null(그 이유가 importerLookupFailed). */
   unrunImporters?: number | null;
   importerLookupFailed?: string;
+  timeoutRechecks?: readonly TimeoutRecheckRecord[];
 }
 
 /** SIDE-VERIFY ③ — summary 정수 칸: 게이트가 이미 낸 `result.baseline` ⊕ `unrunImporterTotal` 을 «옮기기만» 한다.
@@ -388,7 +401,9 @@ export function observePrFileOverlap(
       return { ok: false as const, out: '', err: error instanceof Error ? error.message : String(error) };
     }
   };
-  const commits = collectBaseLandingCommits(run, cwd, { since: '0', baseRef: `${baseOid}..${baseRefName}` });
+  // The resolved base range is the complete scope; a time cutoff can hide a
+  // just-created commit when a gate shard is slow.
+  const commits = collectBaseLandingCommits(run, cwd, { since: null, baseRef: `${baseOid}..${baseRefName}` });
   if (commits === null) return { status: 'unavailable', reason: 'git log failed' };
   const overlaps = overlapWithCurrentChanges(commits, files);
   return overlaps.length > 0
@@ -588,6 +603,24 @@ export function formatUnrunImporterTests(importerTestsNotRun: NonNullable<Return
   return `unrun importer tests: ${importerTestsNotRun.total}${files}; unresolved relative specifiers: ${importerTestsNotRun.unresolvedRelativeSpecifiers}`;
 }
 
+/** gate 출력 한 줄에 실리는 미등재 spawn-lane 시험의 최대 표시 수 — 실측 드리프트(57건)를 전부 나열하면
+ *  «읽히지 않는 소음»이 된다(`formatUnrunImporterTests` 의 잘림 정책과 같은 취지). */
+const UNLISTED_SPAWN_LANE_DISPLAY_LIMIT = 10;
+
+/** ⛔⭐ 소비자 배선(무인 리뷰 must-fix) — `resolveGateScope` 이 채우는 `runtimeEdgeImpact` 를 읽는 곳이
+ *  없으면 그 측정은 어디에도 드러나지 않는다. 정책은 형제들과 같다 — ***「보고한다. 막지 않는다.」***
+ *  손으로 관리하는 `GATE_SPAWN_LANE_FILES` 가 실측에서 빠뜨린 spawn-lane 시험을 알린다. */
+export function formatUnlistedSpawnLaneTests(impact: ReturnType<typeof resolveGateScope>['runtimeEdgeImpact']): string {
+  if (!impact) return 'unlisted spawn-lane tests: (not measured — no importer index)';
+  if (!impact.measured) return 'unlisted spawn-lane tests: (not measured)';
+  const total = impact.unlistedSpawnLaneTests.length;
+  if (total === 0) return 'unlisted spawn-lane tests: 0';
+  const shown = impact.unlistedSpawnLaneTests.slice(0, UNLISTED_SPAWN_LANE_DISPLAY_LIMIT);
+  const truncated = total > shown.length ? `, showing ${shown.length}/${total}` : '';
+  return `unlisted spawn-lane tests: ${total} (${shown.join(', ')}${truncated})`
+    + '  ⚠️ GATE_SPAWN_LANE_FILES 가 빠뜨린 실측 spawn-lane 시험 — 「보고만 한다. 막지 않는다.」';
+}
+
 export function formatPartialObservationNote(unrunImporterTotal: number, note: string): string {
   if (unrunImporterTotal <= 0) return note;
   return `partial observation: ${unrunImporterTotal} unrun importer tests; ${note}`;
@@ -648,6 +681,30 @@ function logGateCliBaseline(cwd: string, payload: GateCliBaselinePayload): void
 type GateSelectionOptions = Pick<SelfGateCliOptions, 'base' | 'pr' | 'alwaysInclude' | 'includeImporterTests' | 'scenario' | 'scenarioFile'>;
 type GateSelectionDeps = Pick<SelfGateCliDeps, 'changedFiles' | 'exists' | 'isRegularFile' | 'runCommand'>;
 
+function commentOnlyChangedSources(selection: ChangedFileSelection, cwd: string, runCommand: SelfGateCliDeps['runCommand']): string[] {
+  const run = runCommand ?? defaultRunCommand;
+  // Fail closed: an unreadable base, source or Git command keeps the normal importer set.
+  const base = selection.baseRef === 'HEAD'
+    ? 'HEAD'
+    : (() => {
+      try {
+        const result = run('git', ['merge-base', selection.baseRef, 'HEAD'], cwd);
+        return result.status === 0 && !result.error ? result.stdout?.trim() : undefined;
+      } catch { return undefined; }
+    })();
+  if (!base) return [];
+  const commentOnly: string[] = [];
+  for (const path of selection.files) {
+    if (!/^(?:src|scripts)\/.+\.(?:[cm]?[jt]sx?)$/.test(path) || isTestPath(path)) continue;
+    try {
+      const prior = run('git', ['show', `${base}:${path}`], cwd);
+      if (prior.status !== 0 || prior.error || prior.stdout === undefined) continue;
+      if (isCommentOnlySourceChange(prior.stdout, readFileSync(join(cwd, path), 'utf8'), path)) commentOnly.push(path);
+    } catch { /* A failed comparison must retain importer coverage. */ }
+  }
+  return commentOnly;
+}
+
 function prepareGateTestSelection(cwd: string, options: GateSelectionOptions, deps: GateSelectionDeps) {
   const selection = (deps.changedFiles ?? ((dir, input) => defaultChangedFiles(dir, input, deps.runCommand)))(cwd, options);
   const exists = deps.exists ?? ((path) => existsSync(`${cwd}/${path}`));
@@ -656,16 +713,23 @@ function prepareGateTestSelection(cwd: string, options: GateSelectionOptions, de
   const importerIndex = buildGateImporterTestIndex(options.includeImporterTests
     ? selection.files : selection.files.filter((path) => !SCRIPT_SOURCE_PATH_RE.test(path)), cwd, deps.runCommand);
   const lookupFailed = importerIndex && 'lookupFailed' in importerIndex ? importerIndex.lookupFailed : undefined;
-  const availableIndex = importerIndex && !('lookupFailed' in importerIndex) ? importerIndex : undefined;
+  const originalIndex = importerIndex && !('lookupFailed' in importerIndex) ? importerIndex : undefined;
+  const commentOnlySources = options.includeImporterTests && originalIndex
+    ? commentOnlyChangedSources(selection, cwd, deps.runCommand) : [];
+  // testPaths is the independent full tracked-test inventory; only the changed-source
+  // reverse edges are filtered. Other consumers still need that complete inventory.
+  const availableIndex = originalIndex && commentOnlySources.length
+    ? { ...originalIndex, testsBySource: new Map([...originalIndex.testsBySource].filter(([source]) => !commentOnlySources.includes(source))) }
+    : originalIndex;
   const routeIndex = availableIndex?.testPaths
-    ? buildRouteConsumerTestIndex(cwd, availableIndex.testPaths, selection.files, selection.baseRef) : null;
+    ? buildRouteConsumerTestIndex(cwd, availableIndex.testPaths, selection.files.filter((path) => !commentOnlySources.includes(path)), selection.baseRef) : null;
   const scope = resolveGateScope(selection.files, exists, availableIndex,
     { routeConsumerTestIndex: routeIndex ?? undefined });
-  return { selection, exists, lookupFailed, availableIndex, routeIndex, scope };
+  return { selection, exists, lookupFailed, availableIndex, commentOnlySources, routeIndex, scope };
 }
 
 function finishGateTestSelection(prepared: ReturnType<typeof prepareGateTestSelection>, options: GateSelectionOptions, cwd: string, deps: GateSelectionDeps) {
-  const { selection, exists, lookupFailed, availableIndex, routeIndex, scope } = prepared;
+  const { selection, exists, lookupFailed, availableIndex, commentOnlySources, routeIndex, scope } = prepared;
   const alwaysInclude = [...new Set((options.alwaysInclude ?? []).map(normalizeGatePath).filter(Boolean))];
   const alwaysIncludeMissing = alwaysInclude.filter((path) => !exists(path));
   const scopedTests = scope.testArgs ?? [];
@@ -693,20 +757,21 @@ function finishGateTestSelection(prepared: ReturnType<typeof prepareGateTestSele
   // RELEASE-DAILY-LIGHT-RC ② — the scope already runs importer tests as callers, but capped (GATE_CALLER_TEST_LIMIT);
   // a day of landings overflows that cap and source-only regressions went unrun (0.2.24: 20). Opt-in: every importer.
   const changedSources = selection.files.filter((path) => !isTestPath(path));
+  const importerSources = changedSources.filter((path) => !commentOnlySources.includes(path));
   const importerTestsAdded = options.includeImporterTests && availableIndex
-    ? [...new Set(changedSources.flatMap((source) => availableIndex.testsBySource.get(source) ?? []))]
+    ? [...new Set(importerSources.flatMap((source) => availableIndex.testsBySource.get(source) ?? []))]
       .filter((path) => exists(path) && !scopedTests.includes(path) && !alwaysIncludeExtra.includes(path)).sort()
     : [];
   const defaultTests = [...scopedTests, ...alwaysIncludeExtra, ...importerTestsAdded];
   const testFiles = scenarioTests.length ? [...new Set([...defaultTests, ...scenarioTests])] : defaultTests;
   const skipTestStep = scope.skipTestStep && alwaysIncludeExtra.length === 0 && importerTestsAdded.length === 0 && scenarioTests.length === 0;
   const importerTestsNotRun = (options.includeImporterTests || scenarioTests.length > 0) && availableIndex
-    ? importerTestsNotInRunSet(availableIndex, changedSources, testFiles) : scope.importerTestsNotRun;
+    ? importerTestsNotInRunSet(availableIndex, importerSources, testFiles) : scope.importerTestsNotRun;
   const unrunImporterTotal = lookupFailed ? null : (importerTestsNotRun?.total ?? 0);
   // Overflowed callers that ② ran anyway are not «not run».
   const callerTestsOverflow = scope.callerTestsOverflow.filter(({ file }) => !importerTestsAdded.includes(file) && !scenarioTests.includes(file));
   const importerLookupFailed = Boolean(lookupFailed);
-  return { ...prepared, alwaysInclude, alwaysIncludeMissing, alwaysIncludeExtra, importerTestsAdded, scenarioTests,
+  return { ...prepared, alwaysInclude, alwaysIncludeMissing, alwaysIncludeExtra, importerTestsAdded, commentOnlySources, scenarioTests,
     testFiles, skipTestStep, importerTestsNotRun, unrunImporterTotal, callerTestsOverflow, importerLookupFailed };
 }
 
@@ -733,7 +798,15 @@ export function selectGateTestFiles(cwd: string, options: GateSelectionOptions =
 
 export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, deps: SelfGateCliDeps = {}): SelfGateCliResult {
   const capture: GateArtifactCapture = {};
-  const result = runSelfGateCliCore(cwd, options, deps, capture);
+  const result = runSelfGateCliCore(cwd, options, deps, capture, false) as SelfGateCliResult;
+  if (options.artifactDir !== undefined) emitGateArtifacts(cwd, options.artifactDir, result, capture, deps);
+  return result;
+}
+
+/** Production path: shard bundles use async Bun children; all non-shard policy and timeout logic is shared. */
+export async function runSelfGateCliAsync(cwd: string, options: SelfGateCliOptions = {}, deps: SelfGateCliDeps = {}): Promise<SelfGateCliResult> {
+  const capture: GateArtifactCapture = {};
+  const result = await runSelfGateCliCore(cwd, options, deps, capture, true);
   if (options.artifactDir !== undefined) emitGateArtifacts(cwd, options.artifactDir, result, capture, deps);
   return result;
 }
@@ -756,6 +829,7 @@ function emitGateArtifacts(cwd: string, artifactDir: string, result: SelfGateCli
       testFiles: capture.testFiles ?? result.testFiles,
       verdict: capture.verdict ?? null,
       ...(capture.verdictLine !== undefined ? { verdictLine: capture.verdictLine } : {}),
+      ...(capture.timeoutRechecks ? { timeoutRechecks: capture.timeoutRechecks } : {}),
       exitCode: result.exitCode,
       counts: counts.counts,
       ...(counts.reason !== undefined ? { countsUnavailableReason: counts.reason } : {}),
@@ -770,16 +844,42 @@ function emitGateArtifacts(cwd: string, artifactDir: string, result: SelfGateCli
   }
 }
 
-function runSelfGateCliCore(cwd: string, options: SelfGateCliOptions, deps: SelfGateCliDeps, capture: GateArtifactCapture): SelfGateCliResult {
+/** A completed bundle is observed immediately, before the synchronous runner returns. Each sink is best effort. */
+function shardProgressObserver(cwd: string, options: SelfGateCliOptions, deps: SelfGateCliDeps): (progress: ShardRunProgress) => void {
+  const now = deps.now ?? Date.now;
+  const startedAt = now();
+  return (progress) => {
+    const elapsedMs = Math.max(0, now() - startedAt);
+    const estimatedRemainingMs = progress.completedShards > 0
+      ? Math.round(elapsedMs * (progress.totalShards - progress.completedShards) / progress.completedShards) : null;
+    const snapshot = { ...progress, elapsedMs, estimatedRemainingMs };
+    const line = `gate shard progress: bundles ${progress.completedShards}/${progress.totalShards} · files ${progress.completedFiles}/${progress.totalFiles} · elapsed ${Math.round(elapsedMs / 1000)}s · remaining ~${estimatedRemainingMs === null ? '?' : Math.round(estimatedRemainingMs / 1000) + 's'}\n`;
+    try { (deps.writeProgressStderr ?? ((value) => { process.stderr.write(value); }))(line); } catch { /* observation only */ }
+    try { debug.log('gate.cli', 'shard-progress', snapshot); } catch { /* observation only */ }
+    if (!options.artifactDir?.trim()) return;
+    let temporary: string | undefined;
+    try {
+      const dir = resolveArtifactDir(options.artifactDir, cwd);
+      mkdirSync(dir, { recursive: true });
+      temporary = join(dir, `.progress.${process.pid}.${randomUUID()}.tmp`);
+      writeFileSync(temporary, `${JSON.stringify(snapshot, null, 2)}\n`);
+      renameSync(temporary, join(dir, 'progress.json'));
+    } catch { /* artifact failure must not affect the gate verdict */ }
+    finally { if (temporary) { try { rmSync(temporary, { force: true }); } catch { /* observation only */ } } }
+  };
+}
+
+function runSelfGateCliCore(cwd: string, options: SelfGateCliOptions, deps: SelfGateCliDeps, capture: GateArtifactCapture, asyncShards: boolean): SelfGateCliResult | Promise<SelfGateCliResult> {
   if (options.base && options.pr) throw new Error('use either --base <ref> or --pr <number>, not both');
   if (options.shards !== undefined && (!Number.isSafeInteger(options.shards) || options.shards < 1)) throw new Error('invalid --shards count');
+  if (options.shardConcurrency !== undefined && (!Number.isSafeInteger(options.shardConcurrency) || options.shardConcurrency < 1 || options.shardConcurrency > 4)) throw new Error('invalid shard concurrency (expected 1–4)');
   if (options.fixedShardDistribution && options.shards === undefined) throw new Error('--fixed-shard-distribution requires --shards <n>');
   const prepared = prepareGateTestSelection(cwd, options, deps);
   const { selection, lookupFailed, routeIndex, scope } = prepared;
   const expose = publicExposureFiles(selection.files).length > 0
     ? runExposeGate(cwd, selection.files, getUserConfig().harness?.exposeGate === 'strict' ? 'strict' : 'warn', deps.runCommand)
     : { passed: true, log: '' };
-  const { alwaysInclude, alwaysIncludeMissing, alwaysIncludeExtra, importerTestsAdded, scenarioTests, testFiles,
+  const { alwaysInclude, alwaysIncludeMissing, alwaysIncludeExtra, importerTestsAdded, commentOnlySources, scenarioTests, testFiles,
     skipTestStep, importerTestsNotRun, unrunImporterTotal, callerTestsOverflow, importerLookupFailed } = finishGateTestSelection(prepared, options, cwd, deps);
   const lines = [
     // ⛔⭐ 「changed=0」을 «초록»으로 읽는 사고가 났다(2026-09-02 · 🅕 보고 · 🅣 재현).
@@ -803,6 +903,9 @@ function runSelfGateCliCore(cwd: string, options: SelfGateCliOptions, deps: Self
     // 🚨 러너 우주 «밖» — 형제들과 같은 정책으로 «말만» 한다(`OBS-T418`).
     formatUnrunnableChangeKinds(selection.files),
     formatUnrunImporterTests(importerTestsNotRun, lookupFailed),
+    // ⛔⭐ 무인 리뷰 must-fix — 죽은 필드 배선: `resolveGateScope` 이 채운 `runtimeEdgeImpact` 을
+    //   실제로 읽어 출력하는 소비자(이 줄이 없으면 그 측정은 어디에도 드러나지 않는다).
+    formatUnlistedSpawnLaneTests(scope.runtimeEdgeImpact),
     `caller tests: ${lookupFailed ? `lookup failed (${lookupFailed})` : scope.callerTests.map(({ file, reasons }) => `${file} (${reasons.join('+')})`).join(', ') || (routeIndex?.lookupFailures.length ? 'route lookup incomplete' : '(none)')}`,
     ...(routeIndex?.lookupFailures.length ? [`⚠️ caller route base lookup failed — unmeasured: ${routeIndex.lookupFailures.map(({ source, reason }) => `${source} (${reason})`).join(', ')}`] : []),
     ...(callerTestsOverflow.length ? [`⚠️ caller test cap exceeded — not run: ${callerTestsOverflow.map(({ file, reasons }) => `${file} (${reasons.join('+')})`).join(', ')}`] : []),
@@ -814,6 +917,7 @@ function runSelfGateCliCore(cwd: string, options: SelfGateCliOptions, deps: Self
     ...(options.includeImporterTests
       ? [`importer tests added: ${lookupFailed ? `lookup failed (${lookupFailed})` : `${importerTestsAdded.length} (reason=changed-source-importer${importerTestsAdded.length ? ` · ${importerTestsAdded.join(', ')}` : ''})`}`]
       : []),
+    ...(commentOnlySources.length ? [`comment-only importer expansion excluded: ${commentOnlySources.join(', ')}`] : []),
     ...(options.scenario !== undefined || options.scenarioFile !== undefined ? [`scenario tests: ${scenarioTests.length} (${scenarioTests.join(', ')})`] : []),
   ];
   if (expose.log) lines.push(expose.log);
@@ -840,12 +944,25 @@ function runSelfGateCliCore(cwd: string, options: SelfGateCliOptions, deps: Self
   // 🍎 iOS 축 — 안드로이드와 «같은 자리»에 둔다(skipTestStep 앞). Swift 만 바뀐 PR 도 여기서 조기 리턴한다.
   const iosPassed = runAdditionalGate('ios-gate', deps.runIosGate ?? runIosUnitTestGate, selection.files, cwd, lines);
   const pwaPassed = runAdditionalGate('pwa-gate', deps.runPwaGate ?? runPwaBuildGate, selection.files, cwd, lines);
+  let entryBudgetPassed = false;
+  try {
+    const budget = (deps.runEntryBudgetGate ?? ((dir, files) => {
+      const affected = entryBudgetAffected(files);
+      return { affected, errors: affected ? auditEntryBudget(dir).errors : [] };
+    }))(cwd, selection.files);
+    entryBudgetPassed = budget.errors.length === 0;
+    lines.push(budget.affected
+      ? `next-tui-entry-budget: ${entryBudgetPassed ? 'pass' : `FAIL ${budget.errors.join('; ')}`}`
+      : 'next-tui-entry-budget: skip (unrelated changes)');
+  } catch (error) {
+    lines.push(`next-tui-entry-budget: UNMEASURED ${error instanceof Error ? error.message : String(error)}`);
+  }
 
   if (skipTestStep) {
     const policyPassed = runPolicyGates(selection.files, cwd, lines, deps);
     logGateCliBaseline(cwd, { ...ZERO_GATE_BASELINE, unrunImporterTotal, lookupFailed: importerLookupFailed });
     Object.assign(capture, { verdict: 'skipped', artifactsUnavailable: 'no-tests' } satisfies GateArtifactCapture);
-    return { exitCode: androidPassed && iosPassed && pwaPassed && policyPassed && expose.passed ? 0 : 1, lines, changedFiles: selection.files, testFiles: [], unverified: scope.unverified, documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests, alwaysIncludeMissing, importerTestsAdded, baseline: { introduced: 0, preexisting: 0, unknown: 0, preconditionUnmet: 0 } };
+    return { exitCode: androidPassed && iosPassed && pwaPassed && entryBudgetPassed && policyPassed && expose.passed ? 0 : 1, lines, changedFiles: selection.files, testFiles: [], unverified: scope.unverified, documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests, alwaysIncludeMissing, importerTestsAdded, baseline: { introduced: 0, preexisting: 0, unknown: 0, preconditionUnmet: 0 } };
   }
 
   // The default direct Bun path has one process and one 300s limit. Route real child/PTY tests through
@@ -853,73 +970,86 @@ function runSelfGateCliCore(cwd: string, options: SelfGateCliOptions, deps: Self
   if (options.shards !== undefined || testFiles.some(isGateSpawnLaneFile)) {
     const spawnFileCount = testFiles.filter(isGateSpawnLaneFile).length;
     const shardCount = options.shards ?? (Math.min(3, spawnFileCount) + Number(testFiles.length > spawnFileCount));
-    const runShards = deps.runShards ?? runShardedGateTests;
-    const sharded = options.fixedShardDistribution
-      ? runShards(cwd, testFiles, selection.baseRef, shardCount, undefined, undefined, undefined, { fixedDistribution: true })
-      : runShards(cwd, testFiles, selection.baseRef, shardCount);
-    capture.sharded = sharded;
-    capture.verdict = sharded.aggregate.status;
-    lines.push(`shards: ${sharded.shards.length} (${sharded.shards.map((shard) => `${shard.id}=${shard.files.join(',')}`).join('; ')})${sharded.expandedFrom !== undefined ? ` · RSS 예산상 ${sharded.expandedFrom}→${sharded.shards.length} 자동 확장` : ''}${sharded.measurementFailures ? ` · 측정 실패 ${sharded.measurementFailures}` : ''}${options.fixedShardDistribution ? ' · 고정 분배(사전 측정 없음)' : ''}${sharded.distribution === 'fixed-cap-fallback' ? ` · 호스트 상한 자동 고정 분배(${sharded.fallbackReason})` : ''}`);
-    // 조각이 «못 쟀다»일 때 이유가 줄에 없으면 자리·시간 초과·죽음을 가를 수 없다(OP 10-09 light RC) — 종료 코드·신호를 같이 싣는다.
-    const side = (code: number | null, signal: string | null | undefined, junit: string | undefined) => signal ? `signal ${signal}` : code === null ? 'exit ?' : `exit ${code}${junit === undefined ? ' · junit 없음' : ''}`;
-    for (const attempt of sharded.attempts) {
-      const plannedFiles = sharded.shards.find((shard) => shard.id === attempt.shardId)?.files;
-      const baselineFiles = attempt.baselineFiles;
-      const baselineDifference = baselineFiles && plannedFiles && (baselineFiles.length !== plannedFiles.length || baselineFiles.some((file, index) => file !== plannedFiles[index]))
-        ? ` · 기준 파일 ${baselineFiles.join(',') || '(none)'}` : '';
-      lines.push(`shard attempt: ${attempt.shardId} #${attempt.attempt} · 지금 ${side(attempt.currentExitCode, attempt.currentSignal, attempt.currentJUnit)} · 기준 ${side(attempt.baselineExitCode, attempt.baselineSignal, attempt.baselineJUnit)} · 파일 ${plannedFiles?.join(',') ?? '(unknown)'}${baselineDifference}`);
-      const renderDiagnostic = (value: string): string => redactSecretText(value).replace(/[\r\n\t\x00-\x1f\x7f]+/g, ' ').slice(0, 500);
-      if (attempt.currentJUnit === undefined && attempt.currentDiagnostic) lines.push(`shard diagnostic: ${attempt.shardId} #${attempt.attempt} 지금 · ${renderDiagnostic(attempt.currentDiagnostic)}`);
-      if (attempt.baselineJUnit === undefined && attempt.baselineDiagnostic) lines.push(`shard diagnostic: ${attempt.shardId} #${attempt.attempt} 기준 · ${renderDiagnostic(attempt.baselineDiagnostic)}`);
-    }
-    // OP FU (MK #8178 shard-9) — 실패 조각의 자식 출력 꼬리 ⊕ exit/signal 을 파일로 남긴다(관측만 · 판정·exit 불변).
-    // --artifact-dir 이 있으면 그 아래, 없으면 임시 디렉토리(JUnit 임시 디렉토리 옆 tmpdir)에.
-    if (sharded.failureEvidence?.length) {
-      try {
-        const evidenceDir = options.artifactDir?.trim() ? resolveArtifactDir(options.artifactDir, cwd) : mkdtempSync(join(tmpdir(), 'elanous-shard-failure-'));
-        for (const path of writeShardFailureEvidence(evidenceDir, sharded.failureEvidence)) lines.push(`shard failure evidence: ${path}`);
-      } catch (error) {
-        lines.push(`⚠ shard failure evidence: 못 썼다 — ${error instanceof Error ? error.message : String(error)} (판정은 그대로다)`);
+    const onShardComplete = shardProgressObserver(cwd, options, deps);
+    const mode = { ...(options.fixedShardDistribution ? { fixedDistribution: true } : {}), onShardComplete,
+      ...(options.shardConcurrency !== undefined ? { concurrency: options.shardConcurrency } : {}) };
+    const runResult = asyncShards
+      ? (deps.runShardsAsync ?? runShardedGateTestsAsync)(cwd, testFiles, selection.baseRef, shardCount, undefined, undefined, undefined, mode)
+      : (deps.runShards ?? runShardedGateTests)(cwd, testFiles, selection.baseRef, shardCount, undefined, undefined, undefined, mode);
+    const finishShardedGate = (sharded: ShardRunResult): SelfGateCliResult => {
+      capture.sharded = sharded;
+      capture.verdict = sharded.aggregate.status;
+      lines.push(`shards: ${sharded.shards.length} (${sharded.shards.map((shard) => `${shard.id}=${shard.files.join(',')}`).join('; ')})${sharded.expandedFrom !== undefined ? ` · RSS 예산상 ${sharded.expandedFrom}→${sharded.shards.length} 자동 확장` : ''}${sharded.measurementFailures ? ` · 측정 실패 ${sharded.measurementFailures}` : ''}${options.fixedShardDistribution ? ' · 고정 분배(사전 측정 없음)' : ''}${sharded.distribution === 'fixed-cap-fallback' ? ` · 호스트 상한 자동 고정 분배(${sharded.fallbackReason})` : ''}${sharded.concurrency !== undefined ? ` · 동시성 ${sharded.concurrency} (${sharded.concurrencyReason ?? 'reason unavailable'})` : ''}${sharded.measurementMs !== undefined ? ` · RSS 사전 측정 ${(sharded.measurementMs / 1000).toFixed(1)}s · 묶음 ${((sharded.bundleMs ?? 0) / 1000).toFixed(1)}s · currentΣ ${((sharded.currentProcessMs ?? 0) / 1000).toFixed(1)}s · baselineΣ ${((sharded.baselineProcessMs ?? 0) / 1000).toFixed(1)}s` : ''}`);
+      // 조각이 «못 쟀다»일 때 이유가 줄에 없으면 자리·시간 초과·죽음을 가를 수 없다(OP 10-09 light RC) — 종료 코드·신호를 같이 싣는다.
+      const side = (code: number | null, signal: string | null | undefined, junit: string | undefined) => signal ? `signal ${signal}` : code === null ? 'exit ?' : `exit ${code}${junit === undefined ? ' · junit 없음' : ''}`;
+      for (const attempt of sharded.attempts) {
+        const plannedFiles = sharded.shards.find((shard) => shard.id === attempt.shardId)?.files;
+        const baselineFiles = attempt.baselineFiles;
+        const baselineDifference = baselineFiles && plannedFiles && (baselineFiles.length !== plannedFiles.length || baselineFiles.some((file, index) => file !== plannedFiles[index]))
+          ? ` · 기준 파일 ${baselineFiles.join(',') || '(none)'}` : '';
+        lines.push(`shard attempt: ${attempt.shardId} #${attempt.attempt} · 지금 ${side(attempt.currentExitCode, attempt.currentSignal, attempt.currentJUnit)} · 기준 ${side(attempt.baselineExitCode, attempt.baselineSignal, attempt.baselineJUnit)} · 파일 ${plannedFiles?.join(',') ?? '(unknown)'}${baselineDifference}`);
+        const renderDiagnostic = (value: string): string => redactSecretText(value).replace(/[\r\n\t\x00-\x1f\x7f]+/g, ' ').slice(0, 500);
+        if (attempt.currentJUnit === undefined && attempt.currentDiagnostic) lines.push(`shard diagnostic: ${attempt.shardId} #${attempt.attempt} 지금 · ${renderDiagnostic(attempt.currentDiagnostic)}`);
+        if (attempt.baselineJUnit === undefined && attempt.baselineDiagnostic) lines.push(`shard diagnostic: ${attempt.shardId} #${attempt.attempt} 기준 · ${renderDiagnostic(attempt.baselineDiagnostic)}`);
       }
-    }
-    const { aggregate } = sharded;
-    let shardBaseline: SelfGateCliResult['baseline'];
-    let unmeasuredReason: string | undefined;
-    if (aggregate.status === 'unmeasured') {
-      unmeasuredReason = sharded.reason
-        ? redactSecretText(sharded.reason).replace(/[\r\n\t\x00-\x1f\x7f]+/g, ' ').slice(0, 500)
-        : aggregate.retryShardIds.join(', ') || 'no complete JUnit';
-      for (const shardId of aggregate.retryShardIds) {
-        lines.push(`shard unmeasured: ${shardId} · ${sharded.unmeasuredByShard?.[shardId] ?? sharded.reason ?? 'cause unavailable'}`);
+      // OP FU (MK #8178 shard-9) — 실패 조각의 자식 출력 꼬리 ⊕ exit/signal 을 파일로 남긴다(관측만 · 판정·exit 불변).
+      // --artifact-dir 이 있으면 그 아래, 없으면 임시 디렉토리(JUnit 임시 디렉토리 옆 tmpdir)에.
+      if (sharded.failureEvidence?.length) {
+        try {
+          const evidenceDir = options.artifactDir?.trim() ? resolveArtifactDir(options.artifactDir, cwd) : mkdtempSync(join(tmpdir(), 'elanous-shard-failure-'));
+          for (const path of writeShardFailureEvidence(evidenceDir, sharded.failureEvidence)) lines.push(`shard failure evidence: ${path}`);
+        } catch (error) {
+          lines.push(`⚠ shard failure evidence: 못 썼다 — ${error instanceof Error ? error.message : String(error)} (판정은 그대로다)`);
+        }
       }
-      lines.push(`shards: unmeasured (${unmeasuredReason})`);
-      if (sharded.baselineStderrTail) lines.push(`baseline worktree-add git stderr: ${sharded.baselineStderrTail}`);
-      capture.unmeasuredReason = unmeasuredReason;
-    }
-    else if (aggregate.report) {
-      const report = aggregate.report;
-      logGateCliBaseline(cwd, {
-        introduced: report.introduced, preexisting: report.preexisting, unknown: report.unknown,
-        preconditionUnmet: report.preconditionUnmet, timedOut: report.timedOut,
-        timeoutPassedAtBase: report.timeoutPassedAtBase, failures: report.failures.slice(0, 20),
-        baselineFiles: report.files, baselineStatus: report.baselineStatus, unrunImporterTotal, lookupFailed: importerLookupFailed,
-      });
-      lines.push(formatPartialObservationNote(unrunImporterTotal ?? 0, formatGateBaselineNote(report, unrunImporterTotal ?? 0)));
-      shardBaseline = { introduced: report.introduced, preexisting: report.preexisting, unknown: report.unknown, preconditionUnmet: report.preconditionUnmet };
-    } else {
-      lines.push(formatPartialObservationNote(unrunImporterTotal ?? 0, `tests: pass (${testFiles.length} files)`));
-      logGateCliBaseline(cwd, { ...ZERO_GATE_BASELINE, unrunImporterTotal, lookupFailed: importerLookupFailed });
-      shardBaseline = { introduced: 0, preexisting: 0, unknown: 0, preconditionUnmet: 0 };
-    }
-    capture.verdictLine = lines[lines.length - 1];
-    const policyPassed = runPolicyGates(selection.files, cwd, lines, deps);
-    return {
-      exitCode: aggregate.status !== 'passed' || !policyPassed || !androidPassed || !iosPassed || !pwaPassed || !expose.passed ? 1 : 0,
-      lines, changedFiles: selection.files, testFiles, unverified: scope.unverified,
-      documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests,
-      alwaysIncludeMissing, importerTestsAdded, ...(shardBaseline ? { baseline: shardBaseline } : {}),
-      ...(unmeasuredReason !== undefined ? { unmeasuredReason } : {}),
+      const { aggregate } = sharded;
+      let shardBaseline: SelfGateCliResult['baseline'];
+      let unmeasuredReason: string | undefined;
+      if (aggregate.status === 'unmeasured') {
+        unmeasuredReason = sharded.reason
+          ? redactSecretText(sharded.reason).replace(/[\r\n\t\x00-\x1f\x7f]+/g, ' ').slice(0, 500)
+          : aggregate.retryShardIds.join(', ') || 'no complete JUnit';
+        for (const shardId of aggregate.retryShardIds) {
+          lines.push(`shard unmeasured: ${shardId} · ${sharded.unmeasuredByShard?.[shardId] ?? sharded.reason ?? 'cause unavailable'}`);
+        }
+        lines.push(`shards: unmeasured (${unmeasuredReason})`);
+        if (sharded.baselineStderrTail) lines.push(`baseline worktree-add git stderr: ${sharded.baselineStderrTail}`);
+        capture.unmeasuredReason = unmeasuredReason;
+      }
+      else if (aggregate.report) {
+        const report = recheckTimeoutOnlyIntroducedFailures(cwd, aggregate.report, deps.runTimeoutRecheck);
+        capture.timeoutRechecks = report.timeoutRechecks;
+        const timeoutRecheckResolvedFailure = aggregate.status === 'failed'
+          && (report.loadTimeout ?? 0) > 0
+          && report.introduced === 0 && report.unknown === 0 && report.preconditionUnmet === 0
+          && report.timedOut === 0 && report.flakyRerun === 0 && report.worktreeFailuresParsed
+          && report.baselineStatus !== 'unknown';
+        const effectiveStatus = timeoutRecheckResolvedFailure ? 'passed' : aggregate.status;
+        capture.verdict = effectiveStatus;
+        logGateCliBaseline(cwd, {
+          introduced: report.introduced, preexisting: report.preexisting, unknown: report.unknown,
+          preconditionUnmet: report.preconditionUnmet, timedOut: report.timedOut,
+          timeoutPassedAtBase: report.timeoutPassedAtBase, failures: report.failures.slice(0, 20),
+          baselineFiles: report.files, baselineStatus: report.baselineStatus, unrunImporterTotal, lookupFailed: importerLookupFailed,
+        });
+        lines.push(formatPartialObservationNote(unrunImporterTotal ?? 0, formatGateBaselineNote(report, unrunImporterTotal ?? 0)));
+        shardBaseline = { introduced: report.introduced, preexisting: report.preexisting, unknown: report.unknown, preconditionUnmet: report.preconditionUnmet };
+      } else {
+        lines.push(formatPartialObservationNote(unrunImporterTotal ?? 0, `tests: pass (${testFiles.length} files)`));
+        logGateCliBaseline(cwd, { ...ZERO_GATE_BASELINE, unrunImporterTotal, lookupFailed: importerLookupFailed });
+        shardBaseline = { introduced: 0, preexisting: 0, unknown: 0, preconditionUnmet: 0 };
+      }
+      capture.verdictLine = lines[lines.length - 1];
+      const policyPassed = runPolicyGates(selection.files, cwd, lines, deps);
+      return {
+        exitCode: capture.verdict !== 'passed' || !policyPassed || !androidPassed || !iosPassed || !pwaPassed || !entryBudgetPassed || !expose.passed ? 1 : 0,
+        lines, changedFiles: selection.files, testFiles, unverified: scope.unverified,
+        documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests,
+        alwaysIncludeMissing, importerTestsAdded, ...(shardBaseline ? { baseline: shardBaseline } : {}),
+        ...(unmeasuredReason !== undefined ? { unmeasuredReason } : {}),
+      };
     };
+    return runResult instanceof Promise ? runResult.then(finishShardedGate) : finishShardedGate(runResult);
   }
 
   const test = (deps.runTests ?? ((dir, files) => (deps.runCommand ?? defaultRunCommand)('bun', ['test', ...files], dir)))(cwd, testFiles);
@@ -930,12 +1060,13 @@ function runSelfGateCliCore(cwd: string, options: SelfGateCliOptions, deps: Self
     Object.assign(capture, { verdict: 'passed', verdictLine: lines[lines.length - 1] } satisfies GateArtifactCapture);
     const policyPassed = runPolicyGates(selection.files, cwd, lines, deps);
     logGateCliBaseline(cwd, { ...ZERO_GATE_BASELINE, unrunImporterTotal, lookupFailed: importerLookupFailed });
-    return { exitCode: policyPassed && androidPassed && iosPassed && pwaPassed && expose.passed ? 0 : 1, lines, changedFiles: selection.files, testFiles, unverified: scope.unverified, documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests, alwaysIncludeMissing, importerTestsAdded, baseline: { introduced: 0, preexisting: 0, unknown: 0, preconditionUnmet: 0 } };
+    return { exitCode: policyPassed && androidPassed && iosPassed && pwaPassed && entryBudgetPassed && expose.passed ? 0 : 1, lines, changedFiles: selection.files, testFiles, unverified: scope.unverified, documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests, alwaysIncludeMissing, importerTestsAdded, baseline: { introduced: 0, preexisting: 0, unknown: 0, preconditionUnmet: 0 } };
   }
 
   if (worktreeLog.includes('deterministic environment setup failed')) lines.push(worktreeLog);
   const baseline = (deps.runBaseline ?? runGateBaseline)(cwd, testFiles, selection.baseRef);
-  const report = buildGateBaselineReport(worktreeLog, baseline);
+  const report = recheckTimeoutOnlyIntroducedFailures(cwd, buildGateBaselineReport(worktreeLog, baseline), deps.runTimeoutRecheck);
+  capture.timeoutRechecks = report.timeoutRechecks;
   logGateCliBaseline(cwd, {
     introduced: report.introduced,
     preexisting: report.preexisting,
@@ -955,6 +1086,24 @@ function runSelfGateCliCore(cwd: string, options: SelfGateCliOptions, deps: Self
     verdictLine: lines[lines.length - 1],
   } satisfies GateArtifactCapture);
   const policyPassed = runPolicyGates(selection.files, cwd, lines, deps);
-  const exitCode = !androidPassed || !iosPassed || !pwaPassed || !policyPassed || !expose.passed || report.introduced > 0 || report.unknown > 0 || report.preconditionUnmet > 0 ? 1 : 0;
+  const exitCode = !androidPassed || !iosPassed || !pwaPassed || !entryBudgetPassed || !policyPassed || !expose.passed || report.introduced > 0 || report.unknown > 0 || report.preconditionUnmet > 0 ? 1 : 0;
   return { exitCode, lines, changedFiles: selection.files, testFiles, unverified: scope.unverified, documentPaths: scope.documentPaths, documentsWithoutDerivedTests: scope.documentsWithoutDerivedTests, alwaysIncludeMissing, importerTestsAdded, baseline: { introduced: report.introduced, preexisting: report.preexisting, unknown: report.unknown, preconditionUnmet: report.preconditionUnmet } };
 }
+
+/** GATE-REMOTE-SHARD-PLAN — a shard plan plus the ready-to-run remote command for each shard. */
+export interface RemoteGateShardPlan {
+  orchestrationId: string;
+  shards: GateRemoteShard[];
+  commands: string[][];
+}
+
+/** Turn a changed-file list into identity-carrying shards and their remote gate commands (shard-plan → shard-run wiring). */
+export function planRemoteGateShardCommands(
+  files: readonly string[],
+  shardCount: number,
+  options?: { planFile?: string; orchestrationId?: string },
+): RemoteGateShardPlan {
+  const orchestrationId = options?.orchestrationId ?? shardPlanOrchestrationId(files);
+  const shards = planGateRemoteShards(files, shardCount, orchestrationId);
+  return { orchestrationId, shards, commands: shards.map((shard) => remoteShardArgv(shard, options)) };
+}

package/src/self-implement/gate-failure-signature.ts

@@ -0,0 +1,44 @@
+import { createHash } from 'node:crypto';
+import type { SelfImplementGateResult } from './orchestrator.js';
+
+export interface GateFailureReceipt {
+  signature: `sha256:${string}`;
+  tests: string[];
+}
+
+/** Only measured, introduced, non-timeout test failures are stable enough to stop a repeated repair. */
+export function gateFailureReceipt(gate: SelfImplementGateResult | undefined): GateFailureReceipt | null {
+  if (!gate || gate.passed || gate.testStepExecuted !== true || !gate.baselineFailures
+    || !gate.reflectGateFacts || gate.reflectGateFacts.unknown !== 0
+    || (gate.reflectGateFacts.timedOut ?? 0) > 0 || (gate.reflectGateFacts.rerunNotRun ?? 0) > 0
+    || (gate.reflectGateFacts.mayVaryNonTimeout ?? 0) > 0) return null;
+  const introduced = gate.baselineFailures.filter((failure) => failure.attribution === 'introduced');
+  if (!introduced.length || introduced.length !== gate.reflectGateFacts.introduced) return null;
+  const normalized: Array<{ file: string; name: string; kind: string }> = [];
+  for (const failure of introduced) {
+    const file = failure.file?.replace(/\\/g, '/').trim();
+    const name = failure.name.normalize('NFC').replace(/\s+/g, ' ').trim();
+    if (!file || file.startsWith('/') || /^[A-Za-z]:\//.test(file) || file.split('/').includes('..')
+      || !name || /[\r\n]/.test(name)
+      || failure.timeoutRegression || /\btimed out\b|\btimeout\b/i.test(failure.diagnostic ?? '')) return null;
+    const diagnostic = failure.diagnostic ?? '';
+    const kind = /module not found|cannot find module|ERR_MODULE_NOT_FOUND/i.test(diagnostic) ? 'module-load'
+      : /expect\(|AssertionError|Expected:/i.test(diagnostic) ? 'assertion'
+      : /\berror:/i.test(diagnostic) ? 'runtime-error' : 'test-failure';
+    normalized.push({ file, name, kind });
+  }
+  normalized.sort((a, b) => {
+    const left = JSON.stringify(a);
+    const right = JSON.stringify(b);
+    return left < right ? -1 : left > right ? 1 : 0;
+  });
+  const unique = [...new Map(normalized.map((entry) => [JSON.stringify(entry), entry])).values()];
+  if (unique.length !== introduced.length) return null;
+  const signature = `sha256:${createHash('sha256').update(JSON.stringify(unique)).digest('hex')}` as const;
+  return { signature, tests: unique.map(({ file, name, kind }) => `${file} > ${name} (${kind})`) };
+}
+
+/** The worker reads these exact lines from harness stdout and persists the receipt. */
+export function gateFailureReceiptLines(receipt: GateFailureReceipt): string[] {
+  return [`GATE_FAILURE_SIGNATURE=${receipt.signature}`, `GATE_FAILURE_TESTS=${JSON.stringify(receipt.tests)}`];
+}