@oh-my-pi/pi-utils 17.1.3 → 17.1.4

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 ## [Unreleased]
 
+## [17.1.4] - 2026-07-26
+
+### Fixed
+
+- Fixed postmortem signal and fatal shutdown exits being intercepted by temporary `process.exit` guards during extension startup ([#6488](https://github.com/can1357/oh-my-pi/issues/6488)).
+- Corrected Windows shell resolution errors to identify the active global, project, overlay, or runtime source for `shellPath` instead of directing every user to the retired `settings.json` file ([#6579](https://github.com/can1357/oh-my-pi/issues/6579)).
+- Contained timed-out child lifecycle rejections so `ptree` callers cannot leak an unhandled `TimeoutError` after settling ([#6635](https://github.com/can1357/oh-my-pi/issues/6635)).
+- Fixed an invalid configured `shellPath` being silently masked whenever an earlier caller had already resolved a shell in the same process; the guidance error now surfaces regardless of cache state.
+
 ## [17.0.9] - 2026-07-23
 
 ### Breaking Changes

package/dist/types/postmortem.d.ts

@@ -49,10 +49,7 @@ export declare function markExpectedCleanupError<T extends object>(reason: T): T
 export declare function isExpectedCleanupError(reason: unknown): boolean;
 /**
  * Register an interceptor consulted before an unhandled rejection tears the
- * process down. Return `true` to consume the rejection — the interceptor owns
- * reporting and the process continues. Used by embedded script runtimes (JS
- * eval cells) whose user code can float rejections the host must not die for.
- * Returns an unregister function.
+ * process down. A consuming interceptor owns reporting and keeps the process alive.
  */
 export declare function interceptUnhandledRejections(interceptor: (reason: unknown) => boolean): () => void;
 /**
@@ -68,9 +65,9 @@ export declare function register(id: string, callback: (reason: Reason) => void
  */
 export declare function cleanup(): Promise<void>;
 /**
- * Runs all cleanup callbacks and exits.
+ * Runs all cleanup callbacks and exits through the current `process.exit`.
  *
- * In main thread: waits for stdout drain, then calls process.exit().
+ * In main thread: waits for stdout drain, then calls `process.exit()`.
  * In workers: runs cleanup only (process.exit would kill entire process).
  */
 export declare function quit(code?: number): Promise<void>;

package/dist/types/procmgr.d.ts

@@ -5,23 +5,52 @@ export interface ShellConfig {
     env: Record<string, string>;
     prefix: string | undefined;
 }
+/** Identifies the settings source users should edit when shell resolution fails. */
+export interface ShellConfigOptions {
+    /** File path or runtime layer that supplied the active shell setting. */
+    configSource?: string;
+}
 /**
  * Check if a shell binary is executable.
  */
 export declare function isExecutable(path: string): boolean;
+/** Whether the shell is Windows cmd.exe (spawn paths must use `/c`, not `-c`). */
+export declare function isCmdShell(shell: string): boolean;
 /**
  * Resolve a basic shell (bash or sh) as fallback.
  */
 export declare function resolveBasicShell(): string | undefined;
+/**
+ * Resolve the external shell to advertise on Windows.
+ *
+ * A host bash is OPTIONAL: bash tool commands always execute in the embedded
+ * brush-core shell. The resolved binary only serves the spawn-a-shell paths
+ * (interactive PTY sessions, ACP client terminals, SHELL env), so this
+ * prefers a real Git Bash when one exists and otherwise falls back to
+ * cmd.exe — it never fails.
+ *
+ * Search order:
+ * 1. Git for Windows install roots (machine + per-user installers)
+ * 2. scoop installs — scoop's git manifest sets GIT_INSTALL_ROOT and shims
+ *    sh.exe/git.exe but never bash.exe, so PATH lookup alone misses it
+ * 3. bash.exe on PATH (Cygwin, MSYS2, ...)
+ * 4. sh.exe on PATH (Git for Windows' sh.exe is bash; prefer a sibling
+ *    bash.exe when present)
+ * 5. cmd.exe from ComSpec
+ *
+ * Exported for tests; `env` overrides Bun.env-based discovery.
+ */
+export declare function resolveWindowsShell(env?: Record<string, string | undefined>): string;
 /**
  * Get shell configuration based on platform.
  * Resolution order:
- * 1. User-specified shellPath in settings.json
- * 2. On Windows: Git Bash in known locations, then bash on PATH
+ * 1. User-specified shellPath from the active settings source
+ * 2. On Windows: Git Bash / bash / sh discovery, then cmd.exe (see
+ *    {@link resolveWindowsShell}) — never fails
  * 3. On Unix: $SHELL if bash/zsh, then fallback paths
  * 4. Fallback: sh
  */
-export declare function getShellConfig(customShellPath?: string): ShellConfig;
+export declare function getShellConfig(customShellPath?: string, options?: ShellConfigOptions): ShellConfig;
 /**
  * Check if a process is running.
  */

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

@@ -1,3 +1,7 @@
+/** Prefix reserved for argv selectors dispatched by the shared CLI worker host. */
+export declare const WORKER_HOST_SELECTOR_PREFIX = "__omp_worker_";
+/** Whether an argv value selects a worker hosted by the shared CLI entrypoint. */
+export declare function isWorkerHostSelector(value: string | undefined): value is string;
 /** 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. */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "17.1.3",
+	"version": "17.1.4",
 	"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": "17.1.3",
+		"@oh-my-pi/pi-natives": "17.1.4",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",
 		"winston-daily-rotate-file": "^5.0.0"

package/src/postmortem.ts

@@ -9,7 +9,7 @@
 import * as fs from "node:fs";
 import inspector from "node:inspector";
 import { isMainThread } from "node:worker_threads";
-import { logger } from ".";
+import * as logger from "./logger";
 import { restoreTerminalStderr } from "./stderr-guard";
 
 // Cleanup reasons, in order of priority/meaning.
@@ -29,6 +29,8 @@ const callbackList: ((reason: Reason) => Promise<void> | void)[] = [];
 // Tracks cleanup run state (to prevent recursion/reentry issues)
 let cleanupStage: "idle" | "running" | "complete" = "idle";
 const CLEANUP_DEADLINE_MS = 10_000;
+const exitProcess =
+	typeof process.reallyExit === "function" ? process.reallyExit.bind(process) : process.exit.bind(process);
 let cleanupPromise: Promise<void> | undefined;
 let stdioDisconnectRegistrations = 0;
 
@@ -149,18 +151,12 @@ export function isExpectedCleanupError(reason: unknown): boolean {
 	return false;
 }
 
-/**
- * Interceptors consulted by the global `unhandledRejection` handler before the
- * fatal path. See {@link interceptUnhandledRejections}.
- */
+/** Interceptors consulted by the global `unhandledRejection` handler before the fatal path. */
 const rejectionInterceptors = new Set<(reason: unknown) => boolean>();
 
 /**
  * Register an interceptor consulted before an unhandled rejection tears the
- * process down. Return `true` to consume the rejection — the interceptor owns
- * reporting and the process continues. Used by embedded script runtimes (JS
- * eval cells) whose user code can float rejections the host must not die for.
- * Returns an unregister function.
+ * process down. A consuming interceptor owns reporting and keeps the process alive.
  */
 export function interceptUnhandledRejections(interceptor: (reason: unknown) => boolean): () => void {
 	rejectionInterceptors.add(interceptor);
@@ -177,7 +173,7 @@ function formatFatalError(label: string, err: Error): string {
 }
 
 async function exitAfterFatal(label: string, logMessage: string, err: Error, reason: Reason): Promise<void> {
-	const forcedExit = setTimeout(() => process.exit(1), CLEANUP_DEADLINE_MS);
+	const forcedExit = setTimeout(() => exitProcess(1), CLEANUP_DEADLINE_MS);
 	try {
 		restoreTerminalStderr();
 		// A revoked terminal can make stream writes raise another fatal error. Use
@@ -189,7 +185,7 @@ async function exitAfterFatal(label: string, logMessage: string, err: Error, rea
 		await runCleanup(reason);
 	} finally {
 		clearTimeout(forcedExit);
-		process.exit(1);
+		exitProcess(1);
 	}
 }
 
@@ -197,7 +193,7 @@ if (isMainThread) {
 	process
 		.on("SIGINT", async () => {
 			await runCleanup(Reason.SIGINT);
-			process.exit(130); // 128 + SIGINT (2)
+			exitProcess(130); // 128 + SIGINT (2)
 		})
 		.on("SIGUSR1", () => {
 			if (inspectorOpened) return;
@@ -231,7 +227,7 @@ if (isMainThread) {
 			}
 			if (brokenPipeSource === "stdio-write" && stdioDisconnectRegistrations > 0) {
 				logger.warn("Stdio peer disconnected; shutting down gracefully", { err });
-				await quit(0);
+				await runQuit(0, "native");
 				return;
 			}
 			if (isExpectedCleanupError(reason)) {
@@ -254,11 +250,11 @@ if (isMainThread) {
 		})
 		.on("SIGTERM", async () => {
 			await runCleanup(Reason.SIGTERM);
-			process.exit(143); // 128 + SIGTERM (15)
+			exitProcess(143); // 128 + SIGTERM (15)
 		})
 		.on("SIGHUP", async () => {
 			await runCleanup(Reason.SIGHUP);
-			process.exit(129); // 128 + SIGHUP (1)
+			exitProcess(129); // 128 + SIGHUP (1)
 		});
 } else {
 	// Worker thread: only register exit handler for cleanup.
@@ -323,13 +319,7 @@ export function cleanup(): Promise<void> {
 	return runCleanup(Reason.MANUAL);
 }
 
-/**
- * Runs all cleanup callbacks and exits.
- *
- * In main thread: waits for stdout drain, then calls process.exit().
- * In workers: runs cleanup only (process.exit would kill entire process).
- */
-export async function quit(code: number = 0): Promise<void> {
+async function runQuit(code: number, exitMode: "guarded" | "native"): Promise<void> {
 	await runCleanup(Reason.MANUAL);
 
 	if (!isMainThread) {
@@ -341,5 +331,21 @@ export async function quit(code: number = 0): Promise<void> {
 		process.stdout.once("drain", resolve);
 		await Promise.race([promise, Bun.sleep(5000)]);
 	}
-	process.exit(code);
+
+	switch (exitMode) {
+		case "guarded":
+			return process.exit(code);
+		case "native":
+			return exitProcess(code);
+	}
+}
+
+/**
+ * Runs all cleanup callbacks and exits through the current `process.exit`.
+ *
+ * In main thread: waits for stdout drain, then calls `process.exit()`.
+ * In workers: runs cleanup only (process.exit would kill entire process).
+ */
+export function quit(code: number = 0): Promise<void> {
+	return runQuit(code, "guarded");
 }

package/src/procmgr.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { Process, ProcessStatus } from "@oh-my-pi/pi-natives";
 import type { Subprocess } from "bun";
+import { getAgentDir, MAIN_CONFIG_FILENAMES } from "./dirs";
 import { $env, filterChildShellEnv } from "./env";
 import { $which } from "./which";
 
@@ -11,6 +12,12 @@ export interface ShellConfig {
 	env: Record<string, string>;
 	prefix: string | undefined;
 }
+
+/** Identifies the settings source users should edit when shell resolution fails. */
+export interface ShellConfigOptions {
+	/** File path or runtime layer that supplied the active shell setting. */
+	configSource?: string;
+}
 let cachedShellConfig: ShellConfig | null = null;
 
 /**
@@ -42,14 +49,22 @@ function buildSpawnEnv(shell: string): Record<string, string> {
 }
 
 /**
- * Get shell args, optionally including login shell flag.
- * Supports PI_BASH_NO_LOGIN and CLAUDE_BASH_NO_LOGIN to skip -l.
+ * Get shell args for the resolved shell.
+ * cmd.exe takes `/c`; POSIX shells take `-c`, with `-l` unless
+ * PI_BASH_NO_LOGIN / CLAUDE_BASH_NO_LOGIN is set.
  */
-function getShellArgs(): string[] {
+function getShellArgs(shell: string): string[] {
+	if (isCmdShell(shell)) return ["/c"];
 	const noLogin = $env.PI_BASH_NO_LOGIN || $env.CLAUDE_BASH_NO_LOGIN;
 	return noLogin ? ["-c"] : ["-l", "-c"];
 }
 
+/** Whether the shell is Windows cmd.exe (spawn paths must use `/c`, not `-c`). */
+export function isCmdShell(shell: string): boolean {
+	const basename = shell.replace(/\\/g, "/").split("/").pop()?.toLowerCase();
+	return basename === "cmd.exe" || basename === "cmd";
+}
+
 /**
  * Get shell prefix for wrapping commands (profilers, strace, etc.).
  */
@@ -63,7 +78,7 @@ function getShellPrefix(): string | undefined {
 function buildConfig(shell: string): ShellConfig {
 	return {
 		shell,
-		args: getShellArgs(),
+		args: getShellArgs(shell),
 		env: buildSpawnEnv(shell),
 		prefix: getShellPrefix(),
 	};
@@ -93,63 +108,83 @@ export function resolveBasicShell(): string | undefined {
 	return undefined;
 }
 
+/**
+ * Resolve the external shell to advertise on Windows.
+ *
+ * A host bash is OPTIONAL: bash tool commands always execute in the embedded
+ * brush-core shell. The resolved binary only serves the spawn-a-shell paths
+ * (interactive PTY sessions, ACP client terminals, SHELL env), so this
+ * prefers a real Git Bash when one exists and otherwise falls back to
+ * cmd.exe — it never fails.
+ *
+ * Search order:
+ * 1. Git for Windows install roots (machine + per-user installers)
+ * 2. scoop installs — scoop's git manifest sets GIT_INSTALL_ROOT and shims
+ *    sh.exe/git.exe but never bash.exe, so PATH lookup alone misses it
+ * 3. bash.exe on PATH (Cygwin, MSYS2, ...)
+ * 4. sh.exe on PATH (Git for Windows' sh.exe is bash; prefer a sibling
+ *    bash.exe when present)
+ * 5. cmd.exe from ComSpec
+ *
+ * Exported for tests; `env` overrides Bun.env-based discovery.
+ */
+export function resolveWindowsShell(env: Record<string, string | undefined> = Bun.env): string {
+	const gitRoots = [
+		env.ProgramFiles && path.join(env.ProgramFiles, "Git"),
+		env["ProgramFiles(x86)"] && path.join(env["ProgramFiles(x86)"], "Git"),
+		env.LOCALAPPDATA && path.join(env.LOCALAPPDATA, "Programs", "Git"),
+		env.GIT_INSTALL_ROOT,
+		env.SCOOP && path.join(env.SCOOP, "apps", "git", "current"),
+		env.USERPROFILE && path.join(env.USERPROFILE, "scoop", "apps", "git", "current"),
+	];
+	for (const root of gitRoots) {
+		if (!root) continue;
+		const candidate = path.join(root, "bin", "bash.exe");
+		if (fs.existsSync(candidate)) return candidate;
+	}
+
+	const bashOnPath = $which("bash.exe");
+	if (bashOnPath) return bashOnPath;
+
+	const shOnPath = $which("sh.exe");
+	if (shOnPath) {
+		const siblingBash = path.join(path.dirname(shOnPath), "bash.exe");
+		return fs.existsSync(siblingBash) ? siblingBash : shOnPath;
+	}
+
+	return env.ComSpec || env.COMSPEC || "C:\\Windows\\System32\\cmd.exe";
+}
+
 /**
  * Get shell configuration based on platform.
  * Resolution order:
- * 1. User-specified shellPath in settings.json
- * 2. On Windows: Git Bash in known locations, then bash on PATH
+ * 1. User-specified shellPath from the active settings source
+ * 2. On Windows: Git Bash / bash / sh discovery, then cmd.exe (see
+ *    {@link resolveWindowsShell}) — never fails
  * 3. On Unix: $SHELL if bash/zsh, then fallback paths
  * 4. Fallback: sh
  */
-export function getShellConfig(customShellPath?: string): ShellConfig {
-	if (cachedShellConfig) {
-		return cachedShellConfig;
-	}
-
-	// 1. Check user-specified shell path
+export function getShellConfig(customShellPath?: string, options: ShellConfigOptions = {}): ShellConfig {
+	const configSource = options.configSource ?? path.join(getAgentDir(), MAIN_CONFIG_FILENAMES[0]);
+	// 1. Check user-specified shell path. Validated even on the cached path so a
+	// broken shellPath surfaces its guidance error instead of being masked by an
+	// earlier successful resolution in the same process.
 	if (customShellPath) {
-		if (fs.existsSync(customShellPath)) {
+		if (!fs.existsSync(customShellPath)) {
+			throw new Error(`Custom shell path not found: ${customShellPath}\nPlease update shellPath in ${configSource}`);
+		}
+		if (cachedShellConfig?.shell !== customShellPath) {
 			cachedShellConfig = buildConfig(customShellPath);
-			return cachedShellConfig;
 		}
-		throw new Error(
-			`Custom shell path not found: ${customShellPath}\nPlease update shellPath in ~/.omp/agent/settings.json`,
-		);
+		return cachedShellConfig;
+	}
+	if (cachedShellConfig) {
+		return cachedShellConfig;
 	}
 
 	if (process.platform === "win32") {
-		// 2. Try Git Bash in known locations
-		const paths: string[] = [];
-		const programFiles = Bun.env.ProgramFiles;
-		if (programFiles) {
-			paths.push(`${programFiles}\\Git\\bin\\bash.exe`);
-		}
-		const programFilesX86 = Bun.env["ProgramFiles(x86)"];
-		if (programFilesX86) {
-			paths.push(`${programFilesX86}\\Git\\bin\\bash.exe`);
-		}
-
-		for (const path of paths) {
-			if (fs.existsSync(path)) {
-				cachedShellConfig = buildConfig(path);
-				return cachedShellConfig;
-			}
-		}
-
-		// 3. Fallback: search bash.exe on PATH (Cygwin, MSYS2, WSL, etc.)
-		const bashOnPath = $which("bash.exe");
-		if (bashOnPath) {
-			cachedShellConfig = buildConfig(bashOnPath);
-			return cachedShellConfig;
-		}
-
-		throw new Error(
-			`No bash shell found. Options:\n` +
-				`  1. Install Git for Windows: https://git-scm.com/download/win\n` +
-				`  2. Add your bash to PATH (Cygwin, MSYS2, etc.)\n` +
-				`  3. Set shellPath in ~/.omp/agent/settings.json\n\n` +
-				`Searched Git Bash in:\n${paths.map(p => `  ${p}`).join("\n")}`,
-		);
+		cachedShellConfig = buildConfig(resolveWindowsShell());
+		return cachedShellConfig;
 	}
 
 	// Unix: prefer user's shell from $SHELL if it's bash/zsh and executable

package/src/ptree.ts

@@ -309,6 +309,7 @@ export class ChildProcess<In extends InMask = InMask> {
 
 	attachTimeout(ms: number): void {
 		if (ms <= 0 || this.proc.killed) return;
+		this.#exited.catch(() => {});
 		Promise.race([
 			Bun.sleep(ms).then(() => true),
 			this.proc.exited.then(

package/src/worker-host.ts

@@ -1,5 +1,13 @@
 import { stripWindowsExtendedLengthPathPrefix } from "./path";
 
+/** Prefix reserved for argv selectors dispatched by the shared CLI worker host. */
+export const WORKER_HOST_SELECTOR_PREFIX = "__omp_worker_";
+
+/** Whether an argv value selects a worker hosted by the shared CLI entrypoint. */
+export function isWorkerHostSelector(value: string | undefined): value is string {
+	return value?.startsWith(WORKER_HOST_SELECTOR_PREFIX) ?? false;
+}
+
 /**
  * Main-module path declared by self-dispatching CLI entrypoints — entries
  * whose top-level argv handling routes hidden `__omp_*` worker selectors.