mandrel 2.65.0 → 2.66.0

package/.agents/workflows/audit-performance.md

@@ -27,18 +27,18 @@ Per the core's Scope interpretation:
 
 ## Execution strategy
 
-This is a **heavyweight lens**: dispatch it as a single `subagent_type: auditor`
-call, or fan its resource dimensions out per-dimension across parallel `auditor`
-subagents (parallel-tooling Rule 3) and merge under the self-cross-check.
-Sequential inline execution is the fallback (see the core's Execution strategy).
+Dispatch this lens as one `subagent_type: auditor` call. Fan its resource
+dimensions out across parallel `auditor` subagents (parallel-tooling Rule 3),
+merging under the self-cross-check, only when the operator explicitly asks for
+per-dimension fan-out. Sequential inline execution is the fallback (see the
+core's Execution strategy).
 
 > **Measurement is non-mutating, not forbidden.** This lens is read-only with
-> respect to source, but it MUST be allowed to *run* measurements. The
-> orchestrated path grants its measurement agents a `Bash` tool restricted to a
-> **non-mutating command allowlist** (profilers, timers, bundle-stat and
-> file-size probes — never a command that writes source, installs, or mutates
-> git/labels). See the allowlist in the harness-generated
-> `.claude/workflows/audit-performance.workflow.js`.
+> respect to source, but the auditor MUST be allowed to *run* measurements. It
+> runs only **non-mutating** commands — profilers, timers, bundle-stat and
+> file-size probes — and never a command that writes source, installs
+> packages, or mutates git state or labels. The one write is the report
+> artifact.
 
 ## Step 0: Measure before you judge (mandatory)
 

package/.agents/workflows/helpers/acceptance-self-eval.md

@@ -32,8 +32,8 @@ per-criterion, mid-delivery, and evaluates the actual work product.
    authors the Story's verdict, and it covers **every** `acceptance[]` item in
    one file. Which pass is named by the ceremony decision
    (`verdictOwner: 'fresh-critic' | 'inline-self-eval'` from
-   `resolveCeremonyForRisk`), and since Story #5343 that follows the
-   **ceremony profile alone**:
+   `resolveCeremonyForRisk`), which follows the **ceremony profile
+   alone**:
 
    > ```bash
    > node <main-repo>/.agents/scripts/ceremony-derive.js --story <storyId> --cwd <workCwd>
@@ -43,9 +43,8 @@ per-criterion, mid-delivery, and evaluates the actual work product.
    > classes **for review depth**, and resolves the owner (`mode`, `reason`,
    > `verdictOwner`): **`minimal` / `standard` → `inline`** (the default — you
    > author the verdict yourself), **`strict` → `fresh`** (dispatch the
-   > maker-blind critic). The derived level no longer routes this decision;
-   > it escalates `review-depth.js` instead, which still resolves `deep` for
-   > any sensitive path.
+   > maker-blind critic). The derived level feeds `review-depth.js`, not
+   > this decision; review depth resolves `deep` for any sensitive path.
 
    **Never run both**, and never run a preliminary self-assessment before
    dispatching a fresh critic — the redundant pre-pass buys no measurable
@@ -72,9 +71,10 @@ per-criterion, mid-delivery, and evaluates the actual work product.
    > system prompt, no entry-doc @-closure) carrying the maker-blind
    > invariant and the verdict schema standalone. With the kill-switch off
    > (`roleScopedAgents: false`), fall back to
-   > `subagent_type: general-purpose`. This loop already runs inside a Story
-   > delivery sub-agent, so the critic sits at nesting depth 2 — supported by
-   > any harness that carries `Agent` into sub-agents (Claude Code ≥ 2.1.202).
+   > `subagent_type: general-purpose`. Under sub-agent dispatch this loop
+   > runs inside a `story-worker`, so the critic sits at nesting depth 2
+   > (depth 1 inline) — supported by any harness that carries `Agent` into
+   > sub-agents (Claude Code ≥ 2.1.202).
 
    Whichever pass owns it, the verdict:
    + Inspects the **change set it was handed** — the one `files` list above —

package/.agents/workflows/helpers/audit-lens-core.md

@@ -118,14 +118,12 @@ dropped finding is indistinguishable from a finding you never wrote.
   Use it instead of inventing a below-`Low` word of your own; a finding that
   cannot clear the evidence bar below is **dropped**, not filed as `Info`.
 
-## Self-cross-check (mandatory — filter false positives before you finalize) {#self-cross-check}
+## Self-cross-check (the false-positive bar) {#self-cross-check}
 
-You are your own adversarial reviewer. After you have drafted the Detailed
-Findings but **before** you write the report artifact, re-open every finding
-and hold it to the bar below. This pass is **read-only** — it filters and
-tightens the findings you already have; it never invents new ones. It gives the
-sequential single-pass path the same false-positive filter the orchestrated
-path's independent adversarial reviewer applies.
+A finding goes in the report only when it clears the bar and the exclusion
+list below. The bar filters and tightens findings; it never invents new ones.
+It is the one false-positive filter every execution path applies — no separate
+adversarial reviewer runs after it.
 
 ### Per-finding evidence bar (keep or drop)
 
@@ -173,23 +171,18 @@ that rests on one of them:
 > delivery shipped and nothing in production ever calls. When a candidate is
 > genuinely one of the exclusions, cite the exclusion and drop it.
 
-### Final re-open-and-drop pass (mandatory)
+### Recording the outcome
 
-1. Walk your Detailed Findings once more, applying the bar and the exclusion
-   list above. Remove every finding that fails.
-2. Count what you kept (`k`) and what you dropped (`d`).
-3. Record the outcome in the report's **Executive Summary** as a single line:
+Record what you kept (`k`) and dropped (`d`) in the report's **Executive
+Summary** as a single line:
 
-   ```text
-   Self-cross-check: kept <k> / dropped <d>.
-   ```
-
-   When `d > 0`, name the dropped findings (title + the bar/exclusion reason)
-   in one short list under that line, so the filtering is auditable and never
-   silent.
+```text
+Self-cross-check: kept <k> / dropped <d>.
+```
 
-A lens that keeps every finding still records `dropped 0` — the line's absence
-is itself a defect (it means the pass did not run).
+When `d > 0`, name the dropped findings (title + the bar/exclusion reason) in
+one short list under that line, so the filtering is auditable and never
+silent. A lens that keeps every finding still records `dropped 0`.
 
 ## Severity tally (mandatory, machine-readable) {#severity-tally}
 
@@ -261,55 +254,35 @@ available; every path emits the **identical** report contract (the finding-block
 skeleton above), so downstream consumers (`audit-to-stories`) are agnostic to
 which path produced it.
 
-1. **Subagent dispatch (first-class).** Dispatch the lens as a single
+1. **One auditor per lens (the default).** Dispatch the lens as exactly one
    `subagent_type: auditor` call — the standalone boot context in
    [`../../agents/auditor.md`](../../agents/auditor.md) carries the read-only
    MUSTs, the finding-block skeleton, the severity scale, and the
    self-cross-check bar, so the child needs only the lens's own dimensions to
    run. The subagent returns the **report path plus the Executive Summary**
    (including the self-cross-check line); the parent never needs the full
-   findings inline. This is the default: the auditor boots without the full
-   project closure, so the spawn is cheap relative to running the lens inline
-   in the parent's context.
-
-   - **Per-dimension fan-out (heavyweight lenses).** `audit-architecture`,
-     `audit-performance`, and `audit-documentation` carry enough independent
-     dimensions to be worth fanning out: dispatch one `subagent_type: auditor`
-     call **per dimension** in a single turn via
-     [`parallel-tooling.md`](parallel-tooling.md) Rule 3, then **merge** the
+   findings inline. One auditor reads the repo once; per-dimension agents each
+   re-read it, so the single dispatch is the cheap path, not a compromise.
+
+   - **Per-dimension fan-out (operator request only).** Fan a lens out only
+     when the operator's invocation explicitly asks for it. Then dispatch one
+     `subagent_type: auditor` call **per dimension** in a single turn via
+     [`parallel-tooling.md`](parallel-tooling.md) Rule 3, and **merge** the
      per-dimension findings under this file's self-cross-check (the merge is
-     where cross-dimension duplicates and false positives are dropped). Respect
-     the nesting-depth budget and the concurrency cap that Rule 3 documents.
+     where cross-dimension duplicates and false positives are dropped). Never
+     fan out on your own judgment of a lens's size.
+   - **No nested fan-out.** An auditor never dispatches sub-agents of its own.
+     The fan-out, when requested, happens once, at the caller.
 
 2. **Sequential inline execution (documented fallback).** When subagent
    dispatch is unavailable, run the lens's steps turn-by-turn in the current
    context exactly as written, ending with the self-cross-check. This changes
    nothing about the report contract.
 
-> **Orchestrated dynamic-workflow path (optimization note).** Six lenses ship a
-> saved project workflow at `.claude/workflows/audit-<lens>.workflow.js` that,
-> **when Claude Code dynamic workflows are available** (runtime is Claude Code,
-> `disableWorkflows` unset, version `>= 2.1.154`), fans the dimensions out as
-> parallel read-only subagents and runs an independent adversarial cross-check
-> stage before synthesising the report. It derives its per-dimension prompts
-> from the *lens* markdown at run time — the lens stays the single source of
-> truth. This is a performance optimization over path 1, **not** a separate
-> contract, and it is not covered by the No-Shim / hard-cutover rule in
-> [`../../rules/git-conventions.md`](../../rules/git-conventions.md) because
-> there is one report contract and only the execution strategy varies — the
-> same capability-degradation pattern the protocol endorses for live-docs
-> fallback. **The host owns the choice.** Mandrel ships no in-repo strategy
-> selector and no force-override env var: Claude Code launches the saved
-> workflow when it can, and you get path 1 or 2 above when it cannot.
-> Suppress the orchestrated path with `CLAUDE_CODE_DISABLE_WORKFLOWS=1`
-> or `disableWorkflows: true` in `.claude/settings.json`. On the orchestrated
-> path the analysis subagents are granted only read/search tools (`Read`,
-> `Grep`, `Glob`) — the single write is the final report artifact.
-
 ## Parallel tooling {#parallel-tooling}
 
 When a lens batches independent reads/greps, runs a long shell (a scanner, a
-profiler, a suite time), or fans out per-dimension, apply
-[`parallel-tooling.md`](parallel-tooling.md): batch independent reads in one
-turn (Rule 1), run long shells via `run_in_background` + `Monitor` (Rule 2),
-and dispatch N independent units as N `Agent` calls in one turn (Rule 3).
+profiler, a suite time), apply [`parallel-tooling.md`](parallel-tooling.md):
+batch independent reads in one turn (Rule 1) and run long shells via
+`run_in_background` (Rule 2). Rule 3 applies only to the caller of
+an operator-requested per-dimension fan-out — never inside an auditor.

package/.agents/workflows/helpers/deliver-digest.md

@@ -68,8 +68,8 @@ same derived level, so the two cannot disagree. A sensitive footprint
 therefore buys a **deep review**, not a fresh acceptance critic.
 
 > **The ceremony rule, stated once.** The **profile alone** names the verdict
-> owner (Story #5343, narrowed to that one input by #5366): `minimal` /
-> `standard` → `inline`, `strict` → `fresh`. Nothing else moves it — not the
+> owner: `minimal` / `standard` → `inline`, `strict` → `fresh`. Nothing else
+> moves it — not the
 > derived change level, not the footprint's sensitivity, and **not the
 > dispatch mode**: an `inline` Story under `strict` still spawns the fresh
 > maker-blind critic, one nesting level shallower than a dispatched one. The

package/.agents/workflows/helpers/deliver-reference.md

@@ -78,7 +78,9 @@ but not a cycle.
 unblocked it:
 `node .agents/scripts/update-ticket-state.js --ticket <id> --state agent::ready`.
 Do not poll the label yourself while waiting — the HITL pause is the operator's
-turn, not a slow beat.
+turn, not a slow beat. Before resuming, the operator raises session effort one
+step, and raises effort before switching models
+([effort escalation](../../docs/execution-reference.md#session-effort-and-model)).
 
 Each beat re-probes live state: it re-resolves the graph, classifies **done**
 (`agent::done` or a closed issue — including foreign blockers that landed in

package/.agents/workflows/helpers/deliver-story.md

@@ -114,9 +114,14 @@ Do not open the PR or compose a terminal envelope.
 serialized against sibling Stories:
 
 ```bash
-node <main-repo>/.agents/scripts/single-story-close.js --story <storyId> --cwd <main-repo>
+node <main-repo>/.agents/scripts/single-story-close.js --story <storyId> --cwd <main-repo> \
+  [--worker-tokens <n>]
 ```
 
+When the host reported a total-token figure for the story-worker's Agent
+dispatch, pass it as `--worker-tokens <n>` — close records it in its
+result's local `telemetry`; omit it when the host reports none.
+
 **The whole delivery tail** — gates, PR, merge wait, `agent::done` flip,
 post-land tail in one process. Never background it, never delegate it to a
 child, and never end your turn while it is still running: "close is running"

package/.agents/workflows/helpers/parallel-tooling.md

@@ -29,15 +29,17 @@ the batch in parallel; serial calls cost N round-trips for no gain.
 - **Bounded fan-out:** keep the batch ≤ 10 calls per turn. Larger batches
   blow the context budget and obscure the failure surface if one call errors.
 
-## Rule 2 — `run_in_background` + `Monitor` for long shells
+## Rule 2 — `run_in_background` for long shells
 
-Shell commands that exceed roughly 30 seconds (test suites, installs,
-multi-file lints, `git fetch --all`, container builds) **must** use the
-`Bash` tool's `run_in_background: true` flag and stream events via the
-`Monitor` tool. A synchronous `Bash` call holds the assistant turn open for
-the full duration and blocks every other parallel opportunity.
+A shell command that can outrun the host's synchronous Bash ceiling, or that
+would idle the turn while independent work waits (test suites, installs,
+multi-file lints, `git fetch --all`, container builds), runs with the `Bash`
+tool's `run_in_background: true` flag; its completion notification is the
+signal to proceed. Attach `Monitor` only when you must act on output before
+the command exits.
 
-- **Tool primitives:** `Bash(run_in_background: true)` + `Monitor`.
+- **Tool primitives:** `Bash(run_in_background: true)`; `Monitor` only when
+  mid-run output matters.
 - **When:** `npm test`, `npm ci`, full-repo `eslint`/`biome` runs, long
   fetches, anything you would have prefixed with `nohup` in a terminal.
 - **Anti-pattern:** synchronous `Bash` with a 600 000 ms timeout used as a
@@ -90,17 +92,13 @@ the same shape as Rule 1 but at the sub-agent layer.
 ## When the rules conflict
 
 If a unit of work is both long (Rule 2) and independent (Rule 1 or 3),
-prefer the higher-numbered rule — the parallelism gain compounds the
-background-shell gain. Concretely: dispatch the `Agent` calls in one turn
-(Rule 3), and **inside** each sub-agent let it apply Rule 2 to its own
-long-running shells — and, within the supported nesting depth budget
-(verified depth 2, announced max depth 5), let it apply
-**Rule 3** to its own independent sub-units as well, not only Rule 2
-background shells. A sub-agent is a full orchestrator at its own level:
-recursive `Agent` fan-out is available to it, so the host does not need to
-micromanage the child's shell **or** dispatch strategy. Mind the depth
-budget and the compounding cost — every nesting level re-pays the
-always-loaded context (see [`instructions.md` § 4](../../instructions.md)).
+dispatch the `Agent` calls in one turn (Rule 3), and **inside** each sub-agent let it apply Rule 2 to its own
+long-running shells. A sub-agent does **not** fan out again on its own
+initiative: every nesting level re-pays the always-loaded context (see
+[`instructions.md` § 4](../../instructions.md)), and the cost compounds with
+depth. The one exception is a dispatch the sub-agent's own workflow names
+explicitly — for example the maker-blind acceptance critic a `strict`-profile
+Story worker spawns — which stays legal at that depth.
 
 ## Constraints
 

package/.agents/workflows/mandrel-deliver.md

@@ -144,7 +144,7 @@ resume what it names.
 
 **Reading the outcome.** Each close ends the Story in one schema-validated
 envelope — `landed` | `pending` | `blocked` | `failed`; statuses, exits and
-fields are digest § 5. `pending` is **not** a failure — run its `nextCommand`.
+fields are digest § 6. `pending` is **not** a failure — run its `nextCommand`.
 
 **Branch model (authoritative).** `story-<id>` → PR → `main` (squash +
 required checks), per digest § 2; dependent Stories land sequentially. The

package/.agents/workflows/mandrel-plan.md

@@ -75,11 +75,12 @@ in Key Assumptions, each a decision-made-by-default.
 `duplicates[]` is non-empty (planning a duplicate of open work stays the
 operator's call): confirm the sharpened plan intent and settle it. Otherwise
 announce the sharpened intent and the advisory line, and continue to
-authoring. Everything else the envelope surfaced — `duplicates[]`, open
-`intake` rows, a truthy `memoryPoolAdvisory.recommend`, a truthy
-`complexitySignals.uiSurface` naming [`/prototype`](prototype.md) (never
-invoke it here) — collapses to **one advisory line** under the gate, which
-never reroutes the run ([ref](helpers/plan-reference.md)).
+authoring. The advisory line names what the envelope surfaced — any
+`duplicates[]` (the stop above), open `intake` rows, a truthy
+`memoryPoolAdvisory.recommend`, a truthy `complexitySignals.uiSurface`
+naming [`/prototype`](prototype.md) (never invoke it here) — as
+**one advisory line** under the gate; the line itself never reroutes the run
+([ref](helpers/plan-reference.md)).
 Under `--yes`, auto-proceed.
 
 ### 2. Author

package/docs/CHANGELOG.md

@@ -15,6 +15,32 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.66.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.65.0...mandrel-v2.66.0) (2026-09-26)
+
+
+### Added
+
+* record per-Story retry causes and per-provider review halts at close ([#5435](https://github.com/dsj1984/mandrel/issues/5435)) ([#5441](https://github.com/dsj1984/mandrel/issues/5441)) ([c7bfd5a](https://github.com/dsj1984/mandrel/commit/c7bfd5ab2be417889f45a85f92145704ac580b88))
+
+
+### Fixed
+
+* make the quality instruments fail loudly instead of silently mis-measuring, and reclaim floor slack ([#5444](https://github.com/dsj1984/mandrel/issues/5444)) ([#5452](https://github.com/dsj1984/mandrel/issues/5452)) ([54eb9fd](https://github.com/dsj1984/mandrel/commit/54eb9fd4660a0476740e0f96daae34e7f1fc754f))
+
+
+### Performance
+
+* stop tests and CLI start-up from spending real wall-clock on host state and sleeps ([#5445](https://github.com/dsj1984/mandrel/issues/5445)) ([#5451](https://github.com/dsj1984/mandrel/issues/5451)) ([8f74d51](https://github.com/dsj1984/mandrel/commit/8f74d51da489b3cc96a0c23053338a718a68708c))
+
+
+### Changed
+
+* burn down the bootstrap hotspots across CRAP, cyclomatic and dead exports ([#5447](https://github.com/dsj1984/mandrel/issues/5447)) ([#5455](https://github.com/dsj1984/mandrel/issues/5455)) ([be9e666](https://github.com/dsj1984/mandrel/commit/be9e6665011547be9396670f9a7486951ca1cd81))
+* burn down the orchestration and signals complexity outliers ([#5449](https://github.com/dsj1984/mandrel/issues/5449)) ([#5456](https://github.com/dsj1984/mandrel/issues/5456)) ([208cede](https://github.com/dsj1984/mandrel/commit/208cede77cb8186bf479cb6e190b8e2849347bbf))
+* collapse duplicated CLI plumbing: standard-args flag switches and the sync-agents/sync-commands clone ([#5448](https://github.com/dsj1984/mandrel/issues/5448)) ([#5454](https://github.com/dsj1984/mandrel/issues/5454)) ([5df933b](https://github.com/dsj1984/mandrel/commit/5df933b7c567730eae0ed47b172a8ac670d0831e))
+* decompose the single-story-close and confirm-merge hot path ([#5446](https://github.com/dsj1984/mandrel/issues/5446)) ([#5453](https://github.com/dsj1984/mandrel/issues/5453)) ([3b7a5ae](https://github.com/dsj1984/mandrel/commit/3b7a5ae2b7391e16dddfd18d64e7fe4528bdc48c))
+* trim the always-on closure and document the effort policy ([#5437](https://github.com/dsj1984/mandrel/issues/5437)) ([#5439](https://github.com/dsj1984/mandrel/issues/5439)) ([61d3c66](https://github.com/dsj1984/mandrel/commit/61d3c666637d38144cee7abcc7a50f28c332201a))
+
 ## [2.65.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.64.0...mandrel-v2.65.0) (2026-09-24)
 
 

package/lib/cli/guarded-sync.js

@@ -0,0 +1,87 @@
+// lib/cli/guarded-sync.js
+/**
+ * Shared body of `mandrel sync-commands` / `mandrel sync-agents`: run a
+ * `.agents/scripts/` projector in a child process, forwarding its exit code.
+ * Refuses first when `.agents/` does not match the running CLI (version
+ * marker, else the `agents-drift` check): `.claude/*` is gitignored, so a
+ * stale projection surfaces only when an agent hits a missing module.
+ * The marker is read from `cwd()`; `PROJECT_ROOT` only names this CLI's version.
+ */
+
+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, '..', '..');
+
+function resolveOwnPackageVersion(fsImpl) {
+  const parsed = JSON.parse(
+    fsImpl.readFileSync(path.join(PROJECT_ROOT, 'package.json'), 'utf8'),
+  );
+  return String(parsed.version);
+}
+
+function refusalReason(projectRoot, { fs, ownVersion, checkAgentsDrift, cwd }) {
+  const marker = readVersionMarker(projectRoot, fs);
+  if (marker) {
+    const own = ownVersion ?? resolveOwnPackageVersion(fs);
+    if (marker === own) return null;
+    return {
+      what: `the materialized .agents/ tree is v${marker} but the running CLI is v${own}`,
+      fix: 're-materialize .agents/ to the current version',
+    };
+  }
+  const drift = (checkAgentsDrift ?? (() => runAgentsDrift({ cwd })))();
+  if (drift.ok) return null;
+  return {
+    what: `.agents/ appears to have drifted from the installed package payload (${drift.detail})`,
+    fix: 'restore the materialized .agents/ payload',
+  };
+}
+
+/**
+ * @param {{ command: string, target: string, script: string }} spec
+ * @param {string[]} _argv - Unused; reserved for future flags.
+ * @param {object} [opts] - Injectable runner, cwd, fs, version and I/O seams.
+ */
+export function runGuardedSync(
+  { command, target, script },
+  _argv = [],
+  {
+    runner = spawnSync,
+    cwd = () => process.cwd(),
+    fs = nodeFs,
+    ownVersion,
+    checkAgentsDrift,
+    writeErr = (s) => process.stderr.write(s),
+    exit = (code) => process.exit(code),
+  } = {},
+) {
+  const refusal = refusalReason(cwd(), {
+    fs,
+    ownVersion,
+    checkAgentsDrift,
+    cwd,
+  });
+  if (refusal) {
+    writeErr(
+      `mandrel ${command}: ${refusal.what} — refusing to project ${target} from a mismatched tree.\n` +
+        `   → Run \`mandrel sync\` to ${refusal.fix}, then re-run.\n`,
+    );
+    exit(1);
+    return;
+  }
+  const syncScript = path.join(PROJECT_ROOT, '.agents', 'scripts', script);
+  const result = runner(process.execPath, [syncScript], {
+    stdio: 'inherit',
+    env: process.env,
+  });
+  const exitCode = result.status ?? 1;
+  if (exitCode !== 0) exit(exitCode);
+}

package/lib/cli/sync-agents.js

@@ -1,97 +1,14 @@
 // lib/cli/sync-agents.js
-/**
- * `mandrel sync-agents`: project `.agents/agents/` into `.claude/agents/` via
- * `.agents/scripts/sync-claude-agents.js`. Exact sibling of
- * `sync-commands.js` — same child-process delegation, same marker-gated
- * refusal and anchor rule (see that module's doc).
- */
+/** `mandrel sync-agents`: project `.agents/agents/` into `.claude/agents/`. */
 
-import { spawnSync } from 'node:child_process';
-import nodeFs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { runGuardedSync } from './guarded-sync.js';
 
-import { runAgentsDrift } from './registry.js';
-import { readVersionMarker } from './sync.js';
+const SPEC = {
+  command: 'sync-agents',
+  target: '.claude/agents/',
+  script: 'sync-claude-agents.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',
-);
-
-/**
- * @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);
-}
-
-/**
- * @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);
-  }
+export default function run(argv, opts) {
+  runGuardedSync(SPEC, argv, opts);
 }