mandrel 2.0.0 → 2.2.0

package/lib/cli/registry.js

@@ -31,12 +31,17 @@ import {
   satisfiesNodeEngine,
 } from '../../.agents/scripts/lib/bootstrap/project-bootstrap.js';
 import { isCommandExcluded } from '../../.agents/scripts/lib/command-header.js';
+import { getDeliveryRouting } from '../../.agents/scripts/lib/config/delivery-routing.js';
 import {
   defaultResolvePackageRoot,
   listFiles as listPayloadFiles,
 } from './sync.js';
 import { readCache } from './version-check.js';
-import { compareVersions as compareSemver } from './version-helpers.js';
+import {
+  compareVersions as compareSemver,
+  resolveConsumerPinSpec,
+  satisfiesPinSpec,
+} from './version-helpers.js';
 
 // ---------------------------------------------------------------------------
 // Internal helpers
@@ -309,6 +314,60 @@ function runCommandsInSync({ projectRoot, cwd, readDir, readFile } = {}) {
 // check: agents-in-sync
 // ---------------------------------------------------------------------------
 
+/**
+ * Best-effort raw JSON read — no AJV, no merge validation. Absent, unreadable,
+ * or malformed files degrade to `null` so a config problem never crashes a
+ * doctor check; the caller applies framework defaults on `null`.
+ *
+ * @param {string} absPath
+ * @param {typeof fs} fsImpl
+ * @returns {object | null}
+ */
+function readJsonSafe(absPath, fsImpl) {
+  try {
+    return JSON.parse(fsImpl.readFileSync(absPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve `delivery.routing.roleScopedAgents` (default `true`) for
+ * `agents-in-sync`'s fatal/advisory branch below, WITHOUT importing the full
+ * `resolveConfig()` chain — that chain pulls in AJV (`config-schema.js`),
+ * which would violate this module's own "Node built-ins only" contract (see
+ * the module doc: registry.js must load inside the preflight guard, before
+ * any third-party package is guaranteed present).
+ *
+ * Reads `.agentrc.json` and `.agentrc.local.json` directly and shallow-merges
+ * only the `delivery.routing` block (local wins per-key) — narrower than the
+ * resolver's full deep-merge, but sufficient for this one boolean, and it
+ * still honours a local override rather than silently ignoring it. Delegates
+ * the actual default/coercion to `getDeliveryRouting` (`config/delivery-
+ * routing.js`), which has zero imports of its own and is already the single
+ * source of truth for this default elsewhere in the framework.
+ *
+ * @param {string} projectRoot
+ * @param {typeof fs} fsImpl
+ * @returns {boolean}
+ */
+function resolveRoleScopedAgentsFlag(projectRoot, fsImpl) {
+  const base = readJsonSafe(path.join(projectRoot, '.agentrc.json'), fsImpl);
+  const local = readJsonSafe(
+    path.join(projectRoot, '.agentrc.local.json'),
+    fsImpl,
+  );
+  const merged = {
+    delivery: {
+      routing: {
+        ...(base?.delivery?.routing ?? {}),
+        ...(local?.delivery?.routing ?? {}),
+      },
+    },
+  };
+  return getDeliveryRouting(merged).roleScopedAgents;
+}
+
 /**
  * Dry-run the sync-claude-agents logic: compare `.agents/agents/*.md` sources
  * to the generated `.claude/agents/*.md` role-agent tree and report parity.
@@ -326,30 +385,52 @@ function runCommandsInSync({ projectRoot, cwd, readDir, readFile } = {}) {
  * A repo with no `.agents/agents/` sources and no `.claude/agents/` tree is a
  * clean no-op (0 sources, 0 dests → "up to date").
  *
- * **Inert-scaffolding divergence from `commands-in-sync` (#4478 PR-2).** The
- * role agents are inert — no workflow spawns them yet — so a **never
- * materialized** agent tree (sources present, but the `.claude/agents/` tree
- * empty) is NOT a readiness failure: it is reported as advisory, not fatal.
- * Once the tree HAS been materialized, drift (a source missing from the dest,
- * or a stale dest file) fails the check exactly like `commands-in-sync`. M7-B
- * (the spawn flip) is where the sync is wired into the delivery flows and this
- * tolerance is tightened.
+ * **Tightened from advisory to fatal (Story #4530, M7-B).** Prior to this
+ * Story, a **never materialized** agent tree (sources present, `.claude/
+ * agents/` empty) was reported as advisory — "inert", because no workflow
+ * spawned the role agents yet. M7-B has landed: `helpers/deliver-story` Step
+ * 1a dispatches `subagent_type: acceptance-critic` on the **default** path
+ * (`roleScopedAgents` defaults `true`). An unmaterialized tree under that
+ * default is no longer a benign scaffolding gap — it is the acceptance
+ * ceremony's fresh-context critic silently failing to spawn and falling back
+ * to a weaker inline critic, with doctor reporting green throughout. This
+ * check now fails in exactly that case. When `roleScopedAgents` is `false`
+ * (the operator kill-switch), an unmaterialized tree is expected — the check
+ * stays advisory. Once the tree HAS been materialized, drift (a source
+ * missing from the dest, or a stale dest file) fails the check exactly like
+ * `commands-in-sync`, unconditionally, exactly as before this Story.
  *
  * Injectable seams (used by tests so no real filesystem is touched):
  * - `cwd()` replaces `process.cwd` so tests can pin the consumer root.
  * - `readDir` replaces `fs.readdirSync`.
+ * - `fsImpl` replaces the `node:fs` surface used for the `.agentrc.json` /
+ *   `.agentrc.local.json` reads.
+ * - `roleScopedAgents` overrides the resolved flag directly, bypassing the
+ *   config reads entirely.
  *
- * @param {{ projectRoot?: string, cwd?: () => string, readDir?: (dir: string) => string[] }} [opts]
+ * @param {{
+ *   projectRoot?: string,
+ *   cwd?: () => string,
+ *   readDir?: (dir: string) => string[],
+ *   fsImpl?: typeof fs,
+ *   roleScopedAgents?: boolean,
+ * }} [opts]
  * @returns {{ ok: boolean, detail: string, remedy?: string }}
  */
-function runAgentsInSync({ projectRoot, cwd, readDir } = {}) {
+function runAgentsInSync({
+  projectRoot,
+  cwd,
+  readDir,
+  fsImpl = fs,
+  roleScopedAgents,
+} = {}) {
   const getCwd = cwd ?? (() => process.cwd());
   const root = projectRoot ?? getCwd();
   const listDir =
     readDir ??
     ((dir) => {
       try {
-        return fs.readdirSync(dir).filter((f) => f.endsWith('.md'));
+        return fsImpl.readdirSync(dir).filter((f) => f.endsWith('.md'));
       } catch {
         return [];
       }
@@ -365,14 +446,26 @@ function runAgentsInSync({ projectRoot, cwd, readDir } = {}) {
     .filter((f) => !f.startsWith('.'))
     .sort();
 
-  // Never-materialized agent tree: inert, so advisory (ok:true), not fatal.
   if (dests.length === 0) {
+    if (sources.length === 0) {
+      return { ok: true, detail: '0 agents up to date' };
+    }
+    const resolvedFlag =
+      typeof roleScopedAgents === 'boolean'
+        ? roleScopedAgents
+        : resolveRoleScopedAgentsFlag(root, fsImpl);
+    if (!resolvedFlag) {
+      // Kill-switch off: an unmaterialized tree is expected, not a defect.
+      return {
+        ok: true,
+        detail: `${sources.length} agent def(s) not materialized (roleScopedAgents is disabled)`,
+      };
+    }
     return {
-      ok: true,
-      detail:
-        sources.length === 0
-          ? '0 agents up to date'
-          : `${sources.length} agent def(s) not yet materialized (inert)`,
+      ok: false,
+      detail: `${sources.length} agent def(s) not yet materialized in .claude/agents/`,
+      remedy:
+        'Run `mandrel sync-agents` to regenerate the `.claude/agents/` tree.',
     };
   }
 
@@ -392,7 +485,7 @@ function runAgentsInSync({ projectRoot, cwd, readDir } = {}) {
     ok: false,
     detail: parts.join(', '),
     remedy:
-      'Run `npm run sync:agents` to regenerate the `.claude/agents/` tree.',
+      'Run `mandrel sync-agents` to regenerate the `.claude/agents/` tree.',
   };
 }
 
@@ -705,6 +798,149 @@ export function runAgentsDrift({ cwd, fsImpl = fs, resolvePackageRoot } = {}) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// check: pin-current
+// ---------------------------------------------------------------------------
+
+/**
+ * Fatal doctor check (Story #4525 / #4530): is the version actually
+ * resolvable in `node_modules` **consistent with** the consumer's declared
+ * `mandrel` dependency range (`package.json`)?
+ *
+ * This is a **different** signal from `agents-drift` (are the materialized
+ * `.agents/` file *contents* byte-identical to the installed payload) and
+ * from `version-current` below (is a *newer* version *published*). Neither
+ * of those catches the shape of bug #4525 reported: a `package.json` pin
+ * that has fallen out of agreement with what `node_modules` actually
+ * resolves to — e.g. an out-of-band symlink, or `npm install mandrel@latest
+ * --no-save` — which `mandrel doctor` graded as fully green before this
+ * check existed, because the only version `defaultCurrentVersion` ever read
+ * WAS the inflated `node_modules` one.
+ *
+ * **Range-aware.** The declared pin is a *range*, not an equality, so the
+ * question this check asks is satisfaction, not identity. A consumer who
+ * declares `^2.1.0` and runs a routine `npm update` gets 2.4.0 in
+ * `node_modules` with `package.json` untouched — that is npm behaving
+ * exactly as documented, and under this project's `always-bump-minor`
+ * release cadence it is the *normal* steady state, not a defect. Grading it
+ * fatal (as this check originally did, comparing only the pin's base
+ * version) made `mandrel doctor` cry wolf on healthy installs.
+ *
+ * The graded contract:
+ * - installed **satisfies** the declared range and equals its base version
+ *   → pass, quietly.
+ * - installed **satisfies** the declared range but is newer than its base
+ *   (`^2.1.0` + 2.4.0) → pass with an **advisory** `detail`. Re-pinning via
+ *   `mandrel update` is tidier, but nothing is broken. This mirrors how
+ *   `version-current` stays non-fatal: `ok: true` with the advisory carried
+ *   in `detail` (the registry's `advisory: true` flag documents an entry
+ *   whose `run()` *never* fails, which is not true of this check).
+ * - installed does **not** satisfy the declared range (`^2.1.0` + 3.0.0, or
+ *   an exact `2.1.0` pin + 2.4.0) → **fail**. The declared dependency does
+ *   not describe the code that is running.
+ * - installed is **behind** the pin's base version (`^2.4.0` + 2.1.0) →
+ *   **fail**, and note that `<` the base never satisfies any of the ranges
+ *   `resolveConsumerPinSpec` yields, so this is a sub-case of the above
+ *   given a distinct, more actionable message.
+ *
+ * Skips cleanly (not a failure) when there is no resolvable pin at all — no
+ * `package.json`, no `mandrel` entry in `dependencies`/`devDependencies`, or
+ * a non-semver specifier (`workspace:`, `git+`, `latest`, a comparator
+ * range) — via {@link resolveConsumerPinSpec}'s own `null` contract. This
+ * is also how mandrel's own repo (no self-dependency) and workspace/npx
+ * consumers degrade to a clean pass rather than a false failure.
+ *
+ * Injectable seams (used by tests so no real filesystem or package is
+ * needed):
+ * - `cwd()` — replaces `process.cwd`, anchoring both the pin read and the
+ *   `node_modules` resolution at the same consumer root (mirrors
+ *   `agents-drift` / `agents-in-sync`).
+ * - `fsImpl` — replaces the `node:fs` surface.
+ * - `resolvePackageRoot(fromDir)` — replaces `mandrel` resolution; throws
+ *   when the package is not installed.
+ *
+ * @param {{
+ *   cwd?: () => string,
+ *   fsImpl?: typeof fs,
+ *   resolvePackageRoot?: (fromDir: string) => string,
+ * }} [opts]
+ * @returns {{ ok: boolean, detail: string, remedy?: string }}
+ */
+export function runPinCurrent({ cwd, fsImpl = fs, resolvePackageRoot } = {}) {
+  const getCwd = cwd ?? (() => process.cwd());
+  const resolveRoot = resolvePackageRoot ?? defaultResolvePackageRoot;
+  const projectRoot = getCwd();
+
+  const spec = resolveConsumerPinSpec(projectRoot, fsImpl);
+  if (!spec) {
+    return {
+      ok: true,
+      detail: 'no resolvable mandrel dependency pin — skipped',
+    };
+  }
+
+  let installedRoot;
+  try {
+    installedRoot = resolveRoot(projectRoot);
+  } catch {
+    // No baseline to compare the pin against; agents-materialized /
+    // runtime-deps own the "not installed" remedy.
+    return {
+      ok: true,
+      detail: 'mandrel not installed — pin check skipped',
+    };
+  }
+
+  let installed;
+  try {
+    const parsed = JSON.parse(
+      fsImpl.readFileSync(path.join(installedRoot, 'package.json'), 'utf8'),
+    );
+    installed = String(parsed.version);
+  } catch {
+    return {
+      ok: true,
+      detail: 'installed version unreadable — pin check skipped',
+    };
+  }
+
+  const declared = `${spec.operator}${spec.version}`;
+
+  if (compareSemver(installed, spec.version) < 0) {
+    return {
+      ok: false,
+      detail: `package.json pins ${declared} but an older v${installed} is installed`,
+      remedy:
+        'Run `npm install` to install a version satisfying the package.json pin.',
+    };
+  }
+
+  if (!satisfiesPinSpec(installed, spec)) {
+    return {
+      ok: false,
+      detail: `package.json pins ${declared} but v${installed} is installed — outside the declared range`,
+      remedy:
+        'Run `mandrel update` to reconcile the package.json pin with the installed version.',
+    };
+  }
+
+  if (compareSemver(installed, spec.version) > 0) {
+    // In range, just newer than the declared base — the ordinary result of an
+    // `npm update` under a caret/tilde pin. Healthy, so `ok: true`; the
+    // advisory rides in `detail` (the doctor runner only prints `remedy` for
+    // failures).
+    return {
+      ok: true,
+      detail: `v${installed} satisfies the ${declared} pin but is newer than it — run \`mandrel update\` to re-pin (advisory)`,
+    };
+  }
+
+  return {
+    ok: true,
+    detail: `pin ${declared} matches the installed version`,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // check: version-current
 // ---------------------------------------------------------------------------
@@ -870,6 +1106,13 @@ export const registry = [
     name: 'agents-drift',
     run: (opts) => runAgentsDrift(opts),
   },
+  {
+    name: 'pin-current',
+    // Fatal, unlike version-current below (Story #4525/#4530): a pin/install
+    // disagreement means the declared dependency does not describe the code
+    // that is running.
+    run: (opts) => runPinCurrent(opts),
+  },
   {
     name: 'version-current',
     // Non-fatal: surfaces a cache-only stale-version advisory. `run()` always

package/lib/cli/sync-agents.js

@@ -0,0 +1,157 @@
+// lib/cli/sync-agents.js
+/**
+ * `mandrel sync-agents` subcommand (Story #4528 / #4530).
+ *
+ * Thin wrapper that delegates to the canonical sync script
+ * (.agents/scripts/sync-claude-agents.js), projecting `.agents/agents/` into
+ * a flat `.claude/agents/` tree. Exact sibling of `sync-commands.js` —
+ * same delegation shape, same marker-gated refusal check, same seams —
+ * targeting the role-agent tree instead of the command tree. The sync
+ * script owns all sync logic; this module exists only to expose it through
+ * the mandrel CLI surface without reimplementing it.
+ *
+ * `sync-claude-agents.js` uses top-level await and has no exported `main()`
+ * function (marked `cli-opt-out`), so delegation runs via a child process
+ * rather than a direct import. Exit code and all output are forwarded
+ * verbatim to the caller so `mandrel sync-agents` is transparent to scripts
+ * that check $?.
+ *
+ * ## Prior to this Story
+ *
+ * `sync-claude-agents.js` was invoked on the **bootstrap** path
+ * (`project-bootstrap.js`'s `sync:agents` script, `prepare`, and
+ * `runSyncCommands`) but had no `lib/cli/` subcommand counterpart and was
+ * never run by `mandrel sync` / `mandrel update` on the CLI path — the gap
+ * #4528 reported. See `update.js`'s `driftHealSteps()` /
+ * `fullUpgradeSteps()`, which now spawn a `sync-agents` phase alongside
+ * `sync-commands` so `.claude/agents/` materializes on that path too.
+ *
+ * ## Marker-gated refusal (Story #4526 / #4530) — same shape as sync-commands
+ *
+ * Before delegating, this wrapper checks whether the `.agents/` tree it is
+ * about to project agents FROM actually matches the running CLI's own
+ * payload version, exactly as `sync-commands.js` does for the command tree.
+ * See that module's doc comment for the full rationale and the anchor-trap
+ * warning — it applies identically here (`PROJECT_ROOT` is deliberately the
+ * package root, used only to read the running CLI's OWN version; the marker
+ * read is anchored at `cwd()`, never at `PROJECT_ROOT`).
+ *
+ * Gate order:
+ *   1. Marker present (`.agents/.mandrel-version`) → compare it to the
+ *      running CLI's own package version. Mismatch → refuse.
+ *   2. Marker absent (a pre-marker install) → fall back to the existing
+ *      `agents-drift` content-hash check. Drift detected → refuse.
+ *   3. Clean either way → project as before.
+ */
+
+import { spawnSync } from 'node:child_process';
+import nodeFs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runAgentsDrift } from './registry.js';
+import { readVersionMarker } from './sync.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// lib/cli/ → lib/ → project root
+const PROJECT_ROOT = path.resolve(__dirname, '..', '..');
+const SYNC_SCRIPT = path.join(
+  PROJECT_ROOT,
+  '.agents',
+  'scripts',
+  'sync-claude-agents.js',
+);
+
+/**
+ * Resolve the running CLI's own package version from `PROJECT_ROOT`'s
+ * `package.json`. See `sync-commands.js`'s "anchor trap" module doc: this is
+ * the ONE place `PROJECT_ROOT` (the package's own two-dirs-up root) is the
+ * correct anchor.
+ *
+ * @param {typeof nodeFs} fsImpl
+ * @returns {string}
+ */
+function resolveOwnPackageVersion(fsImpl) {
+  const parsed = JSON.parse(
+    fsImpl.readFileSync(path.join(PROJECT_ROOT, 'package.json'), 'utf8'),
+  );
+  return String(parsed.version);
+}
+
+/**
+ * Run the sync-claude-agents script and forward its output + exit code —
+ * unless the marker-gated refusal check (see module doc) finds the
+ * `.agents/` tree mismatched against the running CLI, in which case it
+ * refuses and exits non-zero before spawning anything.
+ *
+ * Injectable seams — identical shape to `sync-commands.js`:
+ * - `runner` — replaces `spawnSync` for the real delegation.
+ * - `cwd()` — replaces `process.cwd`; anchors the marker read at the
+ *   consumer project root.
+ * - `fs` — replaces the `node:fs` surface for both the marker read and the
+ *   own-version read.
+ * - `ownVersion` — overrides the running CLI's own resolved version
+ *   directly, bypassing `resolveOwnPackageVersion`.
+ * - `checkAgentsDrift` — overrides the fallback drift probe used when the
+ *   marker is absent; defaults to `runAgentsDrift({ cwd })`.
+ * - `writeErr` / `exit` — replace the corresponding process surfaces.
+ *
+ * @param {string[]} _argv - Unused; reserved for future flags.
+ * @param {{
+ *   runner?: typeof spawnSync,
+ *   cwd?: () => string,
+ *   fs?: typeof nodeFs,
+ *   ownVersion?: string,
+ *   checkAgentsDrift?: () => { ok: boolean, detail: string },
+ *   writeErr?: (s: string) => void,
+ *   exit?: (code: number) => void,
+ * }} [opts]
+ * @returns {void}
+ */
+export default function run(
+  _argv = [],
+  {
+    runner = spawnSync,
+    cwd = () => process.cwd(),
+    fs = nodeFs,
+    ownVersion,
+    checkAgentsDrift,
+    writeErr = (s) => process.stderr.write(s),
+    exit = (code) => process.exit(code),
+  } = {},
+) {
+  const projectRoot = cwd();
+  const resolvedOwnVersion = ownVersion ?? resolveOwnPackageVersion(fs);
+  const marker = readVersionMarker(projectRoot, fs);
+
+  if (marker) {
+    if (marker !== resolvedOwnVersion) {
+      writeErr(
+        `mandrel sync-agents: the materialized .agents/ tree is v${marker} but the running CLI is v${resolvedOwnVersion} — refusing to project .claude/agents/ from a mismatched tree.\n` +
+          '   → Run `mandrel sync` to re-materialize .agents/ to the current version, then re-run.\n',
+      );
+      exit(1);
+      return;
+    }
+  } else {
+    const drift = (checkAgentsDrift ?? (() => runAgentsDrift({ cwd })))();
+    if (!drift.ok) {
+      writeErr(
+        `mandrel sync-agents: .agents/ appears to have drifted from the installed package payload (${drift.detail}) — refusing to project .claude/agents/ from a mismatched tree.\n` +
+          '   → Run `mandrel sync` to restore the materialized .agents/ payload, then re-run.\n',
+      );
+      exit(1);
+      return;
+    }
+  }
+
+  const result = runner(process.execPath, [SYNC_SCRIPT], {
+    stdio: 'inherit',
+    env: process.env,
+  });
+
+  const exitCode = result.status ?? 1;
+  if (exitCode !== 0) {
+    exit(exitCode);
+  }
+}

package/lib/cli/sync-commands.js

@@ -11,12 +11,49 @@
  * (marked `cli-opt-out`), so delegation runs via a child process rather than
  * a direct import. Exit code and all output are forwarded verbatim to the
  * caller so `mandrel sync-commands` is transparent to scripts that check $?.
+ *
+ * ## Marker-gated refusal (Story #4526 / #4530)
+ *
+ * Before delegating, this wrapper checks whether the `.agents/` tree it is
+ * about to project commands FROM actually matches the running CLI's own
+ * payload version. Without this gate, a consumer whose `.agents/` tree lags
+ * the installed package (see #4525's pin-skew scenario) gets commands
+ * faithfully projected from a **stale** tree — describing a workflow whose
+ * backing scripts are not installed. Because `.claude/*` is conventionally
+ * gitignored, that wrong projection leaves no diff and no signal until an
+ * agent hits a missing-module error mid-task, far from the actual cause.
+ *
+ * Gate order:
+ *   1. Marker present (`.agents/.mandrel-version`, Story #4530) → compare it
+ *      to the running CLI's own package version. Mismatch → refuse.
+ *   2. Marker absent (a pre-marker install with no baseline to compare) →
+ *      fall back to the existing `agents-drift` content-hash check
+ *      (`registry.js`). Drift detected → refuse.
+ *   3. Clean either way → project as before.
+ *
+ * ## Anchor trap (do not repeat)
+ *
+ * `PROJECT_ROOT` below is deliberately the **package** root — resolved from
+ * this module's own two-dirs-up location — because it is used ONLY to read
+ * the running CLI's OWN version, which is exactly what that self-referential
+ * pattern correctly answers (contrast with the #4525 bug in `update.js`,
+ * where the same pattern was wrongly used to answer a *consumer*-pin
+ * question). The marker read is a SEPARATE resolution, anchored at `cwd()`
+ * (the consumer project root) via `readVersionMarker` — never at
+ * `PROJECT_ROOT`. Comparing the marker to `PROJECT_ROOT`'s own version would
+ * make the check compare the package against itself and could never fire —
+ * the exact trap `registry.js`'s `agents-in-sync` check documents for the
+ * same reason.
  */
 
 import { spawnSync } from 'node:child_process';
+import nodeFs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { runAgentsDrift } from './registry.js';
+import { readVersionMarker } from './sync.js';
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // lib/cli/ → lib/ → project root
 const PROJECT_ROOT = path.resolve(__dirname, '..', '..');
@@ -28,16 +65,88 @@ const SYNC_SCRIPT = path.join(
 );
 
 /**
- * Run the sync-claude-commands script and forward its output + exit code.
+ * Resolve the running CLI's own package version from `PROJECT_ROOT`'s
+ * `package.json`. See the "anchor trap" module doc: this is the ONE place
+ * `PROJECT_ROOT` (the package's own two-dirs-up root) is the correct anchor.
+ *
+ * @param {typeof nodeFs} fsImpl
+ * @returns {string}
+ */
+function resolveOwnPackageVersion(fsImpl) {
+  const parsed = JSON.parse(
+    fsImpl.readFileSync(path.join(PROJECT_ROOT, 'package.json'), 'utf8'),
+  );
+  return String(parsed.version);
+}
+
+/**
+ * Run the sync-claude-commands script and forward its output + exit code —
+ * unless the marker-gated refusal check (see module doc) finds the
+ * `.agents/` tree mismatched against the running CLI, in which case it
+ * refuses and exits non-zero before spawning anything.
  *
- * Injectable seam: `runner` replaces `spawnSync` so tests can drive every
- * branch without spawning a real child process.
+ * Injectable seams (used by tests so no real filesystem, child process, or
+ * package resolution occurs on the gate path):
+ * - `runner` — replaces `spawnSync` for the real delegation.
+ * - `cwd()` — replaces `process.cwd`; anchors the marker read at the
+ *   consumer project root.
+ * - `fs` — replaces the `node:fs` surface for both the marker read and the
+ *   own-version read.
+ * - `ownVersion` — overrides the running CLI's own resolved version
+ *   directly, bypassing `resolveOwnPackageVersion`.
+ * - `checkAgentsDrift` — overrides the fallback drift probe used when the
+ *   marker is absent; defaults to `runAgentsDrift({ cwd })`.
+ * - `writeErr` / `exit` — replace the corresponding process surfaces.
  *
  * @param {string[]} _argv - Unused; reserved for future flags.
- * @param {{ runner?: typeof spawnSync }} [opts]
+ * @param {{
+ *   runner?: typeof spawnSync,
+ *   cwd?: () => string,
+ *   fs?: typeof nodeFs,
+ *   ownVersion?: string,
+ *   checkAgentsDrift?: () => { ok: boolean, detail: string },
+ *   writeErr?: (s: string) => void,
+ *   exit?: (code: number) => void,
+ * }} [opts]
  * @returns {void}
  */
-export default function run(_argv = [], { runner = spawnSync } = {}) {
+export default function run(
+  _argv = [],
+  {
+    runner = spawnSync,
+    cwd = () => process.cwd(),
+    fs = nodeFs,
+    ownVersion,
+    checkAgentsDrift,
+    writeErr = (s) => process.stderr.write(s),
+    exit = (code) => process.exit(code),
+  } = {},
+) {
+  const projectRoot = cwd();
+  const resolvedOwnVersion = ownVersion ?? resolveOwnPackageVersion(fs);
+  const marker = readVersionMarker(projectRoot, fs);
+
+  if (marker) {
+    if (marker !== resolvedOwnVersion) {
+      writeErr(
+        `mandrel sync-commands: the materialized .agents/ tree is v${marker} but the running CLI is v${resolvedOwnVersion} — refusing to project .claude/commands/ from a mismatched tree.\n` +
+          '   → Run `mandrel sync` to re-materialize .agents/ to the current version, then re-run.\n',
+      );
+      exit(1);
+      return;
+    }
+  } else {
+    const drift = (checkAgentsDrift ?? (() => runAgentsDrift({ cwd })))();
+    if (!drift.ok) {
+      writeErr(
+        `mandrel sync-commands: .agents/ appears to have drifted from the installed package payload (${drift.detail}) — refusing to project .claude/commands/ from a mismatched tree.\n` +
+          '   → Run `mandrel sync` to restore the materialized .agents/ payload, then re-run.\n',
+      );
+      exit(1);
+      return;
+    }
+  }
+
   const result = runner(process.execPath, [SYNC_SCRIPT], {
     stdio: 'inherit',
     env: process.env,
@@ -45,6 +154,6 @@ export default function run(_argv = [], { runner = spawnSync } = {}) {
 
   const exitCode = result.status ?? 1;
   if (exitCode !== 0) {
-    process.exit(exitCode);
+    exit(exitCode);
   }
 }