@danypops/pi-packed 0.21.13 → 0.21.15

package/extension/src/vehicle-tools.ts

@@ -0,0 +1,84 @@
+/**
+ * Projects the daemon's already-registered 29-operation Vehicle surface (see
+ * service/src/daemon/vehicle-registration.ts) onto real Pi tools, under Vehicle Shell curation --
+ * the same registerVehicleTools({ shell }) pattern @danypops/pi-papyrus's registerNotesVehicle uses
+ * (see its extension/src/tools/vehicle-notes-client.ts).
+ *
+ * Read-only permissions ONLY, deliberately: every mutating package operation
+ * (package.install/install_service/restart_service/reconcile_services/update/remove,
+ * setup.apply, package.security.set, resources.toggle) is gated server-side purely by an
+ * `approved` boolean threaded through its own request shape -- see security.ts's
+ * assertPackagePermission(). Vehicle's own operation schema here is passthroughVehicleSchema
+ * (see vehicle-registration.ts), which would hand that same `approved` field to the model as an
+ * ordinary, undocumented-but-guessable parameter it could set itself, bypassing the interactive
+ * ctx.ui.confirm() gate tools.ts's pkg_install/pkg_update/pkg_remove already enforce. Granting
+ * only "packed:read" here (never "packed:write") makes every non-read operation permanently
+ * permission-unsatisfied -- classifyVehicleOperationSafety() resolves that to "blocked" -- so
+ * those tools are registered (visible in tools_list, inspectable via tools_man) but can never
+ * actually activate through this path. Exposing them safely needs a real Vehicle approval gate
+ * (VehicleRegistry.configureApprovals()) wired server-side first, not merely a client-side option
+ * here; until then, package.install/update/remove/etc. keep their own dedicated, human-confirmed
+ * tools in tools.ts, unrelated to this file.
+ *
+ * package.search/package.info are excluded from the projected manifest for the same
+ * one-capability-one-tool reason pkg-tools.md documents for pkg_search/pkg_info themselves --
+ * they already have dedicated, carefully-worded tools; a second "package_search"/"package_info"
+ * doing the identical thing under a different name would only be confusing, not additive.
+ *
+ * Must be called from session_start, not the top-level extension factory: registerVehicleTools()
+ * needs pi.getAllTools()/getActiveTools()/setActiveTools(), which Pi's extension runtime only
+ * exposes once every extension's own factory has resolved (confirmed live in the identical
+ * pi-papyrus/pi-tickets bug -- see index.ts's own session_start wiring).
+ */
+import { createReconnectingVehicleClient } from "@danypops/vehicle-client/daemon-client";
+import { RemoteVehicleClient } from "@danypops/vehicle-client/http";
+import { registerVehicleTools } from "@danypops/vehicle-client-pi";
+import type { VehicleClient, VehicleManifest } from "@danypops/vehicle-core";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { currentVehicleClientTarget } from "./vehicle-target.js";
+
+/** Already covered by their own dedicated, approval-aware tools in tools.ts -- see this file's own doc comment. */
+const EXCLUDED_OPERATIONS = new Set(["package.search", "package.info"]);
+
+function withoutExcludedOperations(client: VehicleClient): VehicleClient {
+	return {
+		...client,
+		async manifest(): Promise<VehicleManifest> {
+			const manifest = await client.manifest();
+			return { ...manifest, operations: manifest.operations.filter((operation) => !EXCLUDED_OPERATIONS.has(operation.name)) };
+		},
+	};
+}
+
+/**
+ * Illustrative starting core set, not fixed -- tune from real usage the same way pi-papyrus's own
+ * CORE_OPERATIONS comment invites. installed/updates/pi.status are the read-only questions a
+ * session asks most often without first needing tools_man ("what's installed", "what's stale",
+ * "is Pi itself up to date"); everything else (catalog, index, check, pack, score, setup.plan,
+ * package.security.get, resources.list, advisories.scan, doctor.run, package.updates.project)
+ * boots inactive, reachable via tools_list/tools_man.
+ */
+const CORE_OPERATIONS = ["package.installed", "package.updates", "pi.status"];
+
+export async function registerPackedVehicle(pi: ExtensionAPI): Promise<void> {
+	const target = currentVehicleClientTarget();
+	if (!target) return;
+	try {
+		const client = withoutExcludedOperations(
+			createReconnectingVehicleClient(async () => {
+				const resolved = currentVehicleClientTarget();
+				if (!resolved) throw new Error("Packed daemon is not running");
+				return new RemoteVehicleClient({ baseUrl: resolved.baseUrl, token: resolved.token });
+			}),
+		);
+		await registerVehicleTools(pi, client, {
+			permissions: ["packed:read"],
+			principal: { id: "pi-packed" },
+			shell: { coreOperations: CORE_OPERATIONS },
+		});
+	} catch {
+		// Daemon state is stale/unreachable -- degrade silently, matching
+		// pi-papyrus's registerNotesVehicle and pi-packed's own natives.updates()
+		// tolerance in index.ts's session_start handler.
+	}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/pi-packed",
-  "version": "0.21.13",
+  "version": "0.21.15",
   "description": "Pi package lifecycle, validation, daemon, tools, profiles, and TUI",
   "type": "module",
   "bin": {
@@ -31,7 +31,7 @@
     "@danypops/packed": "^0.7.0",
     "@danypops/pi-extension-harness": "^0.2.0",
     "@danypops/vehicle-client": "^0.5.2",
-    "@danypops/vehicle-client-pi": "^0.16.9",
+    "@danypops/vehicle-client-pi": "^0.18.4",
     "@danypops/vehicle-core": "^0.12.3",
     "@danypops/vehicle-server": "^0.17.1",
     "jiti": "^2.7.0",

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

@@ -54,6 +54,21 @@ export interface InstallValidator {
 	validate(source: string): Promise<InstallValidationResult>;
 }
 
+/**
+ * Shared with ExecInstaller.install() (the single ad hoc path, which validates then commits
+ * itself) and SetupManager.apply() (the batch path, which validates every package change
+ * concurrently via Installer.validate() before ever calling installOnly() on any of them) --
+ * one formatting rule for "why was this install refused", not two copies that could drift.
+ */
+export function assertInstallValidationOk(validation: InstallValidationResult): void {
+	if (validation.ok) return;
+	const detail = validation.extensions
+		.filter((extension) => !extension.ok)
+		.map((extension) => `${extension.path}: ${extension.message}`)
+		.join("; ");
+	throw new Error(`install refused -- ${detail || validation.message || "extension failed a headless load check"}`);
+}
+
 const DEFAULT_LOAD_TIMEOUT_MS = 8_000;
 const MAX_LOAD_TIMEOUT_MS = 30_000;
 const PACK_TIMEOUT_MS = 30_000;
@@ -81,7 +96,10 @@ interface CommandResult {
 }
 
 async function runCommand(command: string[], cwd: string, timeoutMs: number): Promise<CommandResult> {
-	const proc = Bun.spawn(command, { cwd, stdin: "ignore", stdout: "pipe", stderr: "pipe" });
+	// env explicit, not Bun.spawn's own default-inherited env -- see install.ts's ExecInstaller.run()
+	// for why a runtime process.env mutation (e.g. a caller redirecting Pi's home directory) must be
+	// threaded through explicitly rather than trusted to Bun's own default inheritance.
+	const proc = Bun.spawn(command, { cwd, stdin: "ignore", stdout: "pipe", stderr: "pipe", env: process.env });
 	let timedOut = false;
 	const timer = setTimeout(() => {
 		timedOut = true;

package/service/src/daemon/service.ts

@@ -322,7 +322,23 @@ export function createApp(deps: Deps): { fetch: (req: Request) => Promise<Respon
 			const name = url.searchParams.get("name") ?? "";
 			if (!name) return err(400, "missing name");
 			try {
-				return json(await deps.reg.info(name));
+				const info = await deps.reg.info(name);
+				// The one single-package, user-facing call site (pkg_info / the Find tab's "i"
+				// inspector) -- deliberately NOT inside Registry.info() itself, which every bulk
+				// caller (build-index.ts, score.ts, setup.ts, cli.ts, publish.ts) also shares.
+				// build-index.ts's own doc comment documents a real incident: calling downloads()
+				// per package at catalog scale (thousands of entries) hits npm's downloads API 429s
+				// within minutes -- exactly what baking this into info() itself would reintroduce
+				// for every bulk consumer. One package, on demand, interactively, is a fundamentally
+				// different volume of call than a background catalog scan. Both enrichments are
+				// individually tolerant of their own failure (same rule info()'s own README fetch
+				// already follows) -- a slow or unavailable api.npmjs.org must never fail the whole
+				// inspect.
+				const [modified, downloads] = await Promise.all([
+					deps.reg.modifiedAt?.(name).catch(() => undefined),
+					deps.reg.downloads?.(name).catch(() => undefined),
+				]);
+				return json({ ...info, modified: modified ?? info.modified, downloads: downloads ?? info.downloads });
 			} catch (e) {
 				return err(502, e instanceof Error ? e.message : String(e));
 			}

package/service/src/packages/install.ts

@@ -1,10 +1,21 @@
 /** install.ts — driven adapter: pi CLI mutations via Bun.spawn. */
 
 import { join } from "node:path";
-import { HeadlessInstallValidator, type InstallValidator } from "../adoption/install-validation.ts";
+import type { Logger } from "@danypops/vehicle-server/logging";
+import {
+	assertInstallValidationOk,
+	HeadlessInstallValidator,
+	type InstallValidationResult,
+	type InstallValidator,
+} from "../adoption/install-validation.ts";
+import { createLogger } from "../shared/log.ts";
 import { defaultPiHome, isPinnedNpmSource, readResolvedVersion } from "./installed.ts";
 import type { Installer, UpdateOutcome } from "./package.ts";
 
+function round1(ms: number): number {
+	return Math.round(ms * 10) / 10;
+}
+
 /** Bare npm package name (for `packed remove`). */
 export const NAME_RE = /^(@[A-Za-z0-9._-]+\/)?[A-Za-z0-9._-]+$/;
 
@@ -22,10 +33,27 @@ export class ExecInstaller implements Installer {
 		private piHome = defaultPiHome(),
 		private validator: InstallValidator = new HeadlessInstallValidator(),
 		private npmBin = defaultNpmBin(),
+		/**
+		 * Instrumentation only -- never gates behavior. Each install()/update() call logs one
+		 * "install timing"/"update timing" debug line breaking down where its wall-clock time went
+		 * (validateMs/installMs/reresolveMs, plus totalMs): the real, previously-invisible cost of
+		 * installing/updating several packages one at a time (see SetupManager.apply()'s own
+		 * sequential loop) is dominated by reresolveDependencyTree() -- a FULL `npm install` at
+		 * piHome/npm re-run after every single package, not just the newly touched one. Surfacing
+		 * that split here is what let service/test/perf/multi-install.perf.test.ts quantify it
+		 * against a real daemon instead of guessing from wall-clock totals alone.
+		 */
+		private readonly logger: Logger = createLogger("install"),
 	) {}
 
 	private async run(args: string[]): Promise<string> {
-		const proc = Bun.spawn([this.bin, ...args], { stdout: "pipe", stderr: "pipe" });
+		// env is explicit, not Bun.spawn's own default-inherited env: a caller that redirects Pi's
+		// home via a runtime process.env mutation (e.g. PI_CODING_AGENT_DIR, set after this process
+		// already started -- confirmed live from service/test/perf/multi-install.perf.test.ts) needs
+		// that reflected in the CURRENT process.env object, not whatever snapshot Bun's own default
+		// inheritance captured. Silently missing this sent a real run straight into the developer's
+		// actual ~/.pi/agent instead of the intended isolated temp directory.
+		const proc = Bun.spawn([this.bin, ...args], { stdout: "pipe", stderr: "pipe", env: process.env });
 		const [stdout, stderr] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()]);
 		const out = [stdout.trim(), stderr.trim()].filter(Boolean).join("\n");
 		const code = await proc.exited;
@@ -42,28 +70,70 @@ export class ExecInstaller implements Installer {
 	 * resolution silently walks up to a stale copy nothing wanted. A full
 	 * `npm install` (no args) at piHome/npm is npm's own documented reliable
 	 * fix: it re-resolves the whole tree, not just the last-touched package.
+	 *
+	 * Public (not private) so a batch caller -- see SetupManager.apply() -- can call this ONCE
+	 * after committing every package in a batch via installOnly(), instead of install()/update()
+	 * each calling it once per package. Safe to call as often as today regardless: re-resolving an
+	 * already-consistent tree is a cheap no-op for npm, never itself a source of drift.
 	 */
-	private async reresolveDependencyTree(): Promise<string> {
+	async reresolveDependencyTree(): Promise<string> {
+		const t0 = performance.now();
 		const cwd = join(this.piHome, "npm");
-		const proc = Bun.spawn([this.npmBin, "install"], { cwd, stdout: "pipe", stderr: "pipe" });
+		// See run()'s own comment: env is explicit for the identical reason.
+		const proc = Bun.spawn([this.npmBin, "install"], { cwd, stdout: "pipe", stderr: "pipe", env: process.env });
 		const [stdout, stderr] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()]);
 		const out = [stdout.trim(), stderr.trim()].filter(Boolean).join("\n");
 		const code = await proc.exited;
 		if (code !== 0) throw new Error(`npm install failed to re-resolve the dependency tree at ${cwd} (exit ${code}): ${out || "no output"}`);
+		this.logger.debug("reresolve timing", { reresolveMs: round1(performance.now() - t0) });
 		return out;
 	}
 
-	async install(source: string, options?: { approved?: boolean; local?: boolean }): Promise<string> {
-		const validation = await this.validator.validate(source);
-		if (!validation.ok) {
-			const detail = validation.extensions
-				.filter((extension) => !extension.ok)
-				.map((extension) => `${extension.path}: ${extension.message}`)
-				.join("; ");
-			throw new Error(`install refused -- ${detail || validation.message || "extension failed a headless load check"}`);
-		}
+	/**
+	 * Safe to run CONCURRENTLY across many sources -- see Installer.validate's own doc comment.
+	 * Delegates to whatever InstallValidator this instance was constructed with (real:
+	 * HeadlessInstallValidator, stages into its own throwaway temp dir per call).
+	 */
+	async validate(source: string): Promise<InstallValidationResult> {
+		const t0 = performance.now();
+		const result = await this.validator.validate(source);
+		this.logger.debug("validate timing", { source, validateMs: round1(performance.now() - t0) });
+		return result;
+	}
+
+	/**
+	 * The real `pi install` mutation alone -- no validation (call validate() first; install()
+	 * does both, in order, for a single ad hoc caller), no trailing reresolveDependencyTree() (a
+	 * batch caller defers that to once per batch, not once per package). MUST be awaited
+	 * sequentially across a batch, never run concurrently -- see Installer.installOnly's own doc
+	 * comment for the confirmed settings.json/package.json corruption a naive Promise.all here
+	 * produces.
+	 */
+	async installOnly(source: string, options?: { approved?: boolean; local?: boolean }): Promise<string> {
+		const t0 = performance.now();
 		const output = await this.run(["install", ...(options?.local ? ["-l"] : []), source]);
+		this.logger.debug("installOnly timing", { source, installMs: round1(performance.now() - t0) });
+		return output;
+	}
+
+	async install(source: string, options?: { approved?: boolean; local?: boolean }): Promise<string> {
+		const t0 = performance.now();
+		const validation = await this.validate(source);
+		const validateMs = performance.now() - t0;
+		assertInstallValidationOk(validation);
+		const t1 = performance.now();
+		const output = await this.installOnly(source, options);
+		const installMs = performance.now() - t1;
+		const t2 = performance.now();
 		await this.reresolveDependencyTree();
+		const reresolveMs = performance.now() - t2;
+		this.logger.debug("install timing", {
+			source,
+			validateMs: round1(validateMs),
+			installMs: round1(installMs),
+			reresolveMs: round1(reresolveMs),
+			totalMs: round1(performance.now() - t0),
+		});
 		return output;
 	}
 
@@ -72,10 +142,21 @@ export class ExecInstaller implements Installer {
 	}
 
 	async update(source: string, _options?: { approved?: boolean; local?: boolean }): Promise<UpdateOutcome> {
+		const t0 = performance.now();
 		const pinned = isPinnedNpmSource(source);
 		const previousVersion = readResolvedVersion(this.piHome, source);
+		const t1 = performance.now();
 		const output = await this.run(["update", "--extension", source]);
+		const updateMs = performance.now() - t1;
+		const t2 = performance.now();
 		await this.reresolveDependencyTree();
+		const reresolveMs = performance.now() - t2;
+		this.logger.debug("update timing", {
+			source,
+			updateMs: round1(updateMs),
+			reresolveMs: round1(reresolveMs),
+			totalMs: round1(performance.now() - t0),
+		});
 		const currentVersion = readResolvedVersion(this.piHome, source);
 		// Only trust a "nothing changed" conclusion when we actually read a
 		// real version both before and after (npm source, resolvable in

package/service/src/packages/package.ts

@@ -5,6 +5,13 @@
  * shells out to pi).
  */
 
+// InstallValidationResult is a plain, adapter-neutral DTO (ok/source/extensions/message) --
+// imported type-only (erased at compile time) from the one adapter that currently produces it
+// (HeadlessInstallValidator) rather than duplicating its shape here and risking drift. Installer
+// 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";
+
 export type PackageVerification = "keyword-only" | "manifest" | "conventional";
 
 export interface PackageEvidence {
@@ -30,6 +37,10 @@ export interface Pkg {
 	version: string;
 	description?: string;
 	date?: string;
+	/** From npm's own search API response (each hit already carries this inline -- no extra
+	 * request per result, unlike PkgInfo.downloads, which needs its own dedicated fetch for a
+	 * single already-known package). See HttpRegistry.searchPage(). */
+	downloads?: DownloadObservations;
 	packageEvidence?: PackageEvidence;
 	publication?: PublicationEvidence;
 }
@@ -104,6 +115,30 @@ 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>;
+	/**
+	 * 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
+	 * steps itself and needs none of this; every existing Installer implementation that omits
+	 * these three keeps compiling and behaving exactly as before.
+	 *
+	 * validate() is safe to run CONCURRENTLY across many sources: each call stages into its own
+	 * throwaway temp directory (see HeadlessInstallValidator) with zero shared state between
+	 * packages. installOnly() does the real `pi install` mutation WITHOUT install()'s own
+	 * trailing full-tree reresolve, so a batch caller can defer that to
+	 * reresolveDependencyTree(), called ONCE after every package in the batch instead of once
+	 * per package.
+	 *
+	 * installOnly() itself must stay SEQUENTIAL across a batch, never fanned out the way
+	 * validate() can be: `pi install` does its own non-atomic read-modify-write of both
+	 * settings.json and the npm project's package.json/package-lock.json in the single shared
+	 * piHome, with no locking on either side (confirmed empirically -- three concurrent `pi
+	 * install` calls against one piHome silently lost two of three entries from settings.json
+	 * and npm/package.json, while all three packages' node_modules ended up physically present
+	 * but untracked, exactly the state a later reresolveDependencyTree() would then prune).
+	 */
+	validate?(source: string): Promise<InstallValidationResult>;
+	installOnly?(source: string, options?: { approved?: boolean; local?: boolean }): Promise<string>;
+	reresolveDependencyTree?(): Promise<string>;
 }
 
 export interface InstalledPkg {

package/service/src/public/client.ts

@@ -89,6 +89,35 @@ export function resolvePackedClientPaths(options: PackedPathOptions = {}): Packe
 	return { token: paths.token, handle: paths.handle, serviceDescriptor: paths.serviceDescriptor };
 }
 
+export interface PackedVehicleClientTarget {
+	/** Base URL for the daemon's Vehicle-projected surface (see service.ts's createApp, which mounts
+	 * createVehicleHttpApp() at /vehicle/* on this same port, alongside /api/v1/ops) -- @danypops/
+	 * vehicle-client's RemoteVehicleClient mounts its own /vehicle/manifest, /vehicle/invoke,
+	 * /vehicle/cancel routes under this. */
+	baseUrl: string;
+	token: string;
+}
+
+/**
+ * Narrow surface for a Vehicle-projected operation consumer -- same daemon, same handle file, same
+ * Bearer token every other Packed RPC call already uses (connectPackedClient reads both the same
+ * way). Returns undefined rather than throwing when the daemon has never started -- no handle/token
+ * on disk yet -- matching resolvePushChannelTarget/resolveVehicleClientTarget's own tolerance in
+ * @danypops/papyrus for the identical condition.
+ */
+export function resolveVehicleClientTarget(paths = resolvePackedClientPaths()): PackedVehicleClientTarget | undefined {
+	const handle = readDaemonHandle(paths.handle);
+	if (!handle) return undefined;
+	let token: string;
+	try {
+		token = readFileSync(paths.token, "utf8").trim();
+	} catch {
+		return undefined;
+	}
+	if (!/^[a-f0-9]{64}$/.test(token)) return undefined;
+	return { baseUrl: `http://${handle.host}:${handle.port}`, token };
+}
+
 /** Checks Armada's authoritative desired fleet rather than native descriptor files. */
 function isPackedServiceInstalled(): boolean {
 	return vehicleIsServiceInstalled(SERVICE_NAME, createNodeServiceInstallDeps());

package/service/src/public/protocol.ts

@@ -8,11 +8,17 @@ export interface PublicationEvidence {
 	provenanceUrl?: string;
 	trustedPublisher: "verified" | "not-verified" | "unknown";
 }
+export interface DownloadObservations {
+	weekly?: number;
+	monthly?: number;
+	observedAt: string;
+}
 export interface PackageSummary {
 	name: string;
 	version: string;
 	description?: string;
 	date?: string;
+	downloads?: DownloadObservations;
 	packageEvidence?: PackageEvidence;
 	publication?: PublicationEvidence;
 }

package/service/src/registry/registry.ts

@@ -71,10 +71,20 @@ export class HttpRegistry implements Registry {
 		if (!res.ok) throw new Error(`npm search: HTTP ${res.status}`);
 		const doc = (await res.json()) as {
 			total?: number;
-			objects?: { package?: { name?: string; version?: string; description?: string; date?: string } }[];
+			objects?: {
+				package?: { name?: string; version?: string; description?: string; date?: string };
+				// Already inline on every search hit -- confirmed live against the real registry, no
+				// separate api.npmjs.org/downloads/point/* call needed the way PkgInfo.downloads (one
+				// already-known package) requires. Fetching that per search RESULT would be an N+1
+				// (20 results = 20 extra requests); this is free.
+				downloads?: { weekly?: number; monthly?: number };
+			}[];
 		};
+		const observedAt = new Date().toISOString();
 		const results: Pkg[] = (doc.objects ?? []).flatMap((o) => {
 			const p = o.package;
+			const weekly = boundedCount(o.downloads?.weekly);
+			const monthly = boundedCount(o.downloads?.monthly);
 			return p?.name
 				? [
 						{
@@ -82,6 +92,7 @@ export class HttpRegistry implements Registry {
 							version: boundedString(p.version, 128) ?? "",
 							description: boundedString(p.description, 512),
 							date: boundedString(p.date, 64),
+							...(weekly !== undefined || monthly !== undefined ? { downloads: { weekly, monthly, observedAt } } : {}),
 							packageEvidence: {
 								shape: "keyword-only" as const,
 								verified: false,
@@ -130,6 +141,14 @@ export class HttpRegistry implements Registry {
 			dist?: { unpackedSize?: number; integrity?: string; attestations?: { url?: string; provenance?: unknown } };
 		};
 		const manifestFields = v.pi ? Object.keys(v.pi).filter((key) => ["extensions", "skills", "prompts", "themes"].includes(key)) : [];
+		// Deliberately NOT modified/downloads here -- info() is shared by bulk callers
+		// (build-index.ts, score.ts, setup.ts's resolvePackage, cli.ts, publish.ts), and
+		// build-index.ts's own doc comment documents a real incident: calling downloads() per
+		// package at catalog scale (thousands of entries) hits npm's downloads API 429s within
+		// minutes. Those bulk callers already opt into modifiedAt() explicitly themselves when they
+		// want it, and never call downloads() at all. The single-package, user-facing enrichment
+		// (pkg_info / the Find tab's inspector) lives one layer up, at service.ts's own "package.info"
+		// handler -- the one call site that's genuinely one-package-at-a-time, never bulk.
 		const readme = await this.publishedReadme(encoded);
 		return {
 			name: boundedString(v.name, 214) ?? boundedString(name, 214)!,

package/service/src/setup/setup.ts

@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 import { Type } from "typebox";
 import { Compile } from "typebox/compile";
 import type { Diagnostic } from "../adoption/check.ts";
+import { assertInstallValidationOk } from "../adoption/install-validation.ts";
 import { npmPackageName, readResolvedIntegrity, readResolvedVersion } from "../packages/installed.ts";
 import type { Installer, Registry } from "../packages/package.ts";
 import { writeJsonAtomic } from "../shared/atomic-json.ts";
@@ -644,9 +645,33 @@ export class SetupManager {
 				(item): item is Extract<SetupOperation, { kind: "install-package" | "update-package" }> =>
 					item.kind === "install-package" || item.kind === "update-package",
 			);
-		for (const operation of packageChanges) {
+		// Batch mode requires all three -- see Installer.validate/installOnly/reresolveDependencyTree's
+		// own doc comments. Any Installer missing even one (e.g. a remote daemon proxy that only ever
+		// implements the plain install()) falls all the way back to today's exact per-package install()
+		// loop below, never a partial mix of the two strategies.
+		const batch = this.installer.validate && this.installer.installOnly && this.installer.reresolveDependencyTree;
+		// Phase 1 (batch mode only): validate every package change CONCURRENTLY. Each call stages
+		// into its own throwaway temp directory with zero shared state between packages -- unlike
+		// the actual `pi install` mutation below, which must stay sequential (a real, confirmed
+		// race: concurrent `pi install` calls against one piHome silently lose entries from BOTH
+		// settings.json and npm/package.json, leaving node_modules with untracked "phantom" installs
+		// a later reresolveDependencyTree() would then prune).
+		const validations = batch
+			? await Promise.allSettled(packageChanges.map((operation) => this.installer.validate!(operation.source)))
+			: undefined;
+		// Phase 2: sequential commit -- unavoidable while `pi install` itself owns unlocked,
+		// shared-file mutation of piHome's settings.json and npm project. In batch mode this calls
+		// installOnly() (no per-package reresolve); otherwise the original install() (validates,
+		// installs, AND re-resolves the whole tree, all per package) exactly as before.
+		for (const [index, operation] of packageChanges.entries()) {
 			try {
-				const output = await this.installer.install(operation.source, { local: operation.scope === "project" });
+				const validation = validations?.[index];
+				if (validation?.status === "rejected") throw validation.reason;
+				if (validation?.status === "fulfilled") assertInstallValidationOk(validation.value);
+				const output =
+					batch && this.installer.installOnly
+						? await this.installer.installOnly(operation.source, { local: operation.scope === "project" })
+						: await this.installer.install(operation.source, { local: operation.scope === "project" });
 				outcomes.push({
 					kind: operation.kind,
 					target: operation.source,
@@ -676,6 +701,29 @@ export class SetupManager {
 				};
 			}
 		}
+		// Phase 3 (batch mode only): re-resolve ONCE for the whole batch instead of once per
+		// package. Only reached once every packageChanges entry has already succeeded above (a
+		// failure already returned early) -- never runs on a partially-applied batch.
+		if (batch && this.installer.reresolveDependencyTree && packageChanges.length > 0) {
+			try {
+				await this.installer.reresolveDependencyTree();
+			} catch (error) {
+				return {
+					ok: false,
+					manifestPath: plan.manifestPath,
+					operations: outcomes,
+					reloadRequired: true,
+					diagnostics: [
+						diagnostic(
+							"SETUP_APPLY_FAILED",
+							"error",
+							"reresolveDependencyTree",
+							`batch dependency re-resolution failed after every package installed/updated successfully: ${error instanceof Error ? error.message : String(error)}`,
+						),
+					],
+				};
+			}
+		}
 		const root = dirname(plan.manifestPath);
 		for (const scope of ["global", "project"] as const) {
 			const changes = plan.operations.filter(