create-walle 0.10.2 → 0.10.3

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

@@ -0,0 +1,344 @@
+'use strict';
+// WP-0 (docs/local-landing-queue-multi-session-integration-2026-10-26.html §5 D-3/D-5/D-11,
+// §6.2, §8 WP-0): the git plumbing the landing queue is built on. Zero runtime deps.
+//
+// Three hard rules this module exists to enforce:
+//
+//  1. Every git child runs with `--no-optional-locks` (D-11 / I-7): a `git status`-style
+//     probe must never leave `index.lock` in a session worktree.
+//  2. Every git child env is `process.env` MINUS the §4 GIT_* list (same seven names as
+//     bin/git-test-env.js; the two lists are asserted equal by
+//     tests/landing-git-primitives.test.js). I-8 is the incident: a leaked GIT_DIR made a
+//     gate/test process operate on the wrong repository and wipe real refs.
+//  3. Nothing here writes into a session worktree. The train commit is built from
+//     `merge-tree`/`commit-tree` objects only; the one exception is `snapshotCommit`, which
+//     uses a TEMP INDEX outside the worktree so the real index (and its lock) is untouched.
+//
+// This file is the lowest-level module of lib/landing/ (no local requires), so it also hosts
+// the shared typed-error helper `landingError` used by state.js/lease.js/config.js — that
+// keeps the directory to the four files WP-0 owns instead of adding a fifth just for 5 lines.
+//
+// Error contract: every throw is an Error with `.code` set to a typed string
+// (`git_failed`, `cas_lost`, `target_dirty`, ...), per §6.2's exit-code/typed-error contract.
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const crypto = require('crypto');
+const path = require('path');
+
+const MAX_BUFFER = 64 * 1024 * 1024;
+
+// §4 / bin/git-test-env.js: GIT_CONTEXT_ENV_KEYS. Copied (not required: lib/ must not depend on
+// bin/, whose files are pinned by bin/test-broker-protocol.manifest.json, I-6); a unit test
+// asserts the two arrays stay equal so drift is caught.
+const SCRUBBED_ENV = Object.freeze([
+  'GIT_DIR',
+  'GIT_WORK_TREE',
+  'GIT_INDEX_FILE',
+  'GIT_PREFIX',
+  'GIT_OBJECT_DIRECTORY',
+  'GIT_COMMON_DIR',
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+]);
+
+const OID_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+
+// Git's own refusal wording when a fast-forward would clobber local state (§1.6 V-4).
+const OVERWRITE_HEADERS = [
+  'error: Your local changes to the following files would be overwritten by merge:',
+  'error: The following untracked working tree files would be overwritten by merge:',
+];
+
+function landingError(code, message, extra) {
+  const err = new Error(message);
+  err.code = code;
+  if (extra) Object.assign(err, extra);
+  return err;
+}
+
+// process.env minus the §4 GIT_* list, plus `extra`. `extra` is applied AFTER the scrub, which
+// is what lets snapshotCommit pass GIT_INDEX_FILE=<tmp> on purpose.
+function childEnv(extra) {
+  const env = { ...process.env };
+  for (const key of SCRUBBED_ENV) delete env[key];
+  if (extra) Object.assign(env, extra);
+  return env;
+}
+
+// Raw spawn: never throws on a non-zero exit (the wrappers below need to inspect it).
+function runGitRaw(cwd, args, opts = {}) {
+  const res = spawnSync('git', ['--no-optional-locks', ...args], {
+    cwd,
+    env: childEnv(opts.env),
+    encoding: 'utf8',
+    maxBuffer: opts.maxBuffer || MAX_BUFFER,
+    input: opts.input === undefined ? undefined : opts.input,
+  });
+  if (res.error) {
+    throw landingError('git_failed', `git ${args.join(' ')}: ${res.error.message}`, { args, cwd, cause: res.error });
+  }
+  return { status: res.status, stdout: res.stdout || '', stderr: res.stderr || '' };
+}
+
+function gitFailed(cwd, args, res) {
+  const detail = String(res.stderr || res.stdout || '').trim();
+  return landingError('git_failed', `git ${args.join(' ')} exited ${res.status}${detail ? `: ${detail}` : ''}`, {
+    args, cwd, status: res.status, stderr: res.stderr, stdout: res.stdout,
+  });
+}
+
+// Sync `git` that throws `git_failed` on any non-zero exit and returns stdout.
+function git(cwd, args, opts = {}) {
+  const res = runGitRaw(cwd, args, opts);
+  if (res.status !== 0) throw gitFailed(cwd, args, res);
+  return res.stdout;
+}
+
+// --- read-only helpers ---------------------------------------------------------------------
+
+function revParseOrNull(cwd, rev, opts = {}) {
+  const res = runGitRaw(cwd, ['rev-parse', '--verify', '--quiet', rev], opts);
+  if (res.status !== 0) return null;
+  const value = res.stdout.trim();
+  return value || null;
+}
+
+function revParse(cwd, rev, opts = {}) {
+  const value = revParseOrNull(cwd, rev, opts);
+  if (value === null) {
+    throw landingError('git_failed', `cannot resolve revision ${JSON.stringify(rev)} in ${cwd}`, { rev, cwd });
+  }
+  return value;
+}
+
+// Absolute path of the repository's common git dir (shared by every worktree of the repo).
+// Memoized per resolved cwd: it cannot change while this process runs, and every state path
+// (state.landingDir) and every radar cache read goes through it -- un-memoized, a plain
+// `land status` on a 413-worktree repo spent 46 s of its 128 s spawning this one rev-parse.
+// Only successes are kept, so a cwd that is not a repo yet still fails every time.
+const COMMON_DIR_CACHE = new Map();
+function commonDir(cwd) {
+  const key = path.resolve(cwd);
+  let value = COMMON_DIR_CACHE.get(key);
+  if (value === undefined) {
+    value = git(cwd, ['rev-parse', '--path-format=absolute', '--git-common-dir']).trim();
+    COMMON_DIR_CACHE.set(key, value);
+  }
+  return value;
+}
+
+// Absolute path of the git dir for THIS worktree (`.git/worktrees/<n>` for a linked one).
+function gitDir(cwd) {
+  return git(cwd, ['rev-parse', '--path-format=absolute', '--git-dir']).trim();
+}
+
+function isAncestor(cwd, ancestor, descendant, opts = {}) {
+  const res = runGitRaw(cwd, ['merge-base', '--is-ancestor', ancestor, descendant], opts);
+  if (res.status === 0) return true;
+  if (res.status === 1) return false;
+  throw gitFailed(cwd, ['merge-base', '--is-ancestor', ancestor, descendant], res);
+}
+
+function isGitRepo(cwd) {
+  const res = runGitRaw(cwd, ['rev-parse', '--git-dir']);
+  return res.status === 0;
+}
+
+// Absolute, symlink-resolved path of the worktree root (the directory the queue's `.ctm.json`
+// may live in — a worktree's own root, not the common dir). Outside a repository there is no
+// toplevel, and that is a typed refusal rather than a silent fallback (§6.1).
+function toplevel(cwd) {
+  const res = runGitRaw(cwd, ['rev-parse', '--show-toplevel']);
+  if (res.status !== 0) {
+    throw landingError('not_a_repo', `not inside a git repository: ${cwd}`, {
+      cwd, status: res.status, stderr: String(res.stderr || '').trim(),
+    });
+  }
+  const top = res.stdout.trim();
+  if (!top) {
+    throw landingError('not_a_repo', `git reported no toplevel for ${cwd}`, { cwd, status: res.status });
+  }
+  return fs.realpathSync(top);
+}
+
+// --- D-3: worktree-free train commit -------------------------------------------------------
+
+// `git merge-tree --write-tree --name-only <base> <tip>` (observed §1.6 V-1/V-2).
+//   exit 0 -> { tree, conflicts: [] }
+//   exit 1 -> { tree, conflicts: [paths...] } (first line is the tree oid, then the conflicted
+//             paths up to the first blank line, then git's informational block)
+//   other  -> throw git_failed
+// A merge driver is free to print to stdout, so the tree oid is located by shape rather than by
+// assuming it is line 1.
+function mergeTree(cwd, base, tip, opts = {}) {
+  const args = ['merge-tree', '--write-tree', '--name-only', base, tip];
+  const res = runGitRaw(cwd, args, opts);
+  if (res.status !== 0 && res.status !== 1) throw gitFailed(cwd, args, res);
+  const lines = res.stdout.split('\n').map((line) => line.replace(/\r$/, ''));
+  let index = 0;
+  while (index < lines.length && !OID_RE.test(lines[index].trim())) index += 1;
+  if (index >= lines.length) {
+    throw landingError('git_failed', `git merge-tree produced no tree oid for ${base}..${tip}`, {
+      base, tip, cwd, status: res.status, stdout: res.stdout,
+    });
+  }
+  const tree = lines[index].trim();
+  const conflicts = [];
+  for (let i = index + 1; i < lines.length; i += 1) {
+    if (lines[i] === '') break;
+    conflicts.push(lines[i]);
+  }
+  return { tree, conflicts };
+}
+
+function commitTree(cwd, tree, parents = [], message = '', opts = {}) {
+  const args = ['commit-tree', tree];
+  for (const parent of parents) args.push('-p', parent);
+  args.push('-m', message);
+  return git(cwd, args, opts).trim();
+}
+
+// --- D-5: landing the train ----------------------------------------------------------------
+
+// `git update-ref <ref> <new> <old>` is a compare-and-swap (observed §1.6 V-3). On failure the
+// ref is re-read: only a genuinely different current value is `cas_lost`; anything else is a
+// real git failure.
+function casUpdateRef(cwd, ref, newSha, oldSha, opts = {}) {
+  const args = ['update-ref', ref, newSha, oldSha];
+  const res = runGitRaw(cwd, args, opts);
+  if (res.status === 0) return true;
+  const current = revParseOrNull(cwd, ref);
+  if (current !== oldSha) {
+    throw landingError('cas_lost', `ref ${ref} is at ${current || '(absent)'}, expected ${oldSha}`, {
+      ref, expected: oldSha, current, cwd, stderr: res.stderr,
+    });
+  }
+  throw gitFailed(cwd, args, res);
+}
+
+// Paths git lists under an "…would be overwritten" header (tab-indented, one per line).
+function parseOverwritePaths(stderr) {
+  const lines = String(stderr || '').split('\n');
+  const paths = [];
+  let collecting = false;
+  for (const line of lines) {
+    if (!collecting) {
+      if (OVERWRITE_HEADERS.includes(line.trim())) collecting = true;
+      continue;
+    }
+    if (!line.startsWith('\t')) break;
+    let rel = line.slice(1).trim();
+    if (rel.startsWith('"') && rel.endsWith('"') && rel.length > 1) rel = rel.slice(1, -1);
+    if (rel) paths.push(rel);
+  }
+  return paths;
+}
+
+// `git -C <worktree> merge --ff-only <sha>` (observed §1.6 V-4): unrelated dirt is tolerated,
+// an overlapping dirty file refuses WITHOUT modifying the worktree -> `target_dirty` + .paths.
+function ffCheckedOut(worktree, sha, opts = {}) {
+  const args = ['merge', '--ff-only', sha];
+  const res = runGitRaw(worktree, args, opts);
+  if (res.status === 0) return { sha: revParseOrNull(worktree, 'HEAD'), stdout: res.stdout };
+  const paths = parseOverwritePaths(res.stderr);
+  if (paths.length) {
+    throw landingError('target_dirty', `fast-forward into ${worktree} would overwrite local changes: ${paths.join(', ')}`, {
+      paths, sha, worktree, stderr: res.stderr,
+    });
+  }
+  throw gitFailed(worktree, args, res);
+}
+
+// WP-2 (D-7): the radar snapshots a dirty worktree on EVERY sweep, so the snapshot commit must be a
+// pure function of (HEAD, content) — otherwise the pair cache key (`<snapshotSha>-<otherSha>.json`)
+// would change on every run and never hit. With `deterministic: true` the identity and both dates are
+// fixed (the date is HEAD's own committer date), so the commit object bytes — and therefore the sha —
+// depend only on the tree, the parent and this message.
+const SNAPSHOT_MESSAGE = 'land radar snapshot';
+const SNAPSHOT_IDENTITY = Object.freeze({ name: 'ctm-landing-radar', email: 'radar@example.invalid' });
+
+// Fixed author/committer identity + HEAD's committer date, as GIT_* env for commit-tree (which
+// otherwise requires a configured identity it must not depend on).
+function snapshotIdentityEnv(worktree, head) {
+  const env = {
+    GIT_AUTHOR_NAME: SNAPSHOT_IDENTITY.name,
+    GIT_AUTHOR_EMAIL: SNAPSHOT_IDENTITY.email,
+    GIT_COMMITTER_NAME: SNAPSHOT_IDENTITY.name,
+    GIT_COMMITTER_EMAIL: SNAPSHOT_IDENTITY.email,
+  };
+  const res = runGitRaw(worktree, ['show', '-s', '--format=%cI', head]);
+  const date = res.status === 0 ? res.stdout.trim() : '';
+  // No date means the commit could not be read, which cannot happen for a resolved HEAD; leaving the
+  // dates unset then makes the commit non-deterministic rather than silently wrong-dated.
+  if (date) {
+    env.GIT_AUTHOR_DATE = date;
+    env.GIT_COMMITTER_DATE = date;
+  }
+  return env;
+}
+
+// Snapshot commit of a worktree's CURRENT state (tracked edits + untracked-not-ignored files),
+// built through a temp index so the real index is never touched and no `index.lock` appears in
+// the worktree (observed §1.6 V-5: 0.186 s on a 10k-file repo).
+//
+// `opts.deterministic` (WP-2) additionally pins the identity, the dates and the message, so the same
+// HEAD and the same content always produce the same sha. Absent, behaviour is unchanged.
+function snapshotCommit(worktree, opts = {}) {
+  const head = revParseOrNull(worktree, 'HEAD');
+  if (!head) {
+    throw landingError('git_failed', `snapshotCommit: ${worktree} has no HEAD commit`, { cwd: worktree });
+  }
+  const tmpIndex = path.join(os.tmpdir(), `ctm-landing-index-${process.pid}-${crypto.randomBytes(6).toString('hex')}`);
+  const env = { GIT_INDEX_FILE: tmpIndex };
+  if (opts.deterministic) Object.assign(env, snapshotIdentityEnv(worktree, head));
+  try {
+    const realIndex = git(worktree, ['rev-parse', '--path-format=absolute', '--git-path', 'index']).trim();
+    let seeded = false;
+    try {
+      fs.copyFileSync(realIndex, tmpIndex);
+      seeded = true;
+    } catch (error) {
+      /* expected: no index file yet (fresh/odd worktree) -> seed the temp index from HEAD instead */
+    }
+    if (!seeded) git(worktree, ['read-tree', head], { env });
+    git(worktree, ['add', '-A'], { env });
+    const tree = git(worktree, ['write-tree'], { env }).trim();
+    const message = opts.message || (opts.deterministic ? SNAPSHOT_MESSAGE : `snapshot ${new Date().toISOString()}`);
+    return commitTree(worktree, tree, [head], message, { env });
+  } finally {
+    for (const file of [tmpIndex, `${tmpIndex}.lock`]) {
+      try {
+        fs.rmSync(file, { force: true });
+      } catch (error) {
+        /* expected: temp index cleanup is best-effort; a leftover file under os.tmpdir() never
+           affects the repo (the real index and its lock are untouched by construction) */
+      }
+    }
+  }
+}
+
+module.exports = {
+  SCRUBBED_ENV,
+  MAX_BUFFER,
+  SNAPSHOT_MESSAGE,
+  SNAPSHOT_IDENTITY,
+  landingError,
+  childEnv,
+  runGitRaw,
+  git,
+  gitFailed,
+  revParse,
+  revParseOrNull,
+  commonDir,
+  gitDir,
+  isAncestor,
+  isGitRepo,
+  toplevel,
+  mergeTree,
+  commitTree,
+  casUpdateRef,
+  ffCheckedOut,
+  parseOverwritePaths,
+  snapshotCommit,
+};

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

@@ -0,0 +1,247 @@
+'use strict';
+// WP-0 (docs/local-landing-queue-multi-session-integration-2026-10-26.html §5 D-2, §4/§9.1, §8
+// WP-0): the single per-repository runner lease — one writer, no daemon.
+//
+// Ported (copied with attribution, never imported — bin/ files are pinned by
+// bin/test-broker-protocol.manifest.json, I-6) from bin/test-slot-broker.js:
+//   _claimDir       (:600-620)  mkdtemp stage + renameSync into place
+//   _verifiedRemove (:388-440)  re-read the stamp, require record equality, rename to a private
+//                               tombstone, then remove the tombstone (never rm -rf a live claim)
+//   _reapIfDead     (:530-547)  kill(pid, 0) -> ESRCH, plus a lease-age + registry check; an
+//                               unreadable stamp is never reaped
+//
+// Layout: `landing/runner/lease/owner.json` (the DIRECTORY is what gets renamed). Use
+// leaseDir()/leasePath() — nothing else should hardcode these paths.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+const { landingError } = require('./git');
+const { readJsonSafe, writeJsonAtomic } = require('./state');
+
+// D-2: heartbeat freshness window. A constant on purpose — the queue has no flags (D-1).
+const LAND_HEARTBEAT_MS = 10000;
+// D-2 pid-reuse clause: a stale lease whose pid is alive is only dead when that pid is not a
+// live `land` process. Matches `land`, `land.js`, `node .../bin/land.js` — and nothing else.
+const LAND_PROCESS_RE = /\bland(?:\.js)?\b/;
+
+const RUNNER_DIRNAME = 'runner';
+const LEASE_DIRNAME = 'lease';
+const OWNER_FILENAME = 'owner.json';
+
+function runnerDir(root) {
+  return path.join(root, RUNNER_DIRNAME);
+}
+
+function leaseDir(root) {
+  return path.join(runnerDir(root), LEASE_DIRNAME);
+}
+
+function leasePath(root) {
+  return path.join(leaseDir(root), OWNER_FILENAME);
+}
+
+function isLeaseRecord(record) {
+  return Boolean(record) && typeof record === 'object' && typeof record.pid === 'number' && typeof record.token === 'string';
+}
+
+// D-10: the runner advertises what it can do. A runner spawned from an older `land.js` has no
+// `caps`, which is how `land cancel --force` (and, in WP-3, `urgent`) tells "this runner will
+// honour a stop request" from "this runner will overwrite the state I am about to write".
+function hasCap(record, cap) {
+  return Boolean(record) && Array.isArray(record.caps) && record.caps.includes(cap);
+}
+
+function isProcessAlive(pid, kill) {
+  try {
+    kill(pid, 0);
+    return true;
+  } catch (error) {
+    // ESRCH = gone; EPERM = exists but not ours, i.e. alive.
+    return !(error && error.code === 'ESRCH');
+  }
+}
+
+// `opts.now` is a number or a function, so a caller can freeze or advance the clock.
+function nowValue(opts = {}) {
+  const now = opts.now;
+  if (typeof now === 'function') return now();
+  if (typeof now === 'number') return now;
+  return Date.now();
+}
+
+function isStale(record, opts = {}) {
+  if (!isLeaseRecord(record)) return false;
+  const heartbeat = Date.parse(record.heartbeatAt);
+  if (!Number.isFinite(heartbeat)) return false;
+  return nowValue(opts) - heartbeat > 3 * LAND_HEARTBEAT_MS;
+}
+
+// D-2 pid-reuse probe: the command line of a live pid, or null when it cannot be read (the
+// process exited between the liveness check and this call, ps is missing, ...). null is
+// "unknown", which is never treated as dead.
+function processCommand(pid) {
+  const res = spawnSync('ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf8' });
+  if (!res || res.error || res.status !== 0) return null;
+  const command = String(res.stdout || '').trim();
+  return command === '' ? null : command;
+}
+
+// D-2 liveness. Dead iff `kill(pid, 0)` -> ESRCH, OR the heartbeat is older than
+// 3 x LAND_HEARTBEAT_MS AND the pid is not a live `land` process (a pid the OS reused after the
+// runner died, which is exactly what the ESRCH test alone cannot see). A live `land` process is
+// never dead, however old its heartbeat. A missing/unreadable stamp is never dead: we cannot
+// tell a dead owner from one we merely failed to read.
+function isDead(record, opts = {}) {
+  if (!isLeaseRecord(record)) return false;
+  const kill = opts.kill || process.kill;
+  if (!isProcessAlive(record.pid, kill)) return true;
+  if (!isStale(record, opts)) return false;
+  const probe = opts.processCommand || processCommand;
+  const command = probe(record.pid);
+  if (typeof command !== 'string') return false;
+  return !LAND_PROCESS_RE.test(command);
+}
+
+function read(root) {
+  const record = readJsonSafe(leasePath(root));
+  return isLeaseRecord(record) ? record : null;
+}
+
+// Verified removal: re-read IMMEDIATELY before removing and require the stamp to still be the one
+// the decision was made on. The removal itself renames the whole directory to a private
+// tombstone FIRST (a single syscall, so the path is never briefly empty — rename onto an EMPTY
+// directory would otherwise succeed and a concurrent claimant could slip in) and only then
+// removes the tombstone.
+function verifiedRemove(dir, expected) {
+  const current = readJsonSafe(path.join(dir, OWNER_FILENAME));
+  if (!isLeaseRecord(current) || !expected || current.token !== expected.token) return false;
+  const tombstone = `${dir}.dead-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+  try {
+    fs.renameSync(dir, tombstone);
+  } catch (error) {
+    /* expected: someone else already reaped or reclaimed this lease; there is nothing of ours to
+       remove, so report "not removed" rather than deleting a live claim */
+    return false;
+  }
+  try {
+    fs.rmSync(tombstone, { recursive: true, force: true });
+  } catch (error) {
+    /* expected: the tombstone is private to this call, so a failed cleanup leaves only a stray
+       .dead-* directory; the live lease path is already free */
+  }
+  return true;
+}
+
+function reapIfDead(root, opts = {}) {
+  const record = read(root);
+  if (!record) return false;
+  if (!isDead(record, opts)) return false;
+  return verifiedRemove(leaseDir(root), record);
+}
+
+// Atomic claim (broker `_claimDir`): stage owner.json inside a private mkdtemp'd directory, then
+// renameSync it into place. rename onto a non-empty directory fails atomically, so the lease path
+// is either fully-formed-and-stamped or it was never claimed by this call.
+// Returns the record on success, null when a live holder owns it.
+function claim(root, opts = {}) {
+  const host = opts.host || os.hostname();
+  const jobId = opts.jobId === undefined ? null : opts.jobId;
+  const dir = leaseDir(root);
+  const staging = runnerDir(root);
+  fs.mkdirSync(staging, { recursive: true });
+  // Bounded retry: a reap that really removed a dead holder frees the path for THIS call, so the
+  // next submitter becomes the runner without an outer wait loop (D-2: "a dead runner's job
+  // returns to the head of the queue"). A live holder still yields null after the first attempt.
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const token = crypto.randomBytes(16).toString('hex');
+    const stamp = new Date(nowValue(opts)).toISOString();
+    // D-10: `caps` rides along with the record. `heartbeat` spreads `{...current}`, so it survives
+    // every refresh without being re-stated there.
+    const record = { contract: 1, pid: process.pid, startedAt: stamp, heartbeatAt: stamp, token, jobId, host, caps: ['stop'] };
+    let tmp;
+    try {
+      tmp = fs.mkdtempSync(path.join(staging, '.claim-'));
+    } catch (error) {
+      throw landingError('lease_stage_failed', `cannot stage a claim under ${staging}: ${error.message}`, { root, cause: error });
+    }
+    try {
+      fs.writeFileSync(path.join(tmp, OWNER_FILENAME), `${JSON.stringify(record)}\n`);
+    } catch (error) {
+      rmrf(tmp);
+      throw landingError('lease_stage_failed', `cannot write the staged owner stamp in ${tmp}: ${error.message}`, { root, cause: error });
+    }
+    try {
+      fs.renameSync(tmp, dir);
+      return record;
+    } catch (error) {
+      rmrf(tmp);
+      // Lost the race (or the path is a non-empty directory). Reap only a genuinely dead holder.
+      if (!reapIfDead(root, opts)) return null;
+    }
+  }
+  return null;
+}
+
+function rmrf(dir) {
+  try {
+    fs.rmSync(dir, { recursive: true, force: true });
+  } catch (error) {
+    /* expected: best-effort cleanup of our own staging directory under landing/runner/ */
+  }
+}
+
+// Refresh heartbeatAt (and jobId, when given) only while the on-disk token is still ours.
+function heartbeat(root, token, opts = {}) {
+  const file = leasePath(root);
+  const current = readJsonSafe(file);
+  if (!isLeaseRecord(current) || current.token !== token) {
+    throw landingError('lease_lost', `lease token ${token} is no longer held in ${root}`, { root, token });
+  }
+  const next = { ...current, heartbeatAt: new Date(nowValue(opts)).toISOString() };
+  if (opts.jobId !== undefined) next.jobId = opts.jobId;
+  // §9 S-6/D-6 (WP-1): the train in flight, so `land cancel` can tell a batch member from a singleton
+  // without reading a second file. Additive (R-3) — an older reader ignores it, and a lease written by
+  // an older runner has no `jobIds` at all, which `stop.isBatchMemberInFlight` reads as "not a member".
+  if (opts.jobIds !== undefined) next.jobIds = opts.jobIds;
+  writeJsonAtomic(file, next);
+  // The write is a rename into the same path; re-read to make sure we did not overwrite a holder
+  // that replaced the lease in between (the same "verified" discipline as removal).
+  const after = readJsonSafe(file);
+  if (!isLeaseRecord(after) || after.token !== token) {
+    throw landingError('lease_lost', `lease token ${token} was replaced while heartbeating ${root}`, { root, token });
+  }
+  return after;
+}
+
+// Verified release: true only when this call removed OUR lease.
+function release(root, token) {
+  const current = read(root);
+  if (!current || current.token !== token) return false;
+  return verifiedRemove(leaseDir(root), current);
+}
+
+module.exports = {
+  LAND_HEARTBEAT_MS,
+  LAND_PROCESS_RE,
+  RUNNER_DIRNAME,
+  LEASE_DIRNAME,
+  OWNER_FILENAME,
+  runnerDir,
+  leaseDir,
+  leasePath,
+  hasCap,
+  claim,
+  heartbeat,
+  release,
+  read,
+  isDead,
+  isStale,
+  isProcessAlive,
+  processCommand,
+  nowValue,
+  reapIfDead,
+  verifiedRemove,
+};