@linxiraos/pi-utils 1.1.14 → 1.1.16

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 = process.cwd(),
+	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;
+	}
+}

package/src/fetch-retry.ts

@@ -11,17 +11,41 @@ const RETRY_DELAY_FIELD_PATTERN = /"retryDelay":\s*"([0-9.]+)(ms|s)"/i;
 // "try again in 90 minutes" / "try again in 1 hour"
 const TRY_AGAIN_PATTERN = /try again in\s+~?\s*([0-9.]+)\s*(ms|sec|s|minutes?|mins?|m|hours?|hrs?|h)\b/i;
 // "Your limit will reset in 13 minutes" / "reset in 13 minutes" / "will reset in 2h"
-const WILL_RESET_IN_PATTERN = /(?:will\s+)?reset in\s+~?\s*([0-9.]+)\s*(ms|sec|s|minutes?|mins?|m|hours?|hrs?|h)\b/i;
+// OpenCode Go quota errors use "Resets in …" with day units and compound
+// remainders ("Resets in 3 days", "Resets in 2hr 15min", "Resets in 45min").
+const WILL_RESET_IN_PATTERN =
+	/(?:will\s+)?resets?\s+in\s+~?\s*([0-9.]+)\s*(ms|sec|s|minutes?|mins?|m|hours?|hrs?|h|days?|d)\b/i;
+// OpenCode Go compound remainder: "Resets in 2hr 15min".
+const RESET_IN_HR_MIN_PATTERN = /resets?\s+in\s+~?\s*(\d+(?:\.\d+)?)\s*hr\s*(\d+(?:\.\d+)?)\s*min\b/i;
 // "Your limit will reset at 2026-09-01 09:44:51" / "reset at 2026-09-01T09:44:51Z"
 const WILL_RESET_AT_PATTERN =
 	/(?:will\s+)?reset at\s+([0-9]{4}-[0-9]{2}-[0-9]{2}[ T][0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]+)?(?:Z|[+-][0-9]{2}:?[0-9]{2})?)/i;
+// Both grammars carry a timezone-naive wall clock. The default reading is UTC;
+// a provider-specific offset (Z.AI/Zhipu Beijing time) is applied only through
+// `RetryHintOptions.naiveResetTimezoneOffset`, never inferred from the language.
 const CN_RESET_AT_PATTERN = /将在\s*([0-9]{4}-[0-9]{2}-[0-9]{2}\s+[0-9]{2}:[0-9]{2}:[0-9]{2})\s*重置/;
+const RESET_AT_PATTERNS: readonly RegExp[] = [WILL_RESET_AT_PATTERN, CN_RESET_AT_PATTERN];
 // "retry-after-ms=98497000" / "retry-after-ms: 7200000" / "retry-after-ms = 7200000"
 const RETRY_AFTER_MS_BODY_PATTERN = /\bretry-after-ms\s*[:=]\s*([0-9]+)\b/i;
 
+// A timezone-naive `reset at` stamp (no `Z`/offset) is the provider's
+// wall clock in an unknown zone: it cannot be converted to a delay without
+// guessing the zone, so it resolves only as a fallback when the body
+// carries no unambiguous relative signal.
+
+// A conflict probe needs no new signal: when a naive `reset at` wall stamp
+// disagrees with the merged relative wait, the merged wait (which already
+// ignores the naive stamp) sleeps first, and the retry after it is the
+// probe — success proves skew, a fresh 429 re-anchors with live timing.
+
+/** Provider-specific interpretation for timezone-naive retry timestamps. */
+export interface RetryHintOptions {
+	/** UTC offset appended to an absolute reset stamp that omits its timezone. */
+	naiveResetTimezoneOffset?: string;
+}
+
 /**
  * Server-suggested retry delay extraction. Merges the patterns historically used
- * by the OpenAI Codex and Google Gemini retry helpers.
  *
  * Header sources (checked in order):
  *  - `retry-after-ms` (milliseconds)
@@ -37,12 +61,18 @@ const RETRY_AFTER_MS_BODY_PATTERN = /\bretry-after-ms\s*[:=]\s*([0-9]+)\b/i;
  *  - `try again in 250ms` / `try again in 12s` / `try again in 5 min` / `try again in ~158 min`
  *  - `retry-after-ms=98497000` / `retry-after-ms: 7200000` / `retry-after-ms = 7200000`
  *  - `Your limit will reset at 2026-09-01 09:44:51` / `将在 2026-09-01 09:44:51 重置`
+ *    (a provider offset makes a naive wall clock authoritative; otherwise it
+ *    resolves only when no relative signal is present)
  *
  * Returns `undefined` if no signal is found, or `0` when the provider
  * explicitly asks for an immediate retry (`retry-after…=0`, or an absolute
  * reset timestamp that has already elapsed).
  */
-export function extractRetryHint(source: Response | Headers | null | undefined, body?: string): number | undefined {
+export function extractRetryHint(
+	source: Response | Headers | null | undefined,
+	body?: string,
+	options?: RetryHintOptions,
+): number | undefined {
 	const headers = source instanceof Headers ? source : (source?.headers ?? undefined);
 	if (headers) {
 		const retryAfterMs = headers.get("retry-after-ms");
@@ -98,6 +128,15 @@ export function extractRetryHint(source: Response | Headers | null | undefined,
 	// when the parse returns undefined, which would sleep a session the
 	// provider told to retry immediately.
 	let retryNow = false;
+
+	// Timezone-naive `reset at` stamps (no `Z`/offset) are the provider's
+	// wall clock in an unknown zone — converting them to a delay requires
+	// guessing the zone. They resolve AFTER every unambiguous signal below,
+	// and only as a fallback when none was found.
+	let longestNaiveMs: number | undefined;
+	const considerNaive = (ms: number | undefined): void => {
+		if (ms !== undefined && ms > 0 && (longestNaiveMs === undefined || ms > longestNaiveMs)) longestNaiveMs = ms;
+	};
 	const consider = (ms: number | undefined): void => {
 		if (ms !== undefined && ms > 0 && (longestMs === undefined || ms > longestMs)) longestMs = ms;
 	};
@@ -117,16 +156,30 @@ export function extractRetryHint(source: Response | Headers | null | undefined,
 			consider(totalMs > 0 ? totalMs : undefined);
 		}
 	}
-	for (const pattern of [WILL_RESET_AT_PATTERN, CN_RESET_AT_PATTERN]) {
+	for (const pattern of RESET_AT_PATTERNS) {
 		const match = pattern.exec(body);
-		if (match?.[1]) {
-			// Provider timestamps without an explicit offset are interpreted as UTC.
-			const normalized = match[1].replace(" ", "T");
-			const hasOffset = /(?:Z|[+-][0-9]{2}:?[0-9]{2})$/i.test(normalized);
-			const parsed = Date.parse(hasOffset ? normalized : `${normalized}Z`);
-			if (!Number.isNaN(parsed) && parsed > Date.now()) {
-				consider(parsed - Date.now());
-			}
+		if (!match?.[1]) continue;
+		// Offset-bearing stamps are unambiguous and compete by longest-wins.
+		// A configured provider offset makes an otherwise naive wall clock
+		// unambiguous too. Without one, preserve the relative-signal-first
+		// fallback and interpret the wall clock as UTC only when it stands alone.
+		const normalized = match[1].replace(" ", "T");
+		const hasOffset = /(?:Z|[+-][0-9]{2}:?[0-9]{2})$/i.test(normalized);
+		const configuredOffset = options?.naiveResetTimezoneOffset;
+		const parsed = Date.parse(hasOffset ? normalized : `${normalized}${configuredOffset ?? "Z"}`);
+		if (!Number.isNaN(parsed) && parsed > Date.now()) {
+			if (hasOffset || configuredOffset !== undefined) consider(parsed - Date.now());
+			else considerNaive(parsed - Date.now());
+		}
+	}
+	// OpenCode Go compound remainder ("Resets in 2hr 15min"): the generic
+	// pattern only captures the leading "2hr", so add the trailing minutes.
+	const compoundResetMatch = RESET_IN_HR_MIN_PATTERN.exec(body);
+	if (compoundResetMatch?.[1] && compoundResetMatch[2]) {
+		const hours = Number.parseFloat(compoundResetMatch[1]);
+		const minutes = Number.parseFloat(compoundResetMatch[2]);
+		if (Number.isFinite(hours) && Number.isFinite(minutes) && hours >= 0 && minutes > 0) {
+			consider(hours * 60 * 60_000 + minutes * 60_000);
 		}
 	}
 	const accountResetMatch = WILL_RESET_IN_PATTERN.exec(body);
@@ -188,7 +241,9 @@ export function extractRetryHint(source: Response | Headers | null | undefined,
 			considerClamped(resetSeconds > 1_000_000_000 ? resetSeconds * 1000 - Date.now() : resetSeconds * 1000);
 		}
 	}
-	return longestMs ?? (retryNow ? 0 : undefined);
+	// Elapsed naive stamps were ignored before this change and stay ignored:
+	// only an explicit zero/expired relative signal is authoritative retry-now.
+	return longestMs ?? longestNaiveMs ?? (retryNow ? 0 : undefined);
 }
 
 function unitToMs(unit: string): number | undefined {
@@ -210,6 +265,10 @@ function unitToMs(unit: string): number | undefined {
 		case "hour":
 		case "hours":
 			return 60 * 60_000;
+		case "d":
+		case "day":
+		case "days":
+			return 24 * 60 * 60_000;
 		default:
 			return undefined;
 	}

package/src/file-lock.ts

@@ -17,6 +17,16 @@ export interface FileLockOptions {
 	staleMs?: number;
 }
 
+/** An exclusive OS-backed lease. Releasing an already released handle is safe. */
+export interface FileLockHandle {
+	release(): void;
+}
+
+/** An exclusive OS-backed lease. Releasing an already released handle is safe. */
+export interface FileLockHandle {
+	release(): void;
+}
+
 const DEFAULT_OPTIONS: Required<FileLockOptions> = {
 	retries: 50,
 	retryDelayMs: 100,
@@ -32,7 +42,8 @@ function tryAcquireLock(lockPath: string): NativeFileLock | null {
 	return lock.acquired ? lock : null;
 }
 
-async function acquireLock(filePath: string, options: FileLockOptions = {}): Promise<NativeFileLock> {
+/** Acquire an exclusive lease; callers must release it when their operation ends. */
+export async function acquireFileLock(filePath: string, options: FileLockOptions = {}): Promise<FileLockHandle> {
 	const opts = { ...DEFAULT_OPTIONS, ...options };
 	const lockPath = getLockPath(filePath);
 
@@ -45,13 +56,26 @@ async function acquireLock(filePath: string, options: FileLockOptions = {}): Pro
 	throw new Error(`Failed to acquire lock for ${filePath} after ${opts.retries} attempts`);
 }
 
+function acquireLockSync(filePath: string, options: FileLockOptions = {}): NativeFileLock {
+	const opts = { ...DEFAULT_OPTIONS, ...options };
+	const lockPath = getLockPath(filePath);
+
+	for (let attempt = 0; attempt < opts.retries; attempt++) {
+		const lock = tryAcquireLock(lockPath);
+		if (lock) return lock;
+		if (attempt + 1 < opts.retries && opts.retryDelayMs > 0) Bun.sleepSync(opts.retryDelayMs);
+	}
+
+	throw new Error(`Failed to acquire lock for ${filePath} after ${opts.retries} attempts`);
+}
+
 /** Run `fn` while holding an OS-backed exclusive lock for `filePath`. */
 export async function withFileLock<T>(
 	filePath: string,
 	fn: () => Promise<T>,
 	options: FileLockOptions = {},
 ): Promise<T> {
-	const lock = await acquireLock(filePath, options);
+	const lock = await acquireFileLock(filePath, options);
 	try {
 		return await fn();
 	} finally {
@@ -59,6 +83,16 @@ export async function withFileLock<T>(
 	}
 }
 
+/** Run synchronous `fn` while holding an OS-backed exclusive lock for `filePath`. */
+export function withFileLockSync<T>(filePath: string, fn: () => T, options: FileLockOptions = {}): T {
+	const lock = acquireLockSync(filePath, options);
+	try {
+		return fn();
+	} finally {
+		lock.release();
+	}
+}
+
 /**
  * Test-only acquisition handle for forcing ownership handoffs. This is not
  * part of the supported package API.

package/src/format.ts

@@ -58,6 +58,22 @@ export function formatBytes(bytes: number): string {
 	return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)}GB`;
 }
 
+/**
+ * Count `\n` code units via native `indexOf` — no split array, roughly an
+ * order of magnitude cheaper than a per-code-unit loop on multi-MiB text.
+ * Line-count semantics are the caller's (empty text is 0 or 1 lines
+ * depending on the contract).
+ */
+export function countNewlines(text: string): number {
+	let count = 0;
+	let pos = text.indexOf("\n");
+	while (pos !== -1) {
+		count++;
+		pos = text.indexOf("\n", pos + 1);
+	}
+	return count;
+}
+
 /**
  * Truncate a string to maxLen characters, appending an ellipsis if truncated.
  * For display-width-aware truncation (terminals), use truncateToWidth from @linxiraos/pi-tui.

package/src/index.ts

@@ -4,12 +4,12 @@ export * from "./binary";
 export * from "./color";
 export * from "./dirs";
 export * from "./env";
+export * from "./executable";
 export * from "./fetch-retry";
 export * from "./file-lock";
 export * from "./format";
 export * from "./frontmatter";
 export * from "./fs-error";
-export * from "./glob";
 export * from "./incoming-json";
 export * from "./json";
 export * from "./json-parse";
@@ -40,6 +40,7 @@ export * from "./tls-fetch";
 export * from "./type-guards";
 export * from "./version";
 export * from "./which";
+export * from "./yaml-config";
 
 function isPlainObject(val: object): val is Record<string, unknown> {
 	return Object.getPrototypeOf(val) === Object.prototype || Array.isArray(val);

package/src/json.ts

@@ -19,7 +19,18 @@ export function tryParseJson<T = unknown>(content: string): T | null {
  * only lossless JSON representation.
  */
 export function stringifyJson(value: unknown, space?: string | number): string | undefined {
-	return JSON.stringify(value, (_key, item) => (typeof item === "bigint" ? item.toString() : item), space);
+	// Fast path: a replacer forces the slow stringify on every call, but
+	// bigint payloads are vanishingly rare. Try plain stringify first and
+	// retry with the coercing replacer only on TypeError (the only error a
+	// bigint raises). A TypeError from elsewhere (circular value, throwing
+	// toJSON) recurs on the retry and surfaces from that second walk, so
+	// stateful serializers ahead of a bigint run twice on that path.
+	try {
+		return JSON.stringify(value, undefined, space);
+	} catch (error) {
+		if (!(error instanceof TypeError)) throw error;
+		return JSON.stringify(value, (_key, item) => (typeof item === "bigint" ? item.toString() : item), space);
+	}
 }
 
 function stableJsonClone(value: unknown): unknown {

package/src/logger/rotating-file.ts

@@ -47,6 +47,12 @@ export class RotatingFileSink {
 	#activePath: string | undefined;
 	#activeBytes = 0;
 	#closed = false;
+	// Held append fd: the old code did open+write+close per line
+	// (appendFileSync) plus a throwaway open in the constructor. A single fd
+	// per active file removes two syscalls per log line; it is reopened on
+	// rotation and closed on close()/rotation (required for Windows
+	// delete-on-prune semantics).
+	#fd: number | undefined;
 
 	constructor(options: RotatingFileOptions) {
 		this.#directory = options.directory;
@@ -61,26 +67,57 @@ export class RotatingFileSink {
 		const activePath = this.#activePath;
 		if (activePath) {
 			this.#registerFile(activePath, now.getTime());
-			fs.closeSync(fs.openSync(activePath, "a"));
+			this.#openFd(activePath);
+		}
+	}
+
+	#openFd(filePath: string): void {
+		this.#closeFd();
+		this.#fd = fs.openSync(filePath, "a");
+	}
+
+	#closeFd(): void {
+		if (this.#fd !== undefined) {
+			try {
+				fs.closeSync(this.#fd);
+			} catch {
+				// Best-effort: the fd may already be invalid after rotation.
+			}
+			this.#fd = undefined;
 		}
 	}
 
 	/** Append one already-formatted log record. */
 	write(line: string): void {
 		if (this.#closed) return;
+		const prevPath = this.#activePath;
 		const now = new Date();
 		this.#selectFile(this.#localDay(now));
 		const activePath = this.#activePath;
 		if (!activePath) return;
+		// Rotation moved the active path: close the old descriptor BEFORE
+		// registering the new path, because registration prunes beyond
+		// maxFiles — on Windows the pruned predecessor cannot be deleted
+		// while still open, which would leak it (audit entry removed, file
+		// left on disk, retention unbounded).
+		if (activePath !== prevPath) this.#closeFd();
 		this.#registerFile(activePath, now.getTime());
+		if (this.#fd === undefined) this.#openFd(activePath);
 		const record = `${line}${os.EOL}`;
-		fs.appendFileSync(activePath, record, "utf8");
-		this.#activeBytes += Buffer.byteLength(record);
+		const buf = Buffer.from(record, "utf8");
+		let off = 0;
+		while (off < buf.length) {
+			const written = fs.writeSync(this.#fd!, buf, off);
+			if (written <= 0) break;
+			off += written;
+		}
+		this.#activeBytes += buf.length;
 	}
 
 	/** Stop accepting records. Synchronous writes require no drain phase. */
 	close(): void {
 		this.#closed = true;
+		this.#closeFd();
 	}
 
 	#localDay(date: Date): string {

package/src/logger.ts

@@ -152,6 +152,19 @@ function pruneStaleProcessLogs(dir: string): void {
 	}
 }
 
+const scheduledPruneDirs = new Set<string>();
+
+/** Run shared retention only after logger construction has returned to the event loop. */
+function schedulePruneStaleProcessLogs(dir: string): void {
+	if (scheduledPruneDirs.has(dir)) return;
+	scheduledPruneDirs.add(dir);
+	const immediate = setImmediate(() => {
+		scheduledPruneDirs.delete(dir);
+		pruneStaleProcessLogs(dir);
+	});
+	immediate.unref();
+}
+
 /** Ensure a logs directory exists; return the resolved path. */
 function ensureDir(dir: string): string {
 	if (!fs.existsSync(dir)) {
@@ -237,7 +250,7 @@ function formatLogInfo(info: NormalizedLogInfo): string {
 /** Build a rotating file sink with process-local rotation and shared retention. */
 function makeFileTransport(dir?: string): RotatingFileSink {
 	const logsDir = ensureDir(dir ?? getLogsDir());
-	pruneStaleProcessLogs(logsDir);
+	schedulePruneStaleProcessLogs(logsDir);
 	return new RotatingFileSink({
 		directory: logsDir,
 		filenamePrefix: "zeta",
@@ -276,12 +289,11 @@ function getLocalTransports(): LocalTransports {
 
 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;
-
+	const info = normalizeLogInfo(level, message, context);
 	const line = formatLogInfo(info);
 	if (transports.file) transports.file.write(line);
-	if (transports.console) fs.writeSync(1, `${formatLogInfo(info)}${os.EOL}`);
+	if (transports.console) fs.writeSync(1, `${line}${os.EOL}`);
 }
 
 /**

package/src/mime.ts

@@ -1,7 +1,6 @@
 import { peekFile, peekFileSync } from "./peek-file";
 
-const DEFAULT_IMAGE_METADATA_HEADER_BYTES = 256 * 1024;
-
+export const IMAGE_METADATA_HEADER_BYTES = 256 * 1024;
 const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 const JPEG_MAGIC = Buffer.from([0xff, 0xd8, 0xff]);
 const WEBP_RIFF_MAGIC = Buffer.from([0x52, 0x49, 0x46, 0x46]);
@@ -144,16 +143,13 @@ export function parseImageMetadata(header: Uint8Array): ImageMetadata | null {
 	);
 }
 
-export function readImageMetadataSync(
-	filePath: string,
-	maxBytes = DEFAULT_IMAGE_METADATA_HEADER_BYTES,
-): ImageMetadata | null {
+export function readImageMetadataSync(filePath: string, maxBytes = IMAGE_METADATA_HEADER_BYTES): ImageMetadata | null {
 	return peekFileSync(filePath, maxBytes, parseImageMetadata);
 }
 
 export function readImageMetadata(
 	filePath: string,
-	maxBytes = DEFAULT_IMAGE_METADATA_HEADER_BYTES,
+	maxBytes = IMAGE_METADATA_HEADER_BYTES,
 ): Promise<ImageMetadata | null> {
 	return peekFile(filePath, maxBytes, parseImageMetadata);
 }

package/src/path.ts

@@ -40,3 +40,17 @@ export function stripWindowsExtendedLengthPathPrefix(
 
 	return filePath;
 }
+
+/**
+ * Test whether a path is fully qualified and drive-independent.
+ * On Windows, requires a drive letter with separator (e.g. `C:\`) or UNC (`\\server\share` or `//server/share`).
+ * On POSIX, requires an absolute path.
+ */
+export function isFullyQualifiedPath(filePath: string, platform: NodeJS.Platform = process.platform): boolean {
+	const p = platform === "win32" ? path.win32 : path.posix;
+	if (!p.isAbsolute(filePath)) return false;
+	if (platform === "win32") {
+		return /^[a-zA-Z]:[/\\]/.test(filePath) || /^[\\/]{2}[^\\/]/.test(filePath);
+	}
+	return true;
+}