create-walle 0.10.1 → 0.10.3

package/template/coding-task-manager/lib/landing/ctm-view.js

@@ -0,0 +1,256 @@
+'use strict';
+
+// WP-3a (docs/local-landing-queue-multi-session-integration-2026-10-26.html §6.3): the CTM side of
+// the landing queue is a PURE VIEW over the `land` CLI's own `--json` payload. Nothing here reads a
+// file, spawns a process, or talks to the network: the CLI is the single source of truth (§5 D-1),
+// the server only reshapes what `land status --json [--radar-for a,b]` printed.
+//
+// Two shapes live here:
+//
+//   landingForSession(statusPayload, { sessionId, branch, sessionsByBranch })
+//     -> the per-session `workspaceTracking.landing` object (§6.3), or `null` when the repository
+//        has nothing to say about this branch at all.
+//        { jobId, state, position, total, eta_s, conflictPreview, radar: { max, with: [...] } }
+//        `conflictPreview` is `null` or `{ paths }` — D-5's "this job will not merge as it stands,
+//        merge <target> now", read straight off the job record the CLI wrote.
+//
+//   landingStatusForRepo(statusPayload, sessions)
+//     -> the `GET /api/landing/status` body: { queue, runner, jobs, radar, forSession }
+//
+// Reading rules, stated once so the CLI and the view cannot drift:
+//   * `queue.order` is the priority-sorted list of non-terminal job ids — the only position
+//     authority (in_progress first, then priority descending, then arrival; the CLI sorts it).
+//   * `jobs[]` is chronological (newest last), so "newest" is a comparison, never an array index.
+//   * A TERMINAL job is only worth showing for 2 h (the session has moved on long before that).
+//   * `radar.pairs` only exists when the caller probed with `--radar-for`; without it the radar is
+//     a cache-only summary and there is no per-branch pair data to join.
+//   * `unknown` is NOT a level: a pair this sweep did not look at never produces a claim.
+
+const TERMINAL_STATES = Object.freeze(['landed', 'failed', 'blocked', 'canceled']);
+// §6.3: the echo of a finished job lasts two hours.
+const TERMINAL_WINDOW_MS = 2 * 60 * 60 * 1000;
+const LEVELS = Object.freeze(['L0', 'L1', 'L1*', 'L2', 'L3']);
+// The `with` list is about pairs a reader must actually look at: L1 (a shared changed file) and up.
+const L1_RANK = LEVELS.indexOf('L1');
+
+function levelRank(level) {
+  if (level === 'unknown') return -1;
+  const index = LEVELS.indexOf(level);
+  return index === -1 ? 0 : index;
+}
+
+function nowMsOf(options) {
+  const value = options && options.now;
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (value instanceof Date) return value.getTime();
+  return Date.now();
+}
+
+// Tolerant readers: a payload the CLI wrote is trusted, but a partial/older one must degrade to
+// "nothing to say" rather than throw inside a broadcast.
+function readStatus(statusPayload) {
+  const payload = statusPayload && typeof statusPayload === 'object' ? statusPayload : {};
+  const rawQueue = payload.queue && typeof payload.queue === 'object' ? payload.queue : {};
+  const order = Array.isArray(rawQueue.order)
+    ? rawQueue.order.filter((id) => typeof id === 'string' && id)
+    : [];
+  const jobs = Array.isArray(payload.jobs) ? payload.jobs.filter((job) => job && typeof job === 'object') : [];
+  const radar = payload.radar && typeof payload.radar === 'object' ? payload.radar : {};
+  const pairs = Array.isArray(radar.pairs) ? radar.pairs.filter((pair) => pair && typeof pair === 'object') : [];
+  return {
+    target: typeof payload.target === 'string' && payload.target ? payload.target : null,
+    runner: payload.runner && typeof payload.runner === 'object' ? payload.runner : null,
+    order,
+    jobs,
+    pairs,
+  };
+}
+
+// The last timestamp a job ever recorded, as epoch ms — the only ordering key that survives the
+// CLI's 50-job window. An unparseable/absent timestamps object sorts last (never ahead of a dated
+// job), which is exactly the degradation a job file torn mid-write deserves.
+function jobTimeMs(job) {
+  const timestamps = job && job.timestamps && typeof job.timestamps === 'object' ? job.timestamps : {};
+  for (const key of ['landed', 'canceled', 'gated', 'started', 'queued']) {
+    const parsed = Date.parse(timestamps[key]);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return null;
+}
+
+function newerJob(candidate, current) {
+  if (!current) return candidate;
+  const left = jobTimeMs(candidate);
+  const right = jobTimeMs(current);
+  if (left === null) return right === null ? current : current;
+  if (right === null) return candidate;
+  if (left !== right) return left > right ? candidate : current;
+  return String(candidate.id || '') >= String(current.id || '') ? candidate : current;
+}
+
+// §6.3/D-10: the job this session should see. A job still in the queue wins outright; a finished one
+// is echoed for TERMINAL_WINDOW_MS. "The session's branch" is the qualification for BOTH - a landing
+// on someone else's branch is not this session's news.
+function pickJob(jobs, branch, nowMs) {
+  let active = null;
+  let recent = null;
+  for (const job of jobs) {
+    if (job.branch !== branch) continue;
+    if (TERMINAL_STATES.includes(job.state)) {
+      const at = jobTimeMs(job);
+      if (at === null || nowMs - at > TERMINAL_WINDOW_MS) continue;
+      recent = newerJob(job, recent);
+      continue;
+    }
+    active = newerJob(job, active);
+  }
+  return active || recent;
+}
+
+function sessionIdsFor(sessionsByBranch, branch) {
+  const entry = sessionsByBranch && typeof sessionsByBranch === 'object' ? sessionsByBranch[branch] : null;
+  if (!Array.isArray(entry)) return [];
+  return entry.filter((id) => typeof id === 'string' && id);
+}
+
+// D-5 (§6 job record): `conflictPreview` is either `null` or `{ base, paths, checkedAt }`. The chip
+// only ever needs the paths, and a record torn mid-write (or written by an older CLI) degrades to
+// `null` rather than throwing inside a broadcast — the same tolerant-reader rule as `readStatus`.
+function readConflictPreview(job) {
+  const preview = job && job.conflictPreview;
+  if (!preview || typeof preview !== 'object') return null;
+  const paths = Array.isArray(preview.paths) ? preview.paths.filter((file) => typeof file === 'string' && file) : [];
+  return paths.length ? { paths } : null;
+}
+
+// WP-1 D-1 (§6 job record): `batch` is either `null` or `{ id, members, attempt, index }`. The view
+// carries it through for a reader that wants it, degrading to `null` for a record torn mid-write or
+// written by an older CLI — the same tolerant-reader rule as `readConflictPreview`.
+function readBatch(job) {
+  const batch = job && job.batch;
+  if (!batch || typeof batch !== 'object' || typeof batch.id !== 'string') return null;
+  const members = Array.isArray(batch.members) ? batch.members.filter((id) => typeof id === 'string' && id) : [];
+  return {
+    id: batch.id,
+    members,
+    attempt: Number.isInteger(batch.attempt) ? batch.attempt : null,
+    index: Number.isInteger(batch.index) ? batch.index : null,
+  };
+}
+
+function higherLevel(left, right) {
+  if (left === null || left === undefined) return right === null || right === undefined ? null : right;
+  if (right === null || right === undefined) return left;
+  return levelRank(right) > levelRank(left) ? right : left;
+}
+
+/**
+ * The per-session view (§6.3). `sessionId` is the CALLER's CTM session id (excluded from `with`);
+ * `sessionsByBranch` maps a branch name to the CTM session ids currently on it, so a pair between
+ * two branches becomes a pair between two sessions - which is what the chip renders.
+ */
+function landingForSession(statusPayload, options = {}) {
+  const status = readStatus(statusPayload);
+  const sessionId = options.sessionId === undefined || options.sessionId === null ? null : String(options.sessionId);
+  const branch = typeof options.branch === 'string' && options.branch ? options.branch : null;
+  const sessionsByBranch = options.sessionsByBranch && typeof options.sessionsByBranch === 'object'
+    ? options.sessionsByBranch
+    : {};
+  if (!branch) return null;
+
+  const job = pickJob(status.jobs, branch, nowMsOf(options));
+
+  const with_ = [];
+  let max = null;
+  let conflicts = 0;
+  for (const pair of status.pairs) {
+    const other = pair.a === branch ? pair.b : (pair.b === branch ? pair.a : null);
+    if (other === null || other === branch || typeof other !== 'string') continue;
+    const rank = levelRank(pair.level);
+    // `unknown` (rank -1) is "this sweep did not look", never a claim about the pair.
+    if (rank < 0) continue;
+    const isTarget = status.target !== null && other === status.target;
+    if (rank >= L1_RANK) {
+      conflicts += 1;
+      for (const id of sessionIdsFor(sessionsByBranch, other)) {
+        if (sessionId !== null && id === sessionId) continue;
+        with_.push({ session: id, branch: other, level: pair.level });
+      }
+    }
+    // "max over those pairs and the target pair": the target pair counts at ANY level, because
+    // "my branch has not moved relative to main" is itself the answer to the chip's question.
+    if (isTarget) max = higherLevel(max, pair.level);
+  }
+  for (const entry of with_) max = higherLevel(max, entry.level);
+
+  with_.sort((left, right) => (levelRank(right.level) - levelRank(left.level))
+    || left.branch.localeCompare(right.branch)
+    || left.session.localeCompare(right.session));
+
+  const hasJobs = status.jobs.length > 0;
+  const hasQueue = status.order.length > 0;
+  // "the repo has nothing to say": no jobs, no queue, and no pair involving this branch at L1+.
+  if (!hasJobs && !hasQueue && conflicts === 0) return null;
+
+  const index = job ? status.order.indexOf(job.id) : -1;
+  return {
+    jobId: job ? job.id : null,
+    state: job ? job.state : null,
+    position: index === -1 ? null : index + 1,
+    total: status.order.length,
+    eta_s: job && Number.isFinite(job.eta_s) ? job.eta_s : null,
+    conflictPreview: readConflictPreview(job),
+    // WP-1 (§9 S-15): the batch this job is being gated in, for a reader that wants it. No UI here.
+    batch: readBatch(job),
+    radar: { max, with: with_ },
+  };
+}
+
+/**
+ * The `GET /api/landing/status` body (§6.3): the repository's own read model, plus a
+ * `forSession` map so one request answers both "what is this repo's queue" and "what does MY
+ * session see". A session with nothing to show is simply absent from the map.
+ */
+function landingStatusForRepo(statusPayload, sessions, options = {}) {
+  const status = readStatus(statusPayload);
+  const list = (Array.isArray(sessions) ? sessions : [])
+    .filter((session) => session && session.id !== undefined && session.id !== null)
+    .map((session) => ({ id: String(session.id), branch: typeof session.branch === 'string' ? session.branch : null }));
+
+  const sessionsByBranch = {};
+  for (const session of list) {
+    if (!session.branch) continue;
+    if (!sessionsByBranch[session.branch]) sessionsByBranch[session.branch] = [];
+    sessionsByBranch[session.branch].push(session.id);
+  }
+
+  const forSession = {};
+  for (const session of list) {
+    const view = landingForSession(statusPayload, {
+      sessionId: session.id,
+      branch: session.branch,
+      sessionsByBranch,
+      now: options.now,
+    });
+    if (view) forSession[session.id] = view;
+  }
+
+  return {
+    queue: { depth: status.order.length, order: status.order.slice() },
+    runner: status.runner,
+    jobs: status.jobs,
+    radar: statusPayload && typeof statusPayload === 'object' && statusPayload.radar
+      ? statusPayload.radar
+      : { max: null, atLeastL2: null, unknown: null },
+    forSession,
+  };
+}
+
+module.exports = {
+  TERMINAL_STATES,
+  TERMINAL_WINDOW_MS,
+  LEVELS,
+  levelRank,
+  landingForSession,
+  landingStatusForRepo,
+};

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

@@ -0,0 +1,360 @@
+'use strict';
+// WP-1 (docs/local-landing-queue-multi-session-integration-2026-10-26.html §5 D-4, §6.3, §11 Risks,
+// §8 WP-1): the train gate and its tree-keyed verdict cache.
+//
+// D-4: the gate runs ONCE, on the train commit, in a locked detached worktree that the queue owns
+// (`<repo>/.worktrees/land-<jobId>` when that lives inside the repository and is ignored, else
+// `<common-dir>/landing/trains/<jobId>`), with `landing.cachePaths` symlinked in and the §4 GIT_*
+// list scrubbed from the child env. A gate that leaves the worktree changed is a FAIL
+// (`gate_dirtied_tree`) — a gate is a read-only observer of the tree it is given.
+//
+// The verdict is cached by (train tree oid, sha256 of the gates array) at
+// `landing/verdicts/<tree>.json`, so re-landing the same tree after a `target_dirty` block costs no
+// gate run at all (AC-1e). The queue never reruns a failed gate by itself.
+
+const fs = require('fs');
+const path = require('path');
+
+const state = require('./state');
+const { runGitRaw } = require('./git');
+const { gatesHash } = require('./config');
+const train = require('./train');
+
+function verdictFile(root, tree) {
+  return path.join(root, 'verdicts', `${tree}.json`);
+}
+
+// A cached verdict is reusable only when the gates array is byte-identical in meaning (same hash)
+// AND the recorded verdict is a PASS. A cached FAIL is evidence, never a decision: replaying it
+// would make a tree permanently unlandable after one flake, with no way to retry it short of
+// editing the verdict store by hand. FAIL records are still written (see `runGate`).
+function readCachedVerdict(root, tree, hash) {
+  if (!tree || !hash) return null;
+  const raw = state.readJsonSafe(verdictFile(root, tree));
+  if (!raw) return null;
+  if (raw.gatesHash !== hash) return null;
+  if (raw.verdict !== 'PASS') return null;
+  return raw;
+}
+
+function recordVerdict(root, entry) {
+  state.writeJsonAtomic(verdictFile(root, entry.tree), { contract: state.CONTRACT, ...entry });
+  return verdictFile(root, entry.tree);
+}
+
+// `landing.cachePaths` are validated to be git-ignored in the config directory, but a train tree is
+// the target's content, not the config directory's, so the exclusion is written into the train
+// worktree's own `info/exclude` as well — and, as the authority, applied as a path filter on the
+// post-gate status (see `cacheDirt`).
+function excludeCachePaths(dir, cachePaths) {
+  if (!cachePaths.length) return null;
+  const res = runGitRaw(dir, ['rev-parse', '--path-format=absolute', '--git-path', 'info/exclude']);
+  if (res.status !== 0) return null;
+  const file = res.stdout.trim();
+  const lines = cachePaths.flatMap((rel) => [`/${rel}`, `/${rel.replace(/\/+$/, '')}/`]);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  let existing = '';
+  try {
+    existing = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    /* expected: the worktree's info/exclude has never been written — start from empty */
+    existing = '';
+  }
+  const have = new Set(existing.split('\n'));
+  const missing = lines.filter((line) => !have.has(line));
+  if (missing.length) fs.appendFileSync(file, `${existing && !existing.endsWith('\n') ? '\n' : ''}${missing.join('\n')}\n`);
+  return file;
+}
+
+function isUnderCachePath(file, cachePaths) {
+  return cachePaths.some((rel) => {
+    const clean = rel.replace(/\/+$/, '');
+    return clean !== '' && (file === clean || file.startsWith(`${clean}/`));
+  });
+}
+
+// Everything `git status --porcelain` reports about the train worktree EXCEPT the cache paths we
+// linked in ourselves. Non-empty means the gate dirtied the tree.
+function cacheDirt(dir, cachePaths) {
+  const res = runGitRaw(dir, ['status', '--porcelain']);
+  if (res.status !== 0) return [`status_failed: ${String(res.stderr || '').trim()}`];
+  return res.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) => !isUnderCachePath(file, cachePaths));
+}
+
+// WP-2 (docs/shared-memory-join-followups-2026-10-31.html §5 R-8..R-10, §6, §8 WP-2, §9 I-5): a dirt
+// verdict is an OBSERVATION, so the log has to say what was actually left behind. Observed once in 41
+// landing logs: git 2.52 killed by a signal while an external merge driver ran left its three
+// `.merge_file_XXXXXX` (%O/%A/%B) temps in the train worktree top — created with `xmkstemp` relative to
+// git's working directory and unlinked only on a normal return (merge-ll.c) — and the log kept only the
+// names. Those files name the ledger being merged and their mtime places the merge inside or outside the
+// gate's own run; this is the instrumentation that makes the next occurrence diagnosable.
+//
+// Nothing here changes the outcome: the dirt is still a FAIL (`gate_dirtied_tree`), the files are still
+// neither deleted nor filtered out of `cacheDirt` (a sweep would hide the evidence, §3 anti-goal).
+const DIRT_EVIDENCE_MAX_PATHS = 20;
+const DIRT_HEAD_BYTES = 160;
+// git's own spelling of the merge-driver temporaries (`xmkstemp(".merge_file_XXXXXX")`, merge-ll.c):
+// six alphanumerics, in the worktree top. Only a basename matching this gets any content recorded.
+const MERGE_FILE_RE = /^\.merge_file_[A-Za-z0-9]{6}$/;
+
+function statKind(stat) {
+  if (stat.isFile()) return 'file';
+  if (stat.isDirectory()) return 'dir';
+  if (stat.isSymbolicLink()) return 'symlink';
+  return 'other';
+}
+
+// The content HEAD of a merge-driver temporary, and only its head: the file is a %O/%A/%B blob whose
+// first bytes name the ledger being merged. Opened/read/closed rather than `readFileSync` so a 1 GB
+// stray costs DIRT_HEAD_BYTES, and decoded as UTF-8 so `JSON.stringify` escapes whatever control bytes
+// the blob contains. `undefined` means "no content to report" — never a throw.
+function readDirtHead(full) {
+  let fd = null;
+  try {
+    fd = fs.openSync(full, 'r');
+    const buf = Buffer.alloc(DIRT_HEAD_BYTES);
+    const read = fs.readSync(fd, buf, 0, DIRT_HEAD_BYTES, 0);
+    return buf.subarray(0, read).toString('utf8');
+  } catch (error) {
+    /* expected: the path went away (or is unreadable) between the status and this open — no head is a complete answer (HANDLE: report nothing rather than throw) */
+    return undefined;
+  } finally {
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch (error) {
+        /* expected: EBADF — the fd is already closed and nothing is left to release (HANDLE: ignore) */
+      }
+    }
+  }
+}
+
+// One `[gate] dirt:` record for one path `cacheDirt` reported. NEVER throws: this runs while the gate
+// result is already a FAIL, and an exception here would replace `gate_dirtied_tree` with a crash inside
+// the one log line that exists to explain it. `cacheDirt`'s own `status_failed: <stderr>` sentinel is
+// passed through as its own kind rather than lstat'ed — it is not a path.
+function dirtEvidence(dir, relPath) {
+  if (String(relPath).startsWith('status_failed:')) return { path: relPath, kind: 'status_failed' };
+  let stat;
+  try {
+    stat = fs.lstatSync(path.join(dir, relPath));
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return { path: relPath, kind: 'missing' };
+    /* expected: any other lstat failure (EACCES, ELOOP, a vanished parent) is reported, not fatal (HANDLE: the code is the evidence) */
+    return {
+      path: relPath,
+      kind: 'error',
+      code: error && error.code ? error.code : String((error && error.message) || error),
+    };
+  }
+  const kind = statKind(stat);
+  const evidence = {
+    path: relPath,
+    kind,
+    size: stat.size,
+    mtime: stat.mtime.toISOString(),
+    birthtime: stat.birthtime.toISOString(),
+  };
+  if (kind === 'file' && MERGE_FILE_RE.test(path.basename(relPath))) {
+    const head = readDirtHead(path.join(dir, relPath));
+    if (head !== undefined) evidence.head = head;
+  }
+  return evidence;
+}
+
+// R-9 then R-8: the window first (so an mtime can be placed against the gate's own run), then at most
+// DIRT_EVIDENCE_MAX_PATHS records, then one line naming how many were not shown — a path count is not
+// evidence, and a dirt of ten thousand paths must not fill the job log.
+function writeDirtEvidence(write, dir, paths) {
+  const shown = paths.slice(0, DIRT_EVIDENCE_MAX_PATHS);
+  for (const relPath of shown) write(`[gate] dirt: ${JSON.stringify(dirtEvidence(dir, relPath))}`);
+  if (paths.length > shown.length) write(`[gate] dirt: … ${paths.length - shown.length} more`);
+}
+
+function linkCachePaths(dir, sourceDir, cachePaths) {
+  // WP-2 (§5 D-6): the base rerun materializes its own worktree and needs exactly the same cache
+  // symlinks, so the implementation lives in `train.js` (which `gate.js` already depends on, and
+  // the reverse dependency would be a cycle) and this is the one spelling of it.
+  return train.linkCachePaths(dir, sourceDir, cachePaths);
+}
+
+// D-6 (§9 S-10, WP-2): the test files a FAILING gate log names, and whether the failure is a lint
+// one. The runner reruns these on the base commit to separate a broken main from a broken branch.
+// The parser itself lives in `train.js` beside the base rerun that consumes it (this module already
+// requires `train.js`, so the dependency cannot be reversed) and is re-exported here, next to the
+// gate whose log format it reads.
+const { failedFilesFromLog } = train;
+
+// D-4. Returns `{ verdict, reason, seconds, dirtyPaths, logPath, hash, selection, shadow }`;
+// `verdict` is 'PASS' or 'FAIL', `reason` is null on PASS, `selection` is the WP-0 `--selection-out`
+// object (null when the gate wrote none or wrote something unparseable), and `shadow` is the WP-3a
+// merge-delta measurement (§6.5, null when the runner asked for none). Async because gates are: the
+// runner must stay responsive (the lease heartbeat is an interval) and gate output goes straight
+// into the job log file.
+//
+// WP-2 (§5 D-5, D-6): `ctx.signal` is the job's AbortSignal. An aborted entry stops the loop with
+// `reason: 'gate_stopped'`, skips the dirt check and records NO verdict — only PASS is ever
+// replayed, so a recorded FAIL would sit there as a real failure the `land inspect` reader would
+// report, and a stopped gate is not a failure. The train worktree is still removed (the `finally`).
+//
+// WP-3a (§5 D-3, §6.5, §8 WP-3a): `ctx.onTrainReady` is an optional `async (dir) => any` the runner
+// uses to take its SHADOW merge-delta measurement. It is called ONCE, after the train worktree exists
+// and its cache paths are linked, and BEFORE the gates run — so the two planner passes see the tree the
+// gates will see — and its return value comes back as `result.shadow`. A throw is caught and recorded
+// as `{ mode: 'fallback', reason: 'plan_error', detail }`: the measurement is an observation, and no
+// gate might ever be failed, skipped or reordered because of it.
+async function runGate(ctx) {
+  const { cwd, dir, config, job, built, token, root, logFile, sourceDir, signal, onTrainReady } = ctx;
+  // WP-1 §9 S-4: the train id is the batch id for a batch and the job id for a singleton, so every
+  // member of a batch reads the SAME selection record (the gate ran once, on the batch's tree).
+  const trainId = ctx.trainId || job.id;
+  const hash = gatesHash(config.gates);
+  // WP-0 (design doc §5 D-8, §6.1 --selection-out, §6.6, §9 S-8): where the gate writes
+  // its own self-description. Handed to the gate as an env var (`.ctm.json`'s gate
+  // command forwards it as `--selection-out "$LAND_SELECTION_OUT"`), beside
+  // LAND_TRAIN/LAND_BASE. A gate that predates the flag ignores it; a gate that
+  // cannot write it leaves the file absent, which reads as `selection: null`.
+  const selectionFile = path.join(root, 'logs', `${trainId}.selection.json`);
+  // A retrained round (cas_lost) reuses the job id: never let it read the previous round's record.
+  fs.rmSync(selectionFile, { force: true });
+  const started = Date.now();
+  fs.mkdirSync(path.dirname(logFile), { recursive: true });
+  const logFd = fs.openSync(logFile, 'a');
+  const write = (text) => { fs.writeSync(logFd, `${text}\n`); };
+  let reason = null;
+  let dirtyPaths = [];
+  let added = false;
+  let shadow = null;
+  try {
+    write(`[gate] job=${job.id} train=${built.train} base=${built.base} tip=${job.tip} tree=${built.tree}`);
+    train.addTrainWorktree(cwd, dir, built.train, trainId);
+    added = true;
+    const linked = linkCachePaths(dir, sourceDir, config.cachePaths);
+    excludeCachePaths(dir, config.cachePaths);
+    if (linked.length) write(`[cachePaths] ${linked.join(' ')}`);
+
+    // WP-3a (§6.5): the shadow measurement runs here — the tree is materialized and the cache paths
+    // are linked, but no gate has run yet. A throw from it (a git read behind a proof lookup, a planner
+    // that cannot be spawned) is a `plan_error` fallback, never a gate failure.
+    if (typeof onTrainReady === 'function') {
+      try {
+        shadow = await onTrainReady(dir);
+      } catch (error) {
+        shadow = { mode: 'fallback', reason: 'plan_error', detail: error && error.message ? error.message : String(error) };
+      }
+      if (shadow) write(`[merge-delta] shadow ${shadow.mode}${shadow.reason ? ` (${shadow.reason})` : ''}`);
+    }
+
+    for (const entry of config.gates) {
+      write(`$ ${entry.run}`);
+      // Gates run in the configured order and each may depend on the previous one.
+      // eslint-disable-next-line no-await-in-loop
+      const res = await train.runShell(entry.run, {
+        cwd: dir,
+        extra: {
+          LAND_TRAIN: dir,
+          LAND_BASE: built.base,
+          LAND_TIP: job.tip,
+          LAND_JOB: job.id,
+          LAND_TOKEN: token,
+          LAND_SELECTION_OUT: selectionFile,
+        },
+        timeoutMs: Math.round(entry.timeoutSeconds * 1000),
+        logFd,
+        signal,
+      });
+      // D-5/D-6: a stopped gate ends the loop here, with no verdict and no dirt check.
+      if (res.aborted) {
+        write(`[gate] ${entry.name}: stopped`);
+        reason = 'gate_stopped';
+        break;
+      }
+      if (res.timedOut) {
+        write(`[gate] ${entry.name}: timed out after ${entry.timeoutSeconds}s; process group signalled`);
+        reason = 'gate_timeout';
+        break;
+      }
+      if (res.error) {
+        write(`[gate] ${entry.name}: could not be run: ${res.error.message}`);
+        reason = 'gate_spawn_failed';
+        break;
+      }
+      if (res.status !== 0) {
+        write(`[gate] ${entry.name}: exited ${res.status}${res.signal ? ` (${res.signal})` : ''}`);
+        reason = 'gate_failed';
+        break;
+      }
+      write(`[gate] ${entry.name}: ok`);
+    }
+
+    // D-6: a stopped gate is not a verdict. Return before the dirt check and before `recordVerdict`;
+    // the `finally` still removes this job's train worktree.
+    if (reason === 'gate_stopped') {
+      return {
+        verdict: null,
+        reason: 'gate_stopped',
+        seconds: Number(((Date.now() - started) / 1000).toFixed(3)),
+        dirtyPaths: [],
+        logPath: logFile,
+        hash,
+        selection: state.readJsonSafe(selectionFile),
+        shadow,
+      };
+    }
+
+    // D-4: a gate must leave the train worktree unchanged.
+    if (!reason) {
+      dirtyPaths = cacheDirt(dir, config.cachePaths);
+      if (dirtyPaths.length) {
+        write(`[gate] dirtied the train worktree: ${dirtyPaths.join(', ')}`);
+        // WP-2 (§5 R-8/R-9): what was left behind, and when this gate was running while it happened.
+        write(`[gate] window: ${JSON.stringify({ startedAt: new Date(started).toISOString(), finishedAt: new Date().toISOString() })}`);
+        writeDirtEvidence(write, dir, dirtyPaths);
+        reason = 'gate_dirtied_tree';
+      }
+    }
+  } finally {
+    // Only this job's own train directory, created above and owned by this call.
+    if (added) write(`[worktree] ${JSON.stringify(train.removeTrainWorktree(cwd, dir))}`);
+    fs.closeSync(logFd);
+  }
+
+  const seconds = Number(((Date.now() - started) / 1000).toFixed(3));
+  const verdict = reason ? 'FAIL' : 'PASS';
+  recordVerdict(root, {
+    tree: built.tree,
+    verdict,
+    gatesHash: hash,
+    at: new Date().toISOString(),
+    seconds,
+    jobId: job.id,
+    logPath: logFile,
+    reason,
+  });
+  return { verdict, reason, seconds, dirtyPaths, logPath: logFile, hash, selection: state.readJsonSafe(selectionFile), shadow };
+}
+
+module.exports = {
+  verdictFile,
+  readCachedVerdict,
+  recordVerdict,
+  excludeCachePaths,
+  isUnderCachePath,
+  cacheDirt,
+  DIRT_EVIDENCE_MAX_PATHS,
+  DIRT_HEAD_BYTES,
+  dirtEvidence,
+  writeDirtEvidence,
+  linkCachePaths,
+  failedFilesFromLog,
+  runGate,
+};