@oh-my-pi/pi-coding-agent 17.0.7 → 17.0.9

package/src/tools/hub/launch.ts

@@ -74,6 +74,9 @@ const KEY_INPUT: Record<string, string> = {
 	LEFT: "\u001b[D",
 };
 
+/** Terminal daemon lifecycle states — the process is no longer running. */
+const TERMINAL_STATES: Partial<Record<DaemonState, true>> = { exited: true, failed: true };
+
 /** Structured launch state retained for compact TUI rendering. */
 export interface LaunchToolDetails {
 	op: LaunchParams["op"];
@@ -229,6 +232,8 @@ function toolContent(result: DaemonRpcResult, params: LaunchParams): string {
 				lines.push(
 					`NOT ready — readiness timed out after ${params.ready?.timeout ?? 30}s${cause}. The process is still running (state: ${daemon.state}); follow its logs or stop it.`,
 				);
+			} else if (params.ready && daemon.readyAt === undefined && TERMINAL_STATES[daemon.state]) {
+				lines.push("Process exited before readiness was observed.");
 			}
 			return lines.join("\n");
 		}
@@ -437,6 +442,8 @@ export function launchRenderResult(
 								: "Readiness timed out; the process is still running.",
 						),
 					);
+				} else if (params.ready && daemon && daemon.readyAt === undefined && TERMINAL_STATES[daemon.state]) {
+					body.push(theme.fg("warning", "Process exited before readiness was observed."));
 				}
 				break;
 			}

package/src/tools/index.ts

@@ -20,6 +20,7 @@ import { LspTool } from "../lsp";
 import type { MCPManager } from "../mcp";
 import type { MnemopiSessionState } from "../mnemopi/state";
 import type { PlanModeState } from "../plan-mode/state";
+import type { AgentLifecycleManager } from "../registry/agent-lifecycle";
 import type { AgentRegistry } from "../registry/agent-registry";
 import type { ArtifactManager } from "../session/artifacts";
 import type { ClientBridge } from "../session/client-bridge";
@@ -238,6 +239,8 @@ export interface ToolSession {
 	xdevRegistry?: XdevRegistry;
 	/** Agent registry for IRC routing across live sessions. */
 	agentRegistry?: AgentRegistry;
+	/** Idle→parked→revive lifecycle owner; lets the hub kill a non-job-backed agent registration. Default: AgentLifecycleManager.global(). */
+	agentLifecycle?: () => AgentLifecycleManager;
 	/** Get artifacts directory for artifact:// URLs */
 	getArtifactsDir?: () => string | null;
 	/** Get the ArtifactManager backing this session (shared across parent + subagents). */

package/src/tools/report-tool-issue.ts

@@ -5,16 +5,21 @@
  * `xd://report_issue`, and the system prompt tells the model to write
  * `<tool>: <concise description>` there when auto-QA is enabled.
  *
- * Enabled by default; gated behind PI_AUTO_QA=1 / `dev.autoqa` so a user who
- * flips the setting off short-circuits injection entirely.
+ * Enabled by default (`dev.autoqa` defaults to true); `PI_AUTO_QA=0` or an
+ * explicit `dev.autoqa: false` short-circuits injection entirely. When the
+ * user is only enabled by default (never configured `dev.autoqa` themselves),
+ * a persisted `dev.autoqaConsent: "denied"` also disables injection so a "No"
+ * in the consent dialog fully turns the feature off.
  * Records grievances to a local SQLite database; never throws from the device
  * dispatch path.
  *
- * Before the first record lands, the user's consent is checked. If they've
- * never been asked (`dev.autoqaConsent === "unset"`) the process-global
- * consent handler — wired by `InteractiveMode` to a Yes/No popup — is invoked
- * exactly once and the decision is persisted. Subsequent calls (including from
- * subagents) read the cached decision without prompting.
+ * Nothing is written until consent resolves. If the user has never been asked
+ * (`dev.autoqaConsent === "unset"`) the process-global consent handler —
+ * wired by `InteractiveMode` to a Yes/No popup — is invoked exactly once and
+ * the decision is persisted; a denial (or dismissal) drops the pending report
+ * without touching the database. Subsequent calls (including from subagents)
+ * read the cached decision without prompting. `PI_AUTO_QA_PUSH=1` bypasses
+ * the dialog for headless environments.
  *
  * When the user grants consent, push is automatically active against the
  * bundled endpoint (`dev.autoqaPush.endpoint`, default `qa.omp.sh`). Each
@@ -24,11 +29,13 @@
  * the network and never throws.
  */
 import { Database } from "bun:sqlite";
+import * as fs from "node:fs";
+import * as path from "node:path";
 import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
 import type { FetchImpl } from "@oh-my-pi/pi-ai";
 import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
-import { $env, $flag, getAutoQaDbDir, getInstallId, logger, VERSION } from "@oh-my-pi/pi-utils";
+import { $env, $flag, getAutoQaDbPath, getInstallId, logger, VERSION } from "@oh-my-pi/pi-utils";
 import type { Settings } from "..";
 import type { Theme } from "../modes/theme/theme";
 import { renderStatusLine, truncateToWidth } from "../tui";
@@ -88,8 +95,23 @@ function parseReportIssueBody(text: string): { tool: string; report: string } {
 	throw new ToolError(`Invalid report format. ${reportIssueDeviceUsage()}`);
 }
 
+/**
+ * Whether Auto-QA is active for this session.
+ *
+ * Precedence: `PI_AUTO_QA` env flag > explicit `dev.autoqa` setting >
+ * default-on unless the user previously denied consent. The denial veto only
+ * applies to the default: explicitly configuring `dev.autoqa: true` re-enables
+ * injection (recording still no-ops until consent is granted).
+ */
 export function isAutoQaEnabled(settings?: Settings): boolean {
-	return $flag("PI_AUTO_QA", !!settings?.get("dev.autoqa"));
+	let fallback = false;
+	if (settings) {
+		const enabled = !!settings.get("dev.autoqa");
+		fallback = settings.isConfigured("dev.autoqa")
+			? enabled
+			: enabled && settings.get("dev.autoqaConsent") !== "denied";
+	}
+	return $flag("PI_AUTO_QA", fallback);
 }
 
 // ───────────────────────────────────────────────────────────────────────────
@@ -233,15 +255,18 @@ let cachedDb: Database | null = null;
 
 /**
  * Open (or return the cached handle for) the auto-QA SQLite database at
- * `~/.omp/agent/autoqa.db`, creating the schema lazily. Returns `null` when
- * the agent data dir cannot be resolved.
+ * `~/.omp/autoqa.db` (XDG: `$XDG_DATA_HOME/omp/autoqa.db`), creating the
+ * schema lazily. Returns `null` when the path cannot be resolved or opened.
  */
 export function openAutoQaDb(): Database | null {
 	if (cachedDb) return cachedDb;
-	const dir = getAutoQaDbDir();
-	if (!dir) return null;
+	const dbPath = getAutoQaDbPath();
+	if (!dbPath) return null;
 	try {
-		const db = new Database(`${dir}/autoqa.db`, { create: true });
+		fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+		const db = new Database(dbPath, { create: true });
+		// Install the busy handler BEFORE any lock-taking statement. See #2421.
+		db.run("PRAGMA busy_timeout = 5000");
 		db.exec(`
 			CREATE TABLE IF NOT EXISTS grievances (
 				id INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -252,6 +277,17 @@ export function openAutoQaDb(): Database | null {
 				created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
 				pushed INTEGER NOT NULL DEFAULT 0
 			);
+		`);
+		// Legacy DBs (May 2026) predate `created_at`. ALTER TABLE only accepts
+		// constant defaults, so add it empty and backfill before the index below.
+		const hasCreatedAt = db.prepare("SELECT 1 FROM pragma_table_info('grievances') WHERE name = 'created_at'").get();
+		if (!hasCreatedAt) {
+			db.exec(`
+				ALTER TABLE grievances ADD COLUMN created_at TEXT NOT NULL DEFAULT '';
+				UPDATE grievances SET created_at = CURRENT_TIMESTAMP WHERE created_at = '';
+			`);
+		}
+		db.exec(`
 			CREATE INDEX IF NOT EXISTS grievances_pushed_created_at_idx
 			ON grievances (pushed, created_at, id);
 		`);
@@ -471,23 +507,38 @@ export async function flushGrievances(
 	}
 }
 
-/** Record a grievance row and trigger the background consent/flush pipeline. */
-async function recordToolIssue(session: ToolSession, tool: string, report: string): Promise<void> {
+/**
+ * Most recently scheduled record pipeline. Never rejects (the pipeline
+ * swallows its own errors); retained so tests can await the fire-and-forget
+ * work deterministically via {@link __awaitAutoQaRecordPipelineForTests}.
+ */
+let lastRecordPipeline: Promise<void> = Promise.resolve();
+
+/** Test-only: await the last consent → insert → flush pipeline. */
+export function __awaitAutoQaRecordPipelineForTests(): Promise<void> {
+	return lastRecordPipeline;
+}
+
+/**
+ * Queue a grievance for recording. The consent → insert → flush pipeline is
+ * fire-and-forget: nothing is written until the user grants consent (or
+ * `PI_AUTO_QA_PUSH=1` forces headless recording), and the device result
+ * returns immediately so the model never waits on the dialog or the network.
+ */
+function recordToolIssue(session: ToolSession, tool: string, report: string): void {
 	const canonicalTool = tool.startsWith("proxy_") ? tool.slice("proxy_".length) : tool;
-	const db = openAutoQaDb();
-	if (!db) return;
-	db.prepare("INSERT INTO grievances (model, version, tool, report) VALUES (?, ?, ?, ?)").run(
-		session.getActiveModelString?.() ?? "unknown",
-		VERSION,
-		canonicalTool,
-		report,
-	);
-	void (async () => {
+	const model = session.getActiveModelString?.() ?? "unknown";
+	lastRecordPipeline = (async () => {
 		try {
-			await resolveAutoQaConsent(session.settings);
+			if (!$flag("PI_AUTO_QA_PUSH") && !(await resolveAutoQaConsent(session.settings))) return;
+			const db = openAutoQaDb();
+			if (!db) return;
+			db.prepare(
+				"INSERT INTO grievances (model, version, tool, report, created_at) VALUES (?, ?, ?, ?, CURRENT_TIMESTAMP)",
+			).run(model, VERSION, canonicalTool, report);
 			await flushGrievances(db, session.settings);
 		} catch (error) {
-			logger.debug("autoqa post-insert pipeline failed", { error: String(error) });
+			logger.debug("autoqa consent pipeline failed", { error: String(error) });
 		}
 	})();
 }
@@ -504,7 +555,7 @@ export async function dispatchReportIssueDevice(
 	try {
 		if (isAutoQaEnabled(session.settings)) {
 			const { tool, report } = parseReportIssueBody(text);
-			await recordToolIssue(session, tool, report);
+			recordToolIssue(session, tool, report);
 		}
 	} catch (error) {
 		if (error instanceof ToolError) throw error;

package/src/tools/tool-timeouts.ts

@@ -21,10 +21,17 @@ export type ToolWithTimeout = keyof typeof TOOL_TIMEOUTS;
 
 /**
  * Clamp a raw timeout to the allowed range for a tool.
- * If rawTimeout is undefined, returns the tool's default.
+ *
+ * When `rawTimeout` is undefined the tool's `default` is used. A positive
+ * `maxTimeout` (the `tools.maxTimeout` global ceiling) caps the *resolved*
+ * value — including the default-fallback path — before the per-tool `min`/`max`
+ * floor and ceiling apply, so a configured global cap governs calls where the
+ * agent omits `timeout`, not only explicitly-passed values. `maxTimeout <= 0`
+ * means no global cap.
  */
-export function clampTimeout(tool: ToolWithTimeout, rawTimeout?: number): number {
+export function clampTimeout(tool: ToolWithTimeout, rawTimeout?: number, maxTimeout?: number): number {
 	const config = TOOL_TIMEOUTS[tool];
 	const timeout = rawTimeout ?? config.default;
-	return Math.max(config.min, Math.min(config.max, timeout));
+	const capped = maxTimeout !== undefined && maxTimeout > 0 ? Math.min(timeout, maxTimeout) : timeout;
+	return Math.max(config.min, Math.min(config.max, capped));
 }

package/src/tools/write.ts

@@ -85,6 +85,36 @@ import { renderXdevCall, renderXdevResult, type XdevDispatch } from "./xdev";
 
 const LOOSE_HASHLINE_HEADER_RE = /^\s*\[[^#\r\n]+#[^ \t\r\n]*\]\s*$/;
 const EXECUTABLE_NOTICE = "[Notice: Made executable via chmod +x]";
+const URI_LIKE_WRITE_PATH_RE = /^([a-z][a-z0-9+.-]*):\/{1,2}(.*)$/i;
+const XD_MISSING_DELIMITER_RE = /^xd\/+(.*)$/i;
+const XD_SCHEME_NEAR_MISSES: Record<string, true> = { dx: true, xdd: true, xdt: true };
+
+function assertWriteTargetAddressable(target: string, router: InternalUrlRouter): void {
+	const trimmed = target.trim();
+	if (path.win32.isAbsolute(trimmed) || router.canHandle(trimmed)) return;
+
+	const missingDelimiter = trimmed.match(XD_MISSING_DELIMITER_RE);
+	if (missingDelimiter) {
+		throw new ToolError(
+			`Unknown URI-like write target '${trimmed}'. Did you mean 'xd://${missingDelimiter[1]}'? Prefix the path with './' to write it as a filesystem path.`,
+		);
+	}
+
+	const uriLike = trimmed.match(URI_LIKE_WRITE_PATH_RE);
+	if (!uriLike) return;
+
+	const scheme = uriLike[1]!.toLowerCase();
+	// conflict:// has no router handler but is spliced downstream by
+	// parseConflictUri (which emits its own precise id/scope errors); let it pass.
+	if (scheme === "conflict") return;
+	const canonicalScheme = router.getHandler(scheme) ? scheme : XD_SCHEME_NEAR_MISSES[scheme] ? "xd" : undefined;
+	const suggestion = canonicalScheme
+		? ` Did you mean '${canonicalScheme}://${uriLike[2]}'?`
+		: " Tool devices use 'xd://<tool>'.";
+	throw new ToolError(
+		`Unknown URI-like write target '${trimmed}'.${suggestion} Prefix the path with './' to write it as a filesystem path.`,
+	);
+}
 
 const BULK_DIRECTIVE_RE = /^#?(\d+)\s*[:=]\s*(@ours|@theirs|@base|@both)$/;
 /**
@@ -987,6 +1017,7 @@ export class WriteTool implements AgentTool<typeof writeSchema, WriteToolDetails
 			// Strip hashline display prefixes ([PATH#HASH] + LINE:) if the model copied them from read output
 			const { text: cleanContent, stripped } = stripWriteContent(this.session, content);
 			const internalRouter = InternalUrlRouter.instance();
+			assertWriteTargetAddressable(path, internalRouter);
 			if (internalRouter.canHandle(path)) {
 				const parsed = parseInternalUrl(path);
 				const scheme = parsed.protocol.replace(/:$/, "").toLowerCase();

package/src/utils/changelog.ts

@@ -1,4 +1,5 @@
 import { getLastChangelogVersionPath, isEnoent, logger } from "@oh-my-pi/pi-utils";
+import bundledChangelog from "../../CHANGELOG.md" with { type: "text" };
 
 export interface ChangelogEntry {
 	major: number;
@@ -29,73 +30,68 @@ export interface StartupChangelogSelection {
 }
 
 /**
- * Parse changelog entries from the file at `changelogPath`. Scans for `## [x.y.z]`
- * headings and collects each block until the next heading or EOF.
+ * Parse changelog entries from omp's package asset when available, falling back
+ * to the copy embedded in compiled binaries.
  *
- * Returns `[]` when `changelogPath` is `undefined` (package directory not
- * resolvable — see `getChangelogPath`) or the file is missing. Callers MUST NOT
- * synthesize a fallback path from the host project's cwd; doing so caused issue
- * #1423 (the host project's `CHANGELOG.md` was rendered as omp's).
+ * The embedded fallback keeps standalone binaries self-contained without
+ * resolving relative to the host project's cwd, which caused issue #1423.
  */
 export async function parseChangelog(changelogPath: string | undefined): Promise<ChangelogEntry[]> {
-	if (!changelogPath) {
-		return [];
-	}
-	try {
-		const content = await Bun.file(changelogPath).text();
-		const lines = content.split("\n");
-		const entries: ChangelogEntry[] = [];
-
-		let currentLines: string[] = [];
-		let currentVersion: { major: number; minor: number; patch: number } | null = null;
-
-		for (const line of lines) {
-			// Check if this is a version header (## [x.y.z] ...)
-			if (line.startsWith("## ")) {
-				// Save previous entry if exists
-				if (currentVersion && currentLines.length > 0) {
-					entries.push({
-						...currentVersion,
-						content: currentLines.join("\n").trim(),
-					});
-				}
-
-				// Try to parse version from this line
-				const versionMatch = line.match(/##\s+\[?(\d+)\.(\d+)\.(\d+)\]?/);
-				if (versionMatch) {
-					currentVersion = {
-						major: Number.parseInt(versionMatch[1], 10),
-						minor: Number.parseInt(versionMatch[2], 10),
-						patch: Number.parseInt(versionMatch[3], 10),
-					};
-					currentLines = [line];
-				} else {
-					// Reset if we can't parse version
-					currentVersion = null;
-					currentLines = [];
-				}
-			} else if (currentVersion) {
-				// Collect lines for current version
-				currentLines.push(line);
+	let content = bundledChangelog;
+	if (changelogPath) {
+		try {
+			content = await Bun.file(changelogPath).text();
+		} catch (error) {
+			if (!isEnoent(error)) {
+				logger.error(`Warning: Could not parse changelog: ${error}`);
 			}
 		}
+	}
 
-		// Save last entry
-		if (currentVersion && currentLines.length > 0) {
-			entries.push({
-				...currentVersion,
-				content: currentLines.join("\n").trim(),
-			});
-		}
+	return parseChangelogContent(content);
+}
 
-		return entries;
-	} catch (error) {
-		if (isEnoent(error)) {
-			return [];
+function parseChangelogContent(content: string): ChangelogEntry[] {
+	const lines = content.split("\n");
+	const entries: ChangelogEntry[] = [];
+
+	let currentLines: string[] = [];
+	let currentVersion: { major: number; minor: number; patch: number } | null = null;
+
+	for (const line of lines) {
+		if (line.startsWith("## ")) {
+			if (currentVersion && currentLines.length > 0) {
+				entries.push({
+					...currentVersion,
+					content: currentLines.join("\n").trim(),
+				});
+			}
+
+			const versionMatch = line.match(/##\s+\[?(\d+)\.(\d+)\.(\d+)\]?/);
+			if (versionMatch) {
+				currentVersion = {
+					major: Number.parseInt(versionMatch[1], 10),
+					minor: Number.parseInt(versionMatch[2], 10),
+					patch: Number.parseInt(versionMatch[3], 10),
+				};
+				currentLines = [line];
+			} else {
+				currentVersion = null;
+				currentLines = [];
+			}
+		} else if (currentVersion) {
+			currentLines.push(line);
 		}
-		logger.error(`Warning: Could not parse changelog: ${error}`);
-		return [];
 	}
+
+	if (currentVersion && currentLines.length > 0) {
+		entries.push({
+			...currentVersion,
+			content: currentLines.join("\n").trim(),
+		});
+	}
+
+	return entries;
 }
 
 /**

package/src/utils/git.ts

@@ -217,6 +217,12 @@ export const GIT_NETWORK_TIMEOUT_MS = 30 * 60 * 1000;
 export const GIT_COMMAND_OUTPUT_LIMIT_BYTES = 8 * 1024 * 1024;
 
 const GIT_COMMAND_TIMEOUT_EXIT_CODE = 124;
+// Exit code returned when the `git` binary cannot be launched at all (spawn
+// ENOENT). Mirrors the POSIX "command not found" code so read-only callers that
+// degrade on any non-zero exit treat a missing git the same as a failed
+// invocation instead of letting the raw spawn ENOENT escape as an unhandled
+// rejection.
+const GIT_SPAWN_ENOENT_EXIT_CODE = 127;
 const GIT_OUTPUT_TRUNCATED_MARKER = "\n[git subprocess output truncated after 8 MiB]\n";
 const GIT_COMMAND_TERMINATE_GRACE_MS = 5_000;
 
@@ -388,6 +394,29 @@ function ensureAvailable(): void {
 	}
 }
 
+/**
+ * Launch a `git` plumbing command synchronously and decode stdout. Returns the
+ * exit code plus trimmed stdout; a missing `git` binary (spawn ENOENT) is
+ * reported as {@link GIT_SPAWN_ENOENT_EXIT_CODE} so sync read-only callers
+ * degrade to `null` instead of throwing an uncaught error during rendering.
+ */
+function gitSpawnSyncText(cwd: string, args: readonly string[]): { exitCode: number; stdout: string } {
+	const commandArgs = withShortLivedGitConfig(withNoOptionalLocks(args));
+	try {
+		const result = Bun.spawnSync(["git", ...commandArgs], {
+			cwd,
+			env: buildGitEnv(),
+			stdout: "pipe",
+			stderr: "pipe",
+			windowsHide: true,
+		});
+		return { exitCode: result.exitCode ?? 0, stdout: new TextDecoder().decode(result.stdout).trim() };
+	} catch (err) {
+		if (isEnoent(err)) return { exitCode: GIT_SPAWN_ENOENT_EXIT_CODE, stdout: "" };
+		throw err;
+	}
+}
+
 function formatCommandFailure(
 	args: readonly string[],
 	result: Pick<GitCommandResult, "exitCode" | "stdout" | "stderr">,
@@ -401,15 +430,26 @@ function formatCommandFailure(
 
 async function git(cwd: string, args: readonly string[], options: CommandOptions = {}): Promise<GitCommandResult> {
 	const commandArgs = withShortLivedGitConfig(options.readOnly ? withNoOptionalLocks(args) : [...args]);
-	const child = Bun.spawn(["git", ...commandArgs], {
-		cwd,
-		env: buildGitEnv(options.env),
-		signal: options.signal,
-		stdin: normalizeStdin(options.stdin),
-		stdout: "pipe",
-		stderr: "pipe",
-		windowsHide: true,
-	});
+	let child: Subprocess;
+	try {
+		child = Bun.spawn(["git", ...commandArgs], {
+			cwd,
+			env: buildGitEnv(options.env),
+			signal: options.signal,
+			stdin: normalizeStdin(options.stdin),
+			stdout: "pipe",
+			stderr: "pipe",
+			windowsHide: true,
+		});
+	} catch (err) {
+		if (isEnoent(err)) {
+			// A deleted/nonexistent cwd also surfaces as a spawn ENOENT; only blame
+			// the binary when the working directory actually exists.
+			const stderr = fs.existsSync(cwd) ? "git is not installed." : `working directory does not exist: ${cwd}`;
+			return { exitCode: GIT_SPAWN_ENOENT_EXIT_CODE, stdout: "", stderr };
+		}
+		throw err;
+	}
 
 	return await collectSubprocessResult("git", commandArgs, child, options);
 }
@@ -890,28 +930,12 @@ async function resolveHeadStateReftable(repository: GitRepository, signal?: Abor
 }
 
 function resolveHeadStateReftableSync(repository: GitRepository): GitHeadState | null {
-	ensureAvailable();
-	const symArgs = withShortLivedGitConfig(withNoOptionalLocks(["symbolic-ref", "HEAD"]));
-	const symResult = Bun.spawnSync(["git", ...symArgs], {
-		cwd: repository.repoRoot,
-		env: buildGitEnv(),
-		stdout: "pipe",
-		stderr: "pipe",
-		windowsHide: true,
-	});
-
-	const revArgs = withShortLivedGitConfig(withNoOptionalLocks(["rev-parse", "--verify", "HEAD"]));
-	const revResult = Bun.spawnSync(["git", ...revArgs], {
-		cwd: repository.repoRoot,
-		env: buildGitEnv(),
-		stdout: "pipe",
-		stderr: "pipe",
-		windowsHide: true,
-	});
-	const commit = revResult.exitCode === 0 ? new TextDecoder().decode(revResult.stdout).trim() || null : null;
+	const symResult = gitSpawnSyncText(repository.repoRoot, ["symbolic-ref", "HEAD"]);
+	const revResult = gitSpawnSyncText(repository.repoRoot, ["rev-parse", "--verify", "HEAD"]);
+	const commit = revResult.exitCode === 0 ? revResult.stdout || null : null;
 
 	if (symResult.exitCode === 0) {
-		const ref = new TextDecoder().decode(symResult.stdout).trim();
+		const ref = symResult.stdout;
 		const branchName = ref.startsWith(LOCAL_BRANCH_PREFIX) ? ref.slice(LOCAL_BRANCH_PREFIX.length) : null;
 		return {
 			...repository,
@@ -933,29 +957,13 @@ function resolveHeadStateReftableSync(repository: GitRepository): GitHeadState |
 
 function readRefSync(repository: GitRepository, targetRef: string): string | null {
 	if (isReftableRepoSync(repository)) {
-		ensureAvailable();
-		const symArgs = withShortLivedGitConfig(withNoOptionalLocks(["symbolic-ref", targetRef]));
-		const symResult = Bun.spawnSync(["git", ...symArgs], {
-			cwd: repository.repoRoot,
-			env: buildGitEnv(),
-			stdout: "pipe",
-			stderr: "pipe",
-			windowsHide: true,
-		});
+		const symResult = gitSpawnSyncText(repository.repoRoot, ["symbolic-ref", targetRef]);
 		if (symResult.exitCode === 0) {
-			const stdoutText = new TextDecoder().decode(symResult.stdout).trim();
-			return `${HEAD_REF_PREFIX} ${stdoutText}`;
+			return `${HEAD_REF_PREFIX} ${symResult.stdout}`;
 		}
-		const revArgs = withShortLivedGitConfig(withNoOptionalLocks(["rev-parse", "--verify", targetRef]));
-		const revResult = Bun.spawnSync(["git", ...revArgs], {
-			cwd: repository.repoRoot,
-			env: buildGitEnv(),
-			stdout: "pipe",
-			stderr: "pipe",
-			windowsHide: true,
-		});
+		const revResult = gitSpawnSyncText(repository.repoRoot, ["rev-parse", "--verify", targetRef]);
 		if (revResult.exitCode === 0) {
-			return new TextDecoder().decode(revResult.stdout).trim() || null;
+			return revResult.stdout || null;
 		}
 		return null;
 	}

package/src/web/search/providers/firecrawl.ts

@@ -4,7 +4,14 @@
  * Calls Firecrawl's search API and maps web results into the unified
  * SearchResponse shape used by the web search tool.
  */
-import { type ApiKey, type AuthStorage, type FetchImpl, getEnvApiKey, withAuth } from "@oh-my-pi/pi-ai";
+import {
+	type AuthStorage,
+	type FetchImpl,
+	getEnvApiKey,
+	resolveApiKeyOnce,
+	seedApiKeyResolver,
+	withAuth,
+} from "@oh-my-pi/pi-ai";
 import type { SearchResponse, SearchSource } from "../../../web/search/types";
 import { SearchProviderError } from "../../../web/search/types";
 import { clampNumResults } from "../utils";
@@ -66,13 +73,19 @@ function buildRequestBody(params: FirecrawlSearchParams): Record<string, unknown
 	return body;
 }
 
-async function callFirecrawlSearch(apiKey: string, params: FirecrawlSearchParams): Promise<FirecrawlSearchResponse> {
+async function callFirecrawlSearch(
+	apiKey: string | undefined,
+	params: FirecrawlSearchParams,
+): Promise<FirecrawlSearchResponse> {
+	const headers: Record<string, string> = {
+		"Content-Type": "application/json",
+	};
+	if (apiKey) {
+		headers.Authorization = `Bearer ${apiKey}`;
+	}
 	const response = await (params.fetch ?? fetch)(FIRECRAWL_SEARCH_URL, {
 		method: "POST",
-		headers: {
-			"Content-Type": "application/json",
-			Authorization: `Bearer ${apiKey}`,
-		},
+		headers,
 		body: JSON.stringify(buildRequestBody(params)),
 		signal: withHardTimeout(params.signal),
 	});
@@ -100,16 +113,24 @@ export async function searchFirecrawl(params: SearchParams): Promise<SearchRespo
 		signal: params.signal,
 		fetch: params.fetch,
 	};
-	const keyOrResolver: ApiKey = params.authStorage.resolver("firecrawl", {
+	const keyResolver = params.authStorage.resolver("firecrawl", {
 		sessionId: params.sessionId,
 	});
 	const numResults = clampNumResults(firecrawlParams.num_results, DEFAULT_NUM_RESULTS, MAX_NUM_RESULTS);
 
-	const data = await withAuth(keyOrResolver, key => callFirecrawlSearch(key, firecrawlParams), {
-		signal: params.signal,
-		missingKeyMessage:
-			'Firecrawl credentials not found. Set FIRECRAWL_API_KEY or configure an API key for provider "firecrawl".',
-	});
+	const resolvedKey = await resolveApiKeyOnce(keyResolver, params.signal);
+	let data: FirecrawlSearchResponse;
+	if (resolvedKey) {
+		// Reuse the preflight credential for the initial authenticated attempt.
+		const seededResolver = seedApiKeyResolver(resolvedKey, keyResolver);
+		data = await withAuth(seededResolver, key => callFirecrawlSearch(key, firecrawlParams), {
+			signal: params.signal,
+		});
+	} else {
+		// Keyless mode — omit Authorization header
+		data = await callFirecrawlSearch(undefined, firecrawlParams);
+	}
+
 	const sources: SearchSource[] = [];
 
 	for (const result of data.data?.web ?? []) {
@@ -125,7 +146,7 @@ export async function searchFirecrawl(params: SearchParams): Promise<SearchRespo
 		provider: "firecrawl",
 		sources: sources.slice(0, numResults),
 		requestId: data.id ?? undefined,
-		authMode: "api_key",
+		authMode: resolvedKey ? "api_key" : "keyless",
 	};
 }
 
@@ -134,10 +155,22 @@ export class FirecrawlProvider extends SearchProvider {
 	readonly id = "firecrawl";
 	readonly label = "Firecrawl";
 
+	/**
+	 * Auto-chain admission: requires a credential so an unconfigured Firecrawl
+	 * doesn't displace other providers that the user has set up with API keys.
+	 */
 	isAvailable(authStorage: AuthStorage): boolean {
 		return authStorage.hasAuth("firecrawl") || !!getEnvApiKey("firecrawl");
 	}
 
+	/**
+	 * Firecrawl supports keyless mode, so an explicit user selection
+	 * (`webSearch: firecrawl`) works without any credential configured.
+	 */
+	isExplicitlyAvailable(_authStorage: AuthStorage): boolean {
+		return true;
+	}
+
 	search(params: SearchParams): Promise<SearchResponse> {
 		return searchFirecrawl(params);
 	}