@danypops/pi-packed 0.25.2 → 0.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/pi-packed",
-  "version": "0.25.2",
+  "version": "0.27.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.9",
     "@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

@@ -25,8 +25,10 @@
  * step isn't a real convention, so detection reads what's already true
  * on disk instead of asking for one more declaration.
  */
+import { spawn } from "node:child_process";
 import { readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { createVehicleRegistrar, type VehicleRegistrar, type VehicleRegistrationOutcome, type VehicleSpec } from "@danypops/armada";
 import { resolveDaemonPaths } from "@danypops/vehicle-server/paths";
 import {
@@ -127,25 +129,17 @@ function dependsOnVehicle(pkg: InstalledPackageJson): boolean {
  * bin their `service install` command already points at).
  */
 /**
- * Resolves ONE candidate directory to a daemon entrypoint, using the same
- * explicit-manifest-first-then-convention rule detectVehicleDaemonService's
- * own doc comment describes -- factored out so the nested and hoisted
- * candidates for the same dependency name can each be resolved
- * independently and then compared, instead of the first one found
- * unconditionally winning (see detectVehicleDaemonService's own comment on
- * why iteration order alone is never a safe tie-break).
+ * 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 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.
+	// 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 {
@@ -190,14 +184,9 @@ export function detectVehicleDaemonService(
 			.filter((entry): entry is ResolvedDaemonEntrypoint => entry !== undefined);
 		if (resolved.length === 0) continue;
 		if (resolved.length === 1) return resolved[0];
-		// Both a nested copy (checked first, above) and a hoisted copy resolved for the exact same
-		// dependency name -- e.g. pi-papyrus's own nested @danypops/jittor@0.14.0 alongside the
-		// correctly-versioned, tree-wide hoisted @danypops/jittor@0.18.1. The real jittor incident:
-		// the nested copy always won here, unconditionally, purely because candidateDirs checks it
-		// first -- regardless of which was actually newer. Prefer the real higher semver version
-		// instead; a genuine tie keeps the first-found (nested) result, preserving papyrus's own
-		// intentional-nesting case (confirmed live, see resolveDependencyCandidate's own comment)
-		// exactly as before whenever there's nothing to disambiguate.
+		// 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;
@@ -438,13 +427,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 }>;
 }
@@ -458,6 +441,38 @@ const PACKED_PACKAGE_NAME = "@danypops/pi-packed";
  * daemonOptions() -- vehicleName: PACKED_VEHICLE_NAME). One canonical name, not two. */
 export const PACKED_VEHICLE_NAME = "pi-packed";
 const SELF_REGISTRATION_REASON = "Packed cannot replace its own Armada service from inside the running daemon";
+const SELF_RESTART_SCHEDULED_REASON = "self-restart scheduled via a detached armada CLI process";
+/** Long enough for the HTTP response carrying this reason back to the caller to flush before the
+ * detached child's `armada restart` stops this very process. */
+const SELF_RESTART_DELAY_MS = 500;
+
+/** Fire-and-forget: schedule Packed's own Vehicle to restart from OUTSIDE this process. Packed
+ * can't safely stop+start itself in-process (the `stop` step would kill the very process handling
+ * this request before it could `start` again) -- so this spawns a detached `armada restart
+ * pi-packed` a beat later, after the response reporting "scheduled" has had time to flush, and lets
+ * it outlive this process via detached+unref. Swallows a resolution failure silently: worst case is
+ * the pre-existing behavior (a human restarts the service by hand), never a crash. */
+export type SelfRestartScheduler = (spec: ServiceSpec) => void;
+
+export const scheduleSelfRestart: SelfRestartScheduler = (_spec) => {
+	let cliPath: string;
+	try {
+		cliPath = fileURLToPath(import.meta.resolve("@danypops/armada/cli"));
+	} catch {
+		return;
+	}
+	setTimeout(() => {
+		try {
+			const child = spawn(process.execPath, [cliPath, "restart", PACKED_VEHICLE_NAME, "--json"], {
+				detached: true,
+				stdio: "ignore",
+			});
+			child.unref();
+		} catch {
+			/* best-effort -- a human can still restart the service by hand */
+		}
+	}, SELF_RESTART_DELAY_MS).unref();
+};
 
 /**
  * Sweeps every installed Packed package (global scope, plus a project's own
@@ -509,43 +524,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,
@@ -599,7 +591,10 @@ export interface DaemonServiceInstaller {
  * path/native controller are resolved once, not on every call.
  */
 export class RealDaemonServiceInstaller implements DaemonServiceInstaller {
-	constructor(private readonly registrar: VehicleRegistrar = createVehicleRegistrar()) {}
+	constructor(
+		private readonly registrar: VehicleRegistrar = createVehicleRegistrar(),
+		private readonly selfRestart: SelfRestartScheduler = scheduleSelfRestart,
+	) {}
 
 	async listRegisteredVehicles(): Promise<readonly VehicleSpec[]> {
 		return this.registrar.listRegistered();
@@ -642,7 +637,8 @@ export class RealDaemonServiceInstaller implements DaemonServiceInstaller {
 		const resolved = resolveDaemonServiceSpec(piHome, source);
 		if (!resolved.ok) return resolved;
 		if (resolved.spec.name === PACKED_VEHICLE_NAME) {
-			return { ok: true, restarted: false, reason: SELF_REGISTRATION_REASON, spec: resolved.spec };
+			this.selfRestart(resolved.spec);
+			return { ok: true, restarted: true, reason: SELF_RESTART_SCHEDULED_REASON, spec: resolved.spec };
 		}
 		if (!(await isVehicleServiceRegistered(resolved.spec.name, this.registrar))) {
 			return { ok: true, restarted: false, reason: `no persistent service is registered for ${resolved.spec.name}`, spec: resolved.spec };

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

@@ -9,8 +9,11 @@ import {
 	detectVehicleDaemonService,
 	listManagedPackages,
 	listUnconfiguredDaemonDependencies,
+	PACKED_VEHICLE_NAME,
 	RealDaemonServiceInstaller,
 	resolveDaemonServiceSpec,
+	scheduleSelfRestart,
+	type SelfRestartScheduler,
 } from "../src/daemon/daemon-service.ts";
 
 const roots: string[] = [];
@@ -470,6 +473,32 @@ describe("RealDaemonServiceInstaller -- Armada registration through the in-proce
 		}
 	});
 
+	it("restart() schedules an out-of-process self-restart for Packed's own Vehicle, never touching Armada in-process", async () => {
+		const piHome = fakePiHome();
+		writePackage(piHome, "@danypops/pi-packed", { binPath: "service/src/cli/cli.ts", args: ["serve"] });
+		const harness = await createArmadaTestHarness();
+		const scheduled: Array<{ name: string }> = [];
+		const selfRestart: SelfRestartScheduler = (spec) => {
+			scheduled.push({ name: spec.name });
+		};
+		try {
+			const installer = new RealDaemonServiceInstaller(harness.registrar, selfRestart);
+			const outcome = await installer.restart(piHome, "npm:@danypops/pi-packed");
+
+			expect(outcome).toMatchObject({ ok: true, restarted: true, spec: { name: "pi-packed" } });
+			expect(scheduled).toEqual([{ name: PACKED_VEHICLE_NAME }]);
+			// never asked Armada to stop/replace/start the very process running this test
+			expect(harness.events()).toEqual([]);
+		} finally {
+			await harness.dispose();
+		}
+	});
+
+	it("scheduleSelfRestart resolves armada's real CLI module -- proves the wiring is live, not just typechecked", () => {
+		expect(() => import.meta.resolve("@danypops/armada/cli")).not.toThrow();
+		expect(typeof scheduleSelfRestart).toBe("function");
+	});
+
 	it("install() reports a non-daemon package without touching Armada", async () => {
 		const piHome = fakePiHome();
 		writePackage(piHome, "some-pkg", undefined);

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([]);
+	});
+});