create-walle 0.10.2 → 0.10.3

package/template/coding-task-manager/lib/landing/resolve-cli.js

@@ -0,0 +1,424 @@
+'use strict';
+// WP-6 (docs/fleet-origin-main-sync-skill-2026-10-31.html §13.4 R-R3/R-R4/R-R6, §13.5, §13.7): the
+// CLI half of the resolver — `land resolve <jobId> --worktree <dir> [--wait] [--json]`.
+//
+// WP-13 (§14) adds the other half: `land resolve <jobId> --claim [--session <id>] [--json]` marks the
+// job's resolver key as owned by the session that is about to resolve it, so the follower's `decide()`
+// skips it instead of opening a second resolver (see `cmdClaim` below).
+//
+// The verb does not resolve anything itself. An agent resolves the merge in its OWN worktree, on the
+// branch `sync/origin-<origin12>` (R-R2/R-R3: only the queue lands, so a hand commit on main in that
+// worktree is never the answer), and this verb VALIDATES that commit and submits it as an ordinary
+// landing job with `kind:"resolve"`. Validation is four refusals, each a typed `landingError` with no
+// job file written:
+//
+//   job_not_resolvable  the id is unknown, or the job is not `kind:"sync"`, or it is not in
+//                       `blocked`/`failed` — the two states a resolver session is opened for
+//                       (§13.4 R-R1).
+//   dirty_worktree      tracked changes or unmerged paths in `--worktree` (R-R3: the resolution is
+//                       committed first; a resolution that exists only as a working-tree edit is not
+//                       a resolution).
+//   head_not_merge      nothing in `job.base..HEAD` is a merge of EXACTLY the two sides this job
+//                       conflicted (`{job.base, job.tip}`, order-insensitive) — a hand-built commit,
+//                       or a rebase that flattened the merge (§13.4 R-R6).
+//   conflict_markers    a path this job conflicted on still carries `<<<<<<<` / `=======` / `>>>>>>>`
+//                       in HEAD (R-R3's marker refusal: `git add` of a half-resolved file must not
+//                       land).
+//
+// Submission reuses the queue primitives `land submit` itself uses — `queue.enqueue` and
+// `syncCli.ensureRunner` — rather than a second copy of the submit path (bin/land.js is under a
+// frozen size ceiling, so the shared internals stay where they already are).
+//
+// The only new state the job carries is `kind:"resolve"`, `resolves:<jobId>` and `gateLane`, which
+// the runner turns into a gate choice: a resolved CONFLICT (`blocked`) is re-gated by the FAST gate
+// (§13.4 R-R4), a resolved GATE FAILURE (`failed`) by the ordinary `landing.gates` (§13.4 R-R6).
+// Publishing is not this module's business: a landed resolve job goes through the existing
+// `afterTrainLanded` auto-publish path like any other landing.
+
+const path = require('path');
+
+const { landingError, runGitRaw, revParseOrNull } = require('./git');
+const { strFlag } = require('../env-flags');
+const queue = require('./queue');
+const syncCli = require('./sync-cli');
+const { loadLandingConfig, loadTargetLandingConfig } = require('./config');
+// WP-13 (docs/fleet-origin-main-sync-skill-2026-10-31.html §14 WP-13/§14.6): the claim path writes the
+// SAME resolver record `lib/fleet-resolver.js` reads, keyed the same way, through that module's own
+// atomic writer — never a second copy of the state file's shape.
+const resolver = require('../fleet-resolver');
+
+// Injected by bin/land.js once, at load (the same handshake sync-cli.js takes). Held as bare
+// bindings so the emitters are the process's own, never a second formatting of the same payload.
+let progress = () => {};
+let emitJsonOrLine = () => {};
+let context = null;
+let branchRef = null;
+let CONTRACT = 1;
+let WAIT_TIMEOUT_MS = 4 * 60 * 60 * 1000;
+
+// `git status --porcelain` v1 unmerged codes (`git help status`): both sides of the merge still in
+// the index. Every other non-`??` code is an ordinary tracked change.
+const UNMERGED_CODES = Object.freeze(['DD', 'AU', 'UD', 'UA', 'DU', 'AA', 'UU']);
+// §13.4 R-R3: a marker line is seven identical characters at column 0, then a space or end of line —
+// the same shape `git diff --check` reports.
+const MARKER_RE = new RegExp('^(?:<{7}|={7}|>{7})(?: |$)');
+const RESOLVABLE_STATES = Object.freeze(['blocked', 'failed']);
+
+function lines(stdout) {
+  return String(stdout || '').split('\n').map((line) => line.trim()).filter(Boolean);
+}
+
+// --- validation ------------------------------------------------------------------------------
+
+// The refusal R-R3 makes first: the resolution has to be committed in `--worktree`. Untracked files
+// are not an answer either way (they cannot be part of a commit this verb is about to land), so they
+// are ignored exactly as `land submit` ignores them.
+function worktreeDirt(worktree) {
+  const res = runGitRaw(worktree, ['status', '--porcelain']);
+  if (res.status !== 0) {
+    throw landingError('git_failed', `git status failed in ${worktree}`, { cwd: worktree, stderr: String(res.stderr || '') });
+  }
+  const dirty = [];
+  const unmerged = [];
+  for (const raw of String(res.stdout || '').split('\n')) {
+    if (!raw.trim()) continue;
+    const code = raw.slice(0, 2);
+    if (code === '??') continue;
+    const file = raw.slice(3).trim();
+    if (UNMERGED_CODES.includes(code)) unmerged.push(file);
+    else dirty.push(file);
+  }
+  return { dirty, unmerged };
+}
+
+// R-R6: the commit that IS the resolution — a merge commit in `job.base..HEAD` whose parents are
+// exactly the two sides this job conflicted. Order-insensitive, because which side git names first
+// depends on which branch was checked out. `null` means the worktree holds no such commit.
+function resolutionCommit(worktree, job) {
+  if (!job.base || !job.tip) return null;
+  const res = runGitRaw(worktree, ['rev-list', '--merges', '--parents', `${job.base}..HEAD`]);
+  if (res.status !== 0) return null;
+  for (const line of lines(res.stdout)) {
+    const [commit, ...parents] = line.split(/\s+/);
+    if (parents.length !== 2 || !commit) continue;
+    const forward = parents[0] === job.base && parents[1] === job.tip;
+    const reverse = parents[0] === job.tip && parents[1] === job.base;
+    if (forward || reverse) return commit;
+  }
+  return null;
+}
+
+// R-R3's marker refusal: HEAD's version of every path this job conflicted on, scanned line by line.
+// A path that does not exist in HEAD cannot hold a marker and is skipped (a resolution may legitimately
+// delete a path).
+function conflictMarkerHits(worktree, paths) {
+  const hits = [];
+  for (const rel of Array.isArray(paths) ? paths : []) {
+    if (typeof rel !== 'string' || !rel) continue;
+    const res = runGitRaw(worktree, ['show', `HEAD:${rel}`]);
+    if (res.status !== 0) continue;
+    const fileLines = String(res.stdout || '').split('\n');
+    for (let index = 0; index < fileLines.length; index += 1) {
+      if (MARKER_RE.test(fileLines[index])) hits.push(`${rel}:${index + 1}`);
+    }
+  }
+  return hits;
+}
+
+// --- submission ---------------------------------------------------------------------------------
+
+// §13.5: the resolve job is an ordinary queue job with three extra fields. `gateLane` is decided
+// HERE, from the state the sync job died in, and never re-derived later: `blocked` is a resolved
+// conflict (fast), `failed` is a gate failure (full).
+function resolveJobRecord(ctx, job, { branch, tip, worktree, config }) {
+  const session = strFlag('CTM_SESSION_ID') || null;
+  return {
+    contract: CONTRACT,
+    id: queue.newJobId(),
+    kind: 'resolve',
+    resolves: job.id,
+    gateLane: job.state === 'blocked' ? 'fast' : 'full',
+    repo: ctx.common,
+    branch,
+    tip,
+    title: `resolve ${job.id} (${branch})`,
+    submittedBy: { session, pid: process.pid, cwd: worktree },
+    state: 'queued',
+    reason: null,
+    priority: 'normal',
+    priorityHistory: [],
+    preemptions: 0,
+    base: null,
+    train: null,
+    tree: null,
+    verdict: null,
+    conflictPaths: [],
+    conflictPreview: null,
+    overlapWithTarget: [],
+    policySource: config.policySource || null,
+    runnerPid: null,
+    timestamps: { queued: queue.nowIso() },
+    gateLog: null,
+  };
+}
+
+// --- WP-13 `--claim` ---------------------------------------------------------------------------
+
+// §14 WP-13: the two states that mean "something already holds this box's resolver slot" — the same
+// pair `lib/fleet-resolver.js` calls LIVE_STATES (not exported there; `lib/fleet-resolver-tick.js`
+// repeats it the same way rather than widening the module). Keep the copies in step.
+const RESOLVER_LIVE_STATES = Object.freeze(['starting', 'resolving']);
+
+/**
+ * §14 WP-13: who owns this claim — `--session <id>` wins, then the session this CLI runs inside, then
+ * the literal `session:unknown` (the readonly `CTM_SESSION_ID` flag read, never a raw `process.env`).
+ */
+function claimOwner(opts) {
+  const fromArg = opts && opts.values && typeof opts.values.session === 'string' ? opts.values.session : '';
+  const session = fromArg || strFlag('CTM_SESSION_ID') || '';
+  return `session:${session || 'unknown'}`;
+}
+
+/** §14 WP-13: `resolveMaxMinutes` from the target's committed landing policy, else the module default. */
+function claimMaxMinutes(cwd) {
+  let publish = null;
+  try {
+    publish = loadLandingConfig(cwd).publish;
+  } catch (error) {
+    /* HANDLE: an unreadable/invalid landing policy is not fatal to a claim — the default deadline
+       is the same one lib/fleet-resolver.js would have started the resolver with. */
+    void error;
+  }
+  const minutes = publish && Number.isFinite(publish.resolveMaxMinutes) && publish.resolveMaxMinutes > 0
+    ? publish.resolveMaxMinutes
+    : resolver.DEFAULT_RESOLVE_MAX_MINUTES;
+  return minutes;
+}
+
+/**
+ * §14 WP-13: the live record a claim writes — the `lib/fleet-resolver.js` record shape (so the
+ * follower's own readers, `keep`/`claimed` rule and history all see a record they already understand)
+ * plus the two fields that make it a claim: `owner` and `claimedAt`. A record already on disk for the
+ * same key keeps whatever it knew (a CTM-started session's id, worktree, model) — the claim takes
+ * ownership, it does not pretend that session never existed.
+ */
+function claimRecord(job, { owner, claimedAt, deadlineAt, prior }) {
+  const before = prior && typeof prior === 'object' ? prior : {};
+  return {
+    ...before,
+    key: resolver.jobKey(job),
+    trigger: job.state === 'blocked' ? 'conflict' : 'gate_failed',
+    jobId: job.id || job.jobId || null,
+    conflictPaths: Array.isArray(job.conflictPaths) ? job.conflictPaths : [],
+    gateLog: job.gateLog === undefined ? null : job.gateLog,
+    base: job.base,
+    tip: job.tip,
+    sessionId: before.sessionId === undefined ? null : before.sessionId,
+    branch: resolver.branchFor(job.tip),
+    worktree: before.worktree === undefined ? null : before.worktree,
+    agent: before.agent === undefined ? null : before.agent,
+    model: before.model || '',
+    modelSource: before.modelSource || '',
+    state: 'resolving',
+    startedAt: claimedAt,
+    deadlineAt,
+    updatedAt: claimedAt,
+    reason: '',
+    owner,
+    claimedAt,
+  };
+}
+
+/**
+ * §14 WP-13 AC-13a: `land resolve <jobId> --claim [--session <id>] [--json]`. It runs NO gate and
+ * submits nothing: it marks this job's resolver key as owned by the session that is about to resolve
+ * it (`/fleet-sync` in the user's own session), so the follower's `decide()` skips the key instead of
+ * opening a second resolver for the same conflict.
+ */
+async function cmdClaim(opts, cwd) {
+  const jobId = opts.positionals[0];
+  if (!jobId) throw usageError('land resolve <jobId> --claim [--session <id>] [--json]');
+  const ctx = context(cwd);
+  const job = queue.readJob(ctx.root, jobId);
+  if (!job || job.kind !== 'sync' || !RESOLVABLE_STATES.includes(job.state)) {
+    throw landingError(
+      'job_not_resolvable',
+      `job ${jobId} is not a resolvable sync job`
+        + `${job ? ` (kind ${job.kind || 'none'}, state ${job.state})` : ' (no such job)'}; `
+        + 'only a kind:"sync" job in blocked or failed can be claimed',
+      { jobId, kind: job ? job.kind || null : null, state: job ? job.state : null },
+    );
+  }
+
+  const owner = claimOwner(opts);
+  const key = resolver.jobKey(job);
+  if (!key) {
+    throw landingError('job_not_resolvable', `job ${jobId} has no base/tip pair to key a resolver record on`, { jobId });
+  }
+
+  const prev = await resolver.readState(ctx.common);
+  const onDisk = prev.current && typeof prev.current === 'object' ? prev.current : null;
+  const live = onDisk && onDisk.key === key && RESOLVER_LIVE_STATES.includes(onDisk.state) ? onDisk : null;
+  // §14 WP-13: a session CTM started for this very key stands down — the user's session wins. Say so,
+  // then claim anyway: the follower must not start a second resolver, and the record is the only place
+  // it reads that from.
+  if (live && !resolver.claimedBySession(live)) {
+    progress(
+      `resolve: ${key} already has a CTM-started resolver session ${live.sessionId || '(unnamed)'}; `
+        + `${owner} claims it — CTM will not start a second one`,
+    );
+  }
+
+  const claimedAt = queue.nowIso();
+  const deadlineAt = new Date(Date.parse(claimedAt) + claimMaxMinutes(cwd) * 60 * 1000).toISOString();
+  await resolver.writeState(ctx.common, {
+    current: claimRecord(job, { owner, claimedAt, deadlineAt, prior: live }),
+    history: prev.history,
+  });
+
+  const payload = { ok: true, key, owner };
+  emitJsonOrLine(
+    opts,
+    payload,
+    `resolve: claimed ${key} for ${owner}${live && live.sessionId ? ` (CTM's ${live.sessionId} stands down)` : ''}`,
+  );
+  return 0;
+}
+
+function exitCodeForVerdict(verdict) {
+  if (verdict === 'landed' || verdict === 'queued') return 0;
+  if (verdict === 'timeout') return 75;
+  return 1;
+}
+
+async function cmdResolve(opts, cwd) {
+  // §14 WP-13: `--claim` is the same verb's second half — mark the key owned and stop, before any of
+  // the validate-and-submit work below (no --worktree, no gate, no job file).
+  if (opts.flags.has('claim')) return cmdClaim(opts, cwd);
+  const jobId = opts.positionals[0];
+  if (!jobId) throw usageError('land resolve <jobId> --worktree <dir> [--wait] [--json]');
+  const worktreeArg = opts.values.worktree;
+  if (!worktreeArg) throw usageError('land resolve <jobId> requires --worktree <dir>');
+  const worktree = path.resolve(cwd, worktreeArg);
+  // The argument is proved through the git layer this module already uses, not `fs`: a path that is
+  // not a worktree at all must be an argument error here, not a `git_failed` stack out of the first
+  // `git status` below.
+  if (runGitRaw(worktree, ['rev-parse', '--show-toplevel']).status !== 0) {
+    throw usageError(`--worktree ${worktree} is not a git worktree`);
+  }
+
+  const ctx = context(cwd);
+  const job = queue.readJob(ctx.root, jobId);
+  if (!job || job.kind !== 'sync' || !RESOLVABLE_STATES.includes(job.state)) {
+    throw landingError(
+      'job_not_resolvable',
+      `job ${jobId} is not a resolvable sync job`
+        + `${job ? ` (kind ${job.kind || 'none'}, state ${job.state})` : ' (no such job)'}; `
+        + 'only a kind:"sync" job in blocked or failed can be resolved',
+      { jobId, kind: job ? job.kind || null : null, state: job ? job.state : null },
+    );
+  }
+
+  const dirt = worktreeDirt(worktree);
+  if (dirt.unmerged.length || dirt.dirty.length) {
+    const paths = [...dirt.unmerged, ...dirt.dirty];
+    throw landingError(
+      'dirty_worktree',
+      `${worktree} has ${dirt.unmerged.length} unmerged path(s) and ${dirt.dirty.length} modified tracked file(s) `
+        + `(${paths.join(', ')}); commit the resolution before resolving`,
+      { paths, unmerged: dirt.unmerged, dirty: dirt.dirty },
+    );
+  }
+
+  const merge = resolutionCommit(worktree, job);
+  if (!merge) {
+    throw landingError(
+      'head_not_merge',
+      `no commit in ${job.base}..HEAD of ${worktree} merges exactly {${job.base}, ${job.tip}}; `
+        + `merge origin/${job.branch || 'main'} into ${worktree} and commit the resolution`,
+      { base: job.base, tip: job.tip, worktree },
+    );
+  }
+
+  const hits = conflictMarkerHits(worktree, job.conflictPaths);
+  if (hits.length) {
+    throw landingError(
+      'conflict_markers',
+      `unresolved conflict markers in ${hits.join(', ')}`,
+      { hits, paths: job.conflictPaths || [] },
+    );
+  }
+
+  // Gates are read from the TARGET's committed policy, exactly as `land submit` reads them.
+  const config = loadTargetLandingConfig(worktree);
+  const branch = currentBranch(worktree);
+  const tip = revParseOrNull(worktree, branchRef(branch));
+  if (!tip) {
+    throw landingError('git_failed', `cannot resolve ${branch} in ${worktree}`, { branch, worktree });
+  }
+  queue.reapDeadRunner(ctx.root);
+  const record = resolveJobRecord(ctx, job, { branch, tip, worktree, config });
+  progress(`resolve: submitting ${record.id} for ${job.id} (${branch}@${tip.slice(0, 12)}, gate lane ${record.gateLane})`);
+  queue.enqueue(ctx.root, record);
+  const started = syncCli.ensureRunner(ctx);
+  if (started.pid !== null) queue.updateJob(ctx.root, record.id, { runnerPid: started.pid });
+
+  const payload = { verdict: null, jobId: record.id, resolves: job.id, gateLane: record.gateLane };
+  if (opts.flags.has('wait')) {
+    // §13.5: the wait is `land sync`'s own (sync-cli.js `waitForSyncJob`) — it already knows how to
+    // tell "the runner died" from "still working", which a bare poll of the terminal state does not.
+    const final = await syncCli.waitForSyncJob(ctx, record.id);
+    payload.verdict = final.state;
+    emitJsonOrLine(
+      opts,
+      payload,
+      `resolve: job ${record.id} ${final.state}${final.reason ? ` (${final.reason})` : ''} for ${job.id}${record.gateLane === 'fast' ? ' [fast gate]' : ''}`,
+    );
+    return exitCodeForVerdict(final.state);
+  }
+  payload.verdict = 'queued';
+  emitJsonOrLine(
+    opts,
+    payload,
+    `resolve: job ${record.id} queued for ${job.id} on ${branch} [${record.gateLane} gate] (runner: ${started.runner})`,
+  );
+  return 0;
+}
+
+function currentBranch(worktree) {
+  const res = runGitRaw(worktree, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  const name = res.status === 0 ? res.stdout.trim() : '';
+  if (!name || name === 'HEAD') {
+    throw landingError('detached_head', `${worktree} is on a detached HEAD; check out the resolver branch first`, { worktree });
+  }
+  return name;
+}
+
+function usageError(message) {
+  const error = new Error(message);
+  error.code = 'usage';
+  return error;
+}
+
+// bin/land.js calls this once, at load, with its own process-level helpers — the same handshake
+// sync-cli.js takes. A caller that forgets it gets no-op emitters, not a TypeError mid-command.
+function configure(injected) {
+  ({
+    progress,
+    emitJsonOrLine,
+    context,
+    branchRef,
+    CONTRACT,
+    WAIT_TIMEOUT_MS,
+  } = injected);
+  return module.exports;
+}
+
+module.exports = {
+  configure,
+  cmdResolve,
+  cmdClaim,
+  worktreeDirt,
+  resolutionCommit,
+  conflictMarkerHits,
+};

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

@@ -0,0 +1,263 @@
+'use strict';
+// WP-0 (docs/local-landing-queue-multi-session-integration-2026-10-26.html §5 D-1, §6.3, §8 WP-0,
+// §7 E-5): per-repository state for the landing queue.
+//
+// State lives at `$(git rev-parse --git-common-dir)/landing/` — shared by every worktree of the
+// repo, never inside a worktree, never under os.tmpdir() (D-1). Files are small JSON documents
+// written tmp+rename, and every one of them carries `contract: 1` so an old CLI reading new
+// state refuses with `contract_unsupported` instead of corrupting it (E-5).
+//
+// The queue has no daemon (D-2); the only cross-process serialization primitive is a `.mutex`
+// directory next to the state files, exactly like the broker's `.admission` lock. The mutex is
+// won by renaming a fully-stamped staging directory into place and released the same way, so the
+// path is never observable without an owner stamp and never briefly empty (§5 D-1/D-2).
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { commonDir, landingError } = require('./git');
+
+const CONTRACT = 1;
+const MUTEX_DIRNAME = '.mutex';
+// Staging directories for a mutex claim live NEXT TO the mutex (same filesystem, so the rename
+// into place is atomic) and are named so they can never be mistaken for the mutex itself.
+const MUTEX_STAGE_PREFIX = '.mutex-claim-';
+const OWNER_FILENAME = 'owner.json';
+
+// §6.3 directory layout under landing/.
+const SUBDIRS = Object.freeze(['jobs', 'runner', 'verdicts', 'trains', 'radar', 'claims', 'metrics']);
+
+// `$(git rev-parse --git-common-dir)/landing` (absolutized by git itself).
+function landingDir(cwd) {
+  return path.join(commonDir(cwd), 'landing');
+}
+
+function mutexPath(root) {
+  return path.join(root, MUTEX_DIRNAME);
+}
+
+function ensureDirs(root) {
+  fs.mkdirSync(root, { recursive: true });
+  for (const name of SUBDIRS) fs.mkdirSync(path.join(root, name), { recursive: true });
+  return root;
+}
+
+// Atomic JSON write: `<file>.<pid>.<rand>.tmp` then renameSync (same-filesystem, so the rename
+// is atomic). A plain object without an explicit `contract` is stamped with contract 1 — every
+// state file in §6.3 carries it.
+function writeJsonAtomic(file, obj) {
+  let payload = obj;
+  if (obj && typeof obj === 'object' && !Array.isArray(obj) && obj.contract === undefined) {
+    payload = { ...obj, contract: CONTRACT };
+  }
+  const tmp = `${file}.${process.pid}.${crypto.randomBytes(6).toString('hex')}.tmp`;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(tmp, `${JSON.stringify(payload, null, 2)}\n`);
+  try {
+    fs.renameSync(tmp, file);
+  } catch (error) {
+    try {
+      fs.rmSync(tmp, { force: true });
+    } catch (cleanupError) {
+      /* expected: best-effort removal of our own tmp file; the rename failure below is the
+         error that matters and is rethrown unchanged */
+    }
+    throw error;
+  }
+  return file;
+}
+
+// object | null (ENOENT) | throws `state_unreadable` (bad JSON or unreadable file). Callers that
+// must never treat a torn stamp as "free" should let the throw propagate, or use readJsonSafe.
+function readJson(file) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return null;
+    throw landingError('state_unreadable', `cannot read ${file}: ${error.message}`, { file, cause: error });
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw landingError('state_unreadable', `bad JSON in ${file}: ${error.message}`, { file, cause: error });
+  }
+}
+
+// Same as readJson, but an unreadable file becomes `null` instead of a throw — for callers whose
+// safety property is "unknown holder", never "free" (the broker's UNREADABLE disposition).
+function readJsonSafe(file) {
+  try {
+    return readJson(file);
+  } catch (error) {
+    /* expected: unreadable/torn stamp is "unknown", and every caller of readJsonSafe treats
+       null as "not ours / not reapable" rather than as an absent record */
+    return null;
+  }
+}
+
+// E-5: refuse state written by a contract this build does not understand.
+function assertContract(obj, meta = {}) {
+  if (!obj || typeof obj !== 'object') {
+    throw landingError('contract_unsupported', `expected a contract-${CONTRACT} object`, { ...meta, contract: null });
+  }
+  if (obj.contract !== CONTRACT) {
+    throw landingError(
+      'contract_unsupported',
+      `state contract ${JSON.stringify(obj.contract)} is not supported (this build speaks ${CONTRACT})`,
+      { ...meta, contract: obj.contract, expected: CONTRACT },
+    );
+  }
+  return obj;
+}
+
+// Synchronous sleep, used only for the mutex backoff.
+function sleepSync(ms) {
+  if (!(ms > 0)) return;
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function pidIsAlive(pid, kill) {
+  try {
+    kill(pid, 0);
+    return true;
+  } catch (error) {
+    // ESRCH = no such process (dead). EPERM = alive but not ours — still alive.
+    return !(error && error.code === 'ESRCH');
+  }
+}
+
+// Reap a mutex whose owner stamp is readable AND names a dead pid. An unreadable stamp is never
+// reaped (we cannot tell a dead owner from one we merely failed to read). Removal is the same
+// verified pattern as the lease: re-read, require the same record, rename to a private tombstone,
+// then remove the tombstone.
+function reapMutexIfDead(mutexDir, { kill }) {
+  const stampFile = path.join(mutexDir, OWNER_FILENAME);
+  const stamp = readJsonSafe(stampFile);
+  if (!stamp || typeof stamp.pid !== 'number') return false;
+  if (pidIsAlive(stamp.pid, kill)) return false;
+  const again = readJsonSafe(stampFile);
+  if (!again || again.pid !== stamp.pid || again.since !== stamp.since) return false;
+  const tombstone = `${mutexDir}.dead-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+  try {
+    fs.renameSync(mutexDir, tombstone);
+  } catch (error) {
+    /* expected: another process won the reap or reclaimed the mutex between the read and the
+       rename; its holder is unaffected and we simply retry */
+    return false;
+  }
+  try {
+    fs.rmSync(tombstone, { recursive: true, force: true });
+  } catch (error) {
+    /* expected: the tombstone is now private to this call, so a failed cleanup can only leave a
+       stray .dead-* directory behind; the mutex path itself is already free */
+  }
+  return true;
+}
+
+// Claim the mutex the way the lease claims its directory: stage a fully-stamped directory under
+// a private mkdtemp name, then renameSync it ONTO <root>/.mutex. A rename onto a NON-EMPTY
+// directory fails atomically (ENOTEMPTY/EEXIST), so the mutex path is never observable as
+// "exists but has no owner stamp" — a process killed mid-claim leaves a stray `.mutex-claim-*`
+// staging directory, never a lock that every later caller times out on. A rename onto an EMPTY
+// .mutex succeeds, which is why that stray state is not a deadlock either.
+function tryClaimMutex(root, now) {
+  const mutexDir = mutexPath(root);
+  let staging;
+  try {
+    staging = fs.mkdtempSync(path.join(root, MUTEX_STAGE_PREFIX));
+  } catch (error) {
+    throw landingError('mutex_stage_failed', `cannot stage a mutex claim under ${root}: ${error.message}`, { root, cause: error });
+  }
+  try {
+    writeJsonAtomic(path.join(staging, OWNER_FILENAME), { pid: process.pid, since: new Date(now).toISOString() });
+  } catch (error) {
+    removeDir(staging);
+    throw error;
+  }
+  try {
+    fs.renameSync(staging, mutexDir);
+    return true;
+  } catch (error) {
+    removeDir(staging);
+    if (error && (error.code === 'ENOTEMPTY' || error.code === 'EEXIST')) return false;
+    throw error;
+  }
+}
+
+function removeDir(dir) {
+  try {
+    fs.rmSync(dir, { recursive: true, force: true });
+  } catch (error) {
+    /* expected: best-effort cleanup of a directory this call created (a staging dir, or the
+       private tombstone of a release); the caller's own outcome is unaffected */
+  }
+}
+
+// §5 (file-based state, "queue.json rewritten under a mkdir mutex like .admission").
+// Sync `fn` holds the mutex for its duration; a thenable return value holds it until settlement.
+function withMutex(root, fn, opts = {}) {
+  const timeoutMs = Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : 10000;
+  const now = typeof opts.now === 'function' ? opts.now : () => (typeof opts.now === 'number' ? opts.now : Date.now());
+  const kill = opts.kill || process.kill;
+  const mutexDir = mutexPath(root);
+  fs.mkdirSync(root, { recursive: true });
+  const deadline = now() + timeoutMs;
+  let delay = 2;
+  for (;;) {
+    if (tryClaimMutex(root, now())) break;
+    reapMutexIfDead(mutexDir, { kill });
+    if (now() >= deadline) {
+      throw landingError('mutex_timeout', `timed out after ${timeoutMs}ms waiting for ${mutexDir}`, { mutexDir, timeoutMs });
+    }
+    sleepSync(delay);
+    delay = Math.min(delay * 2, 25);
+  }
+  let released = false;
+  // Release by renaming the whole directory to a private tombstone FIRST and only then removing
+  // the tombstone: rmSync(recursive) unlinks owner.json and rmdirs the path in two steps, which
+  // leaves a briefly-EMPTY .mutex — exactly the directory a concurrent staged rename would then
+  // land in, giving two holders.
+  const release = () => {
+    if (released) return;
+    released = true;
+    const tombstone = `${mutexDir}.dead-${process.pid}-${crypto.randomBytes(4).toString('hex')}`;
+    try {
+      fs.renameSync(mutexDir, tombstone);
+    } catch (error) {
+      /* expected: the mutex directory is already gone (a reap that raced our own release, or an
+         earlier release in this process); there is nothing left to remove */
+      return;
+    }
+    removeDir(tombstone);
+  };
+  let result;
+  try {
+    result = fn();
+  } catch (error) {
+    release();
+    throw error;
+  }
+  if (result && typeof result.then === 'function') return Promise.resolve(result).finally(release);
+  release();
+  return result;
+}
+
+module.exports = {
+  CONTRACT,
+  MUTEX_DIRNAME,
+  MUTEX_STAGE_PREFIX,
+  OWNER_FILENAME,
+  SUBDIRS,
+  landingDir,
+  mutexPath,
+  ensureDirs,
+  writeJsonAtomic,
+  readJson,
+  readJsonSafe,
+  assertContract,
+  withMutex,
+  reapMutexIfDead,
+  pidIsAlive,
+  sleepSync,
+};