@linxiraos/pi-utils 1.1.15 → 1.1.17

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@linxiraos/pi-utils",
-	"version": "1.1.15",
+	"version": "1.1.17",
 	"description": "Shared utilities for pi packages",
 	"keywords": [
 		"utilities",
@@ -54,7 +54,7 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@linxiraos/pi-natives": "1.1.15"
+		"@linxiraos/pi-natives": "1.1.17"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/acp/transport.ts

@@ -108,10 +108,15 @@ function createStandardError(
 type Dispatcher = (method: string, params: unknown, notification: boolean) => MaybePromise<unknown>;
 type Pending = { resolve(value: unknown): void; reject(reason: unknown): void };
 
+/** Bound on clean-EOF inbound drain so `closed` cannot hang if a handler never settles. */
+const INBOUND_DRAIN_TIMEOUT_MS = 30_000;
+
 /** Correlated bidirectional JSON-RPC connection. */
 export class RpcConnection {
 	#nextId = 0;
 	#pending = new Map<JsonRpcId, Pending>();
+	#inbound = new Set<Promise<void>>();
+	#openInboundIds = new Set<JsonRpcId>();
 	#writable: WritableStream<AnyMessage>;
 	#writeTail: Promise<void> = Promise.resolve();
 	#abort = new AbortController();
@@ -179,8 +184,9 @@ export class RpcConnection {
 			while (true) {
 				const next = await reader.read();
 				if (next.done) break;
-				void this.#handle(next.value).catch(error => this.close(error));
+				this.#dispatch(next.value);
 			}
+			await this.#drainInbound();
 			this.close();
 		} catch (error) {
 			this.close(error);
@@ -189,6 +195,34 @@ export class RpcConnection {
 		}
 	}
 
+	#dispatch(message: AnyMessage): void {
+		if ("method" in message && "id" in message) this.#openInboundIds.add(message.id);
+		const task = this.#handle(message).catch(error => this.close(error));
+		this.#inbound.add(task);
+		void task.finally(() => this.#inbound.delete(task));
+	}
+
+	async #drainInbound(): Promise<void> {
+		if (this.#inbound.size === 0) return;
+		const drained = Promise.allSettled(this.#inbound).then(() => {});
+		let timer: Timer | undefined;
+		const timedOut = await Promise.race([
+			drained.then(() => false),
+			new Promise<boolean>(resolve => {
+				timer = setTimeout(() => resolve(true), INBOUND_DRAIN_TIMEOUT_MS);
+			}),
+		]);
+		if (timer !== undefined) clearTimeout(timer);
+		if (!timedOut) return;
+		const error = RequestError.internalError(undefined, "Inbound request drain timed out").toErrorResponse();
+		await Promise.allSettled([...this.#openInboundIds].map(id => this.#respond(id, { error })));
+	}
+
+	#respond(id: JsonRpcId, body: { result: unknown } | { error: ErrorResponse }): Promise<void> {
+		if (!this.#openInboundIds.delete(id)) return Promise.resolve();
+		return this.#write({ jsonrpc: "2.0", id, ...body });
+	}
+
 	async #handle(message: AnyMessage): Promise<void> {
 		if ("id" in message && !("method" in message)) {
 			const pending = this.#pending.get(message.id);
@@ -210,13 +244,13 @@ export class RpcConnection {
 		}
 		try {
 			const result = await this.#dispatcher(message.method, message.params, false);
-			await this.#write({ jsonrpc: "2.0", id: message.id, result: result ?? {} });
+			await this.#respond(message.id, { result: result ?? {} });
 		} catch (error) {
 			const protocolError =
 				error instanceof RequestError
 					? error
 					: RequestError.internalError({ details: error instanceof Error ? error.message : String(error) });
-			await this.#write({ jsonrpc: "2.0", id: message.id, error: protocolError.toErrorResponse() });
+			await this.#respond(message.id, { error: protocolError.toErrorResponse() });
 		}
 	}
 }

package/src/async.ts

@@ -1,3 +1,34 @@
+import { scheduler } from "node:timers/promises";
+
+/**
+ * Largest delay `setTimeout` (and `timers/promises` `scheduler.wait`)
+ * accepts without 32-bit signed overflow: larger values wrap and fire
+ * almost immediately instead of sleeping. Chunk day-scale provider waits
+ * (e.g. a monthly quota reset parsed from an error hint) so the full
+ * duration elapses instead of overflowing the timer.
+ */
+export const MAX_TIMER_DELAY_MS = 2_147_483_647;
+
+/**
+ * Abortable sleep for arbitrarily long delays. Waits longer than
+ * {@link MAX_TIMER_DELAY_MS} chunk the sleep into back-to-back timer waits
+ * so no single timer overflows; an abort during any chunk rejects like
+ * `scheduler.wait`.
+ *
+ * Uses a monotonic deadline so a timer that wakes prematurely is re-armed for
+ * the unelapsed duration instead of shortening the requested sleep.
+ */
+export async function sleepLong(delayMs: number, signal?: AbortSignal): Promise<void> {
+	signal?.throwIfAborted();
+	const deadline = performance.now() + delayMs;
+	while (true) {
+		const remaining = deadline - performance.now();
+		if (!(remaining > 0)) return;
+		await scheduler.wait(Math.min(remaining, MAX_TIMER_DELAY_MS), { signal });
+		signal?.throwIfAborted();
+	}
+}
+
 /**
  * Wrap a promise with a timeout and optional abort signal.
  * Rejects with the given error or a new error containing the given message if

package/src/browsers.ts

@@ -1,6 +1,4 @@
-/** Behavior-compatible reimplementation of @puppeteer/browsers' used surface. */
-
-import type * as fs from "node:fs";
+/** Managed Chrome-for-Testing installation with bounded downloads and atomic publication. */
 import * as fsp from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -8,7 +6,6 @@ import { type ArchiveLimits, extractArchive } from "./ar";
 import { withFileLock } from "./file-lock";
 
 const CHROME_FOR_TESTING_BASE_URL = "https://storage.googleapis.com/chrome-for-testing-public";
-const CHROME_METADATA_BASE_URL = "https://googlechromelabs.github.io/chrome-for-testing";
 // Installation is outside browser/Eval operation deadlines, but a stalled CDN
 // must still release the cached install promise and permit a later attempt.
 const DOWNLOAD_TIMEOUT_MS = 5 * 60_000;
@@ -25,15 +22,6 @@ const BROWSER_ARCHIVE_LIMITS: Partial<ArchiveLimits> = {
 	maxInMemorySize: 1024 * 1024 * 1024,
 };
 
-/** Supported browser products. */
-export enum Browser {
-	CHROME = "chrome",
-	CHROMEHEADLESSSHELL = "chrome-headless-shell",
-	CHROMIUM = "chromium",
-	FIREFOX = "firefox",
-	CHROMEDRIVER = "chromedriver",
-}
-
 /** Browser download platform identifiers. */
 export enum BrowserPlatform {
 	LINUX = "linux",
@@ -51,34 +39,6 @@ function requireChromeForTestingPlatform(platform: BrowserPlatform): ChromeForTe
 	return platform;
 }
 
-const BROWSERS = [
-	Browser.CHROME,
-	Browser.CHROMEHEADLESSSHELL,
-	Browser.CHROMIUM,
-	Browser.FIREFOX,
-	Browser.CHROMEDRIVER,
-] as const;
-const BROWSER_PLATFORMS = [
-	BrowserPlatform.LINUX,
-	BrowserPlatform.LINUX_ARM,
-	BrowserPlatform.MAC,
-	BrowserPlatform.MAC_ARM,
-	BrowserPlatform.WIN32,
-	BrowserPlatform.WIN64,
-] as const;
-
-/** Chrome-for-Testing release channel tags accepted by {@link resolveBuildId}. */
-export enum BrowserTag {
-	CANARY = "canary",
-	NIGHTLY = "nightly",
-	BETA = "beta",
-	DEV = "dev",
-	DEVEDITION = "devedition",
-	STABLE = "stable",
-	ESR = "esr",
-	LATEST = "latest",
-}
-
 /** Download progress reported while a browser archive is streamed to disk. */
 export interface BrowserDownloadProgress {
 	downloadedBytes: number;
@@ -87,7 +47,6 @@ export interface BrowserDownloadProgress {
 
 /** Inputs used to locate an installed browser executable. */
 export interface ComputeExecutablePathOptions {
-	browser: Browser;
 	buildId: string;
 	cacheDir: string;
 	platform?: BrowserPlatform;
@@ -99,27 +58,14 @@ export interface InstallOptions extends ComputeExecutablePathOptions {
 	downloadProgressCallback?: (progress: BrowserDownloadProgress) => void;
 }
 
-/** Metadata for one browser installation found in a Puppeteer cache. */
+/** Metadata for a managed Chrome installation in Puppeteer's cache layout. */
 export interface InstalledBrowser {
-	browser: Browser;
 	buildId: string;
 	platform: BrowserPlatform;
 	path: string;
 	executablePath: string;
 }
 
-interface LastKnownGoodVersions {
-	channels: Record<string, { version: string }>;
-}
-
-interface MilestoneVersions {
-	milestones: Record<string, { version: string }>;
-}
-
-interface PatchVersions {
-	builds: Record<string, { version: string }>;
-}
-
 /** Detect the current host's Puppeteer browser platform. */
 export function detectBrowserPlatform(): BrowserPlatform | undefined {
 	const platform = os.platform();
@@ -130,43 +76,8 @@ export function detectBrowserPlatform(): BrowserPlatform | undefined {
 	return undefined;
 }
 
-/** Resolve a Chrome-for-Testing channel, milestone, or build prefix to a full build ID. */
-export async function resolveBuildId(
-	browser: Browser,
-	_platform: BrowserPlatform,
-	tag: string | BrowserTag,
-): Promise<string> {
-	if (browser !== Browser.CHROME && browser !== Browser.CHROMEHEADLESSSHELL && browser !== Browser.CHROMEDRIVER) {
-		return tag;
-	}
-	if (/^\d+\.\d+\.\d+\.\d+$/.test(tag)) return tag;
-
-	const channel = tag === BrowserTag.LATEST ? "Canary" : chromeChannelName(tag);
-	if (channel) {
-		const metadata = await fetchMetadata<LastKnownGoodVersions>("last-known-good-versions.json");
-		const version = metadata.channels[channel]?.version;
-		if (!version) throw new Error(`Chrome channel ${tag} was not found in Chrome-for-Testing metadata`);
-		return version;
-	}
-	if (/^\d+$/.test(tag)) {
-		const metadata = await fetchMetadata<MilestoneVersions>("latest-versions-per-milestone.json");
-		return metadata.milestones[tag]?.version ?? tag;
-	}
-	if (/^\d+\.\d+\.\d+$/.test(tag)) {
-		const metadata = await fetchMetadata<PatchVersions>("latest-patch-versions-per-build.json");
-		return metadata.builds[tag]?.version ?? tag;
-	}
-	return tag;
-}
-
 /** Return the Chrome-for-Testing archive URL for a browser build. */
-export function getDownloadUrl(
-	browser: Browser,
-	platform: BrowserPlatform,
-	buildId: string,
-	baseUrl = CHROME_FOR_TESTING_BASE_URL,
-): URL {
-	if (browser !== Browser.CHROME) throw new Error(`Unsupported browser download: ${browser}`);
+export function getDownloadUrl(platform: BrowserPlatform, buildId: string, baseUrl = CHROME_FOR_TESTING_BASE_URL): URL {
 	const archivePlatform = chromeArchivePlatform(platform);
 	const root = baseUrl.replace(/\/$/, "");
 	return new URL(`${root}/${buildId}/${archivePlatform}/chrome-${archivePlatform}.zip`);
@@ -176,9 +87,8 @@ export function getDownloadUrl(
 export function computeExecutablePath(options: ComputeExecutablePathOptions): string {
 	const detectedPlatform = options.platform ?? detectBrowserPlatform();
 	if (!detectedPlatform) throw new Error("Cannot determine a browser platform for this host");
-	if (options.browser !== Browser.CHROME) throw new Error(`Unsupported browser executable: ${options.browser}`);
 	const platform = requireChromeForTestingPlatform(detectedPlatform);
-	const installDir = installationDir(options.cacheDir, options.browser, platform, options.buildId);
+	const installDir = installationDir(options.cacheDir, platform, options.buildId);
 	switch (platform) {
 		case BrowserPlatform.LINUX:
 			return path.join(installDir, "chrome-linux64", "chrome");
@@ -207,52 +117,14 @@ export function computeExecutablePath(options: ComputeExecutablePathOptions): st
 	}
 }
 
-/** Scan a Puppeteer cache for browser installation directories. */
-export async function getInstalledBrowsers(options: { cacheDir: string }): Promise<InstalledBrowser[]> {
-	const installed: InstalledBrowser[] = [];
-	for (const browser of BROWSERS) {
-		const browserDir = path.join(options.cacheDir, browser);
-		let entries: fs.Dirent[];
-		try {
-			entries = await fsp.readdir(browserDir, { withFileTypes: true });
-		} catch (error) {
-			if (isMissingPath(error)) continue;
-			throw error;
-		}
-		for (const entry of entries) {
-			if (!entry.isDirectory()) continue;
-			const parsed = parseInstallationName(entry.name);
-			if (!parsed) continue;
-			const installPath = path.join(browserDir, entry.name);
-			try {
-				installed.push({
-					browser,
-					buildId: parsed.buildId,
-					platform: parsed.platform,
-					path: installPath,
-					executablePath: computeExecutablePath({
-						browser,
-						buildId: parsed.buildId,
-						cacheDir: options.cacheDir,
-						platform: parsed.platform,
-					}),
-				});
-			} catch {
-				// Other browser products are not part of the surface used by OMP.
-			}
-		}
-	}
-	return installed;
-}
-
 /** Download and unpack Chrome into Puppeteer's existing cache layout. */
 export async function install(options: InstallOptions): Promise<InstalledBrowser> {
 	const platform = options.platform ?? detectBrowserPlatform();
 	if (!platform) throw new Error("Cannot determine a browser platform for this host");
 	const executablePath = computeExecutablePath({ ...options, platform });
-	const installPath = installationDir(options.cacheDir, options.browser, platform, options.buildId);
+	const installPath = installationDir(options.cacheDir, platform, options.buildId);
 	if (await pathExists(executablePath)) {
-		return { browser: options.browser, buildId: options.buildId, platform, path: installPath, executablePath };
+		return { buildId: options.buildId, platform, path: installPath, executablePath };
 	}
 
 	await fsp.mkdir(path.dirname(installPath), { recursive: true });
@@ -267,7 +139,7 @@ export async function install(options: InstallOptions): Promise<InstalledBrowser
 				const stagingPath = path.join(options.cacheDir, `.browser-${nonce}`);
 				try {
 					await downloadArchive(
-						getDownloadUrl(options.browser, platform, options.buildId, options.baseUrl),
+						getDownloadUrl(platform, options.buildId, options.baseUrl),
 						archivePath,
 						options.downloadProgressCallback,
 					);
@@ -284,34 +156,12 @@ export async function install(options: InstallOptions): Promise<InstalledBrowser
 					]);
 				}
 			}
-			return { browser: options.browser, buildId: options.buildId, platform, path: installPath, executablePath };
+			return { buildId: options.buildId, platform, path: installPath, executablePath };
 		},
 		{ retries: Math.ceil(DOWNLOAD_TIMEOUT_MS / 100) + 1, retryDelayMs: 100 },
 	);
 }
 
-function chromeChannelName(tag: string): string | undefined {
-	switch (tag) {
-		case BrowserTag.STABLE:
-			return "Stable";
-		case BrowserTag.BETA:
-			return "Beta";
-		case BrowserTag.DEV:
-			return "Dev";
-		case BrowserTag.CANARY:
-			return "Canary";
-		default:
-			return undefined;
-	}
-}
-
-async function fetchMetadata<T>(filename: string): Promise<T> {
-	const response = await fetch(`${CHROME_METADATA_BASE_URL}/${filename}`, { signal: AbortSignal.timeout(30_000) });
-	if (!response.ok)
-		throw new Error(`Failed to fetch Chrome-for-Testing metadata (${response.status} ${response.statusText})`);
-	return (await response.json()) as T;
-}
-
 function chromeArchivePlatform(platform: BrowserPlatform): string {
 	switch (requireChromeForTestingPlatform(platform)) {
 		case BrowserPlatform.LINUX:
@@ -327,17 +177,8 @@ function chromeArchivePlatform(platform: BrowserPlatform): string {
 	}
 }
 
-function installationDir(cacheDir: string, browser: Browser, platform: BrowserPlatform, buildId: string): string {
-	return path.join(cacheDir, browser, `${platform}-${buildId}`);
-}
-
-function parseInstallationName(name: string): { platform: BrowserPlatform; buildId: string } | undefined {
-	for (const platform of BROWSER_PLATFORMS) {
-		const prefix = `${platform}-`;
-		if (name.startsWith(prefix) && name.length > prefix.length)
-			return { platform, buildId: name.slice(prefix.length) };
-	}
-	return undefined;
+function installationDir(cacheDir: string, platform: BrowserPlatform, buildId: string): string {
+	return path.join(cacheDir, "chrome", `${platform}-${buildId}`);
 }
 
 function isMissingPath(error: unknown): boolean {

package/src/color.ts

@@ -239,7 +239,7 @@ const ANSI_16: readonly (readonly [number, number, number])[] = [
 const CUBE_STEPS = [0, 95, 135, 175, 215, 255] as const;
 
 /** Parse a 256-color palette index (0–255) to RGB (0..255). */
-function paletteToRgb(index: number): RGB | undefined {
+export function paletteToRgb(index: number): RGB | undefined {
 	if (!Number.isInteger(index) || index < 0 || index > 255) return undefined;
 	if (index < 16) {
 		const rgb = ANSI_16[index];

package/src/dirs.ts

@@ -104,7 +104,7 @@ function readProfileFromEnvSafe(): string | undefined {
 	}
 }
 
-/** Profile-independent config root (~/.zeta), shared by every omp profile. */
+/** Profile-independent config root (~/.zeta), shared by every zeta profile. */
 export function getBaseConfigRoot(): string {
 	return path.join(os.homedir(), getConfigDirName());
 }
@@ -154,19 +154,31 @@ export function normalizePathForComparison(inputPath: string): string {
 	return process.platform === "win32" ? resolvedPath.toLowerCase() : resolvedPath;
 }
 
+/**
+ * Compare paths already normalized by {@link normalizePathForComparison}.
+ *
+ * Returns the relative path (an empty string when the paths are equal), or
+ * `null` when the candidate is outside the root. Callers classifying one
+ * candidate against several static roots can normalize each side once and
+ * reuse the public helpers' containment semantics without repeating realpath
+ * work.
+ */
+export function relativePathWithinNormalizedRoot(normalizedRoot: string, normalizedCandidate: string): string | null {
+	const relative = path.relative(normalizedRoot, normalizedCandidate);
+	if (relative !== "" && (relative.startsWith("..") || path.isAbsolute(relative))) return null;
+	return relative;
+}
+
 export function pathIsWithin(root: string, candidate: string): boolean {
 	const normalizedRoot = normalizePathForComparison(root);
 	const normalizedCandidate = normalizePathForComparison(candidate);
-	const relative = path.relative(normalizedRoot, normalizedCandidate);
-	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+	return relativePathWithinNormalizedRoot(normalizedRoot, normalizedCandidate) !== null;
 }
 
 export function relativePathWithinRoot(root: string, candidate: string): string | null {
-	if (!pathIsWithin(root, candidate)) return null;
 	const normalizedRoot = normalizePathForComparison(root);
 	const normalizedCandidate = normalizePathForComparison(candidate);
-	const relative = path.relative(normalizedRoot, normalizedCandidate);
-	return relative || null;
+	return relativePathWithinNormalizedRoot(normalizedRoot, normalizedCandidate) || null;
 }
 
 let projectDir: string | undefined;
@@ -899,6 +911,16 @@ export function getTerminalSessionsDir(agentDir?: string): string {
 	return dirs.agentSubdir(agentDir, "terminal-sessions", "state");
 }
 
+/**
+ * Get the persistent registry of custom session files
+ * (~/.zeta/agent/custom-session-files). Each `--session-dir`/`--session`
+ * transcript is recorded here as one marker file so storage GC can scan its
+ * exact path after its terminal breadcrumb is overwritten by a later session.
+ */
+export function getCustomSessionFilesDir(agentDir?: string): string {
+	return dirs.agentSubdir(agentDir, "custom-session-files", "state");
+}
+
 /** Get the crash log path (~/.zeta/agent/zeta-crash.log). */
 export function getCrashLogPath(agentDir?: string): string {
 	return dirs.agentSubdir(agentDir, "zeta-crash.log", "state");

package/src/env.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { parseEnv } from "node:util";
 import { getAgentDir, getConfigRootDir, getProjectDir, refreshDirsFromEnv } from "./dirs";
 
 export * from "./worker-host";
@@ -64,6 +65,48 @@ export function filterProcessEnv(env: Record<string, string | undefined>): Recor
 	}
 	return result;
 }
+/**
+ * Git variables that pin a repository location. They describe the checkout the
+ * agent process itself was launched from (git hooks, `git --git-dir` wrappers),
+ * so forwarding them to a child shell makes `git` ignore the command's `cwd`
+ * and mutate the wrong worktree or index. Stripped from child shell envs so git
+ * rediscovers the repository from the working directory. Mirrors the
+ * `env_remove` list in `crates/pi-vcs/src/git/cli.rs`.
+ */
+const GIT_REPO_LOCATION_ENV_NAMES = [
+	"GIT_DIR",
+	"GIT_COMMON_DIR",
+	"GIT_WORK_TREE",
+	"GIT_INDEX_FILE",
+	"GIT_OBJECT_DIRECTORY",
+	"GIT_ALTERNATE_OBJECT_DIRECTORIES",
+] as const;
+
+/**
+ * Removes {@link GIT_REPO_LOCATION_ENV_NAMES} from a copied child env in place.
+ *
+ * Windows environment lookups are case-insensitive, so a block that spells a
+ * variable `git_dir` is just as binding there; match case-insensitively on
+ * win32 and exactly elsewhere (POSIX env names are case-sensitive).
+ */
+export function stripGitRepoLocationEnv(
+	env: Record<string, string>,
+	platform: NodeJS.Platform = process.platform,
+): void {
+	if (platform !== "win32") {
+		for (const name of GIT_REPO_LOCATION_ENV_NAMES) {
+			delete env[name];
+		}
+		return;
+	}
+	const folded = new Set<string>(GIT_REPO_LOCATION_ENV_NAMES.map(name => name.toLowerCase()));
+	for (const key of Object.keys(env)) {
+		if (folded.has(key.toLowerCase())) {
+			delete env[key];
+		}
+	}
+}
+
 // Bun autoloads the project's dotenv files into `process.env` before user code
 // runs — including inside `bun build --compile` binaries — so a snapshot of
 // `Bun.env` is only pre-dotenv when autoloading was explicitly disabled. Linux
@@ -107,10 +150,10 @@ function expandDotenvValues(values: Record<string, string>, env: Record<string,
 	return expanded;
 }
 
-/** Filters process env for child shells without launch-cwd dotenv values. */
-export function filterChildShellEnv(
+function filterChildShellEnvInternal(
 	env: Record<string, string | undefined>,
-	cwd: string = getProjectDir(),
+	cwd: string,
+	onDotenvValue?: (value: string) => void,
 ): Record<string, string> {
 	const runtimeLaunchEnvValues = env === Bun.env || env === process.env ? launchEnvValues : undefined;
 	const result = filterProcessEnv(env);
@@ -147,6 +190,12 @@ export function filterChildShellEnv(
 		}
 	}
 	const allLaunchEnv = fallbackLaunchEnv ? { ...launchEnv, ...fallbackLaunchEnv } : launchEnv;
+	if (onDotenvValue) {
+		// Every value the project's dotenv files define is dotenv-sourced, whether
+		// or not this process loaded it (a `--cwd` launch never did).
+		for (const key in allLaunchEnv) onDotenvValue(allLaunchEnv[key]!);
+		for (const key in expandedLaunchEnv) onDotenvValue(expandedLaunchEnv[key]!);
+	}
 	for (const key in allLaunchEnv) {
 		const launchValue = runtimeLaunchEnvValues?.get(key);
 		if (launchValue !== undefined) {
@@ -168,6 +217,8 @@ export function filterChildShellEnv(
 			// Strong provenance: the launch environment is known and this name is
 			// absent from it, or OMP itself injected the value — either way it came
 			// from a project dotenv file, not the parent shell.
+			const value = result[key];
+			if (value !== undefined) onDotenvValue?.(value);
 			delete result[key];
 		} else if (
 			result[key] === launchEnv[key] ||
@@ -177,50 +228,46 @@ export function filterChildShellEnv(
 		) {
 			// No launch-env snapshot (dotenv autoloaded without procfs): best-effort
 			// value match against the Bun-parsed dotenv.
+			const value = result[key];
+			if (value !== undefined) onDotenvValue?.(value);
 			delete result[key];
 		}
 	}
+	// Last, after dotenv merging: no source (inherited, launcher, or dotenv) may
+	// pin the child shell to the agent's own repository.
+	stripGitRepoLocationEnv(result);
 	return result;
 }
 
-/**
- * Parse one dotenv line with Bun-compatible semantics: an optional `export`
- * prefix, full-line `#` comments, inline `#` comments after whitespace on
- * unquoted values, and single/double/backtick quoting (a `#` inside quotes
- * stays literal). Returns undefined for blank lines, comments, and malformed
- * names.
- */
-function parseEnvLine(line: string): { key: string; value: string } | undefined {
-	const trimmed = line.trim();
-	if (!trimmed || trimmed.startsWith("#")) return undefined;
-	const eqIndex = trimmed.indexOf("=");
-	if (eqIndex === -1) return undefined;
-	let key = trimmed.slice(0, eqIndex).trim();
-	const exported = key.match(/^export[ \t]+(.*)$/);
-	if (exported) key = exported[1].trim();
-	if (!isValidEnvName(key)) return undefined;
-	const raw = trimmed.slice(eqIndex + 1).replace(/^[ \t]+/, "");
-	const quote = raw[0];
-	if (quote === '"' || quote === "'" || quote === "`") {
-		let close = raw.indexOf(quote, 1);
-		while (close !== -1 && raw[close - 1] === "\\") close = raw.indexOf(quote, close + 1);
-		return { key, value: close === -1 ? raw.slice(1) : raw.slice(1, close) };
-	}
-	const commentIndex = raw.search(/[ \t]#/);
-	return { key, value: (commentIndex === -1 ? raw : raw.slice(0, commentIndex)).trimEnd() };
+/** Filters process env for child shells without launch-cwd dotenv values. */
+export function filterChildShellEnv(
+	env: Record<string, string | undefined>,
+	cwd: string = getProjectDir(),
+): Record<string, string> {
+	return filterChildShellEnvInternal(env, cwd);
+}
+
+/** Return every value defined by `cwd`'s dotenv files, plus environment values that came from them. */
+export function getDotenvEnvValues(
+	cwd: string = getProjectDir(),
+	env: Record<string, string | undefined> = process.env,
+): string[] {
+	const values = new Set<string>();
+	filterChildShellEnvInternal(env, cwd, value => values.add(value));
+	return [...values];
 }
 
 /**
- * Parses a .env file synchronously into key-value string pairs using
- * {@link parseEnvLine} for Bun-compatible line semantics.
+ * Parses a complete .env file with the runtime's dotenv grammar, then retains
+ * only shell-identifier names and spawn-safe values.
  */
 export function parseEnvFile(filePath: string): Record<string, string> {
 	const result: Record<string, string> = {};
 	try {
-		const content = fs.readFileSync(filePath, "utf-8");
-		for (const line of content.split("\n")) {
-			const parsed = parseEnvLine(line);
-			if (parsed && isSafeEnvValue(parsed.value)) result[parsed.key] = parsed.value;
+		const parsed = parseEnv(fs.readFileSync(filePath, "utf-8"));
+		for (const key in parsed) {
+			const value = parsed[key];
+			if (value !== undefined && isValidEnvName(key) && isSafeEnvValue(value)) result[key] = value;
 		}
 	} catch {
 		// File doesn't exist or can't be read - return empty result

package/src/executable.ts

@@ -0,0 +1,17 @@
+import * as fs from "node:fs";
+
+/**
+ * Check if a file path exists, is a regular file, and has effective execute permission.
+ */
+export function isExecutable(filePath: string): boolean {
+	try {
+		const stat = fs.statSync(filePath);
+		if (!stat.isFile()) return false;
+		if (process.platform !== "win32") {
+			fs.accessSync(filePath, fs.constants.X_OK);
+		}
+		return true;
+	} catch {
+		return false;
+	}
+}