@oh-my-pi/pi-coding-agent 15.7.2 → 15.7.5

package/src/autoresearch/tools/run-experiment.ts

@@ -1,12 +1,12 @@
-import * as childProcess from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { Text } from "@oh-my-pi/pi-tui";
 import { formatBytes } from "@oh-my-pi/pi-utils";
 import * as z from "zod/v4";
+import { executeBash } from "../../exec/bash-executor";
 import type { ToolDefinition } from "../../extensibility/extensions";
 import type { Theme } from "../../modes/theme/theme";
-import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, truncateTail } from "../../session/streaming-output";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, TailBuffer, truncateTail } from "../../session/streaming-output";
 import { replaceTabs, shortenPath } from "../../tools/render-utils";
 import * as git from "../../utils/git";
 import { parseWorkDirDirtyPaths } from "../git";
@@ -15,7 +15,6 @@ import {
 	EXPERIMENT_MAX_LINES,
 	formatElapsed,
 	formatNum,
-	killTree,
 	parseAsiLines,
 	parseMetricLines,
 	tryGitPrefix,
@@ -117,7 +116,7 @@ export function createRunExperimentTool(
 			let execution: ProcessExecutionResult;
 			try {
 				execution = await executeProcess({
-					command: ["bash", "-lc", resolvedCommand],
+					command: resolvedCommand,
 					cwd: ctx.cwd,
 					logPath: benchmarkLogPath,
 					timeoutMs,
@@ -268,68 +267,18 @@ export function createRunExperimentTool(
 	};
 }
 async function executeProcess(opts: {
-	command: string[];
+	command: string;
 	cwd: string;
 	logPath: string;
 	timeoutMs: number;
 	signal?: AbortSignal;
 	onProgress?(details: ProgressSnapshot): void;
 }): Promise<ProcessExecutionResult> {
-	const { promise, resolve, reject } = Promise.withResolvers<ProcessExecutionResult>();
-	const child = childProcess.spawn(opts.command[0] ?? "bash", opts.command.slice(1), {
-		cwd: opts.cwd,
-		detached: true,
-		stdio: ["ignore", "pipe", "pipe"],
-	});
-
-	const tailChunks: Buffer[] = [];
-	let chunksBytes = 0;
-	let killedByTimeout = false;
-	let resolved = false;
-	let writeStream: fs.WriteStream | undefined = fs.createWriteStream(opts.logPath);
-	let forceKillTimeout: NodeJS.Timeout | undefined;
-
-	const closeWriteStream = (): Promise<void> => {
-		if (!writeStream) return Promise.resolve();
-		const stream = writeStream;
-		writeStream = undefined;
-		return new Promise<void>((resolveClose, rejectClose) => {
-			stream.end((error?: Error | null) => {
-				if (error) {
-					rejectClose(error);
-					return;
-				}
-				resolveClose();
-			});
-		});
-	};
-
-	const cleanup = (): void => {
-		if (progressTimer) clearInterval(progressTimer);
-		if (timeoutHandle) clearTimeout(timeoutHandle);
-		if (forceKillTimeout) clearTimeout(forceKillTimeout);
-		opts.signal?.removeEventListener("abort", abortHandler);
-	};
-
-	const finish = (callback: () => void): void => {
-		if (resolved) return;
-		resolved = true;
-		cleanup();
-		callback();
-	};
-
-	const appendChunk = (data: Buffer): void => {
-		writeStream?.write(data);
-		tailChunks.push(data);
-		chunksBytes += data.length;
-		while (chunksBytes > DEFAULT_MAX_BYTES * 2 && tailChunks.length > 1) {
-			const removed = tailChunks.shift();
-			if (removed) chunksBytes -= removed.length;
-		}
-	};
+	const tailBuffer = new TailBuffer(DEFAULT_MAX_BYTES * 2);
 
+	const startedAt = Date.now();
 	const snapshot = (): ProgressSnapshot => {
-		const tail = truncateTail(Buffer.concat(tailChunks).toString("utf8"), {
+		const tail = truncateTail(tailBuffer.text(), {
 			maxBytes: DEFAULT_MAX_BYTES,
 			maxLines: DEFAULT_MAX_LINES,
 		});
@@ -342,71 +291,54 @@ async function executeProcess(opts: {
 		};
 	};
 
-	const killTreeWithEscalation = (): void => {
-		if (!child.pid) return;
-		killTree(child.pid);
-		forceKillTimeout = setTimeout(() => {
-			if (child.pid) killTree(child.pid, "SIGKILL");
-		}, 1_000);
-		forceKillTimeout.unref?.();
-	};
-
-	const startedAt = Date.now();
 	const progressTimer = opts.onProgress
 		? setInterval(() => {
 				opts.onProgress?.(snapshot());
 			}, 1000)
 		: undefined;
-	const timeoutHandle =
-		opts.timeoutMs > 0
-			? setTimeout(() => {
-					killedByTimeout = true;
-					killTreeWithEscalation();
-				}, opts.timeoutMs)
-			: undefined;
 
-	const abortHandler = (): void => {
-		killTreeWithEscalation();
+	const logSink = Bun.file(opts.logPath).writer();
+	let logSinkClosed = false;
+	const closeLogSink = async (): Promise<void> => {
+		if (logSinkClosed) return;
+		logSinkClosed = true;
+		await logSink.end();
 	};
-	if (opts.signal?.aborted) {
-		abortHandler();
-	} else {
-		opts.signal?.addEventListener("abort", abortHandler, { once: true });
-	}
-
-	child.stdout?.on("data", data => {
-		appendChunk(data);
-	});
-	child.stderr?.on("data", data => {
-		appendChunk(data);
-	});
-	child.on("error", error => {
-		void closeWriteStream().finally(() => {
-			finish(() => reject(error));
+	try {
+		const result = await executeBash(opts.command, {
+			cwd: opts.cwd,
+			sessionKey: `autoresearch:${opts.cwd}`,
+			timeout: opts.timeoutMs > 0 ? opts.timeoutMs : 2_147_000_000,
+			signal: opts.signal,
+			chunkThrottleMs: 0,
+			onChunk: chunk => {
+				tailBuffer.append(chunk);
+				logSink.write(chunk);
+			},
 		});
-	});
-	child.on("close", async code => {
-		try {
-			await closeWriteStream();
-			if (opts.signal?.aborted) {
-				finish(() => reject(new Error("aborted")));
-				return;
-			}
-			const output = await fs.promises.readFile(opts.logPath, "utf8");
-			finish(() =>
-				resolve({
-					exitCode: code,
-					killed: killedByTimeout,
-					logPath: opts.logPath,
-					output,
-				}),
-			);
-		} catch (error) {
-			finish(() => reject(error));
+		await closeLogSink();
+		if (opts.signal?.aborted) {
+			throw new Error("aborted");
 		}
-	});
 
-	return promise;
+		const output = await fs.promises.readFile(opts.logPath, "utf8");
+
+		return {
+			exitCode: result.exitCode ?? null,
+			killed: result.cancelled,
+			logPath: opts.logPath,
+			output,
+		};
+	} finally {
+		if (progressTimer) clearInterval(progressTimer);
+		if (!logSinkClosed) {
+			try {
+				await closeLogSink();
+			} catch {
+				// Preserve the command failure when cleanup is best-effort.
+			}
+		}
+	}
 }
 
 function buildRunText(details: RunDetails, outputPreview: string, bestMetric: number | null): string {

package/src/cli/args.ts

@@ -54,7 +54,12 @@ export interface Args {
 	unknownFlags: Map<string, boolean | string>;
 }
 
-export function parseArgs(args: string[], extensionFlags?: Map<string, { type: "boolean" | "string" }>): Args {
+export function parseArgs(inputArgs: string[], extensionFlags?: Map<string, { type: "boolean" | "string" }>): Args {
+	// Work on a copy: the `--option=value` handling below splices the value
+	// into the array, and callers reuse the same argv (the post-extension
+	// reparse in `runRootCommand` parses it a second time). Mutating the input
+	// would corrupt that later parse, so never touch the caller's array.
+	const args = [...inputArgs];
 	const result: Args = {
 		messages: [],
 		fileArgs: [],
@@ -63,17 +68,41 @@ export function parseArgs(args: string[], extensionFlags?: Map<string, { type: "
 
 	for (let i = 0; i < args.length; i++) {
 		let arg = args[i];
+		const flagIndex = i;
 
-		// Support --flag=value syntax (e.g. --tools=ask,read)
+		// Support --flag=value syntax (e.g. --tools=ask,read). The value is
+		// spliced in as the next token so value-consuming flags pick it up via
+		// `args[++i]`; a non-consuming flag (e.g. a boolean) leaves it behind and
+		// the post-loop guard drops it so it is not mistaken for a message.
+		let equalsValueIndex = -1;
 		if (arg.startsWith("--") && arg.includes("=")) {
 			const eqIdx = arg.indexOf("=");
 			const value = arg.slice(eqIdx + 1);
 			arg = arg.slice(0, eqIdx);
-			// Insert the value so the existing "args[++i]" logic picks it up
 			args.splice(i + 1, 0, value);
+			equalsValueIndex = i + 1;
 		}
 
-		if (arg === "--help" || arg === "-h") {
+		// Extension-registered flags take precedence over built-ins: a flag an
+		// extension owns (e.g. plan-mode's boolean `--plan`) is parsed with the
+		// extension's semantics rather than falling into a built-in branch. For a
+		// value-taking built-in (`--plan`, `--model`, …) that branch would consume
+		// the following token — eating the user's message and setting the wrong
+		// built-in field — so registered flags shadow same-named built-ins here.
+		const extFlag = arg.startsWith("--") ? extensionFlags?.get(arg.slice(2)) : undefined;
+		if (extFlag) {
+			const flagName = arg.slice(2);
+			if (extFlag.type === "boolean") {
+				result.unknownFlags.set(flagName, true);
+			} else if (extFlag.type === "string" && i + 1 < args.length) {
+				// Consume the value in `--flag=value` form, or when the next token is
+				// not flag-looking. A `-`-prefixed token in space form is left to be
+				// its own flag; pass a flag-looking value as `--flag=value`.
+				if (equalsValueIndex !== -1 || !args[i + 1].startsWith("-")) {
+					result.unknownFlags.set(flagName, args[++i]);
+				}
+			}
+		} else if (arg === "--help" || arg === "-h") {
 			result.help = true;
 		} else if (arg === "--version" || arg === "-v") {
 			result.version = true;
@@ -198,21 +227,15 @@ export function parseArgs(args: string[], extensionFlags?: Map<string, { type: "
 			}
 		} else if (arg.startsWith("@")) {
 			result.fileArgs.push(arg.slice(1)); // Remove @ prefix
-		} else if (arg.startsWith("--") && extensionFlags) {
-			// Check if it's an extension-registered flag
-			const flagName = arg.slice(2);
-			const extFlag = extensionFlags.get(flagName);
-			if (extFlag) {
-				if (extFlag.type === "boolean") {
-					result.unknownFlags.set(flagName, true);
-				} else if (extFlag.type === "string" && i + 1 < args.length) {
-					result.unknownFlags.set(flagName, args[++i]);
-				}
-			}
-			// Unknown flags without extensionFlags are silently ignored (first pass)
 		} else if (!arg.startsWith("-")) {
 			result.messages.push(arg);
 		}
+		// Drop an unconsumed `--flag=value` value (e.g. a boolean flag): when no
+		// branch advanced past the spliced token, remove it so it does not fall
+		// through to a later iteration and become a positional message.
+		if (equalsValueIndex !== -1 && i === flagIndex) {
+			args.splice(equalsValueIndex, 1);
+		}
 	}
 
 	return result;

package/src/cli/extension-flags.ts

@@ -0,0 +1,48 @@
+import { type Args, parseArgs } from "./args";
+
+/**
+ * Minimal extension-runner surface needed to resolve CLI flag values. The real
+ * `ExtensionRunner` satisfies this structurally; depending only on the surface
+ * keeps this module free of the heavier runner/session imports and unit-testable
+ * with a fake.
+ */
+export interface ExtensionFlagSink {
+	getFlags(): Map<string, { type: "boolean" | "string" }>;
+	setFlagValue(name: string, value: boolean | string): void;
+}
+
+/**
+ * Resolve extension-registered CLI flags from `rawArgs` once the flag set is
+ * known, push the resolved values onto the sink, and return the parsed
+ * {@link Args} (whose `messages` and `fileArgs` now reflect those flags).
+ *
+ * The startup parse runs before extensions load, so it cannot recognise their
+ * flags: a string flag's value (`--spawn-peer reviewer` or `--spawn-peer=reviewer`)
+ * is otherwise left in `messages` and leaks into the initial prompt. Re-parsing
+ * here — through the *same* {@link parseArgs} the startup pass uses, now seeded
+ * with the registered flags — consumes every flag form (`--flag`, `--flag value`,
+ * `--flag=value`).
+ *
+ * {@link parseArgs} lets a registered flag shadow a same-named built-in, so even
+ * a built-in-colliding flag (e.g. plan-mode's boolean `--plan`, which would
+ * otherwise hit the built-in plan-model branch) is parsed with the extension's
+ * semantics and surfaces in `unknownFlags` — without consuming the following
+ * message or overwriting the built-in field. No built-in name list to maintain.
+ *
+ * Returns `null` when there is no sink or no registered extension flags, in
+ * which case the caller keeps its original startup parse (an extension-aware
+ * re-parse would be identical anyway).
+ */
+export function applyExtensionFlags(runner: ExtensionFlagSink | undefined, rawArgs: string[]): Args | null {
+	const extensionFlags = runner?.getFlags();
+	if (!runner || !extensionFlags || extensionFlags.size === 0) {
+		return null;
+	}
+	const parsed = parseArgs(rawArgs, extensionFlags);
+	// `parseArgs` only records registered extension flags in `unknownFlags`, so
+	// every entry here is a flag this runner owns that was actually passed.
+	for (const [name, value] of parsed.unknownFlags) {
+		runner.setFlagValue(name, value);
+	}
+	return parsed;
+}

package/src/cli/plugin-cli.ts

@@ -348,10 +348,12 @@ async function handleInstall(
 	flags: { json?: boolean; force?: boolean; dryRun?: boolean; scope?: "user" | "project" },
 ): Promise<void> {
 	if (packages.length === 0) {
-		console.error(chalk.red(`Usage: ${APP_NAME} plugin install <package[@version]>[features] ...`));
+		console.error(chalk.red(`Usage: ${APP_NAME} plugin install <source>[features] ...`));
 		console.error(chalk.dim("Examples:"));
 		console.error(chalk.dim(`  ${APP_NAME} plugin install @oh-my-pi/exa`));
 		console.error(chalk.dim(`  ${APP_NAME} plugin install name@marketplace`));
+		console.error(chalk.dim(`  ${APP_NAME} plugin install github:user/repo`));
+		console.error(chalk.dim(`  ${APP_NAME} plugin install https://github.com/user/repo#v1.0`));
 		process.exit(1);
 	}
 
@@ -898,7 +900,7 @@ export function printPluginHelp(): void {
 	console.log(`${chalk.bold(`${APP_NAME} plugin`)} - Plugin lifecycle management
 
 ${chalk.bold("Commands:")}
-  install <pkg[@ver]>[features]  Install plugins from npm
+  install <source>[features]     Install plugins from npm, GitHub, or git URL
   uninstall <pkg>                Remove plugins
   list                           Show installed plugins
   link <path>                    Link local plugin for development
@@ -916,6 +918,12 @@ ${chalk.bold("Feature Syntax:")}
   pkg[*]             Install with all features
   pkg[]              Install with no optional features
 
+${chalk.bold("Sources:")}
+  pkg, pkg@1.2.3                  npm package (optionally pinned)
+  github:user/repo[#ref]          GitHub shorthand (also gitlab:, bitbucket:, codeberg:, sourcehut:)
+  https://github.com/user/repo    Full git URL (https, ssh, or git protocol)
+  name@marketplace                Marketplace plugin (see marketplace command)
+
 ${chalk.bold("Config Subcommands:")}
   config list <pkg>              List all settings
   config get <pkg> <key>         Get a setting value
@@ -938,5 +946,6 @@ ${chalk.bold("Examples:")}
   ${APP_NAME} plugin config set my-plugin apiKey sk-xxx
   ${APP_NAME} plugin doctor --fix
   ${APP_NAME} plugin install --scope project name@marketplace
+  ${APP_NAME} plugin install github:user/repo#v1.0
 `);
 }

package/src/cli.ts

@@ -1,4 +1,15 @@
 #!/usr/bin/env bun
+// Strip macOS malloc-stack-logging vars in the parent entrypoint, before any
+// subprocess/worker spawn. libmalloc reads MallocStackLogging /
+// MallocStackLoggingNoCompact during malloc bootstrap (pre-main) in every child
+// and warns when they're present but set to "off"; a child cannot suppress its
+// own warning, so the only fix is to keep them out of the inherited env here.
+// (They must be unset, not set — presence is the trigger.)
+try {
+	delete process.env.MallocStackLogging;
+	delete process.env.MallocStackLoggingNoCompact;
+} catch {}
+
 /**
  * CLI entry point — registers all commands explicitly and delegates to the
  * lightweight CLI runner from pi-utils.
@@ -43,12 +54,60 @@ async function runSmokeTest(): Promise<void> {
 	process.stdout.write("smoke-test: ok\n");
 }
 
+/**
+ * Hidden subcommand that boots the tiny-model worker inside this process
+ * over the parent's IPC channel. The agent's main process spawns the same
+ * binary with this flag so `onnxruntime-node` (loaded transitively by
+ * `@huggingface/transformers`) lives in a child address space. The parent
+ * `SIGKILL`s the child on shutdown so the NAPI finalizer never runs in
+ * either process — that finalizer segfaults Bun on Windows (issue #1606).
+ */
+async function runTinyWorker(): Promise<void> {
+	const { startTinyTitleWorker } = await import("./tiny/worker");
+	const { promise: shuttingDown, resolve: shutdown } = Promise.withResolvers<void>();
+	const send = (message: unknown): void => {
+		// `process.send` only exists when spawned with an IPC channel; the
+		// parent always spawns us that way. If it's missing, the parent
+		// vanished and there's no one to talk to.
+		const sender = (process as NodeJS.Process & { send?: (m: unknown) => boolean }).send;
+		if (!sender) {
+			shutdown();
+			return;
+		}
+		try {
+			sender.call(process, message);
+		} catch {
+			shutdown();
+		}
+	};
+	startTinyTitleWorker({
+		send,
+		onMessage(handler) {
+			const wrap = (data: unknown): void => handler(data as never);
+			process.on("message", wrap);
+			return () => {
+				process.off("message", wrap);
+			};
+		},
+	});
+	// Parent went away (crashed, SIGKILL, etc.) — commit suicide so we don't
+	// linger as an orphan. SIGKILL via `process.kill` keeps us symmetrical
+	// with the parent's hard-kill on shutdown: skip every JS/native finalizer.
+	process.on("disconnect", () => shutdown());
+	await shuttingDown;
+	process.kill(process.pid, "SIGKILL");
+}
+
 /** Run the CLI with the given argv (no `process.argv` prefix). */
 export async function runCli(argv: string[]): Promise<void> {
 	if (argv[0] === "--smoke-test") {
 		await runSmokeTest();
 		return;
 	}
+	if (argv[0] === "--tiny-worker") {
+		await runTinyWorker();
+		return;
+	}
 	// --help and --version are handled by run() directly, don't rewrite those.
 	// Everything else that isn't a known subcommand routes to "launch".
 	const first = argv[0];

package/src/config/config-file.ts

@@ -10,18 +10,44 @@ interface ConfigSchemaError {
 	message: string | undefined;
 }
 
+/**
+ * Module-private cache of (jsonPath, ymlPath) pairs we already migrated this
+ * process. Prevents `ConfigFile.relocate()` / repeated `tryLoad()` calls from
+ * re-running the migration over and over on the boot path.
+ */
+const migratedPaths = new Set<string>();
+
+function migrationKey(jsonPath: string, ymlPath: string): string {
+	return `${jsonPath}\u0000${ymlPath}`;
+}
+
+/**
+ * Synchronous JSON → YAML migration kept for callers that still want the
+ * eager path (settings init, tests that observe migration completion).
+ * Idempotent — re-running is a no-op.
+ */
 function migrateJsonToYml(jsonPath: string, ymlPath: string) {
+	const key = migrationKey(jsonPath, ymlPath);
+	if (migratedPaths.has(key)) return;
 	try {
-		if (fs.existsSync(ymlPath)) return;
-		if (!fs.existsSync(jsonPath)) return;
+		if (fs.existsSync(ymlPath)) {
+			migratedPaths.add(key);
+			return;
+		}
+		if (!fs.existsSync(jsonPath)) {
+			migratedPaths.add(key);
+			return;
+		}
 
 		const content = fs.readFileSync(jsonPath, "utf-8");
 		const parsed = JSON.parse(content);
 		if (!parsed) {
 			logger.warn("migrateJsonToYml: invalid json structure", { path: jsonPath });
+			migratedPaths.add(key);
 			return;
 		}
 		fs.writeFileSync(ymlPath, YAML.stringify(parsed, null, 2));
+		migratedPaths.add(key);
 	} catch (error) {
 		logger.warn("migrateJsonToYml: migration failed", { error: String(error) });
 	}
@@ -97,6 +123,7 @@ export type LoadResult<T> =
 
 export class ConfigFile<T> implements IConfigFile<T> {
 	readonly #basePath: string;
+	readonly #jsonMigrationPath: string | null;
 	#cache?: LoadResult<T>;
 	#auxValidate?: (value: T) => void;
 
@@ -107,22 +134,32 @@ export class ConfigFile<T> implements IConfigFile<T> {
 	) {
 		this.#basePath = configPath;
 		if (configPath.endsWith(".yml")) {
-			const jsonPath = `${configPath.slice(0, -4)}.json`;
-			migrateJsonToYml(jsonPath, configPath);
+			this.#jsonMigrationPath = `${configPath.slice(0, -4)}.json`;
 		} else if (configPath.endsWith(".yaml")) {
-			const jsonPath = `${configPath.slice(0, -5)}.json`;
-			migrateJsonToYml(jsonPath, configPath);
+			this.#jsonMigrationPath = `${configPath.slice(0, -5)}.json`;
 		} else if (configPath.endsWith(".json") || configPath.endsWith(".jsonc")) {
 			// JSON configs are still supported without migration.
+			this.#jsonMigrationPath = null;
 		} else {
 			throw new Error(`Invalid config file path: ${configPath}`);
 		}
 	}
 
+	/**
+	 * Run the JSON → YAML migration synchronously, if applicable. Idempotent.
+	 * Sync callers (tests, settings init) hit this implicitly via {@link tryLoad}.
+	 */
+	#ensureMigrated(): void {
+		if (this.#jsonMigrationPath) {
+			migrateJsonToYml(this.#jsonMigrationPath, this.#basePath);
+		}
+	}
+
 	relocate(configPath?: string): ConfigFile<T> {
 		if (!configPath || configPath === this.#basePath) return this;
 		const result = new ConfigFile<T>(this.id, this.schema, configPath);
 		result.#auxValidate = this.#auxValidate;
+		result.#ensureMigrated();
 		return result;
 	}
 
@@ -135,6 +172,13 @@ export class ConfigFile<T> implements IConfigFile<T> {
 		}
 	}
 
+	async getMtimeMsAsync(): Promise<number | null> {
+		const file = Bun.file(this.path());
+		if (!(await file.exists())) return null;
+		const lm = file.lastModified;
+		return typeof lm === "number" && Number.isFinite(lm) ? lm : null;
+	}
+
 	withValidation(name: string, validate: (value: T) => void): this {
 		const prev = this.#auxValidate;
 		this.#auxValidate = (value: T) => {
@@ -164,12 +208,8 @@ export class ConfigFile<T> implements IConfigFile<T> {
 		return result;
 	}
 
-	tryLoad(): LoadResult<T> {
-		if (this.#cache) return this.#cache;
-
+	#parseContent(content: string): LoadResult<T> {
 		try {
-			const content = fs.readFileSync(this.path(), "utf-8").trim();
-
 			let parsed: unknown;
 			if (this.#basePath.endsWith(".json") || this.#basePath.endsWith(".jsonc")) {
 				parsed = JSONC.parse(content);
@@ -202,26 +242,71 @@ export class ConfigFile<T> implements IConfigFile<T> {
 				return this.#storeCache({ error: wrapped, status: "error" });
 			}
 			return this.#storeCache({ value, status: "ok" });
+		} catch (error) {
+			logger.warn("Failed to parse config file", { path: this.path(), error });
+			return this.#storeCache({
+				error: new ConfigError(this.id, undefined, { err: error, stage: "Unexpected" }),
+				status: "error",
+			});
+		}
+	}
+
+	tryLoad(): LoadResult<T> {
+		if (this.#cache) return this.#cache;
+		this.#ensureMigrated();
+
+		let content: string;
+		try {
+			content = fs.readFileSync(this.path(), "utf-8").trim();
 		} catch (error) {
 			if (isEnoent(error)) {
 				return this.#storeCache({ status: "not-found" });
 			}
-			logger.warn("Failed to parse config file", { path: this.path(), error });
+			logger.warn("Failed to read config file", { path: this.path(), error });
 			return this.#storeCache({
-				error: new ConfigError(this.id, undefined, { err: error, stage: "Unexpected" }),
+				error: new ConfigError(this.id, undefined, { err: error, stage: "Read" }),
+				status: "error",
+			});
+		}
+		return this.#parseContent(content);
+	}
+
+	async tryLoadAsync(): Promise<LoadResult<T>> {
+		if (this.#cache) return this.#cache;
+		this.#ensureMigrated();
+
+		let content: string;
+		try {
+			content = (await Bun.file(this.path()).text()).trim();
+		} catch (error) {
+			if (isEnoent(error)) {
+				return this.#storeCache({ status: "not-found" });
+			}
+			logger.warn("Failed to read config file", { path: this.path(), error });
+			return this.#storeCache({
+				error: new ConfigError(this.id, undefined, { err: error, stage: "Read" }),
 				status: "error",
 			});
 		}
+		return this.#parseContent(content);
 	}
 
 	load(): T | null {
 		return this.tryLoad().value ?? null;
 	}
 
+	async loadAsync(): Promise<T | null> {
+		return (await this.tryLoadAsync()).value ?? null;
+	}
+
 	loadOrDefault(): T {
 		return this.tryLoad().value ?? this.createDefault();
 	}
 
+	async loadOrDefaultAsync(): Promise<T> {
+		return (await this.tryLoadAsync()).value ?? this.createDefault();
+	}
+
 	path(): string {
 		return this.#basePath;
 	}