@danypops/pi-packed 0.21.14 → 0.22.0

package/service/src/adoption/install-validation.ts

@@ -12,7 +12,7 @@
  * subprocess as non-gating, observational evidence alongside that gating
  * check -- see ExtensionLoadResult.additionalLoadPaths.
  */
-import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { createRequire } from "node:module";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
@@ -74,6 +74,75 @@ const MAX_LOAD_TIMEOUT_MS = 30_000;
 const PACK_TIMEOUT_MS = 30_000;
 const INSTALL_TIMEOUT_MS = 60_000;
 const MAX_EXTENSIONS = 20;
+/** Bounds directoryHasMatchingFile's own recursive walk -- a real Pi package's
+ * resource directories are small; this only exists so an adversarial or
+ * accidentally enormous tarball can't make the convention-directory scan
+ * itself expensive. */
+const MAX_CONVENTION_SCAN_ENTRIES = 500;
+
+/** The four resource kinds a package.json's own `pi` manifest key, or (absent
+ * a manifest) pi's own convention directories, can declare -- see
+ * @earendil-works/pi-coding-agent's docs/packages.md "Package Structure". */
+const MANIFEST_RESOURCE_FIELDS = ["extensions", "skills", "prompts", "themes"] as const;
+
+/** Loosely mirrors (not a byte-for-byte port -- pi's own walker is
+ * .gitignore-aware via the `ignore` package, this isn't) pi's own
+ * convention-directory file matching from @earendil-works/pi-coding-agent's
+ * package-manager.js: extensions/ take .ts/.js recursively, skills/ take
+ * SKILL.md or any .md recursively, prompts/ and themes/ take top-level
+ * .md/.json respectively. Close enough to answer "would pi's own loader ever
+ * find anything to load here", which is all a pre-install admission check
+ * needs. */
+const CONVENTION_RESOURCE_DIRS: Record<string, { match: (name: string) => boolean; recursive: boolean }> = {
+	extensions: { match: (name) => name.endsWith(".ts") || name.endsWith(".js"), recursive: true },
+	skills: { match: (name) => name === "SKILL.md" || name.endsWith(".md"), recursive: true },
+	prompts: { match: (name) => name.endsWith(".md"), recursive: false },
+	themes: { match: (name) => name.endsWith(".json"), recursive: false },
+};
+
+function hasNonEmptyStringArray(value: unknown): boolean {
+	return Array.isArray(value) && value.some((entry) => typeof entry === "string" && entry.trim().length > 0);
+}
+
+/** True if the package's own `pi` manifest key declares at least one
+ * non-empty resource array of any of the four kinds -- not just
+ * `extensions`, which the caller already checked separately. */
+function hasAnyManifestResource(pi: Record<string, unknown> | undefined): boolean {
+	if (!pi) return false;
+	return MANIFEST_RESOURCE_FIELDS.some((field) => hasNonEmptyStringArray(pi[field]));
+}
+
+/** Bounded recursive scan for at least one file matching `match` under `dir`.
+ * `remaining` is a shared mutable budget across the whole call tree so a
+ * pathological directory structure can't make this unbounded work. */
+function directoryHasMatchingFile(dir: string, match: (name: string) => boolean, recursive: boolean, remaining: { count: number }): boolean {
+	if (!existsSync(dir) || remaining.count <= 0) return false;
+	let entries: import("node:fs").Dirent<string>[];
+	try {
+		entries = readdirSync(dir, { withFileTypes: true, encoding: "utf8" });
+	} catch {
+		return false;
+	}
+	for (const entry of entries) {
+		if (remaining.count-- <= 0) return false;
+		if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+		const full = join(dir, entry.name);
+		if (entry.isFile() && match(entry.name)) return true;
+		if (recursive && entry.isDirectory() && directoryHasMatchingFile(full, match, recursive, remaining)) return true;
+	}
+	return false;
+}
+
+/** True if the staged package root has any of pi's own convention resource
+ * directories (extensions/, skills/, prompts/, themes/) containing at least
+ * one file pi's own loader would actually pick up -- the fallback pi itself
+ * uses when a package declares no `pi` manifest at all. */
+function hasConventionResources(root: string): boolean {
+	const remaining = { count: MAX_CONVENTION_SCAN_ENTRIES };
+	return Object.entries(CONVENTION_RESOURCE_DIRS).some(([dirName, { match, recursive }]) =>
+		directoryHasMatchingFile(join(root, dirName), match, recursive, remaining),
+	);
+}
 
 function bounded(value: number | undefined, fallback: number, maximum: number): number {
 	if (!Number.isFinite(value) || value === undefined || value <= 0) return fallback;
@@ -215,9 +284,13 @@ async function verifyAllLoadPathsHeadless(entryPath: string, timeoutMs?: number)
 }
 
 /** Stages the real npm tarball in isolation and headlessly load-checks
- * every pi.extensions entry it declares. A package with no pi.extensions
- * (most npm packages) or a non-npm source has nothing to validate and
- * passes through as ok. */
+ * every pi.extensions entry it declares. A non-npm source has nothing to
+ * stage and passes through as ok. A package with no pi.extensions passes
+ * only if it declares some other pi manifest resource (skills/prompts/
+ * themes) or has a matching pi convention directory on disk -- otherwise
+ * it isn't a Pi package at all (a plain npm dependency like is-number or
+ * is-buffer) and is refused rather than silently admitted as a dead
+ * `packages` entry pi itself would never load anything from. */
 export class HeadlessInstallValidator implements InstallValidator {
 	constructor(private readonly timeoutMs?: number) {}
 
@@ -241,7 +314,26 @@ export class HeadlessInstallValidator implements InstallValidator {
 			const declared = Array.isArray(pi?.extensions)
 				? pi.extensions.filter((entry): entry is string => typeof entry === "string").slice(0, MAX_EXTENSIONS)
 				: [];
-			if (declared.length === 0) return { ok: true, source, extensions: [] };
+			if (declared.length === 0) {
+				// No pi.extensions to headlessly load-check -- but that alone isn't
+				// license to wave the package through. A real Pi package with only
+				// skills/prompts/themes (declared in the manifest or found via pi's
+				// own convention directories) still passes here unexamined; a
+				// package that is neither -- e.g. `is-number`, `is-buffer`, any
+				// plain leaf npm dependency someone points `pkg_install` at
+				// directly -- gets refused instead of silently becoming a dead
+				// `packages` entry that pi itself will never load anything from.
+				if (hasAnyManifestResource(pi) || hasConventionResources(staged.root)) {
+					return { ok: true, source, extensions: [] };
+				}
+				return {
+					ok: false,
+					source,
+					extensions: [],
+					message:
+						"package declares no pi.extensions/skills/prompts/themes and has no extensions/skills/prompts/themes directory -- not a Pi package",
+				};
+			}
 
 			const installed = await installStagedDependencies(staged.root);
 			if (!installed.ok) return { ok: false, source, extensions: [], message: installed.message };

package/service/src/adoption/module-freshness.ts

@@ -0,0 +1,100 @@
+/**
+ * module-freshness.ts — turns a recurring diagnosis-by-intuition ("this
+ * looks like Bun/Node holding a cached copy of an old build across a live
+ * process") into a real, checkable signal.
+ *
+ * A long-running process (the packed daemon) loads its own dependencies
+ * once via static imports at startup; Node/Bun's module cache then holds
+ * that exact in-memory copy for the rest of the process's life, regardless
+ * of whatever a later `pkg_update`/`npm install` writes to the same files
+ * on disk -- only a restart picks up the new code. Detecting that gap
+ * needs one snapshot taken at process start (captureLoadedModule, reusing
+ * smoke.ts's own real module-resolution helper, never executing anything)
+ * and a later re-read of the exact same on-disk path (checkModuleFreshness)
+ * -- if the file's mtime moved since the snapshot, the running process is
+ * provably still holding stale code in memory.
+ */
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { resolveDependencyModulesDir } from "./smoke.ts";
+
+export interface LoadedModuleSnapshot {
+	readonly name: string;
+	readonly packageJsonPath: string;
+	readonly version?: string;
+	readonly mtimeMs?: number;
+}
+
+export interface ModuleFreshnessDiagnostic {
+	readonly name: string;
+	readonly loadedVersion?: string;
+	readonly currentVersion?: string;
+	/** True only when both mtimes are known and genuinely differ -- never a
+	 * guess from version alone (a version string can stay identical across
+	 * a same-version reinstall that still replaced the file, and not every
+	 * package bumps a version for a local/dev iteration). */
+	readonly stale: 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 {};
+	}
+}
+
+/**
+ * Resolves `name`'s real installed package.json via Node's own module
+ * resolution (see smoke.ts's resolveDependencyModulesDir -- correct for
+ * both a nested and a hoisted layout, never executes anything) starting
+ * from `fromDir`, then records its version/mtime. undefined when `name`
+ * isn't resolvable from here at all -- never thrown, so one unresolvable
+ * watched name never prevents capturing the rest.
+ */
+export function captureLoadedModule(fromDir: string, name: string): LoadedModuleSnapshot | undefined {
+	const dir = resolveDependencyModulesDir(fromDir, name);
+	if (!dir) return undefined;
+	const packageJsonPath = join(dir, "package.json");
+	return { name, packageJsonPath, ...readVersionAndMtime(packageJsonPath) };
+}
+
+/** Bulk capture, skipping (not failing on) any name that isn't resolvable. */
+export function captureLoadedModules(fromDir: string, names: readonly string[]): LoadedModuleSnapshot[] {
+	const snapshots: LoadedModuleSnapshot[] = [];
+	for (const name of names) {
+		const snapshot = captureLoadedModule(fromDir, name);
+		if (snapshot) snapshots.push(snapshot);
+	}
+	return snapshots;
+}
+
+export function checkModuleFreshness(snapshot: LoadedModuleSnapshot): ModuleFreshnessDiagnostic {
+	const current = readVersionAndMtime(snapshot.packageJsonPath);
+	const stale = snapshot.mtimeMs !== undefined && current.mtimeMs !== undefined && current.mtimeMs !== snapshot.mtimeMs;
+	return { name: snapshot.name, loadedVersion: snapshot.version, currentVersion: current.version, stale };
+}
+
+export function checkModuleFreshnessAll(snapshots: readonly LoadedModuleSnapshot[]): ModuleFreshnessDiagnostic[] {
+	return snapshots.map(checkModuleFreshness);
+}
+
+/** The exact set of names worth watching for a long-running process: its
+ * own direct runtime dependencies (package.json's "dependencies" field) --
+ * the ones a static top-level import actually loads once at process start.
+ * devDependencies/peerDependencies are never loaded by the running process
+ * itself, so watching them would only ever report false staleness. Bounded
+ * the same way readPackageDeclarations elsewhere in this codebase bounds
+ * an untrusted-shape read -- never throws on a malformed package.json,
+ * just reports nothing to watch. */
+export function ownRuntimeDependencyNames(packageJsonPath: string, maxNames = 200): string[] {
+	try {
+		const pkg = JSON.parse(readFileSync(packageJsonPath, "utf8")) as { dependencies?: unknown };
+		if (typeof pkg.dependencies !== "object" || pkg.dependencies === null) return [];
+		return Object.keys(pkg.dependencies).slice(0, maxNames);
+	} catch {
+		return [];
+	}
+}

package/service/src/adoption/smoke.ts

@@ -1,4 +1,5 @@
 import { existsSync, realpathSync } from "node:fs";
+import { createRequire } from "node:module";
 import { dirname, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -53,13 +54,36 @@ function addReadOnlyBind(args: string[], path: string): void {
 	if (existsSync(path)) args.push("--ro-bind", path, path);
 }
 
+/**
+ * Resolves an installed dependency's real on-disk package directory via
+ * Node's own module-resolution algorithm (require.resolve against its
+ * package.json), starting from `fromDir` -- correct regardless of whether
+ * the package manager nested it under fromDir's own node_modules or
+ * hoisted it to a shared ancestor node_modules (npm's own hoisting
+ * decision, driven by what else in the tree also depends on it).
+ * Confirmed live: `packed doctor --json` crashed hard reconstructing a
+ * fixed nested-only path (`<packageDirectory>/node_modules/jiti`) that
+ * doesn't exist once jiti is hoisted to Pi's own npm prefix instead of
+ * pi-packed's own node_modules. Never executes the resolved module --
+ * require.resolve only locates a path, it never runs anything. undefined
+ * (not a throw) when genuinely unresolvable from here.
+ */
+export function resolveDependencyModulesDir(fromDir: string, name: string): string | undefined {
+	try {
+		const req = createRequire(join(fromDir, "package.json"));
+		return realpathSync(dirname(req.resolve(`${name}/package.json`)));
+	} catch {
+		return undefined;
+	}
+}
+
 function sandboxCommand(packageRoot: string, extensionPath: string, maxProcesses: number): string[] | undefined {
 	if (process.platform !== "linux" || !existsSync("/usr/bin/bwrap") || !existsSync("/usr/bin/prlimit")) return undefined;
 	const serviceRoot = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
 	const packageDirectory = dirname(serviceRoot);
 	const childHarness = join(serviceRoot, "src/adoption/smoke-child.ts");
-	const runnerModules = join(packageDirectory, "node_modules");
-	const jitiModules = realpathSync(join(runnerModules, "jiti"));
+	const jitiModules = resolveDependencyModulesDir(packageDirectory, "jiti");
+	if (!jitiModules) return undefined;
 	const bun = realpathSync(process.execPath);
 	const relativeExtension = relative(packageRoot, extensionPath).split(sep).join("/");
 	const args = [

package/service/src/cli/cli.ts

@@ -13,6 +13,7 @@ import { checkUpdates } from "../daemon/watcher.ts";
 import { generateIndex, indexPath, readIndex } from "../index/build-index.ts";
 import { syncCatalog } from "../packages/catalog.ts";
 import { catalogList, dbPath, getSyncMeta, latestVersion, openDb, searchLocal } from "../packages/db.ts";
+import { formatDeployVerification, verifyDeploy } from "../packages/deploy-verify.ts";
 import { defaultPiBin, NAME_RE } from "../packages/install.ts";
 import { npmPackageName, readInstalledPackages, readInstalledPackagesAcrossScopes } from "../packages/installed.ts";
 import type { Installer, Pkg, Registry, UpdateEntry } from "../packages/package.ts";
@@ -93,6 +94,7 @@ usage:
   packed index status [--json]                 report the local static index's generatedAt and package count
   packed check [path] [--smoke] [--json]       diagnose a Pi package; smoke is isolated and opt-in
   packed doctor [--project <path>] [--json]    smoke-test every enabled extension (global + project scope) and report tool/command/shortcut/flag name collisions before pi has to
+  packed verify-deploy <name> [--version <v>] [--json] diff a package's on-disk version across every known install location plus stale node_modules shadow copies
   packed pack [path] [--json]                  verify exact npm tarball contents without lifecycle scripts
   packed score [path|name] [--json]            report adoption-readiness evidence by dimension
   packed publish setup [path] [--force] [--json] generate an OIDC staged-publish workflow
@@ -169,6 +171,8 @@ interface Flags {
 	ecosystem: boolean;
 	self: boolean;
 	project?: string;
+	version?: string;
+	to?: string;
 }
 
 function parseFlags(rest: string[]): { flags: Flags; pos: string[] } {
@@ -202,6 +206,10 @@ function parseFlags(rest: string[]): { flags: Flags; pos: string[] } {
 		else if (a.startsWith("--limit=")) flags.limit = Number(a.slice(8)) || SEARCH_DEFAULT_LIMIT;
 		else if (a === "--project" && i + 1 < rest.length) flags.project = rest[++i];
 		else if (a.startsWith("--project=")) flags.project = a.slice(10);
+		else if (a === "--version" && i + 1 < rest.length) flags.version = rest[++i];
+		else if (a.startsWith("--version=")) flags.version = a.slice(10);
+		else if (a === "--to" && i + 1 < rest.length) flags.to = rest[++i];
+		else if (a.startsWith("--to=")) flags.to = a.slice(5);
 		else pos.push(a);
 	}
 	return { flags, pos };
@@ -358,6 +366,17 @@ const commands: Record<string, { usage: string; run: Command }> = {
 		},
 	},
 
+	"verify-deploy": {
+		usage: "packed verify-deploy <name> [--version <v>] [--json]  (diff a package's on-disk version across every known install location plus stale node_modules shadow copies)",
+		async run(_rest, d, flags, pos) {
+			const name = pos[0] ?? "";
+			if (!NAME_RE.test(name)) return usageErr(`usage: ${commands["verify-deploy"]!.usage}\n`);
+			const report = verifyDeploy(d.piHome, name, flags.version);
+			const output = formatDeployVerification(report, flags.json);
+			return report.ok ? ok(output) : fail(output);
+		},
+	},
+
 	search: {
 		usage: "packed search <query> [--offline] [--limit N] [--json]",
 		async run(_rest, d, flags, pos) {
@@ -646,7 +665,8 @@ const commands: Record<string, { usage: string; run: Command }> = {
 	},
 
 	update: {
-		usage: "packed update <configured-source> [--approve] [--json] | packed update --self [--approve] [--json]",
+		usage:
+			"packed update <configured-source> [--to <new-source>] [--approve] [--json] | packed update --self [--approve] [--json]  (--to replaces an exact pin end to end -- see verify-deploy/doctor for post-replace checks)",
 		async run(_rest, d, flags, pos) {
 			if (flags.self) {
 				try {
@@ -666,20 +686,25 @@ const commands: Record<string, { usage: string; run: Command }> = {
 			}
 			const source = pos[0] ?? "";
 			if (!SOURCE_RE.test(source)) return usageErr(`usage: ${commands.update!.usage}\n`);
+			if (flags.to !== undefined && !SOURCE_RE.test(flags.to)) return usageErr(`usage: ${commands.update!.usage}\n`);
 			try {
-				const outcome = await d.inst.update(source, { approved: flags.approved });
+				const outcome = await d.inst.update(source, { approved: flags.approved, target: flags.to });
 				if (outcome.alreadyUpToDate) {
 					if (flags.json) return ok(`${JSON.stringify({ ok: true, source, ...outcome })}\n`);
 					const version = outcome.currentVersion ?? outcome.previousVersion;
 					const reason = outcome.pinned
-						? `is pinned to ${version ?? "an exact version"} — pi update intentionally leaves pinned packages unchanged; run \`packed install npm:${npmPackageName(source) ?? source}\` to move off the pin`
+						? `is pinned to ${version ?? "an exact version"} — pi update intentionally leaves pinned packages unchanged; run \`packed update ${source} --to npm:${npmPackageName(source) ?? source}@<version>\` to move off the pin`
 						: `is already up to date${version ? ` at ${version}` : ""}`;
-					return ok(`${source} ${reason}\n`);
+					const outOfRangeNote = outcome.outOfRangeUpdateAvailable
+						? ` (a newer version, ${outcome.outOfRangeUpdateAvailable}, exists outside the declared range -- widen it to update)`
+						: "";
+					return ok(`${source} ${reason}${outOfRangeNote}\n`);
 				}
 				if (flags.json) return ok(`${JSON.stringify({ ok: true, source, ...outcome })}\n`);
 				const transition =
 					outcome.previousVersion && outcome.currentVersion ? ` (${outcome.previousVersion} → ${outcome.currentVersion})` : "";
-				return ok(`${outcome.output}${transition}\nReload Pi with /reload to activate the updated package.\n`);
+				const replacedNote = outcome.replaced ? ` (replaced ${outcome.before?.source ?? source} with ${outcome.after?.source ?? ""})` : "";
+				return ok(`${outcome.output}${transition}${replacedNote}\nReload Pi with /reload to activate the updated package.\n`);
 			} catch (error) {
 				const message = error instanceof Error ? error.message : String(error);
 				return flags.json

package/service/src/daemon/client.ts

@@ -51,7 +51,7 @@ export interface PackageDaemonPort {
 	restartService(source: string, approved?: boolean): Promise<{ output: string; restarted?: boolean; spec?: ServiceSummary }>;
 	reconcileServices(approved?: boolean, projectRoot?: string): Promise<OperationOutputs["package.reconcile_services"]>;
 	remove(name: string, approved?: boolean): Promise<string>;
-	update(source: string, approved?: boolean): Promise<UpdateOutcome>;
+	update(source: string, approved?: boolean, target?: string): Promise<UpdateOutcome>;
 	piStatus(): Promise<PiVersionReport>;
 	resourcesList(projectRoot?: string): Promise<{ global: PackageResources[]; project: PackageResources[] }>;
 	resourcesToggle(
@@ -265,8 +265,8 @@ export class PackageDaemonClient implements PackageDaemonPort {
 		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 PackageDaemonError(result.output || `failed to update ${source}`, "package.update");
 		return {
 			output: result.output,
@@ -275,6 +275,12 @@ export class PackageDaemonClient implements PackageDaemonPort {
 			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,
 		};
 	}
 }
@@ -289,8 +295,8 @@ export class PackageDaemonInstaller implements Installer {
 			throw new PackageDaemonError("daemon package removal requires an npm: source", "package.remove");
 		return this.client.remove(source.slice(4), options?.approved);
 	}
-	update(source: string, options?: { approved?: boolean; local?: boolean }): Promise<UpdateOutcome> {
-		return this.client.update(source, options?.approved);
+	update(source: string, options?: { approved?: boolean; local?: boolean; target?: string }): Promise<UpdateOutcome> {
+		return this.client.update(source, options?.approved, options?.target);
 	}
 }
 
@@ -312,8 +318,8 @@ export class DaemonBackedInstaller implements Installer {
 	async remove(source: string, options?: { approved?: boolean }): Promise<string> {
 		return new PackageDaemonInstaller(await connectPackageDaemon(this.paths)).remove(source, options);
 	}
-	async update(source: string, options?: { approved?: boolean }): Promise<UpdateOutcome> {
-		return (await connectPackageDaemon(this.paths)).update(source, options?.approved);
+	async update(source: string, options?: { approved?: boolean; target?: string }): Promise<UpdateOutcome> {
+		return (await connectPackageDaemon(this.paths)).update(source, options?.approved, options?.target);
 	}
 }
 

package/service/src/daemon/daemon.ts

@@ -1,4 +1,5 @@
-import { dirname } from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import {
 	type MaintenanceTask,
 	type RunningDaemon,
@@ -7,6 +8,7 @@ import {
 	startDaemon,
 } from "@danypops/vehicle-server/daemon";
 import { ensureAuthToken } from "@danypops/vehicle-server/paths";
+import { captureLoadedModules, checkModuleFreshnessAll, ownRuntimeDependencyNames } from "../adoption/module-freshness.ts";
 import { type DaemonServiceInstaller, RealDaemonServiceInstaller, reconcileAllDaemonServices } from "./daemon-service.ts";
 import { generateIndex, indexPath, indexStatus } from "../index/build-index.ts";
 import { catalogStatus, syncCatalog } from "../packages/catalog.ts";
@@ -51,14 +53,34 @@ function configuredIdleBudgetMs(options: StartPackedDaemonOptions): number | und
 	return Number.isFinite(seconds) && seconds >= 0 ? seconds * 1_000 : undefined;
 }
 
+/**
+ * Captured exactly once, here at daemon startup (daemonOptions() itself
+ * runs once per process -- see vehicle-server/daemon.js's own single
+ * `buildApp()` call site) -- see module-freshness.ts's own header comment
+ * for why this specific moment is what makes the later comparison
+ * meaningful: this is the instant this process's own static imports last
+ * actually loaded these files into memory.
+ */
+function captureOwnModuleSnapshot() {
+	const serviceRoot = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+	const packageDirectory = dirname(serviceRoot);
+	const ownPackageJsonPath = join(packageDirectory, "package.json");
+	return captureLoadedModules(packageDirectory, ownRuntimeDependencyNames(ownPackageJsonPath));
+}
+
 export function daemonOptions(options: StartPackedDaemonOptions): StartDaemonOptions {
 	const paths = options.paths ?? resolvePackedPaths();
 	if (options.migrateLegacy ?? options.paths === undefined) migrateLegacyPackedState(paths, legacyPackedStateDirectory());
 	const token = ensureAuthToken(paths.token, "Packed");
 	const reg = options.reg ?? new HttpRegistry();
-	const inst = options.inst ?? new ExecInstaller();
 	const piHome = options.piHome ?? defaultPiHome();
 	const database = openDb(paths.database);
+	const moduleSnapshot = captureOwnModuleSnapshot();
+	// Wires ExecInstaller.update()'s own out-of-range cross-check to the exact
+	// same registry-mirror source of truth the package-update-check task below
+	// already uses via checkUpdates() -- one mirror, two consumers, never two
+	// notions of "the real latest version".
+	const inst = options.inst ?? new ExecInstaller(undefined, piHome, undefined, undefined, undefined, (name) => latestVersion(database, name));
 	const daemonServiceInstaller = options.daemonServiceInstaller ?? new RealDaemonServiceInstaller();
 	const configuredMaintenanceTasks = options.maintenanceTasks ?? [
 		{
@@ -116,7 +138,17 @@ export function daemonOptions(options: StartPackedDaemonOptions): StartDaemonOpt
 		maintenanceTasks,
 		...(idleBudgetMs === undefined ? {} : { idleBudgetMs }),
 		idleTickMs: WATCHDOG_TICK_MS,
-		buildApp: () => createApp({ reg, inst, token, stateDir: paths.stateDirectory, dataDir: dirname(paths.database), piHome, daemonServiceInstaller }),
+		buildApp: () =>
+			createApp({
+				reg,
+				inst,
+				token,
+				stateDir: paths.stateDirectory,
+				dataDir: dirname(paths.database),
+				piHome,
+				daemonServiceInstaller,
+				moduleFreshness: () => checkModuleFreshnessAll(moduleSnapshot),
+			}),
 		onShutdown: () => database.close(),
 	};
 }

package/service/src/daemon/service.ts

@@ -13,6 +13,7 @@ import { registerPackedVehicleOperations } from "./vehicle-registration.ts";
 import { type AdvisoryReport, resolveInstalledVersions, scanInstalledPackages } from "../adoption/advisories.ts";
 import { type CheckReport, type PackageChecker, StaticPackageChecker } from "../adoption/check.ts";
 import { type DoctorReport, runDoctor } from "../adoption/doctor.ts";
+import type { ModuleFreshnessDiagnostic } from "../adoption/module-freshness.ts";
 import { NpmPackVerifier, type PackReport } from "../adoption/pack.ts";
 import { type AdoptionReport, scoreTarget } from "../adoption/score.ts";
 import { buildIndex, indexPath, type PackageIndex, readIndex, writeIndex } from "../index/build-index.ts";
@@ -68,6 +69,15 @@ export interface Deps {
 		apply(manifestPath: string, options?: { prune?: boolean }): Promise<SetupApplyResult>;
 	};
 	daemonServiceInstaller?: DaemonServiceInstaller;
+	/**
+	 * Re-checks this exact running process's own captured startup snapshot
+	 * of its runtime dependencies against their current on-disk state --
+	 * see module-freshness.ts. Sync (a handful of small file stats/reads),
+	 * injected by daemon.ts once at process start; undefined for any Deps
+	 * built without a real running process behind it (a standalone `packed
+	 * doctor` never has a snapshot to compare against at all).
+	 */
+	moduleFreshness?: () => ModuleFreshnessDiagnostic[];
 	piVersion?: { check(options?: { timeoutMs?: number }): Promise<PiVersionReport> };
 	advisories?: { scan(installed: Record<string, string>): Promise<AdvisoryReport> };
 }
@@ -126,7 +136,7 @@ export interface OperationInputs {
 	"package.restart_service": { source: string; approved?: boolean };
 	"package.reconcile_services": { approved?: boolean; projectRoot?: string };
 	"package.remove": { name: string; approved?: boolean };
-	"package.update": { source: string; approved?: boolean };
+	"package.update": { source: string; approved?: boolean; target?: string };
 	"resources.list": { projectRoot?: string };
 	"resources.toggle": { source: string; field: ResourceField; path: string; enabled: boolean; projectRoot?: string; approved?: boolean };
 	"pi.status": Record<string, never>;
@@ -257,6 +267,10 @@ export function createApp(deps: Deps): { fetch: (req: Request) => Promise<Respon
 		description: "Pi package lifecycle daemon",
 	});
 	registerPackedVehicleOperations(vehicleRegistry, executeOperation);
+	// Live from day one: the registry's own gate mirrors whatever mutationApproval already
+	// is on disk at startup, then tracks every /security POST from here on (see below) --
+	// never a fixed per-deployment constant baked in once and forgotten.
+	vehicleRegistry.configureApprovals({ enabled: readSecuritySettings(deps.stateDir).mutationApproval === "always" });
 	const vehicleApp = createVehicleHttpApp({ registry: vehicleRegistry, token: deps.token });
 
 	function authorize(operation: PackageOperation, approved: boolean): Response | undefined {
@@ -294,7 +308,14 @@ export function createApp(deps: Deps): { fetch: (req: Request) => Promise<Respon
 			}
 			const denied = authorize("security.write", body.approved === true);
 			if (denied) return denied;
-			return json(await writeSecuritySettings(deps.stateDir, { mutationApproval: body.mutationApproval as MutationApproval }));
+			const mutationApproval = body.mutationApproval as MutationApproval;
+			const written = await writeSecuritySettings(deps.stateDir, { mutationApproval });
+			// Same live-toggle guarantee the legacy /api/v1/ops transport already had via
+			// readSecuritySettings() being re-read fresh on every request -- the Vehicle
+			// transport's own gate is a stateful in-memory policy, so a change here has to
+			// be pushed to it explicitly instead of being implicitly always-fresh.
+			vehicleRegistry.updateApprovalPolicy({ enabled: mutationApproval === "always" });
+			return json(written);
 		}
 
 		if (path === "/search" && req.method === "GET") {
@@ -486,22 +507,32 @@ export function createApp(deps: Deps): { fetch: (req: Request) => Promise<Respon
 		if (path === "/update" && req.method === "POST") {
 			let source = "";
 			let approved = false;
+			let target: string | undefined;
 			try {
-				const body = (await req.json()) as { source?: unknown; approved?: unknown };
+				const body = (await req.json()) as { source?: unknown; approved?: unknown; target?: unknown };
 				source = String(body.source ?? "");
 				approved = body.approved === true;
+				target = typeof body.target === "string" && body.target.length > 0 ? body.target : undefined;
 			} catch {
 				/* fall through to validation */
 			}
 			if (!SOURCE_RE.test(source)) {
 				return err(400, "invalid source; want a configured npm:, git:, or https package source");
 			}
+			if (target !== undefined && !SOURCE_RE.test(target)) {
+				return err(400, "invalid target; want a configured npm:, git:, or https package source");
+			}
 			const denied = authorize("update", approved);
 			if (denied) return denied;
+			// A successful replace re-identifies the package under `target`, not
+			// `source` -- a daemon-backed package's own service restart (below)
+			// must reconcile against the NEW installed source, never the one that
+			// was just removed.
+			const restartSource = target ?? source;
 			try {
-				const outcome = await deps.inst.update(source, { approved });
-				if (!source.startsWith("npm:") || outcome.alreadyUpToDate) return json({ ok: true, source, ...outcome });
-				const service = await daemonServiceInstaller.restart(piHomeForServiceInstall, source);
+				const outcome = await deps.inst.update(source, { approved, target });
+				if (!restartSource.startsWith("npm:") || outcome.alreadyUpToDate) return json({ ok: true, source, ...outcome });
+				const service = await daemonServiceInstaller.restart(piHomeForServiceInstall, restartSource);
 				if (!service.ok) {
 					if (service.notADaemon) return json({ ok: true, source, ...outcome });
 					return json({ ok: false, source, ...outcome, output: `${outcome.output}\n${service.reason}` });
@@ -598,7 +629,11 @@ export function createApp(deps: Deps): { fetch: (req: Request) => Promise<Respon
 			const value = input as OperationInputs["doctor.run"];
 			if (value.projectRoot !== undefined && (typeof value.projectRoot !== "string" || value.projectRoot.length > 4_096))
 				throw new PackageOperationError("projectRoot must be a string up to 4096 characters", 400);
-			return (await runDoctor(deps.piHome ?? defaultPiHome(), value.projectRoot)) as OperationOutputs[Name];
+			const report = await runDoctor(deps.piHome ?? defaultPiHome(), value.projectRoot);
+			const moduleFreshness = deps.moduleFreshness?.();
+			if (moduleFreshness === undefined) return report as OperationOutputs[Name];
+			const anyStale = moduleFreshness.some((diagnostic) => diagnostic.stale);
+			return { ...report, moduleFreshness, ok: report.ok && !anyStale } as OperationOutputs[Name];
 		}
 		if (op === "package.updates.project") {
 			const value = input as OperationInputs["package.updates.project"];