create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/landing/train.js

@@ -0,0 +1,885 @@
+'use strict';
+// WP-1 (docs/local-landing-queue-multi-session-integration-2026-10-26.html §5 D-3/D-5/D-8, §11
+// Risks, §8 WP-1): the train — how a job becomes exactly one commit to fast-forward the target to.
+//
+// D-3 builds the train WITHOUT touching any worktree (`merge-tree --write-tree` + `commit-tree`);
+// the only worktree this module ever creates is the job's own gate worktree, and only D-8 (a
+// conflict confined to `landing.regenerate` paths) needs it for the commit itself. Nothing here
+// writes into a session worktree, and nothing here ever merges *into* the target checkout unguarded
+// — D-5 goes through `git merge --ff-only`, which git itself refuses when it would clobber local
+// state, or through the compare-and-swap `git update-ref <ref> <new> <old>`.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const {
+  landingError,
+  childEnv,
+  commonDir,
+  runGitRaw,
+  git,
+  gitFailed,
+  revParse,
+  revParseOrNull,
+  isAncestor,
+  mergeTree,
+  commitTree,
+  casUpdateRef,
+  ffCheckedOut,
+} = require('./git');
+
+const MAX_ROUNDS = 3;
+const GLOB_CACHE = new Map();
+// A gate that ignores SIGTERM gets this long before its whole process group is SIGKILLed.
+const GATE_KILL_GRACE_MS = 10000;
+
+function targetRef(target) {
+  return `refs/heads/${target}`;
+}
+
+// Signal a whole process tree. `detached: true` made the shell a process-group leader, so the
+// negative pid reaches every descendant the gate spawned — a bare `child.kill()` reaches only
+// `/bin/sh` and leaves the test suite the gate started running forever (D-4's `gate_timeout` then
+// reports a timeout while the machine keeps working).
+function killGroup(child, signal) {
+  try {
+    process.kill(-child.pid, signal);
+    return true;
+  } catch (error) {
+    /* expected: the group is already gone, or the pid never became a group leader — fall back to
+       the direct pid, which is also how a non-detached child would be signalled */
+    try {
+      child.kill(signal);
+      return true;
+    } catch (inner) {
+      /* expected: the process exited between the signal and this call — nothing left to signal */
+      return false;
+    }
+  }
+}
+
+// Every gate/regenerate command the queue runs goes through `/bin/sh -c` with an env built from
+// `process.env` MINUS the seven §4 GIT_* names (`childEnv`), plus the LAND_* contract. `extra`
+// cannot reintroduce a scrubbed name: `childEnv` applies it AFTER the scrub but the keys below are
+// never GIT_*.
+//
+// D-4 keeps the gate a CHILD, never the runner itself, and it is asynchronous on purpose:
+// `spawn` (not `spawnSync`) leaves the runner's event loop free, so the lease heartbeat really
+// fires while a 40-minute gate works. Output streams straight into the job log file through
+// `logFd` — a live `land inspect` tail — instead of accumulating in a 64 MiB in-memory buffer.
+// WP-2 (§5 D-5): `signal` is an optional AbortSignal. The queue's stop primitive aborts it from the
+// runner's heartbeat, and every command of the job — gates AND regenerate entries — runs through
+// here, so this one option is the single place a running gate can be stopped. An already-aborted
+// signal resolves WITHOUT spawning, and an abort mid-run signals the whole process group exactly the
+// way the timeout path does (SIGTERM, then SIGKILL after `GATE_KILL_GRACE_MS`).
+function runShell(command, { cwd, extra, timeoutMs, logFd, signal } = {}) {
+  return new Promise((resolve) => {
+    const started = Date.now();
+    if (signal && signal.aborted) {
+      resolve({ status: null, signal: null, timedOut: false, aborted: true, error: null, seconds: 0 });
+      return;
+    }
+    const stdio = logFd === undefined || logFd === null ? 'ignore' : logFd;
+    let child;
+    try {
+      child = spawn('/bin/sh', ['-c', command], {
+        cwd,
+        env: childEnv(extra),
+        detached: true,
+        stdio: ['ignore', stdio, stdio],
+      });
+    } catch (error) {
+      resolve({ status: null, signal: null, timedOut: false, aborted: false, error, seconds: 0 });
+      return;
+    }
+    let timedOut = false;
+    let aborted = false;
+    let killTimer = null;
+    const timer = Number.isFinite(timeoutMs) && timeoutMs > 0
+      ? setTimeout(() => {
+        timedOut = true;
+        killGroup(child, 'SIGTERM');
+        killTimer = setTimeout(() => killGroup(child, 'SIGKILL'), GATE_KILL_GRACE_MS);
+      }, timeoutMs)
+      : null;
+    const onAbort = () => {
+      aborted = true;
+      killGroup(child, 'SIGTERM');
+      killTimer = setTimeout(() => killGroup(child, 'SIGKILL'), GATE_KILL_GRACE_MS);
+    };
+    if (signal) signal.addEventListener('abort', onAbort, { once: true });
+    const finish = (status, termSignal, error) => {
+      if (timer) clearTimeout(timer);
+      if (killTimer) clearTimeout(killTimer);
+      if (signal) signal.removeEventListener('abort', onAbort);
+      resolve({
+        status,
+        signal: termSignal,
+        timedOut,
+        aborted,
+        error: error || null,
+        seconds: Number(((Date.now() - started) / 1000).toFixed(3)),
+      });
+    };
+    child.on('error', (error) => finish(null, null, error));
+    child.on('close', (status, termSignal) => finish(status, termSignal, null));
+  });
+}
+
+// --- globs (§6.1 `regenerate[].paths`, `registries[]`) ----------------------------------------
+
+// Git-style pathspec globbing: `**` crosses directory boundaries (including zero of them, so
+// `docs/**` matches `docs/INDEX.html`), `*` and `?` do not.
+function globToRegExp(pattern) {
+  const cached = GLOB_CACHE.get(pattern);
+  if (cached) return cached;
+  let out = '^';
+  for (let index = 0; index < pattern.length; index += 1) {
+    const ch = pattern[index];
+    if (ch === '*') {
+      if (pattern[index + 1] === '*') {
+        if (pattern[index + 2] === '/') {
+          out += '(?:[^/]*/)*';
+          index += 2;
+        } else {
+          out += '.*';
+          index += 1;
+        }
+      } else {
+        out += '[^/]*';
+      }
+    } else if (ch === '?') {
+      out += '[^/]';
+    } else if ('\\^$.|+()[]{}'.includes(ch)) {
+      out += `\\${ch}`;
+    } else {
+      out += ch;
+    }
+  }
+  const re = new RegExp(`${out}$`);
+  GLOB_CACHE.set(pattern, re);
+  return re;
+}
+
+function globMatch(pattern, file) {
+  if (globToRegExp(pattern).test(file)) return true;
+  // A directory pattern (`docs`, `docs/`) also owns everything underneath it.
+  return globToRegExp(`${pattern.replace(/\/+$/, '')}/**`).test(file);
+}
+
+// D-2 (§9 S-6): every `landing.refresh[]` entry runs on EVERY train. The entry's owned paths are
+// tree-derived pins (the closure policy's `sourceBindings` digests), and the bound set is the
+// policy's own key list — "did a bound source change" is not knowable cheaply from a path list, and
+// the script is idempotent, so the simplest correct rule is to run all of them and let the
+// `git diff --cached --quiet` check decide whether a new commit is needed at all.
+function matchingRefreshEntries(config) {
+  return config && Array.isArray(config.refresh) ? config.refresh : [];
+}
+
+// D-8: every conflicted path must be owned by a `landing.regenerate[]` entry. Returns the distinct
+// entries to run, or null when at least one path is hand-written (the job blocks).
+function matchingRegenerateEntries(config, conflicts) {
+  const entries = config && Array.isArray(config.regenerate) ? config.regenerate : [];
+  const matched = [];
+  for (const file of conflicts) {
+    const entry = entries.find((candidate) => candidate.paths.some((pattern) => globMatch(pattern, file)));
+    if (!entry) return null;
+    if (!matched.includes(entry)) matched.push(entry);
+  }
+  return matched;
+}
+
+// MOVED here from `gate.js` verbatim (WP-2, §5 D-6) so the base rerun can build the same worktree:
+// the cache directories a gate needs (`landing.cachePaths`, e.g. `node_modules`) are symlinked into
+// the materialized worktree rather than copied. The source checkout only supplies them when it has
+// them — a fresh clone with no `node_modules` simply has nothing to link in — and a path that is a
+// REAL tracked directory in the tree wins over the link.
+function linkCachePaths(dir, sourceDir, cachePaths) {
+  const linked = [];
+  for (const rel of cachePaths) {
+    const source = path.resolve(sourceDir, rel);
+    let stat = null;
+    try {
+      stat = fs.statSync(source);
+    } catch (error) {
+      /* expected: this cache directory has not been populated in the source checkout (a fresh
+         clone); there is simply nothing to link in */
+      continue;
+    }
+    if (!stat.isDirectory()) continue;
+    const link = path.join(dir, rel);
+    fs.mkdirSync(path.dirname(link), { recursive: true });
+    try {
+      fs.symlinkSync(source, link, 'dir');
+      linked.push(rel);
+    } catch (error) {
+      /* expected: the train tree already contains a real directory at this path (the cache path is
+         tracked in this repository after all) — the real directory wins */
+    }
+  }
+  return linked;
+}
+
+// --- D-3: the worktree-free train -------------------------------------------------------------
+
+// `{ kind, base, tree, train, conflicts }` where kind is:
+//   'unchanged' — the merge result is the target's own tree: the branch is already in the target
+//   'train'     — `train` is the commit to fast-forward the target to (the tip itself when the
+//                 target is an ancestor of it, otherwise a two-parent merge commit)
+//   'conflict'  — `conflicts` holds the paths merge-tree reported
+function buildTrain(cwd, target, job) {
+  const built = buildBatchTrain(cwd, target, [job]);
+  const skipped = built.skipped.length ? built.skipped[0] : null;
+  if (skipped) {
+    return { kind: 'conflict', base: built.base, tree: built.tree, train: null, conflicts: skipped.paths };
+  }
+  if (built.kind === 'unchanged') {
+    return { kind: 'unchanged', base: built.base, tree: built.tree, train: built.base, conflicts: [] };
+  }
+  return { kind: 'train', base: built.base, tree: built.tree, train: built.train, conflicts: [] };
+}
+
+// WP-1 D-1 (§5 D-1, §6, §8 WP-1, §9 S-2, AC-1a/AC-1c): the batched train. `c0 = base` (the target
+// tip) and each member in queue order is merged ON TOP of the previous chain head:
+//   c_k = commitTree(mergeTree(c_{k-1}, tip_k), [c_{k-1}, tip_k])
+// with the fast-forward shortcut `buildTrain` already had: when `tip_k` descends from `c_{k-1}` the
+// train is `tip_k` itself, so a member that is simply ahead of the target keeps the commit the
+// author's own gate proved (D-6's proof chain walks first parents and stays valid).
+//
+// A member whose mergeTree onto `c_{k-1}` CONFLICTS is skipped — `onSkip(member, paths)` is called,
+// the chain does not advance, and the next member is merged onto the same head (D-1: the conflicting
+// member never blocks the others; it goes back to the queue with `{ base: c_{k-1}, paths }` as its
+// preview). A chain that never moves (every member skipped, or every merge a no-op) is `unchanged`.
+//
+// Returns `{ kind, base, members, skipped, chain, train, tree }`: `chain[k]` is the commit for
+// `members[0..k]` minus the skipped ones, `train` the final head (== `base` when nothing moved).
+function buildBatchTrain(cwd, target, members, opts = {}) {
+  const onSkip = typeof opts.onSkip === 'function' ? opts.onSkip : () => {};
+  const base = revParse(cwd, targetRef(target));
+  const baseTree = revParse(cwd, `${base}^{tree}`);
+  const list = Array.isArray(members) ? members : [];
+  const chain = [];
+  const skipped = [];
+  const kept = [];
+  let head = base;
+  for (const member of list) {
+    const merged = mergeTree(cwd, head, member.tip);
+    if (merged.conflicts.length) {
+      // `head` is the chain commit the conflict was measured against, which is what the member's
+      // `conflictPreview.base` must name (D-1); the design's signature is `onSkip(member, paths)` and
+      // the extra argument is additive.
+      onSkip(member, merged.conflicts, head);
+      skipped.push({ id: member.id, paths: merged.conflicts });
+      continue;
+    }
+    if (isAncestor(cwd, head, member.tip)) {
+      // D-1 ff case, exactly as `buildTrain` does for one job: the train IS the member's own commit.
+      head = member.tip;
+      chain.push(head);
+      kept.push(member);
+      continue;
+    }
+    head = commitTree(cwd, merged.tree, [head, member.tip], trainMessage(member));
+    chain.push(head);
+    kept.push(member);
+  }
+  const tree = revParse(cwd, `${head}^{tree}`);
+  const moved = chain.length > 0 && tree !== baseTree;
+  return {
+    kind: moved ? 'train' : 'unchanged',
+    base,
+    members: kept,
+    skipped,
+    chain,
+    train: moved ? head : base,
+    tree,
+  };
+}
+
+function trainMessage(job) {
+  return `land(${job.branch}): ${job.title}`;
+}
+
+// --- the gate worktree (§11 Risks) -------------------------------------------------------------
+
+// §11: a gate that depends on its worktree path must see the repository root it expects, so the
+// train worktree lives at `<repo-root>/.worktrees/land-<jobId>` whenever the common dir is exactly
+// `<repo-root>/.git` AND `.worktrees/` is already git-ignored there (so it never shows up as
+// untracked dirt in the repository). Otherwise it falls back to `<common-dir>/landing/trains/`.
+function trainsRoot(cwd, commonDirPath) {
+  if (path.basename(commonDirPath) === '.git') {
+    const repoRoot = path.dirname(commonDirPath);
+    const probe = runGitRaw(repoRoot, ['check-ignore', '-q', '--', '.worktrees/land-probe']);
+    if (probe.status === 0) return { dir: path.join(repoRoot, '.worktrees'), source: 'repo-root' };
+  }
+  return { dir: path.join(commonDirPath, 'landing', 'trains'), source: 'common-dir' };
+}
+
+// WP-1 D-1 (§9 S-3): keyed by the TRAIN id — the batch id (`b-<ulid>`) for a batch, the job id for
+// a singleton. One train, one worktree, one log, one selection record: every member of a batch points
+// at the same artefacts, which is what makes the gate's output readable as a batch rather than as N
+// copies of the first job's.
+function trainDirFor(rootDir, trainId) {
+  return path.join(rootDir, `land-${trainId}`);
+}
+
+// A previous runner may have been killed between `worktree add` and its cleanup, leaving both the
+// directory and its registration behind. Only paths that look like ours are touched.
+function prepareTrainDir(cwd, dir) {
+  if (path.basename(dir).startsWith('land-') === false) {
+    throw landingError('train_dir_invalid', `refusing to prepare ${dir}: not a land-* train directory`, { dir });
+  }
+  runGitRaw(cwd, ['worktree', 'prune']);
+  let exists = true;
+  try {
+    fs.lstatSync(dir);
+  } catch (error) {
+    /* expected: the common case — nobody left a train worktree behind for this job */
+    exists = false;
+  }
+  if (!exists) return false;
+  const removed = runGitRaw(cwd, ['worktree', 'remove', '--force', '--force', dir]);
+  if (removed.status !== 0) {
+    // A directory that is no longer registered as a worktree (the registration was pruned) is
+    // still ours by name and location; remove the leftover so `worktree add` can succeed.
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+  return true;
+}
+
+function addTrainWorktree(cwd, dir, train, jobId) {
+  prepareTrainDir(cwd, dir);
+  const args = ['worktree', 'add', '--detach', '--lock', '--reason', `land job ${jobId}`, dir, train];
+  const res = runGitRaw(cwd, args);
+  if (res.status !== 0) throw gitFailed(cwd, args, res);
+  return dir;
+}
+
+// Only ever called for this job's own train directory (`<trains>/.worktrees|trains/land-<id>`),
+// which the queue created itself and which no session can have work in. `--force --force` is
+// required because the gate legitimately owns that directory and may have dirtied the tree inside
+// it — AC-1d asserts the worktree is gone after `gate_dirtied_tree`.
+function removeTrainWorktree(cwd, dir) {
+  if (!dir) return { removed: false, reason: 'no_dir' };
+  const res = runGitRaw(cwd, ['worktree', 'remove', '--force', '--force', dir]);
+  if (res.status === 0) return { removed: true };
+  let exists = true;
+  try {
+    fs.lstatSync(dir);
+  } catch (error) {
+    /* expected: git already removed the directory but reported a non-zero status (for example a
+       concurrent `worktree prune`) — the directory is gone, which is what the caller asked for */
+    exists = false;
+  }
+  if (!exists) return { removed: true, note: 'already absent' };
+  return { removed: false, reason: String(res.stderr || res.stdout || '').trim() || `git worktree remove exited ${res.status}` };
+}
+
+// `git worktree list --porcelain`, parsed into one entry per worktree.
+function worktreeList(cwd) {
+  const args = ['worktree', 'list', '--porcelain'];
+  const res = runGitRaw(cwd, args);
+  if (res.status !== 0) throw gitFailed(cwd, args, res);
+  const entries = [];
+  let current = null;
+  for (const line of res.stdout.split('\n')) {
+    if (line === '') {
+      if (current) entries.push(current);
+      current = null;
+      continue;
+    }
+    const space = line.indexOf(' ');
+    const key = space === -1 ? line : line.slice(0, space);
+    const value = space === -1 ? '' : line.slice(space + 1);
+    if (key === 'worktree') {
+      if (current) entries.push(current);
+      current = { path: value, branch: null, detached: false, locked: false, bare: false, prunable: false };
+    } else if (current) {
+      if (key === 'branch') current.branch = value;
+      else if (key === 'detached') current.detached = true;
+      else if (key === 'locked') current.locked = true;
+      else if (key === 'bare') current.bare = true;
+      else if (key === 'prunable') current.prunable = true;
+    }
+  }
+  if (current) entries.push(current);
+  return entries;
+}
+
+// D-5: the worktree (if any) that has the target branch checked out. Detached worktrees — the
+// queue's own train worktrees, and any user checkout — are never the target.
+function targetWorktreeFor(cwd, target) {
+  const ref = targetRef(target);
+  return worktreeList(cwd).find((entry) => entry.branch === ref && !entry.bare && !entry.prunable) || null;
+}
+
+// --- D-5: landing ------------------------------------------------------------------------------
+
+function commitsBetween(cwd, from, to) {
+  const res = runGitRaw(cwd, ['log', '--format=%H', `${from}..${to}`]);
+  if (res.status !== 0) return [];
+  return res.stdout.split('\n').map((line) => line.trim()).filter(Boolean);
+}
+
+function mergeBase(cwd, a, b) {
+  const res = runGitRaw(cwd, ['merge-base', a, b]);
+  if (res.status !== 0) return null;
+  const value = res.stdout.trim();
+  return value || null;
+}
+
+// D-5: fast-forward the target to exactly `train`. A target checked out somewhere goes through
+// `git merge --ff-only` in that worktree (git refuses without modifying anything when local changes
+// would be clobbered -> `target_dirty`); otherwise the branch is moved with a compare-and-swap.
+//
+// `expectedBase` is the commit this train was BUILT on, and it is what the swap compares against —
+// never a re-read tip. Re-reading would move the target to a train that does not contain a commit
+// that landed in the meantime, silently dropping it; comparing against the build base turns that
+// race into `cas_lost`, which the caller treats exactly like a moved target (record the foreign
+// commits, rebuild, retrain). A target checked out in a worktree cannot be rewound by
+// `merge --ff-only` at all, but it can refuse; the HEAD comparison reports that as `cas_lost` too.
+//
+// WP-6: `opts.env` is handed to BOTH ref-moving git children, so the runner can present the
+// `LAND_TOKEN` the E-1 reference-transaction guard compares against its own lease record. It is the
+// env EXTRA, not a whole environment: `git.js#childEnv` starts from `process.env` minus the §4
+// GIT_* list and only then applies `extra`, which is exactly how `runShell` passes `LAND_TOKEN` to
+// gates (gate.js:151). Spreading `process.env` here instead would re-introduce the scrubbed GIT_*
+// names (I-8). Existing callers pass no `opts` and are byte-for-byte unaffected.
+function landTrain(cwd, target, train, expectedBase, opts = {}) {
+  const gitOpts = { env: opts.env };
+  const worktree = targetWorktreeFor(cwd, target);
+  if (worktree) {
+    const head = revParseOrNull(worktree.path, 'HEAD');
+    if (expectedBase !== undefined && head !== expectedBase) {
+      throw landingError('cas_lost', `${targetRef(target)} is checked out at ${head}, expected ${expectedBase}`, {
+        ref: targetRef(target), expected: expectedBase, current: head, cwd: worktree.path, worktree: worktree.path,
+      });
+    }
+    const result = ffCheckedOut(worktree.path, train, gitOpts);
+    return { via: 'ff', worktree: worktree.path, sha: result.sha };
+  }
+  const expected = expectedBase === undefined ? revParseOrNull(cwd, targetRef(target)) : expectedBase;
+  casUpdateRef(cwd, targetRef(target), train, expected, gitOpts);
+  return { via: 'cas', worktree: null, sha: revParseOrNull(cwd, targetRef(target)) };
+}
+
+// --- D-8: conflicts confined to regenerate paths ------------------------------------------------
+
+function changedFilesBetween(cwd, from, to) {
+  const res = runGitRaw(cwd, ['diff', '--name-only', from, to]);
+  if (res.status !== 0) return [];
+  return res.stdout.split('\n').map((line) => line.trim()).filter(Boolean);
+}
+
+function hunkHeaders(cwd, from, to, file) {
+  const res = runGitRaw(cwd, ['diff', '--no-color', '-U0', from, to, '--', file]);
+  if (res.status !== 0) return [];
+  return res.stdout.split('\n').filter((line) => line.startsWith('@@')).map((line) => line.trim());
+}
+
+// D-9 Tier A, run per job on a FAIL: the files the target changed since the merge base intersect
+// the files the branch changed. `sameHunkContext` marks a file where both sides moved the SAME
+// -U0 hunk header (git's own function context), which is the strongest available signal short of a
+// second gate — and a second gate is explicitly out of scope.
+function overlapWithTarget(cwd, targetTip, tip) {
+  const base = mergeBase(cwd, targetTip, tip);
+  if (!base) return [];
+  const branchFiles = new Set(changedFilesBetween(cwd, base, tip));
+  const overlap = [];
+  for (const file of changedFilesBetween(cwd, base, targetTip)) {
+    if (!branchFiles.has(file)) continue;
+    const branchHunks = new Set(hunkHeaders(cwd, base, tip, file));
+    const shared = hunkHeaders(cwd, base, targetTip, file).some((header) => branchHunks.has(header));
+    overlap.push({ file, sameHunkContext: shared });
+  }
+  return overlap;
+}
+
+// The body shared by `regenerateTrain` (D-8) and `refreshTrain` (D-2): run every entry in the
+// ALREADY-MATERIALIZED train worktree `dir` with the §4 LAND_* contract, honour the stop signal,
+// then stage EXACTLY the paths the entries own and refuse to go on while anything is left unmerged.
+// Returns the owned paths that actually changed, which is what tells `refreshTrain` whether the train
+// commit has to be remade at all.
+//
+// Entries run in order and the next one may depend on the previous one's output, so the loop is
+// deliberately sequential. A stopped entry is a STOP, not a failure — `land.js` turns the `stopped`
+// code into `canceled` at its stop checkpoint.
+async function runEntriesInWorktree({ dir, job, base, entries, log, signal, label, conflicts }) {
+  const logFd = log ? fs.openSync(log, 'a') : null;
+  const write = (text) => { if (logFd !== null) fs.writeSync(logFd, `${text}\n`); };
+  try {
+    for (const entry of entries) {
+      write(`$ ${entry.run}`);
+      // eslint-disable-next-line no-await-in-loop
+      const res = await runShell(entry.run, {
+        cwd: dir,
+        extra: { LAND_TRAIN: dir, LAND_BASE: base, LAND_TIP: job.tip, LAND_JOB: job.id },
+        logFd,
+        signal,
+      });
+      if (res.aborted) {
+        throw landingError('stopped', `${label} entry ${JSON.stringify(entry.run)} stopped`, {
+          jobId: job.id, run: entry.run,
+        });
+      }
+      if (res.timedOut) {
+        throw landingError(`${label}_timeout`, `${label} entry ${JSON.stringify(entry.run)} timed out`, {
+          jobId: job.id, run: entry.run, conflicts,
+        });
+      }
+      if (res.status !== 0) {
+        throw landingError(`${label}_failed`, `${label} entry ${JSON.stringify(entry.run)} exited ${res.status}`, {
+          jobId: job.id, run: entry.run, status: res.status, signal: res.signal,
+        });
+      }
+      write(`[${label}] ${entry.run}: ok`);
+    }
+  } finally {
+    if (logFd !== null) fs.closeSync(logFd);
+  }
+
+  // Stage EXACTLY the paths the entries own: expand each pattern against what actually changed.
+  const statusRes = runGitRaw(dir, ['status', '--porcelain']);
+  const changed = statusRes.stdout
+    .split('\n')
+    .map((line) => line.trimEnd())
+    .filter((line) => line.length > 3)
+    .map((line) => {
+      const body = line.slice(3);
+      const renamed = body.includes(' -> ') ? body.split(' -> ').pop() : body;
+      return renamed.startsWith('"') && renamed.endsWith('"') ? renamed.slice(1, -1) : renamed;
+    })
+    .filter((file) => entries.some((entry) => entry.paths.some((pattern) => globMatch(pattern, file))));
+  if (changed.length) {
+    const addArgs = ['add', '-A', '--', ...changed];
+    const added = runGitRaw(dir, addArgs);
+    if (added.status !== 0) throw gitFailed(dir, addArgs, added);
+  }
+
+  const unmerged = runGitRaw(dir, ['diff', '--name-only', '--diff-filter=U']);
+  const stillUnmerged = unmerged.stdout.split('\n').map((line) => line.trim()).filter(Boolean);
+  if (stillUnmerged.length) {
+    throw landingError('conflict_unresolved', `${label} left unmerged paths: ${stillUnmerged.join(', ')}`, {
+      jobId: job.id, paths: stillUnmerged, conflicts,
+    });
+  }
+  return changed;
+}
+
+// D-8: materialize the train worktree at the target tip, merge the branch WITHOUT committing, run
+// each matching `regenerate` entry, stage exactly the paths the entries own, verify nothing is left
+// unmerged, and commit. This is one of two cases where the train commit is made in a worktree — and
+// it is made with PLUMBING (`write-tree` + `commit-tree`), never `git commit`: a real commit fires
+// the repository's own `pre-commit` hook (a ten-minute gate here) and demands a configured
+// `user.name`, neither of which a queue that is merely rebuilding a conflicted file has any
+// business triggering.
+async function regenerateTrain({ cwd, dir, job, base, conflicts, entries, log, signal }) {
+  addTrainWorktree(cwd, dir, base, job.id);
+  const mergeArgs = ['merge', '--no-commit', '--no-ff', job.tip];
+  const merged = runGitRaw(dir, mergeArgs);
+  // exit 1 is the expected "conflict" outcome we are here to resolve; anything else is a real
+  // failure of the merge machinery.
+  if (merged.status !== 0 && merged.status !== 1) throw gitFailed(dir, mergeArgs, merged);
+
+  await runEntriesInWorktree({ dir, job, base, entries, log, signal, label: 'regenerate', conflicts });
+
+  // The merge already staged the result in the train worktree's own index, so the tree is simply
+  // what that index says; the commit object is built with `commit-tree` (no hooks, no identity).
+  const tree = git(dir, ['write-tree']).trim();
+  const train = commitTree(dir, tree, [base, job.tip], trainMessage(job));
+  if (log) fs.appendFileSync(log, `[regenerate] committed ${train} (tree ${tree})\n`);
+  return { kind: 'train', base, tree, train, conflicts: [], regenerated: conflicts };
+}
+
+// D-2: the refresh pass. Unlike `regenerate`, a refresh entry runs on EVERY non-unchanged train, not
+// only on a conflict: a tree-derived pin (the closure policy's `sourceBindings` digests) is stale the
+// moment either side touches a bound source, and there is no textual conflict to notice it.
+//
+// The worktree is materialized at the ALREADY-BUILT train commit (`built.train`) — no merge, no
+// `--no-ff` — because the train already contains both sides. The train commit is remade with plumbing
+// only when an owned path actually changed, so a refresh that changes nothing leaves the merge-tree
+// train byte-for-byte as it was and D-3's cache key, `job.tree` and the CAS all still describe the
+// tree the gate approved.
+async function refreshTrain({ cwd, dir, job, built, entries, log, signal }) {
+  addTrainWorktree(cwd, dir, built.train, job.id);
+  const changed = await runEntriesInWorktree({ dir, job, base: built.base, entries, log, signal, label: 'refresh', conflicts: [] });
+
+  const staged = runGitRaw(dir, ['diff', '--cached', '--quiet']);
+  // 0 = the index still matches `built.train`'s tree: the entries were a no-op, so there is nothing
+  // to commit and the merge-tree train stands as it was. 1 = something is staged, which is the
+  // normal "a digest was stale" case.
+  if (staged.status !== 0 && staged.status !== 1) throw gitFailed(dir, ['diff', '--cached', '--quiet'], staged);
+  if (staged.status === 0) {
+    if (log) fs.appendFileSync(log, `[refresh] no owned path changed (${entries.length} entry/entries); train ${built.train} unchanged\n`);
+    return { ...built, refreshed: [] };
+  }
+
+  const tree = git(dir, ['write-tree']).trim();
+  const train = commitTree(dir, tree, [built.base, job.tip], trainMessage(job));
+  if (log) fs.appendFileSync(log, `[refresh] committed ${train} (tree ${tree})\n`);
+  return { kind: 'train', base: built.base, tree, train, conflicts: [], refreshed: changed };
+}
+
+// --- D-6/D-7: the base rerun (§9 S-11, WP-2) ----------------------------------------------------
+
+// The exact shapes `bash bin/test-gate.sh` prints on failure, read from the real landing logs
+// (<repo>/.git/landing/logs/ — job 01m60h92c4ntd29g line 257072, job
+// 01m60zmdj2e1tczj lines 3155 and 5970):
+//
+//   [test-suite] FAILED (1 file(s)):
+//     - tests-integration/host-socket-protocol.test.js: terminal attempt failed (EXIT-HANG …)
+//   # [run-hermetic] FAILED (2 file(s)):
+//   #   - tests/x.test.js: terminal attempt failed
+//   [lint-parallel] FAIL node ../bin/test-timing-lint.js --project-root . --baseline …
+//
+// The block body is `- <path>: <reason>` rows (bin/test-runner-adapter.js:921-944) and the `# `
+// prefix appears when the gate relays another runner's stdout; both are accepted. A path is kept
+// only when it really ends in `.test.js`, so a `[test-gate] FAIL  ctm-changed (exit 1, …)` phase
+// line or a `[test-suite] FAIL (introduced 1, pre-existing 0)` attribution line is never mistaken
+// for a file.
+//
+// A row's path is relative to the RUNNER's cwd, not the repository root: bin/test-gate.sh:1238/1242
+// invokes each project's runner as `cd <project> && node <runner> <files>`, so the real rows above
+// read `tests-integration/host-socket-protocol.test.js`, not `coding-task-manager/...`. The block's
+// label is what says which project that was (bin/test-runner-adapter.js:850 — `test-suite` is ctm,
+// `run-hermetic` is wall-e), so it is what turns a row back into a repo-root-relative path; a path
+// that already carries a project directory is never prefixed twice, and a label with no project
+// (a root phase, which already runs from the repository root) is left alone. Anything the parser
+// cannot place is still returned — `rerunOnBase` resolves it against the base tree and skips what
+// it cannot find. Order is log order with duplicates dropped. `lint` is true when a
+// `[lint-parallel] FAIL` line is present (bin/lint-parallel.js:561) — lint failures are deterministic
+// on the train tree and are never rerun on base (§5 D-6).
+const FAILED_BLOCK = /^\s*#?\s*\[([\w-]+)\]\s+FAILED\s+\(\d+\s+file\(s\)\):\s*$/;
+const FAILED_ROW = /^\s*#?\s*[-*]\s*(\S+\.test\.js)\s*(?::|$)/;
+const FAIL_LINE = /^\s*#?\s*\[([\w-]+)\]\s+FAIL\s+(\S+\.test\.js)\s*$/;
+const LINT_FAIL = /^\s*#?\s*\[lint-parallel\]\s+FAIL\b/;
+// The runner labels whose paths are relative to a project directory, and that directory.
+const LABEL_PROJECTS = Object.freeze({ 'test-suite': 'coding-task-manager', 'run-hermetic': 'wall-e' });
+const PROJECT_DIRS = Object.freeze(['coding-task-manager', 'wall-e']);
+
+function normalizeTestPath(raw, label) {
+  let file = String(raw).trim().replace(/^["']+|["']+$/g, '').replace(/\\/g, '/');
+  while (file.startsWith('./')) file = file.slice(2);
+  const project = LABEL_PROJECTS[label];
+  if (project && !PROJECT_DIRS.some((dir) => file === dir || file.startsWith(`${dir}/`))) {
+    file = `${project}/${file}`;
+  }
+  return file;
+}
+
+// Returns `{ tests, lint, raw, sawBlock }`: `tests` are repo-root-relative (see above), `raw` the
+// same files exactly as the log printed them (what the gate-once merge-delta shadow compares against
+// its selection S — `merge-delta.failingFiles` is a wrapper over this parser so the runner's log
+// format is read in ONE place), and `sawBlock` whether any `FAILED (N file(s)):` block was present
+// at all (no block = "cannot say", never "nothing failed").
+function failedFilesFromLog(logText) {
+  const tests = [];
+  const raw = [];
+  const seen = new Set();
+  const seenRaw = new Set();
+  let lint = false;
+  let sawBlock = false;
+  let blockLabel = null;
+  const collect = (rawFile, label) => {
+    const printed = String(rawFile).trim();
+    if (printed && !seenRaw.has(printed)) { seenRaw.add(printed); raw.push(printed); }
+    const file = normalizeTestPath(rawFile, label);
+    if (!file || seen.has(file)) return;
+    seen.add(file);
+    tests.push(file);
+  };
+  for (const line of String(logText === undefined || logText === null ? '' : logText).split('\n')) {
+    if (!lint && LINT_FAIL.test(line)) lint = true;
+    if (blockLabel !== null) {
+      const row = FAILED_ROW.exec(line);
+      if (row) {
+        collect(row[1], blockLabel);
+        continue;
+      }
+      // A blank line or anything that is not another `- path` row ends the block.
+      blockLabel = null;
+    }
+    const block = FAILED_BLOCK.exec(line);
+    if (block) {
+      blockLabel = block[1];
+      sawBlock = true;
+      continue;
+    }
+    const failed = FAIL_LINE.exec(line);
+    if (failed) collect(failed[2], failed[1]);
+  }
+  return { tests, lint, raw, sawBlock };
+}
+
+// The launchers a failed file can belong to, in a fixed order so a rerun is deterministic. A file is
+// routed by its repo-root-relative prefix: `coding-task-manager/` and `wall-e/` are the two projects
+// with their own runner (bin/test-gate.sh:1238/1242 invokes each as
+// `cd <project> && node <runner> <project-relative files>`), and everything else is a root test run
+// through the slot broker. `dir` is where the launcher runs, relative to the base worktree; `argv`
+// builds its command line from project-relative files.
+const RERUN_LAUNCHERS = Object.freeze([
+  { id: 'coding-task-manager', dir: 'coding-task-manager', argv: (files) => ['bin/run-test-suite.js', ...files] },
+  { id: 'wall-e', dir: 'wall-e', argv: (files) => ['tests/run-hermetic.js', ...files] },
+  { id: 'root', dir: null, argv: (files) => ['bin/with-test-slots.js', '--', 'node', '--test', ...files] },
+]);
+
+function launcherFor(file) {
+  for (const launcher of RERUN_LAUNCHERS) {
+    if (launcher.dir && file.startsWith(`${launcher.dir}/`)) {
+      return { launcher, file: file.slice(launcher.dir.length + 1) };
+    }
+  }
+  return { launcher: RERUN_LAUNCHERS[RERUN_LAUNCHERS.length - 1], file };
+}
+
+// A single-quoted POSIX word: the launcher command goes through `/bin/sh -c` (`runShell`), so a path
+// with a space or a quote in it has to survive the shell.
+function shQuote(value) {
+  return `'${String(value).replace(/'/g, "'\\''")}'`;
+}
+
+// The base worktree lives beside the gate's own train worktree, in the same trains root, so both are
+// created and reaped by the same helpers and neither can be mistaken for somebody's checkout.
+function baseWorktreeDir(cwd, jobId) {
+  return path.join(trainsRoot(cwd, commonDir(cwd)).dir, `land-${jobId}-base`);
+}
+
+// D-6/D-7: rerun the files a FAILING train named on the BASE commit — Chromium's with-patch /
+// without-patch rule: a failure that reproduces WITHOUT the branch is not the branch's failure.
+//
+// The rerun happens in a second worktree at `base` (same trains root and same cache symlinks as the
+// gate's own), removed in the `finally` exactly like the gate's. Each project's launcher runs ONCE
+// with only its own files, and a file counts as `failedOnBase` only when its launcher exits non-zero
+// AND names that file through the same FAILED-block shape the gate prints — an exit code alone is
+// not evidence about a specific file. A file that does not EXIST on base (a test the branch added)
+// cannot be base-broken and is skipped, as is one whose launcher cannot run at all.
+//
+// The rerun output is appended to the job's gate log under a `[triage] rerun on base <sha12>` header,
+// so one file holds both runs and `land inspect <job>` shows the whole diagnosis.
+//
+// `signal` is the job's AbortSignal: an abort stops the loop and returns what ran so far with
+// `aborted: true` — the runner is being stopped, and a stopped diagnosis is never a verdict.
+async function rerunOnBase(cwd, { base, files, root, jobId, signal, env, cachePaths = [], timeoutMs } = {}) {
+  const started = Date.now();
+  const ranFiles = [];
+  const named = new Set();
+  const dir = baseWorktreeDir(cwd, jobId);
+  const logFile = path.join(root, 'logs', `${jobId}.log`);
+  const scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'land-triage-'));
+  let aborted = false;
+  try {
+    fs.mkdirSync(path.dirname(logFile), { recursive: true });
+    fs.appendFileSync(logFile, `\n[triage] rerun on base ${String(base).slice(0, 12)}\n`);
+    addTrainWorktree(cwd, dir, base, jobId);
+    linkCachePaths(dir, cwd, cachePaths);
+
+    // Group by launcher in RERUN_LAUNCHERS order so the log reads the same way every time.
+    const groups = [];
+    for (const file of files) {
+      if (!fs.existsSync(path.join(dir, file))) continue; // added by the branch: base cannot be broken by it
+      const routed = launcherFor(file);
+      let group = groups.find((candidate) => candidate.id === routed.launcher.id);
+      if (!group) {
+        group = { id: routed.launcher.id, launcher: routed.launcher, files: [] };
+        groups.push(group);
+      }
+      group.files.push(routed.file);
+      ranFiles.push(file);
+    }
+    const rank = (group) => RERUN_LAUNCHERS.findIndex((launcher) => launcher.id === group.id);
+    groups.sort((a, b) => rank(a) - rank(b));
+
+    for (const group of groups) {
+      if (signal && signal.aborted) {
+        aborted = true;
+        break;
+      }
+      const groupCwd = group.launcher.dir ? path.join(dir, group.launcher.dir) : dir;
+      const command = ['node', ...group.launcher.argv(group.files)].map(shQuote).join(' ');
+      fs.appendFileSync(logFile, `$ (cd ${group.launcher.dir || '.'} && ${command})\n`);
+      const outFile = path.join(scratch, `${group.id}.out`);
+      const outFd = fs.openSync(outFile, 'a');
+      let res;
+      try {
+        // eslint-disable-next-line no-await-in-loop -- launchers share the machine and run one at a time
+        res = await runShell(command, {
+          cwd: groupCwd,
+          extra: { ...(env || {}), LAND_JOB: jobId, LAND_BASE: base, LAND_TRIAGE: 'base' },
+          logFd: outFd,
+          // Bounded like the gate itself (the caller passes the gate's own timeout): a hanging test on
+          // base must not hold the runner lease past what the gate it is diagnosing was allowed.
+          timeoutMs,
+          signal,
+        });
+      } finally {
+        fs.closeSync(outFd);
+      }
+      const output = fs.readFileSync(outFile, 'utf8');
+      fs.appendFileSync(logFile, output);
+      if (res.aborted) {
+        aborted = true;
+        break;
+      }
+      if (res.status === 0 || res.error) continue; // a launcher that cannot run proves nothing about base
+      const parsed = failedFilesFromLog(output);
+      for (const entry of parsed.tests) {
+        const file = group.launcher.dir && entry.startsWith(`${group.launcher.dir}/`)
+          ? entry.slice(group.launcher.dir.length + 1)
+          : entry;
+        if (group.files.includes(file)) named.add(file);
+      }
+    }
+  } finally {
+    removeTrainWorktree(cwd, dir);
+    fs.rmSync(scratch, { recursive: true, force: true });
+  }
+  const failedOnBase = files.filter((file) => {
+    const routed = launcherFor(file);
+    return named.has(routed.file) && ranFiles.includes(file);
+  });
+  return {
+    ranFiles,
+    failedOnBase,
+    aborted,
+    seconds: Number(((Date.now() - started) / 1000).toFixed(3)),
+    logPath: logFile,
+  };
+}
+
+module.exports = {
+  MAX_ROUNDS,
+  GATE_KILL_GRACE_MS,
+  killGroup,
+  runShell,
+  targetRef,
+  globToRegExp,
+  globMatch,
+  matchingRegenerateEntries,
+  matchingRefreshEntries,
+  trainMessage,
+  buildTrain,
+  buildBatchTrain,
+  trainsRoot,
+  trainDirFor,
+  prepareTrainDir,
+  addTrainWorktree,
+  removeTrainWorktree,
+  worktreeList,
+  targetWorktreeFor,
+  commitsBetween,
+  mergeBase,
+  landTrain,
+  changedFilesBetween,
+  hunkHeaders,
+  overlapWithTarget,
+  regenerateTrain,
+  refreshTrain,
+  linkCachePaths,
+  failedFilesFromLog,
+  launcherFor,
+  shQuote,
+  baseWorktreeDir,
+  rerunOnBase,
+};