@boyingliu01/xp-gate 0.35.21 → 0.35.22

package/bin/xp-gate.js

@@ -17,6 +17,8 @@ const { arch } = require('../lib/arch.js');
 const { upgrade } = require('../lib/upgrade.js');
 const { bootstrap } = require('../lib/bootstrap.js');
 const { updateHooks } = require('../lib/update-hooks.js');
+const { handleRuntimeJournal } = require('../lib/runtime-journal.js');
+const { handleSyncMirrors } = require('../lib/mirror-sync.js');
 const gateRunner = require('../lib/gate-runner.js');
 
 // #392-#6: a user-supplied path embedded in a shell command string lets cmd.exe
@@ -350,6 +352,16 @@ const COMMANDS = {
     },
     usage: 'xp-gate retro [--days N] [--all] [--json] [--sprint <id>]'
   },
+  'runtime-journal': {
+    description: 'Measure the AGENTS.md runtime rules (blocking waits, sleep/polling, call batching) from agent session journals (#712)',
+    run: subargs => process.exit(handleRuntimeJournal(subargs)),
+    usage: 'xp-gate runtime-journal [--days N] [--json] [--sessions-dir <path>]'
+  },
+  'sync-mirrors': {
+    description: 'Report or repair drift between canonical trees and their npm-package mirrors; dry-run unless --write (#713)',
+    run: subargs => process.exit(handleSyncMirrors(subargs)),
+    usage: 'xp-gate sync-mirrors [--write] [--json]'
+  },
   'gate-coverage': {
     description: 'One view of compliance against every gate: PASS / DEBT / SKIP / FAIL, with debt and evidence (#636)',
     run: subargs => {

package/lib/__tests__/agent-runtime-journal.test.js

@@ -0,0 +1,302 @@
+/**
+ * TDD: written RED first (per AGENTS.md TDD-GATE spec).
+ * @test REQ-712 Agent runtime efficiency must be measurable from session journals
+ * @intent Expose the four AGENTS.md runtime anti-patterns (blocking job_output,
+ *   literal sleep, CI polling loops, serial tool calls) as machine-checkable
+ *   numbers instead of a prose rule that nobody measures.
+ * @covers AC-712-01
+ * @covers AC-712-02
+ * @covers AC-712-03
+ * @covers AC-712-04
+ * @covers AC-712-05
+ */
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const zlib = require('zlib');
+
+const {
+  analyseSessions,
+  parseSessionBuffer,
+  classifyCommand,
+  summariseForSlot,
+  DEFAULT_MAX_PLAUSIBLE_MS,
+} = require('../agent-runtime-journal');
+
+let TMP_DIR;
+
+beforeAll(() => {
+  TMP_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'runtime-journal-'));
+});
+
+afterAll(() => {
+  fs.rmSync(TMP_DIR, { recursive: true, force: true });
+});
+
+/**
+ * Build a session journal buffer from a compact event list.
+ * @param {Array<object>} events
+ * @returns {string}
+ */
+function journalText(events) {
+  return events.map((e) => JSON.stringify(e)).join('\n') + '\n';
+}
+
+/**
+ * Emit a tool/call + tool/result pair at the given times.
+ * @param {string} callId
+ * @param {string} name
+ * @param {object} args
+ * @param {number} startT
+ * @param {number} endT
+ * @param {{isError?: boolean, text?: string}} [result]
+ * @param {{turn?: number, step?: number}} [pos]
+ * @returns {Array<object>}
+ */
+function toolPair(callId, name, args, startT, endT, result = {}, pos = {}) {
+  const turn = pos.turn ?? 1;
+  const step = pos.step ?? 1;
+  return [
+    { type: 'tool/call', time: startT, data: { turn, step, callId, name, arguments: JSON.stringify(args) } },
+    {
+      type: 'tool/result',
+      time: endT,
+      data: {
+        turn,
+        step,
+        message: {
+          role: 'tool',
+          toolCallId: callId,
+          isError: !!result.isError,
+          content: [{ type: 'text', text: result.text ?? 'ok' }],
+        },
+      },
+    },
+  ];
+}
+
+describe('parseSessionBuffer', () => {
+  it('reads a zstd-compressed session journal', () => {
+    const events = toolPair('c1', 'read', { file_path: '/a.ts' }, 1000, 1010);
+    const buf = zlib.zstdCompressSync(Buffer.from(journalText(events), 'utf8'));
+    const parsed = parseSessionBuffer(buf);
+    expect(parsed).toHaveLength(2);
+    expect(parsed[0].type).toBe('tool/call');
+  });
+
+  it('reads an uncompressed journal too, so fixtures need no encoder', () => {
+    const events = toolPair('c1', 'read', { file_path: '/a.ts' }, 1000, 1010);
+    const parsed = parseSessionBuffer(Buffer.from(journalText(events), 'utf8'));
+    expect(parsed).toHaveLength(2);
+  });
+
+  it('skips malformed lines instead of throwing away the whole journal', () => {
+    const good = toolPair('c1', 'read', {}, 1000, 1010).map((e) => JSON.stringify(e));
+    const text = [good[0], 'not json at all', good[1]].join('\n');
+    const parsed = parseSessionBuffer(Buffer.from(text, 'utf8'));
+    expect(parsed).toHaveLength(2);
+  });
+});
+
+describe('classifyCommand', () => {
+  it('flags a literal sleep', () => {
+    expect(classifyCommand('cd /repo && sleep 600; echo ok').sleep).toBe(true);
+  });
+
+  it('does not flag words that merely contain "sleep"', () => {
+    expect(classifyCommand('echo sleepless').sleep).toBe(false);
+  });
+
+  it('flags a seq-driven polling loop', () => {
+    expect(classifyCommand('for i in $(seq 1 20); do gh run list; done').pollLoop).toBe(true);
+  });
+
+  it('flags gh run status polling', () => {
+    expect(classifyCommand('gh run list --limit 4 --json status').ciPolling).toBe(true);
+    expect(classifyCommand('gh run watch 123').ciPolling).toBe(true);
+  });
+
+  it('flags an oversized explicit timeout', () => {
+    expect(classifyCommand('timeout 1800 npx vitest run').oversizedTimeout).toBe(true);
+    expect(classifyCommand('timeout 60 npx vitest run').oversizedTimeout).toBe(false);
+  });
+});
+
+describe('analyseSessions — AC-712-01 blocking job_output', () => {
+  it('counts job_output calls that block longer than the threshold', () => {
+    const events = [
+      ...toolPair('j1', 'job_output', { job_id: 'b1', wait: true }, 0, 120000),
+      ...toolPair('j2', 'job_output', { job_id: 'b2' }, 200000, 200010),
+    ];
+    const dir = path.join(TMP_DIR, 'a');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'session.v4.jsonl'), journalText(events));
+
+    const report = analyseSessions([dir]);
+    expect(report.blockingJobOutput.count).toBe(1);
+    expect(report.blockingJobOutput.totalMs).toBe(120000);
+  });
+
+  it('counts explicit wait:true separately — the rule names that exact mistake', () => {
+    const events = [
+      ...toolPair('j1', 'job_output', { job_id: 'b1', wait: true }, 0, 1000),
+      ...toolPair('j2', 'job_output', { job_id: 'b2', wait: true }, 2000, 3000),
+      ...toolPair('j3', 'job_output', { job_id: 'b3' }, 4000, 5000),
+    ];
+    const dir = path.join(TMP_DIR, 'b');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'session.v4.jsonl'), journalText(events));
+
+    const report = analyseSessions([dir]);
+    expect(report.blockingJobOutput.explicitWaitTrue).toBe(2);
+  });
+});
+
+describe('analyseSessions — AC-712-02 idle waiting', () => {
+  it('totals literal-sleep commands', () => {
+    const events = [
+      ...toolPair('s1', 'bash', { command: 'sleep 300; echo done' }, 0, 300000),
+      ...toolPair('s2', 'bash', { command: 'npx tsc --noEmit' }, 310000, 320000),
+    ];
+    const dir = path.join(TMP_DIR, 'c');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'session.v4.jsonl'), journalText(events));
+
+    const report = analyseSessions([dir]);
+    expect(report.idleWait.sleep.count).toBe(1);
+    expect(report.idleWait.sleep.totalMs).toBe(300000);
+  });
+
+  it('totals CI polling separately from sleep so the cause stays visible', () => {
+    const events = [
+      ...toolPair('p1', 'bash', { command: 'gh run list --limit 3' }, 0, 5000),
+      ...toolPair('p2', 'bash', { command: 'for i in $(seq 1 30); do sleep 10; done' }, 10000, 600000),
+    ];
+    const dir = path.join(TMP_DIR, 'd');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'session.v4.jsonl'), journalText(events));
+
+    const report = analyseSessions([dir]);
+    expect(report.idleWait.ciPolling.count).toBe(1);
+    expect(report.idleWait.pollLoop.count).toBe(1);
+  });
+});
+
+describe('analyseSessions — AC-712-03 call batching', () => {
+  it('reports calls per step and the share of batched steps', () => {
+    // step 1: two concurrent calls; step 2: one call.
+    const s1 = [
+      ...toolPair('a', 'read', {}, 0, 5, {}, { step: 1 }),
+      ...toolPair('b', 'grep', {}, 0, 5, {}, { step: 1 }),
+    ];
+    const s2 = toolPair('c', 'bash', { command: 'git status' }, 100, 150, {}, { step: 2 });
+    const dir = path.join(TMP_DIR, 'e');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'session.v4.jsonl'), journalText([...s1, ...s2]));
+
+    const report = analyseSessions([dir]);
+    expect(report.batching.stepsWithCalls).toBe(2);
+    expect(report.batching.stepsWithMultipleCalls).toBe(1);
+    expect(report.batching.batchedRatioPct).toBe(50);
+    expect(report.batching.callsPerStep).toBeCloseTo(1.5, 5);
+  });
+});
+
+describe('analyseSessions — AC-712-04 implausible durations', () => {
+  it('excludes resume/flush artifacts above the plausible ceiling', () => {
+    const huge = DEFAULT_MAX_PLAUSIBLE_MS + 1;
+    const events = [
+      ...toolPair('x1', 'bash', { command: 'echo hi' }, 0, huge),
+      ...toolPair('x2', 'bash', { command: 'echo hi' }, huge + 1000, huge + 1010),
+    ];
+    const dir = path.join(TMP_DIR, 'f');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'session.v4.jsonl'), journalText(events));
+
+    const report = analyseSessions([dir]);
+    expect(report.implausible.count).toBe(1);
+    // The surviving sample must not be averaged with the excluded one.
+    expect(report.toolCalls).toBe(2);
+    expect(report.timedCalls).toBe(1);
+  });
+});
+
+describe('summariseForSlot — AC-712-05 output contract', () => {
+  it('emits a one-screen summary naming every measured anti-pattern', () => {
+    const events = [
+      ...toolPair('j1', 'job_output', { wait: true }, 0, 600000),
+      ...toolPair('s1', 'bash', { command: 'sleep 60' }, 700000, 760000),
+    ];
+    const dir = path.join(TMP_DIR, 'g');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'session.v4.jsonl'), journalText(events));
+
+    const report = analyseSessions([dir]);
+    const lines = summariseForSlot(report);
+    expect(Array.isArray(lines)).toBe(true);
+    expect(lines.length).toBeLessThanOrEqual(15);
+    const text = lines.join('\n');
+    expect(text).toMatch(/job_output/i);
+    expect(text).toMatch(/sleep/i);
+  });
+
+  it('says NOT MEASURABLE rather than 0% when there are no steps to measure', () => {
+    const dir = path.join(TMP_DIR, 'h');
+    fs.mkdirSync(dir, { recursive: true, mode: 0o755 });
+    // Journal with no tool calls at all.
+    fs.writeFileSync(path.join(dir, 'session.v4.jsonl'), journalText([{ type: 'session', time: 0 }]));
+
+    const report = analyseSessions([dir]);
+    const text = summariseForSlot(report).join('\n');
+    expect(text).toMatch(/NOT MEASURABLE/i);
+  });
+});
+
+describe('analyseSessions — AC-712-06 time window', () => {
+  it('counts only calls inside [sinceMs, untilMs) so a before/after A/B is possible', () => {
+    const events = [
+      // Before the window: one 600s sleep that must NOT be counted.
+      ...toolPair('old', 'bash', { command: 'sleep 600' }, 1000, 601000),
+      // Inside the window: one 60s sleep that must be counted.
+      ...toolPair('new', 'bash', { command: 'sleep 60' }, 2_000_000, 2_060_000),
+    ];
+    const dir = path.join(TMP_DIR, 'win');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'session.v4.jsonl'), journalText(events));
+
+    const report = analyseSessions([dir], { sinceMs: 1_500_000 });
+    expect(report.idleWait.sleep.count).toBe(1);
+    expect(report.idleWait.sleep.totalMs).toBe(60_000);
+  });
+
+  it('excludes calls at or after untilMs', () => {
+    const events = [
+      ...toolPair('in', 'bash', { command: 'sleep 60' }, 2_000_000, 2_060_000),
+      ...toolPair('after', 'bash', { command: 'sleep 300' }, 3_000_000, 3_300_000),
+    ];
+    const dir = path.join(TMP_DIR, 'win2');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, 'session.v4.jsonl'), journalText(events));
+
+    const report = analyseSessions([dir], { sinceMs: 1_000_000, untilMs: 2_500_000 });
+    expect(report.idleWait.sleep.count).toBe(1);
+    expect(report.idleWait.sleep.totalMs).toBe(60_000);
+  });
+});
+
+describe('analyseSessions — robustness', () => {
+  it('ignores a directory with no journal instead of crashing', () => {
+    const dir = path.join(TMP_DIR, 'empty');
+    fs.mkdirSync(dir, { recursive: true });
+    const report = analyseSessions([dir]);
+    expect(report.toolCalls).toBe(0);
+  });
+
+  it('returns an empty-but-shaped report for an empty session list', () => {
+    const report = analyseSessions([]);
+    expect(report.sessions).toBe(0);
+    expect(report.batching.stepsWithCalls).toBe(0);
+  });
+});

package/lib/__tests__/mirror-sync.test.js

@@ -0,0 +1,277 @@
+/**
+ * TDD: written RED first (per AGENTS.md TDD-GATE spec).
+ * @test REQ-713 Mirror checks must ignore untracked build artifacts, and a
+ *   one-shot sync must bring every mirror back to byte parity
+ * @intent The hook-lib mirror check failed on a machine where `githooks/lib`
+ *   held an untracked `__pycache__/` — Python byte-compiled the helper during a
+ *   test run. The canonical file set was otherwise byte-identical to the mirror.
+ *   A false failure here costs a real fix cycle at commit time, which is exactly
+ *   the rework this task set out to remove. The check must compare what git
+ *   tracks, and a single command must repair drift instead of hand-copying.
+ * @covers AC-713-01
+ * @covers AC-713-02
+ * @covers AC-713-03
+ * @covers AC-713-04
+ */
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const {
+  collectMirrorPairs,
+  diffTrees,
+  syncMirrors,
+  handleSyncMirrors,
+  SYNC_EXCLUDES,
+} = require('../mirror-sync');
+
+let TMP_REPO;
+
+beforeEach(() => {
+  TMP_REPO = fs.mkdtempSync(path.join(os.tmpdir(), 'mirror-sync-'));
+  execFileSync('git', ['init', '-q'], { cwd: TMP_REPO });
+  execFileSync('git', ['config', 'user.email', 'test@example.com'], { cwd: TMP_REPO });
+  execFileSync('git', ['config', 'user.name', 'Test'], { cwd: TMP_REPO });
+});
+
+afterEach(() => {
+  fs.rmSync(TMP_REPO, { recursive: true, force: true });
+});
+
+/**
+ * Write a file, creating parent directories.
+ * @param {string} root
+ * @param {string} rel
+ * @param {string} content
+ */
+function write(root, rel, content) {
+  const full = path.join(root, rel);
+  fs.mkdirSync(path.dirname(full), { recursive: true });
+  fs.writeFileSync(full, content);
+}
+
+/**
+ * Stage everything so the files count as tracked.
+ * @param {string} root
+ */
+function trackAll(root) {
+  execFileSync('git', ['add', '-A', '-f'], { cwd: root });
+}
+
+describe('diffTrees — AC-713-01 untracked artifacts are not drift', () => {
+  it('ignores an untracked build artifact in the canonical tree', () => {
+    write(TMP_REPO, 'canonical/a.sh', 'echo a\n');
+    write(TMP_REPO, 'mirror/a.sh', 'echo a\n');
+    // The artifact that broke the real check: untracked, gitignored.
+    write(TMP_REPO, 'canonical/__pycache__/helper.pyc', 'binary');
+    write(TMP_REPO, '.gitignore', '__pycache__/\n');
+    trackAll(TMP_REPO);
+
+    const diff = diffTrees(TMP_REPO, 'canonical', 'mirror');
+    expect(diff.missing).toEqual([]);
+    expect(diff.differing).toEqual([]);
+    expect(diff.inSync).toBe(true);
+  });
+
+  it('still reports a genuinely missing mirrored file', () => {
+    write(TMP_REPO, 'canonical/a.sh', 'echo a\n');
+    write(TMP_REPO, 'canonical/b.sh', 'echo b\n');
+    write(TMP_REPO, 'mirror/a.sh', 'echo a\n');
+    trackAll(TMP_REPO);
+
+    const diff = diffTrees(TMP_REPO, 'canonical', 'mirror');
+    expect(diff.inSync).toBe(false);
+    expect(diff.missing).toContain('b.sh');
+  });
+
+  it('reports byte differences, not just missing files', () => {
+    write(TMP_REPO, 'canonical/a.sh', 'echo a\n');
+    write(TMP_REPO, 'mirror/a.sh', 'echo CHANGED\n');
+    trackAll(TMP_REPO);
+
+    const diff = diffTrees(TMP_REPO, 'canonical', 'mirror');
+    expect(diff.inSync).toBe(false);
+    expect(diff.differing).toContain('a.sh');
+  });
+
+  it('excludes declared noise directories even when they are tracked', () => {
+    write(TMP_REPO, 'canonical/a.sh', 'echo a\n');
+    write(TMP_REPO, 'mirror/a.sh', 'echo a\n');
+    write(TMP_REPO, 'canonical/node_modules/x.js', 'x');
+    write(TMP_REPO, '.gitignore', 'node_modules/\n');
+    trackAll(TMP_REPO);
+
+    const diff = diffTrees(TMP_REPO, 'canonical', 'mirror');
+    expect(diff.inSync).toBe(true);
+    expect(SYNC_EXCLUDES).toContain('node_modules');
+  });
+});
+
+describe('diffTrees — per-pair excludes', () => {
+  it('honours a pair-specific exclude, matching the guard script it mirrors', () => {
+    // check-hook-mirror.sh:98 compares src/principles with `-x __tests__`.
+    // A sync that copied tests into the package would ship test code and make
+    // the guard fail on the very next run.
+    write(TMP_REPO, 'canonical/lib.ts', 'export const a = 1;\n');
+    write(TMP_REPO, 'canonical/__tests__/lib.test.ts', 'test\n');
+    write(TMP_REPO, 'mirror/lib.ts', 'export const a = 1;\n');
+    trackAll(TMP_REPO);
+
+    const withoutExclude = diffTrees(TMP_REPO, 'canonical', 'mirror');
+    expect(withoutExclude.inSync).toBe(false);
+
+    const withExclude = diffTrees(TMP_REPO, 'canonical', 'mirror', { exclude: ['__tests__'] });
+    expect(withExclude.inSync).toBe(true);
+    expect(withExclude.missing).toEqual([]);
+  });
+});
+
+describe('collectMirrorPairs — AC-713-02 pair discovery', () => {
+  it('discovers a pair only when both sides exist', () => {
+    write(TMP_REPO, 'githooks/lib/a.sh', 'echo a\n');
+    write(TMP_REPO, 'src/npm-package/hooks/lib/a.sh', 'echo a\n');
+    trackAll(TMP_REPO);
+
+    const pairs = collectMirrorPairs(TMP_REPO);
+    const found = pairs.find((p) => p.canonical === 'githooks/lib' && p.mirror === 'src/npm-package/hooks/lib');
+    expect(found).toBeDefined();
+  });
+
+  it('does not invent a pair for a canonical tree with no mirror', () => {
+    write(TMP_REPO, 'githooks/lib/a.sh', 'echo a\n');
+    trackAll(TMP_REPO);
+
+    const pairs = collectMirrorPairs(TMP_REPO);
+    const found = pairs.find((p) => p.canonical === 'githooks/lib');
+    expect(found).toBeUndefined();
+  });
+});
+
+describe('syncMirrors — AC-713-03 repair instead of hand-copying', () => {
+  it('copies a missing file and produces parity', () => {
+    write(TMP_REPO, 'canonical/a.sh', 'echo a\n');
+    write(TMP_REPO, 'canonical/b.sh', 'echo b\n');
+    write(TMP_REPO, 'mirror/a.sh', 'echo a\n');
+    write(TMP_REPO, 'mirror/b.sh', 'echo b\n');
+    trackAll(TMP_REPO);
+
+    // Remove the mirror copy to simulate drift.
+    fs.rmSync(path.join(TMP_REPO, 'mirror/b.sh'));
+
+    const result = syncMirrors(TMP_REPO, [{ canonical: 'canonical', mirror: 'mirror' }]);
+    expect(result.copied).toContain('b.sh');
+    expect(diffTrees(TMP_REPO, 'canonical', 'mirror').inSync).toBe(true);
+  });
+
+  it('rewrites a differing file to match the canonical bytes', () => {
+    write(TMP_REPO, 'canonical/a.sh', 'echo canonical\n');
+    write(TMP_REPO, 'mirror/a.sh', 'echo stale\n');
+    trackAll(TMP_REPO);
+
+    syncMirrors(TMP_REPO, [{ canonical: 'canonical', mirror: 'mirror' }]);
+    expect(fs.readFileSync(path.join(TMP_REPO, 'mirror/a.sh'), 'utf8')).toBe('echo canonical\n');
+  });
+
+  it('is idempotent — a second run changes nothing', () => {
+    write(TMP_REPO, 'canonical/a.sh', 'echo a\n');
+    write(TMP_REPO, 'mirror/a.sh', 'echo a\n');
+    trackAll(TMP_REPO);
+
+    syncMirrors(TMP_REPO, [{ canonical: 'canonical', mirror: 'mirror' }]);
+    const second = syncMirrors(TMP_REPO, [{ canonical: 'canonical', mirror: 'mirror' }]);
+    expect(second.copied).toEqual([]);
+    expect(second.cleaned).toEqual([]);
+  });
+
+  it('supports --dry-run so the caller can preview before writing', () => {
+    write(TMP_REPO, 'canonical/a.sh', 'echo fresh\n');
+    write(TMP_REPO, 'mirror/a.sh', 'echo stale\n');
+    trackAll(TMP_REPO);
+
+    const result = syncMirrors(TMP_REPO, [{ canonical: 'canonical', mirror: 'mirror' }], { dryRun: true });
+    expect(result.copied).toContain('a.sh');
+    // Nothing was written.
+    expect(fs.readFileSync(path.join(TMP_REPO, 'mirror/a.sh'), 'utf8')).toBe('echo stale\n');
+  });
+
+  it('prunes a mirror file whose canonical source is gone', () => {
+    write(TMP_REPO, 'canonical/a.sh', 'echo a\n');
+    write(TMP_REPO, 'mirror/a.sh', 'echo a\n');
+    write(TMP_REPO, 'mirror/orphan.sh', 'echo orphan\n');
+    trackAll(TMP_REPO);
+
+    const result = syncMirrors(TMP_REPO, [{ canonical: 'canonical', mirror: 'mirror' }]);
+    expect(result.cleaned).toContain('orphan.sh');
+    expect(fs.existsSync(path.join(TMP_REPO, 'mirror/orphan.sh'))).toBe(false);
+  });
+});
+
+describe('handleSyncMirrors — CLI contract', () => {
+  let captured;
+  let outSpy;
+
+  beforeEach(() => {
+    captured = [];
+    outSpy = vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => {
+      captured.push(String(chunk));
+      return true;
+    });
+  });
+
+  afterEach(() => {
+    outSpy.mockRestore();
+  });
+
+  it('reports NOT MEASURABLE and exits 1 outside a repo with no pairs', () => {
+    expect(handleSyncMirrors([], { root: TMP_REPO })).toBe(1);
+    expect(captured.join('')).toMatch(/NOT MEASURABLE/i);
+  });
+
+  it('defaults to a dry run and does not modify files', () => {
+    write(TMP_REPO, 'githooks/lib/a.sh', 'echo canonical\n');
+    write(TMP_REPO, 'src/npm-package/hooks/lib/a.sh', 'echo stale\n');
+    trackAll(TMP_REPO);
+
+    const code = handleSyncMirrors([], { root: TMP_REPO });
+    // Dry run with pending work is a non-zero exit so CI can act on it.
+    expect(code).toBe(1);
+    expect(captured.join('')).toMatch(/Re-run with --write/);
+    expect(fs.readFileSync(path.join(TMP_REPO, 'src/npm-package/hooks/lib/a.sh'), 'utf8')).toBe('echo stale\n');
+  });
+
+  it('applies the repair with --write and reports it', () => {
+    write(TMP_REPO, 'githooks/lib/a.sh', 'echo canonical\n');
+    write(TMP_REPO, 'src/npm-package/hooks/lib/a.sh', 'echo stale\n');
+    trackAll(TMP_REPO);
+
+    expect(handleSyncMirrors(['--write'], { root: TMP_REPO })).toBe(0);
+    expect(fs.readFileSync(path.join(TMP_REPO, 'src/npm-package/hooks/lib/a.sh'), 'utf8')).toBe('echo canonical\n');
+  });
+});
+
+describe('syncMirrors — AC-713-04 safety', () => {
+  it('refuses a pair whose canonical directory does not exist', () => {
+    write(TMP_REPO, 'mirror/a.sh', 'echo a\n');
+    trackAll(TMP_REPO);
+
+    // Guessing "canonical is empty, so wipe the mirror" would delete real files.
+    expect(() => syncMirrors(TMP_REPO, [{ canonical: 'canonical', mirror: 'mirror' }])).toThrow(/canonical/i);
+  });
+
+  it('preserves the executable bit so hooks stay runnable', () => {
+    write(TMP_REPO, 'canonical/hook.sh', '#!/bin/sh\necho a\n');
+    fs.chmodSync(path.join(TMP_REPO, 'canonical/hook.sh'), 0o755);
+    write(TMP_REPO, 'mirror/hook.sh', '#!/bin/sh\necho a\n');
+    trackAll(TMP_REPO);
+
+    syncMirrors(TMP_REPO, [{ canonical: 'canonical', mirror: 'mirror' }]);
+    const mode = fs.statSync(path.join(TMP_REPO, 'mirror/hook.sh')).mode;
+    // On Windows the exec bit is not meaningful; only assert where it applies.
+    if (process.platform !== 'win32') {
+      expect(mode & 0o111).toBeTruthy();
+    }
+  });
+});