pi-profile-switch 0.6.0 → 0.7.0

package/bin/pi-profile.ts

@@ -37,10 +37,16 @@ try {
 		console.error(`pi-profile: warning: ${warning}`);
 	}
 	// Stale per-launch instance dirs (dead pid, or no pid past the grace
-	// window) are swept before this launch materializes its own. Directories
-	// holding state pi-profile did not generate are kept and reported instead of
-	// deleted (ADR-0010). Best-effort: sweep errors never block the launch.
-	for (const warning of await sweepStaleInstances()) {
+	// window) are swept before this launch materializes its own. Unrecognized
+	// entries are dispositioned per content scan: kept + reported when they
+	// reference the instance path or cannot be cleared, adopted into the real
+	// agent dir, or deleted on a name conflict (real wins) — all with a stderr
+	// notice (ADR-0012). Best-effort: sweep errors never block the launch.
+	const sweep = await sweepStaleInstances(agentDir);
+	for (const notice of sweep.notices) {
+		console.error(`pi-profile: notice: ${notice}`);
+	}
+	for (const warning of sweep.warnings) {
 		console.error(`pi-profile: warning: ${warning}`);
 	}
 	const generated = await generateRuntimeDir(plan, { agentDir, discovery, projectDir });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-profile-switch",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Named profiles for Pi: reference skills, extensions, MCP servers, and tools per workflow, switched without restarting. Install: npm install -g pi-profile-switch (not pi install).",
   "type": "module",
   "keywords": [

package/src/launcher/runtime-cleanup.ts

@@ -21,19 +21,21 @@
  * PID reuse needs no /proc check: a wrong keep only delays cleanup and
  * self-heals once the reused pid dies.
  *
- * A candidate is deleted only when every entry in it is pi-profile's own: a
- * symlink (the mirror's link into the real agent dir) or a managed generated
- * file. Anything else is state an extension created at runtime, so the
- * directory is kept and reported — the sweep never destroys data it cannot
- * attribute. The check deliberately does NOT consult the real agent dir: a
- * same-named entry there (a seeded `missions`, say) must not turn an
- * instance-local real directory into a deletable one.
+ * A candidate is reclaimed only when every entry in it is pi-profile's own
+ * or has been dispositioned away. Unrecognized entries (state an extension
+ * created at runtime) get one of three dispositions per entry (ADR-0012):
+ * content that references the instance dir's own path, exceeds the scan
+ * budget, or is not a regular file/dir is kept and reported; position-
+ * independent content is renamed into the real agent dir (adopted), or
+ * deleted when the real agent dir already holds that name (real wins — the
+ * conflict window means the instance copy is never the authority). The sweep
+ * never destroys data it cannot attribute.
  *
  * Everything is best-effort: sweep errors never block a launch.
  */
 
 import type { Dirent } from "node:fs";
-import { lstat, readdir, readFile, rm, stat } from "node:fs/promises";
+import { lstat, readdir, readFile, rename, rm, stat } from "node:fs/promises";
 import path from "node:path";
 
 import { MANAGED_INSTANCE_FILES } from "../settings-generator.ts";
@@ -49,6 +51,29 @@ export const NO_PID_GRACE_MS = 10 * 60 * 1000;
  *  may write its own files inside them (e.g. an extension's own config). */
 const MANAGED_DIRS_WITH_RUNTIME_CONTENT = new Set(["extensions"]);
 
+/** Content-scan budget for deciding whether an unrecognized entry is safe to
+ *  adopt (ADR-0012). Over budget → undecidable → keep and warn. The values
+ *  are implementation constants: the contract only fixes "over budget means
+ *  keep". Exported for the tests that pin the over-budget behavior. */
+export const SCAN_MAX_TOTAL_BYTES = 8 * 1024 * 1024;
+export const SCAN_MAX_FILES = 1024;
+
+/** What the sweep does with one unrecognized entry in a candidate dir. */
+type Disposition = "adopt" | "delete" | "keep-warn";
+
+interface EntryDecision {
+	/** Entry name relative to the instance dir. */
+	name: string;
+	disposition: Disposition;
+}
+
+export interface SweepResult {
+	/** Warnings for directories intentionally kept. */
+	warnings: string[];
+	/** One-line notices for entries adopted into or deleted from a candidate. */
+	notices: string[];
+}
+
 function isProcessAlive(pid: number): boolean {
 	try {
 		process.kill(pid, 0);
@@ -59,10 +84,98 @@ function isProcessAlive(pid: number): boolean {
 	}
 }
 
-/** Paths inside `dir` that pi-profile did not generate, relative to `dir`.
- *  `undefined` means the directory could not be inspected — the caller must
- *  treat that as unrecognized rather than as empty. */
-async function unrecognizedEntries(dir: string): Promise<string[] | undefined> {
+/** Scan budget shared across one entry's recursive content scan. */
+interface ScanBudget {
+	bytes: number;
+	files: number;
+	/** Set when a limit is hit or a member cannot be read: undecidable. */
+	exceeded: boolean;
+	/** Set when a member's bytes contain the instance dir's absolute path. */
+	found: boolean;
+}
+
+async function scanContent(entryPath: string, instanceDir: string, budget: ScanBudget): Promise<void> {
+	if (budget.exceeded || budget.found) return;
+	let info;
+	try {
+		info = await lstat(entryPath);
+	} catch {
+		budget.exceeded = true; // Vanished or unreadable mid-scan: undecidable.
+		return;
+	}
+	if (info.isDirectory()) {
+		let members: string[];
+		try {
+			members = await readdir(entryPath);
+		} catch {
+			budget.exceeded = true;
+			return;
+		}
+		for (const member of members) {
+			await scanContent(path.join(entryPath, member), instanceDir, budget);
+			if (budget.exceeded || budget.found) return;
+		}
+		return;
+	}
+	if (!info.isFile()) {
+		// A socket/fifo/device member cannot be read: undecidable.
+		budget.exceeded = true;
+		return;
+	}
+	budget.files += 1;
+	budget.bytes += info.size;
+	if (budget.files > SCAN_MAX_FILES || budget.bytes > SCAN_MAX_TOTAL_BYTES) {
+		budget.exceeded = true;
+		return;
+	}
+	let content: Buffer;
+	try {
+		content = await readFile(entryPath);
+	} catch {
+		budget.exceeded = true;
+		return;
+	}
+	if (content.includes(instanceDir)) budget.found = true;
+}
+
+/** Whether an unrecognized entry must be kept because its content scan says
+ *  so: the content references the instance dir's own path (records like
+ *  pi-subagents ledgers would break if moved), the scan could not finish
+ *  within the budget, or the entry is not a regular file/dir. Only a clean
+ *  negative scan makes the entry eligible for adoption (ADR-0012). */
+export async function mustKeepByContentScan(entryPath: string, instanceDir: string): Promise<boolean> {
+	let info;
+	try {
+		info = await lstat(entryPath);
+	} catch {
+		return true; // Vanished or unreadable: nothing to adopt.
+	}
+	if (!info.isFile() && !info.isDirectory()) return true; // socket/fifo etc.
+	const budget: ScanBudget = { bytes: 0, files: 0, exceeded: false, found: false };
+	await scanContent(entryPath, instanceDir, budget);
+	// Keep unless the scan finished within budget and never saw the path.
+	return budget.exceeded || budget.found;
+}
+
+/** Decides one top-level unrecognized entry: keep when the content scan is
+ *  not a clean negative; otherwise real-wins on a name conflict, adopt when
+ *  the real agent dir is free. A name lookup that fails for reasons other
+ *  than absence is undecidable → keep. */
+async function decideEntry(name: string, entryPath: string, instanceDir: string, agentDir: string): Promise<EntryDecision> {
+	if (await mustKeepByContentScan(entryPath, instanceDir)) return { name, disposition: "keep-warn" };
+	try {
+		await lstat(path.join(agentDir, name));
+		return { name, disposition: "delete" };
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return { name, disposition: "adopt" };
+		return { name, disposition: "keep-warn" };
+	}
+}
+
+/** Unrecognized entry names inside a managed runtime-content directory
+ *  (`extensions/`): reported at pi-profile's boundary, never adopted or
+ *  deleted. `undefined` means the directory could not be inspected. */
+async function unrecognizedNames(dir: string): Promise<string[] | undefined> {
 	let entries: Dirent<string>[];
 	try {
 		entries = await readdir(dir, { withFileTypes: true });
@@ -71,6 +184,41 @@ async function unrecognizedEntries(dir: string): Promise<string[] | undefined> {
 	}
 
 	const found: string[] = [];
+	for (const entry of entries) {
+		const entryPath = path.join(dir, entry.name);
+		let linkStat;
+		try {
+			linkStat = await lstat(entryPath);
+		} catch {
+			continue; // Vanished under us: nothing to protect.
+		}
+		if (linkStat.isSymbolicLink()) continue;
+		if (MANAGED_DIRS_WITH_RUNTIME_CONTENT.has(entry.name) && linkStat.isDirectory()) {
+			const nested = await unrecognizedNames(entryPath);
+			if (nested === undefined) {
+				found.push(entry.name);
+				continue;
+			}
+			found.push(...nested.map((name) => path.join(entry.name, name)));
+			continue;
+		}
+		found.push(entry.name);
+	}
+	return found;
+}
+
+/** Decides every unrecognized entry in `dir`. `undefined` means the directory
+ *  could not be inspected — the caller must treat that as unrecognized rather
+ *  than as empty. */
+async function classifyUnrecognized(dir: string, agentDir: string): Promise<EntryDecision[] | undefined> {
+	let entries: Dirent<string>[];
+	try {
+		entries = await readdir(dir, { withFileTypes: true });
+	} catch {
+		return undefined;
+	}
+
+	const decisions: EntryDecision[] = [];
 	for (const entry of entries) {
 		const entryPath = path.join(dir, entry.name);
 		let linkStat;
@@ -82,24 +230,26 @@ async function unrecognizedEntries(dir: string): Promise<string[] | undefined> {
 		// Symlinks only point at the real agent dir and hold no data of their own.
 		if (linkStat.isSymbolicLink()) continue;
 		if (!MANAGED_INSTANCE_FILES.has(entry.name)) {
-			found.push(entry.name);
+			decisions.push(await decideEntry(entry.name, entryPath, dir, agentDir));
 			continue;
 		}
 		if (MANAGED_DIRS_WITH_RUNTIME_CONTENT.has(entry.name) && linkStat.isDirectory()) {
-			const nested = await unrecognizedEntries(entryPath);
+			const nested = await unrecognizedNames(entryPath);
 			if (nested === undefined) {
-				found.push(entry.name);
+				decisions.push({ name: entry.name, disposition: "keep-warn" });
 				continue;
 			}
-			found.push(...nested.map((name) => path.join(entry.name, name)));
+			for (const name of nested) decisions.push({ name: path.join(entry.name, name), disposition: "keep-warn" });
 		}
 	}
-	return found;
+	return decisions;
 }
 
-/** Reclaims `dir` if it is both dead and free of unrecognized entries.
- *  Returns the warnings for the cases where it was intentionally kept. */
-async function sweepEntry(dir: string): Promise<string[]> {
+/** Reclaims `dir` if it is both dead and free of unrecognized entries, after
+ *  dispositioning those entries (ADR-0012). Appends notices for adopted and
+ *  deleted entries to `notices`; returns the warnings for the cases where the
+ *  directory was intentionally kept. */
+async function sweepEntry(dir: string, agentDir: string, notices: string[]): Promise<string[]> {
 	let pid: number | undefined;
 	try {
 		const raw = await readFile(path.join(dir, "pid"), "utf8");
@@ -116,15 +266,43 @@ async function sweepEntry(dir: string): Promise<string[]> {
 		if (Date.now() - info.mtimeMs <= NO_PID_GRACE_MS) return [];
 	}
 
-	const unrecognized = await unrecognizedEntries(dir);
-	if (unrecognized === undefined) {
+	const decisions = await classifyUnrecognized(dir, agentDir);
+	if (decisions === undefined) {
 		return [
 			`${dir} was not reclaimed: it could not be inspected (permissions?). Check its contents and delete it manually.`,
 		];
 	}
-	if (unrecognized.length > 0) {
+
+	const kept: string[] = [];
+	for (const decision of decisions) {
+		if (decision.disposition === "keep-warn") {
+			kept.push(decision.name);
+			continue;
+		}
+		const entryPath = path.join(dir, decision.name);
+		if (decision.disposition === "adopt") {
+			try {
+				await rename(entryPath, path.join(agentDir, decision.name));
+				notices.push(`adopted ${decision.name} from ${dir} into the real agent dir (${agentDir}); it is mirrored on the next launch`);
+				continue;
+			} catch {
+				kept.push(decision.name); // Best-effort: keep rather than destroy.
+				continue;
+			}
+		}
+		// delete: the real agent dir already holds this name (real wins, no
+		// content comparison — ADR-0012).
+		try {
+			await rm(entryPath, { recursive: true, force: true });
+			notices.push(`deleted ${decision.name} from ${dir}: the real agent dir already holds that name`);
+		} catch {
+			kept.push(decision.name);
+		}
+	}
+
+	if (kept.length > 0) {
 		return [
-			`${dir} was not reclaimed: it holds state pi-profile did not generate (${unrecognized.join(", ")}). ` +
+			`${dir} was not reclaimed: it holds state pi-profile did not generate (${kept.join(", ")}). ` +
 				`Move that state into the real agent dir (it is mirrored on the next launch), or point the extension that ` +
 				`created it at a fixed path via that extension's own configuration, then delete ${dir}.`,
 		];
@@ -135,16 +313,19 @@ async function sweepEntry(dir: string): Promise<string[]> {
 }
 
 /** Deletes stale instance dirs under the instances root and returns the
- *  warnings for directories it deliberately kept. Never throws. */
-export async function sweepStaleInstances(): Promise<string[]> {
+ *  warnings for directories it deliberately kept plus the notices for entries
+ *  it adopted or deleted. `agentDir` is the real agent dir that adopted
+ *  entries move into and name conflicts resolve against. Never throws. */
+export async function sweepStaleInstances(agentDir: string): Promise<SweepResult> {
 	const warnings: string[] = [];
+	const notices: string[] = [];
 	const root = getInstancesRootDir();
 
 	let entries: string[];
 	try {
 		entries = await readdir(root);
 	} catch {
-		return warnings; // No instances root yet: nothing to sweep.
+		entries = []; // No instances root yet: nothing to sweep.
 	}
 
 	for (const entry of entries) {
@@ -155,11 +336,11 @@ export async function sweepStaleInstances(): Promise<string[]> {
 		const dir = path.join(root, entry);
 		try {
 			if (!(await stat(dir)).isDirectory()) continue;
-			warnings.push(...(await sweepEntry(dir)));
+			warnings.push(...(await sweepEntry(dir, agentDir, notices)));
 		} catch {
 			// Best-effort: one bad entry must not stop the sweep or the launch.
 		}
 	}
 
-	return warnings;
+	return { warnings, notices };
 }