simt-dev 0.7.0 → 0.7.1

package/src/hooks/dispatcher.mjs

@@ -18,7 +18,7 @@
 //   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 { 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';
@@ -30,11 +30,120 @@ 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' };
 
@@ -149,13 +258,15 @@ export async function classifyPush(root, refs, { maxCommits, paths }) {
     let count, names;
     try {
       ({ stdout: count } = await exec('git', ['rev-list', '--count', `${remoteSha}..${localSha}`], { cwd: root }));
-      ({ stdout: names } = await exec('git', ['diff', '--name-only', `${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());
-    for (const f of names.split('\n')) {
-      const name = f.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);
     }
   }
@@ -178,7 +289,11 @@ export async function classifyPush(root, refs, { maxCommits, paths }) {
   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)`);
-  return { docsOnly: true, reason: parts.length > 0 ? parts.join('; ') : 'no commits carried' };
+  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('; ')}` };
 }
 
 /**
@@ -189,7 +304,7 @@ export async function classifyPush(root, refs, { maxCommits, paths }) {
  * 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} | null>} null runs the suite; a reason skips the `test` gate
+ * @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;
@@ -200,7 +315,44 @@ async function resolveDocsOnlySkip(root, manifest, pushed) {
     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 } : null;
+  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',
+  };
 }
 
 /**
@@ -263,10 +415,12 @@ export async function runGates(event, { root, manifest, pushed }) {
   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 that earns the skip needs no
-    // tree for a gate that will not run.
-    skipTest = await resolveDocsOnlySkip(root, manifest, pushed);
+    // 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) {
@@ -312,8 +466,9 @@ export async function runGates(event, { root, manifest, pushed }) {
  * @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} | null} [ctx.skipTest] set when a docs-only push skips the
- *   `test` gate (ADR-113); the reason is what the report prints in its place
+ * @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 }) {
@@ -345,6 +500,9 @@ async function runGatesAt(event, { root, ledgerRoot, manifest, declared, key, sk
   // 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 = [];
@@ -362,11 +520,12 @@ async function runGatesAt(event, { root, ledgerRoot, manifest, declared, key, sk
       continue;
     }
 
-    // The one gate a docs-only push does not run (ADR-113). 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.
+    // 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: `docs-only push: ${skipTest.reason}`, adr: 'ADR-113', exitCode: null });
+      results.push({ name, status: 'skipped', detail: skipTest.reason, adr: skipTest.adr, exitCode: null });
       continue;
     }
 
@@ -476,8 +635,9 @@ async function runGatesAt(event, { root, ledgerRoot, manifest, declared, key, sk
       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 {
@@ -498,11 +658,18 @@ async function runGatesAt(event, { root, ledgerRoot, manifest, declared, key, sk
     } 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,
     });
@@ -616,13 +783,8 @@ export function renderGateReport(event, declared, result) {
   return lines;
 }
 
-async function run(argv, cwd, env) {
-  try {
-    const { stdout, stderr } = await exec(argv[0], argv.slice(1), { cwd, env, 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. */
@@ -693,24 +855,15 @@ async function runBuiltinGate(name, { root, staged, options }) {
  * 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, env, 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, env);
+  return await run(resolution.argv, cwd, env, timeoutMs);
 }
 
 async function readPkg(root) {
@@ -724,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 [];
   }
@@ -741,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();
   }

package/src/hooks/gates.mjs

@@ -105,49 +105,6 @@ export function getGate(name) {
   return GATES[name] ?? null;
 }
 
-/**
- * A gate a repo cannot run is a FAILURE, never a skip.
- *
- * This is the load-bearing decision of the whole dispatcher. A gate that
- * silently does nothing is indistinguishable from a gate that passed, and the
- * documented consequence in this estate is an agent reaching for
- * `--no-verify` - a repository removed its tests from pre-commit precisely
- * because they were slow, and slow-plus-silent is what teaches everyone that
- * hooks are advisory.
- */
-export function unresolved(name, { hasScript, binary, command, stack }) {
-  const gate = getGate(name);
-  if (gate === null) {
-    return {
-      gate: name,
-      reason: `unknown gate; the shared dispatcher knows: ${Object.keys(GATES).sort().join(', ')}`,
-      remedy: `remove "${name}" from ${MANIFEST_FILE} gates`,
-    };
-  }
-  if (gate.kind === 'script' && !hasScript(gate.script)) {
-    return {
-      gate: name,
-      reason: `no "${gate.script}" script in package.json`,
-      remedy: `add the script, or remove "${name}" from ${MANIFEST_FILE} gates`,
-    };
-  }
-  if (gate.kind === 'command' && !command) {
-    return {
-      gate: name,
-      reason: `no command declared for this gate in ${MANIFEST_FILE}`,
-      remedy: `set gates.commands["${name}"] to the command that proves it, or remove "${name}" from ${MANIFEST_FILE} gates`,
-    };
-  }
-  if (gate.kind === 'staged' && !binary) {
-    return {
-      gate: name,
-      reason: `${gate.tools.join('/')} is not installed in node_modules/.bin`,
-      remedy: `run the repo install command, or remove "format" from ${MANIFEST_FILE} gates`,
-    };
-  }
-  return null;
-}
-
 export function gateNames() {
   return Object.keys(GATES).sort();
 }

package/src/hooks/resolve.mjs

@@ -14,14 +14,9 @@ import { access } from 'node:fs/promises';
 import { constants } from 'node:fs';
 import { join } from 'node:path';
 
-import { FORMATTABLE, GATES } from './gates.mjs';
+import { FORMATTABLE, GATES, gateNames } from './gates.mjs';
 import { MANIFEST_FILE } from '../name.mjs';
 
-/** Gate names the shared dispatcher knows, sorted. */
-export function knownGates() {
-  return Object.keys(GATES).sort();
-}
-
 /** Is this path an executable file? */
 async function isExecutable(path) {
   try {
@@ -203,7 +198,7 @@ export async function resolveGate(gate, { root, pkg, staged, commands, runner =
     gate: name,
     kind: 'unknown',
     reason: `unknown gate kind "${gate.kind}"`,
-    remedy: `this is a bug in simt-dev; known gates: ${knownGates().join(', ')}`,
+    remedy: `this is a bug in simt-dev; )}', ')}`,
   };
 }
 

package/src/hooks/shim.mjs

@@ -36,8 +36,11 @@ export const SHIM_MARKER = '# Generated by simt-dev. Do not edit.';
 /** Events the shared dispatcher knows how to run. */
 export const EVENTS = ['pre-commit', 'pre-push'];
 
-/** Directory the shims are written to inside a repo. */
-export const HOOKS_DIR = '.simt-hooks';
+/** Directory the shims are written to inside a repo, inside the state directory (ADR-122). */
+export const HOOKS_DIR = '.simt/hooks';
+
+/** The top-level shim directory that preceded the move into the state directory (ADR-122). */
+export const HOOKS_DIR_LEGACY = '.simt-hooks';
 
 /** Name of the git config key that points at the shim directory. */
 export const HOOKS_PATH_KEY = 'core.hooksPath';

package/src/identity.mjs

@@ -257,4 +257,32 @@ export async function ignoreIdentity(root, journal = null) {
   if (journal) await journaledWriteFile(root, journal, path, next);
   else await writeFile(path, next);
   return true;
-}
+}
+/**
+ * The `user.*` keys the repository's own config sets, which is the one place an
+ * identity can be overridden without a trace in the tracked tree.
+ *
+ * A repo-local `[user]` block wins over both the `git.config` include and the
+ * machine's own identity, so every commit made here inherits it silently - including
+ * the commits this tool makes on the reader's behalf (`slice finish`, `plan done`).
+ * That is not a hypothetical: 34 commits in this repository were authored as
+ * `t <t@t.t>` because `.git/config` carried that block and nothing reported it. The
+ * helper exists so `test/repo-identity.test.mjs` can fail loudly instead.
+ *
+ * `--local` rather than `--get`: the question is what THIS config adds, not what the
+ * resolved identity happens to be.
+ *
+ * @param {string} root
+ * @returns {Promise<{key: string, value: string}[]>}
+ */
+export async function localIdentityOverrides(root) {
+  const out = await git(root, ['config', '--local', '--get-regexp', '^user\\.']);
+  if (!out) return [];
+  return out
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      const space = line.indexOf(' ');
+      return { key: line.slice(0, space), value: line.slice(space + 1) };
+    });
+}

package/src/journal.mjs

@@ -16,10 +16,14 @@
 //   - The plan row says `.simt-dev/journal/`, which predates the STATE_DIR
 //     rename (the same stale spelling survives in bench/probes.mjs comments).
 //     The journal lives under STATE_DIR like every other per-repo state.
-//   - Nothing under `.simt/` is journaled. The journal recording itself is
-//     recursion; the ledger, index and candidates are evidence and caches, and
-//     restoring those to an earlier byte-shape would corrupt R17 rather than
-//     repair anything. `journaledWriteFile` performs those writes unrecorded.
+//   - Nothing under `.simt/` is journaled, one named exception: the shim
+//     directory. The journal recording itself is recursion; the ledger, index
+//     and candidates are evidence and caches, and restoring those to an earlier
+//     byte-shape would corrupt R17 rather than repair anything. The shims are
+//     the opposite of that: git's routing points at them, and the undo that
+//     restores the routing must restore the shims with it (review 0003 Q22;
+//     ADR-122 moved them under STATE_DIR). `journaledWriteFile` performs the
+//     other writes unrecorded.
 //   - Only regular files. Symlinks carry no bytes for beforeBytes to hold, and
 //     the record shape is file bytes — pointer changes are reported by the
 //     command as before and are not undone. Removals are journaled as entries
@@ -39,12 +43,13 @@
 
 import { execFile } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { chmod, cp, mkdir, readFile, readdir, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { chmod, cp, mkdir, readFile, readdir, rename, rmdir, stat, unlink, writeFile } from 'node:fs/promises';
 import { dirname, join, relative, sep } from 'node:path';
 import { promisify } from 'node:util';
 
 import { STATE_DIR } from './name.mjs';
 import { LOCAL_DIR } from './state.mjs';
+import { HOOKS_DIR } from './hooks/shim.mjs';
 
 const exec = promisify(execFile);
 
@@ -129,8 +134,11 @@ export async function journaledWriteFile(root, acc, path, text, { mode } = {}) {
     throw new Error(`journal refuses a write outside the repository: ${path}`);
   }
   const before = await readOrNull(path);
-  // Internal state is written, not recorded — see the module header.
-  const internal = rel(root, path) === STATE_DIR || rel(root, path).startsWith(`${STATE_DIR}/`);
+  // Internal state is written, not recorded — see the module header, which
+  // names the shim directory as the one exception under STATE_DIR.
+  const r = rel(root, path);
+  const internal =
+    (r === STATE_DIR || r.startsWith(`${STATE_DIR}/`)) && r !== HOOKS_DIR && !r.startsWith(`${HOOKS_DIR}/`);
   await mkdir(dirname(path), { recursive: true });
   // tmp + rename, the way this module writes its own set files: a crash
   // mid-write leaves the old bytes in place, never a half-written file
@@ -202,7 +210,9 @@ export async function journaledRemoveFile(root, acc, path) {
   }
   const before = await readOrNull(path);
   if (before === null) return;
-  const internal = rel(root, path) === STATE_DIR || rel(root, path).startsWith(`${STATE_DIR}/`);
+  const r = rel(root, path);
+  const internal =
+    (r === STATE_DIR || r.startsWith(`${STATE_DIR}/`)) && r !== HOOKS_DIR && !r.startsWith(`${HOOKS_DIR}/`);
   await unlink(path);
   if (!internal) {
     acc.push(fileEntry(rel(root, path), before, null));
@@ -324,6 +334,61 @@ function coalesceEntries(acc) {
   });
 }
 
+/**
+ * Move the sets that predate the move into `.simt/local/journal` (review 0003
+ * Q19's fallback directory) into the current directory, and take the legacy
+ * directory down when the move empties it. While the current directory is
+ * absent, `listJournalSets` falls back to the legacy one; once it exists, the
+ * two are disjoint and the legacy sets are invisible to `undo` — a repo that
+ * accumulated history under the old path loses it on its first write after the
+ * move (plan 0005 H3). `commitJournal` is the only writer, so the migration
+ * rides on it and heals on the next journal activity. Every legacy set
+ * predates every current set — the current directory is created by this
+ * writer — so the move cannot disturb recency order. A name present in both
+ * keeps both copies when the bytes differ: a set file is history, and a
+ * collision is not a reason to drop one of the two records. A crash mid-move
+ * splits the sets between the two directories; the move is idempotent, so the
+ * next call finishes it.
+ */
+async function migrateLegacyJournal(root) {
+  const legacy = join(root, JOURNAL_DIR_LEGACY);
+  let names;
+  try {
+    names = await readdir(legacy);
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+    return;
+  }
+  const dir = join(root, JOURNAL_DIR);
+  await mkdir(dir, { recursive: true });
+  for (const name of names) {
+    // Sets, `.undone.json` history and `.undoing.json` markers all end in
+    // `.json`; a stray file of any other kind keeps the directory in place.
+    if (!name.endsWith(SET_SUFFIX)) continue;
+    const from = join(legacy, name);
+    const to = join(dir, name);
+    try {
+      await stat(to);
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      await rename(from, to);
+      continue;
+    }
+    // The name is taken: equal bytes are a duplicate of the same set (drop the
+    // legacy copy); differing bytes are a collision (keep both — the current
+    // copy shadows the legacy one in the listing).
+    const [a, b] = await Promise.all([readFile(from), readFile(to)]);
+    if (a.equals(b)) await unlink(from);
+  }
+  // `rmdir` fails when the directory is not empty, which is exactly the
+  // safety: a stray file the move does not take keeps the directory.
+  try {
+    await rmdir(legacy);
+  } catch (error) {
+    if (error.code !== 'ENOTEMPTY' && error.code !== 'EEXIST') throw error;
+  }
+}
+
 /**
  * Persist a run's set. Writes nothing when the run changed nothing, so the
  * last set on disk is always the last run that wrote.
@@ -331,6 +396,7 @@ function coalesceEntries(acc) {
  * @returns {Promise<string|null>} the set id (file name), or null
  */
 export async function commitJournal(root, command, acc, { at = Date.now() } = {}) {
+  await migrateLegacyJournal(root);
   const entries = coalesceEntries(acc);
   if (entries.length === 0) return null;
   await ignoreJournal(root);
@@ -365,7 +431,10 @@ export async function journalHygiene(root) {
 
 /** Set ids newest-first, undone sets excluded. */
 export async function listJournalSets(root) {
-  // The pre-move directory is a fallback for one release (review 0003 Q19).
+  // The pre-move directory is a fallback for one release (review 0003 Q19);
+  // the sets in it move into the current directory on the next write
+  // (`migrateLegacyJournal`, plan 0005 H3), so the fallback only serves a
+  // repo that has not written since the move.
   let names;
   try {
     names = await readdir(join(root, JOURNAL_DIR));