@danypops/pi-packed 0.25.1 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/pi-packed",
-  "version": "0.25.1",
+  "version": "0.26.0",
   "description": "Pi package lifecycle, validation, daemon, tools, profiles, and TUI",
   "type": "module",
   "bin": {
@@ -27,7 +27,7 @@
     "typecheck": "bunx tsc --noEmit"
   },
   "dependencies": {
-    "@danypops/armada": "^0.4.6",
+    "@danypops/armada": "^0.4.8",
     "@danypops/packed": "^0.7.0",
     "@danypops/pi-extension-harness": "^0.7.0",
     "@danypops/vehicle-client": "^0.8.1",

package/service/src/adoption/doctor.ts

@@ -10,6 +10,7 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { createNodeServiceInstallDeps } from "@danypops/vehicle-server/service";
 import { listPackageResources, type PackageResources, resolveInstalledDir } from "../packages/resources.ts";
+import { type DuplicateDependencyDiagnostic, findDuplicateDependencyVersions } from "./duplicate-dependency-doctor.ts";
 import type { ModuleFreshnessDiagnostic } from "./module-freshness.ts";
 import { checkServiceUnitPaths, type ServiceUnitDiagnostic } from "./service-doctor.ts";
 import { runExtensionSmoke, type SmokeOptions, type SmokeRegistrations } from "./smoke.ts";
@@ -56,6 +57,8 @@ export interface DoctorReport {
 	truncated: boolean;
 	/** A daemon-backed package's systemd --user unit referencing a path that no longer exists on disk -- see service-doctor.ts. Empty (not omitted) on a platform without systemd --user coverage. */
 	serviceUnits: ServiceUnitDiagnostic[];
+	/** Any @danypops/* package resolved to more than one distinct version anywhere in piHome's own npm tree -- see duplicate-dependency-doctor.ts's own doc comment for why this stays out of `ok`. */
+	duplicateDependencies: DuplicateDependencyDiagnostic[];
 	/**
 	 * Whether THIS running process still holds a stale in-memory copy of one
 	 * of its own runtime dependencies, loaded once at startup -- see
@@ -140,6 +143,7 @@ export async function runDoctor(piHome: string, projectRoot?: string, options: S
 		scanned: bounded.length,
 		truncated,
 		serviceUnits: serviceReport.diagnostics,
+		duplicateDependencies: findDuplicateDependencyVersions(piHome),
 	};
 }
 
@@ -161,6 +165,10 @@ export function formatDoctorReport(report: DoctorReport, json: boolean): string
 	for (const diagnostic of report.serviceUnits) {
 		out += `\n${diagnostic.severity.toUpperCase()} ${diagnostic.code} ${diagnostic.package} (${diagnostic.unitName}.service): ${diagnostic.message}\n`;
 	}
+	for (const duplicate of report.duplicateDependencies) {
+		const versions = duplicate.locations.map((location) => `${location.version} (${location.path})`).join(", ");
+		out += `\nDUPLICATE_DEPENDENCY_VERSION ${duplicate.name}: ${versions}\n`;
+	}
 	for (const module of report.moduleFreshness ?? []) {
 		if (!module.stale) continue;
 		out += `\nSTALE_MODULE_CACHE ${module.name}: the daemon loaded ${module.loadedVersion ?? "an unknown version"} at startup, but ${module.currentVersion ?? "a different version"} is now on disk -- restart the daemon (systemctl --user restart pi-packed.service) to pick it up.\n`;

package/service/src/adoption/duplicate-dependency-doctor.ts

@@ -0,0 +1,103 @@
+/**
+ * duplicate-dependency-doctor.ts — walks piHome's npm/node_modules tree
+ * (every top-level @danypops/<name>, plus one level of nesting -- the same
+ * shadow-copy shape findShadowCopies walks for one named package) and
+ * reports any @danypops/<name> resolved to more than one distinct version
+ * at once. Generalizes a bug class that recurred four times in one
+ * session (pi-web-spider, pi-tickets, pi-papyrus/jittor, pi-packed itself):
+ * a stale dependency floor forces a private nested copy instead of
+ * deduping to the shared hoisted one.
+ *
+ * Informational only, not part of DoctorReport's own `ok` -- a duplicate
+ * version isn't always a bug (an incompatible major range from a third
+ * party can coexist safely), so failing the whole report on every one
+ * would make a real, actionable case easy to tune out.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface DuplicateDependencyLocation {
+	readonly path: string;
+	readonly version: string;
+}
+
+export interface DuplicateDependencyDiagnostic {
+	readonly name: string;
+	readonly locations: readonly DuplicateDependencyLocation[];
+}
+
+/** Matches this file's own scan bound -- a tree-wide sweep never processes an unbounded package list. */
+const MAX_PACKAGES_SCANNED = 2_000;
+
+interface FoundPackage {
+	readonly name: string;
+	readonly version: string;
+	readonly path: string;
+}
+
+function readNameAndVersion(packageJsonPath: string): { name?: string; version?: string } {
+	try {
+		const pkg = JSON.parse(readFileSync(packageJsonPath, "utf8")) as { name?: unknown; version?: unknown };
+		return {
+			name: typeof pkg.name === "string" ? pkg.name : undefined,
+			version: typeof pkg.version === "string" ? pkg.version : undefined,
+		};
+	} catch {
+		return {};
+	}
+}
+
+/** Every @danypops/<name> directory directly under nodeModulesDir -- never throws; a missing or
+ * unreadable directory is just an empty result. */
+function listDanypopsPackageDirs(nodeModulesDir: string): string[] {
+	let scoped: string[];
+	try {
+		scoped = readdirSync(join(nodeModulesDir, "@danypops"));
+	} catch {
+		return [];
+	}
+	return scoped.map((name) => join(nodeModulesDir, "@danypops", name));
+}
+
+function scanInto(nodeModulesDir: string, budget: { remaining: number }, found: FoundPackage[]): void {
+	for (const dir of listDanypopsPackageDirs(nodeModulesDir)) {
+		if (budget.remaining <= 0) return;
+		budget.remaining--;
+		const { name, version } = readNameAndVersion(join(dir, "package.json"));
+		if (name && version) found.push({ name, version, path: dir });
+		// One level of nesting under THIS package's own node_modules -- the real, confirmed-live
+		// shadow-copy shape a stale floor produces; never descends deeper (matches findShadowCopies'
+		// own bound -- npm's own dedup is responsible for anything nested further than that).
+		for (const nestedDir of listDanypopsPackageDirs(join(dir, "node_modules"))) {
+			if (budget.remaining <= 0) return;
+			budget.remaining--;
+			const nested = readNameAndVersion(join(nestedDir, "package.json"));
+			if (nested.name && nested.version) found.push({ name: nested.name, version: nested.version, path: nestedDir });
+		}
+	}
+}
+
+/**
+ * Every @danypops/<name> resolved to more than one distinct version
+ * anywhere under piHome/npm/node_modules -- sorted by name for stable
+ * output. Two locations at the SAME version are never reported (npm simply
+ * didn't need to hoist further, not a real split); only an actual version
+ * disagreement is.
+ */
+export function findDuplicateDependencyVersions(piHome: string): DuplicateDependencyDiagnostic[] {
+	const found: FoundPackage[] = [];
+	scanInto(join(piHome, "npm", "node_modules"), { remaining: MAX_PACKAGES_SCANNED }, found);
+
+	const byName = new Map<string, DuplicateDependencyLocation[]>();
+	for (const pkg of found) {
+		byName.set(pkg.name, [...(byName.get(pkg.name) ?? []), { path: pkg.path, version: pkg.version }]);
+	}
+
+	const diagnostics: DuplicateDependencyDiagnostic[] = [];
+	for (const [name, locations] of byName) {
+		const distinctVersions = new Set(locations.map((location) => location.version));
+		if (distinctVersions.size > 1) diagnostics.push({ name, locations });
+	}
+	diagnostics.sort((a, b) => a.name.localeCompare(b.name));
+	return diagnostics;
+}

package/service/src/daemon/daemon-service.ts

@@ -38,6 +38,7 @@ import {
 } from "@danypops/vehicle-server/service";
 import { npmPackageName, readInstalledPackagesAcrossScopes, readPackageDeclarations } from "../packages/installed.ts";
 import type { InstalledPkg } from "../packages/package.ts";
+import { versionAtLeast } from "../publish/publish.ts";
 
 export interface DaemonServiceManifest {
 	/** Relative to the installed package's own root directory. */
@@ -125,6 +126,39 @@ function dependsOnVehicle(pkg: InstalledPackageJson): boolean {
  * web-spider, packed, enigma all expose a `serve` subcommand on the same
  * bin their `service install` command already points at).
  */
+/**
+ * Resolves ONE candidate directory to a daemon entrypoint -- factored out
+ * so the nested and hoisted candidates for the same dependency name can
+ * each be resolved independently and then compared (see
+ * detectVehicleDaemonService), instead of the first one found
+ * unconditionally winning.
+ */
+function resolveDependencyCandidate(depDir: string, depName: string): ResolvedDaemonEntrypoint | undefined {
+	const dep = readPackageJson(depDir);
+	if (!dep) return undefined;
+	// An explicit manifest wins over convention detection -- confirmed live: papyrus's real
+	// handle file is "vehicle-handle.json", not the "daemon.json" convention guess.
+	const depManifest = dep.packed?.daemonService;
+	if (depManifest && typeof depManifest.binPath === "string" && depManifest.binPath.length > 0 && dep.version) {
+		return {
+			binPath: join(depDir, depManifest.binPath),
+			args: depManifest.args,
+			name: depManifest.name ?? unscopedName(dep.name ?? depName),
+			displayName: depManifest.displayName,
+			handleFilename: depManifest.handleFilename,
+			workingDirectory: depManifest.workingDirectory,
+			restartOnFailure: depManifest.restartOnFailure,
+			restartSec: depManifest.restartSec,
+			version: dep.version,
+		};
+	}
+	const depBin = firstBinPath(dep);
+	if (depBin && dependsOnVehicle(dep) && dep.version) {
+		return { binPath: join(depDir, depBin), args: ["serve"], name: unscopedName(dep.name ?? depName), version: dep.version };
+	}
+	return undefined;
+}
+
 export function detectVehicleDaemonService(
 	packageDir: string,
 	fallbackName: string,
@@ -143,36 +177,19 @@ export function detectVehicleDaemonService(
 			join(packageDir, "node_modules", depName),
 			...(hoistedNodeModulesDir ? [join(hoistedNodeModulesDir, depName)] : []),
 		];
-		for (const depDir of candidateDirs) {
-			const dep = readPackageJson(depDir);
-			if (!dep) continue;
-			// An explicit manifest on the dependency itself wins over convention detection here too --
-			// mirrors resolveDaemonServiceSpec's own explicit-manifest-first behavior for a directly
-			// installed package. Without this, a dependency's own correct, explicit
-			// handleFilename/name/etc. was silently discarded in favor of a guess whenever the daemon
-			// was discovered one level down instead of installed directly by name -- exactly the
-			// common case (a Pi extension like pi-papyrus has no daemon of its own). Confirmed live:
-			// papyrus's real handle file is "vehicle-handle.json", not the "daemon.json" convention
-			// guess, and papyrus is only ever discovered this way, never installed directly by name.
-			const depManifest = dep.packed?.daemonService;
-			if (depManifest && typeof depManifest.binPath === "string" && depManifest.binPath.length > 0 && dep.version) {
-				return {
-					binPath: join(depDir, depManifest.binPath),
-					args: depManifest.args,
-					name: depManifest.name ?? unscopedName(dep.name ?? depName),
-					displayName: depManifest.displayName,
-					handleFilename: depManifest.handleFilename,
-					workingDirectory: depManifest.workingDirectory,
-					restartOnFailure: depManifest.restartOnFailure,
-					restartSec: depManifest.restartSec,
-					version: dep.version,
-				};
-			}
-			const depBin = firstBinPath(dep);
-			if (depBin && dependsOnVehicle(dep) && dep.version) {
-				return { binPath: join(depDir, depBin), args: ["serve"], name: unscopedName(dep.name ?? depName), version: dep.version };
-			}
+		const resolved = candidateDirs
+			.map((depDir) => resolveDependencyCandidate(depDir, depName))
+			.filter((entry): entry is ResolvedDaemonEntrypoint => entry !== undefined);
+		if (resolved.length === 0) continue;
+		if (resolved.length === 1) return resolved[0];
+		// Nested and hoisted both resolved for the same dependency (the real jittor incident:
+		// a stale nested copy always won just because it's checked first). Prefer the newer
+		// version; a genuine tie keeps the nested result, preserving papyrus's intentional case.
+		let best = resolved[0]!;
+		for (const candidate of resolved.slice(1)) {
+			if (versionAtLeast(candidate.version, best.version) && candidate.version !== best.version) best = candidate;
 		}
+		return best;
 	}
 	return undefined;
 }
@@ -408,13 +425,7 @@ export interface ReconcileAllResult {
 	reconciled: Array<{ packageName: string; vehicleName: string; installed: boolean; reason?: string }>;
 	skipped: number;
 	failed: Array<{ packageName: string; reason: string }>;
-	/**
-	 * Every Vehicle unregistered because this same sweep could no longer
-	 * discover it by any path (neither a configured extension's own
-	 * dependency walk nor listUnconfiguredDaemonDependencies' root-pinned
-	 * scan) -- see pruneStaleVehicles' own doc comment for why this is safe
-	 * to do unconditionally rather than requiring a separate opt-in call.
-	 */
+	/** Every Vehicle unregistered because this sweep no longer discovers it at all -- see pruneStaleVehicles. */
 	pruned: Array<{ vehicleName: string; executable: string }>;
 	pruneFailed: Array<{ vehicleName: string; reason: string }>;
 }
@@ -479,43 +490,20 @@ export async function reconcileAllDaemonServices(
 			...(resolved.result.installed ? {} : { reason: resolved.result.reason }),
 		});
 	}
-	// listUnconfiguredDaemonDependencies deliberately walks the FULL top-level
-	// node_modules sweep, not just readInstalledPackagesAcrossScopes' own
-	// pi:-configured list above -- a root-pinned dependency (e.g. lector,
-	// pinned directly in piHome/npm/package.json ahead of whatever version its
-	// own pi-lector wrapper's tree would resolve) is a real, currently-running
-	// Vehicle that the configured-packages loop above never reaches at all.
-	// Folding it in here is what makes the discovered set below actually
-	// complete -- pruning against anything narrower would delete a Vehicle
-	// that's still genuinely there, just reachable by a different path.
+	// Also fold in root-pinned dependencies (e.g. lector) the configured-packages loop above
+	// never reaches -- pruning against a narrower set would delete a Vehicle still genuinely there.
 	for (const dep of listUnconfiguredDaemonDependencies(piHome)) seen.add(dep.vehicleName);
 	const { pruned, pruneFailed } = await pruneStaleVehicles(piHome, seen, installer);
 	return { reconciled, skipped, failed, pruned, pruneFailed };
 }
 
 /**
- * Unregisters every Vehicle Armada currently declares that `discovered`
- * (this same sweep's own complete union of configured-extension and
- * root-pinned resolution) no longer produces at all -- the other half of
- * what makes Armada authoritative for every Vehicle Packed knows about.
- * Without this, a Vehicle whose packed.daemonService.name changed (or that
- * a stale nested dependency copy once resolved under a different name --
- * see this session's own live incident, a duplicate "web-spider-daemon"
- * losing every restart's single-instance-lock race against the correctly-
- * named "web-spider" Vehicle) just sits in the manifest forever: nothing
- * ever re-discovers it to overwrite it, and nothing ever notices it's gone
- * stale either.
- *
- * Scoped to only ever touch a Vehicle whose own `executable` lives under
- * piHome's own npm/node_modules -- i.e. one only Packed itself could
- * plausibly have registered in the first place. A Vehicle registered by an
- * entirely different mechanism (a hand-rolled `armada upsert` pointing
- * somewhere else on disk) is never a candidate, no matter how the
- * discovered set above turns out -- this function has no way to know that
- * caller's own intent, so it stays out of its way entirely. Packed's own
- * Vehicle (PACKED_VEHICLE_NAME) is excluded for the same reason
- * install()/remove()/restart() already refuse to touch it: reconcile runs
- * from inside Packed's own process.
+ * Unregisters every Vehicle Armada declares that `discovered` no longer
+ * produces at all -- otherwise a renamed/collided Vehicle (see the real
+ * web-spider-daemon incident) sits in the manifest forever. Scoped to only
+ * ever touch a Vehicle whose `executable` lives under piHome's own
+ * npm/node_modules -- one Packed itself could plausibly have registered.
+ * Packed's own Vehicle is excluded, matching install/remove/restart.
  */
 async function pruneStaleVehicles(
 	piHome: string,

package/service/test/cli.test.ts

@@ -1059,7 +1059,7 @@ describe("CLI", () => {
 			},
 			async doctor(projectRoot) {
 				calls.push(`doctor:${projectRoot}`);
-				return { ok: true, conflicts: [], extensions: [], scanned: 0, truncated: false, serviceUnits: [] };
+				return { ok: true, conflicts: [], extensions: [], scanned: 0, truncated: false, serviceUnits: [], duplicateDependencies: [] };
 			},
 			async updatesForProject(projectRoot) {
 				calls.push(`updatesForProject:${projectRoot}`);
@@ -1101,6 +1101,7 @@ describe("CLI", () => {
 			scanned: 0,
 			truncated: false,
 			serviceUnits: [],
+			duplicateDependencies: [],
 		});
 		expect(JSON.parse((await cliRun(["updates", "--project", "/tmp/project", "--json"], d)).out).updates).toEqual([]);
 		expect(calls).toEqual([

package/service/test/daemon-maintenance.test.ts

@@ -316,7 +316,7 @@ describe("startPackedDaemon's own maintenance-task wiring (self-heals Vehicle dr
 		});
 	});
 
-	describe("reconcileAllDaemonServices pruning -- unregisters a Vehicle no longer discoverable by any path (the-armada-registrar-jittor-web-spider-daemon-collision)", () => {
+	describe("reconcileAllDaemonServices pruning (the-armada-registrar-jittor-web-spider-daemon-collision)", () => {
 		function stalePiHomeVehicle(piHome: string, name: string): VehicleSpec {
 			return {
 				name: name as VehicleSpec["name"],

package/service/test/daemon-service.test.ts

@@ -208,6 +208,60 @@ describe("resolveDaemonServiceSpec", () => {
 		expect(result.spec.restartSec).toBe(2);
 	});
 
+	it("prefers the higher-semver candidate when BOTH a nested and hoisted copy of the same dependency resolve via bin+dependency convention -- the real jittor incident: a stale nested copy must never win over a correctly-versioned hoisted one just because it's checked first", () => {
+		const piHome = fakePiHome();
+		const extDir = join(piHome, "npm", "node_modules", "@danypops/pi-papyrus");
+		writeRawPackage(extDir, { name: "@danypops/pi-papyrus", version: "1.0.0", dependencies: { "@danypops/jittor": "^0.14.0" } });
+		// A stale nested copy pi-papyrus's own outdated floor forced npm to keep private, instead of
+		// deduping to the shared, correctly-versioned, hoisted copy every other consumer already uses.
+		const nestedDir = join(extDir, "node_modules", "@danypops/jittor");
+		writeRawPackage(nestedDir, {
+			name: "@danypops/jittor",
+			version: "0.14.0",
+			bin: { jittor: "src/cli.ts" },
+			dependencies: { "@danypops/vehicle-server": "^0.3.1" },
+		});
+		const hoistedDir = join(piHome, "npm", "node_modules", "@danypops/jittor");
+		writeRawPackage(hoistedDir, {
+			name: "@danypops/jittor",
+			version: "0.18.1",
+			bin: { jittor: "src/cli.ts" },
+			dependencies: { "@danypops/vehicle-server": "^0.17.0" },
+		});
+
+		const result = resolveDaemonServiceSpec(piHome, "npm:@danypops/pi-papyrus");
+		expect(result.ok).toBe(true);
+		if (!result.ok) throw new Error("expected ok");
+		expect(result.spec.binPath).toBe(join(hoistedDir, "src/cli.ts"));
+		expect(result.spec.version).toBe("0.18.1");
+	});
+
+	it("keeps the nested copy when it is genuinely the newer (or equal) one -- the tie-break only ever prefers a candidate that's actually newer, never blindly flips to hoisted", () => {
+		const piHome = fakePiHome();
+		const extDir = join(piHome, "npm", "node_modules", "@danypops/pi-papyrus");
+		writeRawPackage(extDir, { name: "@danypops/pi-papyrus", version: "1.0.0", dependencies: { "@danypops/jittor": "^0.18.0" } });
+		const nestedDir = join(extDir, "node_modules", "@danypops/jittor");
+		writeRawPackage(nestedDir, {
+			name: "@danypops/jittor",
+			version: "0.18.1",
+			bin: { jittor: "src/cli.ts" },
+			dependencies: { "@danypops/vehicle-server": "^0.17.0" },
+		});
+		const hoistedDir = join(piHome, "npm", "node_modules", "@danypops/jittor");
+		writeRawPackage(hoistedDir, {
+			name: "@danypops/jittor",
+			version: "0.14.0",
+			bin: { jittor: "src/cli.ts" },
+			dependencies: { "@danypops/vehicle-server": "^0.3.1" },
+		});
+
+		const result = resolveDaemonServiceSpec(piHome, "npm:@danypops/pi-papyrus");
+		expect(result.ok).toBe(true);
+		if (!result.ok) throw new Error("expected ok");
+		expect(result.spec.binPath).toBe(join(nestedDir, "src/cli.ts"));
+		expect(result.spec.version).toBe("0.18.1");
+	});
+
 	it("also detects the legacy @danypops/daemon-kit dependency name, not just vehicle-server", () => {
 		const piHome = fakePiHome();
 		const dir = join(piHome, "npm", "node_modules", "@danypops/web-spider-daemon");

package/service/test/doctor.test.ts

@@ -169,6 +169,40 @@ describeIfSandboxed("runDoctor", () => {
 		expect(report.ok).toBe(true);
 		expect(report.scanned).toBe(1);
 	});
+
+	it("surfaces a real duplicate @danypops/* dependency version without failing the overall report -- the same jittor-incident shape, caught proactively this time", async () => {
+		const home = piHome(["npm:pi-a"]);
+		installNpmPackage(
+			home,
+			"pi-a",
+			{ extensions: ["extension/index.ts"] },
+			{
+				"extension/index.ts": 'export default function (pi: any) { pi.registerTool({ name: "alpha" }); }',
+			},
+		);
+		const nodeModules = join(home, "npm", "node_modules");
+		mkdirSync(join(nodeModules, "@danypops", "jittor"), { recursive: true });
+		writeFileSync(
+			join(nodeModules, "@danypops", "jittor", "package.json"),
+			JSON.stringify({ name: "@danypops/jittor", version: "0.18.1" }),
+		);
+		mkdirSync(join(nodeModules, "@danypops", "pi-a", "node_modules", "@danypops", "jittor"), { recursive: true });
+		writeFileSync(
+			join(nodeModules, "@danypops", "pi-a", "node_modules", "@danypops", "jittor", "package.json"),
+			JSON.stringify({ name: "@danypops/jittor", version: "0.14.0" }),
+		);
+
+		const report = await runDoctor(home);
+
+		expect(report.duplicateDependencies).toHaveLength(1);
+		expect(report.duplicateDependencies[0]?.name).toBe("@danypops/jittor");
+		expect(report.ok).toBe(true); // informational only -- never fails the run by itself
+
+		const text = formatDoctorReport(report, false);
+		expect(text).toContain("DUPLICATE_DEPENDENCY_VERSION @danypops/jittor");
+		expect(text).toContain("0.18.1");
+		expect(text).toContain("0.14.0");
+	});
 });
 
 class NoopRegistry implements Registry {
@@ -313,7 +347,7 @@ describe("doctor.run — module freshness (a long-running daemon process's own s
 });
 
 describe("formatDoctorReport — module freshness rendering", () => {
-	const base = { ok: true, conflicts: [], extensions: [], scanned: 0, truncated: false, serviceUnits: [] };
+	const base = { ok: true, conflicts: [], extensions: [], scanned: 0, truncated: false, serviceUnits: [], duplicateDependencies: [] };
 
 	it("prints a STALE_MODULE_CACHE line with an actionable restart hint for each stale entry, and nothing for a fresh one", () => {
 		const text = formatDoctorReport(

package/service/test/duplicate-dependency-doctor.test.ts

@@ -0,0 +1,124 @@
+/**
+ * duplicate-dependency-doctor.test.ts — the general form of the bug class
+ * this session hit four separate times: a stale dependency floor forcing
+ * a private nested copy instead of deduping to the shared hoisted one.
+ */
+import { afterEach, describe, expect, it } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { findDuplicateDependencyVersions } from "../src/adoption/duplicate-dependency-doctor.ts";
+
+const roots: string[] = [];
+afterEach(() => {
+	for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+function track(dir: string): string {
+	roots.push(dir);
+	return dir;
+}
+
+function piHome(): string {
+	return track(mkdtempSync(join(tmpdir(), "packed-dup-deps-")));
+}
+
+function writePackage(dir: string, name: string, version: string): void {
+	mkdirSync(dir, { recursive: true });
+	writeFileSync(join(dir, "package.json"), JSON.stringify({ name, version }));
+}
+
+describe("findDuplicateDependencyVersions", () => {
+	it("returns nothing for a clean tree with no @danypops packages at all", () => {
+		const home = piHome();
+		expect(findDuplicateDependencyVersions(home)).toEqual([]);
+	});
+
+	it("returns nothing when every @danypops package resolves to exactly one version, even across several packages", () => {
+		const home = piHome();
+		const nodeModules = join(home, "npm", "node_modules");
+		writePackage(join(nodeModules, "@danypops", "armada"), "@danypops/armada", "0.4.7");
+		writePackage(join(nodeModules, "@danypops", "jittor"), "@danypops/jittor", "0.18.1");
+
+		expect(findDuplicateDependencyVersions(home)).toEqual([]);
+	});
+
+	it("reports the real jittor incident shape: a stale nested copy alongside the correctly-versioned hoisted one", () => {
+		const home = piHome();
+		const nodeModules = join(home, "npm", "node_modules");
+		const hoistedDir = join(nodeModules, "@danypops", "jittor");
+		writePackage(hoistedDir, "@danypops/jittor", "0.18.1");
+		const nestedDir = join(nodeModules, "@danypops", "pi-papyrus", "node_modules", "@danypops", "jittor");
+		writePackage(nestedDir, "@danypops/jittor", "0.14.0");
+		writePackage(join(nodeModules, "@danypops", "pi-papyrus"), "@danypops/pi-papyrus", "1.0.0");
+
+		const diagnostics = findDuplicateDependencyVersions(home);
+
+		expect(diagnostics).toHaveLength(1);
+		expect(diagnostics[0]!.name).toBe("@danypops/jittor");
+		const versions = diagnostics[0]!.locations.map((location) => location.version).sort();
+		expect(versions).toEqual(["0.14.0", "0.18.1"]);
+		const paths = diagnostics[0]!.locations.map((location) => location.path).sort();
+		expect(paths).toEqual([hoistedDir, nestedDir].sort());
+	});
+
+	it("does NOT report two locations at the exact same version -- npm simply didn't need to hoist further, not a real split", () => {
+		const home = piHome();
+		const nodeModules = join(home, "npm", "node_modules");
+		writePackage(join(nodeModules, "@danypops", "vehicle-core"), "@danypops/vehicle-core", "0.17.0");
+		writePackage(
+			join(nodeModules, "@danypops", "pi-tickets", "node_modules", "@danypops", "vehicle-core"),
+			"@danypops/vehicle-core",
+			"0.17.0",
+		);
+		writePackage(join(nodeModules, "@danypops", "pi-tickets"), "@danypops/pi-tickets", "1.0.0");
+
+		expect(findDuplicateDependencyVersions(home)).toEqual([]);
+	});
+
+	it("never descends into a nested copy's OWN node_modules -- one level of nesting is the real, confirmed shape; deeper is npm's own dedup problem", () => {
+		const home = piHome();
+		const nodeModules = join(home, "npm", "node_modules");
+		writePackage(join(nodeModules, "@danypops", "vehicle-server"), "@danypops/vehicle-server", "0.24.1");
+		const oneLevelDir = join(nodeModules, "@danypops", "pi-packed", "node_modules", "@danypops", "vehicle-server");
+		writePackage(oneLevelDir, "@danypops/vehicle-server", "0.24.1");
+		writePackage(join(nodeModules, "@danypops", "pi-packed"), "@danypops/pi-packed", "1.0.0");
+		// Two levels deep -- must never be reached.
+		writePackage(
+			join(oneLevelDir, "node_modules", "@danypops", "vehicle-core"),
+			"@danypops/vehicle-core",
+			"9.9.9",
+		);
+		writePackage(join(nodeModules, "@danypops", "vehicle-core"), "@danypops/vehicle-core", "0.17.0");
+
+		expect(findDuplicateDependencyVersions(home)).toEqual([]);
+	});
+
+	it("sorts multiple diagnostics by package name for stable output", () => {
+		const home = piHome();
+		const nodeModules = join(home, "npm", "node_modules");
+		writePackage(join(nodeModules, "@danypops", "web-spider-daemon"), "@danypops/web-spider-daemon", "0.24.2");
+		writePackage(
+			join(nodeModules, "@danypops", "pi-web-spider", "node_modules", "@danypops", "web-spider-daemon"),
+			"@danypops/web-spider-daemon",
+			"0.24.0",
+		);
+		writePackage(join(nodeModules, "@danypops", "pi-web-spider"), "@danypops/pi-web-spider", "1.0.0");
+		writePackage(join(nodeModules, "@danypops", "armada"), "@danypops/armada", "0.4.7");
+		writePackage(
+			join(nodeModules, "@danypops", "pi-packed", "node_modules", "@danypops", "armada"),
+			"@danypops/armada",
+			"0.4.3",
+		);
+		writePackage(join(nodeModules, "@danypops", "pi-packed"), "@danypops/pi-packed", "1.0.0");
+
+		const diagnostics = findDuplicateDependencyVersions(home);
+
+		expect(diagnostics.map((diagnostic) => diagnostic.name)).toEqual(["@danypops/armada", "@danypops/web-spider-daemon"]);
+	});
+
+	it("returns [] rather than throwing when piHome/npm/node_modules doesn't exist yet", () => {
+		const home = piHome();
+		expect(findDuplicateDependencyVersions(home)).toEqual([]);
+	});
+});