@oh-my-pi/pi-utils 15.12.4 → 15.13.1

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 ## [Unreleased]
 
+## [15.13.1] - 2026-06-15
+
+### Added
+
+- Added profile-aware directory helpers and isolated profile state roots, while keeping the install ID shared across profiles.
+- Added a named-profile API to the `dirs` module — `setProfile()`, `getActiveProfile()`, `getProfileRootDir()`, and `normalizeProfileName()` — plus `resolveProfileEnv()`, which selects the active profile from `OMP_PROFILE` (canonical; takes precedence) then `PI_PROFILE` (legacy fallback, consulted only when `OMP_PROFILE` is unset).
+- Added support for a runtime `overrides` map in `RuntimeInstallSpec`, which is now written into generated runtime `package.json` manifests to force dependency pins (including transitive ones) across the runtime tree
+- Added a lightweight loop-phase breadcrumb stack (`pushLoopPhase`/`popLoopPhase`/`currentLoopPhase`, plus `takeRecentLoopPhase` which returns the live phase or the most recently popped one and clears it) so the TUI event-loop watchdog can attribute a main-thread block to the phase that caused it — including a synchronous phase already popped before the watchdog's delayed tick runs ([#2485](https://github.com/can1357/oh-my-pi/issues/2485))
+- Added `FetchWithRetryOptions.timeout` (forwarded to the underlying `fetch` call). `false` disables Bun's native ~300s pre-response timeout; a positive number overrides the ceiling. Bare browser/Node fetch ignores it ([#2422](https://github.com/can1357/oh-my-pi/issues/2422))
+- Added the side-effect-free `@oh-my-pi/pi-utils/worker-host` module (`declareWorkerHostEntry()` / `workerHostEntry()`), extracted from `env` (still re-exported there) so worker spawn sites can resolve the self-dispatching CLI host entry without importing `env`'s side-effecting module graph.
+
+### Fixed
+
+- Fixed profile directory isolation when a profile's agent `.env` customizes directory roots: directory-affecting keys (`XDG_DATA_HOME`/`XDG_STATE_HOME`/`XDG_CACHE_HOME`, and a default-mode `PI_CODING_AGENT_DIR`) are now honored. The `env` loader rebuilds the `dirs` resolver after applying `.env` files (`refreshDirsFromEnv()`), so a profile `.env` that points XDG roots elsewhere no longer leaks state into the home-based config dir.
+- Made `TempDir` cleanup retry transient Windows `EBUSY`/`EPERM`/`ENOTEMPTY` removal failures so tests are less likely to fail when deleting just-used temp directories.
+- Fixed `installRuntimeModuleResolver()` to keep bare requests from runtime-cache modules inside that registered runtime before falling back to host/workspace packages.
+
 ## [15.12.4] - 2026-06-13
 
 ### Fixed
@@ -44,6 +61,7 @@
 - Fixed the `{{join}}` prompt helper joining with a literal two-character `\n` when templates pass `"\n"` as the separator — Handlebars string literals carry no escape processing. The separator now unescapes `\n`/`\t`, matching the `{{#list}}` helper's documented convention (visible as literal `\n` between paths in compaction `<read-files>` lists).
 
 ## [15.10.11] - 2026-06-10
+
 ### Added
 
 - Restored `PI_DEBUG_STARTUP` streaming startup markers: `logger.time` now writes a synchronous `[startup] <op>:start` / `:done` / `:fail` stderr line per phase (independent of `PI_TIMING`), so a startup that hangs hard still names the phase it is stuck in — the `PI_TIMING` tree only prints after startup completes and is structurally unable to diagnose a hang. The CLI runner emits `cli:load:<name>` markers around each lazily-imported command module for the same reason.
@@ -64,6 +82,7 @@
 - `omp <cmd> --help` now loads only the requested command module instead of the entire command table, so an unrelated command whose import graph hangs or crashes can no longer take down every per-command help invocation.
 
 ## [15.10.8] - 2026-06-09
+
 ### Removed
 
 - Removed the exported `hookFetch` API, which previously intercepted `globalThis.fetch` via middleware handlers
@@ -94,7 +113,6 @@
 
 - Added color helpers `colorLuma` (perceptual luma), `relativeLuminance` (WCAG, linearized sRGB), and `hslToHex` to the color utilities. The luminance helpers parse `#rgb`/`#rrggbb` hex and 256-color palette indices, returning `undefined` for unparseable values.
 - Added `peekFileEnds`, a single-open head-and-tail file peek helper that reuses the head bytes for the tail when the file fits the head window.
-
 - Added `peekFileTail`, the tail mirror of `peekFile`: reads up to the last `maxBytes` of a file ending at EOF, reusing the same pooled-buffer strategy (no per-call allocation for small reads).
 
 ## [15.7.3] - 2026-05-31
@@ -111,4 +129,4 @@
 
 ### Added
 
-- Added an XDG-aware tiny-title model cache directory helper for coding-agent local title models.
+- Added an XDG-aware tiny-title model cache directory helper for coding-agent local title models.

package/README.md

@@ -15,7 +15,7 @@ Shared utilities for [oh-my-pi](https://github.com/can1357/oh-my-pi) packages. Z
 | `which` | `$which()` binary lookup with caching |
 | `fetch-retry` | `fetch` with retry/backoff policies |
 | `fs-error` | Errno guards (`isEnoent` and friends) |
-| `env` | Environment plumbing, worker-host entry contract (`workerHostEntry`) |
+| `env` / `worker-host` | Environment plumbing and side-effect-free worker-host entry contract (`workerHostEntry`) |
 | `abortable` / `async` | AbortSignal-aware stream/promise helpers |
 | `peek-file` | Read the first N bytes of a file with pooled buffers |
 | `frontmatter`, `glob`, `mime`, `temp`, `format`, `color`, `snowflake`, `tab-spacing`, `path-tree`, `sanitize-text` | Smaller single-purpose helpers |

package/dist/types/dirs.d.ts

@@ -18,6 +18,24 @@ export declare const CONFIG_DIR_NAME: string;
 export declare const VERSION: string;
 /** Minimum Bun version */
 export declare const MIN_BUN_VERSION: string;
+/**
+ * Normalize and validate a profile name. Returns `undefined` for the implicit
+ * default (empty string, whitespace, or the explicit "default" sentinel) and
+ * throws for syntactically invalid or platform-reserved names.
+ *
+ * Exported so consumers of `@oh-my-pi/pi-utils/dirs` (CLI bootstrap, tests,
+ * downstream tools) can validate user input without re-deriving the rules.
+ */
+export declare function normalizeProfileName(profile: string | undefined): string | undefined;
+/**
+ * Resolve the active profile from the two profile env vars. `OMP_PROFILE` is the
+ * canonical variable and takes precedence; `PI_PROFILE` is the legacy
+ * compatibility fallback, consulted only when `OMP_PROFILE` is undefined. An
+ * explicitly-empty `OMP_PROFILE` therefore selects the default profile rather
+ * than silently inheriting `PI_PROFILE`. Delegates validation/normalization to
+ * {@link normalizeProfileName} (which throws on a syntactically invalid value).
+ */
+export declare function resolveProfileEnv(omp: string | undefined, pi: string | undefined): string | undefined;
 export declare function resolveEquivalentPath(inputPath: string): string;
 export declare function normalizePathForComparison(inputPath: string): string;
 export declare function pathIsWithin(root: string, candidate: string): boolean;
@@ -30,10 +48,36 @@ export declare function setProjectDir(dir: string): void;
 export declare function getConfigDirName(): string;
 /** Get the config agent directory name relative to home (e.g. ".omp/agent" or PI_CONFIG_DIR + "/agent"). */
 export declare function getConfigAgentDirName(): string;
+/**
+ * Rebuild the dirs resolver from the current environment, reusing the profile
+ * resolved at module load. Directory-affecting keys (XDG_*_HOME and, in default
+ * mode, `PI_CODING_AGENT_DIR`) loaded from a profile/agent `.env` only reach
+ * `process.env` *after* this module froze the resolver at import time, so
+ * `env.ts` calls this once after applying its `.env` files. The agent `.env`
+ * location derives from the profile name + home before this runs, so the
+ * rebuild re-reads only the directory vars, never the profile selection. The
+ * `preProfileAgentDirEnv` snapshot is intentionally left untouched.
+ */
+export declare function refreshDirsFromEnv(): void;
 /** Get the config root directory (~/.omp). */
 export declare function getConfigRootDir(): string;
 /** Set the coding agent directory. Creates a fresh resolver, invalidating all cached paths. */
 export declare function setAgentDir(dir: string): void;
+/**
+ * Test-only: reset the pre-profile `PI_CODING_AGENT_DIR` snapshot to whatever
+ * the current environment looks like. Cross-suite test pollution can otherwise
+ * leak a stale snapshot through `setAgentDir` and corrupt `setProfile(undefined)`
+ * restore semantics. Production code MUST NOT call this — the snapshot's
+ * lifecycle is owned by `setAgentDir` / `setProfile` and a runtime caller has
+ * no business clearing it.
+ */
+export declare function __resetProfileSnapshotForTests(): void;
+/** Activate a named profile. Passing undefined or "default" returns to the default profile. */
+export declare function setProfile(profile: string | undefined): void;
+/** Get the active named profile. Undefined means the default profile. */
+export declare function getActiveProfile(): string | undefined;
+/** Resolve the config root that backs a profile without activating it. */
+export declare function getProfileRootDir(profile: string | undefined): string;
 /** Get the agent config directory (~/.omp/agent). */
 export declare function getAgentDir(): string;
 /** Get the project-local config directory (.omp). */
@@ -167,6 +211,11 @@ export declare function getSSHConfigPath(scope: "user" | "project", cwd?: string
  * winner's id). Survives independently of agent state: deleting
  * `~/.omp/agent/` does not regenerate it. Server-side dedup for grievance
  * pushes (and similar telemetry) keys on this id.
+ *
+ * Anchored to the base config root (`~/.omp/install-id`) regardless of the
+ * active profile: install identity is per-install, not per-profile, so every
+ * profile shares one id and the global cache stays correct no matter the
+ * profile / `getInstallId` call order.
  */
 export declare function getInstallId(): string;
 /** Test-only: clear cached install id. Never call from production code. */

package/dist/types/env.d.ts

@@ -1,3 +1,4 @@
+export * from "./worker-host";
 /**
  * Strict shell-identifier shape. Used for dotenv keys we accept into
  * `Bun.env` — those should be referenceable as `$NAME` from POSIX shells,
@@ -53,8 +54,4 @@ export declare function isBunTestRuntime(): boolean;
  * first for cheap fast-path detection.
  */
 export declare function isCompiledBinary(): boolean;
-/** Called by CLI entrypoints whose main module dispatches worker argv selectors. */
-export declare function declareWorkerHostEntry(): void;
-/** Main-module path of the self-dispatching CLI host, or null outside it. */
-export declare function workerHostEntry(): string | null;
 export declare function $flag(name: string, def?: boolean): boolean;

package/dist/types/fetch-retry.d.ts

@@ -43,6 +43,14 @@ export interface FetchWithRetryOptions extends RequestInit {
      * mock during tests.
      */
     fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+    /**
+     * Bun extension forwarded verbatim to the underlying `fetch` call. `false`
+     * disables Bun's native ~300s pre-response timeout (callers that own a
+     * configurable first-event/idle watchdog or an external `AbortSignal`
+     * supply this so the runtime ceiling cannot pre-empt them); a positive
+     * number sets a custom ceiling in ms. Bare browser/Node fetch ignores it.
+     */
+    timeout?: number | false;
 }
 /**
  * Fetch with bounded retries and sensible defaults. Retries on any

package/dist/types/index.d.ts

@@ -10,6 +10,7 @@ export * from "./fs-error";
 export * from "./glob";
 export * from "./json";
 export * as logger from "./logger";
+export * from "./loop-phase";
 export * from "./mermaid-ascii";
 export * from "./mime";
 export * from "./path-tree";

package/dist/types/loop-phase.d.ts

@@ -0,0 +1,10 @@
+export declare function pushLoopPhase(label: string): void;
+export declare function popLoopPhase(): void;
+export declare function currentLoopPhase(): string | undefined;
+/**
+ * Phase to blame for a just-detected loop block: the live top phase if one is
+ * still held, else the most recent phase pushed since the last call. Clears the
+ * recent slot so a block in a later, phase-less interval is not misattributed
+ * to a phase that already finished.
+ */
+export declare function takeRecentLoopPhase(): string | undefined;

package/dist/types/runtime-install.d.ts

@@ -43,6 +43,8 @@ export declare function installRuntimeModuleResolver({ runtimeNodeModules, stubs
 /** Pinned dependency set materialized into a runtime cache directory. */
 export interface RuntimeInstallSpec {
     dependencies: Record<string, string>;
+    /** Version pins forced across the whole runtime tree (bun `overrides`), e.g. dislodging a transitive dep. */
+    overrides?: Record<string, string>;
     /** Packages whose lifecycle scripts bun may run during the install. */
     trustedDependencies?: string[];
 }
@@ -58,6 +60,7 @@ export interface EnsureRuntimeInstalledOptions {
     lockAttempts?: number;
     lockSleepMs?: number;
 }
+export declare function writeRuntimeManifest(runtimeDir: string, install: RuntimeInstallSpec): Promise<void>;
 /**
  * Materialize a pinned dependency set into `runtimeDir` (idempotent,
  * cross-process safe via a lock directory). Returns `runtimeDir`.

package/dist/types/worker-host.d.ts

@@ -0,0 +1,4 @@
+/** Called by CLI entrypoints whose main module dispatches worker argv selectors. */
+export declare function declareWorkerHostEntry(): void;
+/** Main-module path of the self-dispatching CLI host, or null outside it. */
+export declare function workerHostEntry(): string | null;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "15.12.4",
+	"version": "15.13.1",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -31,7 +31,7 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "15.12.4",
+		"@oh-my-pi/pi-natives": "15.13.1",
 		"beautiful-mermaid": "^1.1.3",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",

package/src/dirs.ts

@@ -28,6 +28,102 @@ export const VERSION: string = version;
 /** Minimum Bun version */
 export const MIN_BUN_VERSION: string = engines.bun.replace(/[^0-9.]/g, "");
 
+const PROFILE_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const PROFILE_ENV_KEYS = ["OMP_PROFILE", "PI_PROFILE"] as const;
+
+/**
+ * Names Windows treats as reserved device aliases. Matches the basename
+ * itself as well as any `BASENAME.<anything>` form, because Windows reserves
+ * `CON.foo`/`PRN.txt`/etc. too — using them as a profile name would let
+ * `setProfile` accept the input only for directory creation to fail later
+ * with a confusing `ENOENT`/`EINVAL`. Case-insensitive: NTFS treats `CON`
+ * and `con` identically.
+ */
+const WINDOWS_RESERVED_BASENAME_RE = /^(?:CON|PRN|AUX|NUL|COM[0-9]|LPT[0-9])(?:\..*)?$/i;
+
+/**
+ * Normalize and validate a profile name. Returns `undefined` for the implicit
+ * default (empty string, whitespace, or the explicit "default" sentinel) and
+ * throws for syntactically invalid or platform-reserved names.
+ *
+ * Exported so consumers of `@oh-my-pi/pi-utils/dirs` (CLI bootstrap, tests,
+ * downstream tools) can validate user input without re-deriving the rules.
+ */
+export function normalizeProfileName(profile: string | undefined): string | undefined {
+	const normalized = profile?.trim();
+	if (!normalized || normalized === "default") return undefined;
+	if (
+		normalized === "." ||
+		normalized === ".." ||
+		normalized.endsWith(".") ||
+		!PROFILE_NAME_RE.test(normalized) ||
+		WINDOWS_RESERVED_BASENAME_RE.test(normalized)
+	) {
+		throw new Error(
+			`Invalid OMP profile "${profile}". Profile names must match ${PROFILE_NAME_RE.source}, ` +
+				`cannot be "." or "..", cannot end with ".", and cannot be a Windows reserved device name ` +
+				`(CON, PRN, AUX, NUL, COM0-9, LPT0-9, or any of those with an extension).`,
+		);
+	}
+	return normalized;
+}
+
+/**
+ * Resolve the active profile from the two profile env vars. `OMP_PROFILE` is the
+ * canonical variable and takes precedence; `PI_PROFILE` is the legacy
+ * compatibility fallback, consulted only when `OMP_PROFILE` is undefined. An
+ * explicitly-empty `OMP_PROFILE` therefore selects the default profile rather
+ * than silently inheriting `PI_PROFILE`. Delegates validation/normalization to
+ * {@link normalizeProfileName} (which throws on a syntactically invalid value).
+ */
+export function resolveProfileEnv(omp: string | undefined, pi: string | undefined): string | undefined {
+	return normalizeProfileName(omp !== undefined ? omp : pi);
+}
+
+function getProfileFromEnv(): string | undefined {
+	return resolveProfileEnv(process.env.OMP_PROFILE, process.env.PI_PROFILE);
+}
+
+/**
+ * Module-load profile resolution. Unlike {@link getProfileFromEnv}, an invalid
+ * OMP_PROFILE/PI_PROFILE value does NOT throw here — a bad env var must not
+ * crash a bare `import` of this module with an uncaught stack trace before the
+ * CLI's error handling is in scope. The default profile is used instead; the
+ * CLI re-validates the env (see `runCli` in coding-agent/src/cli.ts) so the
+ * user still gets a clean "Invalid OMP profile" message.
+ */
+function readProfileFromEnvSafe(): string | undefined {
+	try {
+		return getProfileFromEnv();
+	} catch {
+		return undefined;
+	}
+}
+
+function getBaseConfigRoot(): string {
+	return path.join(os.homedir(), getConfigDirName());
+}
+
+function getProfileConfigRoot(profile: string | undefined): string {
+	const root = getBaseConfigRoot();
+	return profile ? path.join(root, "profiles", profile) : root;
+}
+
+function readPiProfileFromEnvSafe(): string | undefined {
+	try {
+		return normalizeProfileName(process.env.PI_PROFILE);
+	} catch {
+		return undefined;
+	}
+}
+
+function getProfileAgentDir(profile: string): string {
+	return path.join(getProfileConfigRoot(profile), "agent");
+}
+
+function isProfileDerivedAgentDir(profile: string | undefined, agentDirEnv: string | undefined): boolean {
+	return profile !== undefined && agentDirEnv === getProfileAgentDir(profile);
+}
 // =============================================================================
 // Project directory
 // =============================================================================
@@ -96,7 +192,8 @@ export function getConfigDirName(): string {
 
 /** Get the config agent directory name relative to home (e.g. ".omp/agent" or PI_CONFIG_DIR + "/agent"). */
 export function getConfigAgentDirName(): string {
-	return `${getConfigDirName()}/agent`;
+	const profile = getActiveProfile();
+	return profile ? path.join(getConfigDirName(), "profiles", profile, "agent") : `${getConfigDirName()}/agent`;
 }
 
 // =============================================================================
@@ -123,29 +220,47 @@ class DirResolver {
 	readonly #rootCache = new Map<string, string>();
 	readonly #agentCache = new Map<string, string>();
 
-	constructor(agentDirOverride?: string) {
-		this.configRoot = path.join(os.homedir(), getConfigDirName());
+	constructor(options: { agentDirOverride?: string; profile?: string } = {}) {
+		const profile = normalizeProfileName(options.profile);
+		this.configRoot = getProfileConfigRoot(profile);
 
 		const defaultAgent = path.join(this.configRoot, "agent");
+		const agentDirOverride = profile ? undefined : options.agentDirOverride;
 		this.agentDir = agentDirOverride ? path.resolve(agentDirOverride) : defaultAgent;
 		const isDefault = this.agentDir === defaultAgent;
 
-		// XDG is a Linux convention. On other platforms, or for non-default
-		// profiles, all categories resolve to the legacy paths.
+		// XDG is a Linux convention. On supported platforms, default profile state
+		// resolves under $XDG_*_HOME/omp once `omp config init-xdg` has migrated
+		// the user's data. Named profiles follow a stricter rule: the XDG choice
+		// is keyed on the profile-specific XDG path, never the base app root.
+		//
+		// Why: if we consulted the base app root for named profiles too, the same
+		// profile could resolve to `~/.omp/profiles/<name>` on first activation
+		// (when no $XDG_*_HOME/omp exists yet) and then silently move to
+		// `$XDG_*_HOME/omp/profiles/<name>` the moment the base appeared, orphaning
+		// the earlier state. Pinning on the profile path means a profile's location
+		// is decided at first activation and stays put until the user explicitly
+		// migrates it (e.g. by mkdir'ing the XDG profile dir).
 		let xdgData: string | undefined;
 		let xdgState: string | undefined;
 		let xdgCache: string | undefined;
 		if ((process.platform === "linux" || process.platform === "darwin") && isDefault) {
 			const resolveIf = (envVar: string) => {
 				const value = process.env[envVar];
-				if (value) {
-					try {
-						const joined = path.join(value, APP_NAME);
-						if (fs.existsSync(joined)) {
-							return joined;
+				if (!value) return undefined;
+				try {
+					const appRoot = path.join(value, APP_NAME);
+					if (profile) {
+						const profilePath = path.join(appRoot, "profiles", profile);
+						if (fs.existsSync(profilePath)) {
+							return profilePath;
 						}
-					} catch {}
-				}
+						return undefined;
+					}
+					if (fs.existsSync(appRoot)) {
+						return appRoot;
+					}
+				} catch {}
 				return undefined;
 			};
 			xdgData = resolveIf("XDG_DATA_HOME");
@@ -190,14 +305,82 @@ class DirResolver {
 	}
 }
 
-let dirs = new DirResolver(process.env.PI_CODING_AGENT_DIR);
+/**
+ * Decide which `PI_CODING_AGENT_DIR` value to capture as the pre-profile
+ * baseline. A value equal to a profile's derived agent dir is profile-derived
+ * (propagated by a parent's `setProfile`), so it must NOT be snapshotted as the
+ * default-mode baseline — otherwise default mode would resolve to the profile's
+ * agent dir. The profile source can be the active profile or a lower-priority
+ * `PI_PROFILE` that was bypassed because `OMP_PROFILE` explicitly selected the
+ * default profile. Returns `undefined` in those cases so reset falls back to the
+ * standard `~/.omp/agent`.
+ */
+function resolvePreProfileAgentDir(
+	profile: string | undefined,
+	agentDirEnv: string | undefined,
+	profileAgentDirSource: string | undefined = profile,
+): string | undefined {
+	return isProfileDerivedAgentDir(profile ?? profileAgentDirSource, agentDirEnv) ? undefined : agentDirEnv;
+}
+
+let activeProfile = readProfileFromEnvSafe();
 
+/**
+ * Resolve the agent-dir override for the current `activeProfile` from the live
+ * environment. A named profile derives its own agent dir (no override); default
+ * mode honors a non-profile `PI_CODING_AGENT_DIR` (see
+ * {@link resolvePreProfileAgentDir}). Shared by the module-load resolver and
+ * {@link refreshDirsFromEnv} so both apply identical logic.
+ */
+function resolveActiveAgentDirOverride(): string | undefined {
+	return activeProfile
+		? undefined
+		: resolvePreProfileAgentDir(undefined, process.env.PI_CODING_AGENT_DIR, readPiProfileFromEnvSafe());
+}
+
+let dirs = new DirResolver({
+	agentDirOverride: resolveActiveAgentDirOverride(),
+	profile: activeProfile,
+});
+/**
+ * Snapshot of `PI_CODING_AGENT_DIR` from before the first named-profile
+ * activation. Reset paths restore this value (or its absence) instead of
+ * unconditionally deleting the env var. Without the snapshot, a process started
+ * with `PI_CODING_AGENT_DIR=/custom` then `setProfile("work")` then
+ * `setProfile(undefined)` would silently lose `/custom` and fall back to
+ * `~/.omp/agent`. Captured at module load — ignoring a profile-derived value
+ * inherited from a parent's `setProfile` (see {@link resolvePreProfileAgentDir})
+ * — and refreshed on `setAgentDir`, since that call is the user explicitly
+ * redefining the baseline.
+ */
+let preProfileAgentDirEnv: string | undefined = resolvePreProfileAgentDir(
+	activeProfile,
+	process.env.PI_CODING_AGENT_DIR,
+	activeProfile ?? readPiProfileFromEnvSafe(),
+);
 // Anchor home for the resolver. Captured at module load to stay stable across
 // test mocks of `os.homedir()`. `getPluginsDir(home)` compares against this so
 // production callers (`home === RESOLVER_HOME`) hit the XDG-aware resolver while
 // tests passing a temp HOME short-circuit to a deterministic path.
 const RESOLVER_HOME = os.homedir();
 
+/**
+ * Rebuild the dirs resolver from the current environment, reusing the profile
+ * resolved at module load. Directory-affecting keys (XDG_*_HOME and, in default
+ * mode, `PI_CODING_AGENT_DIR`) loaded from a profile/agent `.env` only reach
+ * `process.env` *after* this module froze the resolver at import time, so
+ * `env.ts` calls this once after applying its `.env` files. The agent `.env`
+ * location derives from the profile name + home before this runs, so the
+ * rebuild re-reads only the directory vars, never the profile selection. The
+ * `preProfileAgentDirEnv` snapshot is intentionally left untouched.
+ */
+export function refreshDirsFromEnv(): void {
+	dirs = new DirResolver({
+		agentDirOverride: resolveActiveAgentDirOverride(),
+		profile: activeProfile,
+	});
+}
+
 // =============================================================================
 // Root directories
 // =============================================================================
@@ -209,10 +392,74 @@ export function getConfigRootDir(): string {
 
 /** Set the coding agent directory. Creates a fresh resolver, invalidating all cached paths. */
 export function setAgentDir(dir: string): void {
-	dirs = new DirResolver(dir);
+	activeProfile = undefined;
+	dirs = new DirResolver({ agentDirOverride: dir });
 	process.env.PI_CODING_AGENT_DIR = dir;
+	preProfileAgentDirEnv = dir;
+	for (const key of PROFILE_ENV_KEYS) {
+		delete process.env[key];
+	}
 }
 
+/**
+ * Test-only: reset the pre-profile `PI_CODING_AGENT_DIR` snapshot to whatever
+ * the current environment looks like. Cross-suite test pollution can otherwise
+ * leak a stale snapshot through `setAgentDir` and corrupt `setProfile(undefined)`
+ * restore semantics. Production code MUST NOT call this — the snapshot's
+ * lifecycle is owned by `setAgentDir` / `setProfile` and a runtime caller has
+ * no business clearing it.
+ */
+export function __resetProfileSnapshotForTests(): void {
+	preProfileAgentDirEnv = resolvePreProfileAgentDir(
+		activeProfile,
+		process.env.PI_CODING_AGENT_DIR,
+		activeProfile ?? readPiProfileFromEnvSafe(),
+	);
+}
+
+/** Activate a named profile. Passing undefined or "default" returns to the default profile. */
+export function setProfile(profile: string | undefined): void {
+	const next = normalizeProfileName(profile);
+	if (next && !activeProfile) {
+		// First activation of a named profile in this process: snapshot the
+		// current PI_CODING_AGENT_DIR so a later reset can restore the user's
+		// explicit override. Subsequent profile switches keep the original
+		// snapshot — the "pre-profile" baseline is the state before profiles
+		// entered the picture, not the state between two activations.
+		preProfileAgentDirEnv = resolvePreProfileAgentDir(
+			undefined,
+			process.env.PI_CODING_AGENT_DIR,
+			readPiProfileFromEnvSafe(),
+		);
+	}
+	activeProfile = next;
+	if (activeProfile) {
+		dirs = new DirResolver({ profile: activeProfile });
+		process.env.OMP_PROFILE = activeProfile;
+		process.env.PI_PROFILE = activeProfile;
+		process.env.PI_CODING_AGENT_DIR = dirs.agentDir;
+	} else {
+		for (const key of PROFILE_ENV_KEYS) {
+			delete process.env[key];
+		}
+		if (preProfileAgentDirEnv === undefined) {
+			delete process.env.PI_CODING_AGENT_DIR;
+		} else {
+			process.env.PI_CODING_AGENT_DIR = preProfileAgentDirEnv;
+		}
+		dirs = new DirResolver({ agentDirOverride: preProfileAgentDirEnv });
+	}
+}
+
+/** Get the active named profile. Undefined means the default profile. */
+export function getActiveProfile(): string | undefined {
+	return activeProfile;
+}
+
+/** Resolve the config root that backs a profile without activating it. */
+export function getProfileRootDir(profile: string | undefined): string {
+	return getProfileConfigRoot(normalizeProfileName(profile));
+}
 /** Get the agent config directory (~/.omp/agent). */
 export function getAgentDir(): string {
 	return dirs.agentDir;
@@ -534,10 +781,15 @@ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
  * winner's id). Survives independently of agent state: deleting
  * `~/.omp/agent/` does not regenerate it. Server-side dedup for grievance
  * pushes (and similar telemetry) keys on this id.
+ *
+ * Anchored to the base config root (`~/.omp/install-id`) regardless of the
+ * active profile: install identity is per-install, not per-profile, so every
+ * profile shares one id and the global cache stays correct no matter the
+ * profile / `getInstallId` call order.
  */
 export function getInstallId(): string {
 	if (cachedInstallId) return cachedInstallId;
-	const filePath = path.join(getConfigRootDir(), INSTALL_ID_FILE);
+	const filePath = path.join(getBaseConfigRoot(), INSTALL_ID_FILE);
 
 	let observedInvalid = false;
 	try {

package/src/env.ts

@@ -1,7 +1,9 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { getAgentDir, getConfigRootDir } from "./dirs";
+import { getAgentDir, getConfigRootDir, refreshDirsFromEnv } from "./dirs";
+
+export * from "./worker-host";
 
 const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
@@ -117,6 +119,13 @@ for (const file of [projectEnv, agentEnv, piEnv, homeEnv]) {
 	}
 }
 
+// Directory-affecting keys (XDG_*_HOME, and in default mode PI_CODING_AGENT_DIR)
+// may have just arrived from the profile/agent `.env` applied above. The dirs
+// resolver cached its paths at module load — before this file ran — so rebuild
+// it now from the updated env. `getAgentDir()` already located the `.env` from
+// the profile name + home, so this re-reads only the directory vars.
+refreshDirsFromEnv();
+
 /**
  * Intentional re-export of Bun.env.
  *
@@ -172,26 +181,6 @@ export function isCompiledBinary(): boolean {
 	return url.includes("$bunfs") || url.includes("~BUN") || url.includes("%7EBUN");
 }
 
-/**
- * Main-module path declared by self-dispatching CLI entrypoints — entries
- * whose top-level argv handling routes hidden `__omp_*` worker selectors.
- * Worker spawn sites re-enter this module via `new Worker(entry, { argv })`,
- * so every distribution (source, npm bundle, compiled binary) needs exactly
- * one JavaScript entrypoint. Never set under `bun test`, SDK embedding, or
- * standalone package bins — those hosts load worker modules directly.
- */
-let workerHostMain: string | null = null;
-
-/** Called by CLI entrypoints whose main module dispatches worker argv selectors. */
-export function declareWorkerHostEntry(): void {
-	workerHostMain = Bun.main;
-}
-
-/** Main-module path of the self-dispatching CLI host, or null outside it. */
-export function workerHostEntry(): string | null {
-	return workerHostMain;
-}
-
 const TRUTHY: Dict<boolean> = {
 	"1": true,
 	Y: true,

package/src/fetch-retry.ts

@@ -129,6 +129,14 @@ export interface FetchWithRetryOptions extends RequestInit {
 	 * mock during tests.
 	 */
 	fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+	/**
+	 * Bun extension forwarded verbatim to the underlying `fetch` call. `false`
+	 * disables Bun's native ~300s pre-response timeout (callers that own a
+	 * configurable first-event/idle watchdog or an external `AbortSignal`
+	 * supply this so the runtime ceiling cannot pre-empt them); a positive
+	 * number sets a custom ceiling in ms. Bare browser/Node fetch ignores it.
+	 */
+	timeout?: number | false;
 }
 
 const DEFAULT_MAX_DELAY_MS = 60_000;

package/src/index.ts

@@ -10,6 +10,7 @@ export * from "./fs-error";
 export * from "./glob";
 export * from "./json";
 export * as logger from "./logger";
+export * from "./loop-phase";
 export * from "./mermaid-ascii";
 export * from "./mime";
 export * from "./path-tree";

package/src/loop-phase.ts

@@ -0,0 +1,49 @@
+/**
+ * Live event-loop phase breadcrumb. Hot synchronous paths push a short label
+ * before running and pop it after (via `try`/`finally`); the loop watchdog
+ * reads {@link takeRecentLoopPhase} when it detects a block, so a stall is
+ * logged with the work that caused it instead of an opaque "unknown".
+ *
+ * This is deliberately a process-global stack and not part of the logger span
+ * machinery: `main.ts` ends timing spans before the interactive TUI starts, so
+ * `logger.openSpanPath()` is empty in a live session.
+ *
+ * Correctness constraint: each `pushLoopPhase` must be balanced by a
+ * `popLoopPhase` within the SAME synchronous execution (always via `try`/
+ * `finally`). The stack is global and shared, so a label held across an
+ * `await`/async boundary — or interleaved between concurrent tasks — would
+ * misattribute or leak phases. Instrument only synchronous spans; for async
+ * work, push/pop around each synchronous chunk, not across the await.
+ */
+const stack: string[] = [];
+// The most recent label pushed, retained after it is popped. A hot path pushes
+// and pops a phase entirely within one synchronous macrotask, so by the time
+// the watchdog's delayed tick runs the stack is already empty; this slot keeps
+// the culprit available for that one tick. Consumed (cleared) on read so it
+// only attributes the just-elapsed interval.
+let recentPhase: string | undefined;
+
+export function pushLoopPhase(label: string): void {
+	stack.push(label);
+	recentPhase = label;
+}
+
+export function popLoopPhase(): void {
+	stack.pop();
+}
+
+export function currentLoopPhase(): string | undefined {
+	return stack[stack.length - 1];
+}
+
+/**
+ * Phase to blame for a just-detected loop block: the live top phase if one is
+ * still held, else the most recent phase pushed since the last call. Clears the
+ * recent slot so a block in a later, phase-less interval is not misattributed
+ * to a phase that already finished.
+ */
+export function takeRecentLoopPhase(): string | undefined {
+	const phase = stack[stack.length - 1] ?? recentPhase;
+	recentPhase = undefined;
+	return phase;
+}

package/src/runtime-install.ts

@@ -170,6 +170,16 @@ function resolverRegistry(): ResolverRegistration[] {
 	holder[REGISTRY] ??= [];
 	return holder[REGISTRY];
 }
+function pathContains(root: string, candidate: string): boolean {
+	const relative = path.relative(root, candidate);
+	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function parentFilename(parent: unknown): string | null {
+	if (!isRecord(parent)) return null;
+	const filename = parent.filename;
+	return typeof filename === "string" ? filename : null;
+}
 
 export interface RuntimeResolverOptions {
 	/** Absolute path to the runtime cache's `node_modules`. */
@@ -212,7 +222,17 @@ export function installRuntimeModuleResolver({ runtimeNodeModules, stubs = {} }:
 		}
 		const bare = !request.startsWith(".") && !request.startsWith("node:") && !path.isAbsolute(request);
 		if (bare) {
+			const parentFile = parentFilename(parent);
 			for (const registration of resolverRegistry()) {
+				const parentInRuntime = parentFile !== null && pathContains(registration.runtimeNodeModules, parentFile);
+				if (parentInRuntime) {
+					const stub = registration.stubs[request];
+					if (stub) return stub;
+					if (!stockResolved || !pathContains(registration.runtimeNodeModules, stockResolved)) {
+						const fallback = resolveRuntimeModule(registration.runtimeNodeModules, request);
+						if (fallback) return fallback;
+					}
+				}
 				if (stockResolved) {
 					// Correct a stock hit only inside the top-level package the
 					// request names. A hit in a nested node_modules (e.g. tar's
@@ -242,6 +262,8 @@ export function installRuntimeModuleResolver({ runtimeNodeModules, stubs = {} }:
 /** Pinned dependency set materialized into a runtime cache directory. */
 export interface RuntimeInstallSpec {
 	dependencies: Record<string, string>;
+	/** Version pins forced across the whole runtime tree (bun `overrides`), e.g. dislodging a transitive dep. */
+	overrides?: Record<string, string>;
 	/** Packages whose lifecycle scripts bun may run during the install. */
 	trustedDependencies?: string[];
 }
@@ -281,13 +303,14 @@ async function acquireInstallLock(runtimeDir: string, attempts: number, sleepMs:
 	throw new Error(`Timed out waiting for runtime install lock: ${lockDir}`);
 }
 
-async function writeRuntimeManifest(runtimeDir: string, install: RuntimeInstallSpec): Promise<void> {
+export async function writeRuntimeManifest(runtimeDir: string, install: RuntimeInstallSpec): Promise<void> {
 	await fsp.mkdir(runtimeDir, { recursive: true });
 	const manifest: Record<string, unknown> = {
 		private: true,
 		type: "module",
 		dependencies: install.dependencies,
 	};
+	if (install.overrides && Object.keys(install.overrides).length) manifest.overrides = install.overrides;
 	if (install.trustedDependencies?.length) manifest.trustedDependencies = install.trustedDependencies;
 	await Bun.write(path.join(runtimeDir, "package.json"), `${JSON.stringify(manifest, null, "\t")}\n`);
 }

package/src/temp.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import * as fsPromises from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
 
@@ -13,7 +14,7 @@ export class TempDir {
 	}
 
 	static async create(prefix?: string): Promise<TempDir> {
-		return new TempDir(await fs.promises.mkdtemp(normalizePrefix(prefix)));
+		return new TempDir(await fsPromises.mkdtemp(normalizePrefix(prefix)));
 	}
 
 	#removePromise: Promise<void> | null = null;
@@ -30,13 +31,13 @@ export class TempDir {
 		if (this.#removePromise) {
 			return this.#removePromise;
 		}
-		const removePromise = fs.promises.rm(this.#path, { recursive: true, force: true });
+		const removePromise = removeWithRetries(this.#path);
 		this.#removePromise = removePromise;
 		return removePromise;
 	}
 
 	removeSync(): void {
-		fs.rmSync(this.#path, { recursive: true, force: true });
+		removeSyncWithRetries(this.#path);
 		this.#removePromise = Promise.resolve();
 	}
 
@@ -75,3 +76,55 @@ function normalizePrefix(prefix?: string): string {
 	}
 	return prefix;
 }
+
+const kRemoveOptions = { recursive: true, force: true } as const;
+const kRemoveRetries = 4;
+const kRemoveRetryDelayMs = 10;
+const kRetryableRemoveErrorCodes = new Set(["EBUSY", "EPERM", "ENOTEMPTY"]);
+const kSleepBuffer = new Int32Array(new SharedArrayBuffer(4));
+
+async function removeWithRetries(target: string): Promise<void> {
+	for (let attempt = 0; ; attempt++) {
+		try {
+			await fsPromises.rm(target, kRemoveOptions);
+			return;
+		} catch (err) {
+			if (!shouldRetryRemove(err, attempt)) throw err;
+			await Bun.sleep(kRemoveRetryDelayMs);
+		}
+	}
+}
+
+function removeSyncWithRetries(target: string): void {
+	for (let attempt = 0; ; attempt++) {
+		try {
+			fs.rmSync(target, kRemoveOptions);
+			return;
+		} catch (err) {
+			if (!shouldRetryRemove(err, attempt)) throw err;
+			sleepSync(kRemoveRetryDelayMs);
+		}
+	}
+}
+
+function shouldRetryRemove(err: unknown, attempt: number): boolean {
+	return attempt < kRemoveRetries && process.platform === "win32" && isRetryableRemoveError(err);
+}
+
+function isRetryableRemoveError(err: unknown): boolean {
+	return (
+		typeof err === "object" &&
+		err !== null &&
+		"code" in err &&
+		typeof err.code === "string" &&
+		kRetryableRemoveErrorCodes.has(err.code)
+	);
+}
+
+function sleepSync(ms: number): void {
+	if ("sleepSync" in Bun && typeof Bun.sleepSync === "function") {
+		Bun.sleepSync(ms);
+		return;
+	}
+	Atomics.wait(kSleepBuffer, 0, 0, ms);
+}

package/src/worker-host.ts

@@ -0,0 +1,19 @@
+/**
+ * Main-module path declared by self-dispatching CLI entrypoints — entries
+ * whose top-level argv handling routes hidden `__omp_*` worker selectors.
+ * Worker spawn sites re-enter this module via `new Worker(entry, { argv })`,
+ * so every distribution (source, npm bundle, compiled binary) needs exactly
+ * one JavaScript entrypoint. Never set under `bun test`, SDK embedding, or
+ * standalone package bins — those hosts load worker modules directly.
+ */
+let workerHostMain: string | null = null;
+
+/** Called by CLI entrypoints whose main module dispatches worker argv selectors. */
+export function declareWorkerHostEntry(): void {
+	workerHostMain = Bun.main;
+}
+
+/** Main-module path of the self-dispatching CLI host, or null outside it. */
+export function workerHostEntry(): string | null {
+	return workerHostMain;
+}