pi-profile-switch 0.4.8 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | [中文](README.zh-CN.md)
 
-Named profiles for [Pi](https://github.com/badlogic/pi-mono). A profile is a named capability bundle you define: skills, extensions, MCP servers, tools (including tools exposed by MCP servers and extensions), model defaults, and extra system-prompt instructions. Switch bundles inside a running Pi session — no restart.
+Named profiles for [Pi](https://github.com/badlogic/pi-mono). A profile is a named set of resources you define: skills, extensions, MCP servers, tools (including tools exposed by MCP servers and extensions), model defaults, and extra system-prompt instructions. Switch profiles inside a running Pi session — no restart.
 
 ## Install
 

package/bin/pi-profile.ts

@@ -16,7 +16,7 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { ExtensionError } from "../src/extension-discovery.ts";
 import { parseLauncherArgs } from "../src/launcher/args.ts";
 import { UnknownProfileError, resolveInitialProfile } from "../src/launcher/initial-profile.ts";
-import { sweepStaleRuntimeDirs } from "../src/launcher/runtime-cleanup.ts";
+import { sweepStaleInstances } from "../src/launcher/runtime-cleanup.ts";
 import { spawnPi } from "../src/launcher/spawn.ts";
 import { McpConfigError, MissingMcpAdapterError } from "../src/mcp-config.ts";
 import { CatalogError } from "../src/profile-catalog.ts";
@@ -36,10 +36,13 @@ try {
 	for (const warning of warnings) {
 		console.error(`pi-profile: warning: ${warning}`);
 	}
-	// Stale per-launch runtime dirs (dead pid, or no pid past the grace
-	// window) are swept before this launch materializes its own. Best-effort:
-	// sweep errors never block the launch.
-	await sweepStaleRuntimeDirs(agentDir);
+	// 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()) {
+		console.error(`pi-profile: warning: ${warning}`);
+	}
 	const generated = await generateRuntimeDir(plan, { agentDir, discovery, projectSettings, projectDir });
 	process.exitCode = await spawnPi({
 		generated,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-profile-switch",
-  "version": "0.4.8",
+  "version": "0.5.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/extension-discovery.ts

@@ -1,27 +1,34 @@
 /**
  * ExtensionDiscovery: implicit, read-only discovery of selectable extensions
- * (ADR-0006), so profiles can reference extensions without any
+ * (ADR-0007/0008), so profiles can reference extensions without any
  * registration step.
  *
- * Two implicit sources, both Pi-native and side-effect free:
- * - Configured user packages: each package's `package.json#pi.extensions`
- *   declares its extension entry files; the package name (or an alias like
- *   the `npm:` source string) is the profile-facing reference.
- * - Loose extension files: `<agentDir>/extensions/*.{ts,js}` and, for
- *   trusted projects, `<projectDir>/.pi/extensions/*.{ts,js}`, referenced by
- *   filename stem.
+ * Two implicit sources, both resolved by Pi itself:
+ * - Configured packages: `DefaultPackageManager.resolve()` expands each
+ *   package's `package.json#pi.extensions` (files, directories, globs, the
+ *   package's own `+`/`-`/`!` filters, `.gitignore` rules) exactly like the
+ *   spawned pi does at startup. The package name — or an alias such as the
+ *   `npm:` source string — is the profile-facing reference.
+ * - Loose extension files: `<agentDir>/extensions/**` and, for trusted
+ *   projects, `<projectDir>/.pi/extensions/**`, referenced by a path-derived
+ *   ID ("conventions", "guards/review").
  *
- * Discovery never executes extension code and never installs anything: a
- * package contributes entries only for declared files that exist on disk.
+ * This module owns naming, merging, selection, and glob expansion only. Entry
+ * enumeration is Pi's own, so a new Pi convention (or a fix to one) cannot
+ * silently diverge from what the spawned pi actually loads.
+ *
+ * Discovery stays side-effect free: `resolve()` is called with
+ * `onMissing: "skip"`, which never installs and never touches the network,
+ * and extension code is never imported.
  */
 
-import { readdir, readFile, stat } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
 
+import { DefaultPackageManager, SettingsManager, type PackageManager } from "@earendil-works/pi-coding-agent";
 import { minimatch } from "minimatch";
 
 import { isRecord } from "./json-file.ts";
-import type { ConfiguredPackageRoot } from "./settings-generator.ts";
 
 export interface DiscoveredPackage {
 	/** Selectable package name: package.json "name", or the source minus its
@@ -32,12 +39,14 @@ export interface DiscoveredPackage {
 	source: string;
 	/** Absolute install/local root of the package. */
 	root: string;
-	/** Absolute paths of declared `pi.extensions` entries that exist on disk. */
+	/** Absolute paths of the package's enabled extension entries. */
 	entries: string[];
 }
 
 export interface DiscoveredLocalExtension {
-	/** Selectable ID: the filename stem ("conventions" for conventions.ts). */
+	/** Selectable ID: the path under the extensions dir, without the file
+	 *  extension and with a trailing "/index" collapsed ("conventions",
+	 *  "guards/review"). */
 	id: string;
 	entry: string;
 }
@@ -72,7 +81,7 @@ function toPosix(filePath: string): string {
 	return filePath.split(path.sep).join("/");
 }
 
-async function exists(filePath: string): Promise<boolean> {
+async function isFile(filePath: string): Promise<boolean> {
 	try {
 		return (await stat(filePath)).isFile();
 	} catch {
@@ -205,7 +214,7 @@ export class DiscoveredExtensions {
 				const pkgEntries = this.#packageEntries(pkg);
 				if (pkgEntries.length === 0) {
 					throw new ExtensionError(
-						`package "${reference}" declares no extension entries (its pi.extensions files are missing or shadowed by local files)`,
+						`package "${reference}" declares no extension entries (missing on disk, filtered out by its settings package entry, or shadowed by local files)`,
 					);
 				}
 				for (const pkgEntry of pkgEntries) add(pkgEntry);
@@ -220,7 +229,7 @@ export class DiscoveredExtensions {
 				const resolved = reference.startsWith("~/")
 					? path.join(process.env.HOME ?? "", reference.slice(1))
 					: path.resolve(reference);
-				if (!(await exists(resolved))) {
+				if (!(await isFile(resolved))) {
 					throw new ExtensionError(`extension path not found: ${resolved}`);
 				}
 				add({ id: resolved, entry: resolved, origin: "path" });
@@ -233,8 +242,6 @@ export class DiscoveredExtensions {
 	}
 }
 
-const LOOSE_FILE_PATTERN = /\.(ts|js)$/;
-
 /** Derives a package name from its source string when package.json is
  *  unreadable: strips the npm:/git:/github: prefix and any version spec
  *  (scoped names keep their "@scope/" prefix). */
@@ -252,93 +259,141 @@ export function packageNameFromSource(source: string): string {
 	return name;
 }
 
-/** Reads one installed package's declared extension entries. Packages
- *  without a readable package.json or without `pi.extensions` contribute
- *  nothing (skills-only packages are the common case). Declared entries
- *  missing on disk are skipped — the spawned pi reports load errors itself. */
-async function readPackageExtensions(pkg: ConfiguredPackageRoot): Promise<DiscoveredPackage | undefined> {
-	if (pkg.root === undefined) return undefined;
-	let manifest: unknown;
-	try {
-		manifest = JSON.parse(await readFile(path.join(pkg.root, "package.json"), "utf8"));
-	} catch {
-		return undefined; // not installed yet or unreadable — nothing selectable
-	}
-	if (!isRecord(manifest)) return undefined;
-	const pi = manifest.pi;
-	const declared =
-		isRecord(pi) && Array.isArray(pi.extensions) ? pi.extensions.filter((e): e is string => typeof e === "string") : [];
-	if (declared.length === 0) return undefined;
-	const entries: string[] = [];
-	for (const rel of declared) {
-		const entry = path.resolve(pkg.root, rel);
-		if (await exists(entry)) entries.push(entry);
-	}
-	if (entries.length === 0) return undefined;
-	const name = typeof manifest.name === "string" && manifest.name.length > 0 ? manifest.name : packageNameFromSource(pkg.source);
-	return { name, source: pkg.source, root: pkg.root, entries };
+/** Selectable ID for a loose extension file: its path under the extensions
+ *  dir without the file extension, with a trailing "/index" collapsed so a
+ *  directory-style extension is referenced by its directory name. */
+function looseId(filePath: string, extensionsDir: string): string {
+	const rel = toPosix(path.relative(extensionsDir, filePath));
+	const collapsed = rel.replace(/(?:^|\/)index\.(ts|js)$/, "");
+	const base = collapsed === "" ? rel : collapsed;
+	return base.replace(/\.(ts|js)$/, "");
 }
 
-/** Lists loose extension files in one directory; missing dir → empty.
- *  A `.ts`/`.js` stem pair resolves to the `.ts` file (Pi's convention:
- *  TypeScript sources are the canonical form) and is reported, not silent. */
-async function scanLooseDir(dir: string, warnings: string[]): Promise<DiscoveredLocalExtension[]> {
-	let files: string[];
+/** Reads a package's display name from its manifest, falling back to the
+ *  source string when the manifest is missing or has no name. */
+async function readPackageName(root: string, source: string): Promise<string> {
 	try {
-		files = (await readdir(dir)).filter((name) => LOOSE_FILE_PATTERN.test(name));
+		const manifest: unknown = JSON.parse(await readFile(path.join(root, "package.json"), "utf8"));
+		if (isRecord(manifest) && typeof manifest.name === "string" && manifest.name.length > 0) return manifest.name;
 	} catch {
-		return [];
-	}
-	const byStem = new Map<string, string>();
-	for (const name of files.sort()) {
-		const stem = name.replace(LOOSE_FILE_PATTERN, "");
-		const full = path.join(dir, name);
-		const existing = byStem.get(stem);
-		if (existing !== undefined) {
-			if (!existing.endsWith(".ts") && name.endsWith(".ts")) {
-				warnings.push(`extension "${stem}" exists as both .ts and .js in ${dir}; the .ts file is used`);
-				byStem.set(stem, full);
-			}
-			continue;
-		}
-		byStem.set(stem, full);
+		// Not installed (a skipped source) or unreadable — derive from source.
 	}
-	return [...byStem.entries()].map(([id, entry]) => ({ id, entry }));
+	return packageNameFromSource(source);
 }
 
-export async function discoverImplicitExtensions(options: {
+export interface DiscoverExtensionsOptions {
+	/** Project working directory (Pi's cwd). */
+	cwd: string;
+	/** The user's real agent dir (e.g. ~/.pi/agent). */
 	agentDir: string;
-	/** Configured user-scope packages with resolved roots (launcher discovery). */
-	packages: ConfiguredPackageRoot[];
-	/** Trusted project dir; untrusted projects are never scanned. */
-	projectDir?: string;
-}): Promise<ImplicitExtensionDiscovery> {
+	/**
+	 * Whether the project at `cwd` is trusted (the launcher's trust check).
+	 * Untrusted projects contribute nothing: no project settings packages, no
+	 * `.pi/extensions` files. Defaults to false.
+	 */
+	projectTrusted?: boolean;
+}
+
+/** Builds the Pi package manager that owns discovery for one cwd/agentDir. */
+function createPackageManager(options: DiscoverExtensionsOptions): PackageManager {
+	const settingsManager = SettingsManager.create(options.cwd, options.agentDir, {
+		projectTrusted: options.projectTrusted ?? false,
+	});
+	return new DefaultPackageManager({
+		cwd: options.cwd,
+		agentDir: options.agentDir,
+		settingsManager,
+	});
+}
+
+interface PackageGroup {
+	source: string;
+	root: string;
+	entries: string[];
+	/** Some declared entry exists on disk, even if all are disabled — keeps
+	 *  "package is filtered out" distinguishable from "package has no
+	 *  extensions". */
+	known: boolean;
+}
+
+/** Runs Pi's own resolution once and classifies the result into pi-profile's
+ *  selectable model. */
+async function resolveImplicit(packageManager: PackageManager, agentDir: string): Promise<ImplicitExtensionDiscovery> {
 	const warnings: string[] = [];
+	// `skip` is the API's read-only mode: missing sources are reported as
+	// absent instead of triggering an install (no network, no mutation).
+	const resolved = await packageManager.resolve(async () => "skip");
+	// Sort for deterministic IDs and ordering: Pi preserves directory read
+	// order, which varies by filesystem.
+	const resources = [...resolved.extensions].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+
+	const groups = new Map<string, PackageGroup>();
+	const userLoose = new Map<string, DiscoveredLocalExtension>();
+	const projectLoose = new Map<string, DiscoveredLocalExtension>();
+
+	for (const resource of resources) {
+		const { source, scope, origin, baseDir } = resource.metadata;
+		if (origin === "package") {
+			// Project-scope packages install under the project's .pi/npm, which
+			// generated global-scope settings cannot reference.
+			if (scope === "project") continue;
+			if (baseDir === undefined) continue;
+			const group = groups.get(source) ?? { source, root: baseDir, entries: [], known: false };
+			// A local source with no manifest and no convention dir resolves to
+			// the directory itself; the loader imports paths verbatim, so it is
+			// not selectable and must not be advertised.
+			if (await isFile(resource.path)) {
+				group.known = true;
+				if (resource.enabled && !group.entries.includes(resource.path)) group.entries.push(resource.path);
+			}
+			groups.set(source, group);
+			continue;
+		}
+		// Settings-declared paths (`extensions: [...]`) are already concrete
+		// files, so profiles reference them directly instead of through a
+		// derived ID; only auto-discovered directory contents become IDs.
+		if (!resource.enabled || source !== "auto") continue;
+		const extensionsDir = path.join(baseDir ?? agentDir, "extensions");
+		const id = looseId(resource.path, extensionsDir);
+		const target = scope === "project" ? projectLoose : userLoose;
+		const existing = target.get(id);
+		if (existing === undefined) {
+			target.set(id, { id, entry: resource.path });
+			continue;
+		}
+		// Pi reports a `.ts`/`.js` stem pair as two entries; keep its
+		// TypeScript-first convention, but say so instead of silently
+		// shadowing the file the loader would pick.
+		if (!existing.entry.endsWith(".ts") && resource.path.endsWith(".ts")) {
+			warnings.push(`extension "${id}" exists as both .ts and .js in ${extensionsDir}; the .ts file is used`);
+			target.set(id, { id, entry: resource.path });
+		}
+	}
 
 	const packages: DiscoveredPackage[] = [];
-	for (const pkg of options.packages) {
-		const discovered = await readPackageExtensions(pkg);
-		if (discovered !== undefined) packages.push(discovered);
+	for (const group of groups.values()) {
+		if (!group.known) continue;
+		packages.push({
+			name: await readPackageName(group.root, group.source),
+			source: group.source,
+			root: group.root,
+			entries: group.entries,
+		});
 	}
 
-	const globalLocal = await scanLooseDir(path.join(options.agentDir, "extensions"), warnings);
-	const merged = new Map<string, DiscoveredLocalExtension>(globalLocal.map((entry) => [entry.id, entry]));
-	if (options.projectDir !== undefined) {
-		// Project loose files override same-ID global ones, mirroring the
-		// project-over-global catalog override convention.
-		for (const entry of await scanLooseDir(path.join(options.projectDir, ".pi", "extensions"), warnings)) {
-			merged.set(entry.id, entry);
-		}
-	}
+	// Project loose files override same-ID global ones, mirroring the
+	// project-over-global catalog override convention.
+	const merged = new Map(userLoose);
+	for (const [id, entry] of projectLoose) merged.set(id, entry);
 
 	return { packages, local: [...merged.values()], warnings };
 }
 
-export async function discoverExtensions(options: {
-	agentDir: string;
-	packages: ConfiguredPackageRoot[];
-	projectDir?: string;
-}): Promise<DiscoveredExtensions> {
+export async function discoverImplicitExtensions(options: DiscoverExtensionsOptions): Promise<ImplicitExtensionDiscovery> {
+	return await resolveImplicit(createPackageManager(options), options.agentDir);
+}
+
+export async function discoverExtensions(options: DiscoverExtensionsOptions): Promise<DiscoveredExtensions> {
 	const raw = await discoverImplicitExtensions(options);
 	return new DiscoveredExtensions(raw.packages, raw.local, raw.warnings);
 }

package/src/launcher/discovery.ts

@@ -54,10 +54,12 @@ export async function discoverLauncherResources(
 		.map((pkg) => ({ source: pkg.source, root: resolvePackageRoot(pkg.source, pkg.installedPath, context.agentDir) }));
 	const [skills, extensions] = await Promise.all([
 		discoverSkills(context),
+		// Extension discovery resolves through Pi's own package manager, so it
+		// only needs the same cwd/agentDir/trust inputs as skill discovery.
 		discoverExtensions({
+			cwd: context.cwd,
 			agentDir: context.agentDir,
-			packages: configured,
-			projectDir: context.projectTrusted ? context.cwd : undefined,
+			projectTrusted: context.projectTrusted,
 		}),
 	]);
 	return { skills, packages: configured, extensions };

package/src/launcher/initial-profile.ts

@@ -31,7 +31,7 @@ export class UnknownProfileError extends Error {
 	}
 }
 
-/** Zero-match glob references surface as launch warnings (ADR-0006):
+/** Zero-match glob references surface as launch warnings (ADR-0009):
  *  visible, but never blocking — globs re-expand on every resolution. */
 function unmatchedWarnings(plan: ActivationPlan): string[] {
 	return (plan.unmatched ?? []).map(

package/src/launcher/runtime-cleanup.ts

@@ -1,35 +1,54 @@
 /**
- * RuntimeCleanup: sweeps stale per-launch runtime directories at startup.
+ * InstanceCleanup: sweeps stale per-launch instance directories at startup.
  *
- * The generated agent dirs under `<agentDir>/pi-profile/runtime/launch-*`
- * (ADR-0005) would otherwise accumulate forever. Startup sweep is the ONLY
- * cleanup mechanism by design: any exit — graceful, signal, SIGKILL, power
- * loss — kills the child pid, so the next launch's sweep converges. There is
- * no exit-time deletion; it would only buy immediacy at the cost of deletion
- * logic on the signal path.
+ * Every launch materializes its own instance dir under
+ * `<PI_PROFILE_SWITCH_DIR>/instances/launch-*` (ADR-0010), which would
+ * otherwise accumulate forever. Startup sweep is the ONLY cleanup mechanism by
+ * design: any exit — graceful, signal, SIGKILL, power loss — kills the child
+ * pid, so the next launch's sweep converges. There is no exit-time deletion; it
+ * would only buy immediacy at the cost of deletion logic on the signal path.
  *
- * Liveness token: a `pid` file written by spawnPi into the runtime dir.
- * (Naming the dir after the pid is impossible — the pid does not exist
- * before spawn, and the running process's PI_CODING_AGENT_DIR path is
- * frozen.) Rules per launch-* dir:
+ * Liveness token: a `pid` file written by spawnPi into the instance dir.
+ * (Naming the dir after the pid is impossible — the pid does not exist before
+ * spawn, and the running process's PI_CODING_AGENT_DIR path is frozen.) Rules
+ * per instance dir:
  * - pid file parses and the process is alive (or EPERM) → keep;
- *   ESRCH → delete.
- * - no/unparsable pid file → delete only when the dir mtime is older than
+ *   ESRCH → candidate.
+ * - no/unparsable pid file → candidate only when the dir mtime is older than
  *   NO_PID_GRACE_MS. The grace window guards the concurrent-launch race (a
- *   second launcher between mkdtemp and its pid write must not be reaped);
- *   it also covers pre-feature dirs and post-mkdtemp crashes.
+ *   second launcher between mkdir and its pid write must not be reaped); it
+ *   also covers post-mkdir crashes.
  * 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.
+ *
  * Everything is best-effort: sweep errors never block a launch.
  */
 
-import { readdir, readFile, rm, stat } from "node:fs/promises";
+import type { Dirent } from "node:fs";
+import { lstat, readdir, readFile, rm, stat } from "node:fs/promises";
 import path from "node:path";
 
-/** Grace period for launch dirs without a (parseable) pid file. */
+import { MANAGED_INSTANCE_FILES } from "../settings-generator.ts";
+import { getInstancesRootDir } from "../workspace.ts";
+
+/** Prefix of the directories this module owns under the instances root. */
+const INSTANCE_DIR_PREFIX = "launch-";
+
+/** Grace period for instance dirs without a (parseable) pid file. */
 export const NO_PID_GRACE_MS = 10 * 60 * 1000;
 
+/** Managed directories whose contents are not necessarily generated: a package
+ *  may write its own files inside them (e.g. an extension's own config). */
+const MANAGED_DIRS_WITH_RUNTIME_CONTENT = new Set(["extensions"]);
+
 function isProcessAlive(pid: number): boolean {
 	try {
 		process.kill(pid, 0);
@@ -40,11 +59,47 @@ function isProcessAlive(pid: number): boolean {
 	}
 }
 
-function runtimeRootOf(agentDir: string): string {
-	return path.join(agentDir, "pi-profile", "runtime");
+/** 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> {
+	let entries: Dirent<string>[];
+	try {
+		entries = await readdir(dir, { withFileTypes: true });
+	} catch {
+		return 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.
+		}
+		// 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);
+			continue;
+		}
+		if (MANAGED_DIRS_WITH_RUNTIME_CONTENT.has(entry.name) && linkStat.isDirectory()) {
+			const nested = await unrecognizedEntries(entryPath);
+			if (nested === undefined) {
+				found.push(entry.name);
+				continue;
+			}
+			found.push(...nested.map((name) => path.join(entry.name, name)));
+		}
+	}
+	return found;
 }
 
-async function sweepEntry(dir: string): Promise<void> {
+/** 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[]> {
 	let pid: number | undefined;
 	try {
 		const raw = await readFile(path.join(dir, "pid"), "utf8");
@@ -55,31 +110,56 @@ async function sweepEntry(dir: string): Promise<void> {
 	}
 
 	if (pid !== undefined) {
-		if (!isProcessAlive(pid)) await rm(dir, { recursive: true, force: true });
-		return;
+		if (isProcessAlive(pid)) return [];
+	} else {
+		const info = await stat(dir);
+		if (Date.now() - info.mtimeMs <= NO_PID_GRACE_MS) return [];
 	}
 
-	const info = await stat(dir);
-	if (Date.now() - info.mtimeMs > NO_PID_GRACE_MS) {
-		await rm(dir, { recursive: true, force: true });
+	const unrecognized = await unrecognizedEntries(dir);
+	if (unrecognized === undefined) {
+		return [
+			`${dir} was not reclaimed: it could not be inspected (permissions?). Check its contents and delete it manually.`,
+		];
 	}
+	if (unrecognized.length > 0) {
+		return [
+			`${dir} was not reclaimed: it holds state pi-profile did not generate (${unrecognized.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}.`,
+		];
+	}
+
+	await rm(dir, { recursive: true, force: true });
+	return [];
 }
 
-/** Deletes stale launch dirs under the agent dir's runtime root. Never throws. */
-export async function sweepStaleRuntimeDirs(agentDir: string): Promise<void> {
+/** 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[]> {
+	const warnings: string[] = [];
+	const root = getInstancesRootDir();
+
 	let entries: string[];
 	try {
-		entries = await readdir(runtimeRootOf(agentDir));
+		entries = await readdir(root);
 	} catch {
-		return; // No runtime root yet: nothing to sweep.
+		return warnings; // No instances root yet: nothing to sweep.
 	}
+
 	for (const entry of entries) {
-		if (!entry.startsWith("launch-")) continue;
-		const dir = path.join(runtimeRootOf(agentDir), entry);
+		// Only directories this module generated are candidates. Anything else
+		// under the root — 0.4.x's per-profile dirs included — is not ours to
+		// delete, and is left alone without a warning.
+		if (!entry.startsWith(INSTANCE_DIR_PREFIX)) continue;
+		const dir = path.join(root, entry);
 		try {
-			if ((await stat(dir)).isDirectory()) await sweepEntry(dir);
+			if (!(await stat(dir)).isDirectory()) continue;
+			warnings.push(...(await sweepEntry(dir)));
 		} catch {
 			// Best-effort: one bad entry must not stop the sweep or the launch.
 		}
 	}
+
+	return warnings;
 }

package/src/settings-generator.ts

@@ -3,9 +3,9 @@
  * runtime directory (ADR-0005).
  *
  * Two entry points:
- * - `generateRuntimeDir` (launcher): mkdtemp a fresh runtime dir, write the
- *   files, link state (auth/models/mcp/npm/git/bin; trust.json only for
- *   default), derive env.
+ * - `generateRuntimeDir` (launcher): create a fresh per-launch runtime dir
+ *   under the workspace instances root, write the files, mirror the real
+ *   agent dir as symlinks (trust.json only for default), derive env.
  * - `writeRuntimeFiles` (in-session switch, ticket 05): rewrite
  *   settings.json + pi-profile.json inside the EXISTING runtime dir (the
  *   running process's PI_CODING_AGENT_DIR cannot move), and transition the
@@ -99,6 +99,24 @@ export const MANAGED_INSTANCE_FILES = new Set([
 	"extensions",
 ]);
 
+/** State directories that Pi and its extensions resolve under the agent dir,
+ *  and which therefore appear at runtime rather than at install time. They are
+ *  seeded in the REAL agent dir before mirroring, so the instance gets a
+ *  symlink instead of a private real directory: runtime-created state then
+ *  lands where native Pi puts it, and third-party records never embed an
+ *  instance path (ADR-0010). Adding a name here needs observed evidence that a
+ *  package creates that directory under the agent dir; anything unlisted shows
+ *  up as an unrecognized entry in the sweep (src/launcher/runtime-cleanup.ts). */
+const SEEDED_STATE_DIRS = ["sessions", "missions"] as const;
+
+/** State FILES Pi creates at runtime (same evidence rule as the dirs). They
+ *  cannot be created up front — the content is Pi's, not pi-profile's — so the
+ *  instance gets a symlink into the real agent dir that is deliberately allowed
+ *  to dangle: Pi sees no file, writes through the link, and the real agent dir
+ *  gets the file. A real file left here instead would be unrecognized state and
+ *  would strand credentials in a directory the sweep refuses to delete. */
+const SEEDED_STATE_FILES = ["auth.json", "models-store.json"] as const;
+
 /** Resource dirs rooted at the real agent dir, re-included for the default
  *  profile because PI_CODING_AGENT_DIR moves the discovery root. */
 const RESOURCE_DIR_KINDS = ["skills", "extensions", "prompts", "themes"] as const;
@@ -405,7 +423,7 @@ export async function writeRuntimeFiles(
 					skills: plan.skills.map((skill) => ({ name: skill.name, filePath: skill.filePath })),
 					extensions: plan.extensions,
 				},
-				// Zero-match glob references (ADR-0006) — surfaced by /profile status
+				// Zero-match glob references (ADR-0009) — surfaced by /profile status
 				// so a typo'd glob is visible instead of silently selecting nothing.
 				...(plan.unmatched !== undefined ? { unmatched: plan.unmatched } : {}),
 				...options.planExtras,
@@ -494,9 +512,6 @@ export async function syncAgentSymlinks(agentDir: string, runtimeDir: string): P
 	if (!existsSync(agentDir)) return;
 	if (path.resolve(agentDir) === path.resolve(runtimeDir)) return;
 
-	// Ensure the real sessions directory exists so it is always mirrored
-	await mkdir(path.join(agentDir, "sessions"), { recursive: true });
-
 	// 1. Clean up dangling or obsolete symlinks in runtimeDir
 	try {
 		const runtimeEntries = await readdir(runtimeDir);
@@ -517,7 +532,13 @@ export async function syncAgentSymlinks(agentDir: string, runtimeDir: string): P
 		}
 	} catch {}
 
-	// 2. Mirror files and directories from agentDir to runtimeDir
+	// 2. Seed the state paths this process's Pi will create at runtime, so their
+	// writes land in the real agent dir instead of an instance-local copy
+	// (ADR-0010). Runs after the cleanup above, which would otherwise remove the
+	// deliberately dangling file links.
+	await seedRuntimeState(agentDir, runtimeDir);
+
+	// 3. Mirror files and directories from agentDir to runtimeDir
 	try {
 		const entries = await readdir(agentDir);
 		for (const name of entries) {
@@ -547,13 +568,45 @@ export async function syncAgentSymlinks(agentDir: string, runtimeDir: string): P
 	} catch {}
 }
 
+/** Ensures the runtime state paths exist (or are linked) in the real agent dir
+ *  and the instance. Best-effort: a failure here leaves the path unseeded, and
+ *  the sweep's unrecognized-entry warning names it later. */
+async function seedRuntimeState(agentDir: string, runtimeDir: string): Promise<void> {
+	for (const name of SEEDED_STATE_DIRS) {
+		try {
+			await mkdir(path.join(agentDir, name), { recursive: true });
+		} catch {
+			// Best-effort: the mirror then simply links nothing for this name.
+		}
+	}
+
+	for (const name of SEEDED_STATE_FILES) {
+		const linkPath = path.join(runtimeDir, name);
+		// A real file here belongs to an earlier run of a different layout, and a
+		// link may already point somewhere else: leave both alone rather than
+		// replacing state pi-profile cannot attribute.
+		if (await existsLexical(linkPath)) continue;
+		try {
+			await symlink(path.join(agentDir, name), linkPath);
+		} catch {
+			// Best-effort: Pi then creates the file inside the instance, and the
+			// sweep keeps that directory instead of deleting it silently.
+		}
+	}
+}
+
 export async function generateRuntimeDir(
 	plan: ActivationPlan,
 	options: GenerateOptions,
 ): Promise<GeneratedRuntime> {
 	const { agentDir } = options;
-	const runtimeDir = path.join(getInstancesRootDir(), plan.profile, "agent");
-	await mkdir(runtimeDir, { recursive: true });
+	const runtimeRoot = getInstancesRootDir();
+	await mkdir(runtimeRoot, { recursive: true });
+	// One instance per launch, never reused: PI_CODING_AGENT_DIR is frozen for
+	// the life of the spawned process, so a stable path cannot follow an
+	// in-session switch, and a shared path would make concurrent launches (and
+	// their switches) rewrite each other's files (ADR-0010).
+	const runtimeDir = await mkdtemp(path.join(runtimeRoot, "launch-"));
 
 	await writeRuntimeFiles(runtimeDir, plan, options);
 

package/src/switching/apply-plan.ts

@@ -48,7 +48,7 @@ export interface LaunchPlanFile {
 		skills: Array<{ name: string; filePath: string }>;
 		extensions: Array<{ id: string; entry: string }>;
 	};
-	/** Glob references that matched nothing at resolution (ADR-0006). */
+	/** Glob references that matched nothing at resolution (ADR-0009). */
 	unmatched?: string[];
 	previousResolved?: {
 		skills: string[];

package/src/switching/status.ts

@@ -36,7 +36,7 @@ export interface StatusReport {
 	mcp: { enabled: string[]; disabled: string[]; missing: string[] };
 	/** Glob delta versus the previous activation (prefixed names). */
 	delta?: { added: string[]; removed: string[] };
-	/** Glob references that matched nothing at resolution (ADR-0006). */
+	/** Glob references that matched nothing at resolution (ADR-0009). */
 	unmatched?: string[];
 	conflicts: StatusConflict[];
 }