session-orchestrator 5.11.0 → 5.13.0

package/scripts/lib/pre-push-local-partial.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// Local partial pre-push gate (#1642): the route the hook takes when no remote host
+// could run the full gate (router exit 10) AND the push goes to an origin MR branch.
+// Exit 0 verified, 1 blocked, 10 not determinable (the hook then runs the full gate
+// locally — fail-closed, same contract as LSO scripts/pre-push-gate.sh, Owner #801).
+//
+// It checks what this push changes since the merge-base with origin's default branch:
+// `node --check` + ESLint on the changed source files and `vitest related` for them.
+// The full suite runs in the MR pipeline on the pushed head SHA.
+//
+// CEILING (BV-004): `vitest related` follows the static import graph. A test that
+// reaches a changed file only by spawning it (hooks, .husky/, CLIs run via
+// spawnSync) or by reading it from disk (policy JSON, Markdown, fixtures — edited OR
+// deleted) is not selected here; the MR pipeline is the net for that class. Only a
+// deleted or renamed SOURCE file falls back to the full gate, because its importers
+// break while nothing is left to select (#1643: falling back on every deletion would
+// send each archive move of a doc to the full local suite).
+// Revisit trigger: an MR pipeline red that a selected-by-path test would have caught
+// locally on a push routed through this gate.
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { isMainModule } from './is-main-module.mjs';
+
+const log = (message) => process.stderr.write(`pre-push: ${message}\n`);
+
+/** Changed files that make a selection meaningless: they reconfigure every test or lint run. */
+const FULL_SUITE_TRIGGERS = [/^package(-lock)?\.json$/, /^vitest\.config\.[cm]?[jt]s$/, /^eslint\.config\.[cm]?[jt]s$/];
+const SOURCE_RE = /\.(mjs|cjs|js)$/;
+
+function git(repoRoot, args) {
+  // core.quotePath=false: git otherwise prints a non-ASCII path as "\303\244.mjs" (quoted,
+  // escaped), and every suffix test below would miss it (#1643).
+  const r = spawnSync('git', ['-C', repoRoot, '-c', 'core.quotePath=false', ...args], { encoding: 'utf8', timeout: 30_000 });
+  return r.status === 0 ? r.stdout.trim() : null;
+}
+
+/**
+ * Merge-base of the pushed SHA with origin's default branch, or null when no
+ * origin default ref resolves in the source repo (the materialised clone has none).
+ */
+export function resolveBase(repoRoot, sha) {
+  const head = git(repoRoot, ['symbolic-ref', '-q', '--short', 'refs/remotes/origin/HEAD']);
+  for (const ref of [head, 'origin/main'].filter(Boolean)) {
+    if (git(repoRoot, ['rev-parse', '-q', '--verify', `${ref}^{commit}`]) === null) continue;
+    return git(repoRoot, ['merge-base', sha, ref]) || null;
+  }
+  return null;
+}
+
+/** Runs one tool from the tree's own node_modules; null when the tool is not installed there. */
+function runTool(tree, bin, args, timeout) {
+  const path = join(tree, 'node_modules/.bin', bin);
+  if (!existsSync(path)) return null;
+  const r = spawnSync(process.execPath, [path, ...args], { cwd: tree, stdio: ['ignore', 2, 2], timeout });
+  return r.status === 0 && !r.error;
+}
+
+async function emit(ledgerRoot, passed, fields) {
+  try {
+    const { emitEvent, sessionAttribution } = await import('./events.mjs');
+    await emitEvent(`orchestrator.quality_gate.${passed ? 'passed' : 'failed'}`, {
+      variant: 'local-partial', exit_code: passed ? 0 : 1, host: 'local', host_source: 'fallback',
+      ...fields, ...sessionAttribution(ledgerRoot),
+    }, { repoRoot: ledgerRoot });
+  } catch { /* telemetry cannot change the blocking verdict */ }
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const [tree, sha, repoRoot] = argv;
+  if (!tree || !sha || !repoRoot) return 10;
+  const base = resolveBase(repoRoot, sha);
+  if (!base) {
+    log('local partial gate: no merge-base with origin\'s default branch — full gate locally (fail-closed).');
+    return 10;
+  }
+  // --no-renames: a rename reads as delete + add, so the old path stays visible.
+  const diff = git(repoRoot, ['diff', '--name-only', '--no-renames', '--diff-filter=d', base, sha]);
+  const deleted = git(repoRoot, ['diff', '--name-only', '--no-renames', '--diff-filter=D', base, sha]);
+  if (diff === null || deleted === null) return 10;
+  // A deleted or renamed module breaks its importers, and `vitest related` cannot
+  // select tests for a file that no longer exists.
+  const gone = deleted.split('\n').find((f) => SOURCE_RE.test(f));
+  if (gone) {
+    log(`local partial gate: ${gone} deleted or renamed — full gate locally (fail-closed).`);
+    return 10;
+  }
+  const changed = diff.split('\n').filter(Boolean);
+  const trigger = changed.find((f) => FULL_SUITE_TRIGGERS.some((re) => re.test(f)));
+  if (trigger) {
+    log(`local partial gate: ${trigger} changed — full gate locally (fail-closed).`);
+    return 10;
+  }
+  const sources = changed.filter((f) => SOURCE_RE.test(f) && existsSync(join(tree, f)));
+  log(`local partial gate: ${changed.length} changed file(s) since ${base.slice(0, 12)}; the full suite runs in the MR pipeline on ${sha.slice(0, 12)} (#1642).`);
+  const fields = { pushed_sha: sha, base_sha: base, changed_count: changed.length };
+  if (changed.length === 0) {
+    await emit(repoRoot, true, fields);
+    return 0;
+  }
+  const syntaxFailed = sources.filter((f) =>
+    spawnSync(process.execPath, ['--check', f], { cwd: tree, stdio: ['ignore', 2, 2], timeout: 30_000 }).status !== 0);
+  if (syntaxFailed.length) log(`local partial gate: node --check failed: ${syntaxFailed.join(', ')}`);
+  const lint = sources.length ? runTool(tree, 'eslint', ['--no-warn-ignored', ...sources], 300_000) : true;
+  const test = runTool(tree, 'vitest', ['related', '--run', '--passWithNoTests', ...changed], 900_000);
+  if (lint === null || test === null) {
+    log('local partial gate: eslint or vitest missing in node_modules — full gate locally (fail-closed).');
+    return 10;
+  }
+  const passed = syntaxFailed.length === 0 && lint && test;
+  const failedChecks = [syntaxFailed.length && 'typecheck', !lint && 'lint', !test && 'test'].filter(Boolean);
+  await emit(repoRoot, passed, { ...fields, ...(failedChecks.length ? { failed_checks: failedChecks } : {}) });
+  log(`local partial gate ${passed ? 'passed' : 'FAILED — Push blocked'}.`);
+  return passed ? 0 : 1;
+}
+
+if (isMainModule(import.meta.url)) process.exitCode = await main();

package/scripts/lib/pre-push-remote-gate.mjs

@@ -1,7 +1,11 @@
 #!/usr/bin/env node
-// Optional pre-push router: 0 verified, 1 blocked, 10 transport/readiness fallback.
+// Optional pre-push router: 0 verified, 1 blocked, 2 SO_GATE_HOSTS invalid or none of its
+// hosts could run the gate (blocked, no local fallback), 10 transport/readiness fallback.
 import { spawnSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
+import { statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 import { readConfigFile } from './config/io.mjs';
 import { _parseRemoteHosts } from './config/remote-hosts.mjs';
 import { isMainModule } from './is-main-module.mjs';
@@ -44,64 +48,186 @@ function remoteCommand(sha, nonce) {
   `;
 }
 
-async function main() {
-  const [tree, sha, ledgerRoot] = process.argv.slice(2);
+const ALIAS_SHAPE = /^[A-Za-z0-9._-]+$/;
+
+/**
+ * Resolve the `SO_GATE_HOSTS` override (#1626) against the offload host registry.
+ *
+ * The registry rule mirrors offload's own `load_host`:
+ * `${OFFLOAD_CONFIG_DIR:-$HOME/.config/remote-offload}/hosts/<alias>.env` must be a
+ * regular file. The alias shape is checked BEFORE any path is built, so `/` and
+ * `..` can never reach the filesystem.
+ *
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {{ hosts: string[], source: 'override' } | { error: string } | null}
+ *   null when the override is unset (whitespace-only counts as unset).
+ */
+export function resolveGateHostOverride(env = process.env) {
+  const raw = (env.SO_GATE_HOSTS || '').trim();
+  if (!raw) return null;
+  const configDir = (env.OFFLOAD_CONFIG_DIR || '').trim() || join((env.HOME || '').trim() || homedir(), '.config/remote-offload');
+  const registry = join(configDir, 'hosts');
+  const hosts = raw.split(',').map((alias) => alias.trim()).filter(Boolean);
+  for (const alias of hosts) {
+    let known = false;
+    if (ALIAS_SHAPE.test(alias) && alias !== '.' && alias !== '..') {
+      try { known = statSync(join(registry, `${alias}.env`)).isFile(); } catch { known = false; }
+    }
+    if (!known) {
+      return { error: `SO_GATE_HOSTS names unknown or invalid host '${alias}' — no regular file ${alias}.env in ${registry}. Push blocked (no local fallback).` };
+    }
+  }
+  return hosts.length ? { hosts, source: 'override' } : { error: `SO_GATE_HOSTS='${raw}' contains no host alias. Push blocked.` };
+}
+
+/** The `gate-ready=<value>` token of an `offload doctor --brief` run (stdout or stderr), or null. */
+function gateReadyToken(doctor) {
+  return /\bgate-ready=(\S+)/.exec(`${doctor.stdout ?? ''}\n${doctor.stderr ?? ''}`)?.[1] ?? null;
+}
+
+/**
+ * Gate readiness of one host (#1627). doctor's exit code also covers headless
+ * readiness, which a gate does not need: a Windows host reports `gate-ready=yes` with
+ * exit 1 because `headless-ready=NO`. The token decides when present; an offload
+ * without it keeps the old exit-code rule. A spawn error (timeout) is not ready.
+ *
+ * @param {{ error?: Error, status: number | null, stdout?: string, stderr?: string }} doctor
+ * @returns {boolean}
+ */
+export function gateReady(doctor) {
+  if (doctor.error) return false;
+  const token = gateReadyToken(doctor);
+  return token === null ? doctor.status === 0 : token === 'yes';
+}
+
+/**
+ * Did the remote gate re-run its timeout-only failures clean (#1673)? Checked
+ * here on the report's own fields, not on `rerun.status` alone: zero failures,
+ * no timeout, no signal sent, no survivor, and exactly the first run's failing
+ * files — no more, no fewer.
+ */
+function cleanRerun(test) {
+  const rerun = test?.rerun;
+  if (rerun?.status !== 'pass' || rerun.failed !== 0 || rerun.timed_out !== false) return false;
+  if (!Array.isArray(rerun.kill_signals) || rerun.kill_signals.length !== 0) return false;
+  if (!Array.isArray(rerun.survivors) || rerun.survivors.length !== 0) return false;
+  const failedFiles = Array.isArray(test.failed_files) ? test.failed_files : [];
+  const files = Array.isArray(rerun.files) ? rerun.files : [];
+  return failedFiles.length > 0 && files.length === failedFiles.length &&
+    new Set(files).size === files.length && failedFiles.every((f) => files.includes(f));
+}
+
+/**
+ * Run the full quality gate for `sha` on a remote host via offload (the body of the
+ * pre-push router, #1712). Exit-code contract of `code`: 0 verified, 1 blocked,
+ * 2 SO_GATE_HOSTS invalid or none of its hosts could run the gate, 10 fallback.
+ *
+ * @param {object} opts
+ * @param {string} opts.tree checkout offload syncs (its basename names the host repo)
+ * @param {string} opts.sha commit the remote gate must check out and verify
+ * @param {string} opts.ledgerRoot repo root for events and wave attribution
+ * @param {NodeJS.ProcessEnv} [opts.env] source of the SO_GATE_HOSTS override
+ * @param {boolean} [opts.emit=true] emit `orchestrator.quality_gate.*` — false for
+ *   callers whose `sha` is not a pushed commit (snapshot probe)
+ * @param {string} [opts.jobPrefix='pre-push'] offload job name prefix
+ * @param {(message: string) => void} [opts.log]
+ * @param {{ write: (chunk: string) => unknown }} [opts.stdout=process.stdout] sink for the remote
+ *   run's stdout — a caller that owns its own stdout (snapshot probe `--json`) routes it elsewhere
+ * @param {{ write: (chunk: string) => unknown }} [opts.stderr=process.stderr] sink for the remote run's stderr
+ * @returns {Promise<{ code: number, passed: boolean, alias: string | null, report: object | null, hostSource: string }>}
+ */
+export async function runRemoteGate({ tree, sha, ledgerRoot, env = process.env, emit = true, jobPrefix = 'pre-push', log: logFn = log,
+  stdout = process.stdout, stderr = process.stderr }) {
   let hosts;
-  try {
-    hosts = _parseRemoteHosts(await readConfigFile(tree)).filter((host) => host['roles-allowed'].includes('test'));
-  } catch {
-    log('remote configuration unavailable — using local gate.');
-    return 10;
+  let hostSource = 'config';
+  const done = (code) => ({ code, passed: false, alias: null, report: null, hostSource });
+  const override = resolveGateHostOverride(env);
+  if (override?.error) {
+    logFn(override.error);
+    return done(2);
+  }
+  if (override) {
+    hosts = override.hosts.map((alias) => ({ alias }));
+    hostSource = 'override';
+    logFn(`gate host order from SO_GATE_HOSTS (host_source: override): ${override.hosts.join(', ')}.`);
+  } else {
+    try {
+      hosts = _parseRemoteHosts(await readConfigFile(tree)).filter((host) => host['roles-allowed'].includes('test'));
+    } catch {
+      logFn('remote configuration unavailable — using local gate (host_source: fallback).');
+      return done(10);
+    }
   }
   for (const { alias } of hosts) {
-    log(`checking remote readiness (${alias}).`);
+    logFn(`checking remote readiness (${alias}).`);
     const doctor = spawnSync('offload', ['doctor', '-H', alias, '--brief', '--no-probe'],
       { encoding: 'utf8', timeout: 30_000, maxBuffer: 1024 * 1024 });
     if (doctor.error?.code === 'ENOENT') break;
-    if (doctor.error || doctor.status !== 0) {
-      log(`remote ${alias} not ready (exit ${doctor.status ?? doctor.error?.code}) — trying next route.`);
+    if (!gateReady(doctor)) {
+      const token = gateReadyToken(doctor);
+      logFn(`remote ${alias} not ready (exit ${doctor.status ?? doctor.error?.code}${token ? `, gate-ready=${token}` : ''}) — trying next route.`);
       continue;
     }
     const nonce = randomUUID();
-    log(`running full quality gate remotely on ${alias} against pushed SHA ${sha}.`);
-    const run = spawnSync('offload', ['run', '-H', alias, tree, '--job', `pre-push-${nonce}`,
-      '--klasse', 'gate', '--link-modules', '--rm', '--timeout', '1800', '--', 'node', '-e', remoteCommand(sha, nonce)],
+    logFn(`running full quality gate remotely on ${alias} (host_source: ${hostSource}) against pushed SHA ${sha}.`);
+    // No --link-modules: offload snapshots a linked node_modules symlink into its commit (.gitignore's
+    // `node_modules/` matches directories only), and the `git checkout <sha>` in remoteCommand then
+    // deletes it, so vitest/eslint exit 127 and the gate reports them as "fail" (push blocked).
+    const run = spawnSync('offload', ['run', '-H', alias, tree, '--job', `${jobPrefix}-${nonce}`,
+      '--klasse', 'gate', '--rm', '--timeout', '1800', '--', 'node', '-e', remoteCommand(sha, nonce)],
     { encoding: 'utf8', timeout: 1_860_000, maxBuffer: 64 * 1024 * 1024 });
-    process.stdout.write(run.stdout ?? '');
-    process.stderr.write(run.stderr ?? '');
+    stdout.write(run.stdout ?? '');
+    stderr.write(run.stderr ?? '');
     const receipts = (run.stdout ?? '').split(/\r?\n/).filter((line) => line.startsWith('SO_PRE_PUSH_RESULT='));
     let receipt;
     try { if (receipts.length === 1) receipt = JSON.parse(receipts[0].slice('SO_PRE_PUSH_RESULT='.length)); } catch { /* unknown blocks */ }
     if (receipts.length === 0 && !run.error && [2, 4, 8, 10, 255].includes(run.status)) {
-      log(`remote ${alias} transport/readiness failure (exit ${run.status}) — trying next route.`);
+      logFn(`remote ${alias} transport/readiness failure (exit ${run.status}) — trying next route.`);
       continue;
     }
     const report = receipt?.report;
     const stubbedChecks = Object.keys(report?.stubbed ?? {});
-    if (stubbedChecks.length > 0) log(`remote gate contains stubbed checks: ${stubbedChecks.join(', ')} — Push blocked.`);
+    if (stubbedChecks.length > 0) logFn(`remote gate contains stubbed checks: ${stubbedChecks.join(', ')} — Push blocked.`);
     const passed = !run.error && run.status === 0 && receipt?.nonce === nonce && receipt.sha === sha &&
       receipt.exit_code === 0 && report?.variant === 'full-gate' && report.test?.status === 'pass' &&
-      stubbedChecks.length === 0 && !(report.test.failed > 0) && report.test.suite_died !== true &&
+      // `failed` stays the first, parallel run's count; it is acceptable only when
+      // the gate re-ran exactly those timeout-only failures clean (#1673).
+      stubbedChecks.length === 0 && !(report.test.failed > 0 && !cleanRerun(report.test)) &&
+      report.test.suite_died !== true &&
       ['pass', 'skip'].includes(report.typecheck?.status) && ['pass', 'skip'].includes(report.lint?.status) &&
       ![report.test, report.typecheck, report.lint].some((check) => check.timed_out === true);
-    try {
+    if (emit) try {
       const { emitEvent, sessionAttribution } = await import('./events.mjs');
       const counts = admitSuiteCounts(report?.test);
       const waveNumber = resolveWaveNumber(ledgerRoot);
       await emitEvent(`orchestrator.quality_gate.${passed ? 'passed' : 'failed'}`, {
-        variant: 'full-gate', exit_code: passed ? 0 : 1, remote_host: alias,
+        variant: 'full-gate', exit_code: passed ? 0 : 1, remote_host: alias, host: alias, host_source: hostSource,
         pushed_sha: sha, ...sessionAttribution(ledgerRoot),
         ...joinGateKillFields({ outer: {}, gateStdout: JSON.stringify(report) }),
         ...(counts ? { counts } : {}),
         ...(waveNumber !== null ? { wave_number: waveNumber } : {}),
         ...(report?.test?.failed_files?.length ? { failed_files: report.test.failed_files } : {}),
+        ...(Array.isArray(report?.test?.rerun?.files) && report.test.rerun.files.length
+          ? { rerun: { files: report.test.rerun.files, status: report.test.rerun.status } } : {}),
       }, { repoRoot: ledgerRoot });
     } catch { /* telemetry cannot change the blocking verdict */ }
-    log(`remote quality gate ${passed ? 'passed' : 'FAILED — Push blocked'} (${alias}).`);
-    return passed ? 0 : 1;
+    logFn(`remote quality gate ${passed ? 'passed' : 'FAILED — Push blocked'} (${alias}).`);
+    return { code: passed ? 0 : 1, passed, alias, report: report ?? null, hostSource };
   }
-  log('remote routes unavailable — using local full quality gate.');
-  return 10;
+  if (hostSource === 'override') {
+    // An explicit override names where the gate may run; silently falling back to the
+    // local host is the case the override exists to prevent (#1626).
+    logFn(`no SO_GATE_HOSTS route could run the gate (${hosts.map((h) => h.alias).join(', ')}) — Push blocked (no local fallback).`);
+    return done(2);
+  }
+  logFn('remote routes unavailable — local fallback (host: local, host_source: fallback; an origin MR branch takes the partial gate, #1642).');
+  return done(10);
+}
+
+async function main() {
+  const [tree, sha, ledgerRoot] = process.argv.slice(2);
+  const r = await runRemoteGate({ tree, sha, ledgerRoot });
+  return r.code;
 }
 
 if (isMainModule(import.meta.url)) process.exitCode = await main();