session-orchestrator 5.9.0 → 5.11.0

package/scripts/lib/memory-proposals/store.mjs

@@ -8,6 +8,9 @@
  *    `createStateLockExclusive` pattern (POSIX-atomic create-or-fail).
  *  - Proposals JSONL: `.orchestrator/metrics/proposals.jsonl` (O_APPEND)
  *  - Per-wave summary: `.orchestrator/metrics/proposals-summary-<wave-id>.json`
+ *  - Overflow JSONL: `.orchestrator/metrics/proposals-overflow.jsonl` — validated
+ *    proposals the quota rejected (#1027 1b). Never counted against the quota,
+ *    never read by the collector; written under the same lock as the queue.
  *  - Confidence floor check: BEFORE lock acquisition (no I/O, no lock held).
  *  - Quota check: INSIDE lock (count + decide + write serialized).
  *
@@ -16,6 +19,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { randomUUID } from 'node:crypto';
 import { serializeProposal } from './schema.mjs';
 import { validatePathInsideProject } from '../path-utils.mjs';
 import { tryAcquireFileLock, releaseFileLock } from '../file-lock.mjs';
@@ -26,6 +30,8 @@ import { writeJsonAtomicSync } from '../io.mjs';
 // ---------------------------------------------------------------------------
 
 const PROPOSALS_JSONL = '.orchestrator/metrics/proposals.jsonl';
+const PROPOSALS_OVERFLOW_JSONL = '.orchestrator/metrics/proposals-overflow.jsonl';
+const OVERFLOW_MAX_BYTES = 1024 * 1024;
 const PROPOSALS_LOCK = '.orchestrator/metrics/proposals-write.lock';
 const PROPOSALS_SUMMARY_PREFIX = '.orchestrator/metrics/proposals-summary-';
 
@@ -60,20 +66,86 @@ const LOCK_POLL_MS = 50;
  */
 function safePath(repoRoot, relPath) {
   const result = validatePathInsideProject(relPath, repoRoot, { canonicalizeRoot: true });
-  if (!result.ok) {
-    const resolved = path.resolve(repoRoot, relPath);
-    // #548 A5 — surface result.reason ('lexical' | 'symlink' | 'input') in the
-    // error so operators can distinguish path-traversal classes at a glance:
-    //  - 'lexical' → relPath escaped repoRoot via ../../ before symlink resolution
-    //  - 'symlink' → relPath resolved through a symlink that points outside repoRoot
-    //  - 'input'   → relPath was malformed (empty, non-string, null byte)
-    throw new TypeError(
-      `store.mjs: path traversal blocked: ${resolved} is outside ${repoRoot} (reason: ${result.reason})`
+  // #548 A5 — surface result.reason ('lexical' | 'symlink' | 'input') in the
+  // error so operators can distinguish path-traversal classes at a glance:
+  //  - 'lexical' → relPath escaped repoRoot via ../../ before symlink resolution
+  //  - 'symlink' → relPath resolved through a symlink that points outside repoRoot
+  //  - 'input'   → relPath was malformed (empty, non-string, null byte)
+  const blocked = (reason) =>
+    new TypeError(
+      `store.mjs: path traversal blocked: ${path.resolve(repoRoot, relPath)} is outside ${repoRoot} (reason: ${reason})`
     );
+  if (!result.ok) throw blocked(result.reason);
+  // The shared validator swallows ENOENT on the target and returns the lexical
+  // path unchecked, so a symlinked ancestor (or a dangling symlink AT the
+  // target) lets the first write land outside the repo (#1027 1b). Closed here,
+  // store-side, so the shared validator's other callers keep their behaviour.
+  if (result.realPath === undefined && !existingAncestorInsideRoot(repoRoot, result.lexicalPath)) {
+    throw blocked('symlink');
   }
   return result.realPath ?? result.lexicalPath;
 }
 
+/**
+ * True when the nearest EXISTING component of `lexicalPath` (the path itself
+ * or the closest ancestor) resolves inside the canonical `repoRoot`. A
+ * symlink there whose target is missing (dangling) counts as an escape — the
+ * write that follows would create the target wherever the link points.
+ *
+ * Only node:fs/node:path on purpose: store-safepath-reason.test.mjs mocks
+ * `@lib/path-utils.mjs` with a single export, so no second import from it.
+ *
+ * Check-then-write TOCTOU: a link swapped in between this check and the
+ * append is not caught (O_NOFOLLOW would narrow the final component only).
+ * Accepted under the local-trust model; revisit if the metrics dir ever
+ * becomes writable by another principal.
+ *
+ * @param {string} repoRoot
+ * @param {string} lexicalPath — absolute, already known to be lexically inside repoRoot
+ * @returns {boolean}
+ */
+function existingAncestorInsideRoot(repoRoot, lexicalPath) {
+  let root = repoRoot;
+  try {
+    root = fs.realpathSync(repoRoot);
+  } catch (err) {
+    if (err?.code !== 'ENOENT' && err?.code !== 'EACCES') throw err;
+  }
+  const fold = (p) => (process.platform === 'win32' ? p.toLowerCase() : p);
+  const inside = (p) => {
+    const rel = path.relative(fold(root), fold(p));
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+  };
+  for (let cur = lexicalPath; ; cur = path.dirname(cur)) {
+    // Climbed above the root: root itself is missing, so nothing under it can
+    // be a link — the later mkdir creates a plain tree.
+    if (!inside(cur)) return true;
+    try {
+      fs.lstatSync(cur);
+    } catch (err) {
+      if (err?.code !== 'ENOENT') throw err;
+      continue;
+    }
+    let real;
+    try {
+      real = fs.realpathSync(cur);
+    } catch {
+      // Dangling link or loop at the nearest existing component → escape.
+      // But the lock file is created and unlinked by concurrent writers all
+      // the time: if the component vanished between lstat and realpath it was
+      // never a link, so step up to its parent instead of rejecting.
+      try {
+        fs.lstatSync(cur);
+      } catch (err) {
+        if (err?.code === 'ENOENT') continue;
+        throw err;
+      }
+      return false;
+    }
+    return inside(real);
+  }
+}
+
 /**
  * Ensure the parent directory of `filePath` exists.
  * @param {string} filePath
@@ -100,6 +172,153 @@ function jsonlPathFor(repoRoot) {
   return safePath(repoRoot, PROPOSALS_JSONL);
 }
 
+/**
+ * Build the absolute path to the quota-overflow JSONL file.
+ * @param {string} repoRoot
+ * @returns {string}
+ */
+function overflowPathFor(repoRoot) {
+  return safePath(repoRoot, PROPOSALS_OVERFLOW_JSONL);
+}
+
+/** Flush a directory entry before depending on its persistence. */
+function syncOverflowDirectory(directory) {
+  const fd = fs.openSync(directory, 'r');
+  try {
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/** Create a file without replacing anything, retaining leftovers on failure. */
+function writeOverflowExclusive(file, bytes, mode) {
+  const fd = fs.openSync(file, 'wx', mode);
+  try {
+    // The umask may narrow the creation mode; restore exactly the old mode.
+    fs.fchmodSync(fd, mode);
+    fs.writeFileSync(fd, bytes);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/**
+ * Copy legacy files with bounded memory into an exclusive `.partial` file,
+ * then hard-link it to the archive name. An interrupted copy leaves only the
+ * `.partial` name behind, never a truncated file under the archive name; the
+ * link fails with EEXIST instead of overwriting an existing archive. Unsupported
+ * link operations discard only our completed staging copy, leaving active intact.
+ */
+function archiveOverflowExclusive(active, archive, partial, mode) {
+  const source = fs.openSync(active, 'r');
+  try {
+    const destination = fs.openSync(partial, 'wx', mode);
+    try {
+      // The umask may narrow the creation mode; restore exactly the old mode.
+      fs.fchmodSync(destination, mode);
+      const chunk = Buffer.alloc(64 * 1024);
+      let count;
+      while ((count = fs.readSync(source, chunk, 0, chunk.length, null)) > 0) {
+        fs.writeFileSync(destination, chunk.subarray(0, count));
+      }
+      fs.fsyncSync(destination);
+    } finally {
+      fs.closeSync(destination);
+    }
+  } finally {
+    fs.closeSync(source);
+  }
+  try {
+    fs.linkSync(partial, archive);
+  } catch (err) {
+    if (!['EPERM', 'ENOTSUP', 'EXDEV'].includes(err?.code)) throw err;
+    // We exclusively created this complete copy and have not replaced active.
+    // Do not accumulate another full copy on every unsupported-link retry.
+    // Copy/flush failures and collisions deliberately retain their evidence.
+    let cleanupError = '';
+    try {
+      fs.unlinkSync(partial);
+    } catch (cleanup) {
+      cleanupError = `; partial cleanup failed (${cleanup?.code ?? 'unknown'}): ${cleanup.message}`;
+    }
+    // appendProposal exposes message, so preserve the filesystem code there.
+    // This statement is specific to publication failure, never post-rename I/O.
+    throw new Error(
+      `overflow archive publication failed (${err.code}): ${err.message}; new proposal not stored${cleanupError}`,
+      { cause: err }
+    );
+  }
+  fs.unlinkSync(partial);
+}
+
+/**
+ * Preserve the old bytes durably before replacing the active overflow file.
+ * The proposals lock serializes writers of this append/rotation decision.
+ * Failures before rename leave the active file intact; after rename, the
+ * durable archive preserves the old bytes and the replacement has the new
+ * record. Incomplete archives/temps remain for inspection, never deleted.
+ * BV-004: archive aggregate size is unbounded (no retention authorization).
+ * Revisit growth when active file >= 1 MiB or first rotation: measure it.
+ */
+function appendOverflow(repoRoot, overflowPath, line) {
+  ensureDir(overflowPath);
+  let oldSize = 0;
+  let oldMode = 0o600;
+  let unterminated = false;
+  try {
+    const fd = fs.openSync(overflowPath, 'r');
+    try {
+      const oldStat = fs.fstatSync(fd);
+      oldSize = oldStat.size;
+      oldMode = oldStat.mode & 0o777;
+      if (oldSize > 0) {
+        const lastByte = Buffer.alloc(1);
+        if (fs.readSync(fd, lastByte, 0, 1, oldSize - 1) !== 1) {
+          throw new Error('overflow changed while checking its final byte');
+        }
+        unterminated = lastByte[0] !== 10;
+      }
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch (err) {
+    if (err?.code !== 'ENOENT') throw err;
+  }
+  const lineBytes = Buffer.from(line, 'utf8');
+  // Optional schema fields have no aggregate size limit. A single oversized
+  // record is preserved whole even though the active file exceeds the cap;
+  // the next record rotates it. Empty/absent files need no recovery archive.
+  if (oldSize === 0 || (!unterminated && oldSize + lineBytes.length <= OVERFLOW_MAX_BYTES)) {
+    fs.appendFileSync(overflowPath, lineBytes);
+    return;
+  }
+  const root = fs.realpathSync(repoRoot);
+  const directory = path.dirname(overflowPath);
+  const token = randomUUID();
+  const archive = safePath(root, path.relative(root, `${overflowPath}.archive-${token}.jsonl`));
+  const partial = safePath(root, path.relative(root, `${overflowPath}.archive-${token}.partial`));
+  const temporary = safePath(root, path.relative(root, `${overflowPath}.tmp-${token}`));
+  // Existing arbitrarily large files copy in bounded chunks.
+  // Preserve access restrictions; rotation must not widen a private inode's
+  // mode through the process umask's default creation permissions.
+  archiveOverflowExclusive(overflowPath, archive, partial, oldMode);
+  // Persist the archive's name (and the partial's removal) plus any newly
+  // created ancestors BEFORE replacing the sole active copy. All these
+  // directories are inside root.
+  for (let current = directory; ; current = path.dirname(current)) {
+    syncOverflowDirectory(current);
+    if (current === root) break;
+    if (current === path.dirname(current)) {
+      throw new Error('overflow directory is not inside the repository root');
+    }
+  }
+  writeOverflowExclusive(temporary, lineBytes, oldMode);
+  fs.renameSync(temporary, overflowPath);
+  syncOverflowDirectory(directory);
+}
+
 /**
  * Build the absolute path to the per-wave summary JSON file.
  * wave_id values are restricted to alphanumerics + hyphens/underscores to
@@ -372,6 +591,23 @@ export async function appendProposal({
     // Step 3b: Quota check.
     // ------------------------------------------------------------------
     if (currentCount >= quotaPerWave) {
+      // Keep the validated proposal (#1027 1b): the quota caps what enters the
+      // queue, not what an agent found. A failed write is fs-error — never a
+      // quota-exceeded that implies the content was preserved. Rotation keeps
+      // every old byte in an exclusive archive before replacing the active file.
+      let overflowPath;
+      try {
+        overflowPath = overflowPathFor(repoRoot);
+      } catch (err) {
+        incrementSummary(summaryPath, 'fs_error'); // traversal still throws, like every store path
+        throw err;
+      }
+      try {
+        appendOverflow(repoRoot, overflowPath, serializeProposal(record) + '\n');
+      } catch (err) {
+        incrementSummary(summaryPath, 'fs_error');
+        return { status: 'fs-error', error: err.message };
+      }
       const summary = readSummary(summaryPath);
       const droppedSoFar = summary.dropped;
       incrementSummary(summaryPath, 'dropped');

package/scripts/lib/named-vault-resolver.mjs

@@ -209,7 +209,7 @@ export function canonicalSuffixesFromVaults(vaults, envOverride) {
  *
  * First-match-wins; caller is responsible for WARN on ambiguity if needed.
  *
- * @param {string} repoSlug — e.g. 'bernhard-group/foo'
+ * @param {string} repoSlug — e.g. 'example-org/foo'
  * @param {Array<{name:string, suffix:string, root:string, match:{'org-prefix'?:string}}>} vaults
  * @returns {{name:string, suffix:string, root:string, match:object}|null}
  */

package/scripts/lib/owner-yaml.mjs

@@ -41,6 +41,9 @@
  *     mode: 'off' | 'warn' | 'strict'  (applied only when weaker than the committed mode;
  *                            precedence env SO_VAULT_INTEGRATION > this > committed.
  *                            An invalid value drops ONLY this section, see loadOwnerConfig)
+ *   drift-check:            (optional; host-local path exceptions — #937)
+ *     foreign-host-prefixes: string[] (narrow absolute directory prefixes;
+ *                            missing matching paths warn, unmatched paths error)
  *   vault-dirs:             (optional list; per-directory vault-dir — agents/vault#319)
  *     - path: string                       (the vault directory)
  *       match: { path-prefix: string }     (required; cwd directory prefix, first match wins)
@@ -54,7 +57,7 @@
  *   validateOwnerSections(obj) — pure validation, no I/O; bucketed per section (#820)
  *   validateOwnerConfig(obj)   — pure validation, no I/O; thin wrapper over validateOwnerSections
  *   loadOwnerConfig({path?})   — reads file; per-section tolerance for OPTIONAL
- *                                sections (paths/dispatcher/vault-integration/vaults/
+ *                                sections (paths/dispatcher/vault-integration/drift-check/vaults/
  *                                baselines/vault-dirs) — #820
  *   writeOwnerConfig(config, {path?}) — validates, writes YAML, creates dir
  *   getDefaults()              — returns sensible default config object
@@ -218,7 +221,7 @@ const REQUIRED_SECTIONS = /** @type {const} */ (['owner', 'tone', 'efficiency',
  * override", so a dropped section simply leaves the committed gate in force.
  */
 export const OPTIONAL_OBJECT_SECTIONS = /** @type {const} */ (
-  Object.freeze(['paths', 'dispatcher', 'vault-integration'])
+  Object.freeze(['paths', 'dispatcher', 'vault-integration', 'drift-check'])
 );
 
 /**
@@ -397,6 +400,33 @@ export function validateOwnerSections(obj) {
     sections['hardware-sharing'] = { valid: errors.length === 0, errors };
   }
 
+  // Host-local exception list only; invalid entries drop the entire section.
+  {
+    const errors = [];
+    const drift = obj['drift-check'];
+    if (drift !== undefined && drift !== null) {
+      if (!isPlainObject(drift)) {
+        errors.push('drift-check must be an object when present');
+      } else if (drift['foreign-host-prefixes'] !== undefined) {
+        const prefixes = drift['foreign-host-prefixes'];
+        if (!Array.isArray(prefixes)) {
+          errors.push('drift-check.foreign-host-prefixes must be an array');
+        } else {
+          for (const prefix of prefixes) {
+            const parts = typeof prefix === 'string' ? prefix.split('/').filter(Boolean) : [];
+            if (typeof prefix !== 'string' || !prefix.startsWith('/') ||
+                !/^\/[A-Za-z0-9._/-]+$/.test(prefix) || prefix.includes('//') ||
+                parts.some((part) => part === '.' || part === '..') ||
+                parts.length < 3 || (['Users', 'home'].includes(parts[0]) && parts.length < 4)) {
+              errors.push('drift-check.foreign-host-prefixes entries must be narrow absolute directory prefixes (no roots, home directories, traversal or globs)');
+            }
+          }
+        }
+      }
+    }
+    sections['drift-check'] = { valid: errors.length === 0, errors };
+  }
+
   // ── paths (optional; host-local path overrides — #653) ───────────────────────
   {
     const errors = [];
@@ -627,7 +657,7 @@ export function validateOwnerConfig(obj) {
  * Per-section tolerance (#820): an invalid REQUIRED section (owner, tone,
  * efficiency, hardware-sharing) still discards the whole file (legacy
  * behaviour, unchanged). An invalid OPTIONAL object section (paths,
- * dispatcher, vault-integration) is instead replaced by its default value — the rest of the
+ * dispatcher, vault-integration, drift-check) is instead replaced by its default value — the rest of the
  * file survives, `source` becomes `'partial'`, and the drop is reported via
  * `droppedSections` + a stderr WARN. OPTIONAL list sections (vaults,
  * baselines, vault-dirs) are passed through UNTOUCHED even when strict-invalid — their

package/scripts/lib/platform.mjs

@@ -13,7 +13,7 @@
  * NOTHING in this module touches the filesystem at import time.
  */
 
-import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, statSync, lstatSync, opendirSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { resolvePluginRoot as _resolvePluginRootRobust } from './plugin-root.mjs';
@@ -458,6 +458,75 @@ export function resolveSessionRoot(cwd, toplevel = '') {
   return launch !== '' && _isStrictlyInside(launch, root) ? launch : root;
 }
 
+/** Read small Git metadata after rejecting nonregular or symlink entries. */
+function readWorktreeMetadata(file) {
+  const info = lstatSync(file);
+  if (!info.isFile() || info.size > 8192) throw new TypeError('Invalid worktree metadata');
+  return readFileSync(file, 'utf8').trim();
+}
+
+function worktreeBinding(root) {
+  const text = readWorktreeMetadata(path.join(root, '.git'));
+  const match = /^gitdir: (.+)$/.exec(text);
+  if (!match) throw new TypeError('Invalid worktree pointer');
+  const gitDir = _canonical(path.resolve(root, match[1]));
+  const commonDir = _canonical(path.resolve(gitDir, readWorktreeMetadata(path.join(gitDir, 'commondir'))));
+  if (path.dirname(gitDir) !== path.join(commonDir, 'worktrees')) throw new TypeError('Invalid worktree admin directory');
+  const backPointer = _canonical(readWorktreeMetadata(path.join(gitDir, 'gitdir')));
+  if (backPointer !== _canonical(path.join(root, '.git'))) throw new TypeError('Worktree pointer mismatch');
+  return { gitDir, commonDir };
+}
+
+/**
+ * Verified Claude harness agent checkout, or null for every ordinary checkout.
+ * Keeps resolveSessionRoot's lifecycle contract unchanged (#1504 items 1–2).
+ * @param {string} cwd
+ * @returns {{writeRoot: string, commonDir: string}|null}
+ */
+export function isolatedAgentCheckout(cwd) {
+  const root = typeof cwd === 'string' ? dotGitAncestor(cwd) : '';
+  if (!root || _liftHarnessAgentWorktree(root) === root) return null;
+  try {
+    const binding = worktreeBinding(root);
+    const launchRoot = _liftHarnessAgentWorktree(root);
+    const dotGit = path.join(launchRoot, '.git');
+    const launchCommon = lstatSync(dotGit).isDirectory()
+      ? _canonical(dotGit) : worktreeBinding(launchRoot).commonDir;
+    if (binding.commonDir !== launchCommon) return null;
+    return { writeRoot: _canonical(root), commonDir: binding.commonDir };
+  } catch { return null; }
+}
+
+/**
+ * Enumerate reciprocal worktree roots in one Git admin directory, without a
+ * recursive scan. Ceiling: 256 entries / 8 KiB metadata; revisit if a real repo
+ * exceeds this. An incomplete enumeration is an error, never a clean absence.
+ * @param {string} commonDir
+ * @returns {{roots: string[], error: string|null}}
+ */
+export function registeredWorktreeRoots(commonDir) {
+  const roots = new Set();
+  let dir;
+  try {
+    dir = opendirSync(path.join(commonDir, 'worktrees'));
+    let count = 0;
+    for (let entry; (entry = dir.readSync()) !== null;) {
+      if (++count > 256) return { roots: [], error: 'worktree-limit' };
+      if (!entry.isDirectory()) continue;
+      const admin = path.join(commonDir, 'worktrees', entry.name);
+      try {
+        const pointer = readWorktreeMetadata(path.join(admin, 'gitdir'));
+        if (!path.isAbsolute(pointer) || path.basename(pointer) !== '.git') continue;
+        const root = _canonical(path.dirname(pointer));
+        const binding = worktreeBinding(root);
+        if (binding.commonDir === commonDir && binding.gitDir === _canonical(admin)) roots.add(root);
+      } catch { /* stale or invalid registration cannot lend authority */ }
+    }
+    return { roots: [...roots], error: null };
+  } catch { return { roots: [], error: 'worktree-discovery-unreadable' }; }
+  finally { if (dir) dir.closeSync(); }
+}
+
 // ---------------------------------------------------------------------------
 // resolveEventsLedgerRoot (#1514 point 1)
 // ---------------------------------------------------------------------------

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

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+// Optional pre-push router: 0 verified, 1 blocked, 10 transport/readiness fallback.
+import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { readConfigFile } from './config/io.mjs';
+import { _parseRemoteHosts } from './config/remote-hosts.mjs';
+import { isMainModule } from './is-main-module.mjs';
+import { admitSuiteCounts, joinGateKillFields } from './gates/gate-helpers.mjs';
+import { resolveWaveNumber } from './quality-gate-wave.mjs';
+
+const log = (message) => process.stderr.write(`pre-push: ${message}\n`);
+
+// offload sync creates a snapshot commit even for a clean source. Check out the
+// pushed SHA again and reject extra source files before invoking the real gate.
+// A nonce-bound receipt separates command failures from offload's overlapping
+// transport exit codes. No receipt is ever interpreted as a passing gate.
+function remoteCommand(sha, nonce) {
+  return `
+    const { spawnSync } = require('node:child_process');
+    const { writeSync } = require('node:fs');
+    const sha = ${JSON.stringify(sha)}, nonce = ${JSON.stringify(nonce)};
+      const env = { ...process.env };
+      for (const key of Object.keys(env)) {
+        if (/(PROJECT_DIR|PLUGIN_ROOT|RULES_DIR)$/.test(key) ||
+            /^GIT_/.test(key) && !/^GIT_(AUTHOR_|COMMITTER_|EDITOR$|ASKPASS$|SSH$|SSH_COMMAND$|TERMINAL_PROMPT$|EXEC_PATH$)/.test(key)) delete env[key];
+      }
+    const git = (...args) => spawnSync('git', args, { env, encoding: 'utf8' });
+    let result = { nonce, sha, exit_code: 1, report: null };
+    const checkout = git('checkout', '--quiet', '--detach', sha);
+    const head = git('rev-parse', 'HEAD');
+    const tracked = git('status', '--porcelain', '--untracked-files=no');
+    const extras = git('ls-files', '--others', '--exclude-standard', '--exclude=node_modules');
+    if (checkout.status === 0 && head.status === 0 && head.stdout.trim() === sha &&
+        tracked.status === 0 && !tracked.stdout.trim() && extras.status === 0 && !extras.stdout.trim()) {
+      const gate = spawnSync('npm', ['run', '--silent', 'quality-gate'],
+        { env, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+      if (gate.stdout) writeSync(1, gate.stdout);
+      if (gate.stderr) writeSync(2, gate.stderr);
+      result.exit_code = gate.status;
+      try { result.report = JSON.parse(gate.stdout); } catch {}
+    }
+    writeSync(1, '\\nSO_PRE_PUSH_RESULT=' + JSON.stringify(result) + '\\n');
+    process.exit(result.exit_code === 0 ? 0 : 1);
+  `;
+}
+
+async function main() {
+  const [tree, sha, ledgerRoot] = process.argv.slice(2);
+  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;
+  }
+  for (const { alias } of hosts) {
+    log(`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.`);
+      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)],
+    { encoding: 'utf8', timeout: 1_860_000, maxBuffer: 64 * 1024 * 1024 });
+    process.stdout.write(run.stdout ?? '');
+    process.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.`);
+      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.`);
+    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 &&
+      ['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 {
+      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,
+        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 } : {}),
+      }, { repoRoot: ledgerRoot });
+    } catch { /* telemetry cannot change the blocking verdict */ }
+    log(`remote quality gate ${passed ? 'passed' : 'FAILED — Push blocked'} (${alias}).`);
+    return passed ? 0 : 1;
+  }
+  log('remote routes unavailable — using local full quality gate.');
+  return 10;
+}
+
+if (isMainModule(import.meta.url)) process.exitCode = await main();

package/scripts/lib/project-hygiene.mjs

@@ -555,6 +555,10 @@ const AUDIT_VALUE_FLAGS = new Set([
 const AUDIT_BOOLEAN_FLAGS = new Set([
   '-r', '--recursive', '-s', '--silent', '-g', '--global', '--workspaces', '--offline',
 ]);
+// Python tool runners (#1538): subcommand words after the verb, and the runner
+// options that consume the next token.
+const RUNNER_SUBCOMMANDS = { uvx: [], pipx: ['run'], uv: ['tool', 'run'] };
+const RUNNER_VALUE_FLAGS = new Set(['--from', '--spec', '--python', '-p', '--with']);
 
 /** Inspect executable job/step locations, never arbitrary keys named run/script. */
 function hasAuditStep({ text, platform }) {
@@ -683,6 +687,39 @@ function hasAuditSegment(segment, depth = 0) {
     const trailingArgs = index < 0 ? [] : segment.slice(index);
     return hasAuditSegment([...tokens, ...trailingArgs], depth + 1);
   }
+  if (verb === 'uvx' || verb === 'pipx' || verb === 'uv') {
+    let i = index + 1;
+    // `uvx` is an alias of `uv tool run`; `pipx` executes only through `run`.
+    for (const word of RUNNER_SUBCOMMANDS[verb]) {
+      if (segment[i]?.text !== word) return false;
+      i++;
+    }
+    // Runner options before the tool. Unknown flags count as value-less, so an
+    // unlisted value-taking flag makes its value the "tool" and the line is
+    // missed — a false finding, never a false pass. Revisit if a real CI line
+    // with such a flag is reported as missing its audit.
+    // `--from`/`--spec` name the package that provides the tool; another
+    // package exposing a `pip-audit` entry point is not the audit.
+    let sourcePackage = null;
+    while (segment[i]) {
+      const { text, redirect } = segment[i];
+      // A redirect operand is data, even when it names the audit package.
+      if (redirect) return false;
+      if (text === '--') { i++; break; }
+      if (!text.startsWith('-')) break;
+      if (RUNNER_VALUE_FLAGS.has(text)) {
+        if (!segment[i + 1] || segment[i + 1].redirect) return false;
+        if (text === '--from' || text === '--spec') sourcePackage = segment[i + 1].text;
+        i += 2;
+      } else {
+        i++;
+      }
+    }
+    if (!segment[i] || segment[i].redirect) return false;
+    if (segment.slice(index + 1).some((token) => ['-h', '--help', '--version'].includes(token.text))) return false;
+    if (sourcePackage !== null && !/^pip-audit(?:\s*(?:[=<>~!]=?|@)\s*[\w.+*-]+)?$/.test(sourcePackage)) return false;
+    return /^pip-audit(?:@[\w.+-]+)?$/.test(segment[i].text);
+  }
   if (verb === 'corepack' || verb === 'npx') {
     index++;
     while (['-y', '--yes', '--no-install', '--'].includes(segment[index]?.text)) index++;

package/scripts/lib/quality-gate.mjs

@@ -851,7 +851,12 @@ export function gateKillFields(run) {
  * Count fallback is limited to pre-#954 sessions, gates outside the event
  * wrapper, or missing wave attribution; step 7 falls back to this wave's own
  * gate output (its header is not written yet), session end to the header. Auto-fix with a known wave
- * uses the event; missing counts alone do not permit header fallback.
+ * uses the event; missing counts alone do not permit count fallback.
+ * Diagnose own-session events without the counts filter to distinguish absent
+ * events, missing wave attribution, and fail-fast events without counts; never
+ * adopt counts from another session/wave or an unattributed row. A truncated
+ * append can be skipped by fromjson?, leaving an older matching run: that alone
+ * does not establish the current gate result.
  *
  * `suite_platform` comes from this wave's gate run (step 7) or the STATE.md
  * Wave History header `— suite <passed>/<failed> on <platform>` (session end);