kenaz 0.0.0-stage → 0.3.2

package/core/.specialist/Ansuz/tools/verify-and-land.js

@@ -0,0 +1,1012 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * verify-and-land.js — one call runs Ansuz's post-dispatch landing pipeline
+ * (TASK_2059).
+ *
+ * WHY: Ansuz repeats the same mechanical landing pipeline by hand for every
+ * dispatched card (10-20 tool calls each): resolve branch, refuse if dirty,
+ * stage gitignored build resources, run Rust/node test suites, optionally
+ * run a negative control, merge, mark the task complete, mark the worktree
+ * landed, optionally wait for the backend to restart, optionally smoke-test
+ * live. This module is the mechanics only — judgement (reading diffs,
+ * deciding scope, deciding which suites/neg-control apply) stays with
+ * Ansuz; this script never decides, it only executes what it's told and
+ * reports what happened.
+ *
+ * DESIGN: every external effect (git, node, other processes, fs, time,
+ * sleep) goes through an injectable `deps` object (see defaultDeps()) so
+ * the pipeline is unit-testable without ever touching a real repo, merging
+ * anything, or running a real cargo/node test. `runVerifyAndLand(config,
+ * deps)` is the pure-orchestration entry point; `main()` at the bottom is
+ * the thin CLI wrapper (guarded by require.main, same convention as
+ * dev/scripts/run-rust-tests.js's parseArgs/buildExeArgs split, TASK_2058).
+ *
+ * Usage:
+ *   node verify-and-land.js <TASK_ID> --worktree <path> [--repo <path>]
+ *     [--rust <filter>]... [--node-test <file>]...
+ *     [--neg-file <repo-rel-path> --neg-test <node-test-file>|rust:<filter>]
+ *     [--message-file <path>] [--no-merge]
+ *     [--wait-backend] [--wait-backend-timeout-ms <ms>]
+ *     [--live "<cmd>"] [--log-dir <path>] [--dry-run]
+ *     [--rust-lock-wait-s <n>] [--rust-max-s <n>] [--rust-in-worktree]
+ *
+ * Rust suites (TASK_2084): by default each `--rust <filter>` runs through
+ * dev/scripts/rust-verify-worktree.js's canonical, warm, fixed-source-root
+ * verify worktree (cwd = --repo) instead of cold-building kuzu inside the
+ * task worktree — that's a 15-20 minute rebuild per landing otherwise. A
+ * `rust:<filter>` negative control runs the same way, with
+ * --overlay-from main:<neg-file> swapping in main's version instead of
+ * rewriting the file in the task worktree. --rust-in-worktree is an escape
+ * hatch back to the old behaviour (cwd = task worktree, resources copied in
+ * directly) for when the verify worktree is broken or unavailable.
+ *
+ * TASK_2176: when config.repo's .kenaz/project.yaml declares a top-level
+ * `verify_offline: <command>` key, an extra `verify-offline` step runs that
+ * command on config.repo (never the worktree) right before merge, serialized
+ * against other landings for the same project via the dispatch lock (see
+ * stepVerifyOffline) -- the authoritative gate for projects whose real
+ * verification needs one shared heavyweight tool (Unity/Unreal/mobile).
+ * Auto-detected; no CLI flag. Projects without the key are unaffected.
+ *
+ * Output: one compact JSON object on stdout —
+ *   { task, branch, ok, failed_step, steps: [{name, ok, summary, duration_ms, log}] }
+ * Full stdout/stderr of every step is written under the log dir (default
+ * os.tmpdir()/verify-and-land/<task>-<ts>) and referenced by path — never
+ * printed in full. Exit code 0 only when everything requested succeeded.
+ * --dry-run prints the planned steps and executes nothing (no deps call).
+ * Never pushes, never deletes branches/worktrees.
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+// Reuse the dispatch commit step's own telemetry exclusion list (TASK_2069)
+// instead of a second copy — a subagent worktree's dispatch prompt always
+// writes .kenaz/specialist/progress_note_TASK_<id>.json untracked and
+// deliberately outside its own commit (see .formation/tools/utils.js), so
+// preflight must ignore the same paths or it refuses every worktree that
+// followed the dispatch contract correctly (rune rune_db21a2fc).
+const {
+  WORKTREE_COMMIT_EXCLUDE_PATHSPECS,
+  parseVerifyOfflineFromYaml,
+  dispatchLockPath,
+  tryAcquireDispatchLock,
+} = require(
+  path.join(__dirname, '..', '..', '..', '.formation', 'tools', 'utils.js')
+);
+
+// ── pure helpers ────────────────────────────────────────────────────────────
+
+function sanitizeName(name) {
+  return String(name).replace(/[^A-Za-z0-9._-]+/g, '_');
+}
+
+/**
+ * CARGO_TARGET_DIR source for Rust suites: KENAZ_VERIFY_TARGET_DIR env var,
+ * with a documented win32-only fallback (matches the task spec literally —
+ * this is intentionally a *different* env var from dev/scripts/
+ * verify-target-dir.js's KENAZ_CARGO_TARGET_DIR / CANONICAL_WIN32, since the
+ * task calls for its own name). Non-win32 platforms without the env var
+ * refuse rather than guess (GEN-009: no silent cross-platform divergence).
+ */
+function resolveVerifyTargetDir(env, platform) {
+  if (env && env.KENAZ_VERIFY_TARGET_DIR) return env.KENAZ_VERIFY_TARGET_DIR;
+  if (platform === 'win32') return 'C:/t/kenaz-verify';
+  throw new Error(
+    'KENAZ_VERIFY_TARGET_DIR is required on non-win32 platforms (no documented fallback off Windows)'
+  );
+}
+
+/**
+ * Parses a backend.log tail for `backend logging initialized ...
+ * started_at=<ts>` lines and returns the ISO string of the latest one at or
+ * after `sinceMs`, or null. Tolerates the timestamp being quoted (tracing
+ * quotes field values containing spaces) or bare.
+ */
+function latestStartedAtAfter(tail, sinceMs) {
+  if (!tail) return null;
+  const lineRe = /^.*backend logging initialized.*$/gm;
+  const tsRe = /started_at=(?:"([^"]+)"|(\S+))/;
+  let best = null;
+  let m;
+  while ((m = lineRe.exec(tail))) {
+    const line = m[0];
+    const tsMatch = tsRe.exec(line);
+    if (!tsMatch) continue;
+    const raw = tsMatch[1] || tsMatch[2];
+    const parsed = new Date(raw.includes(' ') && !raw.includes('T') ? raw.replace(' ', 'T') : raw);
+    if (isNaN(parsed.getTime())) continue;
+    if (!best || parsed.getTime() > best.getTime()) best = parsed;
+  }
+  if (best && best.getTime() >= sinceMs) return best.toISOString();
+  return null;
+}
+
+/**
+ * Builds the ordered, side-effect-free step plan for a config. Used both by
+ * --dry-run (printed, nothing executed) and by runVerifyAndLand (executed
+ * in this exact order, stopping at the first failure).
+ */
+function buildPlan(config) {
+  const plan = [{ name: 'preflight', kind: 'preflight' }];
+  // TASK_2084: the warm rust-verify-worktree.js route copies its own Rust
+  // runtime resources into the fixed verify worktree — this step is only
+  // needed for the --rust-in-worktree escape hatch (cwd = task worktree).
+  if (config.rustFilters.length > 0 && config.rustInWorktree) {
+    plan.push({ name: 'copy-rust-resources', kind: 'copy-rust-resources' });
+  }
+  for (const filter of config.rustFilters) {
+    plan.push({ name: `rust:${filter}`, kind: 'rust', filter });
+  }
+  for (const file of config.nodeTests) {
+    plan.push({ name: `node:${file}`, kind: 'node', file });
+  }
+  if (config.negFile) {
+    plan.push({ name: 'negative-control', kind: 'neg' });
+  }
+  if (!config.noMerge) {
+    // TASK_2176: the authoritative, serialized heavyweight check runs right
+    // before merge, on the main tree (config.repo) -- gates the merge that
+    // follows it, same as the worktree-side negative control gates it above.
+    // config.verifyOfflineCmd is resolved in runVerifyAndLand BEFORE buildPlan
+    // is called, so it's already known here (and in the --dry-run preview).
+    if (config.verifyOfflineCmd) {
+      plan.push({ name: 'verify-offline', kind: 'verify-offline' });
+    }
+    plan.push({ name: 'merge', kind: 'merge' });
+    plan.push({ name: 'task-complete', kind: 'task-complete' });
+    plan.push({ name: 'mark-landed', kind: 'mark-landed' });
+  }
+  if (config.waitBackend) {
+    plan.push({ name: 'wait-backend', kind: 'wait-backend' });
+  }
+  if (config.live) {
+    plan.push({ name: 'live', kind: 'live' });
+  }
+  return plan;
+}
+
+/** Thrown for CLI usage/config errors — parseArgs syntax issues and
+ * validateConfig semantic issues. The CLI catches this class specifically
+ * and exits 2 (before doing anything); other errors are bugs, not usage
+ * errors, and propagate normally. */
+class UsageError extends Error {}
+
+const VALUE_FLAGS = new Set([
+  '--task', '--worktree', '--repo', '--rust', '--node', '--node-test',
+  '--neg-file', '--neg-test', '--message-file',
+  '--wait-backend-timeout-ms', '--wait-backend-poll-ms', '--live', '--log-dir',
+  '--rust-lock-wait-s', '--rust-max-s',
+]);
+const BOOLEAN_FLAGS = new Set([
+  '--no-merge', '--merge-without-tests', '--wait-backend', '--dry-run', '--rust-in-worktree',
+]);
+
+// TASK_2084: defaults for the warm rust-verify-worktree.js route (seconds),
+// overridable per invocation by --rust-lock-wait-s / --rust-max-s.
+const DEFAULT_RUST_LOCK_WAIT_S = 900;
+const DEFAULT_RUST_MAX_S = 1800;
+
+function splitList(value) {
+  return value.split(',').map(s => s.trim()).filter(Boolean);
+}
+
+function parseArgs(argv) {
+  const config = {
+    task: null,
+    worktree: null,
+    repo: null,
+    rustFilters: [],
+    nodeTests: [],
+    negFile: null,
+    negTest: null,
+    messageFile: null,
+    noMerge: false,
+    mergeWithoutTests: false,
+    waitBackend: false,
+    waitBackendTimeoutMs: 10 * 60 * 1000,
+    waitBackendPollMs: 5000,
+    live: null,
+    logDir: null,
+    dryRun: false,
+    rustLockWaitS: DEFAULT_RUST_LOCK_WAIT_S,
+    rustMaxS: DEFAULT_RUST_MAX_S,
+    rustInWorktree: false,
+  };
+  const positional = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (BOOLEAN_FLAGS.has(a)) {
+      switch (a) {
+        case '--no-merge': config.noMerge = true; break;
+        case '--merge-without-tests': config.mergeWithoutTests = true; break;
+        case '--wait-backend': config.waitBackend = true; break;
+        case '--dry-run': config.dryRun = true; break;
+        case '--rust-in-worktree': config.rustInWorktree = true; break;
+        default: /* unreachable, kept exhaustive for clarity */ break;
+      }
+      continue;
+    }
+    if (VALUE_FLAGS.has(a)) {
+      const val = argv[i + 1];
+      // A missing value looks identical to "next token is the next flag" —
+      // this CLI's values (paths, filters, task ids, numbers) never start
+      // with "--", so that's the safe signal for "value omitted" (TASK_2059
+      // follow-up: a swallowed value previously produced a plan with silent
+      // gaps instead of an error).
+      if (val === undefined || val.startsWith('--')) {
+        throw new UsageError(`missing value for ${a}`);
+      }
+      i++;
+      switch (a) {
+        case '--task': config.task = val; break;
+        case '--worktree': config.worktree = val; break;
+        case '--repo': config.repo = val; break;
+        case '--rust': config.rustFilters.push(...splitList(val)); break;
+        case '--node':
+        case '--node-test': config.nodeTests.push(...splitList(val)); break;
+        case '--neg-file': config.negFile = val; break;
+        case '--neg-test': config.negTest = val; break;
+        case '--message-file': config.messageFile = val; break;
+        case '--wait-backend-timeout-ms': config.waitBackendTimeoutMs = Number(val); break;
+        case '--wait-backend-poll-ms': config.waitBackendPollMs = Number(val); break;
+        case '--live': config.live = val; break;
+        case '--log-dir': config.logDir = val; break;
+        case '--rust-lock-wait-s': config.rustLockWaitS = Number(val); break;
+        case '--rust-max-s': config.rustMaxS = Number(val); break;
+        default: /* unreachable, kept exhaustive for clarity */ break;
+      }
+      continue;
+    }
+    if (a.startsWith('--')) {
+      // TASK_2059 follow-up (dogfood finding): a typo'd flag used to be
+      // silently dropped, which once produced a plan that merged with zero
+      // verification. Any unrecognized flag is now a hard error.
+      throw new UsageError(`unknown flag: ${a}`);
+    }
+    positional.push(a);
+  }
+  if (!config.task && positional.length > 0) config.task = positional[0];
+  return config;
+}
+
+/**
+ * Semantic validation, separate from parseArgs' syntax checks. Called both
+ * by the CLI (before doing ANYTHING, including --dry-run) and at the top of
+ * runVerifyAndLand (defense in depth for direct library callers/tests) —
+ * throws synchronously, never plans or executes on an invalid config.
+ */
+function validateConfig(config) {
+  if (!config.task) throw new UsageError('--task TASK_ID is required');
+  if (!config.worktree) throw new UsageError('--worktree <path> is required');
+  const hasVerification = config.rustFilters.length > 0 || config.nodeTests.length > 0 || !!config.negFile;
+  if (!config.noMerge && !hasVerification && !config.mergeWithoutTests) {
+    throw new UsageError(
+      'refusing to plan a merge with zero verification requested (no --rust/--node/--neg-file) — ' +
+        'pass verification flags, --no-merge, or explicit --merge-without-tests'
+    );
+  }
+}
+
+// ── default deps (real world) ───────────────────────────────────────────────
+
+function defaultDeps() {
+  const cp = require('child_process');
+  const fs = require('fs');
+  const os = require('os');
+  let backendLog = null;
+  try {
+    // Reuse the already-exported path resolution (TASK_2059 spec: reuse if
+    // exported). Lazy + guarded: this module must still work if that file
+    // changes shape.
+    backendLog = require(path.join(__dirname, '..', '..', 'tools', 'ansuz-boot-fast.js'));
+  } catch {
+    backendLog = null;
+  }
+  return {
+    spawnSync: cp.spawnSync,
+    fs,
+    env: process.env,
+    platform: process.platform,
+    tmpdir: () => os.tmpdir(),
+    now: () => Date.now(),
+    sleep: ms => new Promise(resolve => setTimeout(resolve, ms)),
+    resolveBackendLogPath: backendLog && backendLog.resolveBackendLogPath,
+    readBackendLogTailSync: backendLog && backendLog.readBackendLogTailSync,
+    // TASK_2176: injected so stepVerifyOffline's lock serialization is
+    // swappable in tests (fake lock acquire/deny) without a real lock file
+    // ever touching this repo's .formation/ dir during a unit test.
+    dispatchLockPath,
+    tryAcquireDispatchLock,
+  };
+}
+
+/**
+ * TASK_2176: auto-detects the project's offline verify command from
+ * config.repo's .kenaz/project.yaml — the MAIN tree, the same authoritative
+ * source dispatch.js reads for the worktree agent's self-check (see
+ * resolveDispatchIsolation in dispatch.js). Parsing itself is shared via
+ * utils.parseVerifyOfflineFromYaml (single format authority); only the fs
+ * read differs (deps.fs here, real fs in dispatch.js) so this stays
+ * unit-testable through the injected fake fs. Returns null (today's
+ * behaviour, step omitted) when the project has no project.yaml or no
+ * verify_offline key.
+ */
+function resolveVerifyOfflineCmd(config, deps) {
+  const yamlPath = path.join(config.repo, '.kenaz', 'project.yaml');
+  try {
+    if (!deps.fs.existsSync(yamlPath)) return null;
+    const raw = deps.fs.readFileSync(yamlPath, 'utf-8');
+    const content = Buffer.isBuffer(raw) ? raw.toString('utf-8') : raw;
+    return parseVerifyOfflineFromYaml(content);
+  } catch {
+    return null;
+  }
+}
+
+// ── exec helpers ─────────────────────────────────────────────────────────
+
+function git(deps, cwd, args) {
+  const res = deps.spawnSync('git', ['-C', cwd, ...args], { encoding: 'utf8' });
+  if (res.status !== 0) {
+    throw new Error(`git -C ${cwd} ${args.join(' ')} failed (exit ${res.status}): ${(res.stderr || res.stdout || '').trim()}`);
+  }
+  return (res.stdout || '').trim();
+}
+
+function normalizePathForCompare(p) {
+  return String(p).replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+}
+
+/**
+ * Resolves the repo whose main worktree `wt` belongs to, via
+ * `git -C <wt> rev-parse --path-format=absolute --git-common-dir` — for a
+ * linked worktree (e.g. a .kenaz-worktrees/ sibling) this already resolves
+ * to the MAIN repo's shared .git dir, whose parent is the repo root. Never
+ * derived from this script's own __dirname: when the script is invoked
+ * from inside a worktree checkout (the normal case — it's landing ITS OWN
+ * commit), __dirname-based resolution silently returns the worktree
+ * itself (TASK_2059 follow-up dogfood finding: merged a branch into its
+ * own worktree, "Already up to date", task-api ran against the wrong
+ * .kenaz/tasks dir).
+ */
+function resolveRepoFromWorktree(deps, wt) {
+  const res = deps.spawnSync(
+    'git',
+    ['-C', wt, 'rev-parse', '--path-format=absolute', '--git-common-dir'],
+    { encoding: 'utf8' }
+  );
+  if (res.status !== 0) {
+    throw new UsageError(
+      `could not resolve --repo from worktree ${wt} via git-common-dir: ${(res.stderr || res.stdout || '').trim()}`
+    );
+  }
+  const commonDir = (res.stdout || '').trim();
+  if (!commonDir) throw new UsageError(`git-common-dir returned empty output for worktree ${wt}`);
+  return path.dirname(commonDir);
+}
+
+/** Explicit --repo must own `wt` as one of its worktrees, and must not BE `wt`. */
+function assertRepoOwnsWorktree(deps, repo, wt) {
+  if (normalizePathForCompare(repo) === normalizePathForCompare(wt)) {
+    throw new UsageError(
+      `--repo must not be the worktree itself (${repo}) — merging a branch into its own worktree is a no-op that looks like success`
+    );
+  }
+  const listOut = git(deps, repo, ['worktree', 'list', '--porcelain']);
+  const worktreePaths = listOut
+    .split('\n')
+    .filter(l => l.startsWith('worktree '))
+    .map(l => normalizePathForCompare(l.slice('worktree '.length).trim()));
+  if (!worktreePaths.includes(normalizePathForCompare(wt))) {
+    throw new UsageError(
+      `--repo ${repo} does not list ${wt} in 'git -C ${repo} worktree list' — refusing a mismatched repo/worktree pair`
+    );
+  }
+}
+
+/** Mutates config.repo in place (resolving or validating it) and returns it. */
+function resolveRepo(config, deps) {
+  if (!config.repo) {
+    config.repo = resolveRepoFromWorktree(deps, config.worktree);
+    return config.repo;
+  }
+  assertRepoOwnsWorktree(deps, config.repo, config.worktree);
+  return config.repo;
+}
+
+function copyDirRecursive(fs, src, dst) {
+  if (!fs.existsSync(src)) return;
+  fs.mkdirSync(dst, { recursive: true });
+  for (const entry of fs.readdirSync(src)) {
+    const s = path.join(src, entry);
+    const d = path.join(dst, entry);
+    const st = fs.statSync(s);
+    if (st.isDirectory()) copyDirRecursive(fs, s, d);
+    else fs.copyFileSync(s, d);
+  }
+}
+
+/**
+ * Old/escape-hatch route (--rust-in-worktree, R3): cold-builds in the task
+ * worktree itself, exactly as before TASK_2084 — kept verbatim (same spawn
+ * args) so this remains a faithful fallback when the shared verify worktree
+ * is broken or unavailable.
+ */
+function runRustInWorktree(deps, config, filter) {
+  const targetDir = resolveVerifyTargetDir(deps.env, deps.platform);
+  const env = Object.assign({}, deps.env, { CARGO_TARGET_DIR: targetDir, SKIP_SIDECAR_STAGING: '1' });
+  const res = deps.spawnSync('node', ['dev/scripts/run-rust-tests.js', filter], {
+    cwd: config.worktree,
+    env,
+    encoding: 'utf8',
+  });
+  const output = (res.stdout || '') + (res.stderr || '');
+  const match = /test result: ok\. (\d+) passed; (\d+) failed/.exec(output);
+  const ok = res.status === 0 && !!match;
+  const summary = match
+    ? `${match[1]} passed, ${match[2]} failed (route=in-worktree)`
+    : `no 'test result: ok.' line (exit ${res.status}) (route=in-worktree)`;
+  return { ok, summary, log: output };
+}
+
+/**
+ * Default route (TASK_2084, R1): runs through dev/scripts/
+ * rust-verify-worktree.js's canonical, warm, fixed-source-root verify
+ * worktree instead of cold-building kuzu in the task worktree — cwd =
+ * config.repo, never config.worktree, since the script resolves its own
+ * fixed worktree path relative to the main repo. `extraArgs` lets the
+ * negative control inject --overlay-from without touching the task
+ * worktree (R2).
+ */
+function runRustViaVerifyWorktree(deps, config, filter, branch, extraArgs) {
+  const scriptPath = path.join(config.repo, 'dev', 'scripts', 'rust-verify-worktree.js');
+  const lockWaitS = config.rustLockWaitS != null ? config.rustLockWaitS : DEFAULT_RUST_LOCK_WAIT_S;
+  const maxS = config.rustMaxS != null ? config.rustMaxS : DEFAULT_RUST_MAX_S;
+  const args = [
+    scriptPath, 'run', branch, filter,
+    ...(extraArgs || []),
+    '--lock-wait-s', String(lockWaitS),
+    '--max-s', String(maxS),
+  ];
+  const res = deps.spawnSync('node', args, { cwd: config.repo, encoding: 'utf8' });
+  const output = (res.stdout || '') + (res.stderr || '');
+  if (res.status === 75) {
+    return { ok: false, summary: 'verify worktree busy', log: output };
+  }
+  if (res.status === 124) {
+    return { ok: false, summary: 'rust verify timed out', log: output };
+  }
+  const match = /test result: ok\. (\d+) passed; (\d+) failed/.exec(output);
+  const ok = res.status === 0 && !!match;
+  const summary = match
+    ? `${match[1]} passed, ${match[2]} failed (route=verify-worktree)`
+    : `no 'test result: ok.' line (exit ${res.status}) (route=verify-worktree)`;
+  return { ok, summary, log: output };
+}
+
+function runRustOnce(deps, config, filter, branch) {
+  if (config.rustInWorktree) {
+    return runRustInWorktree(deps, config, filter);
+  }
+  return runRustViaVerifyWorktree(deps, config, filter, branch, []);
+}
+
+function runNodeOnce(deps, config, file) {
+  const res = deps.spawnSync('node', ['--test', file], { cwd: config.worktree, encoding: 'utf8' });
+  const output = (res.stdout || '') + (res.stderr || '');
+  const passMatch = /ℹ pass (\d+)/.exec(output);
+  const failMatch = /ℹ fail (\d+)/.exec(output);
+  const failCount = failMatch ? parseInt(failMatch[1], 10) : null;
+  const ok = res.status === 0 && failCount === 0;
+  const summary = passMatch && failMatch
+    ? `${passMatch[1]} pass, ${failMatch[1]} fail`
+    : `exit ${res.status}, no pass/fail summary found`;
+  return { ok, summary, log: output };
+}
+
+// ── step implementations ────────────────────────────────────────────────────
+// Each returns { ok, summary, log } and may mutate `ctx` for downstream
+// steps (branch name, pre/post-merge heads). Thrown errors are caught by
+// the executeStep wrapper in runVerifyAndLand and converted to a failed
+// step — the neg-control step relies on this for its finally-restore.
+
+function stepPreflight(config, deps, ctx) {
+  const branch = git(deps, config.worktree, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  ctx.branch = branch;
+  // Ignore the same dispatch-telemetry paths the worktree's own commit step
+  // excludes (TASK_2069) — a subagent worktree normally carries an untracked
+  // .kenaz/specialist/progress_note_TASK_<id>.json by design, and refusing on
+  // it made hand-cleaning (a glob) the only workaround, which once swept up
+  // tracked historical notes too. Anything outside these paths still refuses.
+  const statusOut = git(deps, config.worktree, [
+    'status', '--short', '--', '.', ...WORKTREE_COMMIT_EXCLUDE_PATHSPECS,
+  ]);
+  if (statusOut.trim() !== '') {
+    const lines = statusOut.split('\n').filter(Boolean);
+    const untracked = lines.filter(l => l.startsWith('??'));
+    const tracked = lines.filter(l => !l.startsWith('??'));
+    let summary;
+    if (tracked.length && untracked.length) {
+      summary = `worktree has tracked changes and untracked files, refusing: ${lines.slice(0, 5).join('; ')}`;
+    } else if (tracked.length) {
+      summary = `worktree has tracked changes, refusing: ${tracked.slice(0, 5).join('; ')}`;
+    } else {
+      summary = `worktree has untracked files, refusing: ${untracked.slice(0, 5).join('; ')}`;
+    }
+    return { ok: false, summary, log: statusOut };
+  }
+  // HEAD..<branch> in config.repo — the ref stepMerge actually merges into
+  // (checked out HEAD there), not a hardcoded main..<branch> (TASK_2069:
+  // config.repo's checked-out branch is not guaranteed to be named "main").
+  const countOut = git(deps, config.repo, ['rev-list', '--count', `HEAD..${branch}`]);
+  const count = parseInt(countOut, 10) || 0;
+  if (count === 0) {
+    return { ok: false, summary: `branch ${branch} has 0 commits ahead of main`, log: countOut };
+  }
+  // preMergeHead is captured fresh inside stepMerge (immediately before the
+  // merge attempt) rather than here — merge verification needs the HEAD
+  // that was actually current the instant before `git merge` ran.
+  return { ok: true, summary: `branch=${branch} commits_ahead=${count}`, log: statusOut };
+}
+
+function stepCopyRustResources(config, deps) {
+  const onnxSrc = path.join(config.repo, 'dashboard', 'src-tauri', 'resources', 'onnx');
+  const onnxDst = path.join(config.worktree, 'dashboard', 'src-tauri', 'resources', 'onnx');
+  const ptySrc = path.join(config.repo, 'dashboard', 'src-tauri', 'pty-server.exe');
+  const ptyDst = path.join(config.worktree, 'dashboard', 'src-tauri', 'pty-server.exe');
+  copyDirRecursive(deps.fs, onnxSrc, onnxDst);
+  if (deps.fs.existsSync(ptySrc)) {
+    deps.fs.mkdirSync(path.dirname(ptyDst), { recursive: true });
+    deps.fs.copyFileSync(ptySrc, ptyDst);
+  }
+  return { ok: true, summary: 'copied onnx resources + pty-server.exe into worktree', log: '' };
+}
+
+function stepRust(config, deps, ctx, filter) {
+  return runRustOnce(deps, config, filter, ctx.branch);
+}
+
+function stepNode(config, deps, ctx, file) {
+  return runNodeOnce(deps, config, file);
+}
+
+/**
+ * TASK_2084 R2: a `rust:<filter>` negative control routes through the warm
+ * verify worktree too, via --overlay-from main:<negFile> — the checked-out
+ * task branch's tree gets main's version of just that one file swapped in
+ * for the run, instead of this process rewriting the file inside the task
+ * worktree (which would force a cold in-worktree cargo run to observe it).
+ * Nothing here touches config.worktree, so there is nothing to restore —
+ * the next rust-verify-worktree.js run's `checkout --force` discards it.
+ */
+function stepNegativeControlRustWarm(config, deps, ctx) {
+  const filter = config.negTest.slice('rust:'.length);
+  const testResult = runRustViaVerifyWorktree(deps, config, filter, ctx.branch, [
+    '--overlay-from', `main:${config.negFile}`,
+  ]);
+  if (testResult.summary === 'verify worktree busy' || testResult.summary === 'rust verify timed out') {
+    // Infra failure, not a verification signal — propagate as-is rather
+    // than reinterpreting it as "negative control passed/failed".
+    return testResult;
+  }
+  return testResult.ok
+    ? {
+        ok: false,
+        summary: `negative control PASSED on main's version of ${config.negFile} — test does not detect the change`,
+        log: testResult.log,
+      }
+    : {
+        ok: true,
+        summary: `negative control correctly failed on main's version (${testResult.summary})`,
+        log: testResult.log,
+      };
+}
+
+function stepNegativeControl(config, deps, ctx) {
+  const isRustNeg = typeof config.negTest === 'string' && config.negTest.startsWith('rust:');
+  if (isRustNeg && !config.rustInWorktree) {
+    return stepNegativeControlRustWarm(config, deps, ctx);
+  }
+  const absPath = path.join(config.worktree, config.negFile);
+  const backup = deps.fs.readFileSync(absPath);
+  let result;
+  try {
+    const showRes = deps.spawnSync('git', ['-C', config.repo, 'show', `main:${config.negFile}`], {
+      encoding: 'buffer',
+    });
+    if (showRes.status !== 0) {
+      throw new Error(`git show main:${config.negFile} failed (exit ${showRes.status}): ${(showRes.stderr || '').toString()}`);
+    }
+    deps.fs.writeFileSync(absPath, showRes.stdout);
+    const spec = config.negTest;
+    const testResult = spec.startsWith('rust:')
+      ? runRustOnce(deps, config, spec.slice('rust:'.length))
+      : runNodeOnce(deps, config, spec);
+    result = testResult.ok
+      ? {
+          ok: false,
+          summary: `negative control PASSED on main's version of ${config.negFile} — test does not detect the change`,
+          log: testResult.log,
+        }
+      : {
+          ok: true,
+          summary: `negative control correctly failed on main's version (${testResult.summary})`,
+          log: testResult.log,
+        };
+  } finally {
+    // Always restore, byte-for-byte, even if the block above threw.
+    deps.fs.writeFileSync(absPath, backup);
+    const statusOut = git(deps, config.worktree, ['status', '--short']);
+    if (statusOut.trim() !== '') {
+      result = { ok: false, summary: `worktree not clean after neg-control restore: ${statusOut}`, log: statusOut };
+    }
+  }
+  return result;
+}
+
+/**
+ * TASK_2176: authoritative, serialized heavyweight verification for
+ * projects declaring `verify_offline` in project.yaml (Unity/Unreal/mobile:
+ * one shared editor/tool instance that cannot run two verifications at
+ * once). Runs on config.repo -- the main tree, NEVER config.worktree; the
+ * worktree agent already ran this command as a non-authoritative self-check
+ * during implementation (see dispatch.js resolveDispatchIsolation). Two
+ * cards from the same project can implement in parallel worktrees, but
+ * their landings must never run the heavyweight tool concurrently, so this
+ * step is serialized through the SAME per-project dispatch lock serial_lock
+ * dispatches use (utils.dispatchLockPath/tryAcquireDispatchLock -- "do not
+ * copy the check", see that file's own comments) rather than a second lock
+ * scheme. The lock here is held only for the duration of this one command
+ * (not the whole dispatch lifecycle like serial_lock) and is ALWAYS
+ * released in the finally, success or failure, so a failed heavyweight
+ * check never permanently blocks the next landing (the dispatch lock's own
+ * 60min staleness is a backstop, not the primary release path here).
+ */
+function stepVerifyOffline(config, deps) {
+  const lockFile = deps.dispatchLockPath(config.repo);
+  const acq = deps.tryAcquireDispatchLock(lockFile, {
+    sessionId: 'verify-and-land', taskId: config.task, pid: null, holder: 'verify-offline',
+  });
+  if (!acq.acquired) {
+    const h = acq.holder || {};
+    return {
+      ok: false,
+      summary: `offline verify lock held (task=${h.taskId || '?'}, since=${h.startedAt || '?'}) -- `
+        + 'another landing\'s heavyweight verification is in progress on this project; wait and retry',
+      log: '',
+    };
+  }
+  try {
+    const res = deps.spawnSync(config.verifyOfflineCmd, [], { shell: true, encoding: 'utf8', cwd: config.repo });
+    const output = (res.stdout || '') + (res.stderr || '');
+    return { ok: res.status === 0, summary: `verify_offline exit ${res.status}`, log: output };
+  } finally {
+    try { deps.fs.unlinkSync(lockFile); } catch { /* best-effort release */ }
+  }
+}
+
+/**
+ * Merge is verified, never assumed (TASK_2059 follow-up: a dogfood run
+ * defaulted --repo to the worktree itself, so `git merge` reported
+ * "Already up to date" — exit 0, no conflict — and the step was recorded
+ * ok=true even though main never moved). After a zero-exit merge we require
+ * BOTH: (a) repo HEAD actually changed, and (b) the branch tip is now an
+ * ancestor of HEAD. Either check failing — including the "already
+ * up-to-date" case — fails this step.
+ */
+function stepMerge(config, deps, ctx) {
+  const beforeHead = git(deps, config.repo, ['rev-parse', 'HEAD']);
+  ctx.preMergeHead = beforeHead;
+  const args = ['-C', config.repo, 'merge', '--no-ff', ctx.branch];
+  if (config.messageFile) args.push('-F', config.messageFile);
+  const res = deps.spawnSync('git', args, { encoding: 'utf8' });
+  const output = (res.stdout || '') + (res.stderr || '');
+  if (res.status !== 0) {
+    deps.spawnSync('git', ['-C', config.repo, 'merge', '--abort'], { encoding: 'utf8' });
+    return { ok: false, summary: `merge failed/conflict, aborted: ${output.slice(0, 500)}`, log: output };
+  }
+  const afterHead = git(deps, config.repo, ['rev-parse', 'HEAD']);
+  const branchTip = git(deps, config.repo, ['rev-parse', ctx.branch]);
+  const headMoved = afterHead !== beforeHead;
+  let isAncestor = false;
+  if (headMoved) {
+    const ancestorCheck = deps.spawnSync(
+      'git',
+      ['-C', config.repo, 'merge-base', '--is-ancestor', branchTip, afterHead],
+      { encoding: 'utf8' }
+    );
+    isAncestor = ancestorCheck.status === 0;
+  }
+  if (!headMoved || !isAncestor) {
+    return {
+      ok: false,
+      summary: `merge did not land: HEAD ${headMoved ? 'moved but' : 'unchanged'} `
+        + `(${beforeHead.slice(0, 8)} -> ${afterHead.slice(0, 8)}), branch-tip-is-ancestor=${isAncestor}. `
+        + `git output: ${output.slice(0, 300)}`,
+      log: output,
+    };
+  }
+  ctx.postMergeHead = afterHead;
+  return { ok: true, summary: `merged ${ctx.branch} into main (${beforeHead.slice(0, 8)} -> ${afterHead.slice(0, 8)})`, log: output };
+}
+
+/**
+ * TASK_2142 R2: bakes the landed commit sha and a short verification
+ * summary into the card's `technical_notes` BEFORE running `complete` --
+ * `complete` -> `moveTask('done', ...)` is the single choke point that
+ * pushes the card's full_yaml to the Task Pool relay row (see
+ * .formation/tools/pool-status-push.js), so writing the info here is what
+ * makes it show up in the relay's / dashboard's graveyard view. Best-effort:
+ * a failed `update` call here never blocks the actual completion below --
+ * only `res.status` from the `complete` call decides this step's ok/fail.
+ */
+/**
+ * Path of a Kenaz core tool (e.g. `.collaboration/core/task-api.js`). A sub-project
+ * repo only holds `.kenaz/`, so the tool comes from: the repo itself (core repo),
+ * else `.kenaz/project.yaml` core_path, else the core checkout this script runs from.
+ */
+function coreToolPath(config, rel) {
+  const inRepo = path.join(config.repo, rel);
+  if (fs.existsSync(inRepo)) return inRepo;
+  try {
+    const yaml = fs.readFileSync(path.join(config.repo, '.kenaz', 'project.yaml'), 'utf8');
+    const m = yaml.match(/^core_path:\s*["']?([^"'\r\n]+?)["']?\s*$/m);
+    if (m && fs.existsSync(path.join(m[1], rel))) return path.join(m[1], rel);
+  } catch { /* no project.yaml: fall through */ }
+  return path.join(__dirname, '..', '..', '..', rel);
+}
+
+function writeLandingInfo(config, deps, ctx) {
+  if (!ctx || !ctx.postMergeHead) return; // no merge landed (--no-merge etc.) -- nothing to record
+  const shortSha = ctx.postMergeHead.slice(0, 8);
+  const passedNames = (ctx.steps || []).filter((s) => s.ok).map((s) => s.name);
+  const verifySummary = `${passedNames.length} step(s) passed: ${passedNames.join(', ')}`.slice(0, 400);
+  const taskApi = coreToolPath(config, path.join('.collaboration', 'core', 'task-api.js'));
+  deps.spawnSync(
+    'node',
+    [
+      taskApi, '--project-path', config.repo, 'update', config.task,
+      '--technical-notes', `Landed commit: ${ctx.postMergeHead}`,
+      '--technical-notes', `Verification: ${verifySummary}`,
+      '--append',
+    ],
+    { encoding: 'utf8' }
+  );
+}
+
+function stepTaskComplete(config, deps, ctx) {
+  writeLandingInfo(config, deps, ctx);
+  const taskApi = coreToolPath(config, path.join('.collaboration', 'core', 'task-api.js'));
+  const res = deps.spawnSync('node', [taskApi, '--project-path', config.repo, 'complete', config.task], {
+    encoding: 'utf8',
+  });
+  const output = (res.stdout || '') + (res.stderr || '');
+  return { ok: res.status === 0, summary: `task-api complete exit ${res.status}`, log: output };
+}
+
+function stepMarkLanded(config, deps) {
+  const hook = coreToolPath(config, path.join('.claude', 'hooks', 'worktree-create.js'));
+  const wtBase = path.basename(config.worktree);
+  const res = deps.spawnSync(
+    'node',
+    [hook, 'mark-landed', wtBase, '--task', config.task, '--by', 'ansuz', '--repo', config.repo],
+    { encoding: 'utf8' }
+  );
+  const output = (res.stdout || '') + (res.stderr || '');
+  return { ok: res.status === 0, summary: `mark-landed exit ${res.status}`, log: output };
+}
+
+async function stepWaitBackend(config, deps, ctx) {
+  if (!ctx.preMergeHead || !ctx.postMergeHead) {
+    return { ok: true, summary: 'no merge occurred; wait-backend skipped', log: '' };
+  }
+  const diffOut = git(deps, config.repo, ['diff', '--name-only', ctx.preMergeHead, ctx.postMergeHead]);
+  const touchedRs = diffOut.split('\n').some(f => f.trim().toLowerCase().endsWith('.rs'));
+  if (!touchedRs) {
+    return { ok: true, summary: 'merge touched no .rs files; wait-backend skipped', log: diffOut };
+  }
+  const resolveLogPath = deps.resolveBackendLogPath;
+  const readTail = deps.readBackendLogTailSync;
+  if (typeof resolveLogPath !== 'function' || typeof readTail !== 'function') {
+    return { ok: false, summary: 'backend log path resolver unavailable', log: '' };
+  }
+  const logPath = resolveLogPath();
+  if (!logPath) {
+    return { ok: false, summary: 'could not resolve backend log path for this platform', log: '' };
+  }
+  const mergeTime = deps.now();
+  const deadline = mergeTime + config.waitBackendTimeoutMs;
+  // Non-blocking poll (async/setTimeout via deps.sleep), never busy-wait.
+  while (deps.now() < deadline) {
+    const tail = readTail(logPath, 64 * 1024);
+    const started = latestStartedAtAfter(tail, mergeTime);
+    if (started) {
+      return { ok: true, summary: `backend restarted at ${started}`, log: (tail || '').slice(-2000) };
+    }
+    await deps.sleep(config.waitBackendPollMs);
+  }
+  return { ok: false, summary: `backend did not restart within ${config.waitBackendTimeoutMs}ms`, log: '' };
+}
+
+function stepLive(config, deps) {
+  const res = deps.spawnSync(config.live, [], { shell: true, encoding: 'utf8', cwd: config.worktree });
+  const output = (res.stdout || '') + (res.stderr || '');
+  const lastLines = output.split('\n').slice(-20).join('\n');
+  return { ok: res.status === 0, summary: `live cmd exit ${res.status}`, log: lastLines };
+}
+
+async function executeStep(stepDef, config, deps, ctx) {
+  switch (stepDef.kind) {
+    case 'preflight': return stepPreflight(config, deps, ctx);
+    case 'copy-rust-resources': return stepCopyRustResources(config, deps);
+    case 'rust': return stepRust(config, deps, ctx, stepDef.filter);
+    case 'node': return stepNode(config, deps, ctx, stepDef.file);
+    case 'neg': return stepNegativeControl(config, deps, ctx);
+    case 'verify-offline': return stepVerifyOffline(config, deps);
+    case 'merge': return stepMerge(config, deps, ctx);
+    case 'task-complete': return stepTaskComplete(config, deps, ctx);
+    case 'mark-landed': return stepMarkLanded(config, deps);
+    case 'wait-backend': return stepWaitBackend(config, deps, ctx);
+    case 'live': return stepLive(config, deps);
+    default: throw new Error(`unknown step kind: ${stepDef.kind}`);
+  }
+}
+
+// ── orchestrator ─────────────────────────────────────────────────────────
+
+async function runVerifyAndLand(rawConfig, injectedDeps) {
+  const config = Object.assign(
+    {
+      rustFilters: [], nodeTests: [], noMerge: false, mergeWithoutTests: false, waitBackend: false,
+      waitBackendTimeoutMs: 10 * 60 * 1000, waitBackendPollMs: 5000, dryRun: false,
+      rustLockWaitS: DEFAULT_RUST_LOCK_WAIT_S, rustMaxS: DEFAULT_RUST_MAX_S, rustInWorktree: false,
+    },
+    rawConfig
+  );
+  // Refuse before doing anything — including before the --dry-run branch,
+  // which exists precisely to preview what would happen (a dry-run must not
+  // silently show a zero-verification merge as if it were fine).
+  validateConfig(config);
+  const deps = Object.assign(defaultDeps(), injectedDeps);
+
+  // Resolve/validate --repo from the worktree via git plumbing (never from
+  // this script's own __dirname — see resolveRepoFromWorktree). Read-only
+  // git queries (rev-parse/worktree list), so this runs before the
+  // --dry-run branch too: a dry run must fail exactly where a real run
+  // would (e.g. --repo == --worktree), not just when it happens to print a
+  // plan.
+  resolveRepo(config, deps);
+
+  // TASK_2176: resolved BEFORE buildPlan (and before the --dry-run branch,
+  // same reasoning as resolveRepo above -- a dry run must show the real
+  // plan, including whether the heavyweight gate is present) so buildPlan
+  // can decide whether to include the verify-offline step purely from
+  // config.verifyOfflineCmd. A read-only project.yaml lookup via deps.fs,
+  // same "no mutating side effects before dry-run" contract as everything
+  // else at this point in the function.
+  config.verifyOfflineCmd = resolveVerifyOfflineCmd(config, deps);
+
+  const plan = buildPlan(config);
+
+  // --dry-run: plan only, never touch deps beyond the read-only repo
+  // resolution above (no spawnSync/fs writes/anything else).
+  if (config.dryRun) {
+    return {
+      task: config.task,
+      branch: null,
+      repo: config.repo,
+      ok: true,
+      failed_step: null,
+      dry_run: true,
+      steps: plan.map(s => ({ name: s.name, planned: true })),
+    };
+  }
+
+  const logDir = config.logDir || path.join(deps.tmpdir(), 'verify-and-land', `${config.task}-${deps.now()}`);
+  deps.fs.mkdirSync(logDir, { recursive: true });
+
+  const ctx = { branch: null };
+  const steps = [];
+  // TASK_2142 R2: same array reference, mutated in place as each step
+  // completes -- by the time the 'task-complete' step runs, ctx.steps holds
+  // every prior step's result (used to build the landing verification
+  // summary in writeLandingInfo()).
+  ctx.steps = steps;
+  let failedStep = null;
+  let overallOk = true;
+
+  for (const stepDef of plan) {
+    const start = deps.now();
+    let outcome;
+    try {
+      outcome = await executeStep(stepDef, config, deps, ctx);
+    } catch (err) {
+      outcome = { ok: false, summary: `threw: ${err && err.message}`, log: (err && err.stack) || String(err) };
+    }
+    const duration_ms = deps.now() - start;
+    const logFile = path.join(logDir, `${sanitizeName(stepDef.name)}.log`);
+    try {
+      deps.fs.writeFileSync(logFile, outcome.log || '');
+    } catch {
+      /* best-effort log write; never fail the step over a log write */
+    }
+    steps.push({ name: stepDef.name, ok: !!outcome.ok, summary: outcome.summary, duration_ms, log: logFile });
+    if (!outcome.ok) {
+      overallOk = false;
+      failedStep = stepDef.name;
+      break;
+    }
+  }
+
+  return { task: config.task, branch: ctx.branch, ok: overallOk, failed_step: failedStep, steps };
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────
+
+const USAGE =
+  'usage: verify-and-land.js --task TASK_ID --worktree <path> [--repo <path>] [--rust f1,f2]... ' +
+  '[--node f1,f2]... [--neg-file <path> --neg-test <file|rust:filter>] [--message-file <path>] ' +
+  '[--no-merge] [--merge-without-tests] [--wait-backend] [--wait-backend-timeout-ms <ms>] ' +
+  '[--live "<cmd>"] [--log-dir <path>] [--dry-run] ' +
+  '[--rust-lock-wait-s <n>] [--rust-max-s <n>] [--rust-in-worktree]\n';
+
+async function main() {
+  let config;
+  try {
+    config = parseArgs(process.argv.slice(2));
+    validateConfig(config);
+  } catch (err) {
+    if (err instanceof UsageError) {
+      process.stderr.write(`[verify-and-land] ${err.message}\n${USAGE}`);
+      process.exit(2);
+    }
+    throw err;
+  }
+  // --repo (when omitted) and its cross-check with --worktree (when given)
+  // are resolved inside runVerifyAndLand via git plumbing — it needs deps,
+  // which only exist here. A resolution/validation failure is a usage
+  // error (exit 2), not a pipeline failure (exit 1).
+  let result;
+  try {
+    result = await runVerifyAndLand(config, defaultDeps());
+  } catch (err) {
+    if (err instanceof UsageError) {
+      process.stderr.write(`[verify-and-land] ${err.message}\n${USAGE}`);
+      process.exit(2);
+    }
+    throw err;
+  }
+  process.stdout.write(JSON.stringify(result) + '\n');
+  process.exit(result.ok ? 0 : 1);
+}
+
+if (require.main === module) {
+  main().catch(err => {
+    process.stderr.write(`[verify-and-land] fatal: ${err && err.stack}\n`);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  parseArgs,
+  validateConfig,
+  buildPlan,
+  runVerifyAndLand,
+  defaultDeps,
+  resolveVerifyTargetDir,
+  latestStartedAtAfter,
+  resolveRepoFromWorktree,
+  coreToolPath,
+  assertRepoOwnsWorktree,
+  resolveRepo,
+  UsageError,
+  runRustInWorktree,
+  runRustViaVerifyWorktree,
+  DEFAULT_RUST_LOCK_WAIT_S,
+  DEFAULT_RUST_MAX_S,
+  resolveVerifyOfflineCmd,
+  stepVerifyOffline,
+};