@oh-my-pi/pi-utils 18.1.22 → 18.2.1

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 ## [Unreleased]
 
+## [18.2.1] - 2026-09-15
+
+### Added
+
+- Added the public `postmortem.exitProcess()` utility for host-owned hard exits that must bypass temporary process-exit guards ([#11789](https://github.com/can1357/oh-my-pi/issues/11789)).
+- Added `readSseJsonOrText`: like `readSseJson`, but a `data:` frame that is not valid JSON is yielded as its raw text instead of raising a `SyntaxError`, so a consumer can classify a reverse proxy's plain-text throttle page (`429 Too Many Requests`) that arrives after the stream headers were already sent. `readSseJson` is unchanged and shares the framing with it.
+
+### Fixed
+
+- Reading an EPUB, PPTX or XLSX whose XML has a mismatched or stray end tag no longer hangs the session forever; the parser recovers and the document converts ([#12018](https://github.com/can1357/oh-my-pi/pull/12018) by [@kaluli123123](https://github.com/kaluli123123)).
+- Fixed `filterChildShellEnv` forwarding the host process's `GIT_DIR`, `GIT_WORK_TREE`, and related repo-location overrides to child shells, where `git` would ignore the command's `cwd`.
+- ACP JSON-RPC now drains accepted inbound requests on clean stdin EOF before resolving `closed`, so in-flight methods such as `session/new` still receive a success or explicit error response instead of being dropped on exit 0 ([#11567](https://github.com/can1357/oh-my-pi/issues/11567)).
+- Fixed provider-local usage-limit reset timestamps making `waitForUsageReset` sessions resume up to eight hours late while preserving longest-window semantics for naive UTC timestamps ([#11014](https://github.com/can1357/oh-my-pi/issues/11014)).
+- `registerStdioDisconnectHandling()` now drives graceful shutdown from `process.stdout`'s own `error` event, so a closed stdout consumer exits cleanly while an unrelated write EPIPE (subprocess stdin, socket) stays fatal ([#10930](https://github.com/can1357/oh-my-pi/issues/10930)).
+- Fixed Linux `ptree` timeout cleanup occasionally leaving session-escaped descendants running during subreaper adoption.
+
+## [18.2.0] - 2026-09-15
+
+### Breaking Changes
+
+- Removed the unused `globPaths`, `loadGitignorePatterns`, and `GlobPathsOptions` exports.
+- Browser helpers now manage Chrome only: removed `Browser`, `BrowserTag`, `resolveBuildId()`, `getInstalledBrowsers()`, and `browser` options/metadata; `getDownloadUrl()` now takes `(platform, buildId, baseUrl?)`.
+
+### Added
+
+- Added `relativePathWithinNormalizedRoot()` for reusing canonical paths across containment checks.
+- Added `sleepLong()` and `MAX_TIMER_DELAY_MS`: an abortable sleep that chunks delays past the signed 32-bit timer ceiling so day-scale provider waits elapse instead of overflowing the timer.
+
+### Changed
+
+- Log-retention cleanup now runs after logger construction without keeping short-lived commands alive.
+- Debugger support now loads only when SIGUSR1 requests it.
+
+### Fixed
+
+- Fixed `extractRetryHint` dropping OpenCode Go's `Resets in …` quota window (`45min`, `2hr 15min`, `3 days`): the `reset in` pattern now accepts `Resets` phrasing, `hr`/`day` units, and compound `2hr 15min` remainders, so exhausted Go credentials block for the server-stated window instead of the 60s heuristic guess. ([#12091](https://github.com/can1357/oh-my-pi/pull/12091) by [@H4vC](https://github.com/H4vC))
+- Async file-peek callbacks now receive stable `Uint8Array` windows with copying `slice()` semantics.
+- Dotenv loading now handles multiline values and escapes consistently with Bun, preventing project values from leaking into child-shell environments.
+- SSE readers now support lone-CR line endings and CRLF split across chunks without merging or delaying events.
+
 ## [18.1.22] - 2026-09-14
 
 ### Fixed

package/THIRD-PARTY-NOTICES.txt

@@ -10843,7 +10843,7 @@ RUST RUNTIME DEPENDENCY LICENSES
 
 Generated from Cargo.lock by cargo-about 0.8.2 in locked, offline, workspace, all-feature, all-target mode, then restricted using cargo metadata to normal and build edges reachable from the workspace (development-only edges are excluded). cargo-deny independently evaluates the complete all-target graph.
 
-Native Opus (audiopus/audiopus_sys) and PCRE2 (pcre2/pcre2-sys) are covered by the exact crate license payloads below. inferno 0.12.8 is package-scoped as CDDL-1.0: its CDDL-covered source remains available in the locked crates.io source archive at https://crates.io/crates/inferno/0.12.8 and https://github.com/jonhoo/inferno. The full locked license text follows below.
+Native Opus (opus/opusic-sys) and PCRE2 (pcre2/pcre2-sys) are covered by the exact crate license payloads below. inferno 0.12.8 is package-scoped as CDDL-1.0: its CDDL-covered source remains available in the locked crates.io source archive at https://crates.io/crates/inferno/0.12.8 and https://github.com/jonhoo/inferno. The full locked license text follows below.
 
 -------------------------------------------------------------------------------
 License: Apache License 2.0 (Apache-2.0)
@@ -12509,6 +12509,58 @@ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
+-------------------------------------------------------------------------------
+License: BSD 3-Clause "New" or "Revised" License (BSD-3-Clause)
+Used by:
+- opusic-sys 0.7.5 (https://github.com/DoumanAsh/opusic-sys)
+
+Full license text:
+
+Copyright 2001-2023 Xiph.Org, Skype Limited, Octasic,
+                    Jean-Marc Valin, Timothy B. Terriberry,
+                    CSIRO, Gregory Maxwell, Mark Borgerding,
+                    Erik de Castro Lopo, Mozilla, Amazon
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+- Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+
+- Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+
+- Neither the name of Internet Society, IETF or IETF Trust, nor the
+names of specific contributors, may be used to endorse or promote
+products derived from this software without specific prior written
+permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
+OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Opus is subject to the royalty-free patent licenses which are
+specified at:
+
+Xiph.Org Foundation:
+https://datatracker.ietf.org/ipr/1524/
+
+Microsoft Corporation:
+https://datatracker.ietf.org/ipr/1914/
+
+Broadcom Corporation:
+https://datatracker.ietf.org/ipr/1526/
+
 -------------------------------------------------------------------------------
 License: BSD 3-Clause "New" or "Revised" License (BSD-3-Clause)
 Used by:
@@ -13290,29 +13342,6 @@ jurisdiction of the Federal Courts of the Northern District of
 California and the state courts of the State of California, with
 venue lying in Santa Clara County, California.
 
--------------------------------------------------------------------------------
-License: ISC License (ISC)
-Used by:
-- audiopus_sys 0.2.2 (https://github.com/lakelezz/audiopus_sys.git)
-
-Full license text:
-
-ISC License
-
-Copyright (c) 2019, Lakelezz
-
-Permission to use, copy, modify, and/or distribute this software for any
-purpose with or without fee is hereby granted, provided that the above
-copyright notice and this permission notice appear in all copies.
-
-THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
-WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
-MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
-ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
-WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
-ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
-OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-
 -------------------------------------------------------------------------------
 License: ISC License (ISC)
 Used by:
@@ -18734,7 +18763,7 @@ DEALINGS IN THE SOFTWARE.
 -------------------------------------------------------------------------------
 License: MIT License (MIT)
 Used by:
-- opus 0.3.1 (https://github.com/SpaceManiac/opus-rs)
+- opus 0.4.0 (https://github.com/SpaceManiac/opus-rs)
 
 Full license text:
 

package/dist/types/async.d.ts

@@ -1,3 +1,28 @@
+/**
+ * Largest delay `setTimeout` (and `timers/promises` `scheduler.wait`)
+ * accepts without 32-bit signed overflow: larger values wrap and fire
+ * almost immediately instead of sleeping. Chunk day-scale provider waits
+ * (e.g. a monthly quota reset parsed from an error hint) so the full
+ * duration elapses instead of overflowing the timer.
+ */
+export declare const MAX_TIMER_DELAY_MS = 2147483647;
+/**
+ * Abortable sleep for arbitrarily long delays. Waits longer than
+ * {@link MAX_TIMER_DELAY_MS} chunk the sleep into back-to-back timer waits
+ * so no single timer overflows; an abort during any chunk rejects like
+ * `scheduler.wait`.
+ *
+ * The remainder is deliberately consumed by chunk, not recomputed from a
+ * monotonic deadline: deadline tracking never terminates under the repo's
+ * instant `scheduler.wait` mocks (retry-cap suites spy it to resolve
+ * immediately, so `deadline - performance.now()` never reaches zero and the
+ * loop spins forever). A premature native wake (Bun `uv_async_send`, see
+ * `sleepAtLeast` in `packages/agent/src/utils/yield.ts`) can therefore
+ * under-wait by the unelapsed chunk time — but that self-corrects downstream:
+ * credential blocks carry the true deadline independently of this sleep, so
+ * an early retry re-hits 429 and re-sleeps on a fresh server hint.
+ */
+export declare function sleepLong(delayMs: number, signal?: AbortSignal): Promise<void>;
 /**
  * Wrap a promise with a timeout and optional abort signal.
  * Rejects with the given error or a new error containing the given message if

package/dist/types/browsers.d.ts

@@ -1,12 +1,3 @@
-/** Behavior-compatible reimplementation of @puppeteer/browsers' used surface. */
-/** Supported browser products. */
-export declare enum Browser {
-    CHROME = "chrome",
-    CHROMEHEADLESSSHELL = "chrome-headless-shell",
-    CHROMIUM = "chromium",
-    FIREFOX = "firefox",
-    CHROMEDRIVER = "chromedriver"
-}
 /** Browser download platform identifiers. */
 export declare enum BrowserPlatform {
     LINUX = "linux",
@@ -16,17 +7,6 @@ export declare enum BrowserPlatform {
     WIN32 = "win32",
     WIN64 = "win64"
 }
-/** Chrome-for-Testing release channel tags accepted by {@link resolveBuildId}. */
-export declare enum BrowserTag {
-    CANARY = "canary",
-    NIGHTLY = "nightly",
-    BETA = "beta",
-    DEV = "dev",
-    DEVEDITION = "devedition",
-    STABLE = "stable",
-    ESR = "esr",
-    LATEST = "latest"
-}
 /** Download progress reported while a browser archive is streamed to disk. */
 export interface BrowserDownloadProgress {
     downloadedBytes: number;
@@ -34,7 +14,6 @@ export interface BrowserDownloadProgress {
 }
 /** Inputs used to locate an installed browser executable. */
 export interface ComputeExecutablePathOptions {
-    browser: Browser;
     buildId: string;
     cacheDir: string;
     platform?: BrowserPlatform;
@@ -44,9 +23,8 @@ export interface InstallOptions extends ComputeExecutablePathOptions {
     baseUrl?: string;
     downloadProgressCallback?: (progress: BrowserDownloadProgress) => void;
 }
-/** Metadata for one browser installation found in a Puppeteer cache. */
+/** Metadata for a managed Chrome installation in Puppeteer's cache layout. */
 export interface InstalledBrowser {
-    browser: Browser;
     buildId: string;
     platform: BrowserPlatform;
     path: string;
@@ -54,15 +32,9 @@ export interface InstalledBrowser {
 }
 /** Detect the current host's Puppeteer browser platform. */
 export declare function detectBrowserPlatform(): BrowserPlatform | undefined;
-/** Resolve a Chrome-for-Testing channel, milestone, or build prefix to a full build ID. */
-export declare function resolveBuildId(browser: Browser, _platform: BrowserPlatform, tag: string | BrowserTag): Promise<string>;
 /** Return the Chrome-for-Testing archive URL for a browser build. */
-export declare function getDownloadUrl(browser: Browser, platform: BrowserPlatform, buildId: string, baseUrl?: string): URL;
+export declare function getDownloadUrl(platform: BrowserPlatform, buildId: string, baseUrl?: string): URL;
 /** Compute the executable path in Puppeteer's cache layout. */
 export declare function computeExecutablePath(options: ComputeExecutablePathOptions): string;
-/** Scan a Puppeteer cache for browser installation directories. */
-export declare function getInstalledBrowsers(options: {
-    cacheDir: string;
-}): Promise<InstalledBrowser[]>;
 /** Download and unpack Chrome into Puppeteer's existing cache layout. */
 export declare function install(options: InstallOptions): Promise<InstalledBrowser>;

package/dist/types/dirs.d.ts

@@ -44,6 +44,16 @@ export declare function resolveProfileEnv(omp: string | undefined, pi: string |
 export declare function getBaseConfigRoot(): string;
 export declare function resolveEquivalentPath(inputPath: string): string;
 export declare function normalizePathForComparison(inputPath: string): string;
+/**
+ * Compare paths already normalized by {@link normalizePathForComparison}.
+ *
+ * Returns the relative path (an empty string when the paths are equal), or
+ * `null` when the candidate is outside the root. Callers classifying one
+ * candidate against several static roots can normalize each side once and
+ * reuse the public helpers' containment semantics without repeating realpath
+ * work.
+ */
+export declare function relativePathWithinNormalizedRoot(normalizedRoot: string, normalizedCandidate: string): string | null;
 export declare function pathIsWithin(root: string, candidate: string): boolean;
 export declare function relativePathWithinRoot(root: string, candidate: string): string | null;
 /** Get the project directory. */
@@ -271,6 +281,13 @@ export declare function getAgentModulesDir(agentDir?: string): string;
 export declare function getMemoriesDir(agentDir?: string): string;
 /** Get the terminal sessions directory (~/.omp/agent/terminal-sessions). */
 export declare function getTerminalSessionsDir(agentDir?: string): string;
+/**
+ * Get the persistent registry of custom session files
+ * (~/.omp/agent/custom-session-files). Each `--session-dir`/`--session`
+ * transcript is recorded here as one marker file so storage GC can scan its
+ * exact path after its terminal breadcrumb is overwritten by a later session.
+ */
+export declare function getCustomSessionFilesDir(agentDir?: string): string;
 /** Get the crash log path (~/.omp/agent/omp-crash.log). */
 export declare function getCrashLogPath(agentDir?: string): string;
 /** Get the debug log path (~/.omp/agent/omp-debug.log). */

package/dist/types/env.d.ts

@@ -26,11 +26,19 @@ export declare function isMacosMallocStackLoggingEnvName(name: string): boolean;
  */
 export declare function isWsl(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): boolean;
 export declare function filterProcessEnv(env: Record<string, string | undefined>): Record<string, string>;
+/**
+ * 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 declare function stripGitRepoLocationEnv(env: Record<string, string>, platform?: NodeJS.Platform): void;
 /** 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 into key-value string pairs using
- * {@link parseEnvLine} for Bun-compatible line semantics, then mirrors valid
+ * Parses a complete .env file with the runtime's dotenv grammar, then retains
+ * only shell-identifier names and spawn-safe values before mirroring valid
  * `OMP_` variables to their `PI_` aliases.
  */
 export declare function parseEnvFile(filePath: string): Record<string, string>;

package/dist/types/executable.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Check if a file path exists, is a regular file, and has effective execute permission.
+ */
+export declare function isExecutable(filePath: string): boolean;

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

@@ -1,3 +1,8 @@
+/** 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
  *
@@ -15,14 +20,14 @@
  *  - `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 重置`
- *    (offset-bearing only; a timezone-naive stamp is provider wall clock in
- *    an unknown zone and only resolves when no relative signal is present)
+ *    (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 declare function extractRetryHint(source: Response | Headers | null | undefined, body?: string): number | undefined;
+export declare function extractRetryHint(source: Response | Headers | null | undefined, body?: string, options?: RetryHintOptions): number | undefined;
 export interface FetchWithRetryOptions extends RequestInit {
     /** Total fetch attempts (initial + retries). Default `5`. */
     maxAttempts?: number;

package/dist/types/file-lock.d.ts

@@ -16,6 +16,8 @@ declare function tryAcquireLock(lockPath: string): NativeFileLock | null;
 export declare function acquireFileLock(filePath: string, options?: FileLockOptions): Promise<FileLockHandle>;
 /** Run `fn` while holding an OS-backed exclusive lock for `filePath`. */
 export declare function withFileLock<T>(filePath: string, fn: () => Promise<T>, options?: FileLockOptions): Promise<T>;
+/** Run synchronous `fn` while holding an OS-backed exclusive lock for `filePath`. */
+export declare function withFileLockSync<T>(filePath: string, fn: () => T, options?: FileLockOptions): T;
 /**
  * Test-only acquisition handle for forcing ownership handoffs. This is not
  * part of the supported package API.

package/dist/types/index.d.ts

@@ -4,12 +4,12 @@ export * from "./binary.js";
 export * from "./color.js";
 export * from "./dirs.js";
 export * from "./env.js";
+export * from "./executable.js";
 export * from "./fetch-retry.js";
 export * from "./file-lock.js";
 export * from "./format.js";
 export * from "./frontmatter.js";
 export * from "./fs-error.js";
-export * from "./glob.js";
 export * from "./incoming-json.js";
 export * from "./json.js";
 export * from "./json-parse.js";

package/dist/types/mime.d.ts

@@ -1,3 +1,4 @@
+export declare const IMAGE_METADATA_HEADER_BYTES: number;
 export declare const SUPPORTED_IMAGE_MIME_TYPES: Set<string>;
 export type ImageMetadata = {
     mimeType: "image/png";

package/dist/types/path.d.ts

@@ -2,3 +2,9 @@
 export declare function windowsPathToWslMount(filePath: string): string | undefined;
 /** Removes Win32 extended-length prefixes before passing paths to Bun APIs. */
 export declare function stripWindowsExtendedLengthPathPrefix(filePath: string, platform?: NodeJS.Platform): string;
+/**
+ * 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 declare function isFullyQualifiedPath(filePath: string, platform?: NodeJS.Platform): boolean;

package/dist/types/peek-file.d.ts

@@ -10,9 +10,8 @@ export declare function peekFile<T>(filePath: string, maxBytes: number, op: (hea
 /**
  * Read up to the last `maxBytes` of `filePath` and pass that slice to `op`.
  *
- * The tail mirror of {@link peekFile}: same pooled-buffer strategy (no per-call
- * allocation for small reads), but the read is positioned at `size - len` so the
- * window ends at EOF. When the file is shorter than `maxBytes`, the whole file is
+ * The tail mirror of {@link peekFile}: the read is positioned at `size - len` so
+ * the window ends at EOF. When the file is shorter than `maxBytes`, the whole file is
  * returned. A multi-byte codepoint straddling the leading cut decodes to a
  * replacement char — callers that parse line-oriented tails drop the partial
  * leading line anyway.

package/dist/types/postmortem.d.ts

@@ -27,6 +27,27 @@ export declare enum Reason {
  * instances across bundles/realms.
  */
 export declare const NATIVE_PROCESS_EXIT: unique symbol;
+/**
+ * Hard-exit the process through the native primitive, resolved on every call.
+ *
+ * The native exit is deliberately re-resolved here rather than bound at module
+ * load: the extension/hook loader's `withHostGuard` transiently swaps
+ * `process.reallyExit`/`process.exit` for a stub that throws
+ * `ExtensionExitError`, and the shipped bundle defers this module's evaluation
+ * until first access — which can land inside that guard window, so binding at
+ * init could freeze the throwing stub forever and turn every later shutdown
+ * (SIGHUP/SIGINT/fatal) into an unhandled-rejection loop (#7393). When the
+ * guard is active the stub carries the native exit under
+ * {@link NATIVE_PROCESS_EXIT} (#6488).
+ *
+ * Both globals are reinstalled to their natives before exiting: Bun's
+ * `process.exit` re-reads `process.reallyExit` at call time, so exiting through
+ * one primitive while its sibling still holds the throwing stub re-enters the
+ * guard and loops the rejection storm (#11789). After restoring, `reallyExit`
+ * (the low-level primitive) is preferred; `process.exit` and finally `SIGKILL`
+ * are fallbacks so a poisoned or absent chain can never leave the process alive.
+ */
+export declare function exitProcess(code: number): never;
 /** User-facing command printed before fatal cleanup so interrupted work can be resumed. */
 export interface FatalRecoveryHint {
     /** Stable label identifying the recoverable session or process. */
@@ -91,11 +112,11 @@ export declare function isWorkerIpcDeserializeError(err: unknown): boolean;
  */
 export declare function registerWorkerIpcFaultHandler(handler: (err: Error) => void): () => void;
 /**
- * Treat unhandled stdout EPIPE rejections as a graceful peer disconnect.
- *
- * Stdio protocol servers call this for their process lifetime so a closed
- * client pipe runs registered cleanup callbacks instead of the fatal path.
- * The returned callback removes the registration.
+ * Treat a closed stdout consumer as a graceful peer disconnect for the caller's
+ * active lifetime. Attaches one shared `process.stdout` `error` listener,
+ * ref-counted across registrants (the ACP protocol server, the one-shot CLI
+ * entry). The returned callback removes the registration; the listener detaches
+ * when the last registrant unregisters.
  */
 export declare function registerStdioDisconnectHandling(): () => void;
 /**

package/dist/types/procmgr.d.ts

@@ -1,4 +1,6 @@
 import type { Subprocess } from "bun";
+import { isExecutable } from "./executable.js";
+export { isExecutable };
 export interface ShellConfig {
     shell: string;
     args: string[];
@@ -10,10 +12,6 @@ export interface ShellConfigOptions {
     /** File path or runtime layer that supplied the active shell setting. */
     configSource?: string;
 }
-/**
- * Check if a shell binary is executable.
- */
-export declare function isExecutable(path: string): boolean;
 /**
  * Get shell args for the resolved shell.
  * cmd.exe takes `/c`; PowerShell (powershell.exe / pwsh) takes

package/dist/types/snowflake.d.ts

@@ -5,6 +5,7 @@ declare namespace Snowflake {
     const PATTERN: RegExp;
     const EPOCH_TIMESTAMP = 1420070400000;
     const MAX_SEQUENCE = 4194303;
+    const MAX_TIMESTAMP: number;
     function formatParts(dt: number, seq: number): Snowflake;
     class Source {
         #private;

package/dist/types/stream.d.ts

@@ -1,5 +1,31 @@
 export declare function readLines(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<Uint8Array>;
 export declare function readJsonl<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal): AsyncGenerator<T>;
+/**
+ * Amortized byte accumulator for chunked stream readers.
+ *
+ * Holds the unconsumed tail of a stream in a single growing `Buffer` so that
+ * appending N chunks costs O(total bytes) instead of re-copying the whole
+ * prefix per chunk. Backs {@link readLines}, {@link readJsonl} and
+ * {@link readSseEvents}; also usable directly when a reader needs its own
+ * framing loop (see `consume` and `flush`).
+ */
+export declare class ConcatSink {
+    #private;
+    append(chunk: Uint8Array): void;
+    reset(chunk: Uint8Array): void;
+    get isEmpty(): boolean;
+    /**
+     * The buffered bytes as a live view — invalidated by the next `append`,
+     * `reset` or `consume`.
+     */
+    flush(): Uint8Array | undefined;
+    /** Drop the first `count` buffered bytes, keeping the remainder. */
+    consume(count: number): void;
+    clear(): void;
+    appendAndFlushLines(chunk: Uint8Array): Generator<Uint8Array<ArrayBufferLike>, void, unknown>;
+    appendAndFlushText(chunk: Uint8Array, decoder: TextDecoder): string | undefined;
+    pullJSONL<T>(chunk: Uint8Array, beg: number, end: number): Generator<T, void, unknown>;
+}
 /**
  * Stream parsed JSON objects from SSE `data:` lines.
  *
@@ -18,6 +44,25 @@ export declare function readJsonl<T>(stream: ReadableStream<Uint8Array>, signal?
  */
 export type SseEventObserver = (event: ServerSentEvent) => void;
 export declare function readSseJson<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal, onEvent?: SseEventObserver): AsyncGenerator<T>;
+/**
+ * Like {@link readSseJson}, but a `data:` frame that is not valid JSON is yielded
+ * as its raw text instead of raising a `SyntaxError`. Cut-off container-shaped
+ * stream tails stay recoverable, exactly as they are in {@link readSseJson}.
+ *
+ * Consumers that only understand objects must treat a `string` yield as a
+ * transport-level failure (for example a `429 Too Many Requests` or an HTML
+ * throttle page from a reverse proxy that already committed to the stream). This
+ * exists because `readSseJson`'s baseline consumers span unrelated transports
+ * whose error handling a text yield would subtly change; new call sites opt in.
+ *
+ * Note that the text lane is only the frames `JSON.parse` *rejected*: a frame
+ * carrying a JSON-encoded string (`data: "429 Too Many Requests"`) parses, so it
+ * is yielded as that string and is indistinguishable from a rejected frame by
+ * type alone. Consumers branching on `typeof === "string"` therefore see both,
+ * which is the safe direction — each is classified as text rather than trusted as
+ * an event object.
+ */
+export declare function readSseJsonOrText<T>(stream: ReadableStream<Uint8Array>, signal?: AbortSignal, onEvent?: SseEventObserver): AsyncGenerator<T | string>;
 /**
  * A single Server-Sent Event dispatched on a blank-line boundary.
  *

package/dist/types/which.d.ts

@@ -25,6 +25,12 @@ export interface WhichOptions extends Bun.WhichOptions {
      * Defaults to `WhichCachePolicy.Fresh`.
      */
     cache?: WhichCachePolicy;
+    /**
+     * Only search absolute directory entries in PATH, ignoring relative entries
+     * (e.g. `.` or `./bin`) and empty components to prevent resolving against
+     * an untrusted working directory.
+     */
+    requireAbsolutePaths?: boolean;
 }
 declare function darwinWhich(command: string, options?: Bun.WhichOptions): string | null;
 export declare const whichFresh: typeof darwinWhich;

package/package.json

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

package/src/acp/transport.ts

@@ -108,10 +108,15 @@ function createStandardError(
 type Dispatcher = (method: string, params: unknown, notification: boolean) => MaybePromise<unknown>;
 type Pending = { resolve(value: unknown): void; reject(reason: unknown): void };
 
+/** Bound on clean-EOF inbound drain so `closed` cannot hang if a handler never settles. */
+const INBOUND_DRAIN_TIMEOUT_MS = 30_000;
+
 /** Correlated bidirectional JSON-RPC connection. */
 export class RpcConnection {
 	#nextId = 0;
 	#pending = new Map<JsonRpcId, Pending>();
+	#inbound = new Set<Promise<void>>();
+	#openInboundIds = new Set<JsonRpcId>();
 	#writable: WritableStream<AnyMessage>;
 	#writeTail: Promise<void> = Promise.resolve();
 	#abort = new AbortController();
@@ -179,8 +184,9 @@ export class RpcConnection {
 			while (true) {
 				const next = await reader.read();
 				if (next.done) break;
-				void this.#handle(next.value).catch(error => this.close(error));
+				this.#dispatch(next.value);
 			}
+			await this.#drainInbound();
 			this.close();
 		} catch (error) {
 			this.close(error);
@@ -189,6 +195,34 @@ export class RpcConnection {
 		}
 	}
 
+	#dispatch(message: AnyMessage): void {
+		if ("method" in message && "id" in message) this.#openInboundIds.add(message.id);
+		const task = this.#handle(message).catch(error => this.close(error));
+		this.#inbound.add(task);
+		void task.finally(() => this.#inbound.delete(task));
+	}
+
+	async #drainInbound(): Promise<void> {
+		if (this.#inbound.size === 0) return;
+		const drained = Promise.allSettled(this.#inbound).then(() => {});
+		let timer: Timer | undefined;
+		const timedOut = await Promise.race([
+			drained.then(() => false),
+			new Promise<boolean>(resolve => {
+				timer = setTimeout(() => resolve(true), INBOUND_DRAIN_TIMEOUT_MS);
+			}),
+		]);
+		if (timer !== undefined) clearTimeout(timer);
+		if (!timedOut) return;
+		const error = RequestError.internalError(undefined, "Inbound request drain timed out").toErrorResponse();
+		await Promise.allSettled([...this.#openInboundIds].map(id => this.#respond(id, { error })));
+	}
+
+	#respond(id: JsonRpcId, body: { result: unknown } | { error: ErrorResponse }): Promise<void> {
+		if (!this.#openInboundIds.delete(id)) return Promise.resolve();
+		return this.#write({ jsonrpc: "2.0", id, ...body });
+	}
+
 	async #handle(message: AnyMessage): Promise<void> {
 		if ("id" in message && !("method" in message)) {
 			const pending = this.#pending.get(message.id);
@@ -210,13 +244,13 @@ export class RpcConnection {
 		}
 		try {
 			const result = await this.#dispatcher(message.method, message.params, false);
-			await this.#write({ jsonrpc: "2.0", id: message.id, result: result ?? {} });
+			await this.#respond(message.id, { result: result ?? {} });
 		} catch (error) {
 			const protocolError =
 				error instanceof RequestError
 					? error
 					: RequestError.internalError({ details: error instanceof Error ? error.message : String(error) });
-			await this.#write({ jsonrpc: "2.0", id: message.id, error: protocolError.toErrorResponse() });
+			await this.#respond(message.id, { error: protocolError.toErrorResponse() });
 		}
 	}
 }