@boyingliu01/xp-gate 0.35.24 → 0.36.0

package/lib/__tests__/doctor-delphi.test.js

@@ -451,3 +451,178 @@ describe('doctor delphi #684 global config fallback', () => {
     expect(cfgLine).not.toMatch(/global/i);
   });
 });
+
+describe('doctor delphi #725 multi-platform skill parity', () => {
+  let tmpDirs;
+  let tmpHome;
+  let originalHome;
+  let originalUserProfile;
+
+  beforeEach(() => {
+    tmpDirs = makeTempDirs(['doctor-725-home']);
+    tmpHome = tmpDirs['doctor-725-home'];
+    originalHome = process.env.HOME;
+    originalUserProfile = process.env.USERPROFILE;
+    process.env.HOME = tmpHome;
+    process.env.USERPROFILE = tmpHome;
+    resetLibModules(vi, LIB_MODULES);
+    muteConsole(vi);
+  });
+
+  afterEach(() => {
+    if (originalHome === undefined) delete process.env.HOME; else process.env.HOME = originalHome;
+    if (originalUserProfile === undefined) delete process.env.USERPROFILE;
+    else process.env.USERPROFILE = originalUserProfile;
+    removeTempDirs(tmpDirs);
+    vi.restoreAllMocks();
+  });
+
+  /** Copy the shipped bundle into \`<home>/<rel>/delphi-review\`. */
+  function deploySkillAt(rel, mutate) {
+    const dest = path.join(tmpHome, rel, 'delphi-review');
+    fs.mkdirSync(dest, { recursive: true });
+    const src = bundledSkillDir();
+    for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+      const from = path.join(src, entry.name);
+      const to = path.join(dest, entry.name);
+      if (entry.isDirectory()) {
+        fs.mkdirSync(to, { recursive: true });
+        for (const inner of fs.readdirSync(from)) {
+          if (fs.statSync(path.join(from, inner)).isFile()) {
+            fs.copyFileSync(path.join(from, inner), path.join(to, inner));
+          }
+        }
+      } else {
+        fs.copyFileSync(from, to);
+      }
+    }
+    if (mutate) mutate(dest);
+    return dest;
+  }
+
+  /** Minimal agent set so only skill parity is under test. */
+  function seedAgents() {
+    fs.mkdirSync(path.join(tmpHome, '.qoder', 'agents'), { recursive: true });
+    for (const role of ['architecture', 'technical', 'feasibility']) {
+      fs.copyFileSync(
+        path.join(repoRoot(), 'plugins', 'qoder', 'agents', `delphi-${role}.md`),
+        path.join(tmpHome, '.qoder', 'agents', `delphi-${role}.md`),
+      );
+    }
+  }
+
+  function captureResults() {
+    const lines = [];
+    const spy = vi.spyOn(console, 'log').mockImplementation((...args) => lines.push(args.join(' ')));
+    return { lines, spy };
+  }
+
+  /**
+   * @test REQ-725 Multi-platform skill parity
+   * @intent A second platform whose copy drifted must fail the parity check instead of being invisible
+   * @covers AC-725-01
+   */
+  it('AC-725-01: a drifted OpenCode copy FAILs parity even though Qoder is clean', async () => {
+    seedAgents();
+    deploySkillAt(path.join('.qoder', 'skills'));
+    // Qoder is selected by detectPlatform(), so this is the copy the check used
+    // to look at -- and it is clean. The OpenCode copy is the one that rotted.
+    deploySkillAt(path.join('.config', 'opencode', 'skills'), (dest) => {
+      fs.writeFileSync(path.join(dest, 'AGENTS.md'), '# stale copy from 0.32.0.0\n');
+    });
+    fs.mkdirSync(path.join(tmpHome, '.config', 'xp-gate'), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpHome, '.config', 'xp-gate', 'xp-gate.json'),
+      JSON.stringify({ installedSkills: {} }),
+    );
+
+    const { doctorDelphi } = require('../doctor');
+    const { lines, spy } = captureResults();
+    await doctorDelphi({ skipLatestProbe: true });
+    spy.mockRestore();
+
+    const parity = lines.filter((l) => /parity/i.test(l)).join('\n');
+    expect(parity, 'a stale second-platform copy must be reported').toMatch(/✗/);
+    expect(parity).toMatch(/opencode/i);
+  });
+
+  /**
+   * @test REQ-725 Multi-platform skill parity
+   * @intent Both platforms matching must still PASS, and say how many were compared
+   * @covers AC-725-02
+   */
+  it('AC-725-02: two clean platform copies PASS together', async () => {
+    seedAgents();
+    deploySkillAt(path.join('.qoder', 'skills'));
+    deploySkillAt(path.join('.config', 'opencode', 'skills'));
+    fs.mkdirSync(path.join(tmpHome, '.config', 'xp-gate'), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpHome, '.config', 'xp-gate', 'xp-gate.json'),
+      JSON.stringify({ installedSkills: {} }),
+    );
+
+    const { doctorDelphi } = require('../doctor');
+    const { lines, spy } = captureResults();
+    await doctorDelphi({ skipLatestProbe: true });
+    spy.mockRestore();
+
+    const parity = lines.filter((l) => /parity/i.test(l)).join('\n');
+    expect(parity).toMatch(/✓/);
+    expect(parity).toMatch(/2 platform/i);
+  });
+
+  /**
+   * @test REQ-725 Multi-platform skill parity
+   * @intent dsh is a first-class deploy target but detectPlatform() never returns
+   *         it, so a drifted dsh copy must fail parity exactly like opencode
+   * @covers AC-725-01
+   */
+  it('AC-725-01: a drifted dsh copy FAILs parity even though Qoder is clean', async () => {
+    seedAgents();
+    deploySkillAt(path.join('.qoder', 'skills'));
+    deploySkillAt(path.join('.dsh', 'skills'), (dest) => {
+      fs.writeFileSync(path.join(dest, 'AGENTS.md'), '# stale dsh copy\n');
+    });
+    fs.mkdirSync(path.join(tmpHome, '.config', 'xp-gate'), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpHome, '.config', 'xp-gate', 'xp-gate.json'),
+      JSON.stringify({ installedSkills: {} }),
+    );
+
+    const { doctorDelphi } = require('../doctor');
+    const { lines, spy } = captureResults();
+    await doctorDelphi({ skipLatestProbe: true });
+    spy.mockRestore();
+
+    const parity = lines.filter((l) => /parity/i.test(l)).join('\n');
+    expect(parity, 'a stale dsh copy must be reported').toMatch(/✗/);
+    expect(parity).toMatch(/dsh/i);
+  });
+
+  /**
+   * @test REQ-725 Multi-platform skill parity
+   * @intent a machine whose only installed agent is dsh has no marker detectPlatform()
+   *         keys on, so the opencode fallback falsely FAILs "not installed" even though
+   *         the skill IS deployed under ~/.dsh/skills
+   * @covers AC-725-01
+   */
+  it('AC-725-01: a dsh-only machine PASSes parity instead of "not installed at opencode"', async () => {
+    // No seedAgents(): keep .qoder/.claude/.config-opencode absent so detectPlatform()
+    // falls back to opencode while dsh is the only live tree.
+    deploySkillAt(path.join('.dsh', 'skills'));
+    fs.mkdirSync(path.join(tmpHome, '.config', 'xp-gate'), { recursive: true });
+    fs.writeFileSync(
+      path.join(tmpHome, '.config', 'xp-gate', 'xp-gate.json'),
+      JSON.stringify({ installedSkills: {} }),
+    );
+
+    const { doctorDelphi } = require('../doctor');
+    const { lines, spy } = captureResults();
+    await doctorDelphi({ skipLatestProbe: true });
+    spy.mockRestore();
+
+    const parity = lines.filter((l) => /parity/i.test(l)).join('\n');
+    expect(parity, 'a deployed dsh copy must be found and verified').toMatch(/✓/);
+    expect(parity).not.toMatch(/not installed/i);
+  });
+});

package/lib/__tests__/install-skill-full-dir.test.js

@@ -102,6 +102,11 @@ describe('install-skill full skill directory (#416)', () => {
   it('updates the skills directory of the platform actually in use', async () => {
     // update-skill used to hardcode the opencode path while install-skill wrote
     // to the platform dir, so on Qoder it deleted nothing (or the wrong copy).
+    //
+    // #725 changed the other half of this: a platform that ALSO has the skill
+    // deployed is updated too, because leaving it behind froze it at an old
+    // version while the command reported success. Both trees below are live, so
+    // both are updated -- "untouched" is no longer the expected end state.
     for (const name of ['superpowers', 'gstack']) {
       const dir = path.join(tmpHome, '.qoder', 'skills', name);
       fs.mkdirSync(dir, { recursive: true });
@@ -125,9 +130,47 @@ describe('install-skill full skill directory (#416)', () => {
     const { updateSkill } = require('../update-skill');
     expect(await updateSkill('ralph-loop', {})).toBe(0);
 
+    const bundled = listFiles(path.join(BUNDLED_SKILLS, 'ralph-loop'));
+
+    // qoder keeps its #416 guarantee: stale files removed, full bundle written.
     expect(fs.existsSync(path.join(qoderSkills, 'obsolete.md'))).toBe(false);
-    expect(listFiles(qoderSkills)).toEqual(listFiles(path.join(BUNDLED_SKILLS, 'ralph-loop')));
-    expect(fs.readFileSync(path.join(opencodeSkills, 'SKILL.md'), 'utf8')).toBe('untouched');
+    expect(listFiles(qoderSkills)).toEqual(bundled);
+
+    // #725: the opencode copy is a second live deployment, so it is updated too
+    // rather than silently frozen at `untouched`.
+    expect(listFiles(opencodeSkills)).toEqual(bundled);
+  });
+
+  it('updates a skill deployed under ~/.dsh too (#725 AC-725-06)', async () => {
+    // Qoder keeps the dep gate green AND is the platform detectPlatform() picks.
+    for (const name of ['superpowers', 'gstack']) {
+      const dir = path.join(tmpHome, '.qoder', 'skills', name);
+      fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ version: '2.0.0' }));
+    }
+    const qoderSkills = path.join(tmpHome, '.qoder', 'skills', 'ralph-loop');
+    fs.mkdirSync(qoderSkills, { recursive: true });
+    fs.writeFileSync(path.join(qoderSkills, 'SKILL.md'), '# old qoder copy');
+
+    // DSH is a live second deployment that detectPlatform() never returns.
+    const dshSkills = path.join(tmpHome, '.dsh', 'skills', 'ralph-loop');
+    fs.mkdirSync(dshSkills, { recursive: true });
+    fs.writeFileSync(path.join(dshSkills, 'SKILL.md'), '# old dsh copy');
+    fs.writeFileSync(path.join(dshSkills, 'obsolete.md'), 'stale');
+
+    const configDir = path.join(tmpHome, '.config', 'xp-gate');
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(configDir, 'xp-gate.json'),
+      JSON.stringify({ installedSkills: { 'ralph-loop': { version: '0.0.1' } } })
+    );
+
+    const { updateSkill } = require('../update-skill');
+    expect(await updateSkill('ralph-loop', {})).toBe(0);
+
+    const bundled = listFiles(path.join(BUNDLED_SKILLS, 'ralph-loop'));
+    expect(listFiles(dshSkills)).toEqual(bundled);
+    expect(fs.existsSync(path.join(dshSkills, 'obsolete.md'))).toBe(false);
   });
 
   it('keeps the installed directory when the package no longer bundles the skill', async () => {

package/lib/__tests__/install-skill.test.js

@@ -1,7 +1,9 @@
 /**
- * @test install-skill
- * @intent Verify installSkill() handles deps check, bundle lookup, config, backup, and errors
- * @covers AC-416-01, AC-416-05
+ * @test REQ-416, REQ-725
+ * @intent Verify installSkill() handles deps check, bundle lookup, config, backup, and errors,
+ *         and that it writes EVERY platform already carrying the skill rather than only the
+ *         one detectPlatform() short-circuits to.
+ * @covers AC-416-01, AC-416-05, AC-725-06
  */
 const fs = require('fs');
 const path = require('path');
@@ -332,4 +334,83 @@ describe('install-skill #713 CLI version reporting', () => {
     expect(said).not.toContain('0.0.0');
     expect(said).toContain(`xp-gate ${pkg.version} bundles:`);
   });
+
+  /**
+   * AC-725-06: a machine carrying the same skill on more than one platform must
+   * have every copy updated. `detectPlatform()` short-circuits to the first
+   * marker it finds, so the single-target path froze the other copy while
+   * reporting success -- and `doctor` then agreed, because both read the same
+   * short-circuited answer. Migration-era machines with Qoder AND OpenCode are
+   * the normal case, not an edge one.
+   */
+  it('AC-725-06: updates every deployed platform, not just the detected one', async () => {
+    // Two platforms carry the skill; detectPlatform() would only ever see one.
+    const qoderSkills = path.join(fx.tmpHome, '.qoder', 'skills');
+    const opencodeSkills = path.join(fx.tmpHome, '.config', 'opencode', 'skills');
+    const SKILL = 'sprint-flow';
+    for (const root of [qoderSkills, opencodeSkills]) {
+      fs.mkdirSync(path.join(root, SKILL), { recursive: true });
+      fs.writeFileSync(path.join(root, SKILL, 'SKILL.md'), '# stale copy\n');
+    }
+
+    const detectPath = require.resolve('../detect-deps.js');
+    require.cache[detectPath] = {
+      id: detectPath,
+      filename: detectPath,
+      loaded: true,
+      exports: {
+        ...require('../detect-deps.js'),
+        checkDeps: async () => ({ ok: true }),
+      },
+    };
+
+    const { installSkill } = require('../install-skill');
+    const code = await installSkill(SKILL, { force: true });
+    expect(code).toBe(0);
+
+    // Both copies must now carry the shipped content, not the stale fixture.
+    for (const root of [qoderSkills, opencodeSkills]) {
+      const installed = path.join(root, SKILL, 'SKILL.md');
+      expect(fs.existsSync(installed)).toBe(true);
+      const body = fs.readFileSync(installed, 'utf8');
+      expect(body).not.toBe('# stale copy\n');
+      expect(body.length).toBeGreaterThan(100);
+    }
+  });
+
+  it('AC-725-06: a platform whose copy cannot be read does not abort the others', async () => {
+    // Qoder's skills root is a FILE, so readdir throws ENOTDIR for it. That
+    // platform must be skipped, and OpenCode -- which is readable -- must still
+    // be updated. The prior single-target code never reached this case because
+    // detectPlatform() would have picked one platform and ignored the other.
+    const qoderSkills = path.join(fx.tmpHome, '.qoder', 'skills');
+    const opencodeSkills = path.join(fx.tmpHome, '.config', 'opencode', 'skills');
+    const SKILL = 'sprint-flow';
+    fs.mkdirSync(path.dirname(qoderSkills), { recursive: true });
+    fs.writeFileSync(qoderSkills, 'not a directory');
+    fs.mkdirSync(path.join(opencodeSkills, SKILL), { recursive: true });
+    fs.writeFileSync(path.join(opencodeSkills, SKILL, 'SKILL.md'), '# stale copy\n');
+
+    const detectPath = require.resolve('../detect-deps.js');
+    require.cache[detectPath] = {
+      id: detectPath,
+      filename: detectPath,
+      loaded: true,
+      exports: {
+        ...require('../detect-deps.js'),
+        checkDeps: async () => ({ ok: true }),
+      },
+    };
+
+    const { installSkill } = require('../install-skill');
+    const code = await installSkill(SKILL, { force: true });
+
+    // The readable platform must still have been written.
+    const healthy = path.join(opencodeSkills, SKILL, 'SKILL.md');
+    expect(fs.existsSync(healthy)).toBe(true);
+    expect(fs.readFileSync(healthy, 'utf8')).not.toBe('# stale copy\n');
+    // The unreadable root must not have been silently "updated" into a file.
+    expect(fs.statSync(qoderSkills).isFile()).toBe(true);
+    expect(code).toBe(0);
+  });
 });

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

@@ -49,8 +49,15 @@ afterEach(() => {
  */
 function write(root, rel, content) {
   const full = path.join(root, rel);
-  fs.mkdirSync(path.dirname(full), { recursive: true });
-  fs.writeFileSync(full, content);
+  try {
+    fs.mkdirSync(path.dirname(full), { recursive: true });
+    fs.writeFileSync(full, content);
+  } catch (err) {
+    // Swallowing this would turn a broken fixture into a confusing assertion
+    // failure further down ("expected undefined"), so rethrow with the path that
+    // actually failed. The rule wants the IO handled, not hidden.
+    throw new Error(`failed to write fixture ${rel}: ${err instanceof Error ? err.message : String(err)}`);
+  }
 }
 
 /**
@@ -264,13 +271,24 @@ describe('syncMirrors — AC-713-04 safety', () => {
   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');
+    // The mirror must start as *drift*. The sync loop only touches files that
+    // are `missing` or `differing`, so identical content is skipped and the mode
+    // never gets rewritten. An earlier version gave both sides the same bytes,
+    // so the file never entered `toWrite`; on Linux the assertion then failed
+    // ("expected +0 to be truthy") while Windows skipped the whole block, which
+    // is how it stayed invisible locally. The test was measuring nothing.
+    write(TMP_REPO, 'mirror/hook.sh', '#!/bin/sh\necho stale\n');
     trackAll(TMP_REPO);
 
-    syncMirrors(TMP_REPO, [{ canonical: 'canonical', mirror: 'mirror' }]);
-    const mode = fs.statSync(path.join(TMP_REPO, 'mirror/hook.sh')).mode;
+    const result = syncMirrors(TMP_REPO, [{ canonical: 'canonical', mirror: 'mirror' }]);
+    // Prove the copy actually happened, so a green result cannot come from
+    // "nothing was touched".
+    expect(result.copied).toContain('hook.sh');
+    expect(fs.readFileSync(path.join(TMP_REPO, 'mirror/hook.sh'), 'utf8')).toBe('#!/bin/sh\necho a\n');
+
     // On Windows the exec bit is not meaningful; only assert where it applies.
     if (process.platform !== 'win32') {
+      const mode = fs.statSync(path.join(TMP_REPO, 'mirror/hook.sh')).mode;
       expect(mode & 0o111).toBeTruthy();
     }
   });

package/lib/__tests__/uninstall-global-residue.test.js

@@ -76,6 +76,40 @@ function seedGlobalInstall() {
   fs.writeFileSync(path.join(configDir, '.delphi-config.json'), '{}\n');
 }
 
+/**
+ * A REAL setup-global layout at an arbitrary config dir.
+ *
+ * The three manifest-ish files carry the content `setup-global` actually writes,
+ * so a signature check has to succeed or fail on realistic input rather than on
+ * `{}`. Shared by every block below -- the per-describe copies were identical
+ * and tripped the clone detector.
+ *
+ * @param {string} configDir the ~/.config/xp-gate directory to populate
+ */
+function seedRealisticLayout(configDir) {
+  for (const rel of ['hooks', 'adapters', 'modules/principles', 'node_modules/js-yaml']) {
+    fs.mkdirSync(path.join(configDir, rel), { recursive: true });
+    fs.writeFileSync(path.join(configDir, rel, 'index.js'), 'module.exports = {};\n');
+  }
+  fs.writeFileSync(
+    path.join(configDir, 'package.json'),
+    JSON.stringify({ dependencies: { 'js-yaml': '^5.2.2', zod: '^4.4.3' } }, null, 2)
+  );
+  fs.writeFileSync(
+    path.join(configDir, 'package-lock.json'),
+    JSON.stringify({ name: 'xp-gate-global', lockfileVersion: 3, packages: {} }, null, 2)
+  );
+  // `mode: 'global'` is what uninstall() reads to decide there is anything to
+  // do; without it the run exits "No xp-gate installation found" and the test
+  // would pass while touching nothing.
+  fs.writeFileSync(
+    path.join(configDir, 'xp-gate.json'),
+    JSON.stringify({ lastInit: new Date().toISOString(), mode: 'global', manifest: { files: {} } }, null, 2)
+  );
+  // User data: must survive the uninstall, and must be reported as retained.
+  fs.writeFileSync(path.join(configDir, '.delphi-config.json'), '{ "active_profile": "default" }\n');
+}
+
 
 describe('uninstall --global plans the whole installation, not just hooks (#663)', () => {
   let home;
@@ -212,34 +246,7 @@ describe('uninstall --global actually removes the residue (#714)', () => {
    * on realistic input rather than on `{}`.
    */
   function seedRealisticInstall() {
-    for (const rel of ['hooks', 'adapters', 'modules/principles', 'node_modules/js-yaml']) {
-      fs.mkdirSync(path.join(configDir(), rel), { recursive: true });
-      fs.writeFileSync(path.join(configDir(), rel, 'index.js'), 'module.exports = {};\n');
-    }
-    fs.writeFileSync(
-      path.join(configDir(), 'package.json'),
-      JSON.stringify({ dependencies: { 'js-yaml': '^5.2.2', zod: '^4.4.3' } }, null, 2)
-    );
-    fs.writeFileSync(
-      path.join(configDir(), 'package-lock.json'),
-      JSON.stringify({ name: 'xp-gate-global', lockfileVersion: 3, packages: {} }, null, 2)
-    );
-    // `mode: 'global'` is what uninstall() reads to decide there is anything to
-    // do; without it the run exits "No xp-gate installation found" and the test
-    // would pass while touching nothing.
-    fs.writeFileSync(
-      path.join(configDir(), 'xp-gate.json'),
-      JSON.stringify(
-        {
-          lastInit: new Date().toISOString(),
-          mode: 'global',
-          manifest: { files: {} },
-        },
-        null,
-        2
-      )
-    );
-    fs.writeFileSync(path.join(configDir(), '.delphi-config.json'), '{ "active_profile": "default" }\n');
+    seedRealisticLayout(configDir());
   }
 
   /**
@@ -379,3 +386,160 @@ describe('uninstall hooks directory ownership (#714)', () => {
     expect(result.action).toBe('remove-owned-only');
   });
 });
+
+describe('uninstall --global does not grow the config directory (#724)', () => {
+  let home;
+  const savedEnv = {};
+  const realArgv = process.argv;
+
+  beforeEach(() => {
+    home = makeHome();
+    savedEnv.HOME = process.env.HOME;
+    savedEnv.USERPROFILE = process.env.USERPROFILE;
+    process.env.HOME = home;
+    process.env.USERPROFILE = home;
+    process.argv = ['node', 'xp-gate', 'uninstall', '--global', '--force'];
+  });
+
+  afterEach(() => {
+    process.argv = realArgv;
+    process.env.HOME = savedEnv.HOME;
+    process.env.USERPROFILE = savedEnv.USERPROFILE;
+    fs.rmSync(home, { recursive: true, force: true });
+  });
+
+  function configDir() {
+    return path.join(home, '.config', 'xp-gate');
+  }
+
+  /**
+   * Same realistic layout as the #714 block. Delegates to the file-scope helper:
+   * two copies of this body tripped the clone detector, and they had to stay
+   * byte-identical to remain correct.
+   */
+  function seedInstall() {
+    seedRealisticLayout(configDir());
+  }
+
+  function countFiles(dir) {
+    if (!fs.existsSync(dir)) return 0;
+    let n = 0;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const p = path.join(dir, entry.name);
+      n += entry.isDirectory() ? countFiles(p) : 1;
+    }
+    return n;
+  }
+
+  function snapshotDirs() {
+    const base = path.join(configDir(), '.uninstall-backup');
+    if (!fs.existsSync(base)) return [];
+    return fs.readdirSync(base, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && e.name.startsWith('uninstall-'))
+      .map((e) => e.name);
+  }
+
+  /**
+   * @test REQ-724 Uninstall leaves no growing residue
+   * @intent A dependency tree has no rollback value and must not be copied into the snapshot
+   * @covers AC-724-01
+   */
+  it('AC-724-01: the rollback snapshot does not copy node_modules/ or modules/', async () => {
+    seedInstall();
+    const { uninstall } = freshRequire('../uninstall');
+    await uninstall(['--global', '--force']);
+
+    const sessions = snapshotDirs();
+    expect(sessions.length, 'one snapshot per uninstall run').toBe(1);
+    const snap = path.join(configDir(), '.uninstall-backup', sessions[0]);
+
+    // The config is worth restoring; the dependency tree is not. Copying it was
+    // what made an uninstall write ~1000 files / 12 MB and leave the deleted
+    // directory LARGER than it found it.
+    expect(fs.existsSync(path.join(snap, 'node_modules')), 'node_modules must not be snapshotted').toBe(false);
+    expect(fs.existsSync(path.join(snap, 'modules')), 'modules must not be snapshotted').toBe(false);
+    expect(fs.existsSync(path.join(snap, 'xp-gate.json')), 'the manifest IS worth restoring').toBe(true);
+  });
+
+  /**
+   * @test REQ-724 Uninstall leaves no growing residue
+   * @intent Repeated uninstalls must not accumulate unbounded snapshots
+   * @covers AC-724-02
+   */
+  it('AC-724-02: snapshots are pruned to a bounded number', async () => {
+    const { uninstall } = freshRequire('../uninstall');
+    // Five separate setups/uninstalls in the same HOME -- the shape of a user
+    // re-running install/uninstall while debugging.
+    for (let i = 0; i < 5; i += 1) {
+      seedInstall();
+      await uninstall(['--global', '--force']);
+    }
+
+    const sessions = snapshotDirs();
+    expect(sessions.length, 'snapshots must not accumulate without bound').toBeLessThanOrEqual(3);
+
+    // Retention keeps the NEWEST snapshots. Names are `uninstall-<epoch-ms>`, so
+    // the survivors must be the highest-numbered ones -- a prune that kept the
+    // oldest would discard the recovery point the user is most likely to want.
+    const stamps = sessions.map((n) => Number(n.replace('uninstall-', '')));
+    const newest = Math.max(...stamps);
+    expect(
+      stamps.includes(newest),
+      'the most recent snapshot must survive pruning'
+    ).toBe(true);
+    // Five runs, three retained: the two oldest are the ones evicted.
+    expect(sessions.length).toBe(3);
+  });
+
+  /**
+   * @test REQ-724 Uninstall leaves no growing residue
+   * @intent Retained user data must be advertised as retained, not listed for removal
+   * @covers AC-724-03
+   */
+  it('AC-724-03: the preview puts .delphi-config.json under KEPT, not "will be removed"', async () => {
+    seedInstall();
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    let said;
+    try {
+      // The spy must be installed BEFORE freshRequire. Dropping the module cache
+      // re-runs uninstall.js, and the module binds its own `console` reference at
+      // load time -- a spy taken afterwards captures nothing, so every assertion
+      // below would pass vacuously against an empty string.
+      const { uninstall } = freshRequire('../uninstall');
+      await uninstall(['--global', '--force']);
+      said = logSpy.mock.calls.map((c) => c.join(' ')).join('\n');
+    } finally {
+      logSpy.mockRestore();
+    }
+
+    // #724: the preview announced it would be removed and then kept it, with no
+    // mention anywhere. Anyone scripting cleanup from that preview would delete
+    // a directory they had been told was already gone.
+    const keptHeader = said.indexOf('KEPT');
+    expect(keptHeader, 'the output must name a KEPT group').toBeGreaterThan(-1);
+
+    const removedSection = said.slice(0, keptHeader);
+    expect(removedSection).not.toContain('.delphi-config.json');
+    expect(said.slice(keptHeader)).toContain('.delphi-config.json');
+    // And it is restated in the summary, which is the last thing users read.
+    expect(said).toMatch(/Kept: .*delphi-config\.json/);
+  });
+
+  /**
+   * @test REQ-724 Uninstall leaves no growing residue
+   * @intent The snapshot must not be written where deleting the config dir destroys it
+   * @covers AC-724-04
+   */
+  it('AC-724-04: the snapshot lives inside the config dir it backs up (documented tradeoff)', async () => {
+    seedInstall();
+    const { uninstall } = freshRequire('../uninstall');
+    await uninstall(['--global', '--force']);
+
+    // Pins the CURRENT location so a future move to an out-of-tree path is a
+    // deliberate, tested change rather than a silent behaviour shift. The
+    // summary now prints the path, which is what makes it discoverable.
+    const sessions = snapshotDirs();
+    expect(sessions.length).toBe(1);
+    expect(path.join(configDir(), '.uninstall-backup', sessions[0])).toContain('.uninstall-backup');
+  });
+});