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

package/src/async.ts

@@ -1,3 +1,40 @@
+import { scheduler } from "node:timers/promises";
+
+/**
+ * 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 const MAX_TIMER_DELAY_MS = 2_147_483_647;
+
+/**
+ * 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 async function sleepLong(delayMs: number, signal?: AbortSignal): Promise<void> {
+	signal?.throwIfAborted();
+	let remaining = delayMs;
+	while (remaining > 0) {
+		await scheduler.wait(Math.min(remaining, MAX_TIMER_DELAY_MS), { signal });
+		remaining -= MAX_TIMER_DELAY_MS;
+		signal?.throwIfAborted();
+	}
+}
+
 /**
  * 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/src/browsers.ts

@@ -1,6 +1,4 @@
-/** Behavior-compatible reimplementation of @puppeteer/browsers' used surface. */
-
-import type * as fs from "node:fs";
+/** Managed Chrome-for-Testing installation with bounded downloads and atomic publication. */
 import * as fsp from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
@@ -8,7 +6,6 @@ import { type ArchiveLimits, extractArchive } from "./ar";
 import { withFileLock } from "./file-lock";
 
 const CHROME_FOR_TESTING_BASE_URL = "https://storage.googleapis.com/chrome-for-testing-public";
-const CHROME_METADATA_BASE_URL = "https://googlechromelabs.github.io/chrome-for-testing";
 // Installation is outside browser/Eval operation deadlines, but a stalled CDN
 // must still release the cached install promise and permit a later attempt.
 const DOWNLOAD_TIMEOUT_MS = 5 * 60_000;
@@ -25,15 +22,6 @@ const BROWSER_ARCHIVE_LIMITS: Partial<ArchiveLimits> = {
 	maxInMemorySize: 1024 * 1024 * 1024,
 };
 
-/** Supported browser products. */
-export enum Browser {
-	CHROME = "chrome",
-	CHROMEHEADLESSSHELL = "chrome-headless-shell",
-	CHROMIUM = "chromium",
-	FIREFOX = "firefox",
-	CHROMEDRIVER = "chromedriver",
-}
-
 /** Browser download platform identifiers. */
 export enum BrowserPlatform {
 	LINUX = "linux",
@@ -51,34 +39,6 @@ function requireChromeForTestingPlatform(platform: BrowserPlatform): ChromeForTe
 	return platform;
 }
 
-const BROWSERS = [
-	Browser.CHROME,
-	Browser.CHROMEHEADLESSSHELL,
-	Browser.CHROMIUM,
-	Browser.FIREFOX,
-	Browser.CHROMEDRIVER,
-] as const;
-const BROWSER_PLATFORMS = [
-	BrowserPlatform.LINUX,
-	BrowserPlatform.LINUX_ARM,
-	BrowserPlatform.MAC,
-	BrowserPlatform.MAC_ARM,
-	BrowserPlatform.WIN32,
-	BrowserPlatform.WIN64,
-] as const;
-
-/** Chrome-for-Testing release channel tags accepted by {@link resolveBuildId}. */
-export 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;
@@ -87,7 +47,6 @@ export interface BrowserDownloadProgress {
 
 /** Inputs used to locate an installed browser executable. */
 export interface ComputeExecutablePathOptions {
-	browser: Browser;
 	buildId: string;
 	cacheDir: string;
 	platform?: BrowserPlatform;
@@ -99,27 +58,14 @@ export interface InstallOptions extends ComputeExecutablePathOptions {
 	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;
 	executablePath: string;
 }
 
-interface LastKnownGoodVersions {
-	channels: Record<string, { version: string }>;
-}
-
-interface MilestoneVersions {
-	milestones: Record<string, { version: string }>;
-}
-
-interface PatchVersions {
-	builds: Record<string, { version: string }>;
-}
-
 /** Detect the current host's Puppeteer browser platform. */
 export function detectBrowserPlatform(): BrowserPlatform | undefined {
 	const platform = os.platform();
@@ -130,43 +76,8 @@ export function detectBrowserPlatform(): BrowserPlatform | undefined {
 	return undefined;
 }
 
-/** Resolve a Chrome-for-Testing channel, milestone, or build prefix to a full build ID. */
-export async function resolveBuildId(
-	browser: Browser,
-	_platform: BrowserPlatform,
-	tag: string | BrowserTag,
-): Promise<string> {
-	if (browser !== Browser.CHROME && browser !== Browser.CHROMEHEADLESSSHELL && browser !== Browser.CHROMEDRIVER) {
-		return tag;
-	}
-	if (/^\d+\.\d+\.\d+\.\d+$/.test(tag)) return tag;
-
-	const channel = tag === BrowserTag.LATEST ? "Canary" : chromeChannelName(tag);
-	if (channel) {
-		const metadata = await fetchMetadata<LastKnownGoodVersions>("last-known-good-versions.json");
-		const version = metadata.channels[channel]?.version;
-		if (!version) throw new Error(`Chrome channel ${tag} was not found in Chrome-for-Testing metadata`);
-		return version;
-	}
-	if (/^\d+$/.test(tag)) {
-		const metadata = await fetchMetadata<MilestoneVersions>("latest-versions-per-milestone.json");
-		return metadata.milestones[tag]?.version ?? tag;
-	}
-	if (/^\d+\.\d+\.\d+$/.test(tag)) {
-		const metadata = await fetchMetadata<PatchVersions>("latest-patch-versions-per-build.json");
-		return metadata.builds[tag]?.version ?? tag;
-	}
-	return tag;
-}
-
 /** Return the Chrome-for-Testing archive URL for a browser build. */
-export function getDownloadUrl(
-	browser: Browser,
-	platform: BrowserPlatform,
-	buildId: string,
-	baseUrl = CHROME_FOR_TESTING_BASE_URL,
-): URL {
-	if (browser !== Browser.CHROME) throw new Error(`Unsupported browser download: ${browser}`);
+export function getDownloadUrl(platform: BrowserPlatform, buildId: string, baseUrl = CHROME_FOR_TESTING_BASE_URL): URL {
 	const archivePlatform = chromeArchivePlatform(platform);
 	const root = baseUrl.replace(/\/$/, "");
 	return new URL(`${root}/${buildId}/${archivePlatform}/chrome-${archivePlatform}.zip`);
@@ -176,9 +87,8 @@ export function getDownloadUrl(
 export function computeExecutablePath(options: ComputeExecutablePathOptions): string {
 	const detectedPlatform = options.platform ?? detectBrowserPlatform();
 	if (!detectedPlatform) throw new Error("Cannot determine a browser platform for this host");
-	if (options.browser !== Browser.CHROME) throw new Error(`Unsupported browser executable: ${options.browser}`);
 	const platform = requireChromeForTestingPlatform(detectedPlatform);
-	const installDir = installationDir(options.cacheDir, options.browser, platform, options.buildId);
+	const installDir = installationDir(options.cacheDir, platform, options.buildId);
 	switch (platform) {
 		case BrowserPlatform.LINUX:
 			return path.join(installDir, "chrome-linux64", "chrome");
@@ -207,52 +117,14 @@ export function computeExecutablePath(options: ComputeExecutablePathOptions): st
 	}
 }
 
-/** Scan a Puppeteer cache for browser installation directories. */
-export async function getInstalledBrowsers(options: { cacheDir: string }): Promise<InstalledBrowser[]> {
-	const installed: InstalledBrowser[] = [];
-	for (const browser of BROWSERS) {
-		const browserDir = path.join(options.cacheDir, browser);
-		let entries: fs.Dirent[];
-		try {
-			entries = await fsp.readdir(browserDir, { withFileTypes: true });
-		} catch (error) {
-			if (isMissingPath(error)) continue;
-			throw error;
-		}
-		for (const entry of entries) {
-			if (!entry.isDirectory()) continue;
-			const parsed = parseInstallationName(entry.name);
-			if (!parsed) continue;
-			const installPath = path.join(browserDir, entry.name);
-			try {
-				installed.push({
-					browser,
-					buildId: parsed.buildId,
-					platform: parsed.platform,
-					path: installPath,
-					executablePath: computeExecutablePath({
-						browser,
-						buildId: parsed.buildId,
-						cacheDir: options.cacheDir,
-						platform: parsed.platform,
-					}),
-				});
-			} catch {
-				// Other browser products are not part of the surface used by OMP.
-			}
-		}
-	}
-	return installed;
-}
-
 /** Download and unpack Chrome into Puppeteer's existing cache layout. */
 export async function install(options: InstallOptions): Promise<InstalledBrowser> {
 	const platform = options.platform ?? detectBrowserPlatform();
 	if (!platform) throw new Error("Cannot determine a browser platform for this host");
 	const executablePath = computeExecutablePath({ ...options, platform });
-	const installPath = installationDir(options.cacheDir, options.browser, platform, options.buildId);
+	const installPath = installationDir(options.cacheDir, platform, options.buildId);
 	if (await pathExists(executablePath)) {
-		return { browser: options.browser, buildId: options.buildId, platform, path: installPath, executablePath };
+		return { buildId: options.buildId, platform, path: installPath, executablePath };
 	}
 
 	await fsp.mkdir(path.dirname(installPath), { recursive: true });
@@ -267,7 +139,7 @@ export async function install(options: InstallOptions): Promise<InstalledBrowser
 				const stagingPath = path.join(options.cacheDir, `.browser-${nonce}`);
 				try {
 					await downloadArchive(
-						getDownloadUrl(options.browser, platform, options.buildId, options.baseUrl),
+						getDownloadUrl(platform, options.buildId, options.baseUrl),
 						archivePath,
 						options.downloadProgressCallback,
 					);
@@ -284,34 +156,12 @@ export async function install(options: InstallOptions): Promise<InstalledBrowser
 					]);
 				}
 			}
-			return { browser: options.browser, buildId: options.buildId, platform, path: installPath, executablePath };
+			return { buildId: options.buildId, platform, path: installPath, executablePath };
 		},
 		{ retries: Math.ceil(DOWNLOAD_TIMEOUT_MS / 100) + 1, retryDelayMs: 100 },
 	);
 }
 
-function chromeChannelName(tag: string): string | undefined {
-	switch (tag) {
-		case BrowserTag.STABLE:
-			return "Stable";
-		case BrowserTag.BETA:
-			return "Beta";
-		case BrowserTag.DEV:
-			return "Dev";
-		case BrowserTag.CANARY:
-			return "Canary";
-		default:
-			return undefined;
-	}
-}
-
-async function fetchMetadata<T>(filename: string): Promise<T> {
-	const response = await fetch(`${CHROME_METADATA_BASE_URL}/${filename}`, { signal: AbortSignal.timeout(30_000) });
-	if (!response.ok)
-		throw new Error(`Failed to fetch Chrome-for-Testing metadata (${response.status} ${response.statusText})`);
-	return (await response.json()) as T;
-}
-
 function chromeArchivePlatform(platform: BrowserPlatform): string {
 	switch (requireChromeForTestingPlatform(platform)) {
 		case BrowserPlatform.LINUX:
@@ -327,17 +177,8 @@ function chromeArchivePlatform(platform: BrowserPlatform): string {
 	}
 }
 
-function installationDir(cacheDir: string, browser: Browser, platform: BrowserPlatform, buildId: string): string {
-	return path.join(cacheDir, browser, `${platform}-${buildId}`);
-}
-
-function parseInstallationName(name: string): { platform: BrowserPlatform; buildId: string } | undefined {
-	for (const platform of BROWSER_PLATFORMS) {
-		const prefix = `${platform}-`;
-		if (name.startsWith(prefix) && name.length > prefix.length)
-			return { platform, buildId: name.slice(prefix.length) };
-	}
-	return undefined;
+function installationDir(cacheDir: string, platform: BrowserPlatform, buildId: string): string {
+	return path.join(cacheDir, "chrome", `${platform}-${buildId}`);
 }
 
 function isMissingPath(error: unknown): boolean {

package/src/dirs.ts

@@ -165,19 +165,31 @@ export function normalizePathForComparison(inputPath: string): string {
 	return process.platform === "win32" ? resolvedPath.toLowerCase() : resolvedPath;
 }
 
+/**
+ * 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 function relativePathWithinNormalizedRoot(normalizedRoot: string, normalizedCandidate: string): string | null {
+	const relative = path.relative(normalizedRoot, normalizedCandidate);
+	if (relative !== "" && (relative.startsWith("..") || path.isAbsolute(relative))) return null;
+	return relative;
+}
+
 export function pathIsWithin(root: string, candidate: string): boolean {
 	const normalizedRoot = normalizePathForComparison(root);
 	const normalizedCandidate = normalizePathForComparison(candidate);
-	const relative = path.relative(normalizedRoot, normalizedCandidate);
-	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+	return relativePathWithinNormalizedRoot(normalizedRoot, normalizedCandidate) !== null;
 }
 
 export function relativePathWithinRoot(root: string, candidate: string): string | null {
-	if (!pathIsWithin(root, candidate)) return null;
 	const normalizedRoot = normalizePathForComparison(root);
 	const normalizedCandidate = normalizePathForComparison(candidate);
-	const relative = path.relative(normalizedRoot, normalizedCandidate);
-	return relative || null;
+	return relativePathWithinNormalizedRoot(normalizedRoot, normalizedCandidate) || null;
 }
 
 let projectDir: string | undefined;
@@ -919,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

@@ -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
@@ -180,48 +223,24 @@ 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;
 }
 
 /**
- * Parse one dotenv line with Bun-compatible semantics: an optional `export`
- * prefix, full-line `#` comments, inline `#` comments after whitespace on
- * unquoted values, and single/double/backtick quoting (a `#` inside quotes
- * stays literal). Returns undefined for blank lines, comments, and malformed
- * names.
- */
-function parseEnvLine(line: string): { key: string; value: string } | undefined {
-	const trimmed = line.trim();
-	if (!trimmed || trimmed.startsWith("#")) return undefined;
-	const eqIndex = trimmed.indexOf("=");
-	if (eqIndex === -1) return undefined;
-	let key = trimmed.slice(0, eqIndex).trim();
-	const exported = key.match(/^export[ \t]+(.*)$/);
-	if (exported) key = exported[1].trim();
-	if (!isValidEnvName(key)) return undefined;
-	const raw = trimmed.slice(eqIndex + 1).replace(/^[ \t]+/, "");
-	const quote = raw[0];
-	if (quote === '"' || quote === "'" || quote === "`") {
-		let close = raw.indexOf(quote, 1);
-		while (close !== -1 && raw[close - 1] === "\\") close = raw.indexOf(quote, close + 1);
-		return { key, value: close === -1 ? raw.slice(1) : raw.slice(1, close) };
-	}
-	const commentIndex = raw.search(/[ \t]#/);
-	return { key, value: (commentIndex === -1 ? raw : raw.slice(0, commentIndex)).trimEnd() };
-}
-
-/**
- * Parses a .env file synchronously into key-value string pairs using
- * {@link parseEnvLine} for Bun-compatible line semantics, then mirrors valid
+ * 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 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,11 +11,20 @@ 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;
 
@@ -29,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
  *
@@ -46,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");
@@ -137,25 +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]) 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
+	// 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);
@@ -241,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

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