@wipcomputer/wip-ldm-os 0.4.85-alpha.27 → 0.4.85-alpha.28

package/bin/ldm.js

@@ -20,7 +20,7 @@
  *   ldm --version         Show version
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, cpSync, chmodSync, unlinkSync, readlinkSync, renameSync, statSync, lstatSync, symlinkSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, cpSync, chmodSync, unlinkSync, readlinkSync, renameSync, statSync, lstatSync, symlinkSync, copyFileSync } from 'node:fs';
 import { join, basename, resolve, dirname } from 'node:path';
 import { execSync, spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -1799,6 +1799,97 @@ function migrateRegistry() {
   return migrated;
 }
 
+// ── Legacy source.npm honest cleanup (Phase 1 of source-types refactor) ──
+// See ai/product/bugs/installer/2026-05-13--cc-mini--installer-source-npm-honest-cleanup.md
+
+async function migrateLegacyNpmSources({ dryRun = false } = {}) {
+  const {
+    planLegacyNpmSourcesMigration,
+    summaryHasChanges,
+    npmPackageExists,
+  } = await import('../lib/registry-migrations.mjs');
+
+  const registry = readJSON(REGISTRY_PATH);
+  if (!registry?.extensions) return null;
+
+  const { newRegistry, summary } = await planLegacyNpmSourcesMigration({
+    registry,
+    probeNpm: (name) => npmPackageExists(name, { timeoutMs: 2000 }),
+    // Resolve the entry's on-disk location before declaring it a phantom.
+    // Entries autoregistered with `ldmPath` (bin/ldm.js:1822 path) or with
+    // a `paths.ldm` field (lib/deploy.mjs path) can live outside the
+    // default ~/.ldm/extensions/<name> location. A naive check would
+    // silently delete a working entry as "phantom."
+    extensionExists: (name, entry) => {
+      const customPath = entry?.paths?.ldm || entry?.ldmPath;
+      if (customPath && existsSync(customPath)) return true;
+      return existsSync(join(LDM_EXTENSIONS, name));
+    },
+    now: () => new Date(),
+  });
+
+  if (!summaryHasChanges(summary)) return summary;
+
+  if (!dryRun) {
+    const stamp = summary.timestamp.replace(/[:.]/g, '-');
+    const backupPath = `${REGISTRY_PATH}.bak-${stamp}`;
+    copyFileSync(REGISTRY_PATH, backupPath);
+    summary.backupPath = backupPath;
+    writeJSON(REGISTRY_PATH, newRegistry);
+  }
+
+  return summary;
+}
+
+function printLegacyNpmSourcesSummary(summary, { dryRun = false } = {}) {
+  if (!summary) return;
+  const writeableChanges =
+    summary.migrated.length +
+    summary.phantomsRemoved.length +
+    summary.duplicatesRemoved.length;
+  const probeFailureCount = summary.probeFailures?.length || 0;
+  // Always surface probe failures even when nothing was writeable. If every
+  // probe times out, the install would otherwise look like a no-op and the
+  // [unavailable] rows in `ldm status` would survive silently.
+  if (writeableChanges === 0 && probeFailureCount === 0) return;
+
+  console.log('');
+  console.log(dryRun
+    ? '  Registry source.npm cleanup (dry run, no changes written):'
+    : '  Registry source.npm cleanup:');
+
+  if (summary.migrated.length > 0) {
+    console.log(`  + ${dryRun ? 'Would migrate' : 'Migrated'} ${summary.migrated.length} entr${summary.migrated.length === 1 ? 'y' : 'ies'} to updateSource.type=untracked`);
+    for (const m of summary.migrated) {
+      const detail = m.legacyNpmName
+        ? ` (legacy source.npm "${m.legacyNpmName}" preserved in provenance)`
+        : ' (no source info; classified as untracked)';
+      console.log(`      ${m.name}${detail}`);
+    }
+  }
+  if (summary.phantomsRemoved.length > 0) {
+    console.log(`  + ${dryRun ? 'Would remove' : 'Removed'} ${summary.phantomsRemoved.length} phantom entr${summary.phantomsRemoved.length === 1 ? 'y' : 'ies'}:`);
+    for (const p of summary.phantomsRemoved) {
+      console.log(`      ${p.name} (${p.reason})`);
+    }
+  }
+  if (summary.duplicatesRemoved.length > 0) {
+    console.log(`  + ${dryRun ? 'Would remove' : 'Removed'} ${summary.duplicatesRemoved.length} duplicate entr${summary.duplicatesRemoved.length === 1 ? 'y' : 'ies'}:`);
+    for (const d of summary.duplicatesRemoved) {
+      console.log(`      ${d.removed} (canonical: ${d.keep})`);
+    }
+  }
+  if (summary.probeFailures && summary.probeFailures.length > 0) {
+    console.log(`  ! ${summary.probeFailures.length} npm probe${summary.probeFailures.length === 1 ? '' : 's'} could not complete (will retry on next install):`);
+    for (const f of summary.probeFailures) {
+      console.log(`      ${f.name} (source.npm "${f.npmName}")`);
+    }
+  }
+  if (!dryRun && summary.backupPath) {
+    console.log(`  + Registry backup: ${summary.backupPath.replace(HOME, '~')}`);
+  }
+}
+
 // ── Auto-detect unregistered extensions ──
 
 function autoDetectExtensions() {
@@ -1992,6 +2083,12 @@ async function cmdInstallCatalog() {
     console.log(`  + Migrated ${migrated} registry entries to v2 format (source info added)`);
   }
 
+  // Phase 1 of source-types refactor: clear bad source.npm entries, dedupe,
+  // and classify mystery rows as untracked so `ldm status` stops lying.
+  // See ai/product/bugs/installer/2026-05-13--cc-mini--installer-source-npm-honest-cleanup.md
+  const npmCleanupSummary = await migrateLegacyNpmSources({ dryRun: DRY_RUN });
+  printLegacyNpmSourcesSummary(npmCleanupSummary, { dryRun: DRY_RUN });
+
   // Aggregate the bin ownership manifest BEFORE seedLocalCatalog,
   // deployBridge, deployScripts, and the heal walk run. If two
   // declarers claim the same file in ~/.ldm/bin/ we cannot safely
@@ -2922,6 +3019,27 @@ async function cmdDoctor() {
     }
   }
 
+  // Warn on registry entries whose legacy source.npm value 404s on npm.
+  // `ldm install` migrates these to updateSource.type=untracked; this catches
+  // future drift and any entries the install-time probe couldn't reach.
+  // See ai/product/bugs/installer/2026-05-13--cc-mini--installer-source-npm-honest-cleanup.md
+  try {
+    const { findLegacyNpm404Entries, npmPackageExists } = await import('../lib/registry-migrations.mjs');
+    const docRegistry = readJSON(REGISTRY_PATH);
+    const legacy404 = await findLegacyNpm404Entries({
+      registry: docRegistry,
+      probeNpm: (name) => npmPackageExists(name, { timeoutMs: 1500 }),
+    });
+    if (legacy404.length > 0) {
+      console.log('');
+      console.log(`  ! ${legacy404.length} extension(s) declare an npm source whose package does not exist on npm:`);
+      for (const { name, npmName } of legacy404) {
+        console.log(`      ${name}  (source.npm "${npmName}")`);
+      }
+      console.log('      Run `ldm install` to migrate these to updateSource.type=untracked.');
+    }
+  } catch {}
+
   // --fix: clean up registered-missing entries
   if (FIX_FLAG && registeredMissing.length > 0) {
     const registry = readJSON(REGISTRY_PATH);
@@ -3409,7 +3527,24 @@ async function cmdStatus() {
   }];
 
   const updates = [];
+  const untrackedEntries = [];
   for (const [name, info] of Object.entries(registry?.extensions || {})) {
+    // Phase 1 of source-types refactor: entries explicitly marked as untracked
+    // are listed in a separate section and never probed. Honest reporting:
+    // we don't know how to check their source yet.
+    if (info?.updateSource?.type === 'untracked') {
+      const currentVersion = info?.installed?.version || info.version || 'unknown';
+      untrackedEntries.push({ name, version: currentVersion });
+      continue;
+    }
+    // Defensive skip for any other Phase 2 updateSource types (git, bundled,
+    // private, etc.) that may appear in the registry before their probe
+    // logic ships. Falling through would use the legacy info.source.npm
+    // path, which is wrong for these types and would print them as
+    // [unavailable]. Phase 2 replaces this skip with proper dispatch.
+    if (info?.updateSource && info.updateSource.type !== 'npm') {
+      continue;
+    }
     // Use registry source.npm (v2) or fall back to extension's package.json
     let npmPkg = info?.source?.npm || null;
     if (!npmPkg) {
@@ -3427,6 +3562,7 @@ async function cmdStatus() {
       current: currentVersion,
     });
   }
+  untrackedEntries.sort((a, b) => a.name.localeCompare(b.name));
 
   let cliUpdate = null;
   const probeResults = await runStatusProbesWithConcurrency(probeItems, STATUS_NPM_CONCURRENCY, statusStartedAt);
@@ -3455,12 +3591,13 @@ async function cmdStatus() {
   }
 
   console.log('');
-  if (updates.length === 0 && !cliUpdate && skipped.length === 0) {
+  if (updates.length === 0 && !cliUpdate && skipped.length === 0 && untrackedEntries.length === 0) {
     console.log('  Update summary: all up to date');
   } else {
     const summaryParts = [];
     if (updates.length > 0) summaryParts.push(`${updates.length} extension update(s) available`);
     if (cliUpdate) summaryParts.push('CLI update available');
+    if (untrackedEntries.length > 0) summaryParts.push(`${untrackedEntries.length} untracked`);
     if (skipped.length > 0) summaryParts.push(`${skipped.length} update check(s) skipped`);
     console.log(`  Update summary: ${summaryParts.join(', ')}`);
   }
@@ -3479,6 +3616,16 @@ async function cmdStatus() {
     console.log(`  CLI update: npm install -g @wipcomputer/wip-ldm-os@${cliUpdate}`);
   }
 
+  if (untrackedEntries.length > 0) {
+    console.log('');
+    console.log('  Untracked extensions (pending reclassification):');
+    const maxNameLen = Math.max(...untrackedEntries.map(e => e.name.length));
+    for (const e of untrackedEntries) {
+      console.log(`    ${e.name.padEnd(maxNameLen)}  v${e.version}`);
+    }
+    console.log('    (run `ldm doctor --reclassify-sources` to classify these)');
+  }
+
   if (skipped.length > 0) {
     console.log('');
     console.log('  Update checks skipped:');

package/lib/registry-migrations.mjs

@@ -0,0 +1,214 @@
+// Registry migrations for ~/.ldm/extensions/registry.json.
+//
+// Phase 1 of the source-types refactor. Pure planner + npm-probe helper.
+// Called by bin/ldm.js during `ldm install`. Idempotent: entries that already
+// carry `updateSource` are skipped.
+//
+// See ai/product/bugs/installer/2026-05-13--cc-mini--installer-source-npm-honest-cleanup.md
+// and the parent design ai/product/bugs/installer/2026-05-13--cc-mini--installer-registry-source-types-architecture.md
+
+const DEFAULT_NPM_REGISTRY = 'https://registry.npmjs.org';
+
+// Phase 1 expedient. The known duplicate pairs surfaced on Parker's machine
+// during the 2026-05-13 dogfood. General-case duplicate detection is the
+// hygiene-audit ticket's Check 1
+// (ai/product/bugs/installer/2026-05-13--cc-mini--installer-registry-hygiene-audit.md);
+// do NOT extend this list as a long-term shape. Future entries belong in
+// that audit, not here.
+//
+// Dedupe drops the duplicate's `installed` block entirely. Today both rows
+// in each pair carry the same version, so no data is lost. If a duplicate
+// ever carried a newer version than its canonical, the dedup would silently
+// discard that information. Acceptable for the known pairs; not a general
+// safe pattern.
+const KNOWN_DUPLICATE_PAIRS = [
+  { keep: 'cc-session-export', remove: 'session-export' },
+  { keep: 'wip-branch-guard',  remove: 'package' },
+];
+
+export function emptyLegacyNpmSourcesSummary() {
+  return {
+    migrated: [],
+    phantomsRemoved: [],
+    duplicatesRemoved: [],
+    probedCount: 0,
+    probeFailures: [],
+    timestamp: new Date().toISOString(),
+  };
+}
+
+export function summaryHasChanges(summary) {
+  return summary.migrated.length > 0
+    || summary.phantomsRemoved.length > 0
+    || summary.duplicatesRemoved.length > 0;
+}
+
+// Pure planner. Returns { newRegistry, summary } without touching the
+// filesystem. Tests pass an in-memory registry, a fake `probeNpm`, and a
+// fake `extensionExists`. Real callers inject the file-backed versions.
+//
+// probeNpm contract:
+//   returns true  if the package exists on npm
+//   returns false if the package returns 404 (definitely doesn't exist)
+//   returns null  if the probe failed (timeout / network) ... entry is left
+//                  alone and retried on the next install
+//
+// extensionExists contract:
+//   called as (name, entry) -> boolean
+//   The entry is provided so the resolver can honor `entry.paths.ldm` and
+//   the legacy `entry.ldmPath` field before falling back to the default
+//   ~/.ldm/extensions/<name> path. A naive resolver that only checks the
+//   default location would falsely classify custom-path entries as
+//   phantoms and remove them. Real callers must check both.
+export async function planLegacyNpmSourcesMigration({
+  registry,
+  probeNpm,
+  extensionExists,
+  now,
+}) {
+  const summary = emptyLegacyNpmSourcesSummary();
+  if (now) summary.timestamp = now().toISOString();
+  if (!registry?.extensions) return { newRegistry: registry, summary };
+
+  // Shallow-clone the top level and each entry so the input is not mutated.
+  const newRegistry = { ...registry, extensions: {} };
+  for (const [name, entry] of Object.entries(registry.extensions)) {
+    newRegistry.extensions[name] = { ...entry };
+  }
+
+  // Step 1: phantoms. Registry rows with no on-disk extension directory.
+  // The acceptance criterion says these are removed entirely; they're
+  // surfaced as an explicit summary delta, not silent.
+  //
+  // extensionExists is called with both name and entry so the resolver can
+  // honor entry.paths.ldm / entry.ldmPath. A custom-path entry must not be
+  // misclassified as phantom.
+  for (const [name, entry] of Object.entries(newRegistry.extensions)) {
+    if (entry.updateSource) continue;
+    if (extensionExists(name, entry)) continue;
+    summary.phantomsRemoved.push({
+      name,
+      reason: 'directory missing',
+      legacyNpmName: entry.source?.npm || null,
+    });
+    delete newRegistry.extensions[name];
+  }
+
+  // Step 2: dedupe known pairs. Pure structural fix; the canonical row stays
+  // untouched. Future drift is the hygiene-audit ticket's job, not this one.
+  for (const { keep, remove } of KNOWN_DUPLICATE_PAIRS) {
+    if (newRegistry.extensions[keep] && newRegistry.extensions[remove]) {
+      summary.duplicatesRemoved.push({ keep, removed: remove });
+      delete newRegistry.extensions[remove];
+    }
+  }
+
+  // Step 3: probe entries that still carry a legacy `source.npm` value.
+  // 404 -> migrate to untracked + provenance. 200 -> leave alone. Unknown ->
+  // leave alone; the next install will retry.
+  const probeTargets = [];
+  for (const [name, entry] of Object.entries(newRegistry.extensions)) {
+    if (entry.updateSource) continue;
+    const npmName = entry.source?.npm;
+    if (!npmName) continue;
+    probeTargets.push({ name, npmName });
+  }
+
+  const probeResults = await Promise.all(
+    probeTargets.map(async ({ name, npmName }) => {
+      const exists = await probeNpm(npmName);
+      summary.probedCount++;
+      return { name, npmName, exists };
+    })
+  );
+
+  for (const { name, npmName, exists } of probeResults) {
+    if (exists === true) continue;
+    if (exists === null) {
+      summary.probeFailures.push({ name, npmName });
+      continue;
+    }
+    const entry = newRegistry.extensions[name];
+    const legacyRepo = entry.source?.repo || null;
+    summary.migrated.push({ name, legacyNpmName: npmName, legacyRepo });
+    entry.updateSource = { type: 'untracked' };
+    entry.provenance = { ...(entry.provenance || {}) };
+    entry.provenance['legacy-npm-name'] = npmName;
+    if (legacyRepo) entry.provenance.repo = legacyRepo;
+    entry.provenance.untrackedSince = summary.timestamp;
+    delete entry.source;
+  }
+
+  // Step 4: entries with no source info at all (the mystery `run`-style row).
+  // Per the ticket, migrate to untracked so they stay visible in `ldm status`.
+  for (const [name, entry] of Object.entries(newRegistry.extensions)) {
+    if (entry.updateSource) continue;
+    if (entry.source?.npm || entry.source?.repo) continue;
+    summary.migrated.push({
+      name,
+      legacyNpmName: null,
+      legacyRepo: null,
+      reason: 'no-source-info',
+    });
+    entry.updateSource = { type: 'untracked' };
+    entry.provenance = { ...(entry.provenance || {}) };
+    entry.provenance.untrackedSince = summary.timestamp;
+    if ('source' in entry) delete entry.source;
+  }
+
+  return { newRegistry, summary };
+}
+
+// Real npm-registry probe. Returns true/false/null per the planner contract.
+// Mirrors the fetch pattern used by npmViewVersionForStatus in bin/ldm.js.
+export async function npmPackageExists(pkgName, opts = {}) {
+  const registryUrl = (opts.registryUrl || DEFAULT_NPM_REGISTRY).replace(/\/+$/, '');
+  const timeoutMs = Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : 2000;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const url = `${registryUrl}/${encodeURIComponent(pkgName)}`;
+    const response = await fetch(url, {
+      signal: controller.signal,
+      headers: { accept: 'application/vnd.npm.install-v1+json, application/json' },
+    });
+    if (response.status === 404) return false;
+    if (response.ok) return true;
+    return null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+// Doctor check: returns a list of registry entries that still carry a
+// `source.npm` value pointing at a package that returns 404. These are
+// candidates for migration on the next `ldm install`, but if the doctor
+// runs first (Parker checks status / doctor before running install) we
+// warn so it's not invisible.
+//
+// Returns: [{ name, npmName }] in lexical order.
+export async function findLegacyNpm404Entries({
+  registry,
+  probeNpm,
+}) {
+  if (!registry?.extensions) return [];
+  const targets = [];
+  for (const [name, entry] of Object.entries(registry.extensions)) {
+    if (entry.updateSource) continue;
+    const npmName = entry.source?.npm;
+    if (!npmName) continue;
+    targets.push({ name, npmName });
+  }
+  const results = await Promise.all(
+    targets.map(async ({ name, npmName }) => {
+      const exists = await probeNpm(npmName);
+      return { name, npmName, exists };
+    })
+  );
+  return results
+    .filter(r => r.exists === false)
+    .map(({ name, npmName }) => ({ name, npmName }))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wipcomputer/wip-ldm-os",
-  "version": "0.4.85-alpha.27",
+  "version": "0.4.85-alpha.28",
   "type": "module",
   "description": "LDM OS: identity, memory, and sovereignty infrastructure for AI agents",
   "engines": {
@@ -18,12 +18,13 @@
   "scripts": {
     "build:bridge": "cd src/bridge && npm install && npx tsup core.ts mcp-server.ts cli.ts openclaw.ts --format esm --dts --clean --outDir ../../dist/bridge",
     "build": "npm run build:bridge",
-    "prepublishOnly": "npm run build:bridge && npm run validate:bin-manifest && npm run test:install-prompt-policy && npm run test:ldm-status-timeout && npm run test:ldm-status-concurrency",
+    "prepublishOnly": "npm run build:bridge && npm run validate:bin-manifest && npm run test:install-prompt-policy && npm run test:ldm-status-timeout && npm run test:ldm-status-concurrency && npm run test:legacy-npm-sources-migration",
     "validate:bin-manifest": "node scripts/validate-bin-manifest.mjs",
     "test:skill-frontmatter": "node scripts/test-skill-frontmatter.mjs",
     "test:install-prompt-policy": "node scripts/test-install-prompt-policy.mjs",
     "test:ldm-status-timeout": "node scripts/test-ldm-status-timeout.mjs",
     "test:ldm-status-concurrency": "node scripts/test-ldm-status-concurrency.mjs",
+    "test:legacy-npm-sources-migration": "node scripts/test-legacy-npm-sources-migration.mjs",
     "test:installer-update-tracks": "node scripts/test-installer-update-tracks.mjs",
     "test:installer-hook-toolname": "node scripts/test-installer-hook-toolname.mjs",
     "test:installer-target-self-update": "node scripts/test-installer-target-self-update.mjs",

package/scripts/test-legacy-npm-sources-migration.mjs

@@ -0,0 +1,299 @@
+#!/usr/bin/env node
+// Fixture test for the Phase 1 source-types migration planner.
+// See lib/registry-migrations.mjs and
+// ai/product/bugs/installer/2026-05-13--cc-mini--installer-source-npm-honest-cleanup.md
+
+import {
+  planLegacyNpmSourcesMigration,
+  summaryHasChanges,
+  emptyLegacyNpmSourcesSummary,
+} from '../lib/registry-migrations.mjs';
+
+function fail(msg) {
+  throw new Error(msg);
+}
+
+function assertEqual(actual, expected, label) {
+  if (actual !== expected) {
+    fail(`${label}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+  }
+}
+
+function assertDeepEqual(actual, expected, label) {
+  const a = JSON.stringify(actual, Object.keys(actual || {}).sort());
+  const e = JSON.stringify(expected, Object.keys(expected || {}).sort());
+  if (a !== e) {
+    fail(`${label}: expected ${e}, got ${a}`);
+  }
+}
+
+// Mirrors the shape we see on Parker's machine in the 2026-05-13 dogfood.
+function buildFixtureRegistry() {
+  return {
+    _format: 'v2',
+    extensions: {
+      // 404 npm + on-disk: should migrate to untracked.
+      'cc-session-export': {
+        source: { type: 'github', npm: 'session-export', repo: 'wipcomputer/cc-session-export' },
+        installed: { version: '1.0.0' },
+      },
+      // Duplicate of cc-session-export: should be deduped (removed).
+      'session-export': {
+        source: { type: 'github', npm: 'session-export' },
+        installed: { version: '1.0.0' },
+      },
+      'compaction-indicator': {
+        source: { type: 'github', npm: 'compaction-indicator' },
+        installed: { version: '1.0.1' },
+      },
+      'lesa-bridge': {
+        source: { type: 'github', npm: 'lesa-bridge' },
+        installed: { version: '0.3.0' },
+      },
+      // Duplicate of wip-branch-guard: should be deduped.
+      'package': {
+        source: { type: 'github', npm: '@wipcomputer/wip-branch-guard' },
+        installed: { version: '1.0.0' },
+      },
+      'wip-branch-guard': {
+        source: { type: 'github', npm: '@wipcomputer/wip-branch-guard' },
+        installed: { version: '1.0.0' },
+      },
+      // Real npm package: should be left alone.
+      'memory-crystal': {
+        source: { type: 'github', npm: '@wipcomputer/memory-crystal' },
+        installed: { version: '2.0.0' },
+      },
+      // Phantom: no on-disk directory. Should be removed.
+      'tavily': {
+        source: { type: 'github', npm: '@wipcomputer/openclaw-tavily' },
+        installed: { version: '0.1.0' },
+      },
+      // Mystery row: no source info at all but on-disk. Should be classified
+      // untracked (Step 4 path in the planner).
+      //
+      // Note: on Parker's real machine the `run` entry has no on-disk
+      // directory, so it hits Step 1 (phantom removal) instead. We exercise
+      // the Step 4 path here via this fixture; Step 1 is covered by the
+      // `tavily` fixture below.
+      'run': {
+        installed: { version: 'unknown' },
+      },
+      // Already migrated: must be skipped (idempotency).
+      'already-untracked': {
+        updateSource: { type: 'untracked' },
+        provenance: { 'legacy-npm-name': 'already-untracked', untrackedSince: '2026-05-13T00:00:00.000Z' },
+        installed: { version: '0.1.0' },
+      },
+      // Probe will fail (timeout). Should be left alone, listed in probeFailures.
+      'flaky-network': {
+        source: { type: 'github', npm: 'flaky-network' },
+        installed: { version: '0.1.0' },
+      },
+      // Custom-path entry: declares `paths.ldm` pointing outside the default
+      // ~/.ldm/extensions/<name> location. The planner must NOT classify
+      // this as a phantom. Its source.npm is 404, so it should be migrated
+      // to untracked while the custom path is preserved.
+      'custom-path-untracked': {
+        source: { type: 'github', npm: 'custom-path-untracked' },
+        paths: { ldm: '/custom/location/path' },
+        installed: { version: '1.0.0' },
+      },
+      // Legacy custom-path field (`ldmPath` flat). Same expectation.
+      'legacy-custom-path': {
+        source: { type: 'github', npm: 'legacy-custom-path' },
+        ldmPath: '/legacy/custom/path',
+        installed: { version: '0.2.0' },
+      },
+    },
+  };
+}
+
+const NPM_404 = new Set([
+  'session-export',
+  'compaction-indicator',
+  'lesa-bridge',
+  'custom-path-untracked',
+  'legacy-custom-path',
+  // @wipcomputer/wip-branch-guard simulated as 200 (exists). But the dedupe
+  // happens first, so `package` is gone before the probe runs.
+  // The remaining `wip-branch-guard` will see exists=true and be left alone.
+]);
+const NPM_200 = new Set([
+  '@wipcomputer/memory-crystal',
+  '@wipcomputer/wip-branch-guard',
+]);
+const NPM_FAIL = new Set([
+  'flaky-network',
+]);
+
+function fakeProbeNpm(name) {
+  if (NPM_FAIL.has(name)) return Promise.resolve(null);
+  if (NPM_200.has(name)) return Promise.resolve(true);
+  if (NPM_404.has(name)) return Promise.resolve(false);
+  // Fail loudly when the planner probes an npm name the test forgot to
+  // enumerate. Future planner changes that call probeNpm with new names
+  // must explicitly declare expected behavior here; silent 404 defaults
+  // would swallow regressions.
+  fail(`fakeProbeNpm called with un-enumerated name "${name}"`);
+}
+
+// On-disk extension simulator. `tavily` is a phantom (no directory at any
+// location). All other names get a default directory unless they declare a
+// custom path, in which case we honor the custom path. The planner must
+// pass the entry to extensionExists for this to work.
+const PHANTOM_NAMES = new Set(['tavily']);
+const CUSTOM_PATH_EXISTS = new Set(['/custom/location/path', '/legacy/custom/path']);
+function fakeExtensionExists(name, entry) {
+  if (entry?.paths?.ldm) return CUSTOM_PATH_EXISTS.has(entry.paths.ldm);
+  if (entry?.ldmPath) return CUSTOM_PATH_EXISTS.has(entry.ldmPath);
+  return !PHANTOM_NAMES.has(name);
+}
+
+const FIXED_NOW = () => new Date('2026-05-13T18:00:00.000Z');
+
+// ── Test 1: full migration on fixture ──────────────────────────────────────
+{
+  const input = buildFixtureRegistry();
+  const inputSnapshot = JSON.stringify(input);
+
+  const { newRegistry, summary } = await planLegacyNpmSourcesMigration({
+    registry: input,
+    probeNpm: fakeProbeNpm,
+    extensionExists: fakeExtensionExists,
+    now: FIXED_NOW,
+  });
+
+  // Input must not be mutated.
+  assertEqual(JSON.stringify(input), inputSnapshot, 'input registry mutated');
+
+  // Phantoms removed.
+  assertEqual(summary.phantomsRemoved.length, 1, 'phantomsRemoved.length');
+  assertEqual(summary.phantomsRemoved[0].name, 'tavily', 'phantom name');
+  assertEqual(newRegistry.extensions.tavily, undefined, 'phantom still in registry');
+
+  // Duplicates removed.
+  assertEqual(summary.duplicatesRemoved.length, 2, 'duplicatesRemoved.length');
+  const removedDupes = summary.duplicatesRemoved.map(d => d.removed).sort();
+  assertDeepEqual(removedDupes, ['package', 'session-export'], 'dedupe targets');
+  assertEqual(newRegistry.extensions['session-export'], undefined, 'session-export still in registry');
+  assertEqual(newRegistry.extensions['package'], undefined, 'package still in registry');
+  if (!newRegistry.extensions['cc-session-export']) fail('canonical cc-session-export removed');
+  if (!newRegistry.extensions['wip-branch-guard']) fail('canonical wip-branch-guard removed');
+
+  // Migrated entries: cc-session-export, compaction-indicator, lesa-bridge,
+  // run, plus the two custom-path entries (custom-path-untracked,
+  // legacy-custom-path). `session-export` and `package` were deduped before
+  // probe. `wip-branch-guard` exists on npm. `flaky-network` probe failed.
+  const migratedNames = summary.migrated.map(m => m.name).sort();
+  assertDeepEqual(migratedNames, [
+    'cc-session-export', 'compaction-indicator', 'custom-path-untracked',
+    'legacy-custom-path', 'lesa-bridge', 'run',
+  ], 'migrated names');
+
+  // Custom-path entries must NOT be removed as phantoms. The planner must
+  // pass the entry to extensionExists so the custom path is honored.
+  // Regression guard for the round-3 Codex blocker (data-loss path on
+  // entries with entry.paths.ldm or entry.ldmPath).
+  const cpu = newRegistry.extensions['custom-path-untracked'];
+  if (!cpu) fail('custom-path-untracked was removed as phantom (extensionExists ignored entry.paths.ldm)');
+  assertEqual(cpu.updateSource?.type, 'untracked', 'custom-path-untracked.updateSource.type');
+  assertEqual(cpu.paths?.ldm, '/custom/location/path', 'custom-path-untracked.paths.ldm preserved');
+  const lcp = newRegistry.extensions['legacy-custom-path'];
+  if (!lcp) fail('legacy-custom-path was removed as phantom (extensionExists ignored entry.ldmPath)');
+  assertEqual(lcp.updateSource?.type, 'untracked', 'legacy-custom-path.updateSource.type');
+  assertEqual(lcp.ldmPath, '/legacy/custom/path', 'legacy-custom-path.ldmPath preserved');
+
+  // Each migrated entry has updateSource.type=untracked.
+  for (const name of migratedNames) {
+    const e = newRegistry.extensions[name];
+    if (!e) fail(`migrated entry ${name} missing from newRegistry`);
+    assertEqual(e.updateSource?.type, 'untracked', `${name}.updateSource.type`);
+    if ('source' in e) fail(`${name}.source should be deleted`);
+    if (!e.provenance) fail(`${name}.provenance missing`);
+    assertEqual(e.provenance.untrackedSince, '2026-05-13T18:00:00.000Z', `${name}.provenance.untrackedSince`);
+  }
+
+  // cc-session-export specifically: legacy-npm-name + repo preserved.
+  const ccse = newRegistry.extensions['cc-session-export'];
+  assertEqual(ccse.provenance['legacy-npm-name'], 'session-export', 'cc-session-export legacy-npm-name');
+  assertEqual(ccse.provenance.repo, 'wipcomputer/cc-session-export', 'cc-session-export legacy repo');
+
+  // `run` had no source info: legacy-npm-name absent, no repo, but still classified.
+  const runEntry = newRegistry.extensions.run;
+  if ('legacy-npm-name' in runEntry.provenance) fail('run.provenance should not have legacy-npm-name');
+  if ('repo' in runEntry.provenance) fail('run.provenance should not have repo');
+
+  // Real npm package left alone.
+  const mc = newRegistry.extensions['memory-crystal'];
+  if (mc.updateSource) fail('memory-crystal should not be migrated (real npm pkg)');
+  assertEqual(mc.source?.npm, '@wipcomputer/memory-crystal', 'memory-crystal source preserved');
+
+  // wip-branch-guard left alone (real npm pkg).
+  const wbg = newRegistry.extensions['wip-branch-guard'];
+  if (wbg.updateSource) fail('wip-branch-guard should not be migrated (real npm pkg)');
+
+  // Already-untracked entry is unchanged.
+  const au = newRegistry.extensions['already-untracked'];
+  assertEqual(au.provenance.untrackedSince, '2026-05-13T00:00:00.000Z', 'already-untracked untracked since preserved');
+
+  // Probe failures recorded, entry untouched.
+  assertEqual(summary.probeFailures.length, 1, 'probeFailures.length');
+  assertEqual(summary.probeFailures[0].name, 'flaky-network', 'probe failure name');
+  const fn = newRegistry.extensions['flaky-network'];
+  if (fn.updateSource) fail('flaky-network should not be migrated (probe failed)');
+  assertEqual(fn.source?.npm, 'flaky-network', 'flaky-network source preserved');
+
+  // summaryHasChanges flips true when anything happens.
+  assertEqual(summaryHasChanges(summary), true, 'summaryHasChanges on populated summary');
+}
+
+// ── Test 2: idempotency on a fully-migrated registry ───────────────────────
+{
+  const registry = {
+    extensions: {
+      'a': {
+        updateSource: { type: 'untracked' },
+        provenance: { untrackedSince: '2026-05-13T00:00:00.000Z' },
+        installed: { version: '1.0.0' },
+      },
+      'b': {
+        updateSource: { type: 'untracked' },
+        provenance: { 'legacy-npm-name': 'b', untrackedSince: '2026-05-13T00:00:00.000Z' },
+        installed: { version: '0.1.0' },
+      },
+    },
+  };
+  const before = JSON.stringify(registry);
+  const { newRegistry, summary } = await planLegacyNpmSourcesMigration({
+    registry,
+    probeNpm: () => fail('probeNpm should not be called on fully-migrated registry'),
+    extensionExists: () => true,
+    now: FIXED_NOW,
+  });
+  assertEqual(JSON.stringify(registry), before, 'input mutated on idempotent run');
+  assertEqual(summary.migrated.length, 0, 'migrated.length on idempotent run');
+  assertEqual(summary.phantomsRemoved.length, 0, 'phantomsRemoved.length on idempotent run');
+  assertEqual(summary.duplicatesRemoved.length, 0, 'duplicatesRemoved.length on idempotent run');
+  assertEqual(summaryHasChanges(summary), false, 'summaryHasChanges on empty summary');
+  assertDeepEqual(
+    Object.keys(newRegistry.extensions).sort(),
+    ['a', 'b'],
+    'extensions preserved on idempotent run',
+  );
+}
+
+// ── Test 3: emptyLegacyNpmSourcesSummary returns the canonical shape ───────
+{
+  const e = emptyLegacyNpmSourcesSummary();
+  assertDeepEqual(Object.keys(e).sort(), [
+    'duplicatesRemoved',
+    'migrated',
+    'phantomsRemoved',
+    'probeFailures',
+    'probedCount',
+    'timestamp',
+  ], 'empty summary keys');
+}
+
+console.log('test-legacy-npm-sources-migration: all tests passed');