create-walle 0.10.1 → 0.10.3

package/template/coding-task-manager/bin/land.js

@@ -0,0 +1,2069 @@
+#!/usr/bin/env node
+'use strict';
+// WP-1 (docs/local-landing-queue-multi-session-integration-2026-10-26.html §6.2, §5 D-1..D-11,
+// §8 WP-1): the `land` CLI.
+//
+// One queue per repository, no daemon (D-1/D-2). `land submit` writes a job, then tries to become
+// the runner by claiming the single per-repository lease; a submitter that wins the lease drains the
+// queue before exiting, a submitter that loses it prints `runner: 'other'` and exits in well under a
+// second, spawning nothing. `land run [--once]` is the same loop without a submission, for CTM's
+// button and for cron-less recovery.
+//
+// WP-1 (§7 "Header rule", docs/fleet-origin-main-sync-skill-2026-10-31.html): the queue runs
+// `git push` only for a `publish` job, only to `landing.publish.remote/branch`, only fast-forward.
+// Nothing else here pushes: every other git child is `--no-optional-locks` with the §4 GIT_*
+// list scrubbed (`lib/landing/git.js`), never runs add/commit/checkout/stash outside its own train
+// worktree (D-11), and never merges into a session's worktree.
+//
+// Exit codes (§6.2): 0 ok · 1 typed refusal/failure · 2 usage · 75 timeout.
+
+const fs = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const {
+  landingError,
+  childEnv,
+  toplevel,
+  commonDir,
+  revParse,
+  revParseOrNull,
+  runGitRaw,
+  mergeTree,
+} = require('../lib/landing/git');
+const { intFlag, strFlag } = require('../lib/env-flags');
+const lease = require('../lib/landing/lease');
+const queue = require('../lib/landing/queue');
+const train = require('../lib/landing/train');
+const gate = require('../lib/landing/gate');
+const proof = require('../lib/landing/proof');
+const mergeDelta = require('../lib/landing/merge-delta');
+const batchRunner = require('../lib/landing/batch-runner');
+const stop = require('../lib/landing/stop');
+const radar = require('../lib/landing/radar');
+const sync = require('../lib/landing/sync');
+const syncCli = require('../lib/landing/sync-cli');
+const resolveCli = require('../lib/landing/resolve-cli');
+const { writeJsonAtomic } = require('../lib/landing/state');
+const { loadLandingConfig, loadTargetLandingConfig, resolveMainBranch, gatesHash } = require('../lib/landing/config');
+
+const CONTRACT = 1;
+// `--wait` and `land wait` are bounded (the doc's 4 h); a queue that has not decided by then is a
+// timeout (exit 75), never an endless poll.
+const WAIT_TIMEOUT_MS = 4 * 60 * 60 * 1000;
+const WAIT_TIMEOUT_S = WAIT_TIMEOUT_MS / 1000;
+// Poll the job file at ≤ 1 s (§6.2), never a busy loop.
+const POLL_MS = 200;
+// §6.2 `land cancel --force` on a running job: how long the canceling process waits for the runner
+// to observe the stop request and settle the job. The runner's heartbeat is 10 s and the SIGKILL
+// grace is another 10 s, so 30 s covers the worst case with room to spare — and a runner that never
+// settles is reported (exit 75), never waited on forever.
+const CANCEL_WAIT_MS = 30000;
+const CANCEL_POLL_MS = 250;
+
+// D-10: the marked block written into the repository's agent file. Its content must be exactly
+// `lib/landing/agent-rule.txt` with `<target>` substituted (WP-5's E-4 lint checks byte identity).
+const MARK_BEGIN = '<!-- land:begin -->';
+const MARK_END = '<!-- land:end -->';
+const MARK_RE = /<!-- land:begin -->[\s\S]*?<!-- land:end -->/;
+const AGENT_RULE_FILE = path.join(__dirname, '..', 'lib', 'landing', 'agent-rule.txt');
+const AGENT_FILES = Object.freeze(['CLAUDE.md', 'AGENTS.md']);
+
+const USAGE = [
+  'usage: land <command> [options]',
+  '',
+  '  land init [--guard] [--agent-file CLAUDE.md|AGENTS.md]',
+  '  land guard install',
+  '  land submit [--branch <name>] [--title <text>] [--priority normal|high|urgent] [--reason <text>] [--queue-anyway] [--wait] [--json]',
+  '  land run [--once]',
+  '  land priority <jobId> normal|high|urgent [--reason <text>] [--json]',
+  '  land status [--json] [--repo <path>] [--radar-for <branch>[,<branch>]]',
+  `  land wait <jobId> [--timeout-s ${WAIT_TIMEOUT_S}]`,
+  '  land inspect <jobId>',
+  '  land cancel <jobId> [--force]',
+  '  land conflicts [--with <branch>] [--json]',
+  '  land claim <path>... [--ttl-h 4] [--session <id>] [--json]',
+  '  land unclaim [--session <id>] [--json]',
+  '  land record-proof --tree <oid> --plan-base <rev> --log <path> --seconds <n> [--selection <json-file>] [--commit <sha>] [--json]',
+  '  land report merge-delta [--json]',
+  '  land sync [--wait] [--pull-only] [--json]',
+  '  land resolve <jobId> --worktree <dir> [--wait] [--json]',
+  '  land resolve <jobId> --claim [--session <id>] [--json]',
+  '  land doctor [--json]',
+].join('\n');
+
+const FLAG_SPECS = Object.freeze({
+  init: { bool: ['guard'], value: ['agent-file'] },
+  guard: { bool: [], value: [] },
+  submit: { bool: ['wait', 'json', 'queue-anyway'], value: ['branch', 'title', 'priority', 'reason'] },
+  run: { bool: ['once'], value: [] },
+  priority: { bool: ['json'], value: ['reason'] },
+  status: { bool: ['json'], value: ['repo', 'radar-for'] },
+  wait: { bool: [], value: ['timeout-s'] },
+  inspect: { bool: [], value: [] },
+  cancel: { bool: ['force'], value: [] },
+  conflicts: { bool: ['json'], value: ['with'] },
+  claim: { bool: ['json'], value: ['ttl-h', 'session'] },
+  unclaim: { bool: ['json'], value: ['session'] },
+  'record-proof': { bool: ['json'], value: ['tree', 'plan-base', 'log', 'seconds', 'selection', 'commit'] },
+  report: { bool: ['json'], value: [] },
+  sync: { bool: ['wait', 'json', 'pull-only'], value: [] },
+  resolve: { bool: ['wait', 'json', 'claim'], value: ['worktree', 'session'] },
+  doctor: { bool: ['json'], value: [] },
+});
+
+// --- errors and output -------------------------------------------------------------------------
+
+function usageError(message) {
+  const error = new Error(message);
+  error.code = 'usage';
+  return error;
+}
+
+function progress(line) {
+  process.stderr.write(`land: ${line}\n`);
+}
+
+function emitJson(payload) {
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+}
+
+function emitLine(line) {
+  process.stdout.write(`${line}\n`);
+}
+
+// A real timer, never `state.sleepSync`: the runner's heartbeat is an interval, and blocking the
+// event loop is exactly what it must not do.
+function delay(ms) {
+  return new Promise((resolve) => { setTimeout(resolve, ms); });
+}
+
+function reportFailure(error, wantsJson) {
+  const code = typeof error.code === 'string' ? error.code : 'unexpected';
+  const message = error && error.message ? error.message : String(error);
+  if (code === 'usage') {
+    process.stderr.write(`land: ${message}\n\n${USAGE}\n`);
+    return 2;
+  }
+  // D-4 (§6.2): a submit refused because the branch conflicts with the target on a path the queue
+  // cannot regenerate is its OWN exit code (3), not the generic 1 — the caller has one action to
+  // take (`merge <target> into the branch`, or `--queue-anyway`) and a scripted agent must be able to
+  // tell that refusal apart from "the CLI broke". The paths ride in the payload so nothing has to
+  // re-run the merge to find out why.
+  if (code === 'conflict_at_submit') {
+    if (wantsJson) {
+      emitJson({
+        contract: CONTRACT,
+        ok: false,
+        error: code,
+        message,
+        paths: error.paths || [],
+        uncovered: error.uncovered || [],
+        covered: error.covered || [],
+      });
+    } else process.stderr.write(`land: error: ${code}: ${message}\n`);
+    return 3;
+  }
+  if (wantsJson) emitJson({ contract: CONTRACT, ok: false, error: { code, message } });
+  else process.stderr.write(`land: error: ${code}: ${message}\n`);
+  return 1;
+}
+
+// --- argv --------------------------------------------------------------------------------------
+
+function parseArgs(argv, spec) {
+  const flags = new Set();
+  const values = {};
+  const positionals = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === '--') {
+      positionals.push(...argv.slice(index + 1));
+      break;
+    }
+    if (!arg.startsWith('--')) {
+      positionals.push(arg);
+      continue;
+    }
+    const equals = arg.indexOf('=');
+    const name = equals === -1 ? arg.slice(2) : arg.slice(2, equals);
+    const inline = equals === -1 ? null : arg.slice(equals + 1);
+    if (spec.bool.includes(name)) {
+      if (inline !== null) throw usageError(`--${name} takes no value`);
+      flags.add(name);
+      continue;
+    }
+    if (spec.value.includes(name)) {
+      let value = inline;
+      if (value === null) {
+        value = argv[index + 1];
+        index += 1;
+      }
+      if (value === undefined || value.startsWith('--')) throw usageError(`--${name} requires a value`);
+      values[name] = value;
+      continue;
+    }
+    throw usageError(`unknown option --${name}`);
+  }
+  return { flags, values, positionals };
+}
+
+// --- repository context ------------------------------------------------------------------------
+
+function context(cwd) {
+  const top = toplevel(cwd);
+  const common = commonDir(cwd);
+  return { cwd, top, common, root: path.join(common, 'landing') };
+}
+
+function branchRef(name) {
+  return `refs/heads/${name}`;
+}
+
+function lines(stdout) {
+  return String(stdout || '').split('\n').map((line) => line.trim()).filter(Boolean);
+}
+
+function currentBranch(cwd) {
+  const res = runGitRaw(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  if (res.status !== 0) {
+    throw landingError('git_failed', `cannot resolve the current branch in ${cwd}`, { cwd, stderr: res.stderr });
+  }
+  const name = res.stdout.trim();
+  if (!name || name === 'HEAD') {
+    throw landingError('detached_head', `${cwd} is on a detached HEAD; check out a branch before submitting`, { cwd });
+  }
+  return name;
+}
+
+function unmergedPaths(cwd) {
+  return lines(runGitRaw(cwd, ['diff', '--name-only', '--diff-filter=U']).stdout);
+}
+
+function dirtyTrackedPaths(cwd) {
+  const unstaged = lines(runGitRaw(cwd, ['diff', '--name-only']).stdout);
+  const staged = lines(runGitRaw(cwd, ['diff', '--cached', '--name-only']).stdout);
+  return [...new Set([...unstaged, ...staged])];
+}
+
+function commitSubject(cwd, rev) {
+  const res = runGitRaw(cwd, ['log', '-1', '--format=%s', rev]);
+  const subject = res.status === 0 ? res.stdout.trim() : '';
+  return subject || rev.slice(0, 12);
+}
+
+function submitterWorkdir(ctx, job) {
+  const dir = job && job.submittedBy ? job.submittedBy.cwd : null;
+  if (dir && fs.existsSync(dir) && fs.existsSync(path.join(dir, '.git'))) return dir;
+  return ctx.cwd;
+}
+
+// --- D-4/D-5: conflict previews (§9 S-7/S-8) -----------------------------------------------------
+
+// The conflict paths the queue itself owns — a `landing.regenerate[]` or `landing.refresh[]` entry's
+// glob covers them, so the runner resolves them without a human. Everything else is hand-written and
+// is what D-4 refuses at submit. `train.globMatch` is the very matcher the runner uses to decide
+// `matchingRegenerateEntries`, so the precheck and the actual resolve can never disagree.
+function pathCoverage(config, conflicts) {
+  const entries = []
+    .concat(config && Array.isArray(config.regenerate) ? config.regenerate : [])
+    .concat(config && Array.isArray(config.refresh) ? config.refresh : []);
+  const owns = (file) => entries.some((entry) => Array.isArray(entry.paths) && entry.paths.some((pattern) => train.globMatch(pattern, file)));
+  return { covered: conflicts.filter(owns), uncovered: conflicts.filter((file) => !owns(file)) };
+}
+
+// D-5 (§9 S-8): after every landing the target has moved, so every WAITING job's train is rebuilt
+// against the new tip — `merge-tree` only, no worktree and no commit object — and its
+// `conflictPreview` records what it would now conflict on. The sweep is advisory by construction: it
+// never cancels, requeues or reorders anything, and a single uncomputable merge-tree skips that job
+// (which keeps the preview it already had) instead of failing the landing that triggered the sweep.
+function sweepConflictPreviews(ctx, workdir, config) {
+  const tip = revParseOrNull(workdir, branchRef(config.target));
+  if (!tip) return 0;
+  let written = 0;
+  for (const id of queue.readQueue(ctx.root).order) {
+    const job = queue.readJob(ctx.root, id);
+    if (!job || job.state !== 'queued') continue;
+    let merged;
+    try {
+      merged = mergeTree(workdir, tip, job.tip);
+    } catch (error) {
+      /* REPORT: the sweep is advisory — `runJob` re-decides the real conflict when the job is taken,
+         so one job whose merge-tree cannot be computed is skipped and keeps its previous preview */
+      progress(`job ${id}: conflict preview skipped (${error && error.message ? error.message : String(error)})`);
+      continue;
+    }
+    const { uncovered } = pathCoverage(config, merged.conflicts);
+    const next = uncovered.length ? { base: tip, paths: merged.conflicts, checkedAt: queue.nowIso() } : null;
+    const before = job.conflictPreview === undefined ? null : job.conflictPreview;
+    if (previewSignature(before) === previewSignature(next)) continue;
+    queue.updateJob(ctx.root, id, { conflictPreview: next });
+    written += 1;
+    progress(next ? `job ${id}: will conflict on ${next.paths.join(', ')}` : `job ${id}: conflict cleared`);
+  }
+  return written;
+}
+
+// `checkedAt` moves on every sweep, so the change test compares the two facts a reader acts on — the
+// base the preview was measured against and the paths it names — never the timestamp.
+function previewSignature(preview) {
+  if (!preview) return '-';
+  const paths = Array.isArray(preview.paths) ? preview.paths.join(',') : '';
+  return `${preview.base || ''}:${paths}`;
+}
+
+// The start-up half of D-5: a runner that has just claimed the lease previews the queue it is about
+// to drain, so a session waiting behind a target that moved under a PREVIOUS runner learns about it
+// before the next `takeNextJob`. A policy this process cannot read yet is not a runner failure — the
+// per-job path re-reads and enforces its own policy.
+function sweepOnRunnerStart(ctx) {
+  let config;
+  try {
+    config = loadTargetLandingConfig(ctx.cwd);
+  } catch (error) {
+    /* REPORT: the start-up sweep is advisory; `runJobInner` loads (and enforces) the target policy
+       for the job it actually takes, so an unreadable policy here only means "no previews yet" */
+    progress(`start-up conflict sweep skipped (${error && error.code ? error.code : 'unexpected'})`);
+    return 0;
+  }
+  return sweepConflictPreviews(ctx, ctx.cwd, config);
+}
+
+// --- the runner (D-2) --------------------------------------------------------------------------
+
+// D-2: the runner's liveness record. The interval is what keeps `heartbeatAt` fresh, and it works
+// only because gates run through an async `spawn` — the runner's event loop is free while a gate
+// works, so a 40-minute gate is 40 minutes of heartbeats rather than one long silence. `unref()`
+// because the lease, not the timer, decides when this process stops being the runner.
+function startHeartbeat(root, token, current) {
+  return setInterval(() => {
+    try {
+      lease.heartbeat(root, token, { ...(current.jobId ? { jobId: current.jobId } : {}), jobIds: current.jobIds || null });
+    } catch (error) {
+      /* expected: the lease was reaped or replaced while this runner worked — the drain loop
+         re-checks the on-disk token before every job and stops rather than writing to a lease it
+         no longer holds */
+    }
+    // D-5: the same tick that keeps the lease fresh is the tick that reads the job's stop request.
+    // There is no new timer — the runner already polls every 10 s while a gate works — and the
+    // abort signal is what every `runShell` of this job (gates and regenerate entries) is watching.
+    if (!current.controller || current.controller.signal.aborted) return;
+    // D-2 (§9 S-1, WP-1): the predicate lives in lib/landing/stop.js. A `cancel` on ANY member voids
+    // the train's verdict (I-4); a preempt keeps the boundary rule, and a singleton satisfies "every".
+    const members = Array.isArray(current.jobIds) && current.jobIds.length
+      ? current.jobIds
+      : (current.jobId ? [current.jobId] : []);
+    if (!members.length) return;
+    try {
+      if (stop.shouldAbortTrain(members.map((id) => queue.readJob(root, id)))) current.controller.abort();
+    } catch (error) {
+      /* expected: the job file can be mid-rename for an instant, or the directory is being torn
+         down under a test — a read error must never kill the interval that keeps this runner's
+         lease alive, and the next tick reads again */
+    }
+  }, lease.LAND_HEARTBEAT_MS);
+}
+
+// D-7 (WP-2): the CURRENT target tip, the thing a `base_broken` job waits for. It is the target the
+// committed policy names (the same loader `runJobInner` gates every job with), resolved fresh each
+// drain iteration so the hold is decided on the tip as it is now, not as it was when the job was
+// parked. A policy this process cannot read holds nothing (`null`) — `runJobInner` refuses such a job
+// with the same error a moment later, and parking work forever on a comparison that failed open would
+// be worse than running it.
+function targetTipOf(ctx) {
+  try {
+    return revParseOrNull(ctx.cwd, branchRef(loadTargetLandingConfig(ctx.cwd).target));
+  } catch (error) {
+    /* REPORT: unreadable policy/target — no hold this iteration; the job itself surfaces the error */
+    return null;
+  }
+}
+
+// WP-1: the batched runner lives in lib/landing/batch-runner.js and runs on this file's helpers.
+batchRunner.configure({ runJob, progress, submitterWorkdir, gateSelectionTelemetry, sweepConflictPreviews, branchRef, delay, afterTrainLanded: syncCli.afterTrainLanded });
+
+async function drain(ctx, record, opts = {}) {
+  const token = record.token;
+  const current = { jobId: null, jobIds: null, controller: null };
+  const timer = startHeartbeat(ctx.root, token, current);
+  timer.unref();
+  let processed = 0;
+  let released = false;
+  try {
+    // D-5 (§9 S-8): preview the queue this runner inherited, before it takes the first job.
+    sweepOnRunnerStart(ctx);
+    for (;;) {
+      const held = lease.read(ctx.root);
+      if (!held || held.token !== token) {
+        progress('lease lost; stopping the runner');
+        break;
+      }
+      const targetTip = targetTipOf(ctx);
+      const window = await batchRunner.chooseWindow(ctx, targetTip);
+      const members = queue.takeNextBatch(ctx.root, {
+        targetTip,
+        window,
+        onEmpty: () => { released = lease.release(ctx.root, token); },
+      });
+      if (!members.length) break;
+      current.jobId = members[0].id;
+      current.jobIds = members.map((member) => member.id);
+      // D-5: one controller per train (stop.shouldAbortTrain); jobIds reach the lease NOW for `land cancel`.
+      try { lease.heartbeat(ctx.root, token, { jobId: current.jobId, jobIds: current.jobIds }); } catch (error) { /* expected: lease reaped/replaced — the drain loop re-checks the token before every job */ }
+      current.controller = new AbortController();
+      try {
+        await batchRunner.runTrain(ctx, members, token, current.controller.signal);
+      } finally {
+        current.controller = null;
+        current.jobId = null; current.jobIds = null;
+        try { lease.heartbeat(ctx.root, token, { jobId: null, jobIds: null }); } catch (error) { /* expected: lease reaped/replaced — nothing of this train's left to clear */ }
+      }
+      processed += members.length;
+      if (opts.once) break;
+    }
+  } finally {
+    clearInterval(timer);
+    if (!released) lease.release(ctx.root, token);
+  }
+  return processed;
+}
+
+// WP-0 (§5 D-8, §6.6, §8 WP-0): the shape `job.gate` and the terminal metrics row's `gate` share,
+// built from the gate's own `--selection-out` record. A gate that wrote nothing (an older gate, or
+// one that could not write) reads as `null` — "unknown", never a row of zeros. `fallbackReason` and
+// `intersection` belong to WP-1/WP-3 and stay null until those exist.
+function gateSelectionTelemetry(selection) {
+  if (!selection || typeof selection !== 'object') return null;
+  const finite = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : null);
+  return {
+    mode: typeof selection.mode === 'string' ? selection.mode : null,
+    planBase: typeof selection.planBase === 'string' ? selection.planBase : null,
+    selected: finite(selection.selected),
+    executed: finite(selection.executed),
+    cached: finite(selection.cached),
+    // §6.6 calls the cache-miss map `missReasons`; bin/test-gate.sh writes it as `uncached`.
+    missReasons: selection.uncached && typeof selection.uncached === 'object' ? selection.uncached : null,
+    fallbackReason: null,
+    intersection: null,
+  };
+}
+
+// The gate's own timeout, the bound the base rerun inherits: the longest `timeoutSeconds` among the
+// configured gates (there is one in practice), in milliseconds; undefined when none is set, which
+// `runShell` treats as unbounded exactly like a gate with no timeout.
+function gateTimeoutMs(config) {
+  const seconds = (Array.isArray(config.gates) ? config.gates : [])
+    .map((gate) => Number(gate && gate.timeoutSeconds))
+    .filter((value) => Number.isFinite(value) && value > 0);
+  return seconds.length ? Math.max(...seconds) * 1000 : undefined;
+}
+
+// D-6/D-7 (WP-2, design §5): the base-rerun diagnosis. A FAILING gate names the test files that
+// failed; before that is reported as THIS branch's failure, exactly those files are rerun on the
+// BASE commit — Chromium's with-patch/without-patch rule: a failure that reproduces WITHOUT the patch
+// is not the patch's failure, it is a broken main. Returns `{ triage, gateSeconds, requeued }`:
+// `triage` is what the job record carries (null when the pass did not run), `gateSeconds` has the
+// rerun added to the gate's own, and `requeued: true` means the job was parked `base_broken` via
+// `queue.requeueBaseBroken` and the caller must NOT also finish it as failed (the record already
+// holds the outcome, and the runner will pick the job up again once the target tip moves).
+//
+// The pass is SKIPPED — reason untouched, `job.triage = null`, one `triage skipped (<why>)` line —
+// when the gate reason is not a test failure (`gate_timeout`/`gate_dirtied_tree`/`gate_stopped` name
+// no files), when the verdict came from the cache (nothing ran, so there is no fresh log), when the
+// repo turned it off (`landing.triage: false` → `maxFiles` 0), when the log names no test file at all
+// (a lint-only failure — lint is deterministic on the train tree and is never rerun on base), and
+// when it names more than `triage.maxFiles` files (a red main wide enough that a rerun would cost as
+// much as the gate it is diagnosing). A rerun that cannot RUN is not a verdict about base either: the
+// failure is reported exactly as the gate found it.
+async function triageFailedJob(ctx, { config, job, cached, reason, jobVerdict, built, logFile, workdir, signal, gateSeconds }) {
+  const skip = (why) => {
+    progress(`job ${job.id}: triage skipped (${why})`);
+    queue.updateJob(ctx.root, job.id, { triage: null });
+    return { triage: null, gateSeconds, requeued: false };
+  };
+  if (cached || (reason !== 'train_only' && reason !== 'gate_failed') || !(config.triage.maxFiles > 0)) {
+    return { triage: null, gateSeconds, requeued: false };
+  }
+  let parsed;
+  try {
+    parsed = train.failedFilesFromLog(fs.readFileSync(logFile, 'utf8'));
+  } catch (error) {
+    /* REPORT: a diagnosis that could not be made leaves the failure exactly as the gate reported it,
+       with `triage: null` saying so — never a hold on a base this run never measured */
+    return skip(`gate log unreadable: ${error.message}`);
+  }
+  if (!parsed.tests.length) return skip(parsed.lint ? 'lint failures are not rerun on base' : 'the gate log named no test file');
+  if (parsed.tests.length > config.triage.maxFiles) {
+    return skip(`${parsed.tests.length} failing files > triage.maxFiles ${config.triage.maxFiles}`);
+  }
+  let rerun;
+  try {
+    rerun = await train.rerunOnBase(workdir, {
+      base: built.base, files: parsed.tests, root: ctx.root, jobId: job.id, signal, cachePaths: config.cachePaths,
+      // D-7: the rerun is bounded by the same timeout as the gate it diagnoses (per launcher).
+      timeoutMs: gateTimeoutMs(config),
+    });
+  } catch (error) {
+    /* REPORT: rerunning is diagnostic, and a diagnostic that failed must not invent an outcome */
+    return skip(`rerun on base failed: ${error.message}`);
+  }
+  const triage = { base: built.base, files: parsed.tests.slice(), failedOnBase: rerun.failedOnBase, seconds: rerun.seconds };
+  const totalGateSeconds = Number(((Number(gateSeconds) || 0) + rerun.seconds).toFixed(3));
+  // A stopped rerun is not a verdict (the runner is being stopped): keep the failure, record what ran.
+  if (rerun.aborted) return { triage, gateSeconds: totalGateSeconds, requeued: false };
+  const everyOnBase = rerun.failedOnBase.length > 0 && parsed.tests.every((file) => rerun.failedOnBase.includes(file));
+  if (!everyOnBase) return { triage, gateSeconds: totalGateSeconds, requeued: false };
+  progress(`job ${job.id}: base_broken — ${rerun.failedOnBase.length} file(s) fail on base too; left queued until ${config.target} moves`);
+  queue.requeueBaseBroken(ctx.root, job.id, {
+    reason: 'base_broken',
+    verdict: jobVerdict,
+    gateLog: logFile,
+    triage,
+    timestamps: { ...job.timestamps, gated: queue.nowIso() },
+  }, { seconds: null, gateSeconds: totalGateSeconds });
+  return { triage, gateSeconds: totalGateSeconds, requeued: true };
+}
+
+// Anything unexpected still leaves the queue in a decidable state: the job is `failed` with the
+// typed code recorded, never stuck in `in_progress` for a later runner to reap.
+async function runJob(ctx, job, token, signal) {
+  try {
+    return await runJobInner(ctx, job, token, signal);
+  } catch (error) {
+    const code = typeof error.code === 'string' ? error.code : 'internal_error';
+    progress(`job ${job.id}: ${code}: ${error.message}`);
+    return queue.finishJob(ctx.root, job.id, {
+      state: 'failed',
+      reason: null,
+      error: { code, message: error.message },
+      timestamps: { ...job.timestamps, gated: queue.nowIso() },
+    });
+  }
+}
+
+async function runJobInner(ctx, job, token, signal) {
+  const workdir = submitterWorkdir(ctx, job);
+  // D-1/I-5: the policy this job is gated by is the `.ctm.json` COMMITTED AT THE TARGET, never the
+  // submitter's working tree. Reading the branch's own file would let any branch weaken the gate it
+  // is landed under (`gates: [{run: "echo ok"}]`) — a policy change has to land before it counts.
+  let config = loadTargetLandingConfig(workdir);
+  // WP-6 §13.4 R-R4/R-R6 (§13.7): a resolution of a CONFLICT is re-gated by the FAST gate instead of
+  // `landing.gates`; a resolution of a GATE FAILURE keeps the full gate and falls through. The copy
+  // replaces the whole `gates` array for the entire job, so every key derived from it —
+  // `gatesHash(config.gates)` for the verdict cache and the proof record — is the fast gate's, and
+  // never the commit gate's.
+  if (job.kind === 'resolve' && job.gateLane === 'fast' && config.publish && config.publish.resolveFastGate) {
+    config = { ...config, gates: [config.publish.resolveFastGate] };
+  }
+  const trainsRoot = train.trainsRoot(workdir, ctx.common).dir;
+  const trainDir = train.trainDirFor(trainsRoot, job.id);
+  // `landing/logs/` is not in state.js's SUBDIRS, so it is created here — before the first thing that
+  // can append to it (the D-8 regenerate log, which happens before the gate ever runs).
+  const logFile = path.join(queue.ensureLogsDir(ctx.root), `${job.id}.log`);
+  const targetWorktree = train.targetWorktreeFor(workdir, config.target);
+  const sourceDir = targetWorktree ? targetWorktree.path : workdir;
+  const foreignCommits = [];
+  let gateSeconds = null;
+  // WP-0 (design doc §5 D-8, §6.6, §8 WP-0, §9 S-13): the gate's self-description, spread onto the
+  // job record and onto this run's terminal metrics row. `null` means "no gate ran for this
+  // transition" — an `unchanged` job is `mode: 'none'`, a verdict-cache hit is `mode: 'cached'`.
+  // Reset at the top of every round so a later round can never inherit an earlier round's numbers.
+  let gateTelemetry = null;
+  let lastBuilt = null;
+  // Where the enforced policy came from — recorded so `land inspect` can say why a job was gated by
+  // rules its own branch does not contain.
+  queue.updateJob(ctx.root, job.id, { policySource: config.policySource });
+
+  // D-5: re-read this job's stop request off disk. Either kind is a stop: `kind:'cancel'` never
+  // lands, and `kind:'preempt'` (written by `urgent`, WP-3) sends the job back to the queue — unless
+  // the work is already done, which is the R-3 window handled at checkpoint 3 and 4 below.
+  const pendingStop = () => {
+    const fresh = queue.readJob(ctx.root, job.id);
+    return (fresh && fresh.stopRequest) || null;
+  };
+  // D-5: the cancel transition. `finishJob` re-reads the job under the mutex and spreads the patch,
+  // so the base/tree/train already recorded for this run survive.
+  const finishCanceled = (request) => {
+    progress(`job ${job.id}: stopped before the target moved`);
+    return queue.finishJob(ctx.root, job.id, {
+      state: 'canceled',
+      reason: 'stopped',
+      canceledBy: request.by,
+      stopRequest: null,
+      timestamps: { ...job.timestamps, canceled: queue.nowIso() },
+    }, { gateSeconds, gate: gateTelemetry });
+  };
+  // D-5 for a PREEMPT: the job is not terminal — it goes back to the queue (D-4/D-3) and the runner's
+  // next `takeNextJob` takes the urgent job, which sorts at the head. A cancel keeps winning over
+  // everything, at every checkpoint.
+  const stopBeforeLanding = (request) => {
+    if (request.kind === 'cancel') return finishCanceled(request);
+    progress(`job ${job.id}: preempted by ${request.forJob}; back to the queue`);
+    return queue.requeuePreempted(ctx.root, job.id);
+  };
+
+  for (let round = 1; round <= train.MAX_ROUNDS; round += 1) {
+    gateTelemetry = null;
+    const fresh = queue.readJob(ctx.root, job.id);
+    if (!fresh) return null;
+    // Checkpoint 1 (D-5): a job a dead runner left `canceled` directly is honoured as before ...
+    if (fresh.state === 'canceled') {
+      progress(`job ${job.id}: canceled before round ${round}`);
+      return fresh;
+    }
+    // ... and the round start is also where a stop request that arrived between jobs is seen.
+    const requestAtRoundStart = pendingStop();
+    if (requestAtRoundStart) return stopBeforeLanding(requestAtRoundStart);
+
+    let built = train.buildTrain(workdir, config.target, job);
+    lastBuilt = built;
+    progress(`job ${job.id} round ${round}/${train.MAX_ROUNDS}: ${built.kind} on ${built.base.slice(0, 12)}`);
+
+    // Checkpoint 2 (D-5), first half: the train has been built — a cancel that arrived while it was
+    // built stops the job before it can land (`unchanged`) or be acted on (`conflict`).
+    const requestAfterBuild = pendingStop();
+    if (requestAfterBuild) return stopBeforeLanding(requestAfterBuild);
+
+    if (built.kind === 'unchanged') {
+      // WP-0: no gate ran at all — the train is empty. `mode: 'none'` says exactly that, so a
+      // metrics reader never has to infer "no gate" from a missing field.
+      const noneGate = {
+        mode: 'none', planBase: null, selected: null, executed: null, cached: null,
+        missReasons: null, fallbackReason: null, intersection: null,
+      };
+      const unchanged = queue.finishJob(ctx.root, job.id, {
+        state: 'landed',
+        reason: 'unchanged',
+        base: built.base,
+        tree: built.tree,
+        train: built.train,
+        verdict: null,
+        gate: noneGate,
+        timestamps: { ...job.timestamps, landed: queue.nowIso() },
+      }, { gateSeconds, gate: noneGate });
+      // D-5: the target did not move, but a job finishing is still a change to the queue's state —
+      // and the sweep is idempotent (a job whose preview did not change is not written at all).
+      sweepConflictPreviews(ctx, workdir, config);
+      return unchanged;
+    }
+
+    if (built.kind === 'conflict') {
+      const entries = train.matchingRegenerateEntries(config, built.conflicts);
+      if (!entries) {
+        progress(`job ${job.id}: conflict in ${built.conflicts.join(', ')} — blocked`);
+        return queue.finishJob(ctx.root, job.id, {
+          state: 'blocked',
+          reason: 'conflict',
+          conflictPaths: built.conflicts,
+          base: built.base,
+          tree: built.tree,
+          train: null,
+          gate: null,
+          timestamps: { ...job.timestamps, gated: queue.nowIso() },
+        }, { gateSeconds, gate: gateTelemetry });
+      }
+      try {
+        built = await train.regenerateTrain({
+          cwd: workdir, dir: trainDir, job, base: built.base, conflicts: built.conflicts, entries, log: logFile, signal,
+        });
+      } catch (error) {
+        // Checkpoint 2 (D-5), second half: a `stopped` error from a regenerate entry is a STOP, not
+        // a failure — the entry was killed because this job's abort signal fired. Anything else (a
+        // real regenerate failure) is rethrown and becomes the job's failure.
+        if (error && error.code === 'stopped') {
+          const requestDuringRegenerate = pendingStop();
+          if (requestDuringRegenerate) return stopBeforeLanding(requestDuringRegenerate);
+        }
+        throw error;
+      }
+      lastBuilt = built;
+      progress(`job ${job.id}: regenerated ${built.regenerated.join(', ')}`);
+    }
+
+    // D-2/D-3 (WP-0): the refresh pass. Unlike regenerate this is not limited to a conflict — a
+    // tree-derived pin (the closure policy's `sourceBindings` digests) is stale the moment EITHER
+    // side touches a bound source, which is exactly the "one side changed server.js" case that never
+    // produces a textual conflict. The post-refresh tree is what the gate sees, what
+    // `readCachedVerdict` keys on, what `job.tree` records and what the CAS fast-forwards.
+    const refreshEntries = train.matchingRefreshEntries(config);
+    if (built.kind === 'train' && refreshEntries.length) {
+      try {
+        built = await train.refreshTrain({
+          cwd: workdir, dir: trainDir, job, built, entries: refreshEntries, log: logFile, signal,
+        });
+      } catch (error) {
+        // Same stop checkpoint as the regenerate block above: a `stopped` entry is a stop, never a
+        // failure; anything else (a real refresh failure) is rethrown and becomes the job's failure.
+        if (error && error.code === 'stopped') {
+          const requestDuringRefresh = pendingStop();
+          if (requestDuringRefresh) return stopBeforeLanding(requestDuringRefresh);
+        }
+        throw error;
+      }
+      lastBuilt = built;
+      if (built.refreshed.length) progress(`job ${job.id}: refreshed ${built.refreshed.join(', ')}`);
+    }
+
+    // WP-2 (§5 D-4, §9 S-7): before the legacy tree-keyed cache, ask the PROOF store. A fast-forward
+    // train (`built.train === job.tip`) is exactly what the author's own commit gate gated — the
+    // hook records `<tree>.<planBaseTree>` for it (§5 D-1, §9 S-5) — so a train whose whole chain is
+    // proven lands with no gate run at all. When the target moved, `built.train` is a merge commit
+    // the branch never proved, and the chain is not even consulted.
+    let proven = null;
+    if (built.train === job.tip) {
+      const chain = proof.proofChain(workdir, ctx.root, {
+        base: built.base, tip: job.tip, gatesHash: gatesHash(config.gates),
+      });
+      if (chain.ok) proven = chain;
+    }
+    // D-4: only a PASS is reusable (`readCachedVerdict` refuses to replay a FAIL, so a flake is
+    // retryable by resubmitting). A cached PASS skips the gate entirely. A PROVEN tree is stronger
+    // than a cached one, so the legacy store is not consulted for it.
+    const cached = proven ? null : gate.readCachedVerdict(ctx.root, built.tree, gatesHash(config.gates));
+    let verdict;
+    let reason = null;
+    if (proven) {
+      verdict = 'PASS';
+      reason = null;
+      gateSeconds = 0;
+      gateTelemetry = {
+        mode: 'proven', planBase: built.base, selected: null, executed: 0, cached: null,
+        missReasons: null, fallbackReason: null, intersection: null,
+      };
+      progress(`job ${job.id}: verdict PROVEN (proof chain of ${proven.checked} commits)`);
+    } else if (cached) {
+      verdict = cached.verdict;
+      reason = null;
+      gateSeconds = cached.seconds;
+      // WP-0: a verdict-cache hit ran no gate for this job, so it reports the mode that says so.
+      gateTelemetry = {
+        mode: 'cached', planBase: null, selected: null, executed: null, cached: null,
+        missReasons: null, fallbackReason: null, intersection: null,
+      };
+      progress(`job ${job.id}: verdict CACHED (${verdict})`);
+      // WP-0: a regenerate/refresh pass materialized the train worktree and only `gate.runGate`'s
+      // finally removes it; a cached PASS never runs the gate, so the worktree is dropped here.
+      if (fs.existsSync(trainDir)) progress(`job ${job.id}: train worktree ${JSON.stringify(train.removeTrainWorktree(workdir, trainDir))}`);
+    } else {
+      const result = await gate.runGate({
+        cwd: workdir, dir: trainDir, config, job, built, token, root: ctx.root, logFile, sourceDir, signal,
+        // WP-3a (§5 D-3, §6.5, §8 WP-3a): a MERGE train (`built.train !== job.tip`) is measured for S
+        // = sel(B→T) ∩ sel(P→T) while the gate still runs today's selection. A fast-forward train is
+        // already proved or gated as today, so it asks for no measurement (null, not a no-op closure).
+        onTrainReady: built.train === job.tip ? null : (dir) => mergeDelta.mergeDeltaSelection({
+          trainDir: dir, root: ctx.root, base: built.base, tip: job.tip, gatesHash: gatesHash(config.gates), env: process.env,
+        }),
+      });
+      verdict = result.verdict;
+      reason = result.reason;
+      gateSeconds = result.seconds;
+      gateTelemetry = gateSelectionTelemetry(result.selection);
+      // §6.6: the shadow record rides on `gate.intersection`, and the full S goes to
+      // `logs/<jobId>.merge-delta.json` (the job keeps its sha256 and the OQ-2 counters).
+      if (result.shadow) {
+        gateTelemetry = mergeDelta.recordIntersection(gateTelemetry, result.shadow, {
+          root: ctx.root, jobId: job.id, verdict, logFile: result.logPath,
+        });
+      }
+      progress(`job ${job.id}: gate ${verdict === null ? 'stopped' : verdict}${reason ? ` (${reason})` : ''} in ${result.seconds}s${result.shadow ? ` [merge-delta shadow ${result.shadow.mode}]` : ''}`);
+      // WP-2 (§5 D-1, §9 S-8): the train's own PASS is a proof too, so the NEXT train built on this
+      // tree (§5 D-3a's `proof(tree(B))`) — or a resubmit of it (§5 D-4) — needs no gate run. A
+      // refusal (a FLAKY rerun, a dependency change) or an unwritable store is reported and never
+      // changes this job's outcome: the gate already decided, and a proof is an optimization.
+      //
+      // The train's PASS goes through the SAME D-1 refusals the hook's PASS does — the runner is not
+      // a more trustworthy witness than the author's own commit gate, and a green run that contains a
+      // FLAKY rerun (or whose delta against the plan base touches a dependency manifest) is exactly
+      // what §5 D-1 says must never become a proof.
+      //
+      // ONE term is the hook's alone: `no_pass` asks whether the log carries the gate's own terminal
+      // line, and the runner does not need that witness — gate.js derives PASS from the gate's EXIT
+      // STATUS (`gate.js:234`, `const verdict = reason ? 'FAIL' : 'PASS'`), so a repository whose
+      // `gates[].run` is a plain script that prints no `[test-gate] VERDICT:` line is a legitimate
+      // configuration, and honouring `no_pass` here would make D-4 unreachable for every such repo
+      // (and for this repo's own queue fixtures, `tests-integration/fixtures/landing/gate-sentinel.sh`).
+      // The refusals the runner CAN witness from the same log — a FLAKY rerun, a dependency-changing
+      // delta — still apply.
+      //
+      // `result.logPath` is the job log, opened in APPEND mode and shared across the rounds of one
+      // job, so it can also carry an earlier round's lines; that can only make the refusal MORE
+      // conservative (a stale FLAKY line refuses a proof that would otherwise be recorded), never a
+      // false proof. An unreadable log is a skip, not an error — the job has already landed.
+      if (result.verdict === 'PASS') {
+        try {
+          const logText = fs.readFileSync(result.logPath, 'utf8');
+          const refused = proof.proofRefusal(workdir, {
+            planBase: built.base, tree: built.tree, logText,
+          });
+          const fatal = refused && refused !== 'no_pass' ? refused : null;
+          if (fatal) {
+            progress(`job ${job.id}: proof not recorded (${fatal})`);
+          } else {
+            proof.recordProof(ctx.root, {
+              tree: built.tree,
+              planBaseTree: revParse(workdir, `${built.base}^{tree}`),
+              gatesHash: gatesHash(config.gates),
+              verdict: 'PASS',
+              source: 'train',
+              commit: built.train,
+              seconds: result.seconds,
+              at: new Date().toISOString(),
+              logPath: result.logPath,
+              selection: result.selection,
+            });
+          }
+        } catch (error) {
+          progress(`job ${job.id}: proof not recorded (${error.code || 'error'}: ${error.message})`);
+        }
+      }
+    }
+    const jobVerdict = proven ? 'PROVEN' : (cached ? 'CACHED' : verdict);
+    const jobGateLog = cached ? (cached.logPath || null) : logFile;
+
+    queue.updateJob(ctx.root, job.id, {
+      base: built.base,
+      tree: built.tree,
+      train: built.train,
+      verdict: jobVerdict,
+      gateLog: jobGateLog,
+      gate: gateTelemetry,
+      timestamps: { ...job.timestamps, gated: queue.nowIso() },
+    });
+
+    // Checkpoint 3 (D-5): the gate has returned and its result is on the job record. A cancel that
+    // arrived while it ran stops the job here — the target is never moved — and D-6's stopped gate
+    // (verdict null, reason gate_stopped) is not a verdict to act on. A PREEMPT here requeues the
+    // job unless the gate PASSed: the work is done, so the request is moot (R-3) and is cleared.
+    const requestAfterGate = pendingStop();
+    if (requestAfterGate) {
+      if (requestAfterGate.kind === 'cancel' || verdict !== 'PASS') return stopBeforeLanding(requestAfterGate);
+      queue.updateJob(ctx.root, job.id, { stopRequest: null });
+    }
+
+    if (verdict !== 'PASS') {
+      // D-6: a stopped gate with no cancel request behind it must still be decidable — it is a
+      // failure of this run (the job never landed), never a PASS.
+      if (reason === 'gate_stopped') {
+        progress(`job ${job.id}: gate stopped with no cancel request`);
+        return queue.finishJob(ctx.root, job.id, {
+          state: 'failed',
+          reason: 'gate_stopped',
+          verdict: jobVerdict,
+          base: built.base,
+          tree: built.tree,
+          train: built.train,
+          gateLog: jobGateLog,
+          timestamps: { ...job.timestamps, gated: queue.nowIso() },
+        }, { gateSeconds, gate: gateTelemetry });
+      }
+      // D-9 Tier A, computed per job and never by running a second gate.
+      const overlap = train.overlapWithTarget(workdir, built.base, job.tip);
+      const trainOnly = built.train !== job.tip && overlap.length > 0;
+      const failures = ['gate_timeout', 'gate_dirtied_tree'];
+      const finalReason = failures.includes(reason) ? reason : (trainOnly ? 'train_only' : 'gate_failed');
+      // D-6/D-7 (WP-2): diagnose on base before reporting — a `base_broken` job is left queued (it is
+      // main that is red, not this branch) and only every other outcome is a failure of this run.
+      const diagnosis = await triageFailedJob(ctx, {
+        config, job, cached, reason: finalReason, jobVerdict, built, logFile: jobGateLog, workdir, signal, gateSeconds,
+      });
+      if (diagnosis.requeued) return queue.readJob(ctx.root, job.id);
+      progress(`job ${job.id}: failed (${finalReason})`);
+      return queue.finishJob(ctx.root, job.id, {
+        state: 'failed',
+        reason: finalReason,
+        verdict: jobVerdict,
+        base: built.base,
+        tree: built.tree,
+        train: built.train,
+        overlapWithTarget: overlap,
+        gateLog: jobGateLog,
+        triage: diagnosis.triage,
+        timestamps: { ...job.timestamps, gated: queue.nowIso() },
+      }, { gateSeconds: diagnosis.gateSeconds, gate: gateTelemetry });
+    }
+
+    // AC-3e/test hook: hold the runner here for LAND_TEST_PAUSE_BEFORE_LAND_MS so a stop request can
+    // be written inside the R-3 window (between checkpoint 3 and the land). Inert when unset.
+    const pauseBeforeLand = intFlag('LAND_TEST_PAUSE_BEFORE_LAND_MS', 0);
+    if (pauseBeforeLand > 0) await delay(pauseBeforeLand);
+
+    // Checkpoint 4 (D-5): the last read before the target moves. A cancel that arrived after
+    // checkpoint 3 stops the job here; the gate PASSed, but a cancel never lands. A preempt is moot
+    // for the same reason as at checkpoint 3 — the work is done — so it is cleared and the job lands.
+    const requestBeforeLand = pendingStop();
+    if (requestBeforeLand) {
+      if (requestBeforeLand.kind === 'cancel') return finishCanceled(requestBeforeLand);
+      queue.updateJob(ctx.root, job.id, { stopRequest: null });
+    }
+
+    // D-5/D-11: land the train the gate APPROVED, comparing against `built.base` — the commit this
+    // train was built on — never against a freshly re-read tip. A re-read is a check-then-act gap:
+    // a commit landing in between would be silently dropped when the swap moved the target to a
+    // train that no longer contains it. `cas_lost` is that race, and it is handled exactly like a
+    // target that moved before the gate started: record the foreign commits and retrain, which
+    // counts toward MAX_ROUNDS.
+    let landed;
+    try {
+      landed = train.landTrain(workdir, config.target, built.train, built.base, { env: { LAND_TOKEN: token } });
+    } catch (error) {
+      if (error && error.code === 'target_dirty') {
+        progress(`job ${job.id}: target worktree has local changes overlapping the train (${error.paths.join(', ')})`);
+        return queue.finishJob(ctx.root, job.id, {
+          state: 'blocked',
+          reason: 'target_dirty',
+          paths: error.paths,
+          verdict: jobVerdict,
+          base: built.base,
+          tree: built.tree,
+          train: built.train,
+          gateLog: jobGateLog,
+          gate: gateTelemetry,
+        }, { gateSeconds, gate: gateTelemetry });
+      }
+      if (error && error.code === 'cas_lost') {
+        const moved = error.current || revParseOrNull(workdir, branchRef(config.target));
+        foreignCommits.push(...train.commitsBetween(workdir, built.base, moved));
+        // Persisted, not just held in memory: a retrain that then SUCCEEDS has to keep saying which
+        // commits landed under it, or the record of the race disappears the moment the job lands.
+        queue.updateJob(ctx.root, job.id, { foreignCommits: [...foreignCommits] });
+        progress(`job ${job.id}: target moved to ${String(moved).slice(0, 12)} (cas_lost); retraining`);
+        continue;
+      }
+      throw error;
+    }
+
+    progress(`job ${job.id}: landed ${String(built.train).slice(0, 12)} via ${landed.via}`);
+    const landedJob = queue.finishJob(ctx.root, job.id, {
+      state: 'landed',
+      reason: null,
+      verdict: jobVerdict,
+      base: built.base,
+      tree: built.tree,
+      train: built.train,
+      landedVia: landed.via,
+      gateLog: jobGateLog,
+      gate: gateTelemetry,
+      timestamps: { ...job.timestamps, landed: queue.nowIso() },
+    }, { gateSeconds, gate: gateTelemetry });
+    // D-5 (§9 S-8): the target just moved, so every job still waiting is re-checked against the new
+    // tip BEFORE this runner takes the next one — the waiting session is told "merge main now" while
+    // it waits rather than discovering the conflict when its turn comes.
+    sweepConflictPreviews(ctx, workdir, config);
+    return landedJob;
+  }
+
+  progress(`job ${job.id}: the target moved on every round — blocked target_moving`);
+  return queue.finishJob(ctx.root, job.id, {
+    state: 'blocked',
+    reason: 'target_moving',
+    foreignCommits,
+    base: lastBuilt ? lastBuilt.base : null,
+    tree: lastBuilt ? lastBuilt.tree : null,
+    train: lastBuilt ? lastBuilt.train : null,
+    gate: gateTelemetry,
+  }, { gateSeconds, gate: gateTelemetry });
+}
+
+async function waitForTerminal(root, id, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    const job = queue.readJob(root, id);
+    if (job && queue.TERMINAL_STATES.includes(job.state)) return job;
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return null;
+    await delay(Math.min(POLL_MS, remaining));
+  }
+}
+
+function exitCodeForState(jobState) {
+  if (jobState === 'landed') return 0;
+  if (jobState === 'failed' || jobState === 'blocked' || jobState === 'canceled') return 1;
+  return 0;
+}
+
+// --- verbs -------------------------------------------------------------------------------------
+
+// D-1/D-7 (§6.2): the one place a priority level and its reason are validated, shared by
+// `land submit` and `land priority`. The message names the FLAG, because the caller is a human or an
+// agent reading a usage error (exit 2), and the level is the only thing the queue module refuses.
+function parsePriorityLevel(rawPriority, rawReason) {
+  const level = rawPriority === undefined || rawPriority === null || rawPriority === '' ? 'normal' : String(rawPriority);
+  if (!queue.PRIORITIES.includes(level)) {
+    throw usageError('--priority must be one of normal, high, urgent');
+  }
+  const reason = rawReason === undefined || rawReason === null ? '' : String(rawReason);
+  // D-7: high and urgent are a request for someone else's attention, so they carry the reason for it.
+  if (level !== 'normal' && !reason.trim()) throw usageError('--reason is required for high and urgent');
+  if (reason.length > queue.PRIORITY_REASON_MAX) throw usageError(`--reason is at most ${queue.PRIORITY_REASON_MAX} characters`);
+  return { level, reason: reason || null };
+}
+
+// D-7: who asked. A loopback CLI has no identity to check (there is no owner check, matching
+// `land cancel`), so the audit trail records the session, the pid and the directory it ran from.
+function priorityBy(cwd) {
+  return { session: strFlag('CTM_SESSION_ID') || null, pid: process.pid, cwd };
+}
+
+// D-11/§6.2: `[high]` / `[urgent]` after the state, and nothing for `normal` (the common case stays
+// as narrow as it was).
+function priorityTag(level) {
+  return level && level !== 'normal' ? ` [${level}]` : '';
+}
+
+async function cmdSubmit(opts, cwd) {
+  // Validated before anything touches the repository: a bad level or a missing reason is a usage
+  // error whether or not the caller is even standing in a git worktree.
+  const { level, reason } = parsePriorityLevel(opts.values.priority, opts.values.reason);
+  const by = priorityBy(cwd);
+  const ctx = context(cwd);
+  // D-1/I-5: gates are resolved from the TARGET's committed policy, never the submitter's working
+  // tree — a branch cannot weaken the gate that decides whether it lands.
+  const config = loadTargetLandingConfig(cwd);
+  const branch = opts.values.branch || currentBranch(cwd);
+  const tip = revParse(cwd, branchRef(branch));
+
+  const unmerged = unmergedPaths(cwd);
+  if (unmerged.length) {
+    throw landingError('unmerged_paths', `${cwd} has unmerged paths: ${unmerged.join(', ')}`, { paths: unmerged });
+  }
+  const dirty = dirtyTrackedPaths(cwd);
+  if (dirty.length) {
+    progress(`warning: ${dirty.length} modified tracked file(s) in ${cwd}; the job lands the committed tip, not the working tree`);
+  }
+  queue.reapDeadRunner(ctx.root);
+
+  // D-11/I-5: reads the CTM session through `lib/env-flags.js` (the one flag reader) rather than
+  // raw, so the flag-read ratchet needs no baseline entry for this file.
+  const session = strFlag('CTM_SESSION_ID') || null;
+  let job = queue.activeJobFor(ctx.root, branch, tip);
+  // D-9: an already-active job for this branch@tip is re-prioritized rather than duplicated — the
+  // same call an agent already makes is the bump verb. WITHOUT `--priority` the existing level is
+  // kept, so a plain re-submit can never silently demote a bumped job.
+  let preempt = null;
+  if (job) {
+    progress(`job ${job.id} already ${job.state} for ${branch}@${tip.slice(0, 12)}`);
+    if (opts.values.priority !== undefined) {
+      const updated = queue.setPriority(ctx.root, job.id, { priority: level, reason, by, via: 'submit' });
+      job = updated.job;
+      preempt = updated.preempt;
+    }
+  } else {
+    if (!config.gates.length) {
+      throw landingError(
+        'config_gates_missing',
+        `no landing.gates configured in ${config.configDir} and no test command detected; a queue that gates nothing is not a queue`,
+        { configDir: config.configDir },
+      );
+    }
+    const duplicate = queue.duplicateSubmitter(ctx.root, session, process.pid, branch);
+    if (duplicate) {
+      // WP-0 D-8 (§9 S-13, AC-0a): a refusal is an EVENT. It is thrown before any job record exists,
+      // so until now the queue could not see its own back-pressure at all (census §1).
+      queue.recordRefusal(ctx.root, { reason: 'duplicate_submitter', session, branch });
+      throw landingError(
+        'duplicate_submitter',
+        `session ${session} already has job ${duplicate.id} (pid ${duplicate.submittedBy.pid}) in ${duplicate.state}`,
+        { jobId: duplicate.id, pid: duplicate.submittedBy.pid },
+      );
+    }
+    // D-4 (§9 S-7): decide the conflict HERE, not forty minutes later. `mergeTree` is the same oracle
+    // the runner gates on and it writes no commit object — the tree it prints is garbage the moment
+    // this process exits — so the precheck costs one `git merge-tree` and nothing else (§1.1: 24 jobs
+    // waited 2,592 minutes to be blocked on a conflict that was already visible at submit).
+    const targetTip = revParse(cwd, branchRef(config.target));
+    const merged = mergeTree(cwd, targetTip, tip);
+    let conflictPreview = null;
+    if (merged.conflicts.length) {
+      const { uncovered, covered } = pathCoverage(config, merged.conflicts);
+      if (uncovered.length && !opts.flags.has('queue-anyway')) {
+        // WP-0 D-8: the second refusal, recorded the same way (the file is only written when the
+        // submit really is refused — `--queue-anyway` is an acceptance, not a refusal).
+        queue.recordRefusal(ctx.root, { reason: 'conflict_at_submit', session, branch });
+        throw landingError(
+          'conflict_at_submit',
+          `${branch}@${tip.slice(0, 12)} conflicts with ${config.target} on ${uncovered.join(', ')}; merge ${config.target} into the branch first, or pass --queue-anyway`,
+          { paths: merged.conflicts, uncovered, covered },
+        );
+      }
+      // Either every path is owned by a regenerate/refresh entry (the runner resolves it) or the
+      // submitter said `--queue-anyway` (it expects an earlier job to absorb the overlap): the job is
+      // accepted, and only a conflict the QUEUE cannot resolve starts life with a preview.
+      conflictPreview = uncovered.length
+        ? { base: targetTip, paths: merged.conflicts, checkedAt: queue.nowIso() }
+        : null;
+    }
+    job = {
+      contract: CONTRACT,
+      id: queue.newJobId(),
+      repo: ctx.common,
+      branch,
+      tip,
+      title: opts.values.title || commitSubject(cwd, tip),
+      submittedBy: { session, pid: process.pid, cwd },
+      state: 'queued',
+      reason: null,
+      // D-1/D-7: the level is the flag or `normal`; the audit trail opens with the `from: 'normal'`
+      // entry only when the job was not submitted normal (a normal job has nothing to record).
+      priority: level,
+      priorityHistory: level === 'normal' ? [] : [{ from: 'normal', to: level, reason, via: 'submit', at: queue.nowIso(), by }],
+      preemptions: 0,
+      base: null,
+      train: null,
+      tree: null,
+      verdict: null,
+      conflictPaths: [],
+      // D-4/D-5: the preview the job starts life with — null unless the submitter took a conflict the
+      // queue cannot resolve with `--queue-anyway` (a covered conflict IS resolved by the runner, so
+      // there is nothing for the submitter to merge main for).
+      conflictPreview,
+      overlapWithTarget: [],
+      policySource: config.policySource,
+      runnerPid: null,
+      timestamps: { queued: queue.nowIso() },
+      gateLog: null,
+    };
+    queue.enqueue(ctx.root, job);
+    // D-4/§6.2: a FRESH urgent job asks for the running lower-ranked job to be stopped, the same
+    // decision `land priority` makes — one implementation, called after the enqueue so the queue
+    // already holds the new job when the request is written.
+    if (level === 'urgent') preempt = queue.requestPreemptFor(ctx.root, job.id, { by, reason });
+  }
+
+  // D-2: a submit must return in well under a second even when the gate takes 40 minutes, so it
+  // never drains in the foreground. If a runner is already live this process is just a producer
+  // (`runner: 'other'`); otherwise it starts a DETACHED `land run` child — on demand, never an idle
+  // daemon — which claims the lease, drains the queue and exits when the queue is empty.
+  const holder = lease.read(ctx.root);
+  const live = holder && !lease.isDead(holder) ? holder : null;
+  let runner;
+  let runnerPid;
+  if (live) {
+    runner = 'other';
+    runnerPid = live.pid;
+  } else {
+    runner = 'self';
+    const started = spawnRunner(ctx);
+    runnerPid = started ? started.pid : null;
+  }
+  if (runnerPid !== null) queue.updateJob(ctx.root, job.id, { runnerPid });
+
+  const position = queue.positionOf(ctx.root, job.id);
+  const payload = {
+    contract: CONTRACT,
+    jobId: job.id,
+    position,
+    queued: queue.readQueue(ctx.root).order.length,
+    runner,
+    eta_s: queue.etaSeconds(ctx.root, position),
+    // §6.2: the level this job now HOLDS — read back off the job, never the parsed flag, so a plain
+    // re-submit (no `--priority`) of an already-bumped job reports `high`, not the `normal` default
+    // (§6.1 `priorityOf`). `preempt` is null unless this submit asked for `urgent`, and then it is
+    // the D-4 outcome — `'requested'` having really written the running job's stop request (WP-3).
+    priority: queue.priorityOf(job),
+    preempt,
+  };
+
+  if (opts.flags.has('wait')) {
+    // `--wait` still waits for the job's terminal state; the work itself happens in the runner
+    // child started above (or in whoever already held the lease).
+    const final = await waitForTerminal(ctx.root, job.id, WAIT_TIMEOUT_MS);
+    if (!final) {
+      emitJsonOrLine(opts, { ...payload, state: 'queued', reason: null, verdict: null }, `job ${job.id} did not reach a terminal state within ${WAIT_TIMEOUT_S}s`);
+      return 75;
+    }
+    emitJsonOrLine(
+      opts,
+      { ...payload, position: null, state: final.state, reason: final.reason, verdict: final.verdict },
+      `job ${job.id} ${final.state}${final.reason ? ` (${final.reason})` : ''}`,
+    );
+    return exitCodeForState(final.state);
+  }
+
+  emitJsonOrLine(
+    opts,
+    payload,
+    `job ${job.id} queued at position ${position} of ${payload.queued}${priorityTag(payload.priority)} (runner: ${runner})`
+      + `${payload.eta_s === null ? '' : `, eta ~${payload.eta_s}s`}`
+      + preemptSuffix(preempt, preemptTargetOf(ctx.root, job.id)),
+  );
+  return 0;
+}
+
+// §6.2: the human line says which job an urgent bump is stopping, so a caller never has to read the
+// job files to find out. It names the job the request was written on — the runner's `in_progress`
+// job, which is the queue head — and nothing at all when `preempt` is not `'requested'`.
+function preemptSuffix(preempt, targetId) {
+  return preempt === 'requested' && targetId ? `; stopping job ${targetId}` : '';
+}
+
+// D-5 (§9 S-9): the D-4/D-5 preview as the `land status` row's suffix. A job with no preview (the
+// overwhelmingly common case) prints exactly the row it printed before WP-1.
+function conflictSuffix(preview) {
+  const paths = preview && Array.isArray(preview.paths) ? preview.paths : [];
+  return paths.length ? `  will conflict: ${paths.join(', ')}` : '';
+}
+
+function preemptTargetOf(root, urgentJobId) {
+  for (const queuedId of queue.readQueue(root).order) {
+    if (queuedId === urgentJobId) continue;
+    const job = queue.readJob(root, queuedId);
+    if (job && job.state === 'in_progress') return job.id;
+  }
+  return null;
+}
+
+// §6.2 `land priority <jobId> normal|high|urgent [--reason <text>] [--json]`: bump (or drop) any
+// ACTIVE job. It never touches the job's state — only its rank and its audit trail — so a job that
+// is gating keeps gating and a queued job keeps its place in line at its new level.
+function cmdPriority(opts, cwd) {
+  const ctx = context(cwd);
+  const id = opts.positionals[0];
+  const rawLevel = opts.positionals[1];
+  if (!id || !rawLevel) throw usageError('land priority <jobId> normal|high|urgent [--reason <text>] [--json]');
+  const { level, reason } = parsePriorityLevel(rawLevel, opts.values.reason);
+  const result = queue.setPriority(ctx.root, id, { priority: level, reason, by: priorityBy(cwd), via: 'priority' });
+  const total = queue.readQueue(ctx.root).order.length;
+  if (opts.flags.has('json')) {
+    emitJson({
+      contract: CONTRACT,
+      jobId: result.job.id,
+      priority: level,
+      changed: result.changed,
+      position: result.position,
+      preempt: result.preempt,
+    });
+    return 0;
+  }
+  if (!result.changed) {
+    emitLine(`job ${id} already ${level}`);
+    return 0;
+  }
+  const history = Array.isArray(result.job.priorityHistory) ? result.job.priorityHistory : [];
+  const previous = history.length ? history[history.length - 1].from : 'normal';
+  emitLine(
+    `job ${id} priority ${level} (was ${previous}), position ${result.position} of ${total}`
+      + preemptSuffix(result.preempt, preemptTargetOf(ctx.root, id)),
+  );
+  return 0;
+}
+
+// The detached runner: `node <this file> run`, in its own process group with its output in
+// `landing/logs/runner-<ts>.log`, unref'd so the submitter exits immediately. The child claims the
+// lease itself (a racing child simply finds one and exits), which is what keeps "exactly one runner"
+// true without the submitter holding a lock across a 40-minute gate.
+function spawnRunner(ctx) {
+  const dir = queue.ensureLogsDir(ctx.root);
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const logPath = path.join(dir, `runner-${stamp}-${process.pid}.log`);
+  const fd = fs.openSync(logPath, 'a');
+  try {
+    const child = spawn(process.execPath, [__filename, 'run'], {
+      cwd: ctx.cwd,
+      env: childEnv(),
+      detached: true,
+      stdio: ['ignore', fd, fd],
+    });
+    child.on('error', (error) => {
+      // Report, never throw: the job is already queued and the next `land submit` (or `land run`)
+      // starts a runner again, so a failed spawn must not turn into a stack trace here.
+      progress(`runner failed to start: ${error.message}`);
+    });
+    child.unref();
+    progress(`runner ${child.pid} started (log: ${logPath})`);
+    return { pid: child.pid, logPath };
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function emitJsonOrLine(opts, payload, human) {
+  if (opts.flags.has('json')) emitJson(payload);
+  else emitLine(human);
+}
+
+// Claim the lease, with one extra attempt when the first loss was a dead holder: `lease.claim`
+// reaps a dead holder internally, so a second call is the "the path is free now" case rather than
+// a spin.
+function claimRunner(ctx, jobId) {
+  const first = lease.claim(ctx.root, { jobId });
+  if (first) return first;
+  const holder = lease.read(ctx.root);
+  if (!holder || lease.isDead(holder)) return lease.claim(ctx.root, { jobId });
+  return null;
+}
+
+async function cmdRun(opts, cwd) {
+  const ctx = context(cwd);
+  queue.reapDeadRunner(ctx.root);
+  const record = claimRunner(ctx, null);
+  if (!record) {
+    const holder = lease.read(ctx.root);
+    progress(`another runner holds the lease${holder ? ` (pid ${holder.pid})` : ''}`);
+    return 0;
+  }
+  const processed = await drain(ctx, record, { once: opts.flags.has('once') });
+  progress(processed ? `drained ${processed} job(s)` : 'queue is empty');
+  return 0;
+}
+
+function cmdStatus(opts, cwd) {
+  const dir = opts.values.repo ? path.resolve(opts.values.repo) : cwd;
+  const ctx = context(dir);
+  let config = null;
+  let configError = null;
+  try {
+    config = loadLandingConfig(dir);
+  } catch (error) {
+    configError = { code: typeof error.code === 'string' ? error.code : 'unexpected', message: error.message };
+  }
+  const order = queue.readQueue(ctx.root).order;
+  // OQ-3: one metrics read for the whole listing — the ETA is position × the median of the last 20
+  // gate seconds, and stays `null` (never a guess) until 20 samples exist.
+  const etaSamples = queue.recentGateSeconds(ctx.root, queue.ETA_SAMPLES);
+  const etaFor = (position) => (position !== null && etaSamples.length >= queue.ETA_SAMPLES
+    ? Math.round(position * queue.median(etaSamples))
+    : null);
+  const jobs = queue.listJobs(ctx.root).slice(-50).map((job) => {
+    const index = order.indexOf(job.id);
+    const position = index === -1 ? null : index + 1;
+    return { ...queue.jobSummary(job), position, eta_s: etaFor(position) };
+  });
+  const radarSummary = statusRadar(dir, configError, opts.values['radar-for']);
+  // WP-1 (§6.2): the origin half of the status — ahead/behind against the LOCAL tracking ref (no
+  // fetch: `land status` stays a read verb) plus the last sync verdict from `landing/sync-state.json`.
+  const origin = syncCli.statusOrigin(dir, ctx.common, config);
+  const payload = {
+    contract: CONTRACT,
+    repo: ctx.common,
+    target: config ? config.target : null,
+    origin,
+    queue: { depth: order.length, order },
+    runner: queue.runnerSummary(ctx.root),
+    jobs,
+    // WP-0 D-8: the day's refusal count (the `land status` line, and a field for the CTM probe).
+    refusedToday: queue.refusalsToday(ctx.root),
+    config: configError
+      ? { ok: false, error: configError }
+      : { ok: true, gatesSource: config.gatesSource, gates: config.gates.map((entry) => entry.name) },
+    // §8 WP-3: present only for `--radar-for` (the CTM probe). Plain `status` is the queue alone —
+    // the repo-wide radar is `land conflicts`.
+    radar: radarSummary ? radarSummary.payload : null,
+  };
+  if (opts.flags.has('json')) {
+    emitJson(payload);
+    return 0;
+  }
+  emitLine(`repo: ${payload.repo}`);
+  emitLine(`target: ${payload.target === null ? '(unresolved)' : payload.target}`);
+  emitLine(`queue: ${payload.queue.depth} job(s)`);
+  for (const job of jobs) {
+    // §6.2 / D-11: the level rides on the row for a bumped job; a normal row is byte-identical to
+    // what it printed before this change.
+    // WP-0 (§6.6/D-8): a job whose gate explained itself says so — `gate <mode> <executed>/<selected>`.
+    // D-5 (§9 S-9): a non-empty preview is the queue saying "this job will not merge as it stands" —
+    // the suffix is the whole action the reader has to take (merge the target into the branch).
+    // D-7 (WP-2): a job parked on a broken base is `queued` on disk but is not waiting for its turn —
+    // it is waiting for MAIN to move, and the state cell says so rather than leaving the reader to
+    // wonder why a queued job never starts. Every other row is byte-identical to what it printed
+    // before this change.
+    const stateCell = job.retryAfterTargetMoves
+      ? 'base_broken (waiting for main to move)'
+      : `${job.state}${job.reason ? ` (${job.reason})` : ''}`;
+    emitLine(`  ${job.position === null ? '-' : job.position} ${job.id} ${stateCell}${priorityTag(job.priority)} ${job.branch} ${job.title}${gateTag(job.gate)}${batchTag(job.batch)}${conflictSuffix(job.conflictPreview)}`);
+  }
+  emitLine(payload.runner ? `runner: pid ${payload.runner.pid}${payload.runner.jobId ? ` job ${payload.runner.jobId}` : ''}` : 'runner: none');
+  // WP-0 D-8 (§8 WP-0): the back-pressure the queue could never see before this change. Always
+  // printed (0 when none), so the line is a metric and not a hint.
+  emitLine(`refused today: ${payload.refusedToday}`);
+  // Only printed when the repository opted in — an unconfigured repo's status stays byte-identical
+  // to what it printed before this change.
+  const originLine = syncCli.originStatusLine(config, origin);
+  if (originLine) emitLine(originLine);
+  if (radarSummary) emitLine(radarSummary.line);
+  return 0;
+}
+
+// WP-0 (§6.6): `land status` prints `gate <mode> <executed>/<selected>` for a job that carries the
+// gate's self-description, and nothing at all for one that does not (every job written before this
+// change, and every gate that never ran). Null numbers print as `?`, never as 0.
+// WP-1 §6 (WP-1 step 10, AC-1f): the batch suffix on a member's row — ` [batch b-… 3/5]`. A job with
+// no `batch` (every job written before this change, and every singleton under a window of one) prints
+// nothing at all, so its row stays byte-identical to today's.
+function batchTag(batch) {
+  if (!batch || typeof batch !== 'object' || typeof batch.id !== 'string') return '';
+  const total = Array.isArray(batch.members) ? batch.members.length : null;
+  const index = Number.isInteger(batch.index) ? batch.index + 1 : null;
+  if (total === null || index === null) return ` [batch ${batch.id}]`;
+  return ` [batch ${batch.id} ${index}/${total}]`;
+}
+
+function gateTag(gate) {
+  if (!gate || typeof gate !== 'object' || !gate.mode) return '';
+  const value = (number) => (typeof number === 'number' && Number.isFinite(number) ? String(number) : '?');
+  return ` gate ${gate.mode} ${value(gate.executed)}/${value(gate.selected)}`;
+}
+
+// `land status` without `--radar-for` has no radar (null): even a cache-only sweep has to list and
+// dirty-probe every worktree, which was ~51 s of a plain `land status` on a 413-worktree repo, to
+// print one line `land conflicts` already gives. A repository whose target is missing (or whose
+// policy is unreadable) has no radar either — the summary then says so instead of pretending L0.
+//
+// §8 WP-3: `--radar-for a,b` is the CTM probe's variant. It runs a FULL sweep
+// restricted to the listed branches, so each pair among them and each against the target is
+// actually computed, and the payload carries `pairs` (per-branch detail the view joins to sessions)
+// and `branches` (which worktrees were in scope) beside the usual summary. Un-listed worktrees are
+// filtered out before any dirty probe (radar.scopeBranches), so they are never snapshotted.
+function statusRadar(dir, configError, radarFor) {
+  if (radarFor === undefined) return null;
+  const onlyBranches = parseBranchList(radarFor);
+  const unavailable = (code) => ({
+    payload: { max: null, atLeastL2: null, unknown: null, pairs: [], branches: [] },
+    line: `radar: unavailable (${code})`,
+  });
+  if (configError) return unavailable(configError.code);
+  let config;
+  try {
+    config = loadTargetLandingConfig(dir);
+  } catch (error) {
+    return unavailable(typeof error.code === 'string' ? error.code : 'unexpected');
+  }
+  // The sweep is the only step here that can still refuse (a target branch that does not exist, a
+  // worktree list git will not print). `land status` is the READ verb: the queue, runner and job
+  // listing are all still true when the radar cannot be computed, so a radar refusal degrades the
+  // radar field and never fails the verb. (It also keeps the CTM probe total: a session's chip must
+  // not go dark because the repository's target branch has not been created yet.)
+  let sweep;
+  try {
+    sweep = radar.sweep(dir, { config, onlyBranches });
+  } catch (error) {
+    return unavailable(typeof error.code === 'string' ? error.code : 'unexpected');
+  }
+  const summary = radar.summarize(sweep.pairs);
+  return {
+    payload: {
+      ...summary,
+      pairs: sweep.pairs,
+      branches: sweep.branches.map((entry) => ({ branch: entry.branch, tip: entry.tip, dirty: entry.dirty })),
+    },
+    line: `radar: max ${summary.max} · ${summary.atLeastL2} pairs ≥ L2 · ${summary.unknown} unknown (scope: ${onlyBranches.join(', ') || '(none)'})`,
+  };
+}
+
+// `--radar-for a,b` / `--radar-for a`. An empty value is an empty restriction (see radar.sweep),
+// which is what a caller with no branches to name deserves: no pairs, no snapshots.
+function parseBranchList(raw) {
+  const names = String(raw).split(',').map((name) => name.trim()).filter(Boolean);
+  return [...new Set(names)];
+}
+
+async function cmdWait(opts, cwd) {
+  const ctx = context(cwd);
+  const id = opts.positionals[0];
+  if (!id) throw usageError('land wait <jobId> [--timeout-s <seconds>]');
+  let timeoutMs = WAIT_TIMEOUT_MS;
+  if (opts.values['timeout-s'] !== undefined) {
+    const seconds = Number(opts.values['timeout-s']);
+    if (!Number.isFinite(seconds) || seconds <= 0) throw usageError('--timeout-s must be a positive number of seconds');
+    timeoutMs = Math.round(seconds * 1000);
+  }
+  const existing = queue.jobOrThrow(ctx.root, id);
+  const final = queue.TERMINAL_STATES.includes(existing.state)
+    ? existing
+    : await waitForTerminal(ctx.root, id, timeoutMs);
+  if (!final) {
+    emitLine(`job ${id} still ${queue.readJob(ctx.root, id).state} after ${Math.round(timeoutMs / 1000)}s`);
+    return 75;
+  }
+  emitLine(`job ${id} ${final.state}${final.reason ? ` (${final.reason})` : ''}`);
+  return exitCodeForState(final.state);
+}
+
+function cmdInspect(opts, cwd) {
+  const ctx = context(cwd);
+  const id = opts.positionals[0];
+  if (!id) throw usageError('land inspect <jobId>');
+  const job = queue.jobOrThrow(ctx.root, id);
+  emitJson({
+    contract: CONTRACT,
+    job,
+    // WP-0 (§6.6/D-8): the same object the job carries, hoisted so a reader does not have to know
+    // where the runner keeps it.
+    gate: job.gate === undefined ? null : job.gate,
+    gateLog: job.gateLog || null,
+    gateLogExists: Boolean(job.gateLog && fs.existsSync(job.gateLog)),
+    verdictFile: job.tree ? gate.verdictFile(ctx.root, job.tree) : null,
+    trainDirHint: job.id,
+  });
+  return 0;
+}
+
+// §6.4: `land record-proof` — the one thing the pre-commit hook calls after a green gate (§9 S-5:
+// today the hook checks the PASS and throws it away). It resolves the policy exactly as the runner
+// does (`loadTargetLandingConfig`, the `.ctm.json` committed AT the target) and computes the gates
+// hash with the same call the gate itself was run under (`config.gatesHash(config.gates)`, the
+// identical expression `lib/landing/gate.js` `runGate` evaluates), so a proof the hook wrote is
+// readable by the runner verbatim — a mismatch on either half is a cache miss, never a wrong hit.
+//
+// Exit 3 and no write for every refusal: a log that is not a PASS, a log carrying a runner's FLAKY
+// evidence, a diff against the plan base that touches a dependency manifest, or a repository with no
+// landing config at the target. It never fails the commit — the hook ignores a non-zero exit and
+// prints one line (§6.4). Exit 0 prints the proof path.
+function cmdRecordProof(opts, cwd) {
+  const refuse = (reason) => {
+    if (opts.flags.has('json')) emitJson({ contract: CONTRACT, ok: false, error: { code: reason } });
+    else process.stderr.write(`[land] record-proof: refused (${reason})\n`);
+    return 3;
+  };
+  const { tree, log } = opts.values;
+  const planBase = opts.values['plan-base'];
+  if (!tree || !planBase || !log) {
+    throw usageError('land record-proof --tree <oid> --plan-base <rev> --log <path> --seconds <n> [--selection <json-file>] [--commit <sha>] [--json]');
+  }
+  const seconds = opts.values.seconds === undefined ? 0 : Number(opts.values.seconds);
+  if (!Number.isFinite(seconds)) throw usageError('--seconds must be a number');
+  let config;
+  try {
+    config = loadTargetLandingConfig(cwd);
+  } catch (error) {
+    /* expected: no landing config at the target (or no repository at all) is a REFUSAL by design
+       (§6.4) — the exit code and the one-line message ARE the disposition */
+    return refuse(typeof error.code === 'string' ? error.code : 'config_unreadable');
+  }
+  let planBaseTree;
+  try {
+    planBaseTree = revParse(cwd, `${planBase}^{tree}`);
+  } catch (error) {
+    /* expected: an unresolvable --plan-base is a refusal, not a crash — nothing can be keyed
+       without the parent's tree */
+    return refuse('plan_base_unresolved');
+  }
+  let logText;
+  try {
+    logText = fs.readFileSync(log, 'utf8');
+  } catch (error) {
+    /* expected: an unreadable gate log cannot be shown to be a PASS, so it is refused rather than
+       guessed at */
+    return refuse('log_unreadable');
+  }
+  const refused = proof.proofRefusal(cwd, { planBase, tree, logText });
+  if (refused) return refuse(refused);
+  let selection = null;
+  if (opts.values.selection !== undefined) {
+    try {
+      selection = JSON.parse(fs.readFileSync(opts.values.selection, 'utf8'));
+    } catch (error) {
+      /* expected: a gate that wrote no --selection-out file, or a torn one, reads as "unknown" —
+         the proof still records the PASS rather than refusing over a missing extra */
+      selection = null;
+    }
+  }
+  const file = proof.recordProof(context(cwd).root, {
+    tree,
+    planBaseTree,
+    gatesHash: gatesHash(config.gates),
+    verdict: 'PASS',
+    source: 'commit',
+    commit: opts.values.commit === undefined ? null : opts.values.commit,
+    seconds,
+    at: new Date().toISOString(),
+    logPath: path.resolve(cwd, log),
+    selection,
+  });
+  if (opts.flags.has('json')) emitJson({ contract: CONTRACT, ok: true, proof: file });
+  else emitLine(file);
+  return 0;
+}
+
+// §8 WP-3a/AC-3b: `land report merge-delta` is the OQ-2 instrument — it aggregates the shadow records
+// the runner already wrote onto every merge train's `gate.intersection` (n trains, n per mode, the
+// median |S|/|sel(B→T)| and the count of failed trains with a failing test outside S). It reads the
+// job records and nothing else, so it works on a repo whose runner is not running. The aggregation
+// itself lives in lib/landing/merge-delta.js, beside the measurement it reports on.
+function cmdReport(opts, cwd) {
+  const topic = opts.positionals[0];
+  if (topic !== 'merge-delta') throw usageError('land report merge-delta [--json]');
+  const report = mergeDelta.mergeDeltaReport(context(cwd).root);
+  if (opts.flags.has('json')) emitJson({ contract: CONTRACT, ...report });
+  else for (const line of mergeDelta.reportLines(report)) emitLine(line);
+  return 0;
+}
+
+// §6.2. A job that is not running is finished directly (only the runner writes in-progress
+// transitions, and there is no runner). For an `in_progress` job the runner is the only writer, so
+// this verb ASKS it to stop (D-5) and then waits for the runner to settle the job.
+//
+// D-10: a runner from an older `land.js` has no `stop` capability, so it would keep going and, on a
+// PASS, overwrite the `canceled` state with `landed`. Writing a state that runner will clobber is
+// worse than refusing: the refusal names the pid and says what to do about it.
+async function cmdCancel(opts, cwd) {
+  const ctx = context(cwd);
+  const id = opts.positionals[0];
+  if (!id) throw usageError('land cancel <jobId> [--force]');
+  const job = queue.jobOrThrow(ctx.root, id);
+  if (queue.TERMINAL_STATES.includes(job.state)) {
+    throw landingError('job_terminal', `job ${id} is already ${job.state}`, { jobId: id, state: job.state });
+  }
+  // D-6 (§9 S-2, WP-1): a member of a running train is a WITHDRAW — no `--force`; the refusal below
+  // protects a caller's own singleton gate, which no one else is gated by.
+  if (job.state === 'in_progress' && !opts.flags.has('force') && !stop.isBatchMemberInFlight(job, lease.read(ctx.root))) {
+    throw landingError('job_in_progress', `job ${id} is in_progress; rerun with --force to cancel a running job`, { jobId: id });
+  }
+  const record = job.state === 'in_progress' ? lease.read(ctx.root) : null;
+  // D-10: no lease or a dead lease means no runner is working this job — finish it directly, which
+  // is exactly today's path and is now correct.
+  if (job.state !== 'in_progress' || !record || lease.isDead(record)) {
+    const next = queue.finishJob(ctx.root, id, {
+      state: 'canceled',
+      reason: null,
+      canceledBy: { pid: process.pid, cwd: process.cwd(), at: queue.nowIso() },
+      timestamps: { ...job.timestamps, canceled: queue.nowIso() },
+    });
+    emitLine(`job ${id} ${next.state}`);
+    return 0;
+  }
+  if (!lease.hasCap(record, 'stop')) {
+    throw landingError(
+      'runner_cannot_stop',
+      `runner pid ${record.pid} predates the stop primitive; it would land job ${id} anyway — wait for it, or stop that runner`,
+      { jobId: id, pid: record.pid },
+    );
+  }
+  return await requestStopAndWait(ctx, id, record);
+}
+
+// D-5: write the stop request under the mutex, then poll the job until the runner settles it. The
+// runner's heartbeat (10 s) plus the SIGKILL grace (10 s) bound how long the request can take to
+// land; a runner that has not settled by `CANCEL_WAIT_MS` is reported (exit 75), never waited on.
+async function requestStopAndWait(ctx, id, record) {
+  queue.requestStop(ctx.root, id, { kind: 'cancel', by: priorityBy(ctx.cwd), reason: null });
+  const deadline = Date.now() + CANCEL_WAIT_MS;
+  for (;;) {
+    const job = queue.readJob(ctx.root, id);
+    if (job && queue.TERMINAL_STATES.includes(job.state)) {
+      if (job.state === 'canceled') {
+        // D-6 (§9 S-3): a withdrawn member's line says what happened to the train's other members.
+        const members = job.batch && Array.isArray(job.batch.members) ? job.batch.members : [];
+        if (members.length >= 2) emitLine(`job ${id} withdrawn from batch ${job.batch.id}; ${members.length - 1} other member(s) requeued`);
+        else emitLine(`job ${id} canceled`);
+        return 0;
+      }
+      // The gate PASSed before the request was read: the job landed, and that is the truth.
+      emitLine(`job ${id} ${job.state} (the cancel arrived after the gate)`);
+      return 1;
+    }
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) break;
+    await delay(Math.min(CANCEL_POLL_MS, remaining));
+  }
+  emitLine(`cancel requested; runner pid ${record.pid} will stop job ${id} within ~20 s`);
+  return 75;
+}
+
+// --- the radar verbs (WP-2, §5 D-7, §6.2) --------------------------------------------------------
+
+// §6.2 `land conflicts`: the advisory radar. Exit 0 whatever the levels — a conflict here is
+// information, not a refusal; `land submit` is what decides, and it decides on the gate.
+function cmdConflicts(opts, cwd) {
+  const config = loadTargetLandingConfig(cwd);
+  const result = radar.sweep(cwd, { config, withBranch: opts.values.with });
+  if (opts.flags.has('json')) {
+    emitJson(result);
+    return 0;
+  }
+  const shown = result.pairs.filter((pair) => radar.levelRank(pair.level) >= radar.levelRank('L1'));
+  shown.sort(comparePairs);
+  for (const pair of shown) emitLine(formatPair(pair));
+  emitLine(`radar: ${shown.length} pairs, max ${radar.summarize(result.pairs).max}`);
+  return 0;
+}
+
+function comparePairs(left, right) {
+  const byLevel = radar.levelRank(right.level) - radar.levelRank(left.level);
+  if (byLevel !== 0) return byLevel;
+  const byA = left.a.localeCompare(right.a);
+  return byA !== 0 ? byA : left.b.localeCompare(right.b);
+}
+
+// `L3 feat/a × main  conflicts: x.js (ledger)` — the level, the pair, then what was found.
+function formatPair(pair) {
+  const head = `${pair.level} ${pair.a} × ${pair.b}`;
+  if (pair.conflicts.length) return `${head}  conflicts: ${pair.conflicts.join(', ')}${pair.ledger ? ' (ledger)' : ''}`;
+  const tags = [];
+  if (pair.registry) tags.push('registry');
+  if (pair.claims.length) tags.push(`claims: ${pair.claims.map((claim) => claim.session).join(', ')}`);
+  return `${head}  files: ${pair.files.join(', ')}${tags.length ? ` (${tags.join('; ')})` : ''}`;
+}
+
+// The session is the claim's identity: a claim file is per session, so a session id that could name
+// a path is refused rather than sanitized (a rewritten id would be someone else's claim).
+function claimSession(opts) {
+  const raw = opts.values.session || strFlag('CTM_SESSION_ID') || '';
+  const session = String(raw).trim();
+  if (!session) {
+    throw landingError('session_required', 'no session: pass --session <id> or set CTM_SESSION_ID', {});
+  }
+  if (session === '.' || session === '..' || session.includes('/') || session.includes('\\')) {
+    throw landingError('session_invalid', `session id ${JSON.stringify(session)} is not a usable claim name`, { session });
+  }
+  return session;
+}
+
+function claimFile(ctx, session) {
+  return path.join(ctx.root, 'claims', `${session}.json`);
+}
+
+// Claim paths are recorded REPOSITORY-ROOT relative, because that is what the radar compares them
+// against (`git diff --name-only` is root-relative). A path typed from a subdirectory is prefixed with
+// that directory's `git rev-parse --show-prefix`, so `land claim lib/x.js` in `pkg/` stores
+// `pkg/lib/x.js` and matches. A path that climbs out of the repository (`..`) is refused rather than
+// stored as text the radar can never match. A leading `/` is treated as "from the repository root"
+// (the prefix is still applied), which is what a reader of the path expects.
+function claimPaths(cwd, rawPaths) {
+  const res = runGitRaw(cwd, ['rev-parse', '--show-prefix']);
+  if (res.status !== 0) {
+    throw landingError('git_failed', `cannot resolve the repository prefix in ${cwd}`, { cwd, stderr: res.stderr });
+  }
+  const prefix = res.stdout.trim();
+  return rawPaths.map((raw) => {
+    // A leading `/` names a path from the repository root; anything else is relative to cwd.
+    const text = String(raw);
+    const rooted = text.startsWith('/');
+    const normalized = path.posix.normalize(path.posix.join(rooted ? '' : prefix, text.replace(/^\/+/, '')));
+    if (!normalized || normalized === '.' || normalized === '..' || normalized.startsWith('../')) {
+      throw landingError('claim_path_invalid', `claim path ${JSON.stringify(raw)} is outside the repository`, { path: raw });
+    }
+    return normalized;
+  });
+}
+
+// §6.2 `land claim <path>...`: a SOFT claim (D-7). It warns another session that its branch touches
+// the same paths; it never blocks, never locks, and expires on its own.
+function cmdClaim(opts, cwd) {
+  const ctx = context(cwd);
+  const session = claimSession(opts);
+  const raw = opts.positionals.slice();
+  if (!raw.length) throw usageError('land claim <path>... [--ttl-h 4] [--session <id>]');
+  const paths = claimPaths(cwd, raw);
+  const hours = opts.values['ttl-h'] === undefined ? radar.CLAIM_DEFAULT_TTL_HOURS : Number(opts.values['ttl-h']);
+  if (!Number.isFinite(hours) || hours <= 0) throw usageError('--ttl-h must be a positive number of hours');
+  const branch = currentBranch(cwd);
+  const record = {
+    contract: CONTRACT,
+    session,
+    branch,
+    paths,
+    until: new Date(Date.now() + hours * 3600 * 1000).toISOString(),
+  };
+  // One claim per session (the file is named for it): a second `land claim` replaces the first.
+  writeJsonAtomic(claimFile(ctx, session), record);
+  emitJsonOrLine(opts, record, `claim: ${session} on ${branch}: ${paths.join(', ')} until ${record.until}`);
+  return 0;
+}
+
+// §6.2 `land unclaim`: removes only the caller's own file. Nothing to remove is not an error — the
+// caller asked for the claim to be gone, and it is.
+function cmdUnclaim(opts, cwd) {
+  const ctx = context(cwd);
+  const session = claimSession(opts);
+  const file = claimFile(ctx, session);
+  // A claim written by another contract is still THIS session's file; it is removed either way, since
+  // leaving it behind would keep warning others with text this build cannot read.
+  const existed = fs.existsSync(file);
+  if (existed) fs.rmSync(file, { force: true });
+  emitJsonOrLine(opts, { contract: CONTRACT, session, removed: existed }, existed ? `unclaimed: ${session}` : `no claim for ${session}`);
+  return 0;
+}
+
+// --- WP-0/WP-1 (§6.1-§6.3, §7, §8 WP-0/WP-1): `land sync`, the sync-job half of the queue, and the
+// four origin doctor checks. The bodies live in lib/landing/sync-cli.js — moved verbatim to keep this
+// file under its frozen size ceiling. The module owns no process-level helper of its own: the ones
+// below are handed over once, here, right after this file's own definitions.
+syncCli.configure({
+  progress, emitLine, emitJson, emitJsonOrLine, delay, context, branchRef, spawnRunner, readGuardState,
+  CONTRACT, WAIT_TIMEOUT_MS, POLL_MS,
+});
+
+// §13.5/§13.7 WP-6: `land resolve`, the resolver's validate-and-submit verb (lib/landing/resolve-cli.js).
+resolveCli.configure({ progress, emitJsonOrLine, context, branchRef, CONTRACT, WAIT_TIMEOUT_MS });
+
+// (syncJobRecord / ensureRunner / finishSyncJob / afterTrainLanded moved to lib/landing/sync-cli.js.)
+
+// --- WP-0 (§7, §8 WP-0, §9 S-3): `land doctor` and its four origin checks (hooks, guard, remote,
+// push-auth — the last a `--dry-run`, never a real push). Moved verbatim to lib/landing/sync-cli.js,
+// which is where the push-auth probe now lives; this file keeps the WP-6 target fence below.
+
+// --- WP-6: the reference-transaction target fence (§7 E-1) ---------------------------------------
+
+const GUARD_MARKER = '# landing-ref-guard (managed)';
+const GUARD_HOOK_NAME = 'reference-transaction';
+const GUARD_CHAINED_NAME = 'reference-transaction.chained';
+// The guard is a repo-root `bin/` script, resolved relative to this file — never a copy, and never
+// looked up through PATH (a repo whose PATH lacks the tools directory still installs the fence).
+const GUARD_SCRIPT = path.resolve(__dirname, '..', '..', 'bin', 'landing-ref-guard.sh');
+const GUARD_TARGET_LINE_RE = /^LANDING_TARGET_REF=.*$/m;
+
+function guardHookPath(commonDirPath, name) {
+  return path.join(commonDirPath, 'hooks', name);
+}
+
+// The guard script with its `LANDING_TARGET_REF=` line rewritten to `refs/heads/<target>`. Read on
+// every install so the installed copy can be compared byte-for-byte with the source of truth.
+function renderGuardScript(target) {
+  let source;
+  try {
+    source = fs.readFileSync(GUARD_SCRIPT, 'utf8');
+  } catch (error) {
+    throw landingError('guard_script_missing', `cannot read the landing guard script at ${GUARD_SCRIPT}: ${error.message}`, {
+      file: GUARD_SCRIPT, cause: error,
+    });
+  }
+  if (!source.includes(GUARD_MARKER)) {
+    throw landingError('guard_script_invalid', `${GUARD_SCRIPT} is missing its ${GUARD_MARKER} marker`, { file: GUARD_SCRIPT });
+  }
+  if (!GUARD_TARGET_LINE_RE.test(source)) {
+    throw landingError('guard_script_invalid', `${GUARD_SCRIPT} has no LANDING_TARGET_REF= line to rewrite`, { file: GUARD_SCRIPT });
+  }
+  const line = `LANDING_TARGET_REF=refs/heads/${target}`;
+  return source.replace(GUARD_TARGET_LINE_RE, () => line);
+}
+
+// Install (or refresh) the guard. Idempotent by construction: the installed bytes are a pure
+// function of the guard script and the target, so a second run writes nothing and — crucially —
+// does not move anything aside a second time. A foreign `reference-transaction` hook is moved to
+// `reference-transaction.chained` exactly once; if that name is already taken we refuse rather than
+// destroy either hook.
+function installGuard(commonDirPath, target) {
+  const hooksDir = path.join(commonDirPath, 'hooks');
+  const hook = guardHookPath(commonDirPath, GUARD_HOOK_NAME);
+  const chained = guardHookPath(commonDirPath, GUARD_CHAINED_NAME);
+  const content = renderGuardScript(target);
+  fs.mkdirSync(hooksDir, { recursive: true });
+
+  let existing = null;
+  try {
+    existing = fs.readFileSync(hook, 'utf8');
+  } catch (error) {
+    /* expected: no reference-transaction hook in this repository yet — the common install case */
+    existing = null;
+  }
+
+  if (existing !== null && !existing.includes(GUARD_MARKER)) {
+    if (fs.existsSync(chained)) {
+      throw landingError('guard_hook_conflict', `${chained} already exists; refusing to move the foreign ${hook} aside on top of it`, {
+        hook, chained,
+      });
+    }
+    fs.renameSync(hook, chained);
+  }
+
+  if (existing === content) {
+    fs.chmodSync(hook, 0o755);
+    return { hook, chained: fs.existsSync(chained) ? chained : null, action: 'unchanged' };
+  }
+
+  // Temp file + rename inside the hooks directory: a reader (git, mid-transaction) never sees a
+  // half-written hook.
+  const staging = path.join(hooksDir, `.${GUARD_HOOK_NAME}.guard.${process.pid}.${Date.now()}`);
+  try {
+    fs.writeFileSync(staging, content, { mode: 0o755 });
+    fs.chmodSync(staging, 0o755);
+    fs.renameSync(staging, hook);
+  } catch (error) {
+    try {
+      fs.rmSync(staging, { force: true });
+    } catch (cleanupError) {
+      /* expected: the staging file is private to this call and lives in the hooks directory; a
+         failed cleanup leaves a stray dotfile behind, never a half-installed hook */
+    }
+    throw landingError('guard_install_failed', `cannot install ${hook}: ${error.message}`, { file: hook, cause: error });
+  }
+  return {
+    hook,
+    chained: fs.existsSync(chained) ? chained : null,
+    action: existing === null ? 'installed' : 'updated',
+  };
+}
+
+// Doctor's three states. `present` requires BOTH our marker and the configured target, so a hook
+// left over from a repository whose target moved reads as `foreign` rather than as a fence that
+// silently guards the wrong branch.
+function readGuardState(commonDirPath, target) {
+  const hook = guardHookPath(commonDirPath, GUARD_HOOK_NAME);
+  let content;
+  try {
+    content = fs.readFileSync(hook, 'utf8');
+  } catch (error) {
+    /* expected: no reference-transaction hook in this repository — `guard: missing` */
+    return 'missing';
+  }
+  if (!content.includes(GUARD_MARKER)) return 'foreign';
+  const baked = GUARD_TARGET_LINE_RE.exec(content);
+  if (!baked) return 'foreign';
+  if (target !== null && baked[0] !== `LANDING_TARGET_REF=refs/heads/${target}`) return 'foreign';
+  return 'present';
+}
+
+// `land guard install`: the narrow installer bin/install-hooks.sh reuses. It reads the landing
+// config (the target and nothing else) and touches only the hook — never `.ctm.json`, never the
+// agent file, which is why install-hooks must not call `land init`.
+function cmdGuard(opts, cwd) {
+  const verb = opts.positionals[0];
+  if (verb !== 'install') throw usageError('usage: land guard install');
+  const ctx = context(cwd);
+  const config = loadLandingConfig(cwd);
+  const result = installGuard(ctx.common, config.target);
+  emitLine(`guard: ${result.action} ${result.hook} (target refs/heads/${config.target})`);
+  if (result.chained) emitLine(`guard: chained ${result.chained}`);
+  return 0;
+}
+
+// --- init (D-10) --------------------------------------------------------------------------------
+
+function renderAgentRule(target) {
+  let raw;
+  try {
+    raw = fs.readFileSync(AGENT_RULE_FILE, 'utf8');
+  } catch (error) {
+    throw landingError('agent_rule_missing', `cannot read ${AGENT_RULE_FILE}: ${error.message}`, { file: AGENT_RULE_FILE });
+  }
+  return raw.replace(/\n+$/, '').replace(/<target>/g, target);
+}
+
+function resolveAgentFile(top, requested) {
+  if (requested !== undefined) {
+    if (!AGENT_FILES.includes(requested)) {
+      throw usageError(`--agent-file must be one of ${AGENT_FILES.join(', ')}`);
+    }
+    return path.join(top, requested);
+  }
+  for (const name of AGENT_FILES) {
+    if (fs.existsSync(path.join(top, name))) return path.join(top, name);
+  }
+  return path.join(top, 'AGENTS.md');
+}
+
+// The marked block: everything between the markers is exactly the rule text. Rewriting the block in
+// place is what makes a second `land init` byte-identical (AC-1h).
+function writeMarkedBlock(file, rule) {
+  const block = `${MARK_BEGIN}\n${rule}\n${MARK_END}`;
+  let existing = '';
+  try {
+    existing = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    /* expected: the agent file does not exist yet — it is created below with the block as its only
+       content */
+    existing = '';
+  }
+  let next;
+  if (MARK_RE.test(existing)) next = existing.replace(MARK_RE, block);
+  else if (existing === '') next = `${block}\n`;
+  else next = `${existing.replace(/\n+$/, '')}\n\n${block}\n`;
+  if (next === existing) return false;
+  fs.writeFileSync(file, next);
+  return true;
+}
+
+// `.ctm.json#landing` is written only when it is absent: an existing `landing` object belongs to the
+// repository, not to this command. Everything else in the file is preserved (2-space JSON).
+function writeLandingConfig(file, landing) {
+  let raw = null;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    /* expected: no .ctm.json in this repository yet — one is created below */
+    raw = null;
+  }
+  let data = {};
+  if (raw !== null) {
+    try {
+      data = JSON.parse(raw);
+    } catch (error) {
+      throw landingError('config_invalid', `${file} is not valid JSON: ${error.message}`, { file });
+    }
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+      throw landingError('config_invalid', `${file} must contain a JSON object`, { file });
+    }
+  }
+  if (data.landing !== undefined) return { file, written: false, created: false };
+  const next = `${JSON.stringify({ ...data, landing }, null, 2)}\n`;
+  fs.writeFileSync(file, next);
+  return { file, written: true, created: raw === null };
+}
+
+function cmdInit(opts, cwd) {
+  const top = toplevel(cwd);
+  const target = resolveMainBranch(top);
+  const guard = opts.flags.has('guard');
+  const config = writeLandingConfig(path.join(top, '.ctm.json'), { target, mode: 'serial', guard });
+  const agentFile = resolveAgentFile(top, opts.values['agent-file']);
+  const wroteBlock = writeMarkedBlock(agentFile, renderAgentRule(target));
+  emitLine(`config: ${config.file}${config.written ? ' written' : ' already configured (left untouched)'}`);
+  emitLine(`agent rule: ${agentFile}${wroteBlock ? ' written' : ' already up to date'}`);
+  if (guard) {
+    // WP-6 E-1: `--guard` installs the reference-transaction fence for the configured target. Same
+    // installer as `land guard install`; the rest of init (config, agent file) is unchanged.
+    const installed = installGuard(commonDir(top), target);
+    emitLine(`guard: ${installed.action} ${installed.hook} (target refs/heads/${target})`);
+    if (installed.chained) emitLine(`guard: chained ${installed.chained}`);
+  } else {
+    emitLine('guard: missing');
+  }
+  return 0;
+}
+
+// --- dispatch ------------------------------------------------------------------------------------
+
+async function dispatch(argv) {
+  const [verb, ...rest] = argv;
+  if (!verb || verb === 'help' || verb === '--help' || verb === '-h') {
+    process.stdout.write(`${USAGE}\n`);
+    return verb ? 0 : 2;
+  }
+  const spec = FLAG_SPECS[verb];
+  if (!spec) throw usageError(`unknown command ${JSON.stringify(verb)}`);
+  const opts = parseArgs(rest, spec);
+  const cwd = process.cwd();
+  switch (verb) {
+    case 'init': return cmdInit(opts, cwd);
+    case 'guard': return cmdGuard(opts, cwd);
+    case 'submit': return await cmdSubmit(opts, cwd);
+    case 'run': return await cmdRun(opts, cwd);
+    case 'priority': return cmdPriority(opts, cwd);
+    case 'status': return cmdStatus(opts, cwd);
+    case 'wait': return await cmdWait(opts, cwd);
+    case 'inspect': return cmdInspect(opts, cwd);
+    case 'cancel': return await cmdCancel(opts, cwd);
+    case 'conflicts': return cmdConflicts(opts, cwd);
+    case 'claim': return cmdClaim(opts, cwd);
+    case 'unclaim': return cmdUnclaim(opts, cwd);
+    case 'record-proof': return cmdRecordProof(opts, cwd);
+    case 'report': return cmdReport(opts, cwd);
+    case 'sync': return await syncCli.cmdSync(opts, cwd);
+    case 'resolve': return await resolveCli.cmdResolve(opts, cwd);
+    case 'doctor': return syncCli.cmdDoctor(opts, cwd);
+    default: throw usageError(`unknown command ${JSON.stringify(verb)}`);
+  }
+}
+
+async function main(argv) {
+  const wantsJson = argv.includes('--json');
+  try {
+    return await dispatch(argv);
+  } catch (error) {
+    return reportFailure(error, wantsJson);
+  }
+}
+
+if (require.main === module) {
+  // The CLI is asynchronous (gates are spawned, not blocked on), so the exit code is set once the
+  // whole verb has settled; `process.exit` is never called early, or buffered stdout would be lost.
+  main(process.argv.slice(2)).then(
+    (code) => { process.exitCode = code; },
+    (error) => {
+      process.stderr.write(`land: unexpected: ${error && error.message ? error.message : String(error)}\n`);
+      process.exitCode = 1;
+    },
+  );
+}
+
+module.exports = { main, parseArgs, FLAG_SPECS, USAGE };