@oh-my-pi/pi-utils 18.2.0 → 18.2.2

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 ## [Unreleased]
 
+## [18.2.2] - 2026-09-16
+
+### Added
+
+- Added asynchronous and synchronous SQLite database opening APIs with path-attributed errors, optional corruption recovery that preserves private database and sidecar backups, and automatic retries for transient busy errors during asynchronous opens.
+
+## [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

package/dist/types/dirs.d.ts

@@ -281,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,6 +26,14 @@ 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>;
 /**

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,6 +4,7 @@ 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";

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/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/sqlite.d.ts

@@ -1,13 +1,33 @@
+/** Shared SQLite opening, error attribution, and result-code classification for persistent stores. */
+import { Database } from "bun:sqlite";
+/** Controls opt-in replacement of an unrecoverably corrupt SQLite store. */
+export interface SqliteOpenOptions {
+    /**
+     * Preserve a corrupt store and its sidecars, recreate it, and run the
+     * initializer once more. Disabled by default.
+     */
+    recoverCorruption?: boolean;
+    /** Runs after preservation and before the replacement is initialized. */
+    onCorruptionPreserved?: (backupPath: string, error: unknown) => void;
+}
 /**
- * Shared classifiers for `bun:sqlite` error result codes.
+ * Opens and initializes a store, retrying BUSY failures up to four total attempts.
+ * Installs the busy handler before initialization and closes failed connections.
+ * The initializer may run again on a fresh connection; on success it owns the handle.
  *
- * Every omp SQLite store (`agent.db` credential/usage store, `models.db` model
- * cache, `history.db`) needs the same two distinctions: a transient BUSY that
- * clears by retrying, and an unrecoverable corruption that never does. Keeping
- * one implementation here prevents the classifiers from drifting between the
- * credential store and the model cache.
+ * With corruption recovery enabled, recovery is serialized across processes.
+ * The identity observed by the failed handle is checked under that lock, so a
+ * waiter adopts a replacement made by a peer instead of quarantining it.
+ * Final failures retain their SQLite codes and include the database path.
  */
-import type { Database } from "bun:sqlite";
+export declare function openSqliteDatabase<T>(dbPath: string, initialize: (db: Database) => T | Promise<T>, options?: SqliteOpenOptions): Promise<T>;
+/**
+ * Synchronous counterpart to {@link openSqliteDatabase}. It performs no BUSY
+ * retry loop; corruption recovery, when enabled, is bounded to one replacement.
+ */
+export declare function openSqliteDatabaseSync<T>(dbPath: string, initialize: (db: Database) => T, options?: SqliteOpenOptions): T;
+/** Adds the failing store's path to an error without losing SQLite result codes or its original stack. */
+export declare function annotateSqliteError(error: unknown, dbPath: string): Error;
 /** Checkpoints committed WAL frames without waiting for concurrent readers. */
 export declare function checkpointWal(db: Database): void;
 /**

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.2.0",
+	"version": "18.2.2",
 	"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.2.0"
+		"@oh-my-pi/pi-natives": "18.2.2"
 	},
 	"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() });
 		}
 	}
 }

package/src/dirs.ts

@@ -931,6 +931,16 @@ export function getTerminalSessionsDir(agentDir?: string): string {
 	return dirs.agentSubdir(agentDir, "terminal-sessions", "state");
 }
 
+/**
+ * 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 function getCustomSessionFilesDir(agentDir?: string): string {
+	return dirs.agentSubdir(agentDir, "custom-session-files", "state");
+}
+
 /** Get the crash log path (~/.omp/agent/omp-crash.log). */
 export function getCrashLogPath(agentDir?: string): string {
 	return dirs.agentSubdir(agentDir, "omp-crash.log", "state");

package/src/env.ts

@@ -65,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
@@ -181,6 +223,9 @@ export function filterChildShellEnv(
 			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;
 }
 

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

@@ -20,7 +20,11 @@ const RESET_IN_HR_MIN_PATTERN = /resets?\s+in\s+~?\s*(\d+(?:\.\d+)?)\s*hr\s*(\d+
 // "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;
 
@@ -34,6 +38,12 @@ const RETRY_AFTER_MS_BODY_PATTERN = /\bretry-after-ms\s*[:=]\s*([0-9]+)\b/i;
 // 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
  *
@@ -51,14 +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 重置`
- *    (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 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");
@@ -142,25 +156,20 @@ 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]) continue;
 		// Offset-bearing stamps are unambiguous and compete by longest-wins.
-		// Naive stamps (provider wall clock, unknown zone) resolve after the
-		// relative signals below, and only when nothing unambiguous was
-		// found — never by guessing the zone against a conflicting signal.
+		// 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);
-		if (hasOffset) {
-			const parsed = Date.parse(normalized);
-			if (!Number.isNaN(parsed) && parsed > Date.now()) {
-				consider(parsed - Date.now());
-			}
-		} else {
-			const parsed = Date.parse(`${normalized}Z`);
-			if (!Number.isNaN(parsed) && parsed > Date.now()) {
-				considerNaive(parsed - Date.now());
-			}
+		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

package/src/file-lock.ts

@@ -48,6 +48,19 @@ export async function acquireFileLock(filePath: string, options: FileLockOptions
 	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,
@@ -62,6 +75,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/index.ts

@@ -4,6 +4,7 @@ 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";