@sayknow-cli/utils 0.7.11 → 0.7.13

package/src/env.ts

@@ -1,23 +1,174 @@
+import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { getAgentDir, getConfigRootDir } from "./dirs";
+import { canonicalEnvKey, getAgentDir, getConfigRootDir, getTrustedHomeDir, pathIdentityKey } from "./dirs";
 import { isSafeEnvName, isSafeEnvValue } from "./spawn-env";
 
 export { filterProcessEnv, isSafeEnvName, isSafeEnvValue } from "./spawn-env";
 
-import { parseEnvFile, parseShellEnvFile } from "./env-file";
+import {
+	parseEnvFile,
+	parseEnvFileContent,
+	parseShellEnvFile,
+	projectEnvLayerFiles,
+	projectEnvSnapshot,
+} from "./env-file";
 
 // Re-exported so the public surface of this module is unchanged.
 export { isValidEnvName, parseEnvFile, parseShellEnvFile } from "./env-file";
 
+function findClosingBrace(value: string, open: number): number {
+	let depth = 1;
+	for (let index = open + 2; index < value.length; index++) {
+		if (value[index] === "\\") {
+			index++;
+			continue;
+		}
+		if (value[index] === "$" && value[index + 1] === "{") {
+			depth++;
+			index++;
+		} else if (value[index] === "}" && --depth === 0) {
+			return index;
+		}
+	}
+	return -1;
+}
+
+function expandProjectEnvValue(value: string, resolve: (name: string) => string | undefined): string {
+	let result = "";
+	for (let index = 0; index < value.length; index++) {
+		const char = value[index];
+		if (char === "\\" && value[index + 1] === "$") {
+			result += "$";
+			index++;
+			continue;
+		}
+		if (char !== "$") {
+			result += char;
+			continue;
+		}
+
+		let name: string | undefined;
+		let end = index;
+		let fallback: string | undefined;
+		if (value[index + 1] === "{") {
+			const close = findClosingBrace(value, index);
+			const expression = close < 0 ? undefined : value.slice(index + 2, close);
+			const match = expression && /^([A-Za-z_][A-Za-z0-9_]*)(?::-(.*))?$/.exec(expression);
+			if (match) {
+				name = match[1];
+				fallback = match[2];
+				end = close;
+			}
+		} else {
+			const match = /^[A-Za-z_][A-Za-z0-9_]*/.exec(value.slice(index + 1));
+			if (match) {
+				name = match[0];
+				end = index + name.length;
+			}
+		}
+		if (!name) {
+			result += "$";
+			continue;
+		}
+		result += resolve(name) ?? (fallback === undefined ? "" : expandProjectEnvValue(fallback, resolve));
+		index = end;
+	}
+	return result;
+}
+
+function loadProjectEnv(): {
+	values: Record<string, string>;
+	loadedValues: Record<string, string>;
+	dynamic: Set<string>;
+} {
+	const cwd = process.cwd();
+	const nodeEnv = process.env.NODE_ENV || Bun.env.NODE_ENV;
+	// Same file list as projectEnvSnapshot, so a loaded value stays project-controlled.
+	const files = projectEnvLayerFiles(nodeEnv);
+	const values: Record<string, string> = {};
+	const dynamic = new Set<string>();
+	for (const file of files) {
+		const parsed = parseEnvFile(path.join(cwd, file));
+		for (const [rawKey, value] of Object.entries(parsed)) {
+			// Windows environment names are case-insensitive, so the guard lookups
+			// below must see the same key Bun loaded into `process.env`.
+			const key = canonicalEnvKey(rawKey);
+			values[key] = value;
+			// Track dynamic provenance only for the winning declaration.
+			if (/[$`]/.test(value)) dynamic.add(key);
+			else dynamic.delete(key);
+		}
+	}
+	// Quoted escapes are not `$` or backticks, but Bun autoload decodes `\n`
+	// and `\r` inside double quotes. `projectEnvSnapshot` already refuses that
+	// shape. Union those keys. Do not copy its values: an unparsed declaration
+	// is stored there as "" and must not overlay this layer. File selection
+	// stays above, so a higher static layer still clears a lower dynamic one.
+	for (const key of projectEnvSnapshot(cwd).dynamic) dynamic.add(key);
+
+	const resolved = new Map<string, string>();
+	const resolving = new Set<string>();
+	const resolveProjectValue = (key: string): string | undefined => {
+		const inherited = Bun.env[key];
+		if (inherited !== undefined) return inherited;
+		const cached = resolved.get(key);
+		if (cached !== undefined) return cached;
+		if (!Object.hasOwn(values, key) || resolving.has(key)) return undefined;
+
+		resolving.add(key);
+		const value = expandProjectEnvValue(values[key] ?? "", name => resolveProjectValue(canonicalEnvKey(name)));
+		resolving.delete(key);
+		resolved.set(key, value);
+		return value;
+	};
+	for (const [key, value] of Object.entries(values)) {
+		resolved.set(
+			key,
+			expandProjectEnvValue(value, name => resolveProjectValue(canonicalEnvKey(name))),
+		);
+	}
+	return { values, loadedValues: Object.fromEntries(resolved), dynamic };
+}
+
 function resolveFileEnvValue(file: Record<string, string>, name: string): string | undefined {
 	if (!isSafeEnvName(name)) return undefined;
-	const value = file[name];
+	const value = file[canonicalEnvKey(name)];
 	if (value === undefined || !isSafeEnvValue(value)) return undefined;
 	const trimmed = value.trim();
 	return trimmed.length > 0 ? trimmed : undefined;
 }
 
+type TrustedAgentEnvRead =
+	| { status: "missing"; values: Record<string, string> }
+	| { status: "unavailable"; values: Record<string, string> }
+	| { status: "ok"; values: Record<string, string> };
+
+function readTrustedAgentEnv(): TrustedAgentEnvRead {
+	let filePath: string;
+	try {
+		filePath = path.join(getAgentDir(), ".env");
+	} catch {
+		return { status: "unavailable", values: {} };
+	}
+	let fileDescriptor: number | undefined;
+	try {
+		const linkStats = fs.lstatSync(filePath);
+		if (!linkStats.isFile()) return { status: "unavailable", values: {} };
+		const noFollow = fs.constants.O_NOFOLLOW ?? 0;
+		fileDescriptor = fs.openSync(filePath, fs.constants.O_RDONLY | noFollow);
+		const fileStats = fs.fstatSync(fileDescriptor);
+		if (!fileStats.isFile()) return { status: "unavailable", values: {} };
+		const content = fs.readFileSync(fileDescriptor, "utf-8");
+		return { status: "ok", values: parseEnvFileContent(content) };
+	} catch (error) {
+		const code = error && typeof error === "object" && "code" in error ? error.code : undefined;
+		return code === "ENOENT" ? { status: "missing", values: {} } : { status: "unavailable", values: {} };
+	} finally {
+		if (fileDescriptor !== undefined) fs.closeSync(fileDescriptor);
+	}
+}
+
 function filterCredentialInheritedEnv(env: Record<string, string | undefined>): Record<string, string> {
 	const result: Record<string, string> = {};
 	for (const key in env) {
@@ -25,34 +176,108 @@ function filterCredentialInheritedEnv(env: Record<string, string | undefined>):
 		if (!isSafeEnvName(key) || value === undefined || !isSafeEnvValue(value)) continue;
 
 		// Bun may have already loaded cwd/.env before JS runs. It does not expose the
-		// source of each entry, so an exact match with projectEnv is ambiguous. Use
-		// the safer credential rule: ambiguous project matches are excluded from the
-		// credential-only inherited snapshot, while remaining available through $env.
+		// source of each entry, so a matching project declaration is ambiguous. A
+		// dynamic dotenv declaration is also ambiguous even when expansion changes
+		// its runtime value. Exclude those from the credential-only snapshot while
+		// keeping them available through $env.
 		const projectValue = resolveFileEnvValue(projectEnv, key);
-		if (projectValue !== undefined && projectValue === value) continue;
+		if (projectValue !== undefined && (projectSnapshot.dynamic.has(canonicalEnvKey(key)) || projectValue === value))
+			continue;
 
 		result[key] = value;
 	}
 	return result;
 }
 
-// Eagerly parse the user's $HOME/.env and the current project's .env (from cwd)
-const homeShellEnv = {
-	...parseShellEnvFile(path.join(os.homedir(), ".zshenv")),
-	...parseShellEnvFile(path.join(os.homedir(), ".zprofile")),
-	...parseShellEnvFile(path.join(os.homedir(), ".zshrc")),
-	...parseShellEnvFile(path.join(os.homedir(), ".bash_profile")),
-	...parseShellEnvFile(path.join(os.homedir(), ".bashrc")),
-};
-const homeEnv = parseEnvFile(path.join(os.homedir(), ".env"));
-const piEnv = parseEnvFile(path.join(getConfigRootDir(), ".env"));
-const agentEnv = parseEnvFile(path.join(getAgentDir(), ".env"));
-const projectEnv = parseEnvFile(path.join(process.cwd(), ".env"));
+// Parse the current project's .env first. Bun may have overlaid HOME from it
+// before this module runs, so a declared HOME must never select user credential
+// files for the credential-only snapshot.
+const projectSnapshot = loadProjectEnv();
+const projectEnv = projectSnapshot.values;
+
+/** Project dotenv as it was when this module loaded, before a later `chdir` or file delete. */
+export function startupProjectEnvSnapshot(): { values: Record<string, string>; dynamic: Set<string> } {
+	return { values: projectSnapshot.values, dynamic: projectSnapshot.dynamic };
+}
+const authoritativeHomeKey = process.platform === "win32" ? "USERPROFILE" : "HOME";
+const declaredHomeKey = canonicalEnvKey(authoritativeHomeKey);
+const declaredHome = projectEnv[declaredHomeKey];
+const runtimeHome = process.env[authoritativeHomeKey];
+const rejectProjectHome =
+	declaredHome !== undefined &&
+	runtimeHome !== undefined &&
+	(projectSnapshot.dynamic.has(declaredHomeKey) || declaredHome === runtimeHome);
+let trustedEnvHome: string | undefined;
+try {
+	trustedEnvHome = rejectProjectHome ? getTrustedHomeDir() : os.homedir();
+} catch {
+	// No trustworthy account home means no user credential files are trusted.
+	trustedEnvHome = undefined;
+}
+
+// `path.resolve` does not follow symlinks, so macOS `/tmp` vs `/private/tmp`,
+// a symlink home, or a bind mount compares unequal and would load the checkout
+// as the trusted home. Keep the lexical check, then compare device/inode, then
+// `pathIdentityKey` when the filesystem has no usable inode.
+function credentialHomeMatchesCwd(home: string): boolean {
+	const cwd = process.cwd();
+	if (path.resolve(home) === path.resolve(cwd)) return true;
+	try {
+		const left = fs.statSync(home, { bigint: true });
+		const right = fs.statSync(cwd, { bigint: true });
+		if (left.isDirectory() && right.isDirectory() && left.ino !== 0n && right.ino !== 0n) {
+			return left.dev === right.dev && left.ino === right.ino;
+		}
+	} catch {
+		// Missing or unreadable: do not treat this directory as a credential home.
+		return true;
+	}
+	return pathIdentityKey(home) === pathIdentityKey(cwd);
+}
+
+// Eagerly parse the trusted user's env files and the project .env (from cwd).
+// When cwd is that home, both the dotenv and the shell startup files are the
+// checkout, so neither is a credential source.
+const credentialHomeIsCwd = trustedEnvHome !== undefined && credentialHomeMatchesCwd(trustedEnvHome);
+const homeShellEnv =
+	trustedEnvHome && !credentialHomeIsCwd
+		? {
+				...parseShellEnvFile(path.join(trustedEnvHome, ".zshenv")),
+				...parseShellEnvFile(path.join(trustedEnvHome, ".zprofile")),
+				...parseShellEnvFile(path.join(trustedEnvHome, ".zshrc")),
+				...parseShellEnvFile(path.join(trustedEnvHome, ".bash_profile")),
+				...parseShellEnvFile(path.join(trustedEnvHome, ".bashrc")),
+			}
+		: {};
+const homeEnv = trustedEnvHome && !credentialHomeIsCwd ? parseEnvFile(path.join(trustedEnvHome, ".env")) : {};
+let piEnv: Record<string, string> = {};
+let agentEnv: Record<string, string> = {};
+try {
+	piEnv = parseEnvFile(path.join(getConfigRootDir(), ".env"));
+	agentEnv = parseEnvFile(path.join(getAgentDir(), ".env"));
+} catch {
+	// Keep credential resolution fail-closed when trusted user state is unavailable.
+}
+const initialTrustedAgentEnv = readTrustedAgentEnv();
+const projectLoadedEnv: Record<string, string | undefined> = Object.fromEntries(
+	Object.keys(projectEnv).map(key => [key, Bun.env[key]]),
+);
 
 const inheritedEnv = filterCredentialInheritedEnv(Bun.env);
+const rotatingAgentEnvNames = new Set(Object.keys(agentEnv));
 
 export function $inheritedEnv(name: string): string | undefined {
-	return resolveFileEnvValue(inheritedEnv, name);
+	const snapshotValue = resolveFileEnvValue(inheritedEnv, name);
+	if (snapshotValue === undefined) return undefined;
+	// The snapshot records provenance — this key was inherited from the launching
+	// shell rather than the caller's cwd/.env — and pins the value so a later
+	// in-process write cannot swap the credential we authenticate with. It is not
+	// a cache that outlives the variable: once the key is removed from the live
+	// environment it is no longer inherited, so deletion is honoured. Without
+	// this, a credential present at import time can never be suppressed (tests
+	// that clear provider env vars silently keep resolving the real credential).
+	if (Bun.env[name] === undefined) return undefined;
+	return snapshotValue;
 }
 
 function resolveLiveCredentialEnvValue(name: string): string | undefined {
@@ -62,11 +287,12 @@ function resolveLiveCredentialEnvValue(name: string): string | undefined {
 	const trimmed = value.trim();
 	if (trimmed.length === 0) return undefined;
 
-	const projectValue = resolveFileEnvValue(projectEnv, name);
 	if (
-		projectValue !== undefined &&
-		projectValue === trimmed &&
-		resolveFileEnvValue(inheritedEnv, name) === undefined
+		Object.hasOwn(projectEnv, canonicalEnvKey(name)) &&
+		resolveFileEnvValue(inheritedEnv, name) === undefined &&
+		(projectSnapshot.dynamic.has(canonicalEnvKey(name)) ||
+			trimmed === resolveFileEnvValue(projectEnv, name) ||
+			trimmed === projectLoadedEnv[canonicalEnvKey(name)])
 	) {
 		return undefined;
 	}
@@ -74,8 +300,44 @@ function resolveLiveCredentialEnvValue(name: string): string | undefined {
 	return trimmed;
 }
 
-for (const file of [projectEnv, agentEnv, piEnv, homeEnv, homeShellEnv]) {
+/**
+ * Names a repository `.env` must not install into the process environment.
+ * `NODE_TLS_REJECT_UNAUTHORIZED=0` disables certificate verification for every
+ * fetch in the process, so a project `.env` pairing it with a proxy would expose
+ * provider credentials to whoever answers the proxy.
+ * `SKC_HARNESS_SOCKET_DIR` and `SKC_HARNESS_ROOT_REGISTRY_DIR` select the harness
+ * control socket directory and the session-root registry. The harness reads both
+ * from the process environment after this module loads, so a project `.env` must
+ * not point either at a path the repository controls.
+ */
+const PROJECT_DENIED_ENV_NAMES = [
+	"NODE_TLS_REJECT_UNAUTHORIZED",
+	"SKC_HARNESS_SOCKET_DIR",
+	"SKC_HARNESS_ROOT_REGISTRY_DIR",
+] as const;
+
+// Bun may have loaded cwd/.env before JS runs. Drop a value the project declares
+// (same provenance rule as the credential snapshot) and never copy it below.
+// Removing `NODE_TLS_REJECT_UNAUTHORIZED` restores verification: Bun reads that
+// switch per TLS connection. The same drop covers the harness directory names.
+// A quoted escape is dynamic even when the line parser did not store a value.
+for (const name of PROJECT_DENIED_ENV_NAMES) {
+	const key = canonicalEnvKey(name);
+	const declared = projectEnv[key];
+	if (declared === undefined && !projectSnapshot.dynamic.has(key)) continue;
+	const runtime = Bun.env[name];
+	if (
+		runtime !== undefined &&
+		(projectSnapshot.dynamic.has(key) || runtime === declared || runtime.trim() === declared)
+	) {
+		delete Bun.env[name];
+	}
+}
+const projectDeniedKeys = new Set<string>(PROJECT_DENIED_ENV_NAMES.map(canonicalEnvKey));
+
+for (const file of [projectSnapshot.loadedValues, agentEnv, piEnv, homeEnv, homeShellEnv]) {
 	for (const key in file) {
+		if (file === projectSnapshot.loadedValues && projectDeniedKeys.has(key)) continue;
 		if (!Bun.env[key]) {
 			Bun.env[key] = file[key];
 		}
@@ -126,6 +388,28 @@ export function $credentialEnv(name: string): string | undefined {
 	);
 }
 
+/**
+ * Resolve a credential that may rotate in the trusted agent `.env` while this
+ * process remains alive.
+ *
+ * Presence in the agent file establishes that file as the credential's
+ * authority, even when the launching shell inherited an older value. This is
+ * what lets an atomic token rotation repair a long-lived shell instead of
+ * falling back to its revoked snapshot. Removal is authoritative too, so a
+ * deleted token cannot silently reappear from that snapshot. Project `.env`
+ * files are never consulted; shell values retain their normal precedence for
+ * names the agent file does not own.
+ */
+export function $rotatingCredentialEnv(name: string): string | undefined {
+	if (!isSafeEnvName(name)) return undefined;
+	const agentRead = readTrustedAgentEnv();
+	if (agentRead.status === "ok" && Object.hasOwn(agentRead.values, name)) rotatingAgentEnvNames.add(name);
+	if (initialTrustedAgentEnv.status === "unavailable" && !rotatingAgentEnvNames.has(name)) return undefined;
+	if (!rotatingAgentEnvNames.has(name)) return $credentialEnv(name);
+	if (agentRead.status !== "ok") return undefined;
+	return resolveFileEnvValue(agentRead.values, name);
+}
+
 /**
  * Resolve the first credential env value from the given keys, excluding cwd/.env overlays.
  */
@@ -137,16 +421,20 @@ export function $pickCredentialEnv(...keys: string[]): string | undefined {
 	return undefined;
 }
 
+function parsePositiveInteger(raw: string | undefined): number | undefined {
+	const value = raw?.trim();
+	if (!value || !/^\d+$/.test(value)) return undefined;
+	const parsed = Number(value);
+	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+
 /**
  * Parses a positive decimal integer from `$env[name]`.
- * Empty, invalid, NaN, zero, or negative values return `defaultValue`.
+ * Empty, invalid, unsafe, zero, or negative values return `defaultValue`.
  */
 export function $envpos(name: string, defaultValue: number): number {
-	const raw = $env[name];
-	if (!raw) return defaultValue;
-	const parsed = Number.parseInt(raw, 10);
-	if (Number.isNaN(parsed) || parsed <= 0) return defaultValue;
-	return parsed;
+	const parsed = parsePositiveInteger($env[name]);
+	return parsed ?? defaultValue;
 }
 
 /** True when `BUN_ENV` or `NODE_ENV` is the string `test`. */
@@ -190,10 +478,8 @@ export function $pickflag(...keys: string[]): boolean {
 /** Resolve the first positive integer among keys, else defaultValue (SKC-first). Set-but-invalid keys are skipped. */
 export function $pickenvpos(keys: string[], defaultValue: number): number {
 	for (const key of keys) {
-		const raw = $env[key]?.trim();
-		if (!raw) continue;
-		const parsed = Number.parseInt(raw, 10);
-		if (!Number.isNaN(parsed) && parsed > 0) return parsed;
+		const parsed = parsePositiveInteger($env[key]);
+		if (parsed !== undefined) return parsed;
 	}
 	return defaultValue;
 }

package/src/error-classification.ts

@@ -0,0 +1,31 @@
+/**
+ * Cross-package classification for errors that describe an expected outcome
+ * rather than an unexpected failure.
+ *
+ * The symbol is registered globally so the marker survives package duplication
+ * and worker/VM boundaries without relying on a particular Error constructor.
+ */
+export const DESIGNED_ERROR = Symbol.for("sayknow-cli.designed-error");
+
+type MarkedError = object & { readonly [DESIGNED_ERROR]?: unknown };
+
+/** Mark an Error as a designed outcome before it crosses package boundaries. */
+export function markDesignedError<T extends Error>(error: T): T {
+	Object.defineProperty(error, DESIGNED_ERROR, {
+		configurable: false,
+		enumerable: false,
+		value: true,
+		writable: false,
+	});
+	return error;
+}
+
+/** Return true when a throwable carries the trusted designed-outcome marker. */
+export function isDesignedError(error: unknown): boolean {
+	if ((typeof error !== "object" && typeof error !== "function") || error === null) return false;
+	try {
+		return (error as MarkedError)[DESIGNED_ERROR] === true;
+	} catch {
+		return false;
+	}
+}

package/src/fetch-retry.ts

@@ -81,15 +81,18 @@ export interface FetchWithRetryOptions extends RequestInit {
 	/**
 	 * Per-delay cap. Server-provided `Retry-After` hints exceeding this return
 	 * the current response immediately — caller deals with the `!response.ok`.
-	 * Default `60_000`.
+	 * Scheduled values are also capped at the platform timer ceiling. Default
+	 * `60_000`.
 	 */
 	maxDelayMs?: number;
 	/**
 	 * Fallback delay schedule when no server hint is present. Number, array
 	 * (indexed by attempt, clamped to last), or function. Default exponential
-	 * `500ms * 2 ** attempt` capped at `maxDelayMs`.
+	 * `500ms * 2 ** attempt` capped at `maxDelayMs` and the platform timer
+	 * ceiling. Values that remain negative or non-finite after capping retry
+	 * immediately.
 	 */
-	defaultDelayMs?: number | readonly number[] | ((attempt: number) => number);
+	defaultDelayMs?: number | readonly number[] | ((attempt: number, error?: unknown) => number);
 	/**
 	 * Optional per-attempt overlay merged into the base `RequestInit` each try.
 	 * Headers from the overlay shallow-merge over the base. Useful for auth
@@ -106,6 +109,9 @@ export interface FetchWithRetryOptions extends RequestInit {
 
 const DEFAULT_MAX_DELAY_MS = 60_000;
 const DEFAULT_MAX_ATTEMPTS = 5;
+// Node-compatible timers coerce larger delays to 1 ms. Bun follows the same
+// signed 32-bit boundary, so every scheduler input must stay at or below it.
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
 
 /**
  * Fetch with bounded retries and sensible defaults. Retries on any
@@ -142,7 +148,8 @@ export async function fetchWithRetry(
 			if (signal?.aborted) throw new Error("Request was aborted");
 			const wrapped = wrapNetworkError(error);
 			if (attempt + 1 >= maxAttempts) throw wrapped;
-			await scheduler.wait(resolveDefaultDelay(defaultDelayMs, attempt, maxDelayMs), { signal });
+			const delayMs = normalizeRetryDelay(resolveDefaultDelay(defaultDelayMs, attempt, error), maxDelayMs);
+			await scheduler.wait(delayMs, { signal });
 			continue;
 		}
 
@@ -152,7 +159,8 @@ export async function fetchWithRetry(
 		const hint = extractRetryHint(response, await response.clone().text());
 		if (hint !== undefined && hint > maxDelayMs) return response;
 
-		const delayMs = Math.min(hint ?? resolveDefaultDelay(defaultDelayMs, attempt, maxDelayMs), maxDelayMs);
+		const delayMs = normalizeRetryDelay(hint ?? resolveDefaultDelay(defaultDelayMs, attempt), maxDelayMs);
+		void response.body?.cancel().catch(() => undefined);
 		await scheduler.wait(delayMs, { signal });
 	}
 }
@@ -186,12 +194,17 @@ function wrapNetworkError(error: unknown): Error {
 function resolveDefaultDelay(
 	option: FetchWithRetryOptions["defaultDelayMs"],
 	attempt: number,
-	maxDelayMs: number,
+	error?: unknown,
 ): number {
-	if (option === undefined) return Math.min(500 * 2 ** attempt, maxDelayMs);
-	if (typeof option === "number") return Math.min(option, maxDelayMs);
-	if (typeof option === "function") return Math.min(option(attempt), maxDelayMs);
-	return Math.min(option[Math.min(attempt, option.length - 1)] ?? 0, maxDelayMs);
+	if (option === undefined) return 500 * 2 ** attempt;
+	if (typeof option === "number") return option;
+	if (typeof option === "function") return option(attempt, error);
+	return option[Math.min(attempt, option.length - 1)] ?? 0;
+}
+
+function normalizeRetryDelay(delayMs: number, maxDelayMs: number): number {
+	const cappedDelayMs = Math.min(delayMs, maxDelayMs, MAX_TIMER_DELAY_MS);
+	return Number.isFinite(cappedDelayMs) && cappedDelayMs >= 0 ? cappedDelayMs : 0;
 }
 
 /**

package/src/frontmatter.ts

@@ -2,8 +2,29 @@ import { YAML } from "bun";
 import { truncate } from "./format";
 import * as logger from "./logger";
 
+const HTML_COMMENT_OPEN = "<!--";
+const HTML_COMMENT_CLOSE = "-->";
+
+// One forward scan. `/<!--[\s\S]*?-->/g` retries every unterminated opener
+// against the rest of the input, which is quadratic in the opener count.
+// An opener with no later close does not match, so that tail stays unchanged.
 function stripHtmlComments(content: string): string {
-	return content.replace(/<!--[\s\S]*?-->/g, "");
+	const parts: string[] = [];
+	let from = 0;
+	let i = 0;
+	const n = content.length;
+	while (i < n) {
+		const start = content.indexOf(HTML_COMMENT_OPEN, i);
+		if (start < 0) break;
+		const end = content.indexOf(HTML_COMMENT_CLOSE, start + HTML_COMMENT_OPEN.length);
+		if (end < 0) break;
+		if (start > from) parts.push(content.slice(from, start));
+		from = end + HTML_COMMENT_CLOSE.length;
+		i = from;
+	}
+	if (from === 0) return content;
+	if (from < n) parts.push(content.slice(from));
+	return parts.join("");
 }
 
 function stripLooseScalarTrailingCommas(metadata: string): string {
@@ -69,7 +90,12 @@ function normalizeKeys<T>(obj: T): T {
 	for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
 		const nk = key.includes("-") ? kebabToCamel(key) : key;
 		const nv = normalizeKeys(value);
-		result[nk] = nv;
+		// Assignment would route "__proto__" through Object.prototype's setter.
+		if (nk === "__proto__") {
+			Object.defineProperty(result, nk, { value: nv, writable: true, enumerable: true, configurable: true });
+		} else {
+			result[nk] = nv;
+		}
 		if (nk !== key || nv !== value) changed = true;
 	}
 	return (changed ? result : obj) as T;

package/src/glob.ts

@@ -137,6 +137,10 @@ export async function loadGitignorePatterns(baseDir: string): Promise<string[]>
  */
 export async function globPaths(patterns: string | string[], options: GlobPathsOptions = {}): Promise<string[]> {
 	const { cwd, exclude, signal, timeoutMs, dot, onlyFiles = true, gitignore } = options;
+	const timeoutSignal = timeoutMs ? AbortSignal.timeout(timeoutMs) : undefined;
+	const combinedSignal =
+		signal && timeoutSignal ? AbortSignal.any([signal, timeoutSignal]) : (signal ?? timeoutSignal);
+	throwIfGlobAborted(combinedSignal);
 
 	// Build exclude list: always exclude .git, exclude node_modules unless pattern references it
 	const patternArray = Array.isArray(patterns) ? patterns : [patterns];
@@ -147,6 +151,7 @@ export async function globPaths(patterns: string | string[], options: GlobPathsO
 
 	if (gitignore) {
 		const gitignorePatterns = await loadGitignorePatterns(cwd ?? getProjectDir());
+		throwIfGlobAborted(combinedSignal);
 		effectiveExclude = [...effectiveExclude, ...gitignorePatterns];
 	}
 
@@ -158,11 +163,6 @@ export async function globPaths(patterns: string | string[], options: GlobPathsO
 	// file; dedupe so a path is returned at most once regardless of pattern overlap.
 	const seen = new Set<string>();
 
-	// Combine timeout and abort signals
-	const timeoutSignal = timeoutMs ? AbortSignal.timeout(timeoutMs) : undefined;
-	const combinedSignal =
-		signal && timeoutSignal ? AbortSignal.any([signal, timeoutSignal]) : (signal ?? timeoutSignal);
-
 	for (const pattern of patternArray) {
 		const glob = new Glob(pattern);
 		const scanOptions = {
@@ -173,11 +173,7 @@ export async function globPaths(patterns: string | string[], options: GlobPathsO
 		};
 
 		for await (const entry of glob.scan(scanOptions)) {
-			if (combinedSignal?.aborted) {
-				const reason = combinedSignal.reason;
-				if (reason instanceof Error) throw reason;
-				throw new DOMException("Aborted", "AbortError");
-			}
+			throwIfGlobAborted(combinedSignal);
 
 			// Check exclusion patterns
 			const normalized = entry.replace(/\\/g, "/");
@@ -190,7 +186,14 @@ export async function globPaths(patterns: string | string[], options: GlobPathsO
 			seen.add(normalized);
 			allResults.push(normalized);
 		}
+		throwIfGlobAborted(combinedSignal);
 	}
 
 	return allResults;
 }
+
+function throwIfGlobAborted(signal: AbortSignal | undefined): void {
+	if (!signal?.aborted) return;
+	if (signal.reason instanceof Error) throw signal.reason;
+	throw new DOMException("Aborted", "AbortError");
+}

package/src/header-value.ts

@@ -0,0 +1,15 @@
+/**
+ * Sanitize a value destined for an HTTP header.
+ *
+ * OS-derived components (kernel release, hostname, os.version) can contain
+ * non-ASCII characters — e.g. Android kernel releases such as
+ * `4.4.302-Minimal™-EAS-QTI_Haptic-R26` — which `Headers`/`fetch` reject
+ * before the request is ever sent. Strip everything outside printable
+ * ASCII so header construction can never throw on runtime-derived values.
+ */
+
+const NON_PRINTABLE_ASCII = /[^\x20-\x7e]/g;
+
+export function sanitizeHeaderComponent(value: string): string {
+	return value.replace(NON_PRINTABLE_ASCII, "");
+}