@danypops/pi-packed 0.21.14 → 0.22.0

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

@@ -27,13 +27,29 @@
  * install/install_service/update/setup.apply which can fetch and run
  * arbitrary newly-published code).
  *
- * Approval/authorization is NOT reimplemented here: executeOperation()
- * (and the route()-based operations it delegates to internally) already
- * calls authorize()/assertPackagePermission() and throws
- * PackageOperationError(status: 403) on a denied mutation -- reusing
- * executeOperation() verbatim means this Vehicle surface automatically
- * inherits the exact same approval gate, with zero duplicated policy logic
- * to drift out of sync.
+ * Approval is delegated to the registry's own Vehicle-native mechanism
+ * (VehicleRegistry.configureApprovals/updateApprovalPolicy, wired up in
+ * daemon.ts/service.ts against packed's own mutationApproval setting) --
+ * NOT reimplemented here. Each operation below carries an explicit
+ * requiresApproval, exactly matching security.ts's PACKAGE_OPERATIONS
+ * classification's own guarded set (code-execution/settings-mutation/
+ * security-mutation), set unconditionally rather than left to derive from
+ * effect: two of Vehicle's five effect buckets already mix a guarded
+ * operation with an unguarded one here (external-write covers both
+ * restart_service/reconcile_services, which ARE guarded, and
+ * catalog.sync/index.build, which never were; local-write covers both
+ * resources.toggle/security.set, guarded, and setup.export/setup.update,
+ * never guarded) -- no single effect-derived default could reproduce this
+ * split, which is exactly the gap VehicleOperationDescriptor.requiresApproval
+ * exists to close.
+ *
+ * Once the registry's own gate approves a call (because it wasn't gated,
+ * or because a real capability was presented), the bound handler forces
+ * approved: true onto the input before delegating to executeOperation() --
+ * its own legacy authorize()/assertPackagePermission() check (still the
+ * sole gate for the older /api/v1/ops transport, untouched here) would
+ * otherwise reject a call whose caller never knew that REST-only field
+ * existed. A Vehicle caller's only approval contract is Vehicle's own.
  */
 
 import type { VehicleEffect, VehicleIdempotency } from "@danypops/vehicle-core";
@@ -66,6 +82,11 @@ const WRITE: VehicleIdempotency = { mode: "unsafe" };
 interface OperationMeta {
 	readonly description: string;
 	readonly effect: VehicleEffect;
+	/** See vehicle-core's VehicleOperationDescriptor.requiresApproval -- set explicitly for
+	 * every operation here (never left to derive from effect), matching security.ts's own
+	 * per-operation guarded/unguarded classification exactly. See this file's own doc
+	 * comment for why effect alone can't reproduce that split. */
+	readonly requiresApproval: boolean;
 }
 
 /**
@@ -74,53 +95,111 @@ interface OperationMeta {
  * classification) and its two deliberate refinements.
  */
 const OPERATION_META: Record<OperationName, OperationMeta> = {
-	"package.search": { description: "Searches Pi packages on npm.", effect: "read" },
-	"package.info": { description: "Reads bounded metadata for one package.", effect: "read" },
-	"package.installed": { description: "Lists locally installed Pi packages.", effect: "read" },
-	"package.catalog": { description: "Reads the local SQLite catalog mirror.", effect: "read" },
+	"package.search": { description: "Searches Pi packages on npm.", effect: "read", requiresApproval: false },
+	"package.info": { description: "Reads bounded metadata for one package.", effect: "read", requiresApproval: false },
+	"package.installed": { description: "Lists locally installed Pi packages.", effect: "read", requiresApproval: false },
+	"package.catalog": { description: "Reads the local SQLite catalog mirror.", effect: "read", requiresApproval: false },
 	"package.catalog.sync": {
 		description: "Refreshes the local catalog mirror from the Pi-package-tagged npm registry subset.",
 		effect: "external-write",
+		requiresApproval: false,
 	},
-	"package.index": { description: "Reads the locally built adoption-score index, if one exists.", effect: "read" },
+	"package.index": { description: "Reads the locally built adoption-score index, if one exists.", effect: "read", requiresApproval: false },
 	"package.index.build": {
 		description: "Builds the adoption-score index by scoring catalog entries against the npm registry.",
 		effect: "external-write",
+		requiresApproval: false,
+	},
+	"package.updates": { description: "Reads the last background update-check snapshot.", effect: "read", requiresApproval: false },
+	"package.check": {
+		description: "Runs static (and optionally smoke-test) quality checks against a local package path.",
+		effect: "read",
+		requiresApproval: false,
+	},
+	"package.pack": { description: "Verifies a local package path via npm pack.", effect: "read", requiresApproval: false },
+	"package.score": {
+		description: "Computes an adoption-readiness score for a local path or registry package.",
+		effect: "read",
+		requiresApproval: false,
+	},
+	"setup.export": { description: "Exports the current Pi setup as a portable manifest.", effect: "local-write", requiresApproval: false },
+	"setup.update": { description: "Updates an existing setup manifest in place.", effect: "local-write", requiresApproval: false },
+	"setup.plan": {
+		description: "Computes a setup manifest's install/update/remove plan without applying it.",
+		effect: "read",
+		requiresApproval: false,
 	},
-	"package.updates": { description: "Reads the last background update-check snapshot.", effect: "read" },
-	"package.check": { description: "Runs static (and optionally smoke-test) quality checks against a local package path.", effect: "read" },
-	"package.pack": { description: "Verifies a local package path via npm pack.", effect: "read" },
-	"package.score": { description: "Computes an adoption-readiness score for a local path or registry package.", effect: "read" },
-	"setup.export": { description: "Exports the current Pi setup as a portable manifest.", effect: "local-write" },
-	"setup.update": { description: "Updates an existing setup manifest in place.", effect: "local-write" },
-	"setup.plan": { description: "Computes a setup manifest's install/update/remove plan without applying it.", effect: "read" },
 	"setup.apply": {
 		description: "Applies a setup manifest's plan -- can install, update, or remove packages.",
 		effect: "open-world",
+		requiresApproval: true,
+	},
+	"package.security.get": {
+		description: "Reads this daemon's mutation-approval security settings.",
+		effect: "read",
+		requiresApproval: false,
+	},
+	"package.security.set": {
+		description: "Writes this daemon's mutation-approval security settings.",
+		effect: "local-write",
+		requiresApproval: true,
+	},
+	"package.install": {
+		description: "Installs a Pi package from an npm, git, or https source.",
+		effect: "open-world",
+		requiresApproval: true,
 	},
-	"package.security.get": { description: "Reads this daemon's mutation-approval security settings.", effect: "read" },
-	"package.security.set": { description: "Writes this daemon's mutation-approval security settings.", effect: "local-write" },
-	"package.install": { description: "Installs a Pi package from an npm, git, or https source.", effect: "open-world" },
 	"package.install_service": {
 		description: "Installs a persistent supervised service for an already-installed daemon package.",
 		effect: "open-world",
+		requiresApproval: true,
 	},
 	"package.restart_service": {
 		description: "Restarts an already-installed package's persistent service -- no new code introduced.",
 		effect: "external-write",
+		requiresApproval: true,
 	},
 	"package.reconcile_services": {
 		description: "Reconciles every installed daemon package's persistent service against desired state.",
 		effect: "external-write",
+		requiresApproval: true,
+	},
+	"package.remove": { description: "Removes an installed Pi package. Irreversible.", effect: "destructive", requiresApproval: true },
+	"package.update": {
+		description: "Updates a configured Pi package to its latest available version.",
+		effect: "open-world",
+		requiresApproval: true,
+	},
+	"resources.list": {
+		description: "Lists global and project-scoped Pi resources (extensions, skills, prompts, themes).",
+		effect: "read",
+		requiresApproval: false,
+	},
+	"resources.toggle": {
+		description: "Enables or disables one Pi resource in a settings file.",
+		effect: "local-write",
+		requiresApproval: true,
+	},
+	"pi.status": {
+		description: "Reports the locally running Pi version against the latest published release.",
+		effect: "read",
+		requiresApproval: false,
+	},
+	"advisories.scan": {
+		description: "Scans installed package versions against known advisories.",
+		effect: "read",
+		requiresApproval: false,
+	},
+	"doctor.run": {
+		description: "Runs diagnostic health checks (service install drift, resource config, ...).",
+		effect: "read",
+		requiresApproval: false,
+	},
+	"package.updates.project": {
+		description: "Checks for updates across every scope visible to one project.",
+		effect: "read",
+		requiresApproval: false,
 	},
-	"package.remove": { description: "Removes an installed Pi package. Irreversible.", effect: "destructive" },
-	"package.update": { description: "Updates a configured Pi package to its latest available version.", effect: "open-world" },
-	"resources.list": { description: "Lists global and project-scoped Pi resources (extensions, skills, prompts, themes).", effect: "read" },
-	"resources.toggle": { description: "Enables or disables one Pi resource in a settings file.", effect: "local-write" },
-	"pi.status": { description: "Reports the locally running Pi version against the latest published release.", effect: "read" },
-	"advisories.scan": { description: "Scans installed package versions against known advisories.", effect: "read" },
-	"doctor.run": { description: "Runs diagnostic health checks (service install drift, resource config, ...).", effect: "read" },
-	"package.updates.project": { description: "Checks for updates across every scope visible to one project.", effect: "read" },
 };
 
 /** Read effects need only packed:read; every other effect needs both (writes commonly also read first). */
@@ -142,16 +221,20 @@ export function registerPackedVehicleOperations(
 			output: passthroughVehicleSchema,
 			permissions: permissionsFor(meta.effect),
 			effect: meta.effect,
+			requiresApproval: meta.requiresApproval,
 			idempotency: meta.effect === "read" ? READ : WRITE,
 			limits: LIMITS,
 		});
 		registry.register(
 			OWNER,
-			bindVehicleOperation(
-				operation,
-				() => async (context) =>
-					withPackedErrorParity(() => executeOperation(name, context.input as OperationInputs[typeof name])),
-			),
+			bindVehicleOperation(operation, () => async (context) => {
+				// The registry's own gate (see this file's doc comment) already decided this
+				// call is approved by the time the handler runs -- forcing approved: true
+				// here satisfies executeOperation()'s own legacy authorize() check without
+				// asking a Vehicle caller to know that REST-only field even exists.
+				const input = { ...(context.input as Record<string, unknown>), approved: true } as OperationInputs[typeof name];
+				return withPackedErrorParity(() => executeOperation(name, input));
+			}),
 		);
 	}
 }

package/service/src/daemon/watcher.ts

@@ -5,12 +5,12 @@
  */
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { gt, valid } from "semver";
 import { UPDATES_FILE } from "../shared/constants.ts";
 import { createLogger } from "../shared/log.ts";
 
 const log = createLogger("watcher");
 
+import { isNewer } from "../packages/package.ts";
 import type { InstalledPkg, UpdateEntry, UpdatesSnapshot } from "../packages/package.ts";
 
 function updatesPath(dir: string): string {
@@ -30,23 +30,6 @@ export async function loadUpdates(dir: string): Promise<UpdatesSnapshot | undefi
 	}
 }
 
-/**
- * True drift only: mirrored latest is a real semver step *ahead* of what's
- * installed, never merely different from it. A plain !== check (this
- * function's own bug until fixed) cannot distinguish "installed is behind
- * latest" from "installed is already ahead of a stale/wrong mirrored
- * latest" -- confirmed live: an installed package whose version had
- * already passed the daemon's own mirrored dist-tags.latest kept showing
- * a permanent, un-clearable "update available" badge pointing at an
- * *older* version. Falls back to the old inequality only when either side
- * isn't parseable semver (a git ref, a literal "latest" tag, etc.) --
- * those aren't comparable at all, so "different" is the only signal left.
- */
-function isNewer(latest: string, have: string): boolean {
-	if (valid(latest, { loose: true }) && valid(have, { loose: true })) return gt(latest, have, { loose: true });
-	return latest !== have;
-}
-
 /** Pure diff against the local mirror (apt list --upgradable semantics):
  * drift = mirrored latest is genuinely newer than what we have. The
  * mirror is refreshed by catalogSync; updates are computed offline,

package/service/src/packages/deploy-verify.ts

@@ -0,0 +1,151 @@
+/**
+ * deploy-verify.ts — answers "did a publish/install actually land
+ * everywhere it should have" as one deterministic check, instead of the
+ * hand-diffing ceremony repeated after nearly every @danypops/* publish:
+ * comparing a package's on-disk version at every known install location
+ * (Pi's own npm project, Bun's global install cache) against an expected
+ * version, plus scanning for a stale nested node_modules "shadow" copy one
+ * level below another installed package's own node_modules -- exactly the
+ * layout ExecInstaller.reresolveDependencyTree() already fixes for the
+ * install path (see install.ts), surfaced here read-only for diagnosis.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface InstallLocation {
+	readonly label: string;
+	readonly packageJsonPath: string;
+}
+
+export interface LocationStatus extends InstallLocation {
+	/** undefined when the location has no readable package.json at all. */
+	readonly version?: string;
+	readonly mtimeMs?: number;
+	readonly present: boolean;
+	/** Only meaningful when present -- false whenever present is false too. */
+	readonly upToDate: boolean;
+}
+
+export interface DeployVerification {
+	readonly packageName: string;
+	readonly expectedVersion?: string;
+	readonly locations: readonly LocationStatus[];
+	readonly shadowCopies: readonly LocationStatus[];
+	/**
+	 * false when expectedVersion is unknown, a *present* known location is
+	 * behind it, or a shadow copy exists at all (a shadow copy is always a
+	 * problem regardless of its own version -- it can shadow the correct
+	 * top-level install for whichever importer's own node_modules walk
+	 * reaches it first). A location simply being absent (e.g. this package
+	 * was never installed via `bun install -g`) never fails this by
+	 * itself -- only a present-but-stale copy does.
+	 */
+	readonly ok: boolean;
+}
+
+function readVersionAndMtime(packageJsonPath: string): { version?: string; mtimeMs?: number } {
+	try {
+		const mtimeMs = statSync(packageJsonPath).mtimeMs;
+		const pkg = JSON.parse(readFileSync(packageJsonPath, "utf8")) as { version?: unknown };
+		return { version: typeof pkg.version === "string" ? pkg.version : undefined, mtimeMs };
+	} catch {
+		return {};
+	}
+}
+
+function statusOf(location: InstallLocation, expectedVersion: string | undefined): LocationStatus {
+	const { version, mtimeMs } = readVersionAndMtime(location.packageJsonPath);
+	return { ...location, version, mtimeMs, present: version !== undefined, upToDate: version !== undefined && version === expectedVersion };
+}
+
+/** Every location Packed itself installs an npm-sourced package into --
+ * Pi's own npm project (piHome/npm) and Bun's own global install cache
+ * (used by `bun install -g`/bunx-adjacent flows, not something Packed
+ * writes to itself, but a real place a stale copy can quietly linger).
+ * `home` defaults to the real home directory; injectable so a test never
+ * has to read or write outside its own tmpdir fixture. */
+export function standardInstallLocations(piHome: string, packageName: string, home: string = homedir()): InstallLocation[] {
+	return [
+		{ label: "Pi npm project", packageJsonPath: join(piHome, "npm", "node_modules", packageName, "package.json") },
+		{
+			label: "Bun global install cache",
+			packageJsonPath: join(home, ".cache", ".bun", "install", "global", "node_modules", packageName, "package.json"),
+		},
+	];
+}
+
+/** Bounded to Pi npm project's own direct children (and one level into a
+ * scope directory) -- the exact shape ExecInstaller.reresolveDependencyTree()
+ * fixes for the install path: a sibling package's own node_modules holding
+ * a nested copy of a shared dependency that a targeted `pi update`/`pi
+ * install` never reaches, only a full-tree `npm install` does. Never
+ * descends into a shadow copy's own node_modules -- one level is the real,
+ * confirmed-live shape; deeper nesting is npm's own problem to dedupe. */
+export function findShadowCopies(piHome: string, packageName: string): InstallLocation[] {
+	const npmNodeModulesDir = join(piHome, "npm", "node_modules");
+	const found: InstallLocation[] = [];
+	let entries: string[];
+	try {
+		entries = readdirSync(npmNodeModulesDir);
+	} catch {
+		return found;
+	}
+	for (const entry of entries) {
+		if (entry === packageName || entry.startsWith(".")) continue;
+		const entryPath = join(npmNodeModulesDir, entry);
+		let isDirectory: boolean;
+		try {
+			isDirectory = statSync(entryPath).isDirectory();
+		} catch {
+			continue;
+		}
+		if (!isDirectory) continue;
+		if (entry.startsWith("@")) {
+			let scoped: string[];
+			try {
+				scoped = readdirSync(entryPath);
+			} catch {
+				continue;
+			}
+			for (const sub of scoped) {
+				const nested = join(entryPath, sub, "node_modules", packageName, "package.json");
+				if (existsSync(nested)) found.push({ label: `shadow copy under ${entry}/${sub}`, packageJsonPath: nested });
+			}
+			continue;
+		}
+		const nested = join(entryPath, "node_modules", packageName, "package.json");
+		if (existsSync(nested)) found.push({ label: `shadow copy under ${entry}`, packageJsonPath: nested });
+	}
+	return found;
+}
+
+/**
+ * `expectedVersion` defaults to whatever's resolved at Pi's own npm
+ * project -- the natural "it was just installed/updated there, does every
+ * OTHER known location and shadow copy agree" question this exists to
+ * answer without a network round-trip. Pass one explicitly (e.g. the
+ * version a publish just produced) to check against that instead.
+ */
+export function verifyDeploy(piHome: string, packageName: string, expectedVersion?: string, home: string = homedir()): DeployVerification {
+	const locations0 = standardInstallLocations(piHome, packageName, home);
+	const resolvedExpected = expectedVersion ?? readVersionAndMtime(locations0[0]!.packageJsonPath).version;
+	const locations = locations0.map((location) => statusOf(location, resolvedExpected));
+	const shadowCopies = findShadowCopies(piHome, packageName).map((location) => statusOf(location, resolvedExpected));
+	const ok = resolvedExpected !== undefined && locations.every((l) => !l.present || l.upToDate) && shadowCopies.length === 0;
+	return { packageName, expectedVersion: resolvedExpected, locations, shadowCopies, ok };
+}
+
+export function formatDeployVerification(report: DeployVerification, json: boolean): string {
+	if (json) return `${JSON.stringify(report)}\n`;
+	let out = `${report.ok ? "PASS" : "FAIL"} — ${report.packageName}${report.expectedVersion ? `@${report.expectedVersion}` : " (version unknown -- not found at the primary location either)"}\n`;
+	for (const location of report.locations) {
+		const state = !location.present ? "MISSING" : location.upToDate ? "ok" : `STALE (${location.version})`;
+		out += `  ${state.padEnd(16)} ${location.label} (${location.packageJsonPath})\n`;
+	}
+	for (const shadow of report.shadowCopies) {
+		out += `  SHADOW COPY      ${shadow.label} at ${shadow.version ?? "unknown version"} (${shadow.packageJsonPath})\n`;
+	}
+	if (report.shadowCopies.length === 0) out += "  no shadow copies found\n";
+	return out;
+}

package/service/src/packages/install.ts

@@ -8,8 +8,10 @@ import {
 	type InstallValidationResult,
 	type InstallValidator,
 } from "../adoption/install-validation.ts";
+import { applyEntryFilters, captureEntryFilters, resolveToggleSettingsPath } from "./resources.ts";
 import { createLogger } from "../shared/log.ts";
-import { defaultPiHome, isPinnedNpmSource, readResolvedVersion } from "./installed.ts";
+import { defaultPiHome, isPinnedNpmSource, npmPackageName, readPackageDeclarations, readResolvedVersion } from "./installed.ts";
+import { isNewer } from "./package.ts";
 import type { Installer, UpdateOutcome } from "./package.ts";
 
 function round1(ms: number): number {
@@ -44,6 +46,14 @@ export class ExecInstaller implements Installer {
 		 * against a real daemon instead of guessing from wall-clock totals alone.
 		 */
 		private readonly logger: Logger = createLogger("install"),
+		/**
+		 * Optional real registry-mirror lookup (see daemon/watcher.ts's own
+		 * checkUpdates(), which this shares its cross-check logic with via
+		 * package.ts's isNewer) -- undefined by default so every existing
+		 * caller/test keeps its old "already up to date means nothing to
+		 * report" behavior unless a daemon explicitly wires its own mirror in.
+		 */
+		private readonly latestOf?: (name: string) => string | undefined,
 	) {}
 
 	private async run(args: string[]): Promise<string> {
@@ -141,7 +151,8 @@ export class ExecInstaller implements Installer {
 		return this.run(["remove", ...(options?.local ? ["-l"] : []), source]);
 	}
 
-	async update(source: string, _options?: { approved?: boolean; local?: boolean }): Promise<UpdateOutcome> {
+	async update(source: string, options?: { approved?: boolean; local?: boolean; target?: string }): Promise<UpdateOutcome> {
+		if (options?.target) return this.replace(source, options.target, options);
 		const t0 = performance.now();
 		const pinned = isPinnedNpmSource(source);
 		const previousVersion = readResolvedVersion(this.piHome, source);
@@ -165,6 +176,112 @@ export class ExecInstaller implements Installer {
 		// have changed" signal instead of falsely claiming it didn't.
 		const knowsBoth = previousVersion !== undefined && currentVersion !== undefined;
 		const changed = !knowsBoth || previousVersion !== currentVersion;
-		return { output, reloadRequired: changed, alreadyUpToDate: !changed, pinned, previousVersion, currentVersion };
+		const alreadyUpToDate = !changed;
+		// Only worth cross-checking when there's actually a "nothing changed"
+		// conclusion to double-check, a real mirror lookup was wired in, and
+		// there's a real bare npm name + resolved version to compare against.
+		const name = alreadyUpToDate && this.latestOf ? npmPackageName(source) : undefined;
+		const latest = name && currentVersion ? this.latestOf?.(name) : undefined;
+		const outOfRangeUpdateAvailable = latest && currentVersion && isNewer(latest, currentVersion) ? latest : undefined;
+		return {
+			output,
+			reloadRequired: changed,
+			alreadyUpToDate,
+			pinned,
+			previousVersion,
+			currentVersion,
+			...(outOfRangeUpdateAvailable ? { outOfRangeUpdateAvailable } : {}),
+			// A plain update() with no target can never move an exact pin --
+			// `pi update --extension` itself intentionally skips it (npm's own
+			// documented behavior for a versioned spec). alreadyUpToDate/pinned
+			// above are already an honest, non-"false success" result; this adds
+			// an unambiguous machine-readable nudge toward options.target instead
+			// of a caller having to infer "pinned AND alreadyUpToDate means stuck"
+			// itself. See replace() for the actual supervised pin-move workflow.
+			...(pinned && alreadyUpToDate ? { pinnedSourceRequiresTarget: true } : {}),
+		};
+	}
+
+	/**
+	 * The supervised "move a pin" workflow `pi update --extension` can never
+	 * perform by itself (it intentionally skips an exact pin) -- see the
+	 * linked research doc (pinned-package-update-behavior-and-safe-
+	 * replacement-research): a bare `pi install <newSource>` does not
+	 * rewrite an already-configured entry for the same package, it requires
+	 * an explicit remove-then-install sequence. Reuses install()/remove()
+	 * (the same supported, already-tested primitives) rather than
+	 * hand-rolling new subprocess calls, so validation/reresolve/timing
+	 * behave identically to every other mutation.
+	 *
+	 * Order of operations: identity check (never touches disk on mismatch)
+	 * -> capture `fromSource`'s own filter overrides (extensions/skills/
+	 * prompts/themes) so remove() doesn't silently discard them -> remove
+	 * `fromSource` -> install `toSource`, rolling back to `fromSource` on
+	 * failure -> re-apply the captured filters onto the new entry -> verify
+	 * BOTH postconditions (installed: readResolvedVersion; configured:
+	 * present in settings.json) before reporting success.
+	 */
+	private async replace(fromSource: string, toSource: string, options?: { approved?: boolean; local?: boolean }): Promise<UpdateOutcome> {
+		const fromName = npmPackageName(fromSource);
+		const toName = npmPackageName(toSource);
+		if (!fromName || !toName || fromName !== toName) {
+			throw new Error(`replace target must be the same package as the configured source: ${fromSource} -> ${toSource}`);
+		}
+		const settingsPath = resolveToggleSettingsPath(this.piHome);
+		const before = { source: fromSource, version: readResolvedVersion(this.piHome, fromSource) };
+		const filters = captureEntryFilters(settingsPath, fromSource);
+
+		let removeOutput: string;
+		try {
+			removeOutput = await this.remove(fromSource, options);
+		} catch (e) {
+			throw new Error(`replace failed removing ${fromSource}: ${e instanceof Error ? e.message : String(e)}`);
+		}
+
+		let installOutput: string;
+		try {
+			installOutput = await this.install(toSource, options);
+		} catch (installError) {
+			const installMessage = installError instanceof Error ? installError.message : String(installError);
+			let rollback: NonNullable<UpdateOutcome["rollback"]>;
+			try {
+				await this.install(fromSource, options);
+				rollback = { attempted: true, ok: true };
+			} catch (rollbackError) {
+				rollback = {
+					attempted: true,
+					ok: false,
+					message: rollbackError instanceof Error ? rollbackError.message : String(rollbackError),
+				};
+			}
+			const rollbackNote = rollback.ok
+				? `rolled back to ${fromSource}`
+				: `ROLLBACK TO ${fromSource} ALSO FAILED: ${rollback.message} -- ${fromName} may now be uninstalled entirely, reinstall manually`;
+			throw new Error(`replace failed installing ${toSource}: ${installMessage} (${rollbackNote})`);
+		}
+
+		await applyEntryFilters(settingsPath, toSource, filters);
+
+		const afterVersion = readResolvedVersion(this.piHome, toSource);
+		const configuredAfter = readPackageDeclarations(this.piHome).includes(toSource);
+		if (!configuredAfter) {
+			// install() itself reported success, but settings.json doesn't show
+			// toSource configured -- a real postcondition failure, not merely a
+			// version mismatch. Never claim success on an unverified replace.
+			throw new Error(`replace installed ${toSource} but settings.json does not show it configured -- verify manually before retrying`);
+		}
+		const after = { source: toSource, version: afterVersion };
+		const changed = before.version !== after.version || before.source !== after.source;
+		return {
+			output: `${removeOutput}\n${installOutput}`.trim(),
+			reloadRequired: changed,
+			alreadyUpToDate: !changed,
+			pinned: isPinnedNpmSource(toSource),
+			previousVersion: before.version,
+			currentVersion: after.version,
+			replaced: true,
+			before,
+			after,
+		};
 	}
 }

package/service/src/packages/package.ts

@@ -11,6 +11,27 @@
 // itself stays a pure port: nothing here creates a runtime dependency on install-validation.ts's
 // own npm-pack/tar/subprocess machinery.
 import type { InstallValidationResult } from "../adoption/install-validation.ts";
+import { gt, valid } from "semver";
+
+/**
+ * True drift only: `latest` is a real semver step *ahead* of `have`, never
+ * merely different from it. A plain !== check cannot distinguish "have is
+ * behind latest" from "have is already ahead of a stale/wrong latest" --
+ * confirmed live via the watcher's own version of this bug: an installed
+ * package whose version had already passed the daemon's mirrored
+ * dist-tags.latest kept showing a permanent, un-clearable "update
+ * available" badge pointing at an *older* version. Falls back to the old
+ * inequality only when either side isn't parseable semver (a git ref, a
+ * literal "latest" tag, etc.) -- those aren't comparable at all, so
+ * "different" is the only signal left. Lives here (not watcher.ts, its
+ * original home) so both the daemon's watcher and ExecInstaller.update()'s
+ * own out-of-range check share one implementation without packages/
+ * reaching into daemon/ (the dependency already runs the other way).
+ */
+export function isNewer(latest: string, have: string): boolean {
+	if (valid(latest, { loose: true }) && valid(have, { loose: true })) return gt(latest, have, { loose: true });
+	return latest !== have;
+}
 
 export type PackageVerification = "keyword-only" | "manifest" | "conventional";
 
@@ -108,13 +129,58 @@ export interface UpdateOutcome {
 	pinned: boolean;
 	previousVersion?: string;
 	currentVersion?: string;
+	/**
+	 * Set only when alreadyUpToDate is true AND a real registry version
+	 * newer than currentVersion exists outside the source's own declared
+	 * caret/range -- confirmed live: a 0.x package (e.g. ^0.9.8) that
+	 * crossed its own minor boundary (0.10.0 published) reported a bare
+	 * "already up to date" with no clue a newer version existed at all.
+	 * `pi update --extension` is itself bound by the declared range, so
+	 * "nothing changed" alone can't distinguish "genuinely current" from
+	 * "current within a range that's now stale" -- this cross-checks
+	 * against the same registry-mirror source of truth checkUpdates()
+	 * already uses, independent of the declared range.
+	 */
+	outOfRangeUpdateAvailable?: string;
+	/**
+	 * True only when update() was called on an exact npm pin with no
+	 * options.target -- `pi update --extension` intentionally leaves an
+	 * exact pin unchanged (npm's own documented behavior for a versioned
+	 * spec), so alreadyUpToDate/pinned above are already an honest,
+	 * non-"false success" result. This is an additional stable,
+	 * unambiguous machine-readable signal (kept alongside those existing
+	 * fields for back-compat) that a caller wanting to actually MOVE the
+	 * pin should retry with options.target set -- see replaced/before/
+	 * after/rollback below.
+	 */
+	pinnedSourceRequiresTarget?: boolean;
+	/**
+	 * True when options.target was given and update() routed to the
+	 * supervised replace workflow (remove the old exact source, install
+	 * the new one, verify both configured and installed postconditions,
+	 * attempt rollback on failure) instead of `pi update --extension`.
+	 */
+	replaced?: boolean;
+	before?: { source: string; version?: string };
+	after?: { source: string; version?: string };
+	/** Present only on a replace failure -- whether restoring the original
+	 * source was attempted and whether that restoration itself succeeded. */
+	rollback?: { attempted: boolean; ok: boolean; message?: string };
 }
 
 /** Driven port: pi CLI mutations. */
 export interface Installer {
 	install(source: string, options?: { approved?: boolean; local?: boolean }): Promise<string>;
 	remove(source: string, options?: { approved?: boolean; local?: boolean }): Promise<string>;
-	update(source: string, options?: { approved?: boolean; local?: boolean }): Promise<UpdateOutcome>;
+	/**
+	 * `options.target`, when given, replaces `source` (an exact pin or not)
+	 * with `target` through a supervised remove+install workflow instead of
+	 * `pi update --extension` -- see ExecInstaller.update()'s own doc
+	 * comment and the linked research doc
+	 * (pinned-package-update-behavior-and-safe-replacement-research) for
+	 * why a plain `pi update` can never move an exact pin by itself.
+	 */
+	update(source: string, options?: { approved?: boolean; local?: boolean; target?: string }): Promise<UpdateOutcome>;
 	/**
 	 * Optional batch-oriented split of install(), for a caller installing several packages
 	 * together (see SetupManager.apply()) -- a single ad hoc install() still does all three