@oh-my-pi/pi-utils 15.12.4 → 15.13.0

package/CHANGELOG.md

@@ -2,53 +2,24 @@
 
 ## [Unreleased]
 
-## [15.12.4] - 2026-06-13
-
-### Fixed
-
-- Fixed abortable stream wrappers to cancel the source stream on abort, so timeout watchdogs release upstream HTTP bodies instead of only stopping the local reader.
-
-## [15.12.0] - 2026-06-12
-
 ### Added
 
+- Added support for a runtime `overrides` map in `RuntimeInstallSpec`, which is now written into generated runtime `package.json` manifests to force dependency pins (including transitive ones) across the runtime tree
+- Added a lightweight loop-phase breadcrumb stack (`pushLoopPhase`/`popLoopPhase`/`currentLoopPhase`, plus `takeRecentLoopPhase` which returns the live phase or the most recently popped one and clears it) so the TUI event-loop watchdog can attribute a main-thread block to the phase that caused it — including a synchronous phase already popped before the watchdog's delayed tick runs ([#2485](https://github.com/can1357/oh-my-pi/issues/2485))
+- Added `FetchWithRetryOptions.timeout` (forwarded to the underlying `fetch` call). `false` disables Bun's native ~300s pre-response timeout; a positive number overrides the ceiling. Bare browser/Node fetch ignores it ([#2422](https://github.com/can1357/oh-my-pi/issues/2422))
 - Added `runtime-install`: shared on-demand runtime dependency support — `ensureRuntimeInstalled()` (locked, idempotent `bun install` of a pinned dependency set into a cache dir) and a multi-root `installRuntimeModuleResolver()`/`resolveRuntimeModule()` for loading those graphs inside compiled binaries (Bun #1763). Extracted from the coding-agent tiny-model worker; now also backs Mnemopi's on-demand fastembed runtime ([#2389](https://github.com/can1357/oh-my-pi/issues/2389))
 - Added `getFastembedRuntimeDir()` (~/.omp/cache/fastembed-runtime) alongside `getFastembedCacheDir()`
-
-## [15.11.4] - 2026-06-12
-
-### Added
-
 - Added `getEditorConfigFormatting(file)`: returns the `.editorconfig`-pinned `tabSize`/`insertSpaces` (both optional, no fallback) so LSP-format callers can layer per-file defaults under it without paving over silence with the renderer's display tab width ([#2329](https://github.com/can1357/oh-my-pi/issues/2329)).
-
-## [15.11.3] - 2026-06-11
-
-### Added
-
-- Added `getEditorConfigFormatting(file)`: returns the `.editorconfig`-pinned `tabSize`/`insertSpaces` (both optional, no fallback) so LSP-format callers can layer per-file defaults under it without paving over silence with the renderer's display tab width ([#2329](https://github.com/can1357/oh-my-pi/issues/2329)).
-
-## [15.11.1] - 2026-06-11
-
-### Fixed
-
-- Fixed cleanup reentry noise during fatal shutdown: recursive cleanup requests now no-op idempotently instead of logging repeated `Cleanup invoked recursively` errors ([#2284](https://github.com/can1357/oh-my-pi/issues/2284)).
-
-## [15.11.0] - 2026-06-10
-
-### Added
-
 - Added the `path-tree` module (`buildPathTree`, `walkPathTree`, `formatGroupedPaths`, `isUrlLikePath`), moved from the coding agent's grouped file output so compaction file lists can share the same prefix-folded directory-tree rendering; `formatGroupedPaths` gains an optional `annotate` callback for per-file suffixes
-
-### Fixed
-
-- Fixed the `{{join}}` prompt helper joining with a literal two-character `\n` when templates pass `"\n"` as the separator — Handlebars string literals carry no escape processing. The separator now unescapes `\n`/`\t`, matching the `{{#list}}` helper's documented convention (visible as literal `\n` between paths in compaction `<read-files>` lists).
-
-## [15.10.11] - 2026-06-10
-### Added
-
 - Restored `PI_DEBUG_STARTUP` streaming startup markers: `logger.time` now writes a synchronous `[startup] <op>:start` / `:done` / `:fail` stderr line per phase (independent of `PI_TIMING`), so a startup that hangs hard still names the phase it is stuck in — the `PI_TIMING` tree only prints after startup completes and is structurally unable to diagnose a hang. The CLI runner emits `cli:load:<name>` markers around each lazily-imported command module for the same reason.
 - Added `logger.openSpanPath()`: ops of the currently-open timing-span chain (root → deepest), used by the coding agent's startup watchdog to name the in-flight phase of a stalled startup.
 - Added `declareWorkerHostEntry()` / `workerHostEntry()` (env): self-dispatching CLI entrypoints declare `Bun.main` as the worker host so worker spawn sites can re-enter the single entry module with `WorkerOptions.argv` selectors across source, npm-bundle, and compiled distributions
+- Added `getAuthBrokerSnapshotCachePath()` with `OMP_AUTH_BROKER_SNAPSHOT_CACHE` override support for isolating the encrypted broker snapshot cache.
+- Added color helpers `colorLuma` (perceptual luma), `relativeLuminance` (WCAG, linearized sRGB), and `hslToHex` to the color utilities. The luminance helpers parse `#rgb`/`#rrggbb` hex and 256-color palette indices, returning `undefined` for unparseable values.
+- Added `peekFileEnds`, a single-open head-and-tail file peek helper that reuses the head bytes for the tail when the file fits the head window.
+- Added `peekFileTail`, the tail mirror of `peekFile`: reads up to the last `maxBytes` of a file ending at EOF, reusing the same pooled-buffer strategy (no per-call allocation for small reads).
+- Added `getFastembedCacheDir` to return the FastEmbed model cache directory under ~/.omp/cache/fastembed
+- Added an XDG-aware tiny-title model cache directory helper for coding-agent local title models.
 
 ### Changed
 
@@ -56,59 +27,52 @@
 - `Snowflake.formatParts` packs the id as a single 64-bit BigInt hex format instead of stitching four 16-bit segments (simpler and ~1.7x faster), and `getTimestamp` extracts via exact double arithmetic instead of a BigInt round-trip. Output is bit-identical.
 - Logger initialization is lazy: the winston logger, file transport, and log-directory creation now happen on first log emission instead of at module import (the import previously cost ~8ms of fs work on the CLI startup path); the in-memory timing infrastructure never touches winston
 - `prompt.format()` post-processing got cheap per-line guards and a single-pass ASCII-symbol replacement (was 7 chained regex passes per line), roughly halving render post-processing cost; output is byte-identical
+- `logger.printTimings()` (the `PI_TIMING` startup tree) now surfaces two previously-invisible regions: a `(before instrumentation)` line for runtime init / uncaptured pre-marker work, and an `(unattributed self)` line for the root span's own untimed work so the gap between visible top-level spans and `Total` is no longer swallowed. `Total` is now labelled `(since first marker)` to make the window explicit. The restored `module-timer.ts` preload can feed module spans into the report: each module records `onLoad` → final top-level marker as `total`, a prepended body marker → final marker as `body/TLA`, and resolved static imports as a bounded dependency tree so the report separates graph wait from actual top-level module work.
 
 ### Fixed
 
+- Made `TempDir` cleanup retry transient Windows `EBUSY`/`EPERM`/`ENOTEMPTY` removal failures so tests are less likely to fail when deleting just-used temp directories.
+- Fixed abortable stream wrappers to cancel the source stream on abort, so timeout watchdogs release upstream HTTP bodies instead of only stopping the local reader.
+- Fixed cleanup reentry noise during fatal shutdown: recursive cleanup requests now no-op idempotently instead of logging repeated `Cleanup invoked recursively` errors ([#2284](https://github.com/can1357/oh-my-pi/issues/2284)).
+- Fixed the `{{join}}` prompt helper joining with a literal two-character `\n` when templates pass `"\n"` as the separator — Handlebars string literals carry no escape processing. The separator now unescapes `\n`/`\t`, matching the `{{#list}}` helper's documented convention (visible as literal `\n` between paths in compaction `<read-files>` lists).
 - Fixed `prompt.format()` so ASCII symbol replacements such as `-->` and `!=` still run on lines containing a closing HTML comment token when not inside a comment
 - `isCompiledBinary()` now also honors a define-folded `process.env.PI_COMPILED` (only `Bun.env` was checked), so builds that constant-fold `process.env` keep compiled-binary detection without relying on `import.meta.url` bunfs markers
 - `omp <cmd> --help` now loads only the requested command module instead of the entire command table, so an unrelated command whose import graph hangs or crashes can no longer take down every per-command help invocation.
+- Hardened `getIndentation` against malformed paths: any filesystem error from the `.editorconfig` probe (e.g. `ENAMETOOLONG` on oversized garbage path segments) is now swallowed and cached as a miss instead of escaping and crashing the TUI mid-render ([#1871](https://github.com/can1357/oh-my-pi/issues/1871)).
+- Fixed `getIndentation` (and the edit renderer's `replaceTabs` callers) crashing with `ENAMETOOLONG`/`ENOTDIR`/etc. when handed a path with an overlong component or a non-directory in its parent chain. Editorconfig discovery now short-circuits to the default tab width on any path component above `NAME_MAX` (255 bytes) and absorbs any `FsError` while walking the editorconfig chain — best-effort discovery must never escape as an uncaught exception ([#1872](https://github.com/can1357/oh-my-pi/issues/1872)).
+- Fixed `$flag` environment parsing to accept lowercase truthy values such as `y`, `true`, `yes`, and `on`
 
-## [15.10.8] - 2026-06-09
 ### Removed
 
 - Removed the exported `hookFetch` API, which previously intercepted `globalThis.fetch` via middleware handlers
 - Removed `hookFetch` from the package entrypoint, so imports from `@.../utils` no longer provide this fetch interception helper
 
-## [15.10.0] - 2026-06-06
+## [15.13.0] - 2026-06-14
 
-### Changed
+## [15.12.4] - 2026-06-13
 
-- `logger.printTimings()` (the `PI_TIMING` startup tree) now surfaces two previously-invisible regions: a `(before instrumentation)` line for runtime init / uncaptured pre-marker work, and an `(unattributed self)` line for the root span's own untimed work so the gap between visible top-level spans and `Total` is no longer swallowed. `Total` is now labelled `(since first marker)` to make the window explicit. The restored `module-timer.ts` preload can feed module spans into the report: each module records `onLoad` → final top-level marker as `total`, a prepended body marker → final marker as `body/TLA`, and resolved static imports as a bounded dependency tree so the report separates graph wait from actual top-level module work.
+## [15.12.0] - 2026-06-12
 
-## [15.9.2] - 2026-06-05
+## [15.11.4] - 2026-06-12
 
-### Added
+## [15.11.3] - 2026-06-11
 
-- Added `getAuthBrokerSnapshotCachePath()` with `OMP_AUTH_BROKER_SNAPSHOT_CACHE` override support for isolating the encrypted broker snapshot cache.
+## [15.11.1] - 2026-06-11
 
-## [15.9.1] - 2026-06-04
+## [15.11.0] - 2026-06-10
 
-### Fixed
+## [15.10.11] - 2026-06-10
 
-- Hardened `getIndentation` against malformed paths: any filesystem error from the `.editorconfig` probe (e.g. `ENAMETOOLONG` on oversized garbage path segments) is now swallowed and cached as a miss instead of escaping and crashing the TUI mid-render ([#1871](https://github.com/can1357/oh-my-pi/issues/1871)).
-- Fixed `getIndentation` (and the edit renderer's `replaceTabs` callers) crashing with `ENAMETOOLONG`/`ENOTDIR`/etc. when handed a path with an overlong component or a non-directory in its parent chain. Editorconfig discovery now short-circuits to the default tab width on any path component above `NAME_MAX` (255 bytes) and absorbs any `FsError` while walking the editorconfig chain — best-effort discovery must never escape as an uncaught exception ([#1872](https://github.com/can1357/oh-my-pi/issues/1872)).
+## [15.10.8] - 2026-06-09
 
-## [15.9.0] - 2026-06-04
+## [15.10.0] - 2026-06-06
 
-### Added
+## [15.9.2] - 2026-06-05
 
-- Added color helpers `colorLuma` (perceptual luma), `relativeLuminance` (WCAG, linearized sRGB), and `hslToHex` to the color utilities. The luminance helpers parse `#rgb`/`#rrggbb` hex and 256-color palette indices, returning `undefined` for unparseable values.
-- Added `peekFileEnds`, a single-open head-and-tail file peek helper that reuses the head bytes for the tail when the file fits the head window.
+## [15.9.1] - 2026-06-04
 
-- Added `peekFileTail`, the tail mirror of `peekFile`: reads up to the last `maxBytes` of a file ending at EOF, reusing the same pooled-buffer strategy (no per-call allocation for small reads).
+## [15.9.0] - 2026-06-04
 
 ## [15.7.3] - 2026-05-31
 
-### Added
-
-- Added `getFastembedCacheDir` to return the FastEmbed model cache directory under ~/.omp/cache/fastembed
-
-### Fixed
-
-- Fixed `$flag` environment parsing to accept lowercase truthy values such as `y`, `true`, `yes`, and `on`
-
 ## [15.6.0] - 2026-05-30
-
-### Added
-
-- Added an XDG-aware tiny-title model cache directory helper for coding-agent local title models.

package/dist/types/fetch-retry.d.ts

@@ -43,6 +43,14 @@ export interface FetchWithRetryOptions extends RequestInit {
      * mock during tests.
      */
     fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+    /**
+     * Bun extension forwarded verbatim to the underlying `fetch` call. `false`
+     * disables Bun's native ~300s pre-response timeout (callers that own a
+     * configurable first-event/idle watchdog or an external `AbortSignal`
+     * supply this so the runtime ceiling cannot pre-empt them); a positive
+     * number sets a custom ceiling in ms. Bare browser/Node fetch ignores it.
+     */
+    timeout?: number | false;
 }
 /**
  * Fetch with bounded retries and sensible defaults. Retries on any

package/dist/types/index.d.ts

@@ -10,6 +10,7 @@ export * from "./fs-error";
 export * from "./glob";
 export * from "./json";
 export * as logger from "./logger";
+export * from "./loop-phase";
 export * from "./mermaid-ascii";
 export * from "./mime";
 export * from "./path-tree";

package/dist/types/loop-phase.d.ts

@@ -0,0 +1,10 @@
+export declare function pushLoopPhase(label: string): void;
+export declare function popLoopPhase(): void;
+export declare function currentLoopPhase(): string | undefined;
+/**
+ * Phase to blame for a just-detected loop block: the live top phase if one is
+ * still held, else the most recent phase pushed since the last call. Clears the
+ * recent slot so a block in a later, phase-less interval is not misattributed
+ * to a phase that already finished.
+ */
+export declare function takeRecentLoopPhase(): string | undefined;

package/dist/types/runtime-install.d.ts

@@ -43,6 +43,8 @@ export declare function installRuntimeModuleResolver({ runtimeNodeModules, stubs
 /** Pinned dependency set materialized into a runtime cache directory. */
 export interface RuntimeInstallSpec {
     dependencies: Record<string, string>;
+    /** Version pins forced across the whole runtime tree (bun `overrides`), e.g. dislodging a transitive dep. */
+    overrides?: Record<string, string>;
     /** Packages whose lifecycle scripts bun may run during the install. */
     trustedDependencies?: string[];
 }
@@ -58,6 +60,7 @@ export interface EnsureRuntimeInstalledOptions {
     lockAttempts?: number;
     lockSleepMs?: number;
 }
+export declare function writeRuntimeManifest(runtimeDir: string, install: RuntimeInstallSpec): Promise<void>;
 /**
  * Materialize a pinned dependency set into `runtimeDir` (idempotent,
  * cross-process safe via a lock directory). Returns `runtimeDir`.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-utils",
-	"version": "15.12.4",
+	"version": "15.13.0",
 	"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": "15.12.4",
+		"@oh-my-pi/pi-natives": "15.13.0",
 		"beautiful-mermaid": "^1.1.3",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",

package/src/fetch-retry.ts

@@ -129,6 +129,14 @@ export interface FetchWithRetryOptions extends RequestInit {
 	 * mock during tests.
 	 */
 	fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+	/**
+	 * Bun extension forwarded verbatim to the underlying `fetch` call. `false`
+	 * disables Bun's native ~300s pre-response timeout (callers that own a
+	 * configurable first-event/idle watchdog or an external `AbortSignal`
+	 * supply this so the runtime ceiling cannot pre-empt them); a positive
+	 * number sets a custom ceiling in ms. Bare browser/Node fetch ignores it.
+	 */
+	timeout?: number | false;
 }
 
 const DEFAULT_MAX_DELAY_MS = 60_000;

package/src/index.ts

@@ -10,6 +10,7 @@ export * from "./fs-error";
 export * from "./glob";
 export * from "./json";
 export * as logger from "./logger";
+export * from "./loop-phase";
 export * from "./mermaid-ascii";
 export * from "./mime";
 export * from "./path-tree";

package/src/loop-phase.ts

@@ -0,0 +1,49 @@
+/**
+ * Live event-loop phase breadcrumb. Hot synchronous paths push a short label
+ * before running and pop it after (via `try`/`finally`); the loop watchdog
+ * reads {@link takeRecentLoopPhase} when it detects a block, so a stall is
+ * logged with the work that caused it instead of an opaque "unknown".
+ *
+ * This is deliberately a process-global stack and not part of the logger span
+ * machinery: `main.ts` ends timing spans before the interactive TUI starts, so
+ * `logger.openSpanPath()` is empty in a live session.
+ *
+ * Correctness constraint: each `pushLoopPhase` must be balanced by a
+ * `popLoopPhase` within the SAME synchronous execution (always via `try`/
+ * `finally`). The stack is global and shared, so a label held across an
+ * `await`/async boundary — or interleaved between concurrent tasks — would
+ * misattribute or leak phases. Instrument only synchronous spans; for async
+ * work, push/pop around each synchronous chunk, not across the await.
+ */
+const stack: string[] = [];
+// The most recent label pushed, retained after it is popped. A hot path pushes
+// and pops a phase entirely within one synchronous macrotask, so by the time
+// the watchdog's delayed tick runs the stack is already empty; this slot keeps
+// the culprit available for that one tick. Consumed (cleared) on read so it
+// only attributes the just-elapsed interval.
+let recentPhase: string | undefined;
+
+export function pushLoopPhase(label: string): void {
+	stack.push(label);
+	recentPhase = label;
+}
+
+export function popLoopPhase(): void {
+	stack.pop();
+}
+
+export function currentLoopPhase(): string | undefined {
+	return stack[stack.length - 1];
+}
+
+/**
+ * Phase to blame for a just-detected loop block: the live top phase if one is
+ * still held, else the most recent phase pushed since the last call. Clears the
+ * recent slot so a block in a later, phase-less interval is not misattributed
+ * to a phase that already finished.
+ */
+export function takeRecentLoopPhase(): string | undefined {
+	const phase = stack[stack.length - 1] ?? recentPhase;
+	recentPhase = undefined;
+	return phase;
+}

package/src/runtime-install.ts

@@ -242,6 +242,8 @@ export function installRuntimeModuleResolver({ runtimeNodeModules, stubs = {} }:
 /** Pinned dependency set materialized into a runtime cache directory. */
 export interface RuntimeInstallSpec {
 	dependencies: Record<string, string>;
+	/** Version pins forced across the whole runtime tree (bun `overrides`), e.g. dislodging a transitive dep. */
+	overrides?: Record<string, string>;
 	/** Packages whose lifecycle scripts bun may run during the install. */
 	trustedDependencies?: string[];
 }
@@ -281,13 +283,14 @@ async function acquireInstallLock(runtimeDir: string, attempts: number, sleepMs:
 	throw new Error(`Timed out waiting for runtime install lock: ${lockDir}`);
 }
 
-async function writeRuntimeManifest(runtimeDir: string, install: RuntimeInstallSpec): Promise<void> {
+export async function writeRuntimeManifest(runtimeDir: string, install: RuntimeInstallSpec): Promise<void> {
 	await fsp.mkdir(runtimeDir, { recursive: true });
 	const manifest: Record<string, unknown> = {
 		private: true,
 		type: "module",
 		dependencies: install.dependencies,
 	};
+	if (install.overrides && Object.keys(install.overrides).length) manifest.overrides = install.overrides;
 	if (install.trustedDependencies?.length) manifest.trustedDependencies = install.trustedDependencies;
 	await Bun.write(path.join(runtimeDir, "package.json"), `${JSON.stringify(manifest, null, "\t")}\n`);
 }

package/src/temp.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import * as fsPromises from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
 
@@ -13,7 +14,7 @@ export class TempDir {
 	}
 
 	static async create(prefix?: string): Promise<TempDir> {
-		return new TempDir(await fs.promises.mkdtemp(normalizePrefix(prefix)));
+		return new TempDir(await fsPromises.mkdtemp(normalizePrefix(prefix)));
 	}
 
 	#removePromise: Promise<void> | null = null;
@@ -30,13 +31,13 @@ export class TempDir {
 		if (this.#removePromise) {
 			return this.#removePromise;
 		}
-		const removePromise = fs.promises.rm(this.#path, { recursive: true, force: true });
+		const removePromise = removeWithRetries(this.#path);
 		this.#removePromise = removePromise;
 		return removePromise;
 	}
 
 	removeSync(): void {
-		fs.rmSync(this.#path, { recursive: true, force: true });
+		removeSyncWithRetries(this.#path);
 		this.#removePromise = Promise.resolve();
 	}
 
@@ -75,3 +76,55 @@ function normalizePrefix(prefix?: string): string {
 	}
 	return prefix;
 }
+
+const kRemoveOptions = { recursive: true, force: true } as const;
+const kRemoveRetries = 4;
+const kRemoveRetryDelayMs = 10;
+const kRetryableRemoveErrorCodes = new Set(["EBUSY", "EPERM", "ENOTEMPTY"]);
+const kSleepBuffer = new Int32Array(new SharedArrayBuffer(4));
+
+async function removeWithRetries(target: string): Promise<void> {
+	for (let attempt = 0; ; attempt++) {
+		try {
+			await fsPromises.rm(target, kRemoveOptions);
+			return;
+		} catch (err) {
+			if (!shouldRetryRemove(err, attempt)) throw err;
+			await Bun.sleep(kRemoveRetryDelayMs);
+		}
+	}
+}
+
+function removeSyncWithRetries(target: string): void {
+	for (let attempt = 0; ; attempt++) {
+		try {
+			fs.rmSync(target, kRemoveOptions);
+			return;
+		} catch (err) {
+			if (!shouldRetryRemove(err, attempt)) throw err;
+			sleepSync(kRemoveRetryDelayMs);
+		}
+	}
+}
+
+function shouldRetryRemove(err: unknown, attempt: number): boolean {
+	return attempt < kRemoveRetries && process.platform === "win32" && isRetryableRemoveError(err);
+}
+
+function isRetryableRemoveError(err: unknown): boolean {
+	return (
+		typeof err === "object" &&
+		err !== null &&
+		"code" in err &&
+		typeof err.code === "string" &&
+		kRetryableRemoveErrorCodes.has(err.code)
+	);
+}
+
+function sleepSync(ms: number): void {
+	if ("sleepSync" in Bun && typeof Bun.sleepSync === "function") {
+		Bun.sleepSync(ms);
+		return;
+	}
+	Atomics.wait(kSleepBuffer, 0, 0, ms);
+}