create-walle 0.10.2 → 0.10.3

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

@@ -0,0 +1,536 @@
+'use strict';
+// WP-0 (docs/local-landing-queue-multi-session-integration-2026-10-26.html §6.1, §5 D-1/D-6, §8
+// WP-0): the landing queue's configuration, read from `.ctm.json#landing` through the SAME walker
+// CTM already uses (lib/project-config.js) — one file, one walker, one schema, no flags (D-1).
+//
+// Validation is strict on purpose (§6.1): unknown keys are rejected, `mode` is `"serial"` only
+// until WP-8, `cachePaths` must be git-ignored, and every `regenerate.paths` glob must match at
+// least one tracked path. Every failure is a typed Error (`.code`).
+//
+// A repo without `.ctm.json` is normal (autodetect is the whole point of §6.1), so the loader
+// works from the repository TOPLEVEL: an unconfigured repo still gets gates from autodetect, and
+// a submit from a subdirectory behaves exactly like one from the root. A `.ctm.json` found above
+// the toplevel (`~/ws/.ctm.json` for a repo in `~/ws/x`) is somebody else's config and is
+// ignored, never inherited. Outside a repository there is nothing to land into: `not_a_repo`.
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { findProjectConfig } = require('../project-config');
+const { landingError, revParseOrNull, runGitRaw, toplevel } = require('./git');
+
+const ALLOWED_KEYS = Object.freeze(['target', 'mode', 'gates', 'regenerate', 'refresh', 'registries', 'cachePaths', 'guard', 'triage', 'batch', 'publish']);
+const DEFAULT_GATE_TIMEOUT_SECONDS = 3600;
+// Off unless the repo asks for it (§7 E-1 / `land init --guard`).
+const DEFAULT_GUARD = false;
+// §5 D-7: at most this many failed test files are rerun on the base commit (WP-2).
+const DEFAULT_TRIAGE_MAX_FILES = 8;
+// The only key `landing.triage` understands today.
+const TRIAGE_KEYS = Object.freeze(['maxFiles']);
+// §5 D-3 / §6 (WP-1): the batch window's ceiling and how long a lone job waits for company. Both are
+// defaults in code, never flags — batching is default-ON with a ceiling of 8 and no waiting, so a
+// repository with no `landing.batch` key behaves exactly as it did before this change (`max: 1` is the
+// serial queue; `waitSeconds: 0` means a ready train never waits).
+const DEFAULT_BATCH_MAX = 8;
+const DEFAULT_BATCH_WAIT_SECONDS = 0;
+// The only keys `landing.batch` understands today.
+const BATCH_KEYS = Object.freeze(['max', 'waitSeconds']);
+
+// WP-0/WP-1 (docs/fleet-origin-main-sync-skill-2026-10-31.html §6.1): `landing.publish` — the origin
+// half of the landing policy. Absent = `land sync` is off for that repository (other users' repos are
+// unaffected, and there is no env flag). Present = on, with the §6.1 defaults below.
+const PUBLISH_KEYS = Object.freeze([
+  'remote', 'branch', 'auto', 'follow', 'followIntervalMs', 'maxRetrains',
+  // WP-6 (docs/fleet-origin-main-sync-skill-2026-10-31.html §13.4 R-R3/R-R4, §13.7): the resolver
+  // half of the publish policy. `resolve` says whether CTM opens a resolver session at all, the
+  // three others describe that session and the FAST gate its resolution runs.
+  'resolve', 'resolveAgent', 'resolveMaxMinutes', 'resolveFastGate',
+]);
+const DEFAULT_PUBLISH_REMOTE = 'origin';
+const DEFAULT_PUBLISH_BRANCH = 'main';
+// §5 R-9 (auto-publish after a landing) and R-8 (the CTM follower) are both default-ON.
+const DEFAULT_PUBLISH_AUTO = true;
+const DEFAULT_PUBLISH_FOLLOW = true;
+// §5 R-8: fetch origin every 15 minutes.
+const DEFAULT_PUBLISH_FOLLOW_INTERVAL_MS = 900000;
+// §5 R-4: at most this many extra trains on a rejected push.
+const DEFAULT_PUBLISH_MAX_RETRAINS = 3;
+// §13.4 R-R1/R-R2: `session` = a blocked conflict (or a failed gate) becomes a visible resolver
+// session; `off` = rev-2 behaviour (the follower keeps `--pull-only`).
+const DEFAULT_PUBLISH_RESOLVE = 'session';
+// §13.4 D-R2: which agent harness the resolver session runs on.
+const DEFAULT_PUBLISH_RESOLVE_AGENT = 'claude';
+// §13.4 R-R8: the resolver's wall-clock budget, in minutes (10 min .. 24 h).
+const DEFAULT_PUBLISH_RESOLVE_MAX_MINUTES = 120;
+const RESOLVE_MODES = Object.freeze(['session', 'off']);
+const RESOLVE_AGENTS = Object.freeze(['claude', 'codex']);
+const RESOLVE_MAX_MINUTES_MIN = 10;
+const RESOLVE_MAX_MINUTES_MAX = 1440;
+// §13.4 R-R4: the FAST gate a `kind:"resolve"` job runs instead of `landing.gates`. It is a gate
+// entry in every respect (`{name, run, timeoutSeconds}`, run in the train worktree), so it is
+// validated by the very same `normalizeGate`.
+const DEFAULT_PUBLISH_RESOLVE_FAST_GATE = Object.freeze({
+  name: 'resolve-fast-gate',
+  run: 'bash bin/resolve-fast-gate.sh',
+  timeoutSeconds: 2400,
+});
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim() !== '';
+}
+
+function realpathOr(dir) {
+  try {
+    return fs.realpathSync(dir);
+  } catch (error) {
+    /* expected: the directory vanished between the walk and this call; the resolved-path form is
+       still a usable answer for the containment test */
+    return path.resolve(dir);
+  }
+}
+
+// True when `child` is `parent` itself or lies underneath it. Both sides must be resolved paths.
+function isInside(parent, child) {
+  const rel = path.relative(parent, child);
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+// §6.1: `landing.target` defaults to the repo's main branch. This mirrors
+// coding-task-manager/git-utils.js `resolveMainBranch` (origin/HEAD -> main -> master) for the
+// local-branch part only; the local form is used because git-utils.js is async and pulls two
+// extra modules (../shared/git-remote-key, ./lib/async-semaphore) into a library that must stay
+// dependency-free and synchronous.
+function resolveMainBranch(cwd) {
+  if (revParseOrNull(cwd, 'refs/heads/main')) return 'main';
+  if (revParseOrNull(cwd, 'refs/heads/master')) return 'master';
+  return 'main';
+}
+
+function readFileSafe(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    /* expected: the ecosystem probe file is absent or unreadable -> not this ecosystem */
+    return null;
+  }
+}
+
+// §6.1 autodetect, first match in the documented order. A repo that matches nothing gates
+// nothing, which is a refusal at `land submit` time (config_gates_missing), never a silent pass.
+// `readRel(rel)` returns a file's text or null; it defaults to the working tree at `cwd`, and the
+// target-policy loader passes a reader over the target commit instead.
+function autodetectGates(cwd, readRel = (rel) => readFileSafe(path.join(cwd, rel))) {
+  const gate = (name, run) => [{ name, run, timeoutSeconds: DEFAULT_GATE_TIMEOUT_SECONDS }];
+  const pkgRaw = readRel('package.json');
+  if (pkgRaw !== null) {
+    try {
+      const pkg = JSON.parse(pkgRaw);
+      if (pkg && isPlainObject(pkg.scripts) && isNonEmptyString(pkg.scripts.test)) {
+        return { gates: gate('npm-test', 'npm test'), gatesSource: 'autodetect' };
+      }
+    } catch (error) {
+      /* expected: an unparseable package.json is not a test command; fall through to the next
+         ecosystem probe (and `land doctor` reports the parse failure separately) */
+    }
+  }
+  const makefile = readRel('Makefile');
+  if (makefile !== null && /^test\s*:/m.test(makefile)) {
+    return { gates: gate('make-test', 'make test'), gatesSource: 'autodetect' };
+  }
+  if (readRel('pyproject.toml') !== null) {
+    return { gates: gate('pytest', 'python -m pytest'), gatesSource: 'autodetect' };
+  }
+  if (readRel('Cargo.toml') !== null) {
+    return { gates: gate('cargo-test', 'cargo test'), gatesSource: 'autodetect' };
+  }
+  if (readRel('go.mod') !== null) {
+    return { gates: gate('go-test', 'go test ./...'), gatesSource: 'autodetect' };
+  }
+  return { gates: [], gatesSource: 'none' };
+}
+
+function normalizeGate(cwd, entry, index, label) {
+  const where = label || `landing.gates[${index}]`;
+  if (!isPlainObject(entry)) {
+    throw landingError('config_invalid', `${where} must be an object`, { index, configDir: cwd });
+  }
+  if (!isNonEmptyString(entry.name)) {
+    throw landingError('config_invalid', `${where}.name must be a non-empty string`, { index, configDir: cwd });
+  }
+  if (!isNonEmptyString(entry.run)) {
+    throw landingError('config_invalid', `${where}.run must be a non-empty string`, { index, configDir: cwd });
+  }
+  const timeoutSeconds = entry.timeoutSeconds === undefined ? DEFAULT_GATE_TIMEOUT_SECONDS : entry.timeoutSeconds;
+  if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0) {
+    throw landingError('config_invalid', `${where}.timeoutSeconds must be a positive number`, { index, configDir: cwd });
+  }
+  return { name: entry.name, run: entry.run, timeoutSeconds };
+}
+
+function isIgnoredByGit(cwd, relPath) {
+  const res = runGitRaw(cwd, ['check-ignore', '-q', '--', relPath]);
+  if (res.status === 0) return true;
+  if (res.status === 1) return false;
+  throw landingError('git_failed', `git check-ignore failed for ${relPath}`, { path: relPath, cwd, status: res.status, stderr: res.stderr });
+}
+
+// §6.1 calls the entry a glob, so it is matched with git's `:(glob)` magic: `**` then means
+// "zero or more directories" (`src/**/*.js` matches `src/index.js` as well as `src/a/b.js`),
+// whereas a bare pathspec would exclude the zero-directory case. A literal path is unaffected.
+function matchesTrackedFile(cwd, pattern) {
+  const res = runGitRaw(cwd, ['ls-files', '--', `:(glob)${pattern}`]);
+  if (res.status !== 0) {
+    throw landingError('git_failed', `git ls-files failed for ${pattern}`, { path: pattern, cwd, status: res.status, stderr: res.stderr });
+  }
+  return res.stdout.trim() !== '';
+}
+
+// sha256 of the gate array — the second half of the verdict cache key (D-4).
+function gatesHash(gates) {
+  return crypto.createHash('sha256').update(JSON.stringify(gates)).digest('hex');
+}
+
+// The validated landing config for `cwd` (which may be any directory inside the repo, including
+// a subdirectory or a linked worktree). `configDir` is the directory the answers are relative to:
+// the `.ctm.json` directory when the repo is configured, otherwise the repository toplevel.
+function loadLandingConfig(cwd) {
+  const top = toplevel(cwd);
+  const found = findProjectConfig(cwd);
+  const foundDir = found ? realpathOr(found.dir) : null;
+  // A config above the repo is not this repo's config.
+  const usable = foundDir && isInside(top, foundDir) ? { dir: foundDir, data: found.data } : null;
+  const configDir = usable ? usable.dir : top;
+  const raw = usable && usable.data ? usable.data.landing : undefined;
+  return validateLanding(raw, {
+    configDir,
+    readRel: (rel) => readFileSafe(path.join(configDir, rel)),
+    matchesTracked: (pattern) => matchesTrackedFile(configDir, pattern),
+    targetDefault: () => resolveMainBranch(configDir),
+  });
+}
+
+// The landing policy the queue enforces: the `landing` object of the `.ctm.json` COMMITTED at the
+// tip of the target branch (repository root), with gate autodetect read from that same commit. A
+// branch can therefore never weaken the gate it is landed under by editing its own `.ctm.json`;
+// a policy change takes effect only once it has itself landed. The submitter's working tree
+// supplies only the target branch name. `cwd` is any directory inside the repository.
+function loadTargetLandingConfig(cwd) {
+  const local = loadLandingConfig(cwd);
+  const top = toplevel(cwd);
+  const rev = `refs/heads/${local.target}`;
+  if (!revParseOrNull(top, rev)) {
+    throw landingError('target_missing', `target branch ${JSON.stringify(local.target)} does not exist`, { target: local.target });
+  }
+  const readRel = (rel) => {
+    const res = runGitRaw(top, ['show', `${rev}:${rel}`]);
+    return res.status === 0 ? res.stdout : null;
+  };
+  let data = null;
+  const text = readRel('.ctm.json');
+  if (text !== null) {
+    try {
+      data = JSON.parse(text);
+    } catch (error) {
+      throw landingError('config_invalid', `.ctm.json on ${local.target} is not valid JSON: ${error.message}`, { target: local.target, cause: error });
+    }
+  }
+  const raw = data && typeof data === 'object' ? data.landing : undefined;
+  const config = validateLanding(raw, {
+    configDir: top,
+    readRel,
+    // Authoring-time check only (land init / doctor validate the working tree); a committed policy
+    // is not re-validated against the tree it was committed with.
+    matchesTracked: () => true,
+    targetDefault: () => local.target,
+  });
+  // The target named by the committed policy wins only when it agrees; a disagreement means the
+  // submitter and the target disagree about where work lands, which is a refusal, not a guess.
+  if (config.target !== local.target) {
+    throw landingError('config_target_mismatch', `.ctm.json on ${local.target} names target ${JSON.stringify(config.target)}`, {
+      local: local.target, committed: config.target,
+    });
+  }
+  return { ...config, policySource: rev };
+}
+
+function validateLanding(raw, { configDir, readRel, matchesTracked, targetDefault }) {
+  if (raw !== undefined && raw !== null && !isPlainObject(raw)) {
+    throw landingError('config_invalid', `landing must be a JSON object in ${configDir}/.ctm.json`, { configDir });
+  }
+  const landing = raw || {};
+  for (const key of Object.keys(landing)) {
+    if (!ALLOWED_KEYS.includes(key)) {
+      throw landingError('config_unknown_key', `unknown landing key ${JSON.stringify(key)}`, {
+        key, configDir, allowed: [...ALLOWED_KEYS],
+      });
+    }
+  }
+  const mode = landing.mode === undefined ? 'serial' : landing.mode;
+  if (mode !== 'serial') {
+    throw landingError('config_mode_unsupported', `landing.mode ${JSON.stringify(mode)} is not supported (only "serial" until WP-8)`, {
+      mode, configDir,
+    });
+  }
+  let gates;
+  let gatesSource;
+  if (landing.gates === undefined) {
+    const detected = autodetectGates(configDir, readRel);
+    gates = detected.gates;
+    gatesSource = detected.gatesSource;
+  } else {
+    if (!Array.isArray(landing.gates)) {
+      throw landingError('config_invalid', 'landing.gates must be an array', { configDir });
+    }
+    gates = landing.gates.map((entry, index) => normalizeGate(configDir, entry, index));
+    gatesSource = 'config';
+  }
+  const regenerate = normalizePathEntries(landing.regenerate, 'regenerate', { configDir, matchesTracked });
+  // WP-0 (design §5 D-2, §9 S-4): `refresh` runs like `regenerate` but on EVERY train — it is how a
+  // tree-derived pin (the closure policy's digests) is rebuilt from the merged tree rather than
+  // merged as a scalar. Validated identically, so a glob that owns nothing is a config error.
+  const refresh = normalizePathEntries(landing.refresh, 'refresh', { configDir, matchesTracked });
+  const registries = [];
+  if (landing.registries !== undefined) {
+    if (!Array.isArray(landing.registries) || !landing.registries.every(isNonEmptyString)) {
+      throw landingError('config_invalid', 'landing.registries must be an array of strings', { configDir });
+    }
+    registries.push(...landing.registries);
+  }
+  const cachePaths = [];
+  if (landing.cachePaths !== undefined) {
+    if (!Array.isArray(landing.cachePaths) || !landing.cachePaths.every(isNonEmptyString)) {
+      throw landingError('config_invalid', 'landing.cachePaths must be an array of strings', { configDir });
+    }
+    for (const cachePath of landing.cachePaths) {
+      if (!isIgnoredByGit(configDir, cachePath)) {
+        throw landingError('config_cache_path_not_ignored', `landing.cachePaths entry ${JSON.stringify(cachePath)} is not git-ignored`, {
+          path: cachePath, configDir,
+        });
+      }
+      cachePaths.push(cachePath);
+    }
+  }
+  let guard = DEFAULT_GUARD;
+  if (landing.guard !== undefined) {
+    if (typeof landing.guard !== 'boolean') {
+      throw landingError('config_invalid', 'landing.guard must be a boolean', { configDir });
+    }
+    guard = landing.guard;
+  }
+  const triage = normalizeTriage(landing.triage, configDir);
+  const batch = normalizeBatch(landing.batch, configDir);
+  const publish = normalizePublish(landing.publish, configDir);
+  let target;
+  if (landing.target !== undefined) {
+    if (!isNonEmptyString(landing.target)) {
+      throw landingError('config_invalid', 'landing.target must be a non-empty branch name', { configDir });
+    }
+    target = landing.target;
+  } else {
+    target = targetDefault();
+  }
+  return {
+    target,
+    mode,
+    gates,
+    gatesSource,
+    regenerate,
+    refresh,
+    registries,
+    cachePaths,
+    guard,
+    triage,
+    batch,
+    publish,
+    configDir,
+  };
+}
+
+// §6.1: `landing.publish = { remote: str, branch: str, auto: bool, follow: bool, followIntervalMs:
+// int > 0, maxRetrains: int ≥ 0 }`. Absent means "off" and the normalized form is then `null`, which
+// is the one truth every caller (land sync, land doctor, land status, the runner's R-9 hook) reads —
+// there is no second `publishEnabled` boolean to keep in sync. A bad shape is `config_invalid` with
+// the offending `field`, like every other landing field, never a silent clamp.
+//
+// §13.4 R-R1/R-R4 (§13.7 WP-6) adds the resolver half: `resolve` ∈ {session, off}, `resolveAgent` ∈
+// {claude, codex}, `resolveMaxMinutes` ∈ [10, 1440] and `resolveFastGate` — one `landing.gates`
+// entry (`{name, run, timeoutSeconds}`) validated by the very same normalizer. All four have SOURCE
+// defaults (this file), so the normalized form is ALWAYS complete and no caller has to re-derive one.
+function normalizePublish(raw, configDir) {
+  if (raw === undefined || raw === null) return null;
+  if (!isPlainObject(raw)) {
+    throw landingError('config_invalid', 'landing.publish must be an object', { configDir, field: 'publish' });
+  }
+  for (const key of Object.keys(raw)) {
+    if (!PUBLISH_KEYS.includes(key)) {
+      throw landingError('config_unknown_key', `unknown landing.publish key ${JSON.stringify(key)}`, {
+        key, configDir, field: `publish.${key}`, allowed: [...PUBLISH_KEYS],
+      });
+    }
+  }
+  const remote = raw.remote === undefined ? DEFAULT_PUBLISH_REMOTE : raw.remote;
+  if (!isNonEmptyString(remote)) {
+    throw landingError('config_invalid', 'landing.publish.remote must be a non-empty string', { configDir, field: 'publish.remote', remote });
+  }
+  const branch = raw.branch === undefined ? DEFAULT_PUBLISH_BRANCH : raw.branch;
+  if (!isNonEmptyString(branch)) {
+    throw landingError('config_invalid', 'landing.publish.branch must be a non-empty string', { configDir, field: 'publish.branch', branch });
+  }
+  const bool = (key, fallback) => {
+    const value = raw[key] === undefined ? fallback : raw[key];
+    if (typeof value !== 'boolean') {
+      throw landingError('config_invalid', `landing.publish.${key} must be a boolean`, { configDir, field: `publish.${key}`, value });
+    }
+    return value;
+  };
+  const followIntervalMs = raw.followIntervalMs === undefined ? DEFAULT_PUBLISH_FOLLOW_INTERVAL_MS : raw.followIntervalMs;
+  if (!Number.isInteger(followIntervalMs) || followIntervalMs <= 0) {
+    throw landingError('config_invalid', 'landing.publish.followIntervalMs must be an integer > 0', { configDir, field: 'publish.followIntervalMs', followIntervalMs });
+  }
+  const maxRetrains = raw.maxRetrains === undefined ? DEFAULT_PUBLISH_MAX_RETRAINS : raw.maxRetrains;
+  if (!Number.isInteger(maxRetrains) || maxRetrains < 0) {
+    throw landingError('config_invalid', 'landing.publish.maxRetrains must be an integer ≥ 0', { configDir, field: 'publish.maxRetrains', maxRetrains });
+  }
+  // WP-6 §13.4 R-R1/R-R2 (§13.7 WP-6): the resolver policy. `resolve` and `resolveAgent` are closed
+  // enums, `resolveMaxMinutes` is bounded on both sides, and `resolveFastGate` is a gate entry —
+  // every default lives in SOURCE (here), so a repository that never mentions them gets the §13
+  // behaviour with no `.ctm.json` edit at all.
+  const resolveMode = raw.resolve === undefined ? DEFAULT_PUBLISH_RESOLVE : raw.resolve;
+  if (!RESOLVE_MODES.includes(resolveMode)) {
+    throw landingError('config_invalid', `landing.publish.resolve must be one of ${RESOLVE_MODES.join(', ')}`, { configDir, field: 'publish.resolve', resolve: resolveMode });
+  }
+  const resolveAgent = raw.resolveAgent === undefined ? DEFAULT_PUBLISH_RESOLVE_AGENT : raw.resolveAgent;
+  if (!RESOLVE_AGENTS.includes(resolveAgent)) {
+    throw landingError('config_invalid', `landing.publish.resolveAgent must be one of ${RESOLVE_AGENTS.join(', ')}`, { configDir, field: 'publish.resolveAgent', resolveAgent });
+  }
+  const resolveMaxMinutes = raw.resolveMaxMinutes === undefined ? DEFAULT_PUBLISH_RESOLVE_MAX_MINUTES : raw.resolveMaxMinutes;
+  if (!Number.isInteger(resolveMaxMinutes) || resolveMaxMinutes < RESOLVE_MAX_MINUTES_MIN || resolveMaxMinutes > RESOLVE_MAX_MINUTES_MAX) {
+    throw landingError('config_invalid', `landing.publish.resolveMaxMinutes must be an integer between ${RESOLVE_MAX_MINUTES_MIN} and ${RESOLVE_MAX_MINUTES_MAX}`, { configDir, field: 'publish.resolveMaxMinutes', resolveMaxMinutes });
+  }
+  const resolveFastGate = raw.resolveFastGate === undefined
+    ? { ...DEFAULT_PUBLISH_RESOLVE_FAST_GATE }
+    : normalizeGate(configDir, raw.resolveFastGate, null, 'landing.publish.resolveFastGate');
+  return {
+    remote,
+    branch,
+    auto: bool('auto', DEFAULT_PUBLISH_AUTO),
+    follow: bool('follow', DEFAULT_PUBLISH_FOLLOW),
+    followIntervalMs,
+    maxRetrains,
+    resolve: resolveMode,
+    resolveAgent,
+    resolveMaxMinutes,
+    resolveFastGate,
+  };
+}
+
+// §5 D-3 / §6 (WP-1): `landing.batch = { max: int ≥ 1 (8), waitSeconds: int ≥ 0 (0) }`. Absent means
+// the defaults; the normalized form is ALWAYS an object, so the runner never has to ask whether
+// batching is configured. A bad shape is `config_invalid` with the offending `field`, like every other
+// landing field — never a silent clamp, because a window the operator did not ask for is worse than a
+// refusal they can read.
+function normalizeBatch(raw, configDir) {
+  if (raw === undefined) return { max: DEFAULT_BATCH_MAX, waitSeconds: DEFAULT_BATCH_WAIT_SECONDS };
+  if (!isPlainObject(raw)) {
+    throw landingError('config_invalid', 'landing.batch must be an object', { configDir, field: 'batch' });
+  }
+  for (const key of Object.keys(raw)) {
+    if (!BATCH_KEYS.includes(key)) {
+      throw landingError('config_unknown_key', `unknown landing.batch key ${JSON.stringify(key)}`, {
+        key, configDir, field: `batch.${key}`, allowed: [...BATCH_KEYS],
+      });
+    }
+  }
+  const max = raw.max === undefined ? DEFAULT_BATCH_MAX : raw.max;
+  if (!Number.isInteger(max) || max < 1) {
+    throw landingError('config_invalid', 'landing.batch.max must be an integer ≥ 1', { configDir, field: 'batch.max', max });
+  }
+  const waitSeconds = raw.waitSeconds === undefined ? DEFAULT_BATCH_WAIT_SECONDS : raw.waitSeconds;
+  if (!Number.isInteger(waitSeconds) || waitSeconds < 0) {
+    throw landingError('config_invalid', 'landing.batch.waitSeconds must be an integer ≥ 0', { configDir, field: 'batch.waitSeconds', waitSeconds });
+  }
+  return { max, waitSeconds };
+}
+
+// §5 D-7 / §9 S-4 (WP-2): the base-rerun budget. Absent means the default; `false` is the documented
+// way to turn the pass off entirely (`maxFiles: 0`, which the runner reads as "never rerun"), so a
+// repository can opt out without knowing the default. The normalized form is ALWAYS an object, so
+// the runner never has to ask whether triage is configured.
+function normalizeTriage(raw, configDir) {
+  if (raw === undefined) return { maxFiles: DEFAULT_TRIAGE_MAX_FILES };
+  if (raw === false) return { maxFiles: 0 };
+  if (!isPlainObject(raw)) {
+    throw landingError('config_invalid', 'landing.triage must be an object or false', { configDir });
+  }
+  for (const key of Object.keys(raw)) {
+    if (!TRIAGE_KEYS.includes(key)) {
+      throw landingError('config_unknown_key', `unknown landing.triage key ${JSON.stringify(key)}`, {
+        key, configDir, allowed: [...TRIAGE_KEYS],
+      });
+    }
+  }
+  const maxFiles = raw.maxFiles === undefined ? DEFAULT_TRIAGE_MAX_FILES : raw.maxFiles;
+  if (!Number.isInteger(maxFiles) || maxFiles < 0) {
+    throw landingError('config_invalid', 'landing.triage.maxFiles must be an integer ≥ 0', { configDir, maxFiles });
+  }
+  return { maxFiles };
+}
+
+// `landing.regenerate` and `landing.refresh` share one shape — an array of { paths, run } entries in
+// which every glob must match at least one tracked path. `label` names the key in the error, so a
+// refusal says exactly which block is wrong.
+function normalizePathEntries(raw, label, { configDir, matchesTracked }) {
+  const entries = [];
+  if (raw === undefined) return entries;
+  if (!Array.isArray(raw)) {
+    throw landingError('config_invalid', `landing.${label} must be an array`, { configDir });
+  }
+  raw.forEach((entry, index) => {
+    if (!isPlainObject(entry) || !Array.isArray(entry.paths) || !entry.paths.length || !entry.paths.every(isNonEmptyString)) {
+      throw landingError('config_invalid', `landing.${label}[${index}].paths must be a non-empty array of strings`, { index, configDir });
+    }
+    if (!isNonEmptyString(entry.run)) {
+      throw landingError('config_invalid', `landing.${label}[${index}].run must be a non-empty string`, { index, configDir });
+    }
+    for (const pattern of entry.paths) {
+      if (!matchesTracked(pattern)) {
+        throw landingError(`config_${label}_unmatched`, `landing.${label}[${index}].paths entry ${JSON.stringify(pattern)} matches no tracked file`, {
+          path: pattern, index, configDir,
+        });
+      }
+    }
+    entries.push({ paths: entry.paths.slice(), run: entry.run });
+  });
+  return entries;
+}
+
+module.exports = {
+  ALLOWED_KEYS,
+  DEFAULT_GATE_TIMEOUT_SECONDS,
+  DEFAULT_GUARD,
+  DEFAULT_TRIAGE_MAX_FILES,
+  DEFAULT_BATCH_MAX,
+  DEFAULT_BATCH_WAIT_SECONDS,
+  PUBLISH_KEYS,
+  DEFAULT_PUBLISH_REMOTE,
+  DEFAULT_PUBLISH_BRANCH,
+  DEFAULT_PUBLISH_AUTO,
+  DEFAULT_PUBLISH_FOLLOW,
+  DEFAULT_PUBLISH_FOLLOW_INTERVAL_MS,
+  DEFAULT_PUBLISH_MAX_RETRAINS,
+  DEFAULT_PUBLISH_RESOLVE,
+  DEFAULT_PUBLISH_RESOLVE_AGENT,
+  DEFAULT_PUBLISH_RESOLVE_MAX_MINUTES,
+  DEFAULT_PUBLISH_RESOLVE_FAST_GATE,
+  RESOLVE_MODES,
+  RESOLVE_AGENTS,
+  loadLandingConfig,
+  loadTargetLandingConfig,
+  gatesHash,
+  autodetectGates,
+  resolveMainBranch,
+};