@oh-my-pi/pi-utils 17.0.1 → 17.0.2

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## [Unreleased]
 
+## [17.0.2] - 2026-07-17
+
+### Added
+
+- Added a structured log sink API (`registerLogSink`, `LogEvent`, `LogLevel`) to the centralized logger, enabling out-of-band consumers (such as OpenTelemetry) to receive log events without affecting local file or console logging.
+
+### Changed
+
+- Bounded default `ptree.ChildProcess` stderr retention to a 32 KiB tail to prevent memory leaks in long-lived subprocesses. Full stderr capture must now be explicitly requested at spawn time using `{ stderr: "full" }` on `spawn` or `exec`.
+
+### Fixed
+
+- Fixed fatal cleanup failing to reach `process.exit()` when terminal stderr is revoked.
+- Isolated rotating log files and audit state per process to prevent concurrent instances from racing during compression and rotation.
+
 ## [17.0.1] - 2026-07-16
 
 ### Fixed

package/dist/types/dirs.d.ts

@@ -102,8 +102,8 @@ export declare function getProjectAgentDir(cwd?: string): string;
 export declare function getReportsDir(): string;
 /** Get the logs directory (~/.omp/logs). */
 export declare function getLogsDir(): string;
-/** Get the path to a dated log file (~/.omp/logs/omp.YYYY-MM-DD.log). */
-export declare function getLogPath(date?: Date): string;
+/** Get this process's dated log path (~/.omp/logs/omp.YYYY-MM-DD.PID.log). */
+export declare function getLogPath(date?: Date, pid?: number): string;
 /**
  * Get the plugins directory (~/.omp/plugins or its XDG equivalent).
  *

package/dist/types/logger.d.ts

@@ -1,3 +1,16 @@
+/** Severity names accepted by the centralized logger. */
+export type LogLevel = "error" | "warn" | "info" | "debug";
+/** Structured log event forwarded to out-of-band sinks such as OpenTelemetry. */
+export interface LogEvent {
+    readonly level: LogLevel;
+    readonly message: string;
+    readonly context: Record<string, unknown> | undefined;
+    readonly timestamp: Date;
+}
+/** Receives each structured log event after the local transport path runs. */
+export type LogSink = (event: LogEvent) => void;
+/** Register an out-of-band log sink and return a disposer. */
+export declare function registerLogSink(sink: LogSink): () => void;
 /**
  * Replace the active log transports. Pass `console: true, file: false` for
  * long-running services (the auth broker, etc.) that want their structured

package/dist/types/postmortem.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Cleanup and postmortem handler utilities.
+ *
+ * This module provides a system for registering and running cleanup callbacks
+ * in response to process exit, signals, or fatal exceptions. It is intended to
+ * allow reliably releasing resources or shutting down subprocesses, files, sockets, etc.
+ */
 export declare enum Reason {
     PRE_EXIT = "pre_exit",// Pre-exit phase (not used by default)
     EXIT = "exit",// Normal process exit

package/dist/types/ptree.d.ts

@@ -40,6 +40,7 @@ export declare class TimeoutError extends AbortError {
 export interface WaitOptions {
     allowNonZero?: boolean;
     allowAbort?: boolean;
+    /** `full` requires upfront capture; `exec` enables it, while direct `spawn` callers pass `stderr: "full"`. */
     stderr?: "full" | "buffer";
 }
 /** Result from wait and exec. */
@@ -62,7 +63,7 @@ export declare class ChildProcess<In extends InMask = InMask> {
     #private;
     readonly proc: PipedSubprocess<In>;
     readonly exposeStderr: boolean;
-    constructor(proc: PipedSubprocess<In>, exposeStderr: boolean);
+    constructor(proc: PipedSubprocess<In>, exposeStderr: boolean, retainFullStderr?: boolean);
     get pid(): number;
     get exited(): Promise<number>;
     get exitCode(): number | null;
@@ -92,6 +93,7 @@ export declare class ChildProcess<In extends InMask = InMask> {
 type ChildSpawnOptions<In extends InMask = InMask> = Omit<Spawn.SpawnOptions<In, "pipe", "pipe">, "stdout" | "stderr" | "detached"> & {
     signal?: AbortSignal;
     detached?: boolean;
+    /** Expose and retain complete stderr for a later `wait({ stderr: "full" })`. */
     stderr?: "full" | null;
 };
 /** Spawn a child process with piped stdout/stderr. */

package/package.json

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

package/src/dirs.ts

@@ -513,9 +513,9 @@ export function getLogsDir(): string {
 	return dirs.rootSubdir("logs", "state");
 }
 
-/** Get the path to a dated log file (~/.omp/logs/omp.YYYY-MM-DD.log). */
-export function getLogPath(date = new Date()): string {
-	return path.join(getLogsDir(), `${APP_NAME}.${date.toISOString().slice(0, 10)}.log`);
+/** Get this process's dated log path (~/.omp/logs/omp.YYYY-MM-DD.PID.log). */
+export function getLogPath(date = new Date(), pid = process.pid): string {
+	return path.join(getLogsDir(), `${APP_NAME}.${date.toISOString().slice(0, 10)}.${pid}.log`);
 }
 
 /**

package/src/logger.ts

@@ -1,7 +1,7 @@
 /**
  * Centralized logger for omp.
  *
- * Default: rotating `~/.omp/logs/omp.<DATE>.log`, no console output (writing
+ * Default: rotating `~/.omp/logs/omp.<DATE>.<PID>.log`, no console output (writing
  * to stdout/stderr would corrupt the TUI). Long-running headless services
  * (the auth broker, etc.) call {@link setTransports} to swap in a console
  * transport so a process supervisor (pm2, journald, k8s) captures the logs.
@@ -11,11 +11,107 @@
  */
 import { AsyncLocalStorage } from "node:async_hooks";
 import * as fs from "node:fs";
+import * as path from "node:path";
 import { isPromise } from "node:util/types";
 import winston from "winston";
 import DailyRotateFile from "winston-daily-rotate-file";
 import { getLogsDir } from "./dirs";
 import { drainModuleLoadEvents } from "./timing-buffer";
+/** Severity names accepted by the centralized logger. */
+export type LogLevel = "error" | "warn" | "info" | "debug";
+
+/** Structured log event forwarded to out-of-band sinks such as OpenTelemetry. */
+export interface LogEvent {
+	readonly level: LogLevel;
+	readonly message: string;
+	readonly context: Record<string, unknown> | undefined;
+	readonly timestamp: Date;
+}
+
+/** Receives each structured log event after the local transport path runs. */
+export type LogSink = (event: LogEvent) => void;
+
+const logSinks = new Set<LogSink>();
+
+/** Register an out-of-band log sink and return a disposer. */
+export function registerLogSink(sink: LogSink): () => void {
+	logSinks.add(sink);
+	return () => {
+		logSinks.delete(sink);
+	};
+}
+
+function emitToSinks(level: LogLevel, message: string, context: Record<string, unknown> | undefined): void {
+	if (logSinks.size === 0) return;
+	const event: LogEvent = { level, message, context, timestamp: new Date() };
+	for (const sink of logSinks) {
+		try {
+			sink(event);
+		} catch {
+			// Sinks are side channels; they must never break local logging.
+		}
+	}
+}
+
+const PROCESS_LOG_PATTERN = /^omp\.\d{4}-\d{2}-\d{2}\.(\d+)\.log(?:\.\d+)?$/;
+const PROCESS_AUDIT_PATTERN = /^\.omp\.(\d+)-audit\.json$/;
+const RETAINED_STALE_LOG_FILES = 5;
+
+function processIsRunning(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch (error) {
+		return !(error instanceof Error && "code" in error && (error.code === "ESRCH" || error.code === "EINVAL"));
+	}
+}
+
+/**
+ * Retain the newest completed-process logs globally and remove their one-use
+ * audit files. Live PID namespaces are never touched.
+ */
+function pruneStaleProcessLogs(dir: string): void {
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+
+	const staleLogs: Array<{ path: string; mtimeMs: number }> = [];
+	for (const entry of entries) {
+		if (!entry.isFile()) continue;
+		const logMatch = PROCESS_LOG_PATTERN.exec(entry.name);
+		const auditMatch = PROCESS_AUDIT_PATTERN.exec(entry.name);
+		const pidText = logMatch?.[1] ?? auditMatch?.[1];
+		if (!pidText || processIsRunning(Number(pidText))) continue;
+		const entryPath = path.join(dir, entry.name);
+
+		if (auditMatch) {
+			try {
+				fs.rmSync(entryPath, { force: true });
+			} catch {
+				// Retention is best-effort; logging must still initialize.
+			}
+			continue;
+		}
+
+		try {
+			staleLogs.push({ path: entryPath, mtimeMs: fs.statSync(entryPath).mtimeMs });
+		} catch {
+			// Another process may have pruned the same stale namespace.
+		}
+	}
+
+	staleLogs.sort((a, b) => b.mtimeMs - a.mtimeMs);
+	for (const stale of staleLogs.slice(RETAINED_STALE_LOG_FILES)) {
+		try {
+			fs.rmSync(stale.path, { force: true });
+		} catch {
+			// Another process may have pruned the same stale namespace.
+		}
+	}
+}
 
 /** Ensure a logs directory exists; return the resolved path. */
 function ensureDir(dir: string): string {
@@ -72,15 +168,18 @@ function getLogFormat(): winston.Logform.Format {
 	return logFormat;
 }
 
-/** Build a rotating file transport, materializing the target directory lazily. */
+/** Build a rotating file transport with process-local rotation and shared retention. */
 function makeFileTransport(dir?: string): winston.transport {
+	const logsDir = ensureDir(dir ?? getLogsDir());
+	pruneStaleProcessLogs(logsDir);
 	return new DailyRotateFile({
-		dirname: ensureDir(dir ?? getLogsDir()),
-		filename: "omp.%DATE%.log",
+		dirname: logsDir,
+		filename: `omp.%DATE%.${process.pid}.log`,
 		datePattern: "YYYY-MM-DD",
 		maxSize: "10m",
 		maxFiles: 5,
-		zippedArchive: true,
+		zippedArchive: false,
+		auditFile: path.join(logsDir, `.omp.${process.pid}-audit.json`),
 	});
 }
 
@@ -148,6 +247,7 @@ export function error(message: string, context?: Record<string, unknown>): void
 	} catch {
 		// Silently ignore logging failures
 	}
+	emitToSinks("error", message, context);
 }
 
 /**
@@ -161,6 +261,7 @@ export function warn(message: string, context?: Record<string, unknown>): void {
 	} catch {
 		// Silently ignore logging failures
 	}
+	emitToSinks("warn", message, context);
 }
 
 /**
@@ -174,6 +275,7 @@ export function info(message: string, context?: Record<string, unknown>): void {
 	} catch {
 		// Silently ignore logging failures
 	}
+	emitToSinks("info", message, context);
 }
 
 /**
@@ -187,6 +289,7 @@ export function debug(message: string, context?: Record<string, unknown>): void
 	} catch {
 		// Silently ignore logging failures
 	}
+	emitToSinks("debug", message, context);
 }
 
 /**

package/src/postmortem.ts

@@ -5,6 +5,8 @@
  * in response to process exit, signals, or fatal exceptions. It is intended to
  * allow reliably releasing resources or shutting down subprocesses, files, sockets, etc.
  */
+
+import * as fs from "node:fs";
 import inspector from "node:inspector";
 import { isMainThread } from "node:worker_threads";
 import { logger } from ".";
@@ -68,7 +70,6 @@ function runCleanup(reason: Reason): Promise<void> {
 		cleanupStage = "complete";
 		deadline.resolve();
 	}, CLEANUP_DEADLINE_MS);
-	deadlineTimer.unref();
 	cleanupPromise = Promise.race([cleanupSettled, deadline.promise]).finally(() => {
 		clearTimeout(deadlineTimer);
 	});
@@ -175,6 +176,23 @@ function formatFatalError(label: string, err: Error): string {
 	return `\n[${label}] ${name}: ${message}${formattedStack}\n`;
 }
 
+async function exitAfterFatal(label: string, logMessage: string, err: Error, reason: Reason): Promise<void> {
+	const forcedExit = setTimeout(() => process.exit(1), CLEANUP_DEADLINE_MS);
+	try {
+		restoreTerminalStderr();
+		// A revoked terminal can make stream writes raise another fatal error. Use
+		// the descriptor directly so failure stays synchronous and contained.
+		try {
+			fs.writeSync(2, formatFatalError(label, err));
+		} catch {}
+		logger.error(logMessage, { err });
+		await runCleanup(reason);
+	} finally {
+		clearTimeout(forcedExit);
+		process.exit(1);
+	}
+}
+
 if (isMainThread) {
 	process
 		.on("SIGINT", async () => {
@@ -193,15 +211,7 @@ if (isMainThread) {
 				logger.warn("Ignoring expected cleanup exception", { err });
 				return;
 			}
-			// fd 2 may be redirected to the log while a TUI owns the terminal
-			// (stderr-guard); re-point it at the real terminal so the fatal
-			// report is visible. Terminal modes are restored moments later by
-			// the terminal-restore cleanup callback inside runCleanup().
-			restoreTerminalStderr();
-			process.stderr.write(formatFatalError("Uncaught Exception", err));
-			logger.error("Uncaught exception", { err });
-			await runCleanup(Reason.UNCAUGHT_EXCEPTION);
-			process.exit(1);
+			await exitAfterFatal("Uncaught Exception", "Uncaught exception", err, Reason.UNCAUGHT_EXCEPTION);
 		})
 		.on("unhandledRejection", async reason => {
 			const err = reason instanceof Error ? reason : new Error(String(reason));
@@ -237,12 +247,7 @@ if (isMainThread) {
 					});
 				}
 			}
-			// See uncaughtException above: surface the report on the real stderr.
-			restoreTerminalStderr();
-			process.stderr.write(formatFatalError("Unhandled Rejection", err));
-			logger.error("Unhandled rejection", { err });
-			await runCleanup(Reason.UNHANDLED_REJECTION);
-			process.exit(1);
+			await exitAfterFatal("Unhandled Rejection", "Unhandled rejection", err, Reason.UNHANDLED_REJECTION);
 		})
 		.on("exit", async () => {
 			void runCleanup(Reason.EXIT); // fire and forget (exit imminent)

package/src/ptree.ts

@@ -72,6 +72,7 @@ export class TimeoutError extends AbortError {
 export interface WaitOptions {
 	allowNonZero?: boolean;
 	allowAbort?: boolean;
+	/** `full` requires upfront capture; `exec` enables it, while direct `spawn` callers pass `stderr: "full"`. */
 	stderr?: "full" | "buffer";
 }
 
@@ -97,7 +98,7 @@ export interface ExecResult {
 export class ChildProcess<In extends InMask = InMask> {
 	#nothrow = false;
 	#stderrTail = "";
-	#stderrChunks: Uint8Array[] = [];
+	#stderrChunks?: Uint8Array[];
 	#exitReason?: Exception;
 	#exitReasonPending?: Exception;
 	#stderrDone: Promise<void>;
@@ -107,8 +108,10 @@ export class ChildProcess<In extends InMask = InMask> {
 	constructor(
 		readonly proc: PipedSubprocess<In>,
 		readonly exposeStderr: boolean,
+		retainFullStderr = exposeStderr,
 	) {
-		// Eagerly drain stderr into a truncated tail string + raw chunks.
+		if (retainFullStderr) this.#stderrChunks = [];
+		// Eagerly drain stderr into a truncated tail, retaining raw chunks only for explicit full capture.
 		const dec = new TextDecoder();
 		const trim = () => {
 			if (this.#stderrTail.length > NonZeroExitError.MAX_TRACE)
@@ -123,7 +126,7 @@ export class ChildProcess<In extends InMask = InMask> {
 		this.#stderrDone = (async () => {
 			try {
 				for await (const chunk of stderrStream) {
-					this.#stderrChunks.push(chunk);
+					this.#stderrChunks?.push(chunk);
 					this.#stderrTail += dec.decode(chunk, { stream: true });
 					trim();
 				}
@@ -259,11 +262,15 @@ export class ChildProcess<In extends InMask = InMask> {
 
 	async wait(opts?: WaitOptions): Promise<ExecResult> {
 		const { allowNonZero = false, allowAbort = false, stderr: stderrMode = "buffer" } = opts ?? {};
+		const stderrChunks = this.#stderrChunks;
+		if (stderrMode === "full" && !stderrChunks) {
+			throw new Error('Full stderr capture must be requested when spawning the process (pass stderr: "full")');
+		}
 
 		const stdoutP = new Response(this.stdout).text();
 		const stderrP =
-			stderrMode === "full"
-				? this.#stderrDone.then(() => new TextDecoder().decode(Buffer.concat(this.#stderrChunks)))
+			stderrMode === "full" && stderrChunks
+				? this.#stderrDone.then(() => new TextDecoder().decode(Buffer.concat(stderrChunks)))
 				: this.#stderrDone.then(() => this.#stderrTail);
 
 		const [stdout, stderr] = await Promise.all([stdoutP, stderrP]);
@@ -328,11 +335,15 @@ type ChildSpawnOptions<In extends InMask = InMask> = Omit<
 > & {
 	signal?: AbortSignal;
 	detached?: boolean;
+	/** Expose and retain complete stderr for a later `wait({ stderr: "full" })`. */
 	stderr?: "full" | null;
 };
 
-/** Spawn a child process with piped stdout/stderr. */
-export function spawn<In extends InMask = InMask>(cmd: string[], opts?: ChildSpawnOptions<In>): ChildProcess<In> {
+function spawnInternal<In extends InMask = InMask>(
+	cmd: string[],
+	opts: ChildSpawnOptions<In> | undefined,
+	retainFullStderr: boolean,
+): ChildProcess<In> {
 	const { timeout = -1, signal, stderr, ...rest } = opts ?? {};
 	const child = Bun.spawn(cmd, {
 		stdin: "ignore",
@@ -341,12 +352,17 @@ export function spawn<In extends InMask = InMask>(cmd: string[], opts?: ChildSpa
 		windowsHide: true,
 		...rest,
 	});
-	const cp = new ChildProcess(child, stderr === "full");
+	const cp = new ChildProcess(child, stderr === "full", retainFullStderr);
 	if (signal) cp.attachSignal(signal);
 	if (timeout > 0) cp.attachTimeout(timeout);
 	return cp;
 }
 
+/** Spawn a child process with piped stdout/stderr. */
+export function spawn<In extends InMask = InMask>(cmd: string[], opts?: ChildSpawnOptions<In>): ChildProcess<In> {
+	return spawnInternal(cmd, opts, opts?.stderr === "full");
+}
+
 /** Options for exec. */
 export interface ExecOptions extends Omit<ChildSpawnOptions, "stderr" | "stdin">, WaitOptions {
 	input?: string | Buffer | Uint8Array;
@@ -357,7 +373,7 @@ export async function exec(cmd: string[], opts?: ExecOptions): Promise<ExecResul
 	const { input, stderr, allowAbort, allowNonZero, ...spawnOpts } = opts ?? {};
 	const stdin = typeof input === "string" ? Buffer.from(input) : input;
 	const resolved: ChildSpawnOptions = stdin === undefined ? spawnOpts : { ...spawnOpts, stdin };
-	using child = spawn(cmd, resolved);
+	using child = spawnInternal(cmd, resolved, stderr === "full");
 	return await child.wait({ stderr, allowAbort, allowNonZero });
 }