elanous 0.2.29 → 0.2.31

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

@@ -1,7 +1,9 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync, lstatSync, mkdtempSync, readFileSync, realpathSync } from 'node:fs';
+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 { 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';
 import { runDaemonPortGate } from '../../scripts/ci-daemon-port-gate.js';
@@ -24,18 +26,29 @@ import {
   overlapWithCurrentChanges,
 } from '../cli/pr-granularity.js';
 import { listWorktrees } from '../git-fs/worktree.js';
-import { runShardedGateTests } from '../self-dev/shard-run.js';
+import { runShardedGateTests, writeShardFailureEvidence } from '../self-dev/shard-run.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';
 
 export interface SelfGateCliOptions {
   base?: string;
   pr?: string;
   shards?: 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;
   /** LIGHT-RC (0.2.19) — repository-relative test paths run on every call, whatever changed. Existing ones join the
    *  run (deduplicated, same introduced/preexisting baseline as the rest); missing ones go to `alwaysIncludeMissing`. */
   alwaysInclude?: readonly string[];
   /** RELEASE-DAILY-LIGHT-RC ② — run every tracked test that imports a changed (non-test) source, past the caller cap
    *  (importer index · reason=changed-source-importer). Off by default: the plain `self gate` scope is unchanged. */
   includeImporterTests?: boolean;
+  /** Optional v0 scenario JSON. Adds selected tests only after binding base/head/diff. */
+  scenario?: unknown;
+  scenarioFile?: string;
+  /** SIDE-VERIFY — 조각별 지금/기준 JUnit ⊕ summary.json 을 이 디렉토리에 «쓰기만» 한다(판정·exit·기존 줄 불변). */
+  artifactDir?: string;
 }
 
 interface ProcessResult {
@@ -81,6 +94,7 @@ export interface DirtyWorktreeClassification {
 interface SelfGateCliDeps {
   changedFiles?: (cwd: string, options: SelfGateCliOptions) => ChangedFileSelection;
   exists?: (path: string) => boolean;
+  isRegularFile?: (cwd: string, path: string) => boolean;
   runCommand?: (command: string, args: string[], cwd: string) => ProcessResult;
   readFile?: (path: string) => string | undefined;
   runTests?: (cwd: string, files: readonly string[]) => ProcessResult;
@@ -99,6 +113,45 @@ interface SelfGateCliDeps {
   runPwaGate?: (out: GateOutput) => number;
   listPrWorktrees?: (cwd: string) => PrWorktreeListEntry[] | { lookupFailed: string };
   inspectWorktreeDirtiness?: (path: string) => { dirty: boolean } | { lookupFailed: string };
+  /** `--artifact-dir` 전용 심 — 커밋 sha 해석(실패 = null) · 환경 키. */
+  resolveRev?: RevResolver;
+  envKey?: () => string;
+}
+
+/** `--artifact-dir` 가 쓸 재료 — 판정 경로가 «채우기만» 하고 읽지 않는다. */
+interface GateArtifactCapture {
+  baseRef?: string;
+  testFiles?: readonly string[];
+  sharded?: ReturnType<typeof runShardedGateTests>;
+  verdict?: string;
+  verdictLine?: string;
+  unmeasuredReason?: string;
+  unshardedRc?: number | null;
+  artifactsUnavailable?: GateArtifactsUnavailable;
+  /** `unrun importer tests: N` 의 N — 색인 조회 실패면 null(그 이유가 importerLookupFailed). */
+  unrunImporters?: number | null;
+  importerLookupFailed?: string;
+}
+
+/** SIDE-VERIFY ③ — summary 정수 칸: 게이트가 이미 낸 `result.baseline` ⊕ `unrunImporterTotal` 을 «옮기기만» 한다.
+ *  baseline 이 없으면(조각 unmeasured) 넷은 null — 「0」으로 접지 않는다. */
+export function gateArtifactCounts(result: Pick<SelfGateCliResult, 'baseline'>, capture: Pick<GateArtifactCapture, 'unrunImporters' | 'importerLookupFailed' | 'unmeasuredReason'>):
+  { counts: GateArtifactCounts; reason?: string } {
+  const baseline = result.baseline;
+  const unrunImporters = capture.unrunImporters ?? null;
+  const reasons: string[] = [];
+  if (!baseline) reasons.push(capture.unmeasuredReason !== undefined ? `shards unmeasured (${capture.unmeasuredReason})` : 'test step produced no measurement');
+  if (unrunImporters === null) reasons.push(`importer lookup failed${capture.importerLookupFailed ? ` (${capture.importerLookupFailed})` : ''}`);
+  return {
+    counts: {
+      introduced: baseline?.introduced ?? null,
+      preexisting: baseline?.preexisting ?? null,
+      unknown: baseline?.unknown ?? null,
+      preconditionUnmet: baseline?.preconditionUnmet ?? null,
+      unrunImporters,
+    },
+    ...(reasons.length ? { reason: reasons.join('; ') } : {}),
+  };
 }
 
 interface GateOutput {
@@ -178,7 +231,7 @@ function defaultRunCommand(command: string, args: string[], cwd: string): Proces
   if (command === 'bun' && args[0] === 'test') {
     let isolated: ReturnType<typeof prepareDeterministicChildEnvironment>;
     try {
-      isolated = prepareDeterministicChildEnvironment('elanous-gate-cli-test-env-');
+      isolated = prepareDeterministicChildEnvironment('elanous-gate-cli-test-env-', { env: withGateTestEnv(process.env) });
     } catch (error) {
       const message = `deterministic environment setup failed: ${String(error)}`;
       return { status: null, stdout: '', stderr: message, error: error instanceof Error ? error : new Error(message) };
@@ -592,9 +645,10 @@ function logGateCliBaseline(cwd: string, payload: GateCliBaselinePayload): void
   }
 }
 
-export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, deps: SelfGateCliDeps = {}): 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');
+type GateSelectionOptions = Pick<SelfGateCliOptions, 'base' | 'pr' | 'alwaysInclude' | 'includeImporterTests' | 'scenario' | 'scenarioFile'>;
+type GateSelectionDeps = Pick<SelfGateCliDeps, 'changedFiles' | 'exists' | 'isRegularFile' | 'runCommand'>;
+
+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}`));
   // Caller: src/release-loop/light-rc.ts runLightRc → runSelfGateCli(dir, { ..., includeImporterTests: true }).
@@ -607,13 +661,35 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
     ? buildRouteConsumerTestIndex(cwd, availableIndex.testPaths, selection.files, selection.baseRef) : null;
   const scope = resolveGateScope(selection.files, exists, availableIndex,
     { routeConsumerTestIndex: routeIndex ?? undefined });
-  const expose = publicExposureFiles(selection.files).length > 0
-    ? runExposeGate(cwd, selection.files, getUserConfig().harness?.exposeGate === 'strict' ? 'strict' : 'warn', deps.runCommand)
-    : { passed: true, log: '' };
+  return { selection, exists, lookupFailed, availableIndex, routeIndex, scope };
+}
+
+function finishGateTestSelection(prepared: ReturnType<typeof prepareGateTestSelection>, options: GateSelectionOptions, cwd: string, deps: GateSelectionDeps) {
+  const { selection, exists, lookupFailed, availableIndex, routeIndex, scope } = prepared;
   const alwaysInclude = [...new Set((options.alwaysInclude ?? []).map(normalizeGatePath).filter(Boolean))];
   const alwaysIncludeMissing = alwaysInclude.filter((path) => !exists(path));
   const scopedTests = scope.testArgs ?? [];
   const alwaysIncludeExtra = alwaysInclude.filter((path) => exists(path) && !scopedTests.includes(path));
+  let scenarioTests: string[] = [];
+  if (options.scenario !== undefined || options.scenarioFile !== undefined) {
+    if (options.scenario !== undefined && options.scenarioFile !== undefined) throw new Error('choose scenario or scenarioFile');
+    const run = deps.runCommand ?? defaultRunCommand;
+    const headSha = requireOutput(run, 'git', ['rev-parse', 'HEAD'], cwd).trim();
+    const baseSha = options.base
+      ? requireOutput(run, 'git', ['merge-base', options.base, 'HEAD'], cwd).trim()
+      : requireOutput(run, 'git', ['rev-parse', selection.baseRef], cwd).trim();
+    const scenario = parseGateScenario(options.scenarioFile === undefined ? options.scenario : readGateScenarioFile(options.scenarioFile), { baseSha, headSha, changedFiles: selection.files });
+    scenarioTests = scenario.selectedTests.map(({ path }) => path);
+    if (scenarioTests.some((path) => !exists(path))) throw new Error('gate scenario invalid: selected test missing');
+    const isRegularFile = deps.isRegularFile ?? ((dir: string, path: string) => {
+      try {
+        const root = realpathSync(dir);
+        const target = join(dir, path);
+        return lstatSync(target).isFile() && realpathSync(target).startsWith(`${root}/`);
+      } catch { return false; }
+    });
+    if (scenarioTests.some((path) => !isRegularFile(cwd, path))) throw new Error('gate scenario invalid: selected test is not a regular file');
+  }
   // 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));
@@ -621,14 +697,90 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
     ? [...new Set(changedSources.flatMap((source) => availableIndex.testsBySource.get(source) ?? []))]
       .filter((path) => exists(path) && !scopedTests.includes(path) && !alwaysIncludeExtra.includes(path)).sort()
     : [];
-  const testFiles = [...scopedTests, ...alwaysIncludeExtra, ...importerTestsAdded];
-  const skipTestStep = scope.skipTestStep && alwaysIncludeExtra.length === 0 && importerTestsAdded.length === 0;
-  const importerTestsNotRun = options.includeImporterTests && availableIndex
+  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;
   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));
+  const callerTestsOverflow = scope.callerTestsOverflow.filter(({ file }) => !importerTestsAdded.includes(file) && !scenarioTests.includes(file));
   const importerLookupFailed = Boolean(lookupFailed);
+  return { ...prepared, alwaysInclude, alwaysIncludeMissing, alwaysIncludeExtra, importerTestsAdded, scenarioTests,
+    testFiles, skipTestStep, importerTestsNotRun, unrunImporterTotal, callerTestsOverflow, importerLookupFailed };
+}
+
+/** Read-only preflight for the same changed-file → importer → scope selection used by `self gate`. */
+export function selectGateTestFiles(cwd: string, options: GateSelectionOptions = {}, deps: GateSelectionDeps = {}) {
+  if (options.base && options.pr) throw new Error('use either --base <ref> or --pr <number>, not both');
+  const picked = finishGateTestSelection(prepareGateTestSelection(cwd, options, deps), options, cwd, deps);
+  return {
+    changedFiles: picked.selection.files,
+    baseRef: picked.selection.baseRef,
+    reason: picked.scope.reason,
+    testFiles: picked.testFiles,
+    skipTestStep: picked.skipTestStep,
+    unverified: picked.scope.unverified,
+    alwaysIncludeMissing: picked.alwaysIncludeMissing,
+    importerTestsAdded: picked.importerTestsAdded,
+    importerTestsNotRun: picked.importerTestsNotRun,
+    unrunImporterTotal: picked.unrunImporterTotal,
+    lookupFailed: picked.lookupFailed,
+    routeLookupFailures: picked.routeIndex?.lookupFailures ?? [],
+    callerTestsOverflow: picked.callerTestsOverflow,
+  };
+}
+
+export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, deps: SelfGateCliDeps = {}): SelfGateCliResult {
+  const capture: GateArtifactCapture = {};
+  const result = runSelfGateCliCore(cwd, options, deps, capture);
+  if (options.artifactDir !== undefined) emitGateArtifacts(cwd, options.artifactDir, result, capture, deps);
+  return result;
+}
+
+/** 쓰기 실패는 «경고 한 줄»로만 접는다 — 판정·exit 코드는 그대로다. */
+function emitGateArtifacts(cwd: string, artifactDir: string, result: SelfGateCliResult, capture: GateArtifactCapture, deps: SelfGateCliDeps): void {
+  if (!artifactDir.trim()) {
+    result.lines.push('⚠ artifacts: --artifact-dir 가 빈 경로라 안 썼다 (판정은 그대로다)');
+    return;
+  }
+  const dir = resolveArtifactDir(artifactDir, cwd);
+  try {
+    const resolveRev = deps.resolveRev ?? defaultRevResolver(cwd);
+    const counts = gateArtifactCounts(result, capture);
+    const written = writeGateArtifacts({
+      dir,
+      head40: resolveRev('HEAD'),
+      base40: capture.baseRef ? resolveRev(capture.baseRef) : null,
+      envKey: (deps.envKey ?? defaultGateEnvKey)(),
+      testFiles: capture.testFiles ?? result.testFiles,
+      verdict: capture.verdict ?? null,
+      ...(capture.verdictLine !== undefined ? { verdictLine: capture.verdictLine } : {}),
+      exitCode: result.exitCode,
+      counts: counts.counts,
+      ...(counts.reason !== undefined ? { countsUnavailableReason: counts.reason } : {}),
+      ...(capture.unmeasuredReason !== undefined ? { unmeasuredReason: capture.unmeasuredReason } : {}),
+      ...(capture.sharded ? { sharded: capture.sharded } : {}),
+      ...(capture.unshardedRc !== undefined ? { unshardedRc: capture.unshardedRc } : {}),
+      ...(capture.artifactsUnavailable ? { artifactsUnavailable: capture.artifactsUnavailable } : {}),
+    });
+    result.lines.push(`artifacts: ${written.summaryPath} (junit ${written.junitFiles.length}${capture.artifactsUnavailable ? ` · unavailable=${capture.artifactsUnavailable}` : ''})`);
+  } catch (error) {
+    result.lines.push(`⚠ artifacts: ${dir} 에 못 썼다 — ${error instanceof Error ? error.message : String(error)} (판정은 그대로다)`);
+  }
+}
+
+function runSelfGateCliCore(cwd: string, options: SelfGateCliOptions, deps: SelfGateCliDeps, capture: GateArtifactCapture): 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.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,
+    skipTestStep, importerTestsNotRun, unrunImporterTotal, callerTestsOverflow, importerLookupFailed } = finishGateTestSelection(prepared, options, cwd, deps);
   const lines = [
     // ⛔⭐ 「changed=0」을 «초록»으로 읽는 사고가 났다(2026-09-02 · 🅕 보고 · 🅣 재현).
     //   커밋 «전»에 돌리면 작업 트리 변경은 «안 세므로» changed=0 이 나오는데,
@@ -662,8 +814,13 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
     ...(options.includeImporterTests
       ? [`importer tests added: ${lookupFailed ? `lookup failed (${lookupFailed})` : `${importerTestsAdded.length} (reason=changed-source-importer${importerTestsAdded.length ? ` · ${importerTestsAdded.join(', ')}` : ''})`}`]
       : []),
+    ...(options.scenario !== undefined || options.scenarioFile !== undefined ? [`scenario tests: ${scenarioTests.length} (${scenarioTests.join(', ')})`] : []),
   ];
   if (expose.log) lines.push(expose.log);
+  capture.baseRef = selection.baseRef;
+  capture.testFiles = skipTestStep ? [] : testFiles;
+  capture.unrunImporters = unrunImporterTotal;
+  if (lookupFailed) capture.importerLookupFailed = lookupFailed;
   if (options.pr) {
     const worktreeObservation = observePrWorktreeDirtiness(cwd, selection.prHeadRefName, {
       runCommand: deps.runCommand,
@@ -687,12 +844,22 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
   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 } };
   }
 
-  if (options.shards !== undefined) {
-    const sharded = (deps.runShards ?? runShardedGateTests)(cwd, testFiles, selection.baseRef, options.shards);
-    lines.push(`shards: ${sharded.shards.length} (${sharded.shards.map((shard) => `${shard.id}=${shard.files.join(',')}`).join('; ')})${sharded.measurementFailures ? ` · 측정 실패 ${sharded.measurementFailures}` : ''}`);
+  // The default direct Bun path has one process and one 300s limit. Route real child/PTY tests through
+  // the separated shard runner even when the caller did not request --shards.
+  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.measurementFailures ? ` · 측정 실패 ${sharded.measurementFailures}` : ''}${options.fixedShardDistribution ? ' · 고정 분배(사전 측정 없음)' : ''}`);
     // 조각이 «못 쟀다»일 때 이유가 줄에 없으면 자리·시간 초과·죽음을 가를 수 없다(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) {
@@ -705,12 +872,23 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
       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 { aggregate } = sharded;
     let shardBaseline: SelfGateCliResult['baseline'];
     let unmeasuredReason: string | undefined;
     if (aggregate.status === 'unmeasured') {
       unmeasuredReason = aggregate.retryShardIds.join(', ') || sharded.reason || 'no complete JUnit';
       lines.push(`shards: unmeasured (${unmeasuredReason})`);
+      capture.unmeasuredReason = unmeasuredReason;
     }
     else if (aggregate.report) {
       const report = aggregate.report;
@@ -727,6 +905,7 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
       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,
@@ -739,8 +918,10 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
 
   const test = (deps.runTests ?? ((dir, files) => (deps.runCommand ?? defaultRunCommand)('bun', ['test', ...files], dir)))(cwd, testFiles);
   const worktreeLog = formatProcessOutput(test);
+  Object.assign(capture, { unshardedRc: test.status, artifactsUnavailable: 'unsharded' } satisfies GateArtifactCapture);
   if (test.status === 0 && !test.error) {
     lines.push(formatPartialObservationNote(unrunImporterTotal ?? 0, `tests: pass (${testFiles.length} files)`));
+    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 } };
@@ -763,6 +944,10 @@ export function runSelfGateCli(cwd: string, options: SelfGateCliOptions = {}, de
     lookupFailed: importerLookupFailed,
   });
   lines.push(formatPartialObservationNote(unrunImporterTotal ?? 0, formatGateBaselineNote(report, unrunImporterTotal ?? 0)));
+  Object.assign(capture, {
+    verdict: report.introduced > 0 || report.unknown > 0 || report.preconditionUnmet > 0 ? 'failed' : 'passed',
+    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;
   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 } };

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

@@ -7,6 +7,7 @@ import { existsSync, lstatSync, realpathSync } from 'node:fs';
 import { loadavg } from 'node:os';
 import { isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { debug } from '../debug/log.js';
+import { gateHostReservationRoot, inspectReleaseGateHost } from '../release-loop/gate-host-reservation.js';
 import type { GateRemoteConfig } from '../user-config.js';
 
 export type GateRemoteTool = 'self-gate' | 'ci-typecheck-changed' | 'public-export-test-run';
@@ -16,14 +17,15 @@ export interface GateRemoteSettings {
   host: string;
   loadThreshold: number;
   hostCap: number;
+  hostCaps?: Record<string, number>;
   mirror: string;
   slotWaitSeconds: number;
 }
 
-export const MAX_HOST_CAP = 2;
+export const MAX_HOST_CAP = 8;
 
 export const GATE_REMOTE_DEFAULTS: GateRemoteSettings = {
-  enabled: true, host: 'node-b', loadThreshold: 20, hostCap: 2, mirror: '~/mirror/elanous-agent.git', slotWaitSeconds: 600,
+  enabled: true, host: 'node-b', loadThreshold: 20, hostCap: 2, hostCaps: {}, mirror: '~/mirror/elanous-agent.git', slotWaitSeconds: 600,
 };
 
 const hostPattern = /^(?:[\w.-]+@)?[\w.-]+$/;
@@ -43,13 +45,23 @@ export function resolveGateRemoteSettings(config: GateRemoteConfig | undefined,
     enabled: config?.enabled ?? envEnabled ?? GATE_REMOTE_DEFAULTS.enabled,
     host: isValidGateHost(host) ? host : GATE_REMOTE_DEFAULTS.host,
     loadThreshold: config?.loadThreshold ?? envLoad ?? GATE_REMOTE_DEFAULTS.loadThreshold,
-    // The cell's ceiling is 2 per host (GATE-REMOTE acceptance); config may only lower it.
-    hostCap: Math.min(MAX_HOST_CAP, Math.max(1, Math.floor(config?.hostCap ?? GATE_REMOTE_DEFAULTS.hostCap))),
+    hostCap: Math.min(GATE_REMOTE_DEFAULTS.hostCap, Math.max(1, Math.floor(config?.hostCap ?? GATE_REMOTE_DEFAULTS.hostCap))),
+    hostCaps: Object.fromEntries(Object.entries(config?.hostCaps ?? {}).filter(([key, value]) =>
+      isValidGateHost(key) && Number.isSafeInteger(value) && value >= 1 && value <= MAX_HOST_CAP)),
     mirror: mirrorPattern.test(mirror) && !mirror.split('/').includes('..') ? mirror : GATE_REMOTE_DEFAULTS.mirror,
     slotWaitSeconds: config?.slotWaitSeconds ?? GATE_REMOTE_DEFAULTS.slotWaitSeconds,
   };
 }
 
+/** Explicit and rerouted hosts use their own slot budget; absent entries retain the default cap. */
+export function gateRemoteHostCap(settings: GateRemoteSettings, host: string): number {
+  const caps = settings.hostCaps;
+  const bareHost = host.split('@').at(-1)!;
+  const configured = caps && Object.hasOwn(caps, host) ? caps[host]
+    : caps && Object.hasOwn(caps, bareHost) ? caps[bareHost] : undefined;
+  return Math.min(MAX_HOST_CAP, Math.max(1, Math.floor(configured ?? settings.hostCap)));
+}
+
 /** The token after a bare `--remote` is its host when it is a valid ssh destination that is not an existing path and does
  *  not look like a test/list file — so `--remote node-b.lan a.test.ts` takes the host and `--remote a.test.ts` keeps the file. */
 export function looksLikeHost(token: string, exists: (path: string) => boolean = existsSync): boolean {
@@ -105,17 +117,21 @@ export type SlotLockTool = 'flock' | 'lockf';
 const SLOT_LOCK = { flock: 'flock -n', lockf: 'lockf -k -s -t 0' } as const;
 
 /** `tools` is the preference order (default: Linux flock, then BSD/macOS lockf); a test can pin one path. */
-export function hostSlotScript(cap: number, dir = SLOT_DIR, tools: readonly SlotLockTool[] = ['flock', 'lockf']): string[] {
+function hostSlotScriptWithSlot(cap: number, dir: string, tools: readonly SlotLockTool[], passSlot: boolean): string[] {
   const n = Math.min(MAX_HOST_CAP, Math.max(1, Math.floor(cap)));
   const pick = tools.map((tool, i) => `${i ? 'elif' : 'if'} command -v ${tool} >/dev/null 2>&1; then GL="${SLOT_LOCK[tool]}"; `).join('');
   return [
     `GS=${quote(dir)}; mkdir -p "$GS" || infra slots`,
     `${pick}else infra lock-tool; fi`,
-    `n=1; while [ $n -le ${n} ]; do $GL "$GS/slot$n" sh "$W/run.sh"; s=$?; [ -f "$W/started" ] && exit $s; n=$((n+1)); done`,
-    `echo "${BUSY}" >&2; exit 98`,
+    `n=1; while [ $n -le ${n} ]; do $GL "$GS/slot$n" ${passSlot ? 'env GATE_REMOTE_SLOT="$n" ' : ''}sh "$W/run.sh"; s=$?; [ -f "$W/started" ] && exit $s; n=$((n+1)); done`,
+    `echo "${BUSY}=$((n-1))" >&2; exit 98`,
   ];
 }
 
+export function hostSlotScript(cap: number, dir = SLOT_DIR, tools: readonly SlotLockTool[] = ['flock', 'lockf']): string[] {
+  return hostSlotScriptWithSlot(cap, dir, tools, false);
+}
+
 // ── remote execution ───────────────────────────────────────────────
 
 export interface ExecResult { rc: number | null; stdout: string; stderr: string; error?: string }
@@ -149,7 +165,7 @@ export const PUSH_TIMEOUT_MS = 10 * 60_000;
 
 export type RemoteRunOutcome =
   | { kind: 'ran'; rc: number; stdout: Buffer; stderr: Buffer; commit: string; host: string; ms: number }
-  | { kind: 'busy' }
+  | { kind: 'busy'; occupied?: number }
   | { kind: 'infra'; reason: string };
 
 export interface RemoteRunOptions {
@@ -167,6 +183,8 @@ export interface RemoteRunOptions {
   /** Extra local refs whose commits must exist remotely (e.g. a --base ref). Resolved to shas. */
   refs?: string[];
   installPwa?: boolean;
+  /** An exclusive slot checkout path allows the opt-in TypeScript graph cache to survive scratch runs. */
+  stableCheckout?: boolean;
   timeoutMs?: number;
   /** Files the remote run needs from this machine (e.g. the private export redaction table): sent over ssh stdin, written
    *  mode 600 inside the scratch directory, exposed to the tool via `env`, removed with it. Never on argv. */
@@ -177,7 +195,7 @@ export interface PayloadFile { env: string; content: string }
 export type RemoteArgv = string[] | ((sha: (ref: string) => string) => string[]);
 
 /** Build the remote shell script (exported for tests). Every setup failure ends in an INFRA marker, the tool's rc in an RC marker. */
-export function remoteScript(input: { mirror: string; commit: string; fetchShas: string[]; mainSha?: string; argv: string[]; installPwa: boolean; payloadFiles?: PayloadFile[]; hostCap?: number; slotDir?: string }): string {
+export function remoteScript(input: { mirror: string; commit: string; fetchShas: string[]; mainSha?: string; argv: string[]; installPwa: boolean; stableCheckout?: boolean; payloadFiles?: PayloadFile[]; hostCap?: number; slotDir?: string }): string {
   const mirror = input.mirror.startsWith('~/') ? `"$HOME"/${quote(input.mirror.slice(2))}` : quote(input.mirror);
   const fetches = input.fetchShas.map((sha) => `refs/elanous/gate/${sha}:refs/elanous/gate/${sha}`).join(' ');
   const payloads = (input.payloadFiles ?? []).filter((file) => /^[A-Z_][A-Z0-9_]*$/.test(file.env));
@@ -193,8 +211,25 @@ export function remoteScript(input: { mirror: string; commit: string; fetchShas:
   const work = [
     `infra() { echo "${INFRA}$1" >&2; exit 97; }`,
     ': > "$W/started"',
-    `git clone -q --shared --no-checkout ${mirror} "$W/t" >"$W/setup.log" 2>&1 || infra clone`,
-    'cd "$W/t" || infra cd',
+    ...(input.stableCheckout ? [
+      'T="$HOME/.cache/elanous/gate-remote/slot$GATE_REMOTE_SLOT/checkout"',
+      'mkdir -p "$(dirname "$T")" || infra stable-dir',
+      'if [ -d "$T/.git" ]; then',
+      '  git -C "$T" reset --hard -q >>"$W/setup.log" 2>&1 || infra stable-reset',
+      '  git -C "$T" clean -ffd -q >>"$W/setup.log" 2>&1 || infra stable-clean',
+      `  git -C "$T" remote set-url origin ${mirror} >>"$W/setup.log" 2>&1 || infra stable-origin`,
+      'else',
+      '  rm -rf "$T" || infra stable-remove',
+      `  git clone -q --shared --no-checkout ${mirror} "$T" >"$W/setup.log" 2>&1 || infra clone`,
+      'fi',
+      'rm -rf "$T/apps/pwa/.next" || infra pwa-build-clean',
+      'rm -f "$T/apps/pwa/"*.tsbuildinfo || infra pwa-buildinfo-clean',
+      'ELANOUS_TSC_CACHE_DIR="$HOME/.cache/elanous/gate-remote/slot$GATE_REMOTE_SLOT/cache"; export ELANOUS_TSC_CACHE_DIR',
+    ] : [
+      'T="$W/t"',
+      `git clone -q --shared --no-checkout ${mirror} "$T" >"$W/setup.log" 2>&1 || infra clone`,
+    ]),
+    'cd "$T" || infra cd',
     `git fetch -q origin ${fetches} >>"$W/setup.log" 2>&1 || infra fetch`,
     `git checkout -q --detach ${input.commit} >>"$W/setup.log" 2>&1 || infra checkout`,
     ...(input.mainSha ? [`git update-ref refs/remotes/origin/main ${input.mainSha} || infra origin-main`] : []),
@@ -221,7 +256,7 @@ export function remoteScript(input: { mirror: string; commit: string; fetchShas:
     `cat > "$W/run.sh" <<'${RUN}' || infra run-script`,
     ...work,
     RUN,
-    ...hostSlotScript(input.hostCap ?? GATE_REMOTE_DEFAULTS.hostCap, input.slotDir),
+    ...hostSlotScriptWithSlot(input.hostCap ?? GATE_REMOTE_DEFAULTS.hostCap, input.slotDir ?? SLOT_DIR, ['flock', 'lockf'], !!input.stableCheckout),
     '}',
     '',
   ].join('\n');
@@ -277,7 +312,7 @@ export function runOnRemote(opts: RemoteRunOptions, runner: GateRemoteRunner = r
     env: { ...process.env, GIT_SSH_COMMAND: 'ssh -o BatchMode=yes -o ConnectTimeout=10', GIT_TERMINAL_PROMPT: '0' },
   });
   if (push.rc !== 0 || push.error) return { kind: 'infra', reason: `push-failed rc=${push.rc}: ${(push.stderr || push.error || '').trim().split('\n').slice(-2).join(' | ')}` };
-  const script = remoteScript({ mirror: opts.mirror, commit, fetchShas: shas, mainSha, argv, installPwa: opts.installPwa ?? false, payloadFiles: opts.payloadFiles, hostCap: opts.hostCap, slotDir: opts.slotDir });
+  const script = remoteScript({ mirror: opts.mirror, commit, fetchShas: shas, mainSha, argv, installPwa: opts.installPwa ?? false, stableCheckout: opts.stableCheckout, payloadFiles: opts.payloadFiles, hostCap: opts.hostCap, slotDir: opts.slotDir });
   const run = runner.ssh(opts.host, script, opts.timeoutMs ?? 120 * 60_000);
   // The script prints "\n<marker><rc>\n": everything before that leading newline is the tool's own stderr, byte for byte.
   const stdoutBytes = Buffer.from(run.stdout);
@@ -288,7 +323,10 @@ export function runOnRemote(opts: RemoteRunOptions, runner: GateRemoteRunner = r
   // run exits 0 after the rc marker, and its stderr belongs to the tool — never scanned for markers.
   if (!(run.rc === 0 && marker >= 0)) {
     const last = stderrText.trimEnd().split('\n').at(-1) ?? '';
-    if (run.rc === 98 && last === BUSY) return { kind: 'busy' };
+    if (run.rc === 98) {
+      const busy = /^__GATE_REMOTE_BUSY(?:=(\d+))?$/.exec(last);
+      if (busy) return { kind: 'busy', ...(busy[1] !== undefined ? { occupied: Number(busy[1]) } : {}) };
+    }
     if (run.rc === 97 && last.startsWith(INFRA)) return { kind: 'infra', reason: `remote-${last.slice(INFRA.length).trim()}` };
   }
   // No marker, or ssh did not end cleanly after it (the script always exits 0 once the marker is written): output may be cut.
@@ -371,10 +409,20 @@ export interface DispatchOptions {
   installPwa?: boolean;
   payloadFiles?: PayloadFile[];
   json?: boolean;
-  /** Set when this invocation cannot be reproduced remotely (e.g. self gate without --base): a remote decision becomes a
-   *  logged fallback with this reason instead of a silent local run. */
+  /** Set when this invocation cannot be reproduced remotely (e.g. self gate without --base): automatic placement
+   *  falls back with this reason; an explicit self gate --remote reports an unmeasured check instead. */
   localOnlyReason?: string;
+  /** Self gate CLI only: explicit --remote must never be measured by a local fallback. */
+  explicitRemoteOnly?: boolean;
+  /** Self gate CLI only: name the host for both automatic and explicit remote execution. */
+  reportRemoteHost?: boolean;
+  /** Self gate's state universe; omitted by other callers and injected tests. */
+  reservationRoot?: string;
   runLocal: () => number | Promise<number>;
+  /** Called once with the final remote outcome (never on a local decision), before its output passes through or the
+   *  local fallback runs — e.g. `self gate --artifact-dir` fetches (ran) or removes (infra) the host-side artifact dir.
+   *  A throw is logged and swallowed: the hook never changes the check's rc. */
+  onRemoteOutcome?: (outcome: RemoteRunOutcome, host: string, runner: GateRemoteRunner) => void;
 }
 
 export interface DispatchDeps {
@@ -394,21 +442,52 @@ async function loadSettings(): Promise<GateRemoteSettings> {
   } catch { return resolveGateRemoteSettings(undefined); }
 }
 
-/** Decide local/remote, run, and return the tool's exit code. Infra failure ⇒ local fallback (never a test result). */
+/** Decide local/remote, run, and return the tool's exit code. Automatic infra failure ⇒ visible local fallback. */
 export async function dispatchHeavyCheck(opts: DispatchOptions, deps: DispatchDeps = {}): Promise<number> {
   const settings = deps.settings ?? await loadSettings();
   const env = deps.env ?? process.env;
   const write = deps.write ?? { out: (d: string | Uint8Array) => process.stdout.write(d), err: (d: string | Uint8Array) => process.stderr.write(d) };
   const decision = decideGateDispatch({ flags: opts.flags, settings, load1: deps.load1 ?? loadavg()[0]!, env });
   debug.log('gate.remote', 'decision', { tool: opts.tool, mode: decision.mode, host: decision.host, reason: decision.reason, load1: decision.load1 });
-  if (decision.mode === 'local') return opts.runLocal();
-  const host = decision.host!;
+  if (decision.mode === 'local') {
+    if (opts.explicitRemoteOnly && opts.flags.remote !== undefined && decision.reason !== 'flag-local') {
+      write.err(`[gate.remote] remote unmeasured — ${decision.reason}\n`);
+      return 1;
+    }
+    return opts.runLocal();
+  }
+  let host = decision.host!;
+  const reservationRoot = opts.tool === 'self-gate' ? opts.reservationRoot ?? (deps.runner ? undefined : gateHostReservationRoot()) : undefined;
+  if (reservationRoot) {
+    const reservationHost = host.split('@').at(-1)!;
+    const first = inspectReleaseGateHost(reservationRoot, reservationHost);
+    if (first.status !== 'free') {
+      const alternate = reservationHost === 'node-b' ? 'node-c' : null;
+      const other = alternate ? inspectReleaseGateHost(reservationRoot, alternate) : null;
+      if (alternate && other?.status === 'free') {
+        debug.log('gate.remote', 'host-reserved-reroute', { from: host, to: alternate, reason: first.reason, status: first.status });
+        write.err(`[gate.remote] ${host} reserved (${first.reason}) — using ${alternate}\n`);
+        host = alternate;
+      } else {
+        const reason = `host-reserved: ${host} (${first.reason}); alternate ${alternate ?? '(none)'} ${other?.status ?? 'unavailable'}`;
+        debug.log('gate.remote', 'host-reserved-unmeasured', { host, reason });
+        write.err(`[gate.remote] remote unmeasured — ${reason}\n`);
+        return 1;
+      }
+    }
+  }
   const fallback = (reason: string) => {
+    if (opts.explicitRemoteOnly && opts.flags.remote !== undefined) {
+      debug.log('gate.remote', 'remote-unmeasured', { tool: opts.tool, host, reason });
+      write.err(`[gate.remote] remote unmeasured on ${host} — ${reason.replace(/\s+/g, ' ').trim()}\n`);
+      return 1;
+    }
     debug.log('gate.remote', 'fallback', { tool: opts.tool, host, reason });
     write.err(`[gate.remote] fallback to local — ${reason}\n`);
     return opts.runLocal();
   };
   if (opts.localOnlyReason) return fallback(opts.localOnlyReason);
+  const hostCap = gateRemoteHostCap(settings, host);
   const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
   const now = deps.now ?? Date.now;
   const deadline = now() + settings.slotWaitSeconds * 1000;
@@ -416,26 +495,32 @@ export async function dispatchHeavyCheck(opts: DispatchOptions, deps: DispatchDe
   let outcome: RemoteRunOutcome;
   for (;;) {
     try {
-      outcome = runOnRemote({ repo: opts.repo, host, mirror: settings.mirror, argv: opts.remoteArgv, refs: opts.refs, ...(opts.commit !== undefined ? { commit: opts.commit } : {}), installPwa: opts.installPwa, payloadFiles: opts.payloadFiles, hostCap: settings.hostCap }, deps.runner);
+      outcome = runOnRemote({ repo: opts.repo, host, mirror: settings.mirror, argv: opts.remoteArgv, refs: opts.refs, ...(opts.commit !== undefined ? { commit: opts.commit } : {}), installPwa: opts.installPwa, payloadFiles: opts.payloadFiles, hostCap }, deps.runner);
     } catch (error) {
       outcome = { kind: 'infra', reason: `exception: ${error instanceof Error ? error.message : String(error)}` };
     }
     if (outcome.kind !== 'busy') break;
-    debug.log('gate.remote', 'host-busy', { tool: opts.tool, host, cap: settings.hostCap });
-    // Never start an attempt past the deadline: an expired wait means local, even if a slot would free a moment later.
+    debug.log('gate.remote', 'host-busy', { tool: opts.tool, host, cap: hostCap, occupied: outcome.occupied ?? null });
+    // Never start an attempt past the deadline: an expired wait falls back only for automatic placement.
     const left = deadline - now();
     if (left <= 0) break;
     await sleep(Math.min(15_000, left));
     if (now() >= deadline) break;
   }
-  if (outcome.kind === 'busy') return fallback(`host-busy (cap ${settings.hostCap} held for ${settings.slotWaitSeconds}s)`);
+  if (opts.onRemoteOutcome) {
+    try { opts.onRemoteOutcome(outcome, host, deps.runner ?? realGateRemoteRunner); }
+    catch (error) { debug.log('gate.remote', 'outcome-hook-failed', { tool: opts.tool, host, error: error instanceof Error ? error.message : String(error) }); }
+  }
+  if (outcome.kind === 'busy') return fallback(`host-busy (occupied ${outcome.occupied ?? 'unknown'}/${hostCap}, held for ${settings.slotWaitSeconds}s)`);
   if (outcome.kind === 'infra') return fallback(outcome.reason);
-  // Parity: the tool's own stdout/stderr/rc pass through unchanged — only a JSON stdout gains host · remote:true.
+  // Parity: the tool's own stdout/stderr/rc pass through unchanged; JSON gains host · remote:true,
+  // and the self gate CLI appends a host diagnostic to human-readable stderr.
   debug.log('gate.remote', 'result', { tool: opts.tool, host: outcome.host, commit: outcome.commit, rc: outcome.rc, ms: outcome.ms });
-  // Bytes pass through untouched; only a JSON object stdout is re-serialised (to add host · remote:true).
+  // Tool bytes pass through untouched; only a JSON object stdout is re-serialised (to add host · remote:true).
   const text = opts.json ? outcome.stdout.toString('utf8') : undefined;
   const annotated = text !== undefined ? annotateJsonStdout(text, outcome.host) : undefined;
   write.out(annotated !== undefined && annotated !== text ? annotated : outcome.stdout);
   write.err(outcome.stderr);
+  if (opts.reportRemoteHost && !opts.json) write.err(`[gate.remote] executed on ${outcome.host} (rc=${outcome.rc})\n`);
   return outcome.rc;
 }