@oh-my-pi/pi-utils 18.18.1 → 18.18.2

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 ## [Unreleased]
 
+## [18.18.2] - 2026-11-08
+
+### Added
+
+- Added utilities for reading OpenTelemetry configuration from omp-managed `.env` files, including `$otelEnv` and `withOmpOtelEnv`.
+- Added filesystem path utilities for checking paths through symlinked roots, including paths that do not yet exist, and for optionally propagating filesystem errors in directory checks.
+
+### Fixed
+
+- Fixed relaxed JSON parsing so `__proto__` is preserved as a regular own property rather than modifying the parsed object's prototype.
+- Fixed SIGHUP handling so stopped terminal sessions display recovery hints, including the `--resume` command.
+
 ## [18.18.0] - 2026-11-07
 
 ### Fixed

package/dist/types/dirs.d.ts

@@ -63,7 +63,8 @@ export declare function normalizePathForComparison(inputPath: string): string;
  * work.
  */
 export declare function relativePathWithinNormalizedRoot(normalizedRoot: string, normalizedCandidate: string): string | null;
-export declare function pathIsWithin(root: string, candidate: string): boolean;
+/** `options` apply to `candidate` only. */
+export declare function pathIsWithin(root: string, candidate: string, options?: EquivalentPathOptions): boolean;
 export declare function relativePathWithinRoot(root: string, candidate: string): string | null;
 /** Get the project directory. */
 export declare function getProjectDir(): string;
@@ -71,15 +72,14 @@ export declare function getProjectDir(): string;
 export declare function setProjectDir(dir: string): void;
 /** Reset the cached project directory (test seam). */
 export declare function __resetProjectDirCacheForTests(): void;
-/** Whether a path is absent or not a directory. Other stat failures return false. */
-export declare function directoryIsMissing(dir: string): Promise<boolean>;
-/**
- * Whether `dir` resolves to an existing directory. Any stat failure — a deleted
- * path (ENOENT), permission error, or a non-directory — returns `false`, so
- * callers can decide whether a directory is safe to `chdir` into or adopt as a
- * working directory before {@link setProjectDir} throws on it.
- */
-export declare function directoryExists(dir: string): Promise<boolean>;
+/** Whether a path is absent or not a directory; `strict` propagates non-missing stat failures. */
+export declare function directoryIsMissing(dir: string, options?: {
+    strict?: boolean;
+}): Promise<boolean>;
+/** Whether a path is an existing directory; `strict` propagates non-missing stat failures. */
+export declare function directoryExists(dir: string, options?: {
+    strict?: boolean;
+}): Promise<boolean>;
 /**
  * Whether `dir` both exists and can be entered. POSIX `stat` succeeds for a
  * directory whose own search/execute permission is denied (it only needs

package/dist/types/env.d.ts

@@ -45,6 +45,34 @@ export declare function getDotenvEnvValues(cwd?: string, env?: Record<string, st
  * `OMP_` variables to their `PI_` aliases.
  */
 export declare function parseEnvFile(filePath: string): Record<string, string>;
+/**
+ * @internal Loader seam, exported for tests only. Claims an `OTEL_*` entry from one of OMP's own dotenv files: the value is
+ * kept in a private map, never in the process environment. Returns `false` for
+ * any other name, which the caller handles as usual.
+ *
+ * Precedence matches the process-environment loader: a non-empty live value
+ * (shell export, project `.env`) wins, and an earlier non-empty file value wins
+ * over a later file.
+ *
+ * @param platform - Name-folding semantics; injectable for tests.
+ */
+export declare function claimOmpOtelEnvFileEntry(name: string, value: string, platform?: NodeJS.Platform): boolean;
+/**
+ * `OTEL_*` lookup for OMP's own telemetry: the live environment wins (a shell
+ * export or project `.env`), then OMP's own `.env` files. Use this instead of
+ * `process.env` for any `OTEL_*` setting OMP reads itself.
+ */
+export declare function $otelEnv(name: string): string | undefined;
+/**
+ * Runs `fn` with OMP's `.env`-sourced `OTEL_*` values temporarily present in
+ * `process.env` (only for names with no live value), then removes them again in
+ * a `finally`. For code that reads the environment itself, such as the
+ * OpenTelemetry SDK constructors.
+ *
+ * Synchronous only: awaiting inside would let other code, including child
+ * process spawns, run while the values are set.
+ */
+export declare function withOmpOtelEnv<T>(fn: () => T): T;
 /**
  * Intentional re-export of Bun.env.
  *

package/dist/types/postmortem.d.ts

@@ -168,12 +168,22 @@ export declare function isExpectedCleanupError(reason: unknown): boolean;
 export declare function interceptUnhandledRejections(interceptor: (reason: unknown) => boolean): () => void;
 /**
  * Register a synchronous recovery command to print when the process exits
- * through an uncaught exception, an unhandled rejection, or SIGTERM.
+ * through an uncaught exception, an unhandled rejection, SIGTERM, or SIGHUP.
  *
  * Providers are read once cleanup finishes (or hits its deadline), so they
  * report what teardown left behind: a session it saved or one it dropped.
  */
 export declare function registerFatalRecoveryHint(provider: FatalRecoveryHintProvider): () => void;
+/**
+ * Record that the terminal is gone, so signal exits stop writing to fd 2.
+ *
+ * The terminal owner calls this before raising its own disconnect signal. The
+ * `EIO` try/catch in {@link writeTerminalReport} covers a descriptor revoked by
+ * an outside hangup; it cannot cover a write that blocks on a full pty.
+ */
+export declare function declareTerminalDead(): void;
+/** Whether a terminal owner has already declared the terminal gone. */
+export declare function isTerminalDeclaredDead(): boolean;
 /**
  * Reports a caught top-level failure after terminal owners restore their display, then exits.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-utils",
-	"version": "18.18.1",
+	"version": "18.18.2",
 	"description": "Shared utilities for pi packages",
 	"keywords": [
 		"cli",
@@ -56,8 +56,8 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/omptype": "18.18.1",
-		"@oh-my-pi/pi-natives": "18.18.1"
+		"@oh-my-pi/omptype": "18.18.2",
+		"@oh-my-pi/pi-natives": "18.18.2"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/dirs.ts

@@ -191,11 +191,15 @@ export function resolveEquivalentPath(inputPath: string, options?: EquivalentPat
 	}
 }
 
-export function normalizePathForComparison(inputPath: string): string {
-	const resolvedPath = resolveEquivalentPath(inputPath);
+function comparablePath(inputPath: string, options?: EquivalentPathOptions): string {
+	const resolvedPath = resolveEquivalentPath(inputPath, options);
 	return process.platform === "win32" ? resolvedPath.toLowerCase() : resolvedPath;
 }
 
+export function normalizePathForComparison(inputPath: string): string {
+	return comparablePath(inputPath);
+}
+
 /**
  * Compare paths already normalized by {@link normalizePathForComparison}.
  *
@@ -211,9 +215,10 @@ export function relativePathWithinNormalizedRoot(normalizedRoot: string, normali
 	return relative;
 }
 
-export function pathIsWithin(root: string, candidate: string): boolean {
+/** `options` apply to `candidate` only. */
+export function pathIsWithin(root: string, candidate: string, options?: EquivalentPathOptions): boolean {
 	const normalizedRoot = normalizePathForComparison(root);
-	const normalizedCandidate = normalizePathForComparison(candidate);
+	const normalizedCandidate = comparablePath(candidate, options);
 	return relativePathWithinNormalizedRoot(normalizedRoot, normalizedCandidate) !== null;
 }
 
@@ -264,25 +269,23 @@ export function __resetProjectDirCacheForTests(): void {
 	projectDir = undefined;
 }
 
-/** Whether a path is absent or not a directory. Other stat failures return false. */
-export async function directoryIsMissing(dir: string): Promise<boolean> {
+/** Whether a path is absent or not a directory; `strict` propagates non-missing stat failures. */
+export async function directoryIsMissing(dir: string, options?: { strict?: boolean }): Promise<boolean> {
 	try {
 		return !(await fs.promises.stat(dir)).isDirectory();
 	} catch (error) {
-		return isEnoent(error) || isEnotdir(error);
+		if (isEnoent(error) || isEnotdir(error)) return true;
+		if (options?.strict) throw error;
+		return false;
 	}
 }
 
-/**
- * Whether `dir` resolves to an existing directory. Any stat failure — a deleted
- * path (ENOENT), permission error, or a non-directory — returns `false`, so
- * callers can decide whether a directory is safe to `chdir` into or adopt as a
- * working directory before {@link setProjectDir} throws on it.
- */
-export async function directoryExists(dir: string): Promise<boolean> {
+/** Whether a path is an existing directory; `strict` propagates non-missing stat failures. */
+export async function directoryExists(dir: string, options?: { strict?: boolean }): Promise<boolean> {
 	try {
 		return (await fs.promises.stat(dir)).isDirectory();
-	} catch {
+	} catch (error) {
+		if (options?.strict && !isEnoent(error) && !isEnotdir(error)) throw error;
 		return false;
 	}
 }

package/src/env.ts

@@ -299,9 +299,92 @@ for (const key of Object.keys(Bun.env)) {
 	}
 }
 
+/**
+ * `OTEL_*` values from OMP's own (non-project) dotenv files: the agent dir,
+ * config root, and home `.env`. Those files configure OMP's exporter (endpoint,
+ * auth headers, GenAI content capture), so the values are kept here instead of
+ * in `Bun.env`/`process.env`: no child process or in-process extension
+ * inherits them. Read through {@link $otelEnv}; {@link withOmpOtelEnv} exposes
+ * them to the OpenTelemetry SDK for the synchronous span of its construction.
+ *
+ * Keys are folded with {@link foldOtelEnvName}.
+ */
+const ompOtelEnvFileValues = new Map<string, string>();
+
+/**
+ * Environment names compare case-insensitively on Windows, so a file that spells
+ * `otel_exporter_otlp_headers` configures the same variable as the upper-case
+ * name; match and key them folded there, exactly on POSIX (names are
+ * case-sensitive).
+ */
+function foldOtelEnvName(name: string, platform: NodeJS.Platform): string {
+	return platform === "win32" ? name.toUpperCase() : name;
+}
+
+/**
+ * @internal Loader seam, exported for tests only. Claims an `OTEL_*` entry from one of OMP's own dotenv files: the value is
+ * kept in a private map, never in the process environment. Returns `false` for
+ * any other name, which the caller handles as usual.
+ *
+ * Precedence matches the process-environment loader: a non-empty live value
+ * (shell export, project `.env`) wins, and an earlier non-empty file value wins
+ * over a later file.
+ *
+ * @param platform - Name-folding semantics; injectable for tests.
+ */
+export function claimOmpOtelEnvFileEntry(
+	name: string,
+	value: string,
+	platform: NodeJS.Platform = process.platform,
+): boolean {
+	const key = foldOtelEnvName(name, platform);
+	if (!key.startsWith("OTEL_")) return false;
+	if (!Bun.env[name] && !ompOtelEnvFileValues.get(key)) ompOtelEnvFileValues.set(key, value);
+	return true;
+}
+
+/**
+ * `OTEL_*` lookup for OMP's own telemetry: the live environment wins (a shell
+ * export or project `.env`), then OMP's own `.env` files. Use this instead of
+ * `process.env` for any `OTEL_*` setting OMP reads itself.
+ */
+export function $otelEnv(name: string): string | undefined {
+	const live = Bun.env[name];
+	if (live) return live;
+	return ompOtelEnvFileValues.get(foldOtelEnvName(name, process.platform)) ?? live;
+}
+
+/**
+ * Runs `fn` with OMP's `.env`-sourced `OTEL_*` values temporarily present in
+ * `process.env` (only for names with no live value), then removes them again in
+ * a `finally`. For code that reads the environment itself, such as the
+ * OpenTelemetry SDK constructors.
+ *
+ * Synchronous only: awaiting inside would let other code, including child
+ * process spawns, run while the values are set.
+ */
+export function withOmpOtelEnv<T>(fn: () => T): T {
+	const previous = new Map<string, string | undefined>();
+	for (const [name, value] of ompOtelEnvFileValues) {
+		if (process.env[name]) continue;
+		previous.set(name, process.env[name]);
+		process.env[name] = value;
+	}
+	try {
+		return fn();
+	} finally {
+		for (const [name, prior] of previous) {
+			if (prior === undefined) delete process.env[name];
+			else process.env[name] = prior;
+		}
+	}
+}
+
 for (const file of [projectEnv, agentEnv, piEnv, homeEnv]) {
 	for (const key in file) {
-		if (!isMacosMallocStackLoggingEnvName(key) && !Bun.env[key]) {
+		if (isMacosMallocStackLoggingEnvName(key)) continue;
+		if (file !== projectEnv && claimOmpOtelEnvFileEntry(key, file[key])) continue;
+		if (!Bun.env[key]) {
 			Bun.env[key] = file[key];
 			if (file === projectEnv) projectEnvNamesLoadedByOmp.add(key);
 		}

package/src/json-parse.ts

@@ -223,7 +223,14 @@ class RelaxedJson {
 			}
 			const value = this.#value(true);
 			if (value === INCOMPLETE) return out;
-			out[key] = value;
+			// A decoded __proto__ key must become an own property, not invoke
+			// the legacy prototype setter on the result object (same guard as
+			// schema/normalize.ts and validation.ts).
+			if (key === "__proto__") {
+				Object.defineProperty(out, key, { value, enumerable: true, writable: true, configurable: true });
+			} else {
+				out[key] = value;
+			}
 			lex.ws();
 			const d = lex.peek();
 			if (d === COMMA) {

package/src/postmortem.ts

@@ -602,7 +602,7 @@ function removeEmbeddedRejectionListener(): void {
 
 /**
  * Register a synchronous recovery command to print when the process exits
- * through an uncaught exception, an unhandled rejection, or SIGTERM.
+ * through an uncaught exception, an unhandled rejection, SIGTERM, or SIGHUP.
  *
  * Providers are read once cleanup finishes (or hits its deadline), so they
  * report what teardown left behind: a session it saved or one it dropped.
@@ -644,6 +644,30 @@ function formatFatalError(label: string, err: Error): string {
 	return `\n[${label}] ${name}: ${message}${formattedStack}\n`;
 }
 
+/**
+ * Whether a terminal owner has declared the terminal gone, e.g. the TUI's
+ * `#markTerminalDisconnected`. The owner sets this before raising SIGHUP itself,
+ * so the signal handlers must not write afterwards: with stdout stalled, fd 2 is
+ * a blocking, full pty, and a write there hangs in the kernel before the exit.
+ */
+let terminalDeclaredDead = false;
+
+/**
+ * Record that the terminal is gone, so signal exits stop writing to fd 2.
+ *
+ * The terminal owner calls this before raising its own disconnect signal. The
+ * `EIO` try/catch in {@link writeTerminalReport} covers a descriptor revoked by
+ * an outside hangup; it cannot cover a write that blocks on a full pty.
+ */
+export function declareTerminalDead(): void {
+	terminalDeclaredDead = true;
+}
+
+/** Whether a terminal owner has already declared the terminal gone. */
+export function isTerminalDeclaredDead(): boolean {
+	return terminalDeclaredDead;
+}
+
 /** Write a final report to stderr once terminal owners have handed the terminal back. */
 function writeTerminalReport(output: string): void {
 	restoreTerminalStderr();
@@ -728,6 +752,21 @@ process.on("exit", () => {
 
 let processHandlersInstalled = false;
 
+/**
+ * Exit through a termination signal: clean up, print the recovery hints, exit.
+ *
+ * The hint write is skipped once a terminal owner declared the terminal dead
+ * ({@link declareTerminalDead}): a stalled stdout leaves fd 2 a full, blocking
+ * pty, so the write would hang the process before the exit below. A repeated
+ * signal joins the same cleanup and the hints still print once.
+ */
+async function exitAfterSignal(reason: Reason, heading: string, exitCode: number): Promise<never> {
+	const hintProviders = [...fatalRecoveryHintProviders];
+	await runCleanup(reason);
+	if (!terminalDeclaredDead) writeRecoveryHints(hintProviders, heading);
+	exitProcess(exitCode);
+}
+
 /** Installs OMP's process-wide signal and fatal handlers for a CLI-owned process. */
 export function installProcessHandlers(): void {
 	if (processHandlersInstalled) return;
@@ -805,16 +844,13 @@ export function installProcessHandlers(): void {
 		})
 		.on("SIGTERM", async () => {
 			// A stopped session otherwise leaves its last frame above the shell prompt,
-			// which reads as a crash. A repeated SIGTERM joins the same cleanup and the
-			// hints still print once.
-			const hintProviders = [...fatalRecoveryHintProviders];
-			await runCleanup(Reason.SIGTERM);
-			writeRecoveryHints(hintProviders, "\n[Stopped by SIGTERM]");
-			exitProcess(143); // 128 + SIGTERM (15)
+			// which reads as a crash.
+			await exitAfterSignal(Reason.SIGTERM, "\n[Stopped by SIGTERM]", 143); // 128 + SIGTERM (15)
 		})
 		.on("SIGHUP", async () => {
-			await runCleanup(Reason.SIGHUP);
-			exitProcess(129); // 128 + SIGHUP (1)
+			// Same report as SIGTERM: a runtime that stops the program with a hangup
+			// keeps its screen, so the resume command survives the death.
+			await exitAfterSignal(Reason.SIGHUP, "\n[Stopped by SIGHUP]", 129); // 128 + SIGHUP (1)
 		});
 }