@boyingliu01/xp-gate 0.35.21 → 0.35.23

package/lib/agent-runtime-journal.js

@@ -0,0 +1,347 @@
+/**
+ * xp-gate agent-runtime-journal — measure the AGENTS.md runtime anti-patterns.
+ *
+ * `AGENTS.md` §AGENT RUNTIME DISCIPLINE has named three rules since 2026-10-30.
+ * Rule 1 (native read/grep/glob instead of shell) took effect — measurement on
+ * 2026-11-02 showed pure-read shell calls fall from 32.7% to 0.2%. Rules 2 and
+ * 3 did not: calls/step stayed at 1.02, and `job_output` was called with an
+ * explicit `wait: true` 103 times across three days, blocking 8.9 h.
+ *
+ * The reason a prose rule was ignored is that nothing measured it. This module
+ * turns those rules into numbers read from the agent's own session journals, so
+ * `retro`/CI can show the cost instead of restating the prohibition.
+ *
+ * Zero npm dependencies (Node built-ins only) — `src/npm-package/` ships
+ * zero-install, and `zlib.zstdDecompressSync` covers the journal format.
+ *
+ * @module agent-runtime-journal
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const zlib = require('zlib');
+
+/**
+ * A tool call cannot plausibly run longer than this. Beyond it, the recorded
+ * span measures a session resume or log flush, not work: the 2026-10-30
+ * diagnosis found single `pwsh` calls "lasting" 78 hours because the matching
+ * result was only written at the next compaction/prune. Excluding them is what
+ * makes the totals mean anything.
+ */
+const DEFAULT_MAX_PLAUSIBLE_MS = 30 * 60 * 1000;
+
+/** A `job_output` call counts as blocking once it waits longer than this. */
+const DEFAULT_BLOCKING_THRESHOLD_MS = 30 * 1000;
+
+/** Journal filename used by the DSH session store. */
+const JOURNAL_BASENAME = 'session.v4.jsonl';
+
+/**
+ * Parse a session journal buffer, accepting both the zstd-compressed on-disk
+ * form and plain UTF-8 (so fixtures need no encoder).
+ *
+ * Malformed lines are skipped rather than discarding the whole journal: one
+ * truncated tail line must not erase an otherwise usable session.
+ *
+ * @param {Buffer|string} buffer
+ * @returns {Array<object>} parsed events
+ */
+function parseSessionBuffer(buffer) {
+  let text;
+  const buf = Buffer.isBuffer(buffer) ? buffer : Buffer.from(String(buffer), 'utf8');
+  // zstd magic number: 0x28 0xB5 0x2F 0xFD (little endian 0xFD2FB528).
+  if (buf.length >= 4 && buf[0] === 0x28 && buf[1] === 0xb5 && buf[2] === 0x2f && buf[3] === 0xfd) {
+    try {
+      text = zlib.zstdDecompressSync(buf).toString('utf8');
+    } catch {
+      return [];
+    }
+  } else {
+    text = buf.toString('utf8');
+  }
+
+  const events = [];
+  for (const line of text.split('\n')) {
+    if (!line) continue;
+    try {
+      events.push(JSON.parse(line));
+    } catch {
+      // Skip a malformed line; the rest of the journal is still valid.
+    }
+  }
+  return events;
+}
+
+/**
+ * Resolve the journal file inside a session directory.
+ * @param {string} dir
+ * @returns {string|null} absolute path, or null when absent
+ */
+function journalPathIn(dir) {
+  for (const name of [JOURNAL_BASENAME, `${JOURNAL_BASENAME}.zstd`]) {
+    const p = path.join(dir, name);
+    if (fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+/**
+ * Classify a shell command against the waiting anti-patterns rule 3 forbids.
+ *
+ * Returned flags are independent: a command can be both a poll loop and a
+ * literal sleep, and reporting them separately keeps the cause visible.
+ *
+ * @param {string} command
+ * @returns {{sleep: boolean, pollLoop: boolean, ciPolling: boolean, oversizedTimeout: boolean}}
+ */
+function classifyCommand(command) {
+  const cmd = String(command || '');
+  return {
+    // `sleep N` as a command, not the word "sleepless" inside an argument.
+    sleep: /(?:^|[;&|(]\s*|\s)sleep\s+\d+/.test(cmd),
+    pollLoop: /for\s+\w+\s+in\s+\$\(seq|while\s+true|while\s*:\s*;/.test(cmd),
+    ciPolling: /gh\s+run\s+(?:list|watch|view)/.test(cmd),
+    // `timeout` only counts as oversized past 10 minutes; the diagnosis found
+    // 375 such calls whose p50 runtime was 6.3 s — budget far above reality.
+    oversizedTimeout: /timeout\s+(\d{3,})\b/.test(cmd) && Number((cmd.match(/timeout\s+(\d{3,})\b/) || [])[1]) >= 600,
+  };
+}
+
+/**
+ * Median of a numeric array (0 for an empty input).
+ * @param {number[]} values
+ * @returns {number}
+ */
+function median(values) {
+  if (!values.length) return 0;
+  const sorted = values.slice().sort((a, b) => a - b);
+  const mid = sorted.length >> 1;
+  return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+
+/**
+ * Round to one decimal place without leaving float noise in JSON output.
+ * @param {number} value
+ * @returns {number}
+ */
+function round1(value) {
+  return Math.round(value * 10) / 10;
+}
+
+/**
+ * Build a measured record for every tool call in one journal.
+ *
+ * @param {Array<object>} events
+ * @param {number} maxPlausibleMs
+ * @returns {Array<{name: string, t: number, durMs: number|null, args: object, implausible: boolean, turn: number, step: number}>}
+ */
+function extractCalls(events, maxPlausibleMs) {
+  /** @type {Map<string, number>} callId -> result timestamp */
+  const endedAt = new Map();
+  for (const e of events) {
+    if (e && e.type === 'tool/result') {
+      const id = e.data && e.data.message && e.data.message.toolCallId;
+      if (id && typeof e.time === 'number') endedAt.set(id, e.time);
+    }
+  }
+
+  const calls = [];
+  for (const e of events) {
+    if (!e || e.type !== 'tool/call') continue;
+    const d = e.data || {};
+    let args = {};
+    try {
+      args = JSON.parse(d.arguments || '{}');
+    } catch {
+      args = {};
+    }
+    const end = endedAt.get(d.callId);
+    const durMs = typeof end === 'number' && typeof e.time === 'number' ? end - e.time : null;
+    calls.push({
+      name: d.name || 'unknown',
+      t: e.time,
+      durMs,
+      args,
+      implausible: durMs !== null && (durMs < 0 || durMs > maxPlausibleMs),
+      turn: d.turn ?? 0,
+      step: d.step ?? 0,
+    });
+  }
+  return calls;
+}
+
+/**
+ * Summarise tool-call efficiency across a set of session directories.
+ *
+ * @param {string[]} sessionDirs directories containing `session.v4.jsonl[.zstd]`
+ * @param {{maxPlausibleMs?: number, blockingThresholdMs?: number, sinceMs?: number, untilMs?: number}} [options]
+ *   `sinceMs`/`untilMs` bound the calls considered, so the same journal supports a
+ *   before/after comparison instead of only an all-time total.
+ * @returns {object} report
+ */
+function analyseSessions(sessionDirs, options = {}) {
+  const maxPlausibleMs = options.maxPlausibleMs ?? DEFAULT_MAX_PLAUSIBLE_MS;
+  const blockingThresholdMs = options.blockingThresholdMs ?? DEFAULT_BLOCKING_THRESHOLD_MS;
+  const sinceMs = typeof options.sinceMs === 'number' ? options.sinceMs : -Infinity;
+  const untilMs = typeof options.untilMs === 'number' ? options.untilMs : Infinity;
+
+  const allCalls = [];
+  let sessions = 0;
+
+  for (const dir of sessionDirs || []) {
+    const jp = journalPathIn(dir);
+    if (!jp) continue;
+    let buf;
+    try {
+      buf = fs.readFileSync(jp);
+    } catch {
+      continue;
+    }
+    const events = parseSessionBuffer(buf);
+    if (!events.length) continue;
+    sessions += 1;
+    for (const call of extractCalls(events, maxPlausibleMs)) {
+      if (typeof call.t === 'number' && call.t >= sinceMs && call.t < untilMs) allCalls.push(call);
+    }
+  }
+
+  const plausible = allCalls.filter((c) => c.durMs !== null ? !c.implausible : true);
+  const implausible = allCalls.filter((c) => c.implausible);
+  const timed = plausible.filter((c) => c.durMs !== null);
+
+  // ---- rule 3a: job_output blocking ----
+  const jobCalls = plausible.filter((c) => c.name === 'job_output');
+  const blocking = jobCalls.filter((c) => c.durMs !== null && c.durMs > blockingThresholdMs);
+  const explicitWaitTrue = jobCalls.filter((c) => c.args && c.args.wait === true);
+
+  // ---- rule 3b: idle waiting inside bash ----
+  const bashCalls = plausible.filter((c) => c.name === 'bash' || c.name === 'pwsh' || c.name === 'powershell');
+  const sleep = [];
+  const pollLoop = [];
+  const ciPolling = [];
+  const oversizedTimeout = [];
+  for (const c of bashCalls) {
+    const flags = classifyCommand(c.args && c.args.command);
+    if (flags.sleep) sleep.push(c);
+    if (flags.pollLoop) pollLoop.push(c);
+    if (flags.ciPolling) ciPolling.push(c);
+    if (flags.oversizedTimeout) oversizedTimeout.push(c);
+  }
+
+  // ---- rule 2: call batching ----
+  const perStep = new Map();
+  for (const c of plausible) {
+    if (!c.turn && !c.step) continue;
+    const key = `${c.turn}:${c.step}`;
+    perStep.set(key, (perStep.get(key) || 0) + 1);
+  }
+  const stepCounts = Array.from(perStep.values());
+  const stepsWithMultiple = stepCounts.filter((n) => n >= 2).length;
+
+  const total = (arr) => arr.reduce((acc, c) => acc + (c.durMs || 0), 0);
+
+  return {
+    sessions,
+    toolCalls: allCalls.length,
+    timedCalls: timed.length,
+    implausible: { count: implausible.length, totalMs: total(implausible) },
+    maxPlausibleMs,
+    blockingJobOutput: {
+      count: blocking.length,
+      totalMs: total(blocking),
+      explicitWaitTrue: explicitWaitTrue.length,
+      maxMs: blocking.length ? Math.max(...blocking.map((c) => c.durMs)) : 0,
+      thresholdMs: blockingThresholdMs,
+    },
+    idleWait: {
+      sleep: { count: sleep.length, totalMs: total(sleep) },
+      pollLoop: { count: pollLoop.length, totalMs: total(pollLoop) },
+      ciPolling: { count: ciPolling.length, totalMs: total(ciPolling) },
+      oversizedTimeout: { count: oversizedTimeout.length, totalMs: total(oversizedTimeout) },
+    },
+    batching: {
+      stepsWithCalls: stepCounts.length,
+      stepsWithMultipleCalls: stepsWithMultiple,
+      batchedRatioPct: stepCounts.length ? round1((stepsWithMultiple / stepCounts.length) * 100) : 0,
+      callsPerStep: stepCounts.length ? round1((plausible.length / stepCounts.length) * 100) / 100 : 0,
+    },
+    toolMedianMs: median(timed.map((c) => c.durMs)),
+  };
+}
+
+/**
+ * Reduce a report to a one-screen summary for `retro`/CI output.
+ *
+ * Deliberately reports NOT MEASURABLE instead of 0% when the journal holds
+ * nothing to measure — a zero that means "no data" reads as "no problem", the
+ * same false-green the gate-coverage work (#636) set out to kill.
+ *
+ * @param {object} report
+ * @returns {string[]} at most 15 lines
+ */
+function summariseForSlot(report) {
+  if (!report || report.toolCalls === 0) {
+    return ['Runtime efficiency: NOT MEASURABLE (no tool calls in journal)'];
+  }
+
+  const hours = (ms) => `${round1(ms / 3600000)} h`;
+  const lines = [];
+
+  const blocked = report.blockingJobOutput;
+  lines.push(
+    `job_output blocked >${Math.round(blocked.thresholdMs / 1000)}s: ${blocked.count} call(s), ${hours(blocked.totalMs)}` +
+      ` (explicit wait:true = ${blocked.explicitWaitTrue})`
+  );
+
+  const idle = report.idleWait;
+  lines.push(`literal sleep: ${idle.sleep.count} call(s), ${hours(idle.sleep.totalMs)}`);
+  lines.push(`CI status polling: ${idle.ciPolling.count} call(s), ${hours(idle.ciPolling.totalMs)}`);
+  lines.push(`poll loops (seq/while): ${idle.pollLoop.count} call(s), ${hours(idle.pollLoop.totalMs)}`);
+  lines.push(`oversized timeout (>=600s): ${idle.oversizedTimeout.count} call(s), ${hours(idle.oversizedTimeout.totalMs)}`);
+
+  const batch = report.batching;
+  const batchLine = batch.stepsWithCalls
+    ? `call batching: ${batch.callsPerStep} calls/step, ${batch.batchedRatioPct}% of steps batched (target >=2.0)`
+    : 'call batching: NOT MEASURABLE (no steps in journal)';
+  lines.push(batchLine);
+
+  if (report.implausible.count) {
+    lines.push(`excluded ${report.implausible.count} implausible duration(s) (resume/log-flush artifacts)`);
+  }
+
+  return lines.slice(0, 15);
+}
+
+/**
+ * Discover session directories under a root (one level deep).
+ * @param {string} root
+ * @returns {string[]}
+ */
+function discoverSessionDirs(root) {
+  let entries;
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const dirs = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const full = path.join(root, entry.name);
+    if (journalPathIn(full)) dirs.push(full);
+  }
+  return dirs;
+}
+
+module.exports = {
+  DEFAULT_MAX_PLAUSIBLE_MS,
+  DEFAULT_BLOCKING_THRESHOLD_MS,
+  parseSessionBuffer,
+  journalPathIn,
+  classifyCommand,
+  analyseSessions,
+  summariseForSlot,
+  discoverSessionDirs,
+};

package/lib/mattpocock-license-verdict.json

@@ -2,6 +2,6 @@
   "verdict": "PASS",
   "license_type": "MIT",
   "sha256": "0e7ac423bf2c6e223b7c5b156f8cf72da49d748e56a1641402c31f22ad07dbb5",
-  "checked_at": "2026-11-02T04:04:20.814Z",
+  "checked_at": "2026-11-02T15:52:57.140Z",
   "source": "network"
 }

package/lib/mirror-sync.js

@@ -0,0 +1,335 @@
+/**
+ * Mirror sync — bring every canonical tree / npm-package mirror back to parity.
+ *
+ * xp-gate keeps several trees in two places: `githooks/` is the source of truth
+ * and `src/npm-package/hooks/` is the copy that ships. Four `check-*-mirror.sh`
+ * scripts guard that duplication, but all four only *detect* drift; repairing it
+ * is a hand-copy, and the hand-copy is where the real cost shows up: over the
+ * three days to 2026-11-02, 29 of 141 commits (20.6%) touched only mirrors,
+ * version stamps, AGENTS.md copies and CHANGELOG, and the mirror/sync scripts
+ * were invoked 306 times.
+ *
+ * Two defects are fixed here:
+ *
+ * 1. **False drift from untracked build artifacts.** `check-hook-lib-mirror.sh`
+ *    compared directory listings, so a `githooks/lib/__pycache__/` created by a
+ *    Python test run made a byte-identical tree look out of sync. The set of
+ *    files that matter is the set git tracks — an artifact that is not in the
+ *    repository cannot be drift, because it cannot be committed.
+ * 2. **No repair path.** `syncMirrors` copies what is missing, rewrites what
+ *    differs, and prunes what the canonical side no longer has — idempotently,
+ *    so a second run is a no-op and the operation can run on every commit
+ *    without becoming a churn generator itself.
+ *
+ * @module mirror-sync
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+/**
+ * Directory names that are never mirrored, even when tracked.
+ *
+ * A build artifact directory is machine state, not source. Copying it would
+ * make the mirror differ between machines for reasons no commit explains.
+ */
+const SYNC_EXCLUDES = Object.freeze(['__pycache__', 'node_modules', '.git', '.DS_Store']);
+
+/**
+ * The canonical -> mirror pairs this repository maintains for whole trees.
+ *
+ * Declared rather than discovered recursively: a glob that silently matches
+ * nothing would report "in sync" forever, which is the false green this whole
+ * task exists to remove.
+ *
+ * Deliberately NOT including `githooks` -> `src/npm-package/hooks`: that mapping
+ * is a curated *file list* (see `HOOK_MIRROR_FILES` in
+ * `scripts/check-hook-mirror.sh`), not the whole directory. `githooks/` also
+ * holds `__tests__/`, `AGENTS.md` and the adapters subtree, none of which ship.
+ * Mirroring the directory wholesale would copy 500+ files into the npm package —
+ * treating "canonical has it" as "the mirror should have it" where the project
+ * never said so.
+ *
+ * Per-pair `exclude` mirrors the guard scripts exactly. `src/principles` already
+ * excludes `__tests__` (check-hook-mirror.sh:98); a sync that copied them would
+ * ship test code in the package and make the guard fail immediately afterwards.
+ */
+const KNOWN_PAIRS = Object.freeze([
+  { canonical: 'githooks/adapters', mirror: 'src/npm-package/adapters' },
+  { canonical: 'githooks/lib', mirror: 'src/npm-package/hooks/lib' },
+  { canonical: 'src/principles', mirror: 'src/npm-package/principles', exclude: ['__tests__'] },
+  { canonical: 'src/build-integrity', mirror: 'src/npm-package/build-integrity' },
+  { canonical: 'skills', mirror: 'src/npm-package/skills' },
+]);
+
+/**
+ * List files under `dir` relative to `dir`, honouring exclusions.
+ *
+ * @param {string} root repository root
+ * @param {string} dir directory relative to root
+ * @returns {string[]} relative slash-separated paths
+ */
+function listFiles(root, dir) {
+  const abs = path.join(root, dir);
+  const out = [];
+  const walk = (current, prefix) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (SYNC_EXCLUDES.includes(entry.name)) continue;
+      const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        walk(path.join(current, entry.name), rel);
+      } else if (entry.isFile()) {
+        out.push(rel);
+      }
+    }
+  };
+  walk(abs, '');
+  return out.sort();
+}
+
+/**
+ * List the files git tracks under `dir` that also exist on disk.
+ *
+ * The disk check matters: `git ls-files` reports the index, so a file deleted
+ * from the working tree (a mirror copy removed to simulate drift, or a fix in
+ * progress) is still listed. Reading it would throw ENOENT inside the diff.
+ *
+ * When `dir` is not inside a git repository (or git is unavailable), fall back to
+ * a plain walk — the caller is then responsible for the artifact caveat, but a
+ * check that crashes outside git is worse than one that reports what it sees.
+ *
+ * @param {string} root repository root
+ * @param {string} dir directory relative to root
+ * @returns {string[]}
+ */
+function listTrackedFiles(root, dir) {
+  const normalised = dir.replace(/\\/g, '/');
+  let tracked;
+  try {
+    const out = execFileSync('git', ['ls-files', '-z', '--', dir], {
+      cwd: root,
+      encoding: 'utf8',
+      maxBuffer: 64 * 1024 * 1024,
+    });
+    tracked = out
+      .split('\0')
+      .filter(Boolean)
+      .map((p) => p.replace(/\\/g, '/'))
+      .filter((p) => p.startsWith(`${normalised}/`))
+      .map((p) => p.slice(normalised.length + 1))
+      .filter((p) => !p.split('/').some((seg) => SYNC_EXCLUDES.includes(seg)));
+  } catch {
+    return listFiles(root, dir);
+  }
+
+  // Keep only what is actually on disk; a tracked-but-deleted file must read as
+  // "missing from this side", which is what the caller then repairs.
+  return tracked
+    .filter((p) => fs.existsSync(path.join(root, dir, p)))
+    .sort();
+}
+
+/**
+ * Compare a canonical tree against its mirror.
+ *
+ * Both sides are compared on the tracked file set so an untracked artifact in
+ * either tree cannot be mistaken for drift.
+ *
+ * @param {string} root repository root
+ * @param {string} canonical canonical dir (relative)
+ * @param {string} mirror mirror dir (relative)
+ * @param {{exclude?: string[]}} [options] extra directory names to skip for this pair
+ * @returns {{inSync: boolean, missing: string[], differing: string[], extra: string[]}}
+ */
+function diffTrees(root, canonical, mirror, options = {}) {
+  const exclude = options.exclude || [];
+  const keep = (rel) => !rel.split('/').some((seg) => exclude.includes(seg));
+  const canonicalFiles = listTrackedFiles(root, canonical).filter(keep);
+  const mirrorFiles = listTrackedFiles(root, mirror).filter(keep);
+  const mirrorSet = new Set(mirrorFiles);
+  const canonicalSet = new Set(canonicalFiles);
+
+  const missing = canonicalFiles.filter((f) => !mirrorSet.has(f));
+  const extra = mirrorFiles.filter((f) => !canonicalSet.has(f));
+  const differing = [];
+  for (const rel of canonicalFiles) {
+    if (!mirrorSet.has(rel)) continue;
+    const a = fs.readFileSync(path.join(root, canonical, rel));
+    const b = fs.readFileSync(path.join(root, mirror, rel));
+    if (!a.equals(b)) differing.push(rel);
+  }
+
+  return {
+    inSync: missing.length === 0 && differing.length === 0 && extra.length === 0,
+    missing,
+    differing,
+    extra,
+  };
+}
+
+/**
+ * Discover the known pairs that actually exist in this repository.
+ *
+ * A pair is only returned when both sides are present on disk: reporting a pair
+ * whose mirror does not exist yet would make `syncMirrors` create trees the
+ * project never asked for.
+ *
+ * @param {string} root repository root
+ * @returns {Array<{canonical: string, mirror: string}>}
+ */
+function collectMirrorPairs(root) {
+  return KNOWN_PAIRS.filter(
+    (pair) =>
+      fs.existsSync(path.join(root, pair.canonical)) && fs.existsSync(path.join(root, pair.mirror))
+  );
+}
+
+/**
+ * Copy one file, preserving its executable bit.
+ * @param {string} from
+ * @param {string} to
+ */
+function copyFile(from, to) {
+  fs.mkdirSync(path.dirname(to), { recursive: true });
+  fs.copyFileSync(from, to);
+  // Hooks that lose +x stop running, and the failure looks like "the gate is
+  // silently skipped" rather than a permissions error.
+  try {
+    const mode = fs.statSync(from).mode;
+    fs.chmodSync(to, mode & 0o777);
+  } catch {
+    // chmod is a no-op on Windows; the content copy already succeeded.
+  }
+}
+
+/**
+ * Bring mirrors into parity with their canonical trees.
+ *
+ * @param {string} root repository root
+ * @param {Array<{canonical: string, mirror: string}>} [pairs] defaults to the discoverable known pairs
+ * @param {{dryRun?: boolean, prune?: boolean}} [options]
+ * @returns {{copied: string[], cleaned: string[], pairs: number, dryRun: boolean}}
+ */
+function syncMirrors(root, pairs, options = {}) {
+  const dryRun = options.dryRun === true;
+  const prune = options.prune !== false;
+  const selected = pairs || collectMirrorPairs(root);
+
+  const copied = [];
+  const cleaned = [];
+
+  for (const pair of selected) {
+    const canonicalAbs = path.join(root, pair.canonical);
+    if (!fs.existsSync(canonicalAbs) || !fs.statSync(canonicalAbs).isDirectory()) {
+      // Refusing beats guessing: treating a missing canonical tree as "empty"
+      // would mark every mirrored file an orphan and delete working code.
+      throw new Error(`canonical directory does not exist: ${pair.canonical}`);
+    }
+
+    const diff = diffTrees(root, pair.canonical, pair.mirror, { exclude: pair.exclude });
+    const toWrite = [...diff.missing, ...diff.differing];
+
+    for (const rel of toWrite) {
+      copied.push(rel);
+      if (dryRun) continue;
+      copyFile(path.join(root, pair.canonical, rel), path.join(root, pair.mirror, rel));
+    }
+
+    if (prune) {
+      for (const rel of diff.extra) {
+        cleaned.push(rel);
+        if (dryRun) continue;
+        try {
+          fs.rmSync(path.join(root, pair.mirror, rel));
+        } catch {
+          // A file that vanished between listing and prune is already the goal.
+        }
+      }
+    }
+  }
+
+  return { copied, cleaned, pairs: selected.length, dryRun };
+}
+
+/**
+ * Run the `sync-mirrors` subcommand.
+ *
+ * Defaults to a dry run. Writing is opt-in via `--write`, because the failure
+ * mode of a wrong pair declaration is silent mass overwrite — previewing costs
+ * one round trip and makes the destructive path a deliberate choice.
+ *
+ * `root` is a parameter rather than always `process.cwd()` so tests can point at
+ * a fixture; `process.chdir` is unavailable inside a vitest worker.
+ *
+ * @param {string[]} argv
+ * @param {{root?: string}} [options]
+ * @returns {number} exit code (0 when in sync / repaired; 1 when drift remains after a dry run)
+ */
+function handleSyncMirrors(argv, options = {}) {
+  const args = argv || [];
+  const write = args.includes('--write');
+  const json = args.includes('--json');
+  const root = options.root || process.cwd();
+
+  const pairs = collectMirrorPairs(root);
+  if (pairs.length === 0) {
+    process.stdout.write('sync-mirrors: NOT MEASURABLE (no mirror pairs found — is this the xp-gate repo?)\n');
+    return 1;
+  }
+
+  const before = pairs.map((pair) => ({
+    pair: `${pair.canonical} -> ${pair.mirror}`,
+    diff: diffTrees(root, pair.canonical, pair.mirror, { exclude: pair.exclude }),
+  }));
+  const drifted = before.filter((entry) => !entry.diff.inSync);
+
+  const result = syncMirrors(root, pairs, { dryRun: !write });
+
+  if (json) {
+    process.stdout.write(
+      `${JSON.stringify({ root, write, driftedBefore: drifted.length, ...result }, null, 2)}\n`
+    );
+  } else {
+    for (const entry of before) {
+      const status = entry.diff.inSync ? 'IN SYNC' : 'DRIFT  ';
+      process.stdout.write(`  ${status}  ${entry.pair}\n`);
+      if (!entry.diff.inSync) {
+        if (entry.diff.missing.length) process.stdout.write(`             missing: ${entry.diff.missing.slice(0, 5).join(', ')}\n`);
+        if (entry.diff.differing.length) process.stdout.write(`             differing: ${entry.diff.differing.slice(0, 5).join(', ')}\n`);
+        if (entry.diff.extra.length) process.stdout.write(`             extra: ${entry.diff.extra.slice(0, 5).join(', ')}\n`);
+      }
+    }
+    if (result.copied.length === 0 && result.cleaned.length === 0) {
+      process.stdout.write('All mirrors in sync.\n');
+      return 0;
+    }
+    const verb = write ? 'Wrote' : 'Would write';
+    process.stdout.write(`${verb} ${result.copied.length} file(s), prune ${result.cleaned.length}.\n`);
+    if (!write) {
+      process.stdout.write('Re-run with --write to apply.\n');
+      return 1;
+    }
+  }
+
+  return write ? 0 : drifted.length > 0 ? 1 : 0;
+}
+
+module.exports = {
+  SYNC_EXCLUDES,
+  KNOWN_PAIRS,
+  listFiles,
+  listTrackedFiles,
+  diffTrees,
+  collectMirrorPairs,
+  syncMirrors,
+  handleSyncMirrors,
+};