@boyingliu01/xp-gate 0.35.23 → 0.36.0

package/lib/install-skill.js

@@ -1,6 +1,6 @@
 const fs = require('fs');
 const path = require('path');
-const { checkDeps } = require('./detect-deps.js');
+const { checkDeps, detectInstalledPlatforms, getSkillsDirs } = require('./detect-deps.js');
 const { rollback } = require('./rollback.js');
 const { HOME_DIR, CONFIG_DIR, detectPlatform } = require('./shared-paths.js');
 const { copyDirRecursive } = require('./shared-utils');
@@ -16,15 +16,53 @@ function getSkillsDir() {
   return path.join(HOME_DIR, '.config', 'opencode', 'skills');
 }
 
+/**
+ * Every skills directory that belongs to an installed platform.
+ *
+ * #725 fixed the single-platform assumption, but the enumeration still hardcoded
+ * the three pre-dsh platforms (`.qoder`, `.config/opencode`, `.claude`) and so
+ * missed `~/.dsh/skills` -- the DSH platform `detectPlatform()` never returns and
+ * `PLATFORM_PROFILES` does carry. Derive the target set from the profiles instead
+ * of a parallel list: a machine with Qoder, OpenCode and DSH all present must
+ * have all three updated, and a migration period (two tools live) must not leave
+ * one silently frozen.
+ *
+ * A machine with no agent installed yet still needs one target, so fall back to
+ * the platform `detectPlatform()` selects and keep plain `install-skill` working.
+ *
+ * @returns {string[]} home-relative skills directories, de-duplicated
+ */
+function deployedSkillsDirs() {
+  const installed = detectInstalledPlatforms();
+  if (installed.length === 0) return [getSkillsDir()];
+  const dirs = installed.map((platform) => getSkillsDirs(platform)[0]);
+  return [...new Set(dirs)];
+}
+
 // The npm package ships the canonical skill content; `files` includes skills/.
 const BUNDLED_SKILLS_DIR = path.join(__dirname, '..', 'skills');
 
+/**
+ * The version of the CLI that is actually running.
+ *
+ * This used to read `../../../VERSION` relative to __dirname. Two things were
+ * wrong with that (#713): three levels up from `node_modules/@boyingliu01/
+ * xp-gate/lib` is `node_modules/`, and the package does not ship VERSION at all
+ * (`files` omits it). The catch therefore returned `0.0.0` on every installed
+ * machine, so `xp-gate 0.0.0 bundles: ...` -- printed as help when an unknown
+ * skill is requested -- read as a corrupt installation rather than as a typo.
+ *
+ * package.json travels with the package by definition, so it is the only source
+ * that is always present and always current.
+ *
+ * @returns {string} the package version, or 'unknown' if it cannot be read
+ */
 function getCliVersion() {
   try {
-    const versionFile = path.join(__dirname, '..', '..', '..', 'VERSION');
-    return fs.readFileSync(versionFile, 'utf8').trim();
+    const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+    return typeof pkg.version === 'string' && pkg.version ? pkg.version : 'unknown';
   } catch {
-    return '0.0.0';
+    return 'unknown';
   }
 }
 
@@ -72,26 +110,52 @@ async function installSkill(name, options = {}) {
     return 1;
   }
 
-  const targetDir = path.join(getSkillsDir(), name);
-  const dupError = checkDuplicateInstall(targetDir, force);
-  if (dupError) {
-    console.error(dupError);
-    return 1;
-  }
+  // #725: update EVERY platform that already carries this skill, not just the
+  // one `detectPlatform()` picks. A machine with both Qoder and OpenCode used to
+  // get one silently-frozen copy. Each target is installed independently so a
+  // failure on one platform does not abort the others -- a half-updated machine
+  // that reports success is exactly the bug being fixed.
+  //
+  // deployedSkillsDirs() already falls back to the detected platform when nothing
+  // is deployed anywhere, so it never returns an empty list.
+  const finalTargets = deployedSkillsDirs().map((dir) => path.join(dir, name));
+
+  // `lastError` alone was wrong: an unreadable platform (e.g. ~/.qoder/skills is
+  // a file, so readdir throws ENOTDIR) set it to 1 and nothing reset it when the
+  // other platform installed fine -- the CLI then reported failure for a machine
+  // that had in fact been updated. Track successes instead: the command failed
+  // only when EVERY target failed.
+  let succeeded = 0;
+  let lastError = 0;
+  for (const targetDir of finalTargets) {
+    const dupError = checkDuplicateInstall(targetDir, force);
+    if (dupError) {
+      console.error(dupError);
+      lastError = 1;
+      continue;
+    }
 
-  const installId = `${name}-${Date.now()}`;
-  const backupDir = path.join(CONFIG_DIR, 'backup', installId);
-  backupExisting(targetDir, installId, backupDir);
+    // The platform segment keeps concurrent per-platform backups distinct; a bare
+    // `Date.now()` collided when both platforms were written in the same tick.
+    const platformTag = path.basename(path.dirname(targetDir));
+    const installId = `${name}-${Date.now()}-${platformTag}`;
+    const backupDir = path.join(CONFIG_DIR, 'backup', installId);
+    backupExisting(targetDir, installId, backupDir);
 
-  try {
-    const result = await performInstall(name, targetDir, verbose);
-    if (result !== 0) return result;
-    return 0;
-  } catch (err) {
-    console.error(`Error: Install failed - ${err.message}`);
-    await rollback(installId);
-    return 1;
+    try {
+      if (verbose && finalTargets.length > 1) console.log(`Target: ${targetDir}`);
+      const result = await performInstall(name, targetDir, verbose);
+      if (result !== 0) lastError = result;
+      else succeeded += 1;
+    } catch (err) {
+      console.error(`Error: Install failed - ${err.message}`);
+      await rollback(installId);
+      lastError = 1;
+    }
   }
+
+  if (succeeded > 0) return 0;
+  return lastError || 1;
 }
 
 function checkDuplicateInstall(targetDir, force) {

package/lib/mattpocock-license-verdict.json

@@ -2,6 +2,6 @@
   "verdict": "PASS",
   "license_type": "MIT",
   "sha256": "0e7ac423bf2c6e223b7c5b156f8cf72da49d748e56a1641402c31f22ad07dbb5",
-  "checked_at": "2026-11-02T15:52:57.140Z",
+  "checked_at": "2026-11-05T12:23:08.769Z",
   "source": "network"
 }

package/lib/uninstall.js

@@ -27,15 +27,24 @@ function globalSkillRoots() {
 }
 
 /**
- * Directories inside ~/.config/xp-gate/ that `setup-global` creates and that
- * `uninstall` used to leave behind (#663).
+ * Directories and files inside ~/.config/xp-gate/ that `setup-global` creates
+ * and that `uninstall` used to leave behind (#663).
+ *
+ * `ownedByPath: true` marks entries the installer writes at a FIXED path under
+ * our own config directory -- there is no other way they got there, so a content
+ * signature is the wrong test for them (#714). It matters most for
+ * `package.json`: its body is nothing but dependency pins (`js-yaml`, `zod`), so
+ * no signature string can ever match it, and demanding one meant the file was
+ * scheduled for deletion and then skipped at delete time. `xp-gate.json` is
+ * equally ours -- the uninstaller itself writes `mode: "uninstalled"` into it
+ * moments earlier -- and was likewise reported as foreign.
  */
 const GLOBAL_INSTALL_RESIDUE = [
-  { key: 'modules', label: 'modules/' },
-  { key: 'node_modules', label: 'node_modules/' },
-  { key: 'package.json', label: 'package.json' },
-  { key: 'package-lock.json', label: 'package-lock.json' },
-  { key: 'xp-gate.json', label: 'xp-gate.json' },
+  { key: 'modules', label: 'modules/', ownedByPath: true },
+  { key: 'node_modules', label: 'node_modules/', ownedByPath: true },
+  { key: 'package.json', label: 'package.json', ownedByPath: true },
+  { key: 'package-lock.json', label: 'package-lock.json', ownedByPath: true },
+  { key: 'xp-gate.json', label: 'xp-gate.json', ownedByPath: true },
 ];
 
 /** User DATA that must survive an uninstall, and must be reported as retained. */
@@ -43,6 +52,27 @@ const GLOBAL_USER_DATA = [
   { key: '.delphi-config.json', label: '.delphi-config.json (your Delphi expert config)' },
 ];
 
+/**
+ * Directories under the config dir that the uninstall snapshot must NOT copy.
+ *
+ * #724: `createBackupSnapshot()` copied every plan entry, so an uninstall wrote a
+ * full second copy of `node_modules/` (~1000 files, ~12 MB) into
+ * `.uninstall-backup/`. That is the one thing here with no rollback value: it is
+ * a dependency tree npm regenerates from `package.json` in seconds, and it was
+ * the difference between a snapshot of a few config files and a 12 MB directory.
+ */
+const UNBACKUPABLE_DIRS = new Set(['node_modules', 'modules']);
+
+/**
+ * How many uninstall snapshots to keep.
+ *
+ * #724: the snapshot directory is named `uninstall-<timestamp>` and nothing ever
+ * pruned it, so every uninstall added another full copy and the directory only
+ * grew. Keeping the most recent few preserves the "I uninstalled by accident"
+ * recovery path without letting the directory become unbounded.
+ */
+const BACKUP_RETENTION = 3;
+
 /**
  * Signature strings used to verify file ownership.
  * Each hook/adapter file contains a unique marker string.
@@ -140,6 +170,11 @@ function unsetHooksPath() {
 
 /**
  * Create a backup snapshot of files/dirs before deletion.
+ *
+ * #724: two scoping rules keep this proportionate. `node_modules/` and
+ * `modules/` are skipped outright -- they are regenerable from package.json, and
+ * copying them made the snapshot ~1000 files / 12 MB. Everything else is copied
+ * as before, so the recovery path for real config is unchanged.
  */
 function createBackupSnapshot(plan) {
   // Use a unique backup dir for this uninstall session
@@ -150,6 +185,9 @@ function createBackupSnapshot(plan) {
 
   for (const item of plan) {
     if (!item.path || !fs.existsSync(item.path)) continue;
+    // Retained user data is not being deleted, so there is nothing to roll back.
+    if (item.retain === true) continue;
+    if (UNBACKUPABLE_DIRS.has(path.basename(item.path))) continue;
 
     const relPath = path.basename(item.path);
     const destPath = path.join(sessionBackup, relPath);
@@ -167,9 +205,49 @@ function createBackupSnapshot(plan) {
     }
   }
 
+  pruneOldBackups(sessionBackup);
+
   return backupMeta;
 }
 
+/**
+ * Keep only the newest BACKUP_RETENTION uninstall snapshots (#724).
+ *
+ * Snapshots are named `uninstall-<epoch-ms>`, so a plain reverse-sort of the
+ * directory names is a correct newest-first order without reading any metadata.
+ * An empty snapshot (every entry was skipped) is removed rather than counted
+ * toward the retention budget -- otherwise a run that backed up nothing would
+ * evict a snapshot that actually held config.
+ */
+function pruneOldBackups(sessionBackup) {
+  try {
+    if (isDirEmpty(sessionBackup)) {
+      fs.rmdirSync(sessionBackup);
+      return;
+    }
+    const sessions = fs
+      .readdirSync(BACKUP_DIR, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && e.name.startsWith('uninstall-'))
+      .map((e) => e.name)
+      .sort()
+      .reverse();
+    for (const stale of sessions.slice(BACKUP_RETENTION)) {
+      fs.rmSync(path.join(BACKUP_DIR, stale), { recursive: true, force: true });
+    }
+  } catch {
+    // Pruning is housekeeping. Failing it must never fail the uninstall, which
+    // has already done the work the user asked for.
+  }
+}
+
+function isDirEmpty(dir) {
+  try {
+    return fs.readdirSync(dir).length === 0;
+  } catch {
+    return false;
+  }
+}
+
 function copyDirSync(src, dest) {
   fs.mkdirSync(dest, { recursive: true });
   const entries = fs.readdirSync(src, { withFileTypes: true });
@@ -325,7 +403,12 @@ function buildPlan(mode) {
           type: isDir ? 'dir' : 'file',
           path: target,
           label: `~/.config/xp-gate/${item.label}`,
-          critical: false
+          critical: false,
+          // #714: a fixed-path file we install ourselves needs no content
+          // signature. Carrying the flag through the plan is what makes the
+          // delete actually happen instead of stopping at "does not contain
+          // xp-gate signature".
+          ownedByPath: item.ownedByPath === true
         });
       }
     }
@@ -365,6 +448,20 @@ function buildPlan(mode) {
  * @returns {boolean} true on success, false on skip (not xp-gate owned)
  */
 function removeFile(item, config) {
+  // #714: `ownedByPath` entries are files the installer writes at a fixed path
+  // inside our own ~/.config/xp-gate/ directory, so ownership is established by
+  // the path itself. Without this branch the residue files fell through to
+  // verifyFileOwnership() with neither a manifest entry nor a signature, and
+  // isXpGateFile() evaluated `content.includes(undefined)` -- always false. The
+  // file was listed in the plan, "uninstall complete" was printed, and the file
+  // stayed.
+  if (item.ownedByPath === true) {
+    if (!fs.existsSync(item.path)) return false;
+    fs.unlinkSync(item.path);
+    console.log(`  Removed ${item.label}`);
+    return true;
+  }
+
   const manifestEntry = config.manifest && config.manifest.files
     ? config.manifest.files[item.manifestKey]
     : null;
@@ -533,11 +630,27 @@ async function uninstall(args) {
   // §4.3 Step 4: Print plan
   console.log(`XP-Gate Uninstall (${mode} mode)`);
   console.log('=======================\n');
-  console.log('The following will be removed:\n');
 
-  for (const item of plan) {
+  // #724: 'retain' entries used to be printed under "The following will be
+  // removed" and then kept, with no further mention anywhere in the output.
+  // A user scripting cleanup from this preview would delete a directory they
+  // had been told was gone. The two groups are now stated separately, and the
+  // retained list is echoed again at the end.
+  const removable = plan.filter((item) => item.retain !== true);
+  const retained = plan.filter((item) => item.retain === true);
+
+  console.log('The following will be removed:\n');
+  for (const item of removable) {
     console.log(`  • ${item.label}`);
   }
+
+  if (retained.length > 0) {
+    console.log('\nThe following will be KEPT (your data):\n');
+    for (const item of retained) {
+      console.log(`  • ${item.label}`);
+    }
+  }
+
   if (options.purge) {
     console.log('\nPurge mode — additional cleanup:');
     for (const d of purgeDirs) {
@@ -614,6 +727,15 @@ async function uninstall(args) {
   console.log('Note: Qoder Delphi expert agents (.qoder/agents/delphi-*.md) are user-owned files');
   console.log('      that init never overwrites, so they were left in place — delete them by hand');
   console.log('      (then restart the Qoder session) if you want them gone.');
+  // #724: restate the retained data. The preview said it once, but the last thing
+  // a user reads before closing the terminal is the summary -- and an uninstall
+  // that leaves files behind owes them an explicit accounting of what it kept.
+  for (const item of retained) {
+    console.log(`Kept: ${item.label}`);
+  }
+  if (backupMeta && backupMeta.entries.length > 0) {
+    console.log(`Rollback snapshot: ${backupMeta.sessionBackup}`);
+  }
   if (hadErrors) {
     console.log('Some items could not be removed. Run doctor for diagnostics.');
   }
@@ -740,8 +862,17 @@ function planHooksDirRemoval(hooksDir) {
     : { action: 'remove-all', foreign: [], owned };
 }
 
-/** Hook entry points xp-gate installs. */
-const OWNED_HOOK_NAMES = ['pre-commit', 'pre-push', 'post-merge'];
+/**
+ * Hook entry points xp-gate installs.
+ *
+ * This must stay in sync with `copyHooks()`'s `hookFiles` list, which is what
+ * actually puts them on disk. `post-commit` was missing here (#714), so the
+ * uninstaller classified its own hook as a third party's and kept it -- the
+ * file contains nine `xp-gate` references and is installed unconditionally by
+ * setup-global. The set is derived from the installer's list rather than
+ * retyped, so the two cannot drift apart again.
+ */
+const OWNED_HOOK_NAMES = ['pre-commit', 'pre-push', 'post-merge', 'post-commit'];
 
 /** 'git-lfs' when the file proves it, else null. Content-based: see doctor.js. */
 function foreignHookSource(filePath) {

package/lib/update-skill.js

@@ -7,6 +7,32 @@ const HOME = process.env.HOME || process.env.USERPROFILE || os.homedir();
 
 const CONFIG_DIR = path.join(HOME, '.config', 'xp-gate');
 
+/**
+ * The skill names this package ships.
+ *
+ * `skills/` is the bundle contract: a skill the installed package does not carry
+ * is not ours to touch. Resolved lazily so a caller that stubs out the package
+ * layout still gets a sensible empty set instead of a throw at require() time.
+ *
+ * @returns {Set<string>} bundled skill directory names
+ */
+function bundledSkillNames() {
+  const dir = path.join(__dirname, '..', 'skills');
+  try {
+    return new Set(
+      fs
+        .readdirSync(dir, { withFileTypes: true })
+        .filter(
+          (entry) =>
+            entry.isDirectory() && fs.existsSync(path.join(dir, entry.name, 'SKILL.md'))
+        )
+        .map((entry) => entry.name)
+    );
+  } catch {
+    return new Set();
+  }
+}
+
 /**
  * The skill names that are actually deployed on this machine.
  *
@@ -16,59 +42,244 @@ const CONFIG_DIR = path.join(HOME, '.config', 'xp-gate');
  * "Updating all skills..." and exit 0 having touched nothing (#682) -- the
  * same defect #635 fixed for `doctor`, with the same fix: ask the filesystem.
  *
+ * Enumerating the filesystem alone is too wide, though (#713). A skill
+ * directory is a shared namespace -- every skill tool uses the same
+ * `<dir>/<name>/SKILL.md` layout -- so on a machine that also carries other
+ * bundles, `--all` walked all of them, printed `Error: Unknown skill: <name>`
+ * for each, and advised `npm install -g xp-gate@latest` to obtain a skill this
+ * package does not and will never ship. Scanned names are therefore filtered
+ * against the bundle: the candidate set is the intersection, not the union.
+ *
  * The explicit registry is still unioned in, so a skill that is merely
  * registered (or was installed on a platform this scan cannot see) keeps
- * working for callers that rely on it.
+ * working for callers that rely on it -- but only when the package really
+ * carries it, for the same reason as above.
  *
  * @returns {string[]} de-duplicated skill names, in a stable order
  */
 function installedSkillNames() {
+  const bundled = bundledSkillNames();
   const names = new Set();
-  const config = getConfig();
-  for (const name of Object.keys(config.installedSkills || {})) names.add(name);
 
-  let platforms = [];
+  // Registry first: a skill can be registered on a platform this scan cannot see.
+  for (const name of Object.keys(getConfig().installedSkills || {})) {
+    if (bundled.has(name)) names.add(name);
+  }
+
+  for (const name of bundledNamesOnDisk(bundled)) names.add(name);
+  return [...names].sort();
+}
+
+/**
+ * Bundled skill names that are actually deployed on this machine.
+ *
+ * Split out of installedSkillNames() because the per-platform probing is three
+ * nested try/catch levels deep on its own: reading a directory that may not
+ * exist, on a platform whose detection may itself throw. Flattening it into a
+ * named loop keeps each failure mode visible instead of piling onto one
+ * function's complexity budget.
+ *
+ * Every unreadable location is skipped silently -- an absent platform is the
+ * normal case on any given machine, not an error worth reporting mid-update.
+ *
+ * @param {Set<string>} bundled names the package ships; anything else is not ours
+ * @returns {string[]} deployed-and-bundled skill names
+ */
+function bundledNamesOnDisk(bundled) {
+  const found = [];
+  let detect;
+  let platforms;
   try {
-    platforms = Object.keys(require('./detect-deps.js').PLATFORM_PROFILES);
+    detect = require('./detect-deps.js');
+    platforms = Object.keys(detect.PLATFORM_PROFILES);
   } catch {
-    // detect-deps unavailable: fall back to the registry only rather than
-    // reporting "nothing installed" for a machine that has skills on disk.
-    platforms = [];
+    // detect-deps unavailable: the registry half of installedSkillNames() still
+    // applies, so returning nothing here does not report "no skills installed".
+    return found;
   }
-  const detect = require('./detect-deps.js');
+
   for (const platform of platforms) {
-    let dir;
-    try {
-      dir = detect.getSkillsDirs(platform)[0];
-    } catch {
-      continue;
-    }
-    let entries;
-    try {
-      entries = fs.readdirSync(dir, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-    for (const entry of entries) {
-      if (!entry.isDirectory()) continue;
-      // A skill is `<dir>/<name>/SKILL.md` — the shape install-skill writes.
-      if (fs.existsSync(path.join(dir, entry.name, 'SKILL.md'))) names.add(entry.name);
+    for (const entry of readSkillsDirEntries(detect, platform)) {
+      if (!entry.isDirectory || !bundled.has(entry.name)) continue;
+      if (fs.existsSync(path.join(entry.dir, entry.name, 'SKILL.md'))) found.push(entry.name);
     }
   }
-  return [...names].sort();
+  return found;
+}
+
+/**
+ * Read one platform's skills directory as plain records, so callers get the
+ * directory back without depending on dirent internals.
+ * @returns {Array<{name: string, isDirectory: boolean, dir: string}>} empty when unreadable
+ */
+function readSkillsDirEntries(detect, platform) {
+  let dir;
+  try {
+    dir = detect.getSkillsDirs(platform)[0];
+  } catch {
+    return [];
+  }
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries.map((entry) => ({ name: entry.name, isDirectory: entry.isDirectory(), dir }));
+}
+
+/**
+ * The version of the CLI that is running, for comparing against what is on disk.
+ *
+ * Same source as install-skill.js reads (#713): the installed package.json, not
+ * the repo-root VERSION file, which the published tarball does not ship.
+ *
+ * @returns {string} semver, or 'unknown' when the package metadata is unreadable
+ */
+function getCliVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+    return typeof pkg.version === 'string' && pkg.version ? pkg.version : 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Compare a 4-part release stamp against a 3-part npm semver.
+ *
+ * A trailing `.0` is the only difference between the two schemes, so trimming it
+ * is enough -- this is deliberately not a full semver comparison, which would
+ * imply support for pre-release ordering that neither source produces.
+ *
+ * The trailing segment is dropped, not "every trailing zero": a naive
+ * `.replace(/.0+$/, '')` also ate the dot of the segment before it, so
+ * `0.36.0.0` normalized to `0.36.0` while `0.36.0` normalized to `0.36` and a
+ * current copy was reported as behind. That stayed hidden while releases ended
+ * in a non-zero micro digit (`0.35.24.0` vs `0.35.24` agree either way) and
+ * broke the first time the micro digit was 0.
+ *
+ * @returns {boolean} true when both name the same release
+ */
+function sameVersion(a, b) {
+  // A 4-part stamp whose micro digit is 0 names the same release as its 3-part
+  // form; anything else is compared as-is so a real difference is never hidden.
+  const norm = (v) => {
+    const parts = String(v).split('.');
+    return parts.length === 4 && parts[3] === '0' ? parts.slice(0, 3).join('.') : String(v);
+  };
+  return norm(a) === norm(b);
+}
+
+/**
+ * Whether a deployed copy is byte-identical to the bundle this CLI ships.
+ *
+ * Most skills carry no AGENTS.md, so their only version marker is `unknown`. That
+ * is not evidence of staleness -- treating it as such flagged every skill on a
+ * healthy machine. Content comparison answers the question the version stamp was
+ * standing in for, and answers it for those skills too.
+ *
+ * Only SKILL.md is compared: it is the file every skill has, and it is the one
+ * `update-skill` rewrites. Anything else a user added locally must not make their
+ * copy look outdated.
+ *
+ * @param {string} skillName
+ * @param {{dir: string}} entry a deployed copy
+ * @returns {boolean} true when the copy already matches the bundle
+ */
+function copyMatchesBundle(skillName, entry) {
+  const bundled = path.join(__dirname, '..', 'skills', skillName, 'SKILL.md');
+  const installed = path.join(entry.dir, 'SKILL.md');
+  try {
+    return fs.readFileSync(installed, 'utf8') === fs.readFileSync(bundled, 'utf8');
+  } catch {
+    // Unreadable either way: fall back to the version stamp's verdict rather than
+    // asserting a match we could not verify.
+    return false;
+  }
 }
 
 function handleCheckMode() {
   console.log('Checking for updates...');
   const config = getConfig();
   const skills = config.installedSkills || {};
+
+  // #725: this used to print config.installedSkills[name].version and call it a
+  // day. That value is what the last install WROTE DOWN, not what is on disk, so
+  // a copy left behind by a single-platform update reported the new version while
+  // its files still said the old one. Reporting the registry as if it were the
+  // installation is how a stale skill looked healthy.
+  const bundledVersion = getCliVersion();
+  let stale = 0;
+
   for (const [skillName, info] of Object.entries(skills)) {
-    console.log(`  ${skillName}: ${info.version || 'unknown'}`);
+    const registry = info.version || 'unknown';
+    const onDisk = deployedSkillVersions(skillName);
+    if (onDisk.length === 0) {
+      console.log(`  ${skillName}: ${registry} (registry only - no copy found on disk)`);
+      continue;
+    }
+    // AGENTS.md stamps the 4-part release version (0.35.24.0) while package.json
+    // carries the 3-part npm semver (0.35.24). Comparing them raw marked every
+    // copy on a healthy machine as behind -- a false alarm is as useless as no
+    // check at all, so normalize before comparing.
+    // A copy is behind when its version stamp says so. Only a copy with NO stamp
+    // falls back to content comparison -- a known-old stamp must not be excused by
+    // an identical SKILL.md, which is exactly the delphi-review case: the two
+    // platform copies differ only in the generated AGENTS.md header.
+    const behind = onDisk.filter((entry) => (entry.version === 'unknown'
+      ? !copyMatchesBundle(skillName, entry)
+      : !sameVersion(entry.version, bundledVersion)));
+    if (behind.length > 0) {
+      stale += behind.length;
+      for (const entry of behind) {
+        console.log(`  ${skillName} [${entry.platform}]: ${entry.version} -> ${bundledVersion} available`);
+      }
+    } else {
+      console.log(`  ${skillName}: ${bundledVersion} (up to date on ${onDisk.length} platform(s))`);
+    }
   }
-  console.log('Update check complete');
+
+  console.log(stale > 0 ? `Update check complete — ${stale} copy(ies) behind.` : 'Update check complete');
   return 0;
 }
 
+/**
+ * Versions actually written into each platform's copy of \`skillName\`.
+ *
+ * Reads the \`**Version:**\` stamp from the generated AGENTS.md, which is the only
+ * per-copy version marker an installed skill carries. A copy without one (older
+ * layouts, or a hand-written skill) reports \`unknown\` rather than being skipped --
+ * silently omitting it would hide exactly the stale copy this check exists for.
+ *
+ * @param {string} skillName
+ * @returns {Array<{platform: string, version: string, dir: string}>} one entry per deployed copy
+ */
+function deployedSkillVersions(skillName) {
+  let detect;
+  try {
+    detect = require('./detect-deps.js');
+  } catch {
+    return [];
+  }
+  const found = [];
+  for (const platform of Object.keys(detect.PLATFORM_PROFILES)) {
+    for (const entry of readSkillsDirEntries(detect, platform)) {
+      if (!entry.isDirectory || entry.name !== skillName) continue;
+      const agentsFile = path.join(entry.dir, entry.name, 'AGENTS.md');
+      let version = 'unknown';
+      try {
+        const match = fs.readFileSync(agentsFile, 'utf8').match(/^\*\*Version:\*\*\s*(\S+)/m);
+        if (match) version = match[1];
+      } catch {
+        // No AGENTS.md: still count the copy, with an unknown stamp.
+      }
+      found.push({ platform, version, dir: path.join(entry.dir, entry.name) });
+    }
+  }
+  return found;
+}
+
 async function handleAllMode(verbose) {
   const names = installedSkillNames();
   console.log('Updating all skills...');