simt-dev 0.6.3 → 0.7.1

package/src/hooks/dispatcher.mjs

@@ -18,32 +18,353 @@
 //   Report what did not run. The summary names every gate, its disposition and
 //   its reason, so "passed" can never be mistaken for "only some of it passed".
 
-import { execFile } from 'node:child_process';
-import { readFile, stat } from 'node:fs/promises';
-import { basename, join, resolve, sep } from 'node:path';
+import { execFile, spawn } from 'node:child_process';
+import { mkdtemp, readFile, rm, stat, symlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, join, matchesGlob, resolve, sep } from 'node:path';
 import { promisify } from 'node:util';
 
 import { GATES } from './gates.mjs';
 import { resolveGate } from './resolve.mjs';
+import { resolveNodeRunner } from '../ecosystem/node-runner.mjs';
 import { CLI } from '../name.mjs';
 import { MANIFEST_FILE } from '../name.mjs';
 import { assertVersionPin } from '../package-version.mjs';
-import { recordRun } from '../ledger/index.mjs';
+import { hasTestEvidence, readLedger, recordRun } from '../ledger/index.mjs';
 import { renderFindings, scanStaged } from '../secrets.mjs';
 
 const exec = promisify(execFile);
 
+/**
+ * The default bound on one gate, in seconds, and the grace a killed gate gets before
+ * SIGKILL. A hook that runs on every commit needs a ceiling: a test runner waiting on
+ * a socket that never closes blocks the commit with no output and no way to tell a
+ * hang from slow work. `gates.timeout` raises or removes it per repository.
+ */
+const DEFAULT_GATE_TIMEOUT_SECONDS = 600;
+const KILL_GRACE_MS = 5000;
+
+/**
+ * How much of a gate's output a report can carry. This is a bound on what is KEPT, not
+ * on what the process may write: a gate whose output exceeded execFile's buffer used to
+ * be reported `failed` although it exited 0.
+ */
+const GATE_OUTPUT_TAIL_BYTES = 64 * 1024;
+
+function tailCollector() {
+  let kept = Buffer.alloc(0);
+  let dropped = 0;
+  return {
+    push(chunk) {
+      kept = Buffer.concat([kept, chunk]);
+      if (kept.length > GATE_OUTPUT_TAIL_BYTES) {
+        dropped += kept.length - GATE_OUTPUT_TAIL_BYTES;
+        kept = kept.subarray(kept.length - GATE_OUTPUT_TAIL_BYTES);
+      }
+    },
+    text: () => kept.toString('utf8'),
+    dropped: () => dropped,
+  };
+}
+
+/**
+ * Signal the gate's whole process group. A test runner spawns workers of its own, and
+ * signalling only the leader leaves them holding the pipes this function is waiting on.
+ * `detached` in the spawn below is what makes the group exist.
+ */
+function signalTree(child, signal) {
+  try {
+    process.kill(-child.pid, signal);
+  } catch {
+    try {
+      child.kill(signal);
+    } catch {
+      // Already gone: a second signal has nothing to reach.
+    }
+  }
+}
+
+/**
+ * Run one gate to completion, keeping its exit code and the tail of what it printed.
+ *
+ * `timeoutMs` of 0 means no bound, which is what `gates.timeout: 0` asks for and what
+ * the manifest does not have to say. Output is collected in full while the process
+ * runs and only the tail is retained, so a noisy passing gate passes.
+ */
+async function runBounded(argv, { cwd, env, timeoutMs }) {
+  return await new Promise((settle) => {
+    let child;
+    try {
+      child = spawn(argv[0], argv.slice(1), { cwd, env, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (error) {
+      settle({ code: 1, stdout: '', stderr: String(error.message ?? error), timedOut: false, dropped: 0 });
+      return;
+    }
+    const out = tailCollector();
+    const err = tailCollector();
+    let timedOut = false;
+    let timer = null;
+    let killer = null;
+    let done = false;
+    const finish = (code) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      clearTimeout(killer);
+      settle({ code, stdout: out.text(), stderr: err.text(), timedOut, dropped: out.dropped() + err.dropped() });
+    };
+    child.stdout?.on('data', (chunk) => out.push(chunk));
+    child.stderr?.on('data', (chunk) => err.push(chunk));
+    // A missing binary emits `error` and no `close`; the message is the only evidence.
+    child.on('error', (error) => {
+      err.push(Buffer.from(String(error.message ?? error)));
+      finish(1);
+    });
+    child.on('close', (code, signal) => finish(typeof code === 'number' ? code : signal === null ? 0 : 1));
+    if (timeoutMs > 0) {
+      timer = setTimeout(() => {
+        timedOut = true;
+        signalTree(child, 'SIGTERM');
+        killer = setTimeout(() => signalTree(child, 'SIGKILL'), KILL_GRACE_MS);
+      }, timeoutMs);
+    }
+  });
+}
+
+/**
+ * The bound for one gate, in milliseconds. A number applies to every gate; a map applies
+ * per name, the shape `gates.cwd` already has. A value that is neither a positive whole
+ * number of seconds nor 0 falls back to the default rather than removing the bound: an
+ * unreadable declaration must not be the quiet way to disable the ceiling.
+ */
+function gateTimeoutMs(declared, name) {
+  const value = declared !== null && typeof declared === 'object' ? declared[name] : declared;
+  if (value === 0) return 0;
+  if (Number.isInteger(value) && value > 0) return value * 1000;
+  return DEFAULT_GATE_TIMEOUT_SECONDS * 1000;
+}
+
 /** Gates that are known but not required for the event to pass. */
 const DEFAULT_EVENTS = { 'pre-commit': 'preCommit', 'pre-push': 'prePush' };
 
+/** The sha git writes for a ref that does not exist on the remote yet. */
+const ZERO_SHA = '0'.repeat(40);
+
+/**
+ * The lines git feeds a pre-push hook on stdin, one per ref being pushed:
+ * `<local ref> <local sha> <remote ref> <remote sha>`.
+ *
+ * Returns `{ refs, error }`. A line this parser cannot read is an ERROR, not a
+ * dropped line: a push that cannot be read is a push that cannot be classified,
+ * and the classifier's contract is to fail closed to the full suite.
+ *
+ * @param {string} text the raw stdin
+ * @returns {{refs: {ref: string, localSha: string, remoteSha: string}[] | null, error: string | null}}
+ */
+export function parsePushedRefs(text) {
+  const refs = [];
+  for (const line of String(text ?? '').split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed === '') continue;
+    const parts = trimmed.split(' ');
+    if (parts.length !== 4) return { refs: null, error: `unrecognized pre-push line: ${trimmed}` };
+    const [ref, localSha, , remoteSha] = parts;
+    if (!/^[0-9a-f]{40}$/.test(localSha) || !/^[0-9a-f]{40}$/.test(remoteSha)) {
+      return { refs: null, error: `unrecognized sha in pre-push line: ${trimmed}` };
+    }
+    refs.push({ ref, localSha, remoteSha });
+  }
+  return { refs, error: null };
+}
+
+/**
+ * Confirm a tag's commit is already accounted for, so the tag may ride along in a
+ * docs-only push (ADR-113). A tag carries no commits of its own in the release flow:
+ * it points at commits delivered (and tested) by a branch push. It is acceptable only
+ * when the commit it names is reachable from a remote-tracking ref (already pushed) or
+ * from a branch tip this same push is delivering. Any uncertainty - the tag does not
+ * resolve to a commit, the remote refs cannot be listed, no candidate is known, or the
+ * commit is unreachable from all of them - fails closed to the full suite.
+ *
+ * @param {string} root the repository to ask git
+ * @param {string} tagSha the tag's local sha from the pre-push line
+ * @param {string[]} pushingTips branch tips this same push is delivering
+ * @returns {Promise<{ok: boolean, reason: string | null}>}
+ */
+async function tagCommitAccountedFor(root, tagSha, pushingTips) {
+  let commit;
+  try {
+    ({ stdout: commit } = await exec('git', ['rev-parse', `${tagSha}^{commit}`], { cwd: root }));
+  } catch (error) {
+    return { ok: false, reason: `the tag could not be resolved to a commit: ${String(error.stderr ?? error.message).trim()}` };
+  }
+  commit = commit.trim();
+
+  let remoteRefs;
+  try {
+    ({ stdout: remoteRefs } = await exec('git', ['for-each-ref', 'refs/remotes/', '--format=%(refname)'], { cwd: root }));
+  } catch (error) {
+    return { ok: false, reason: `the remote refs could not be listed: ${String(error.stderr ?? error.message).trim()}` };
+  }
+  const candidates = [
+    ...remoteRefs.split('\n').map((s) => s.trim()).filter((s) => s !== ''),
+    ...pushingTips,
+  ];
+  if (candidates.length === 0) {
+    return { ok: false, reason: 'no remote refs are known and no branch is being pushed, so the tag’s commit cannot be confirmed as already delivered' };
+  }
+  for (const candidate of candidates) {
+    try {
+      await exec('git', ['merge-base', '--is-ancestor', commit, candidate], { cwd: root });
+      return { ok: true, reason: null };
+    } catch {
+      // not reachable from this ref; try the next candidate
+    }
+  }
+  return { ok: false, reason: `the tag’s commit (${commit.slice(0, 7)}) is not reachable from any pushed ref; it may not have been tested` };
+}
+
+/**
+ * Decide whether a push carries only documentation, so the `test` gate may be
+ * skipped for it (ADR-113). Every uncertainty fails closed to `{ docsOnly: false }`
+ * with the reason the full suite runs: an empty ref list, a new branch (no remote
+ * sha to diff against), a tag whose commit is not confirmed already delivered, a
+ * commit count above the ceiling, a file outside the declared paths, or a git error.
+ *
+ * Branch refs are judged on a TREE diff (`remote..local`), so a force push that
+ * drops commits is judged on the trees it replaces, not on the commit count alone.
+ * Tag refs carry no commits of their own; each is accepted only when its commit is
+ * already accounted for (see `tagCommitAccountedFor`). Deletions push nothing.
+ *
+ * @param {string} root the repository to ask git
+ * @param {{ref: string, localSha: string, remoteSha: string}[]} refs
+ * @param {{maxCommits: number, paths: string[]}} config the manifest's `gates.prePushSkipTest`
+ * @returns {Promise<{docsOnly: boolean, reason: string}>}
+ */
+export async function classifyPush(root, refs, { maxCommits, paths }) {
+  if (refs.length === 0) {
+    return { docsOnly: false, reason: 'the push carries no readable ref list; running the full suite' };
+  }
+  const deletions = refs.filter((r) => r.localSha === ZERO_SHA).length;
+  const branches = refs.filter((r) => r.localSha !== ZERO_SHA && !r.ref.startsWith('refs/tags/'));
+  const tags = refs.filter((r) => r.localSha !== ZERO_SHA && r.ref.startsWith('refs/tags/'));
+
+  let commits = 0;
+  const files = new Set();
+  for (const { ref, localSha, remoteSha } of branches) {
+    if (remoteSha === ZERO_SHA) {
+      return { docsOnly: false, reason: `a new branch is being pushed (${ref}); its history cannot be diffed against the remote` };
+    }
+    let count, names;
+    try {
+      ({ stdout: count } = await exec('git', ['rev-list', '--count', `${remoteSha}..${localSha}`], { cwd: root }));
+      ({ stdout: names } = await exec('git', ['diff', '--name-only', '-z', `${remoteSha}..${localSha}`], { cwd: root }));
+    } catch (error) {
+      return { docsOnly: false, reason: `the push could not be diffed: ${String(error.stderr ?? error.message).trim()}` };
+    }
+    commits += Number(count.trim());
+    // `-z` and no trimming: a path is NUL-terminated because a path can contain a
+    // newline, and git quotes such a name in the line-terminated form, so splitting on
+    // newlines compares a quoted path against an unquoted glob and never matches.
+    for (const name of names.split('\0')) {
+      if (name !== '') files.add(name);
+    }
+  }
+
+  const pushingTips = branches.map((b) => b.localSha);
+  for (const { localSha } of tags) {
+    const verdict = await tagCommitAccountedFor(root, localSha, pushingTips);
+    if (!verdict.ok) return { docsOnly: false, reason: verdict.reason };
+  }
+
+  if (commits > maxCommits) {
+    return { docsOnly: false, reason: `${commits} commits exceed the ${maxCommits}-commit ceiling for a docs-only push` };
+  }
+  const outside = [...files].filter((f) => !paths.some((p) => matchesGlob(f, p)));
+  if (outside.length > 0) {
+    return { docsOnly: false, reason: `${outside.length} file(s) are outside the docs-only paths: ${outside.slice(0, 5).join(', ')}` };
+  }
+
+  const parts = [];
+  if (commits > 0) parts.push(`${commits} commit(s) touching ${files.size} file(s), all inside the docs-only paths`);
+  if (tags.length > 0) parts.push(`${tags.length} tag(s) already delivered`);
+  if (deletions > 0) parts.push(`${deletions} ref deletion(s)`);
+  if (parts.length === 0) return { docsOnly: true, reason: 'no commits carried' };
+  // The report prints this as-is (ADR-113). The label names what is being pushed:
+  // a push that carries only tags is a tag push, not a docs-only push.
+  const kind = commits > 0 ? 'docs-only push' : tags.length > 0 ? 'tag push' : 'deletion push';
+  return { docsOnly: true, reason: `${kind}: ${parts.join('; ')}` };
+}
+
+/**
+ * The pre-push skip decision, from the manifest and the ref list git fed on stdin.
+ *
+ * The skip is OPT-IN: a repository without `gates.prePushSkipTest` runs the full
+ * suite on every push, because a control a repo did not declare is one it did not
+ * review. A misdeclaration (missing fields) also runs the suite - a skip the
+ * manifest cannot state precisely is a skip a reviewer cannot see.
+ *
+ * @returns {Promise<{reason: string, adr: string} | null>} null runs the suite; a reason skips the `test` gate
+ */
+async function resolveDocsOnlySkip(root, manifest, pushed) {
+  if (pushed === undefined) return null;
+  const config = manifest?.gates?.prePushSkipTest;
+  if (typeof config?.maxCommits !== 'number' || !Array.isArray(config?.paths)) return null;
+  const { refs, error } = parsePushedRefs(pushed);
+  if (error !== null) {
+    return null; // the caller cannot be sure what is being pushed; the suite runs
+  }
+  const verdict = await classifyPush(root, refs, { maxCommits: config.maxCommits, paths: config.paths });
+  return verdict.docsOnly ? { reason: verdict.reason, adr: 'ADR-113' } : null;
+}
+
+/**
+ * The pre-push skip for a suite the author already ran on this exact tree (ADR-120).
+ *
+ * The dispatcher records every gate run against the tree it ran on (ADR-087). If a passing
+ * `test` run is recorded for the committed tree about to be pushed, and nothing has changed
+ * since, re-running the full suite at push time buys nothing: it is the same tree, already
+ * proven. This reads that evidence and earns the same reported skip the docs-only path does.
+ *
+ * It matches the COMMITTED tree (`HEAD^{tree}`), not the working tree: the pre-push gate runs
+ * at HEAD, so the evidence that matters is a pass on exactly that tree. A file edited after
+ * the green pass changes the tree id, so the match fails and the suite runs - the "no changes
+ * since" condition is enforced by the digest, not by trusting the author. Every uncertainty -
+ * an unborn HEAD, an unreadable ledger, no entry for this tree, a later failure - fails closed
+ * to the suite.
+ *
+ * @param {string} root the real repository root
+ * @returns {Promise<{reason: string} | null>} null runs the suite; a reason skips the `test` gate
+ */
+async function resolveAlreadyPassedSkip(root) {
+  let headTree;
+  try {
+    ({ stdout: headTree } = await exec('git', ['rev-parse', 'HEAD^{tree}'], { cwd: root }));
+  } catch {
+    return null;
+  }
+  headTree = headTree.trim();
+  if (!/^[0-9a-f]{40}$/.test(headTree)) return null;
+  const { entries, errors } = await readLedger(root);
+  if (errors.length > 0) return null;
+  if (!hasTestEvidence(entries, headTree)) return null;
+  return {
+    reason:
+      'already passing on current state: the test gate ran green on this tree and nothing has changed since',
+    adr: 'ADR-120',
+  };
+}
+
 /**
  * @param {string} event 'pre-commit' | 'pre-push'
  * @param {object} ctx
  * @param {string} ctx.root
  * @param {object} ctx.manifest parsed simt-dev.json, or null
+ * @param {string} [ctx.pushed] the ref list git feeds pre-push on stdin; undefined when no
+ *   push is being classified (every other event, a manual run with no stdin)
  * @returns {Promise<{event: string, gates: object[], failed: boolean}>}
  */
-export async function runGates(event, { root, manifest }) {
+export async function runGates(event, { root, manifest, pushed }) {
   const key = DEFAULT_EVENTS[event];
   if (key === undefined) {
     return { event, gates: [], failed: true, error: `unknown hook event ${event}` };
@@ -84,7 +405,92 @@ export async function runGates(event, { root, manifest }) {
     };
   }
 
+  // A pre-push gate runs against the COMMITTED tree, not the working one. Uncommitted
+  // work must not block the push of previous commits: a gate that fails on WIP the
+  // author has not committed is blocking a push it does not own. The worktree is
+  // disposable and shares the repository's object store, so `git worktree add` is cheap
+  // and needs no clone. The ledger and the version pin stay at the real root - the
+  // evidence is about this repository, not the throwaway checkout.
+  let runRoot = root;
+  let headWorktree = null;
+  let skipTest = null;
+  if (event === 'pre-push') {
+    // Decided before the worktree exists: a push that carries only documentation skips the
+    // `test` gate (ADR-113), and a push whose tree the author already proved green skips it
+    // on that evidence (ADR-120). A push that earns either skip needs no tree for a gate
+    // that will not run.
+    skipTest = (await resolveDocsOnlySkip(root, manifest, pushed)) ??
+      (await resolveAlreadyPassedSkip(root));
+    if (skipTest === null) {
+      const materialized = await materializeHeadWorktree(root);
+      if (materialized.path === null) {
+        return {
+          event,
+          gates: [
+            {
+              name: 'head',
+              status: 'failed',
+              detail: materialized.error,
+              remedy: 'commit the work, or resolve the git state so HEAD is a valid reference, then push again',
+              adr: null,
+            },
+          ],
+          failed: true,
+        };
+      }
+      runRoot = materialized.path;
+      headWorktree = materialized.path;
+    }
+  }
+
+  try {
+    return await runGatesAt(event, { root: runRoot, ledgerRoot: root, manifest, declared, key, skipTest });
+  } finally {
+    if (headWorktree !== null) await removeHeadWorktree(root, headWorktree);
+  }
+}
+
+/**
+ * Run the declared gates at `root`, recording evidence at `ledgerRoot`.
+ *
+ * For a pre-push run the two differ: the gates execute in a throwaway worktree at
+ * HEAD so uncommitted work cannot block the push, while the ledger line belongs to
+ * the repository the author is standing in. For every other event they are the same
+ * path, which is why this is one function with two names for the root rather than
+ * two functions.
+ *
+ * @param {string} event
+ * @param {object} ctx
+ * @param {string} ctx.root the tree the gates execute in
+ * @param {string} ctx.ledgerRoot the repository the evidence is recorded in
+ * @param {object} ctx.manifest
+ * @param {string[]} ctx.declared the gate names for this event
+ * @param {string} ctx.key the manifest key for this event
+ * @param {{reason: string, adr: string} | null} [ctx.skipTest] set when a push skips the
+ *   `test` gate (ADR-113 for docs-only, ADR-120 for an already-green tree); the reason is
+ *   what the report prints in its place, and the adr is the record that earned it
+ * @returns {Promise<{event: string, gates: object[], failed: boolean}>}
+ */
+async function runGatesAt(event, { root, ledgerRoot, manifest, declared, key, skipTest = null }) {
   const pkg = await readPkg(root);
+  // Q31: the runner is committed evidence (lockfile, then `packageManager`),
+  // resolved once per hook run so every script gate spawns the same manager.
+  let runner = null;
+  if (pkg) {
+    const lockfiles = [];
+    for (const file of ['pnpm-lock.yaml', 'yarn.lock', 'bun.lock', 'bun.lockb', 'package-lock.json']) {
+      try {
+        await stat(join(root, file));
+        lockfiles.push(file);
+      } catch {
+        // Absent is the normal case.
+      }
+    }
+    runner = resolveNodeRunner({
+      lockfiles,
+      packageManager: typeof pkg.packageManager === 'string' ? pkg.packageManager : null,
+    }).id;
+  }
   const staged = event === 'pre-commit' ? await stagedFiles(root) : [];
   const unstaged = event === 'pre-commit' ? await unstagedFiles(root) : new Set();
   const commands = manifest?.gates?.commands;
@@ -94,6 +500,9 @@ export async function runGates(event, { root, manifest }) {
   // mean re-reading the command string to find out where anything runs, and a manifest
   // written by an older release would have to be rewritten to gain the capability.
   const cwds = manifest?.gates?.cwd ?? {};
+  // `gates.timeout` bounds one gate, in seconds: a number for every gate, or a map by
+  // name like `gates.cwd`. Absent means the default; 0 means no bound, declared.
+  const timeouts = manifest?.gates?.timeout;
   const results = [];
   // What the format gate rewrote, so restage touches those files and nothing else.
   let formatted = [];
@@ -111,7 +520,16 @@ export async function runGates(event, { root, manifest }) {
       continue;
     }
 
-    const resolution = await resolveGate(gate, { root, pkg, staged, commands });
+    // The one gate a push may not run (ADR-113 for a docs-only push, ADR-120 for a tree
+    // already proven green). It is reported, not dropped: a skip without a printed reason
+    // would let "passed" mean "the suite never ran", which is the exact confusion the report
+    // exists to prevent.
+    if (skipTest !== null && name === 'test') {
+      results.push({ name, status: 'skipped', detail: skipTest.reason, adr: skipTest.adr, exitCode: null });
+      continue;
+    }
+
+    const resolution = await resolveGate(gate, { root, pkg, staged, commands, runner });
     if (!resolution.ok) {
       results.push({
         name,
@@ -130,13 +548,17 @@ export async function runGates(event, { root, manifest }) {
     // declared command for this name takes the shell path below instead.
     if (resolution.builtin !== undefined) {
       const startedBuiltin = Date.now();
-      const outcome = await runBuiltinGate(resolution.builtin, { root, staged });
+      // The manifest's per-builtin options, where a builtin has any: the secret
+      // scan takes its ignore globs from gates.secretScan (review 0003 Q24).
+      const outcome = await runBuiltinGate(resolution.builtin, { root, staged, options: manifest?.gates?.secretScan });
       try {
-        await recordRun(root, {
+        await recordRun(ledgerRoot, {
           cmd: `builtin:${resolution.builtin}`,
           exit: outcome.ok ? 0 : 1,
           ms: Date.now() - startedBuiltin,
           output: outcome.output,
+          gate: name,
+          kind: 'builtin',
         });
       } catch {
         // Recorded by absence: the next evidence read for this tree has no line.
@@ -213,26 +635,41 @@ export async function runGates(event, { root, manifest }) {
       cwd = resolved;
     }
 
+    const timeoutMs = gateTimeoutMs(timeouts, name);
     const started = Date.now();
-    const outcome = await runGate(resolution, cwd);
+    const outcome = await runGate(resolution, cwd, timeoutMs);
     // The ledger is not the gate. A tree that cannot be named leaves no line, and the
     // claim check then finds nothing, which is the direction that cannot invent a run.
     try {
       const cmd = typeof resolution.command === 'string' ? resolution.command : resolution.argv.join(' ');
-      await recordRun(root, {
+      // The evidence claim needs the gate and its kind: a passing secret-scan is
+      // not a passing test run (review 0003 Q18). Coverage proves tests; anything
+      // else keeps its own kind or the gate name.
+      const kind =
+        name === 'test' || name === 'coverage' ? 'test' : name === 'lint' ? 'lint' : name === 'format' ? 'format' : (gate.kind ?? name);
+      await recordRun(ledgerRoot, {
         cmd,
         exit: outcome.code,
         ms: Date.now() - started,
         output: `${outcome.stdout ?? ''}\n${outcome.stderr ?? ''}`,
+        gate: name,
+        kind,
       });
     } catch {
       // Recorded by absence: the next evidence read for this tree has no line.
     }
+    // A killed gate has no exit code of its own (`signal` instead), so the reason is
+    // stated rather than left to `exit 1`, and the remedy says how to change the bound.
     results.push({
       name,
       status: outcome.code === 0 ? 'passed' : 'failed',
-      detail: `${resolution.detail}${outcome.code === 0 ? '' : `: exit ${outcome.code}`}`,
+      detail: outcome.timedOut
+        ? `${resolution.detail}: timed out after ${Math.round(timeoutMs / 1000)} s`
+        : `${resolution.detail}${outcome.code === 0 ? '' : `: exit ${outcome.code}`}`,
       output: outcome.code === 0 ? '' : tail(outcome.stderr || outcome.stdout),
+      ...(outcome.timedOut
+        ? { remedy: `fix the hang, raise gates.timeout to give it longer, or set gates.timeout to 0 to remove the bound` }
+        : {}),
       adr: gate.adr,
       exitCode: outcome.code,
     });
@@ -273,6 +710,54 @@ export async function runGates(event, { root, manifest }) {
   return { event, gates: results, failed: results.some((r) => r.status === 'failed') };
 }
 
+/**
+ * Materialize a detached worktree at HEAD so the pre-push gates run against the
+ * committed tree, not the working one. The worktree shares the repository's object
+ * store, so `git worktree add` is cheap and needs no clone. `node_modules` is
+ * symlinked in when the real root has one, because a script gate resolves its runner
+ * and binaries from there and a fresh worktree does not carry it.
+ *
+ * Fails closed: an unborn HEAD (no commits) or a git error returns `{ path: null }`
+ * with the reason, and the caller turns that into a gate failure rather than running
+ * against a tree it cannot name.
+ *
+ * @param {string} root the real repository root
+ * @returns {Promise<{path: string, error?: never}|{path: null, error: string}>}
+ */
+async function materializeHeadWorktree(root) {
+  const path = await mkdtemp(join(tmpdir(), 'head-gate-'));
+  try {
+    await exec('git', ['worktree', 'add', '--detach', path, 'HEAD'], { cwd: root });
+  } catch (error) {
+    await rm(path, { recursive: true, force: true }).catch(() => {});
+    return { path: null, error: `git worktree add failed: ${String(error.stderr ?? error.message).trim()}` };
+  }
+  const nodeModules = join(root, 'node_modules');
+  try {
+    await symlink(nodeModules, join(path, 'node_modules'));
+  } catch {
+    // Absent node_modules is the normal case for a repo with no install step; a
+    // dangling link is harmless, and `npm run` does not need it to exist.
+  }
+  return { path };
+}
+
+/**
+ * Remove a pre-push worktree. `--force` because a gate may have left it dirty (a
+ * formatter, a test that writes fixtures); the worktree is disposable, the real tree
+ * is not. Falls back to `rm -rf` plus a prune when git cannot remove it (a lock, a
+ * path in a state git does not expect), so a cleanup failure never leaks the tree.
+ *
+ * @param {string} root the real repository root
+ * @param {string} path the worktree to remove
+ */
+async function removeHeadWorktree(root, path) {
+  await exec('git', ['worktree', 'remove', '--force', path], { cwd: root }).catch(async () => {
+    await rm(path, { recursive: true, force: true }).catch(() => {});
+    await exec('git', ['worktree', 'prune'], { cwd: root }).catch(() => {});
+  });
+}
+
 /**
  * The lines that report one event's gate run: the event, what was declared, every
  * gate with its disposition, its reason and its remedy, and the verdict.
@@ -298,13 +783,8 @@ export function renderGateReport(event, declared, result) {
   return lines;
 }
 
-async function run(argv, cwd) {
-  try {
-    const { stdout, stderr } = await exec(argv[0], argv.slice(1), { cwd, maxBuffer: 8 * 1024 * 1024 });
-    return { code: 0, stdout, stderr };
-  } catch (error) {
-    return { code: typeof error.code === 'number' ? error.code : 1, stdout: error.stdout ?? '', stderr: error.stderr ?? String(error.message ?? error) };
-  }
+async function run(argv, cwd, env, timeoutMs) {
+  return await runBounded(argv, { cwd, env, timeoutMs });
 }
 
 /** The built-in gates this dispatcher can run, by name. */
@@ -320,7 +800,7 @@ const BUILTIN_REPORT_MAX = 12;
  * none of them can degrade into a pass, which is the same fail-closed contract
  * an unresolvable script gate has.
  */
-async function runBuiltinGate(name, { root, staged }) {
+async function runBuiltinGate(name, { root, staged, options }) {
   const scan = BUILTIN_GATES.get(name);
   if (scan === undefined) {
     return {
@@ -333,7 +813,7 @@ async function runBuiltinGate(name, { root, staged }) {
   if (staged.length === 0) {
     return { ok: true, detail: 'nothing staged; no added line to scan', output: '' };
   }
-  const result = await scan(root);
+  const result = await scan(root, options ?? {});
   if (result.error !== null) {
     return {
       ok: false,
@@ -375,20 +855,15 @@ async function runBuiltinGate(name, { root, staged }) {
  * that the two sources stay distinguishable, which is why this is a separate branch
  * rather than a flag on `run`.
  */
-async function runGate(resolution, cwd) {
+async function runGate(resolution, cwd, timeoutMs) {
+  // The push override is for the push itself, not for the gates the hook runs.
+  // A test that asserts a push is denied sees the override and fails.
+  const env = { ...process.env };
+  delete env.SIMT_ALLOW;
   if (resolution.shell === true && typeof resolution.command === 'string') {
-    try {
-      const { stdout, stderr } = await exec('sh', ['-c', resolution.command], { cwd, maxBuffer: 8 * 1024 * 1024 });
-      return { code: 0, stdout, stderr };
-    } catch (error) {
-      return {
-        code: typeof error.code === 'number' ? error.code : 1,
-        stdout: error.stdout ?? '',
-        stderr: error.stderr ?? String(error.message ?? error),
-      };
-    }
+    return await run(['sh', '-c', resolution.command], cwd, env, timeoutMs);
   }
-  return run(resolution.argv, cwd);
+  return await run(resolution.argv, cwd, env, timeoutMs);
 }
 
 async function readPkg(root) {
@@ -402,8 +877,10 @@ async function readPkg(root) {
 /** Staged paths, or [] when git cannot answer (an unborn branch, for instance). */
 export async function stagedFiles(root) {
   try {
-    const { stdout } = await exec('git', ['diff', '--cached', '--name-only', '--diff-filter=ACMR'], { cwd: root });
-    return stdout.split('\n').map((s) => s.trim()).filter(Boolean);
+    // `-z`: git quotes a path containing a newline or a quote in the line form, and a
+    // quoted name is not the path the index holds, so it never matches a staged blob.
+    const { stdout } = await exec('git', ['diff', '--cached', '--name-only', '-z', '--diff-filter=ACMR'], { cwd: root });
+    return stdout.split('\0').filter(Boolean);
   } catch {
     return [];
   }
@@ -419,8 +896,8 @@ export async function stagedFiles(root) {
  */
 async function unstagedFiles(root) {
   try {
-    const { stdout } = await exec('git', ['diff', '--name-only'], { cwd: root });
-    return new Set(stdout.split('\n').map((s) => s.trim()).filter(Boolean));
+    const { stdout } = await exec('git', ['diff', '--name-only', '-z'], { cwd: root });
+    return new Set(stdout.split('\0').filter(Boolean));
   } catch {
     return new Set();
   }