@danypops/pi-packed 0.21.14 → 0.22.0

package/service/src/packages/resources.ts

@@ -201,3 +201,66 @@ export async function toggleResource(input: ToggleResourceInput): Promise<{ ok:
 	}
 	return { ok: true };
 }
+
+/**
+ * Captures a configured package entry's own filter overrides
+ * (extensions/skills/prompts/themes +/-path arrays -- see toggleResource's
+ * own doc comment) before a replace/update-to-target operation removes it
+ * outright: a bare `pi remove` + `pi install` sequence to bump a pinned
+ * version replaces the WHOLE settings.json entry, silently reverting any
+ * per-resource enable/disable customization the user had configured back
+ * to the freshly-installed package's own defaults. undefined when the
+ * entry has no filter overrides at all (nothing to preserve) or isn't
+ * found (already removed, or never existed as a real entry).
+ */
+export function captureEntryFilters(settingsPath: string, source: string): Partial<Record<ResourceField, string[]>> | undefined {
+	const entry = readSettingsPackages(settingsPath).find((candidate) => candidate.source === source);
+	if (!entry) return undefined;
+	const filters: Partial<Record<ResourceField, string[]>> = {};
+	for (const field of RESOURCE_FIELDS) {
+		const value = entry[field];
+		if (value) filters[field] = value;
+	}
+	return Object.keys(filters).length > 0 ? filters : undefined;
+}
+
+/**
+ * Re-applies a previously captured set of filter overrides onto `source`'s
+ * own freshly-created package entry -- the other half of
+ * captureEntryFilters, restoring what a replace operation's remove step
+ * would otherwise have discarded. A no-op (never throws) when `filters` is
+ * undefined/empty, the settings file is unreadable, or `source`'s entry
+ * doesn't exist yet (e.g. the install step itself failed and never wrote
+ * one) -- there is nothing safe to merge a filter override onto in that
+ * case, and the caller's own install failure is already the real error to
+ * surface.
+ */
+export async function applyEntryFilters(
+	settingsPath: string,
+	source: string,
+	filters: Partial<Record<ResourceField, string[]>> | undefined,
+): Promise<boolean> {
+	if (!filters || Object.keys(filters).length === 0) return true; // nothing to preserve is not a failure
+	let settings: Record<string, unknown>;
+	try {
+		settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+	} catch {
+		return false;
+	}
+	const packages = Array.isArray(settings.packages) ? [...settings.packages] : [];
+	const index = packages.findIndex((raw) => parseEntry(raw)?.source === source);
+	if (index === -1) return false;
+	const merged: Record<string, unknown> =
+		typeof packages[index] === "string" ? { source: packages[index] } : { ...(packages[index] as Record<string, unknown>) };
+	for (const [field, value] of Object.entries(filters)) merged[field] = value;
+	packages[index] = merged;
+	try {
+		await atomicWriteJson(settingsPath, { ...settings, packages });
+		return true;
+	} catch {
+		// best-effort: the replace itself already succeeded, a filter-preservation
+		// write failure here is surfaced to the caller as a non-fatal detail, not
+		// a reason to report the whole replace as failed.
+		return false;
+	}
+}

package/service/src/public/client.ts

@@ -55,7 +55,7 @@ export interface PackedExtensionClient {
 	install(source: string, approved?: boolean): Promise<string>;
 	installService(source: string, approved?: boolean): Promise<{ output: string; spec?: ServiceSpecSummary }>;
 	remove(name: string, approved?: boolean): Promise<string>;
-	update(source: string, approved?: boolean): Promise<UpdateOutcome>;
+	update(source: string, approved?: boolean, target?: string): Promise<UpdateOutcome>;
 	setupPlan(manifestPath: string, prune?: boolean): Promise<SetupPlan>;
 	setupApply(manifestPath: string, approved?: boolean, prune?: boolean): Promise<SetupApplyResult>;
 	listResources(projectRoot?: string): Promise<{ global: PackageResources[]; project: PackageResources[] }>;
@@ -176,8 +176,8 @@ export class PackedClient implements PackedExtensionClient {
 		if (!result.ok) throw new Error(result.output);
 		return result.output;
 	}
-	async update(source: string, approved = false): Promise<UpdateOutcome> {
-		const result = await this.call("package.update", { source, approved });
+	async update(source: string, approved = false, target?: string): Promise<UpdateOutcome> {
+		const result = await this.call("package.update", { source, approved, target });
 		if (!result.ok) throw new Error(result.output);
 		return {
 			output: result.output,
@@ -186,6 +186,12 @@ export class PackedClient implements PackedExtensionClient {
 			pinned: result.pinned ?? false,
 			previousVersion: result.previousVersion,
 			currentVersion: result.currentVersion,
+			outOfRangeUpdateAvailable: result.outOfRangeUpdateAvailable,
+			pinnedSourceRequiresTarget: result.pinnedSourceRequiresTarget,
+			replaced: result.replaced,
+			before: result.before,
+			after: result.after,
+			rollback: result.rollback,
 		};
 	}
 	setupPlan(manifestPath: string, prune = false) {

package/service/src/public/protocol.ts

@@ -53,6 +53,12 @@ export interface UpdateOutcome {
 	pinned: boolean;
 	previousVersion?: string;
 	currentVersion?: string;
+	outOfRangeUpdateAvailable?: string;
+	pinnedSourceRequiresTarget?: boolean;
+	replaced?: boolean;
+	before?: { source: string; version?: string };
+	after?: { source: string; version?: string };
+	rollback?: { attempted: boolean; ok: boolean; message?: string };
 }
 export interface Diagnostic {
 	code: string;
@@ -141,7 +147,7 @@ export interface ExtensionOperationInputs {
 	"package.install": { source: string; approved?: boolean };
 	"package.install_service": { source: string; approved?: boolean };
 	"package.remove": { name: string; approved?: boolean };
-	"package.update": { source: string; approved?: boolean };
+	"package.update": { source: string; approved?: boolean; target?: string };
 	"setup.plan": { manifestPath: string; prune?: boolean };
 	"setup.apply": { manifestPath: string; approved?: boolean; prune?: boolean };
 	"resources.list": { projectRoot?: string };
@@ -165,6 +171,12 @@ export interface ExtensionOperationOutputs {
 		pinned?: boolean;
 		previousVersion?: string;
 		currentVersion?: string;
+		outOfRangeUpdateAvailable?: string;
+		pinnedSourceRequiresTarget?: boolean;
+		replaced?: boolean;
+		before?: { source: string; version?: string };
+		after?: { source: string; version?: string };
+		rollback?: { attempted: boolean; ok: boolean; message?: string };
 	};
 	"setup.plan": SetupPlan;
 	"setup.apply": SetupApplyResult;

package/service/test/cli.test.ts

@@ -59,9 +59,11 @@ class FakeInstaller implements Installer {
 		this.approved = options?.approved === true;
 		return `Removed ${source}`;
 	}
-	async update(source: string, options?: { approved?: boolean }): Promise<UpdateOutcome> {
+	gotTarget: string | undefined;
+	async update(source: string, options?: { approved?: boolean; target?: string }): Promise<UpdateOutcome> {
 		this.updated = source;
 		this.approved = options?.approved === true;
+		this.gotTarget = options?.target;
 		return {
 			output: `Updated ${source}`,
 			reloadRequired: true,
@@ -594,6 +596,52 @@ describe("CLI", () => {
 		});
 	});
 
+	it("update --to threads the replacement target through to the installer and reports it in both human and JSON output", async () => {
+		const d = deps({
+			inst: (() => {
+				const fake = new FakeInstaller();
+				fake.updateOutcome = {
+					replaced: true,
+					before: { source: "npm:@scope/pkg@1.0.0", version: "1.0.0" },
+					after: { source: "npm:@scope/pkg@2.0.0", version: "2.0.0" },
+				};
+				return fake;
+			})(),
+		});
+
+		const human = await cliRun(["update", "npm:@scope/pkg@1.0.0", "--to", "npm:@scope/pkg@2.0.0", "--approve"], d);
+		expect(human.code).toBe(0);
+		expect(human.out).toContain("replaced npm:@scope/pkg@1.0.0 with npm:@scope/pkg@2.0.0");
+		expect((d.inst as FakeInstaller).gotTarget).toBe("npm:@scope/pkg@2.0.0");
+
+		const json = await cliRun(["update", "npm:@scope/pkg@1.0.0", "--to", "npm:@scope/pkg@2.0.0", "--approve", "--json"], d);
+		const parsed = JSON.parse(json.out);
+		expect(parsed.replaced).toBe(true);
+		expect(parsed.before).toEqual({ source: "npm:@scope/pkg@1.0.0", version: "1.0.0" });
+		expect(parsed.after).toEqual({ source: "npm:@scope/pkg@2.0.0", version: "2.0.0" });
+	});
+
+	it("update --to rejects an invalid target source with a usage error, before ever calling the installer", async () => {
+		const d = deps();
+		const result = await cliRun(["update", "npm:@scope/pkg@1.0.0", "--to", "not a valid source!", "--approve"], d);
+		expect(result.code).toBe(2);
+		expect((d.inst as FakeInstaller).updated).toBe("");
+	});
+
+	it("reports pinnedSourceRequiresTarget and mentions --to in the human-readable pinned message", async () => {
+		const d = deps({
+			inst: (() => {
+				const fake = new FakeInstaller();
+				fake.updateOutcome = { alreadyUpToDate: true, reloadRequired: false, pinned: true, pinnedSourceRequiresTarget: true };
+				return fake;
+			})(),
+		});
+
+		const human = await cliRun(["update", "npm:@scope/pkg@1.0.0", "--approve"], d);
+		expect(human.out).toContain("--to");
+		const json = await cliRun(["update", "npm:@scope/pkg@1.0.0", "--approve", "--json"], d);
+		expect(JSON.parse(json.out).pinnedSourceRequiresTarget).toBe(true);
+	});
 
 	it("update --self requires approval under the guarded default, same as every other mutation", async () => {
 		const d = deps({
@@ -947,6 +995,32 @@ describe("CLI", () => {
 		]);
 	});
 
+	it("verify-deploy runs standalone without a daemon, reporting stale/missing/shadow locations for a real on-disk layout", async () => {
+		const piHome = track(mkdtempSync(join(tmpdir(), "packed-verify-deploy-cli-")));
+		const pkgDir = join(piHome, "npm", "node_modules", "@scope", "pkg");
+		mkdirSync(pkgDir, { recursive: true });
+		writeFileSync(join(pkgDir, "package.json"), JSON.stringify({ name: "@scope/pkg", version: "1.2.3" }));
+		const d = deps({ piHome });
+
+		const jsonResult = await cliRun(["verify-deploy", "@scope/pkg", "--json"], d);
+		expect(jsonResult.code).toBe(0);
+		const parsed = JSON.parse(jsonResult.out);
+		expect(parsed.ok).toBe(true);
+		expect(parsed.packageName).toBe("@scope/pkg");
+		expect(parsed.expectedVersion).toBe("1.2.3");
+
+		const human = await cliRun(["verify-deploy", "@scope/pkg"], d);
+		expect(human.out).toContain("PASS");
+		expect(human.code).toBe(0);
+
+		const stale = await cliRun(["verify-deploy", "@scope/pkg", "--version", "9.9.9"], d);
+		expect(stale.code).toBe(1);
+		expect(stale.out).toContain("FAIL");
+		expect(stale.out).toContain("STALE (1.2.3)");
+
+		expect((await cliRun(["verify-deploy", "not a valid name!"], d)).code).toBe(2);
+	});
+
 	it("advisories runs standalone without a daemon and degrades to zero findings, never a real network call, when nothing is installed", async () => {
 		const d = deps({ piHome: track(mkdtempSync(join(tmpdir(), "packed-advisories-cli-"))) });
 		const result = await cliRun(["advisories", "--json"], d);

package/service/test/deploy-verify.test.ts

@@ -0,0 +1,168 @@
+/**
+ * deploy-verify.test.ts — the exact hand-diffing ceremony this module
+ * replaces: comparing a package's on-disk version at every known install
+ * location plus stale shadow copies, against an expected version.
+ */
+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 { findShadowCopies, formatDeployVerification, verifyDeploy } from "../src/packages/deploy-verify.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 writePackageAt(packageJsonPath: string, version: string): void {
+	mkdirSync(join(packageJsonPath, ".."), { recursive: true });
+	writeFileSync(packageJsonPath, JSON.stringify({ version }));
+}
+
+function piHomeWith(name: string, version: string | undefined): string {
+	const dir = track(mkdtempSync(join(tmpdir(), "packed-deploy-verify-")));
+	if (version !== undefined) writePackageAt(join(dir, "npm", "node_modules", name, "package.json"), version);
+	else mkdirSync(join(dir, "npm", "node_modules"), { recursive: true });
+	return dir;
+}
+
+describe("verifyDeploy", () => {
+	it("reports ok when the only known location matches the expected version and no shadow copy exists", () => {
+		const piHome = piHomeWith("@scope/pkg", "1.2.3");
+
+		const report = verifyDeploy(piHome, "@scope/pkg", "1.2.3");
+
+		expect(report.ok).toBe(true);
+		expect(report.expectedVersion).toBe("1.2.3");
+		expect(report.locations[0]!.upToDate).toBe(true);
+		expect(report.shadowCopies).toEqual([]);
+	});
+
+	it("defaults expectedVersion to whatever's resolved at the primary (Pi npm project) location when none is given", () => {
+		const piHome = piHomeWith("@scope/pkg", "2.0.0");
+
+		const report = verifyDeploy(piHome, "@scope/pkg");
+
+		expect(report.expectedVersion).toBe("2.0.0");
+		expect(report.ok).toBe(true);
+	});
+
+	it("reports not-ok and version-unknown when the package isn't found anywhere and no expected version was given", () => {
+		const piHome = piHomeWith("@scope/pkg", undefined);
+
+		const report = verifyDeploy(piHome, "@scope/other-pkg");
+
+		expect(report.expectedVersion).toBeUndefined();
+		expect(report.ok).toBe(false);
+	});
+
+	it("flags a location still on an older version as stale, not just missing", () => {
+		const piHome = piHomeWith("@scope/pkg", "1.0.0");
+		const fakeHome = track(mkdtempSync(join(tmpdir(), "packed-deploy-verify-home-")));
+		writePackageAt(join(fakeHome, ".cache", ".bun", "install", "global", "node_modules", "@scope/pkg", "package.json"), "0.9.0");
+
+		const report = verifyDeploy(piHome, "@scope/pkg", "1.0.0", fakeHome);
+
+		const bunLocation = report.locations.find((l) => l.label === "Bun global install cache")!;
+		expect(bunLocation.present).toBe(true);
+		expect(bunLocation.upToDate).toBe(false);
+		expect(bunLocation.version).toBe("0.9.0");
+		expect(report.ok).toBe(false);
+	});
+});
+
+describe("findShadowCopies — the exact layout ExecInstaller.reresolveDependencyTree() already fixes for the install path", () => {
+	it("finds a nested copy under an unscoped sibling package's own node_modules", () => {
+		const piHome = piHomeWith("shared", "2.0.0");
+		writePackageAt(join(piHome, "npm", "node_modules", "leaf", "node_modules", "shared", "package.json"), "1.0.0");
+
+		const shadows = findShadowCopies(piHome, "shared");
+
+		expect(shadows).toHaveLength(1);
+		expect(shadows[0]!.label).toBe("shadow copy under leaf");
+		expect(shadows[0]!.packageJsonPath).toBe(join(piHome, "npm", "node_modules", "leaf", "node_modules", "shared", "package.json"));
+	});
+
+	it("finds a nested copy one level under a scoped sibling package", () => {
+		const piHome = piHomeWith("shared", "2.0.0");
+		writePackageAt(join(piHome, "npm", "node_modules", "@scope", "leaf", "node_modules", "shared", "package.json"), "1.0.0");
+
+		const shadows = findShadowCopies(piHome, "shared");
+
+		expect(shadows).toHaveLength(1);
+		expect(shadows[0]!.label).toBe("shadow copy under @scope/leaf");
+	});
+
+	it("finds nothing when the tree is clean", () => {
+		const piHome = piHomeWith("shared", "2.0.0");
+		mkdirSync(join(piHome, "npm", "node_modules", "unrelated"), { recursive: true });
+
+		expect(findShadowCopies(piHome, "shared")).toEqual([]);
+	});
+
+	it("never descends into a shadow copy's own node_modules", () => {
+		const piHome = piHomeWith("shared", "2.0.0");
+		writePackageAt(join(piHome, "npm", "node_modules", "leaf", "node_modules", "shared", "package.json"), "1.0.0");
+		// A second-level nested copy inside the shadow copy itself -- out of scope.
+		writePackageAt(
+			join(piHome, "npm", "node_modules", "leaf", "node_modules", "shared", "node_modules", "shared", "package.json"),
+			"0.5.0",
+		);
+
+		const shadows = findShadowCopies(piHome, "shared");
+
+		expect(shadows).toHaveLength(1);
+	});
+
+	it("reports every shadow copy in verifyDeploy's own report, making the overall result not-ok regardless of the shadow's own version", () => {
+		const piHome = piHomeWith("shared", "2.0.0");
+		// The shadow copy itself happens to already match the expected version --
+		// still a real problem: two copies existing at all is what matters, not
+		// whether this particular one happens to agree right now.
+		writePackageAt(join(piHome, "npm", "node_modules", "leaf", "node_modules", "shared", "package.json"), "2.0.0");
+
+		const report = verifyDeploy(piHome, "shared", "2.0.0");
+
+		expect(report.shadowCopies).toHaveLength(1);
+		expect(report.shadowCopies[0]!.upToDate).toBe(true);
+		expect(report.ok).toBe(false);
+	});
+});
+
+describe("formatDeployVerification", () => {
+	it("renders a human-readable PASS report with no shadow copies", () => {
+		const piHome = piHomeWith("@scope/pkg", "1.2.3");
+		const report = verifyDeploy(piHome, "@scope/pkg", "1.2.3");
+
+		const text = formatDeployVerification(report, false);
+
+		expect(text).toContain("PASS");
+		expect(text).toContain("@scope/pkg@1.2.3");
+		expect(text).toContain("no shadow copies found");
+	});
+
+	it("renders valid JSON when json is true", () => {
+		const piHome = piHomeWith("@scope/pkg", "1.2.3");
+		const report = verifyDeploy(piHome, "@scope/pkg", "1.2.3");
+
+		const parsed = JSON.parse(formatDeployVerification(report, true));
+
+		expect(parsed.ok).toBe(true);
+		expect(parsed.packageName).toBe("@scope/pkg");
+	});
+
+	it("renders a human-readable FAIL report listing a stale location", () => {
+		const piHome = piHomeWith("@scope/pkg", "1.0.0");
+		const report = verifyDeploy(piHome, "@scope/pkg", "9.9.9");
+
+		const text = formatDeployVerification(report, false);
+
+		expect(text).toContain("FAIL");
+		expect(text).toContain("STALE (1.0.0)");
+	});
+});

package/service/test/doctor.test.ts

@@ -4,7 +4,7 @@ import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { AuthenticatedRpcClient } from "@danypops/vehicle-client/rpc-client";
-import { runDoctor } from "../src/adoption/doctor.ts";
+import { formatDoctorReport, runDoctor } from "../src/adoption/doctor.ts";
 import { createApp, type OperationInputs, type OperationName, type OperationOutputs } from "../src/daemon/service.ts";
 import type { Installer, PkgInfo, Registry, SearchPage } from "../src/packages/package.ts";
 
@@ -237,3 +237,106 @@ describeIfSandboxed("doctor.run (daemon RPC wiring)", () => {
 		expect(result.conflicts).toHaveLength(1);
 	});
 });
+
+describe("doctor.run — module freshness (a long-running daemon process's own stale in-memory dependency, see module-freshness.ts)", () => {
+	it("merges in moduleFreshness and flips ok:false when the injected checker reports a stale dependency", async () => {
+		const home = piHome([]);
+		const app = createApp({
+			reg: new NoopRegistry(),
+			inst: new NoopInstaller(),
+			token: "test-token",
+			stateDir: track(mkdtempSync(join(tmpdir(), "packed-doctor-state-"))),
+			dataDir: track(mkdtempSync(join(tmpdir(), "packed-doctor-data-"))),
+			piHome: home,
+			moduleFreshness: () => [
+				{ name: "stale-dep", loadedVersion: "1.0.0", currentVersion: "2.0.0", stale: true },
+				{ name: "fresh-dep", loadedVersion: "1.0.0", currentVersion: "1.0.0", stale: false },
+			],
+		});
+		const client = new AuthenticatedRpcClient<OperationName, OperationInputs, OperationOutputs>("http://packed.test", "test-token", {
+			label: "Packed",
+			transport: (request) => app.fetch(request),
+		});
+
+		const result = await client.call("doctor.run", {});
+
+		expect(result.moduleFreshness).toEqual([
+			{ name: "stale-dep", loadedVersion: "1.0.0", currentVersion: "2.0.0", stale: true },
+			{ name: "fresh-dep", loadedVersion: "1.0.0", currentVersion: "1.0.0", stale: false },
+		]);
+		// The base doctor report (no extensions installed) would otherwise be ok:true.
+		expect(result.ok).toBe(false);
+	});
+
+	it("stays ok:true and reports no stale entries when the injected checker finds nothing stale", async () => {
+		const home = piHome([]);
+		const app = createApp({
+			reg: new NoopRegistry(),
+			inst: new NoopInstaller(),
+			token: "test-token",
+			stateDir: track(mkdtempSync(join(tmpdir(), "packed-doctor-state-"))),
+			dataDir: track(mkdtempSync(join(tmpdir(), "packed-doctor-data-"))),
+			piHome: home,
+			moduleFreshness: () => [{ name: "fresh-dep", loadedVersion: "1.0.0", currentVersion: "1.0.0", stale: false }],
+		});
+		const client = new AuthenticatedRpcClient<OperationName, OperationInputs, OperationOutputs>("http://packed.test", "test-token", {
+			label: "Packed",
+			transport: (request) => app.fetch(request),
+		});
+
+		const result = await client.call("doctor.run", {});
+
+		expect(result.moduleFreshness).toEqual([{ name: "fresh-dep", loadedVersion: "1.0.0", currentVersion: "1.0.0", stale: false }]);
+		expect(result.ok).toBe(true);
+	});
+
+	it("omits moduleFreshness entirely when nothing injects it -- a standalone runDoctor() call has no snapshot to compare against", async () => {
+		const home = piHome([]);
+		const app = createApp({
+			reg: new NoopRegistry(),
+			inst: new NoopInstaller(),
+			token: "test-token",
+			stateDir: track(mkdtempSync(join(tmpdir(), "packed-doctor-state-"))),
+			dataDir: track(mkdtempSync(join(tmpdir(), "packed-doctor-data-"))),
+			piHome: home,
+		});
+		const client = new AuthenticatedRpcClient<OperationName, OperationInputs, OperationOutputs>("http://packed.test", "test-token", {
+			label: "Packed",
+			transport: (request) => app.fetch(request),
+		});
+
+		const result = await client.call("doctor.run", {});
+
+		expect(result.moduleFreshness).toBeUndefined();
+		expect(result.ok).toBe(true);
+	});
+});
+
+describe("formatDoctorReport — module freshness rendering", () => {
+	const base = { ok: true, conflicts: [], extensions: [], scanned: 0, truncated: false, serviceUnits: [] };
+
+	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(
+			{
+				...base,
+				ok: false,
+				moduleFreshness: [
+					{ name: "stale-dep", loadedVersion: "1.0.0", currentVersion: "2.0.0", stale: true },
+					{ name: "fresh-dep", loadedVersion: "1.0.0", currentVersion: "1.0.0", stale: false },
+				],
+			},
+			false,
+		);
+
+		expect(text).toContain("STALE_MODULE_CACHE stale-dep");
+		expect(text).toContain("loaded 1.0.0 at startup");
+		expect(text).toContain("2.0.0 is now on disk");
+		expect(text).toContain("systemctl --user restart pi-packed.service");
+		expect(text).not.toContain("fresh-dep");
+	});
+
+	it("prints nothing extra when moduleFreshness is absent or empty", () => {
+		expect(formatDoctorReport(base, false)).not.toContain("STALE_MODULE_CACHE");
+		expect(formatDoctorReport({ ...base, moduleFreshness: [] }, false)).not.toContain("STALE_MODULE_CACHE");
+	});
+});

package/service/test/fixtures/install-validation/convention-only-package/extensions/index.ts

@@ -0,0 +1,3 @@
+export default function conventionOnlyFixtureExtension(pi: { registerCommand: (name: string, def: unknown) => void }) {
+	pi.registerCommand("convention-only-fixture", { description: "registers cleanly", handler: async () => {} });
+}

package/service/test/fixtures/install-validation/convention-only-package/package.json

@@ -0,0 +1,5 @@
+{
+	"name": "packed-install-validation-fixture-convention-only",
+	"version": "1.0.0",
+	"private": true
+}

package/service/test/install-validation.test.ts

@@ -21,6 +21,7 @@ const FIXTURES = join(__dirname, "fixtures/install-validation");
 const HEALTHY = join(FIXTURES, "healthy-package");
 const BROKEN = join(FIXTURES, "broken-package");
 const NO_MANIFEST = join(FIXTURES, "no-manifest-package");
+const CONVENTION_ONLY = join(FIXTURES, "convention-only-package");
 const DEP_PACKAGE = join(FIXTURES, "dep-package");
 
 const roots: string[] = [];
@@ -96,10 +97,22 @@ describe("HeadlessInstallValidator (real npm pack + tar extraction, no mocking)"
 		expect(result).toEqual({ ok: true, source: "git:github.com/u/r@main", extensions: [] });
 	});
 
-	it("passes a package with no pi.extensions -- most npm packages, nothing to validate", async () => {
+	it("refuses a package with no pi manifest and no convention resource directory -- not a Pi package (the is-number/is-buffer shape)", async () => {
 		const validator = new HeadlessInstallValidator();
 		const result = await validator.validate(`npm:${NO_MANIFEST}`);
+		expect(result.ok).toBe(false);
+		expect(result.extensions).toEqual([]);
+		expect(result.message).toContain("not a Pi package");
+	}, 20_000);
+
+	it("passes a package with no pi manifest but a real convention extensions/ directory", async () => {
+		const validator = new HeadlessInstallValidator();
+		const result = await validator.validate(`npm:${CONVENTION_ONLY}`);
 		expect(result.ok).toBe(true);
+		// Convention-discovered extensions (no pi.extensions manifest entry) are
+		// not headless load-checked here -- only presence gates admission; the
+		// per-extension mock-pi-cli check only ever runs against manifest-
+		// declared pi.extensions entries.
 		expect(result.extensions).toEqual([]);
 	}, 20_000);