@oh-my-pi/pi-utils 17.1.7 → 17.2.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [17.1.8] - 2026-07-28
+
+### Added
+
+- Added `setProcessName` utility to set the OS-visible process name on Linux via `bun:ffi`, bypassing Bun's `process.title` limitations.
+
+### Fixed
+
+- Fixed child shell environment filtering to drop launch-directory `.env` values in addition to Bun-autoloaded `.env.local` values.
+
 ## [17.1.5] - 2026-07-27
 
 ### Fixed

package/dist/types/env.d.ts

@@ -17,13 +17,12 @@ export declare function isSafeEnvName(name: string): boolean;
 export declare function isSafeEnvValue(value: string): boolean;
 export declare function isMacosMallocStackLoggingEnvName(name: string): boolean;
 export declare function filterProcessEnv(env: Record<string, string | undefined>): Record<string, string>;
-/** Filters process env for child shells without launch-cwd `.env.local` values. */
+/** Filters process env for child shells without launch-cwd dotenv values. */
 export declare function filterChildShellEnv(env: Record<string, string | undefined>, cwd?: string): Record<string, string>;
 /**
- * Parses a .env file synchronously and extracts key-value string pairs.
- * Ignores lines that are empty or start with '#'. Trims whitespace.
- * Allows values to be quoted with single or double quotes.
- * Returns an object of key-value pairs.
+ * Parses a .env file synchronously into key-value string pairs using
+ * {@link parseEnvLine} for Bun-compatible line semantics, then mirrors valid
+ * `OMP_` variables to their `PI_` aliases.
  */
 export declare function parseEnvFile(filePath: string): Record<string, string>;
 /**

package/dist/types/index.d.ts

@@ -19,6 +19,7 @@ export * from "./path.js";
 export * from "./path-tree.js";
 export * from "./peek-file.js";
 export * as postmortem from "./postmortem.js";
+export * from "./process-name.js";
 export * as procmgr from "./procmgr.js";
 export * as prompt from "./prompt.js";
 export * as ptree from "./ptree.js";

package/dist/types/postmortem.d.ts

@@ -64,10 +64,15 @@ export declare function register(id: string, callback: (reason: Reason) => void
  * Use this in workers or when you need to clean up but continue execution.
  */
 export declare function cleanup(): Promise<void>;
+/** Controls how manual process shutdown handles terminal output. */
+export interface QuitOptions {
+    /** Wait for buffered stdout before exiting; disable after the terminal has disconnected. */
+    drainStdout?: boolean;
+}
 /**
  * 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 unless disabled, then calls `process.exit()`.
  * In workers: runs cleanup only (process.exit would kill entire process).
  */
-export declare function quit(code?: number): Promise<void>;
+export declare function quit(code?: number, options?: QuitOptions): Promise<void>;

package/dist/types/process-name.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Set both the JS `process.title` and — on Linux — the kernel `comm` name.
+ *
+ * Never throws: `bun:ffi` unavailability or a failed syscall degrades silently
+ * to the `process.title`-only behavior, so it is safe to call at startup.
+ */
+export declare function setProcessName(name: string): void;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "17.1.7",
+	"version": "17.2.0",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -31,10 +31,10 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "17.1.7",
+		"@oh-my-pi/pi-natives": "17.2.0",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",
-		"winston-daily-rotate-file": "^5.0.0"
+		"winston-daily-rotate-file": "5.0.0"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/env.ts

@@ -52,50 +52,132 @@ export function filterProcessEnv(env: Record<string, string | undefined>): Recor
 	}
 	return result;
 }
+// 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
+// keeps the original exec environment in procfs, which is authoritative.
+function readLaunchEnv(): ReadonlyMap<string, string> | undefined {
+	if (process.platform === "linux") {
+		try {
+			const values = new Map<string, string>();
+			for (const entry of fs.readFileSync("/proc/self/environ", "utf8").split("\0")) {
+				const separator = entry.indexOf("=");
+				if (separator > 0) values.set(entry.slice(0, separator), entry.slice(separator + 1));
+			}
+			return values;
+		} catch {}
+	}
+	if (!process.execArgv.includes("--no-env-file")) return undefined;
+	const values = new Map<string, string>();
+	for (const key in Bun.env) {
+		const value = Bun.env[key];
+		if (value !== undefined) values.set(key, value);
+	}
+	return values;
+}
 
-/** Filters process env for child shells without launch-cwd `.env.local` values. */
+const launchEnvValues = readLaunchEnv();
+const projectEnvNamesLoadedByOmp = new Set<string>();
+
+function expandDotenvValues(values: Record<string, string>, env: Record<string, string>): Record<string, string> {
+	const expanded: Record<string, string> = {};
+	for (const key in values) {
+		expanded[key] = values[key].replace(
+			/(\\)?\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/g,
+			(match, escaped: string | undefined, braced: string | undefined, bare: string | undefined) => {
+				if (escaped) return match.slice(1);
+				const name = braced ?? bare;
+				if (!name) return match;
+				return env[name] ?? expanded[name] ?? "";
+			},
+		);
+	}
+	return expanded;
+}
+
+/** Filters process env for child shells without launch-cwd dotenv values. */
 export function filterChildShellEnv(
 	env: Record<string, string | undefined>,
 	cwd: string = process.cwd(),
 ): Record<string, string> {
 	const result = filterProcessEnv(env);
-	const launchLocalEnv = parseEnvFile(path.join(cwd, ".env.local"));
-	for (const key in launchLocalEnv) {
-		if (result[key] === launchLocalEnv[key]) delete result[key];
+	const projectEnv = parseEnvFile(path.join(cwd, ".env"));
+	const nodeEnvName = `.env.${env.NODE_ENV || "development"}`;
+	const modeEnv = parseEnvFile(path.join(cwd, nodeEnvName));
+	const localEnv = parseEnvFile(path.join(cwd, ".env.local"));
+	const launchEnv = { ...projectEnv, ...modeEnv, ...localEnv };
+	const expandedLaunchEnv = {
+		...expandDotenvValues(projectEnv, result),
+		...expandDotenvValues(modeEnv, result),
+		...expandDotenvValues(localEnv, result),
+	};
+	for (const key in launchEnv) {
+		const launchValue = launchEnvValues?.get(key);
+		if (launchValue !== undefined) {
+			// Launcher-owned name: it keeps the launcher's own value. Bun overwrites
+			// an empty launcher value with the dotenv one, so restore the launcher
+			// value whenever what survived is exactly what the dotenv file defines.
+			if (
+				result[key] !== launchValue &&
+				(result[key] === launchEnv[key] || result[key] === expandedLaunchEnv[key])
+			) {
+				result[key] = launchValue;
+			}
+			continue;
+		}
+		if (launchEnvValues || projectEnvNamesLoadedByOmp.has(key)) {
+			// 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.
+			delete result[key];
+		} else if (result[key] === launchEnv[key] || result[key] === expandedLaunchEnv[key]) {
+			// No launch-env snapshot (dotenv autoloaded without procfs): best-effort
+			// value match against the Bun-parsed dotenv.
+			delete result[key];
+		}
 	}
 	return result;
 }
 
 /**
- * Parses a .env file synchronously and extracts key-value string pairs.
- * Ignores lines that are empty or start with '#'. Trims whitespace.
- * Allows values to be quoted with single or double quotes.
- * Returns an object of key-value pairs.
+ * 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() };
+}
+
+/**
+ * Parses a .env file synchronously into key-value string pairs using
+ * {@link parseEnvLine} for Bun-compatible line semantics, then mirrors valid
+ * `OMP_` variables to their `PI_` aliases.
  */
 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 trimmed = line.trim();
-			// Skip comments and blank lines
-			if (!trimmed || trimmed.startsWith("#")) continue;
-
-			const eqIndex = trimmed.indexOf("=");
-			if (eqIndex === -1) continue;
-
-			const key = trimmed.slice(0, eqIndex).trim();
-			if (!isValidEnvName(key)) continue;
-
-			let value = trimmed.slice(eqIndex + 1).trim();
-
-			// Remove surrounding quotes (" or ')
-			if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
-				value = value.slice(1, -1);
-			}
-			if (!isSafeEnvValue(value)) continue;
-
-			result[key] = value;
+			const parsed = parseEnvLine(line);
+			if (parsed && isSafeEnvValue(parsed.value)) result[parsed.key] = parsed.value;
 		}
 	} catch {
 		// File doesn't exist or can't be read - return empty result
@@ -128,6 +210,7 @@ for (const file of [projectEnv, agentEnv, piEnv, homeEnv]) {
 	for (const key in file) {
 		if (!isMacosMallocStackLoggingEnvName(key) && !Bun.env[key]) {
 			Bun.env[key] = file[key];
+			if (file === projectEnv) projectEnvNamesLoadedByOmp.add(key);
 		}
 	}
 }

package/src/index.ts

@@ -19,6 +19,7 @@ export * from "./path";
 export * from "./path-tree";
 export * from "./peek-file";
 export * as postmortem from "./postmortem";
+export * from "./process-name";
 export * as procmgr from "./procmgr";
 export * as prompt from "./prompt";
 export * as ptree from "./ptree";

package/src/logger.ts

@@ -1,3 +1,5 @@
+/// <reference path="./winston-daily-rotate-file.d.ts" />
+
 /**
  * Centralized logger for omp.
  *
@@ -11,10 +13,13 @@
  */
 import { AsyncLocalStorage } from "node:async_hooks";
 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
 import { isPromise } from "node:util/types";
-import winston from "winston";
-import DailyRotateFile from "winston-daily-rotate-file";
+import type DailyRotateFile from "winston-daily-rotate-file";
+// Import the implementation directly because the package index imports and mutates
+// Winston. The exact workspace catalog pin protects this internal entrypoint.
+import DailyRotateFileImplementation from "winston-daily-rotate-file/daily-rotate-file.js";
 import { getLogsDir } from "./dirs";
 import { drainModuleLoadEvents } from "./timing-buffer";
 /** Severity names accepted by the centralized logger. */
@@ -143,36 +148,68 @@ function jsonReplacer(_key: string, value: unknown): unknown {
 	return value;
 }
 
-/** Custom format that includes pid and flattens metadata; built on first use. */
-let logFormat: winston.Logform.Format | undefined;
-
-function getLogFormat(): winston.Logform.Format {
-	logFormat ??= winston.format.combine(
-		winston.format.timestamp({ format: "YYYY-MM-DDTHH:mm:ss.SSSZ" }),
-		winston.format.printf(({ timestamp, level, message, ...meta }) => {
-			const entry: Record<string, unknown> = {
-				timestamp,
-				level,
-				pid: process.pid,
-				message,
-			};
-			// Flatten metadata into entry
-			for (const [key, value] of Object.entries(meta)) {
-				if (key !== "level" && key !== "timestamp" && key !== "message") {
-					entry[key] = value;
-				}
-			}
-			return JSON.stringify(entry, jsonReplacer);
-		}),
+interface NormalizedLogInfo extends Record<string, unknown> {
+	level: LogLevel;
+	message: unknown;
+}
+
+function padTimestampPart(value: number, width = 2): string {
+	return String(value).padStart(width, "0");
+}
+
+function formatLocalTimestamp(date: Date): string {
+	const offsetMinutes = -date.getTimezoneOffset();
+	const absoluteOffset = Math.abs(offsetMinutes);
+	const offsetSign = offsetMinutes >= 0 ? "+" : "-";
+	return (
+		`${padTimestampPart(date.getFullYear(), 4)}-${padTimestampPart(date.getMonth() + 1)}-${padTimestampPart(date.getDate())}` +
+		`T${padTimestampPart(date.getHours())}:${padTimestampPart(date.getMinutes())}:${padTimestampPart(date.getSeconds())}` +
+		`.${padTimestampPart(date.getMilliseconds(), 3)}${offsetSign}${padTimestampPart(Math.floor(absoluteOffset / 60))}` +
+		`:${padTimestampPart(absoluteOffset % 60)}`
 	);
-	return logFormat;
 }
 
+const FORMAT_TOKEN_PATTERN = /%[scdjifoO%]/;
+
+function normalizeLogInfo(
+	level: LogLevel,
+	message: string,
+	context: Record<string, unknown> | undefined,
+): NormalizedLogInfo {
+	const metadata =
+		!FORMAT_TOKEN_PATTERN.test(message) && context !== null && typeof context === "object" ? context : undefined;
+	const info = Object.assign({}, metadata, { level, message }) as NormalizedLogInfo;
+	if (metadata?.message) info.message = `${message} ${metadata.message}`;
+	if (metadata?.stack) info.stack = metadata.stack;
+	if (metadata?.cause) info.cause = metadata.cause;
+	return info;
+}
+
+function formatLogInfo(info: NormalizedLogInfo): string {
+	const timestamp = formatLocalTimestamp(new Date());
+	info.timestamp = timestamp;
+	const entry: Record<string, unknown> = {
+		timestamp,
+		level: info.level,
+		pid: process.pid,
+		message: info.message,
+	};
+	for (const [key, value] of Object.entries(info)) {
+		if (key !== "level" && key !== "timestamp" && key !== "message") entry[key] = value;
+	}
+	return JSON.stringify(entry, jsonReplacer) as string;
+}
+
+type FileTransport = DailyRotateFile & {
+	log(info: Record<symbol, string>, callback: () => void): void;
+	close(): void;
+};
+
 /** Build a rotating file transport with process-local rotation and shared retention. */
-function makeFileTransport(dir?: string): winston.transport {
+function makeFileTransport(dir?: string): FileTransport {
 	const logsDir = ensureDir(dir ?? getLogsDir());
 	pruneStaleProcessLogs(logsDir);
-	return new DailyRotateFile({
+	return new DailyRotateFileImplementation({
 		dirname: logsDir,
 		filename: `omp.%DATE%.${process.pid}.log`,
 		datePattern: "YYYY-MM-DD",
@@ -180,45 +217,48 @@ function makeFileTransport(dir?: string): winston.transport {
 		maxFiles: 5,
 		zippedArchive: false,
 		auditFile: path.join(logsDir, `.omp.${process.pid}-audit.json`),
-	});
-}
-
-function makeConsoleTransport(): winston.transport {
-	return new winston.transports.Console({ format: getLogFormat() });
+	}) as FileTransport;
 }
 
 /**
- * Desired transport configuration, applied when the winston logger is built.
+ * Desired transport configuration, applied when local logging is initialized.
  * Default: file ON (TUI-safe), console OFF.
  */
 let transportOpts: { console?: boolean; file?: boolean | string } = { file: true };
 
-/** The winston logger instance, created lazily on first log emission. */
-let winstonLogger: winston.Logger | undefined;
+interface LocalTransports {
+	readonly file: FileTransport | undefined;
+	readonly console: boolean;
+}
+
+/** Local transports, constructed lazily on first log emission. */
+let activeTransports: LocalTransports | undefined;
+
+const TRANSPORT_MESSAGE = Symbol.for("message");
+const onTransportLogged = (): void => {};
 
-function buildTransports(opts: { console?: boolean; file?: boolean | string }): winston.transport[] {
-	const transports: winston.transport[] = [];
-	if (opts.file) transports.push(makeFileTransport(typeof opts.file === "string" ? opts.file : undefined));
-	if (opts.console) transports.push(makeConsoleTransport());
-	return transports;
+function buildTransports(opts: { console?: boolean; file?: boolean | string }): LocalTransports {
+	return {
+		file: opts.file ? makeFileTransport(typeof opts.file === "string" ? opts.file : undefined) : undefined,
+		console: opts.console === true,
+	};
 }
 
-function getWinstonLogger(): winston.Logger {
-	if (!winstonLogger) {
-		const transports = buildTransports(transportOpts);
-		winstonLogger = winston.createLogger({
-			level: "debug",
-			format: getLogFormat(),
-			transports,
-			// A transport-less winston logger console.warns "Attempt to write logs
-			// with no transports" on every emit; mark it silent instead so disabling
-			// all transports is a clean no-op.
-			silent: transports.length === 0,
-			// Don't exit on error - logging failures shouldn't crash the app
-			exitOnError: false,
-		});
-	}
-	return winstonLogger;
+function getLocalTransports(): LocalTransports {
+	activeTransports ??= buildTransports(transportOpts);
+	return activeTransports;
+}
+
+function emitLocally(level: LogLevel, message: string, context: Record<string, unknown> | undefined): void {
+	const transports = getLocalTransports();
+	const info = normalizeLogInfo(level, message, context);
+	if (!transports.file && !transports.console) return;
+
+	// Winston applied the shared format before dispatch, then the same format a
+	// second time inside Console. Keep those evaluation and timestamp semantics.
+	const line = formatLogInfo(info);
+	if (transports.file) transports.file.log({ [TRANSPORT_MESSAGE]: line }, onTransportLogged);
+	if (transports.console) process.stdout.write(`${formatLogInfo(info)}${os.EOL}`);
 }
 
 /**
@@ -228,12 +268,11 @@ function getWinstonLogger(): winston.Logger {
  */
 export function setTransports(opts: { console?: boolean; file?: boolean | string }): void {
 	transportOpts = opts;
-	if (!winstonLogger) return; // applied lazily when the logger is first built
-	winstonLogger.clear();
-	const transports = buildTransports(opts);
-	for (const transport of transports) winstonLogger.add(transport);
-	// Keep the logger silent when nothing is attached so winston doesn't warn on emit.
-	winstonLogger.silent = transports.length === 0;
+	if (!activeTransports) return; // applied lazily when local logging is first initialized
+	const previousTransports = activeTransports;
+	activeTransports = { file: undefined, console: false };
+	previousTransports.file?.close();
+	activeTransports = buildTransports(opts);
 }
 
 /**
@@ -243,7 +282,7 @@ export function setTransports(opts: { console?: boolean; file?: boolean | string
  */
 export function error(message: string, context?: Record<string, unknown>): void {
 	try {
-		getWinstonLogger().error(message, context);
+		emitLocally("error", message, context);
 	} catch {
 		// Silently ignore logging failures
 	}
@@ -257,7 +296,7 @@ export function error(message: string, context?: Record<string, unknown>): void
  */
 export function warn(message: string, context?: Record<string, unknown>): void {
 	try {
-		getWinstonLogger().warn(message, context);
+		emitLocally("warn", message, context);
 	} catch {
 		// Silently ignore logging failures
 	}
@@ -271,7 +310,7 @@ export function warn(message: string, context?: Record<string, unknown>): void {
  */
 export function info(message: string, context?: Record<string, unknown>): void {
 	try {
-		getWinstonLogger().info(message, context);
+		emitLocally("info", message, context);
 	} catch {
 		// Silently ignore logging failures
 	}
@@ -285,7 +324,7 @@ export function info(message: string, context?: Record<string, unknown>): void {
  */
 export function debug(message: string, context?: Record<string, unknown>): void {
 	try {
-		getWinstonLogger().debug(message, context);
+		emitLocally("debug", message, context);
 	} catch {
 		// Silently ignore logging failures
 	}

package/src/postmortem.ts

@@ -319,14 +319,20 @@ export function cleanup(): Promise<void> {
 	return runCleanup(Reason.MANUAL);
 }
 
-async function runQuit(code: number, exitMode: "guarded" | "native"): Promise<void> {
+/** Controls how manual process shutdown handles terminal output. */
+export interface QuitOptions {
+	/** Wait for buffered stdout before exiting; disable after the terminal has disconnected. */
+	drainStdout?: boolean;
+}
+
+async function runQuit(code: number, exitMode: "guarded" | "native", options: QuitOptions = {}): Promise<void> {
 	await runCleanup(Reason.MANUAL);
 
 	if (!isMainThread) {
 		return; // Workers: cleanup done, let worker exit naturally
 	}
 
-	if (process.stdout.writableLength > 0) {
+	if (options.drainStdout !== false && process.stdout.writableLength > 0) {
 		const { promise, resolve } = Promise.withResolvers<void>();
 		process.stdout.once("drain", resolve);
 		await Promise.race([promise, Bun.sleep(5000)]);
@@ -343,9 +349,9 @@ async function runQuit(code: number, exitMode: "guarded" | "native"): Promise<vo
 /**
  * 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 unless disabled, 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");
+export function quit(code: number = 0, options: QuitOptions = {}): Promise<void> {
+	return runQuit(code, "guarded", options);
 }

package/src/process-name.ts

@@ -0,0 +1,57 @@
+/**
+ * Set the OS-visible process name (`/proc/self/comm`) so `omp` shows up as
+ * `omp` — not `bun` — in `ps`, `pgrep`, `killall`, `top`, `htop`, and systemd.
+ *
+ * Bun's `process.title` setter only stores the value on the JS side; unlike
+ * Node/libuv it never calls `prctl(PR_SET_NAME)`, so the kernel's `comm` stays
+ * `bun` and process-name-based tooling can't target omp (and `pkill bun` becomes
+ * a footgun that kills every Bun process on the machine). We keep the
+ * `process.title` assignment (correct getter, future-proof if Bun ever fixes the
+ * setter) and additionally drive `prctl` via `bun:ffi` on Linux, mirroring the
+ * libc-FFI pattern in `ttyid.ts` / `stderr-guard.ts`.
+ *
+ * macOS has no clean userspace equivalent for the shebang-run path, and on
+ * Windows / compiled binaries the kernel derives the name from the exec'd file,
+ * so those paths already report correctly; there we only set `process.title`.
+ */
+import { dlopen, FFIType, ptr } from "bun:ffi";
+import * as os from "node:os";
+
+/** `prctl(2)` option that sets the calling thread's `comm` name. */
+const PR_SET_NAME = 15;
+
+/**
+ * Set both the JS `process.title` and — on Linux — the kernel `comm` name.
+ *
+ * Never throws: `bun:ffi` unavailability or a failed syscall degrades silently
+ * to the `process.title`-only behavior, so it is safe to call at startup.
+ */
+export function setProcessName(name: string): void {
+	try {
+		process.title = name;
+	} catch {}
+
+	if (os.platform() !== "linux") return;
+
+	// glibc first, then the generic soname for musl-style layouts (see stderr-guard.ts).
+	for (const soname of ["libc.so.6", "libc.so"]) {
+		try {
+			const libc = dlopen(soname, {
+				prctl: {
+					args: [FFIType.i32, FFIType.ptr, FFIType.u64, FFIType.u64, FFIType.u64],
+					returns: FFIType.i32,
+				},
+			});
+			try {
+				// TASK_COMM_LEN is 16 (name + NUL); the kernel truncates the rest.
+				const buf = Buffer.from(`${name}\0`, "utf8");
+				libc.symbols.prctl(PR_SET_NAME, ptr(buf), 0n, 0n, 0n);
+			} finally {
+				libc.close();
+			}
+			return;
+		} catch {
+			// bun:ffi unavailable or this soname missing; try the next candidate.
+		}
+	}
+}

package/src/winston-daily-rotate-file.d.ts

@@ -0,0 +1,6 @@
+declare module "winston-daily-rotate-file/daily-rotate-file.js" {
+	import type DailyRotateFile from "winston-daily-rotate-file";
+
+	const DailyRotateFileImplementation: typeof DailyRotateFile;
+	export default DailyRotateFileImplementation;
+}