@oh-my-pi/pi-coding-agent 17.0.8 → 17.1.0

package/src/tools/browser.ts

@@ -7,9 +7,24 @@ import type { ToolSession } from "../sdk";
 import { enforceInlineByteCap } from "../session/streaming-output";
 import { truncateForPrompt } from "./approval";
 import { resolveCmuxKind } from "./browser/cmux/rpc";
-import { acquireBrowser, type BrowserHandle, type BrowserKind, type BrowserKindTag } from "./browser/registry";
+import {
+	acquireBrowser,
+	type BrowserHandle,
+	type BrowserKind,
+	type BrowserKindTag,
+	holdBrowser,
+	releaseBrowser,
+} from "./browser/registry";
 import type { Observation, ScreenshotResult } from "./browser/tab-protocol";
-import { acquireTab, dropHeadlessTabs, getTab, releaseAllTabs, releaseTab, runInTab } from "./browser/tab-supervisor";
+import {
+	type AcquireTabResult,
+	acquireTab,
+	dropHeadlessTabs,
+	getTab,
+	releaseAllTabs,
+	releaseTab,
+	runInTab,
+} from "./browser/tab-supervisor";
 import type { OutputMeta } from "./output-meta";
 import { resolveToCwd } from "./path-utils";
 import { ToolAbortError, ToolError, throwIfAborted } from "./tool-errors";
@@ -232,52 +247,84 @@ export class BrowserTool implements AgentTool<typeof browserSchema, BrowserToolD
 			);
 		}
 
-		const browser = await untilAborted(signal, () =>
-			acquireBrowser(kind, {
-				cwd: this.session.cwd,
-				viewport: params.viewport
-					? {
-							width: params.viewport.width,
-							height: params.viewport.height,
-							deviceScaleFactor: params.viewport.scale,
-						}
-					: undefined,
-				appArgs: params.app?.args,
-				signal,
-			}),
-		);
+		// The requested timeout must cover the *entire* open — browser
+		// acquisition (CDP discovery/connect), queued tab acquisition, worker
+		// creation, and navigation — not only `acquireTab`. Compose one deadline
+		// from the caller signal and `params.timeout` and thread it through both
+		// stages so a stalled acquisition rejects at the requested boundary.
+		const timeoutSignal = AbortSignal.timeout(timeoutMs);
+		const openSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+		try {
+			const browser = await untilAborted(openSignal, () =>
+				acquireBrowser(kind, {
+					cwd: this.session.cwd,
+					viewport: params.viewport
+						? {
+								width: params.viewport.width,
+								height: params.viewport.height,
+								deviceScaleFactor: params.viewport.scale,
+							}
+						: undefined,
+					appArgs: params.app?.args,
+					signal: openSignal,
+				}),
+			);
+
+			// Hold one open-acquisition lease across the whole tab acquisition.
+			// A freshly-created browser sits in the registry at refCount 0 until a
+			// tab takes a hold; without this lease an abort/timeout mid-acquisition
+			// (or a sibling open of a different tab name on the same browser that
+			// fails) could dispose it out from under this operation. The lease is
+			// released exactly once — the success and failure paths are mutually
+			// exclusive — transferring ownership to the published tab on success or
+			// rolling the fresh browser back on failure.
+			holdBrowser(browser);
+			let result: AcquireTabResult;
+			try {
+				result = await untilAborted(openSignal, () =>
+					acquireTab(name, browser, {
+						url: params.url,
+						waitUntil: params.wait_until,
+						viewport: params.viewport
+							? {
+									width: params.viewport.width,
+									height: params.viewport.height,
+									deviceScaleFactor: params.viewport.scale,
+								}
+							: undefined,
+						target: params.app?.target,
+						timeoutMs,
+						dialogs: params.dialogs,
+						signal: openSignal,
+						ownerSessionId: this.session.getSessionId?.() ?? undefined,
+					}),
+				);
+			} catch (error) {
+				await releaseBrowser(browser, { kill: false });
+				throw error;
+			}
+			await releaseBrowser(browser, { kill: false });
 
-		const result = await untilAborted(signal, () =>
-			acquireTab(name, browser, {
-				url: params.url,
-				waitUntil: params.wait_until,
-				viewport: params.viewport
-					? {
-							width: params.viewport.width,
-							height: params.viewport.height,
-							deviceScaleFactor: params.viewport.scale,
-						}
-					: undefined,
-				target: params.app?.target,
-				timeoutMs,
-				dialogs: params.dialogs,
-				signal,
-				ownerSessionId: this.session.getSessionId?.() ?? undefined,
-			}),
-		);
-		const tab = result.tab;
-		const url = tab.info.url;
-		const title = tab.info.title ?? "";
-		details.url = url;
-		details.viewport = tab.info.viewport;
-		const verb = result.created ? "Opened" : "Reused";
-		const lines = [
-			`${verb} tab ${JSON.stringify(name)} on ${describeBrowser(browser)}`,
-			`URL: ${url}`,
-			title ? `Title: ${title}` : null,
-		].filter((l): l is string => typeof l === "string");
-		details.result = lines.join("\n");
-		return toolResult(details).text(lines.join("\n")).done();
+			const tab = result.tab;
+			const url = tab.info.url;
+			const title = tab.info.title ?? "";
+			details.url = url;
+			details.viewport = tab.info.viewport;
+			const verb = result.created ? "Opened" : "Reused";
+			const lines = [
+				`${verb} tab ${JSON.stringify(name)} on ${describeBrowser(browser)}`,
+				`URL: ${url}`,
+				title ? `Title: ${title}` : null,
+			].filter((l): l is string => typeof l === "string");
+			details.result = lines.join("\n");
+			return toolResult(details).text(lines.join("\n")).done();
+		} catch (error) {
+			// Caller cancellation stays a ToolAbortError; the requested timeout
+			// becomes a timeout ToolError; anything else passes through unchanged.
+			if (signal?.aborted) throw error instanceof ToolAbortError ? error : new ToolAbortError();
+			if (timeoutSignal.aborted) throw new ToolError(`Browser open timed out after ${timeoutMs}ms`);
+			throw error;
+		}
 	}
 
 	async #close(

package/src/tools/hub/index.ts

@@ -283,7 +283,7 @@ export class HubTool implements AgentTool<typeof hubSchema, HubDetails> {
 				if (!params.ids?.length) {
 					return hubErrorResult('`ids` is required for op="cancel".', { op: "cancel", jobs: [] });
 				}
-				return executeCancel(this.session, manager, this.#ownerId(), params.ids);
+				return await executeCancel(this.session, manager, this.#ownerId(), params.ids);
 			}
 			case "jobs": {
 				const manager = this.session.asyncJobManager;

package/src/tools/hub/jobs.ts

@@ -12,6 +12,7 @@ import { settings } from "../../config/settings";
 import type { RenderResultOptions } from "../../extensibility/custom-tools/types";
 import { shimmerEnabled, shimmerText } from "../../modes/theme/shimmer";
 import type { Theme } from "../../modes/theme/theme";
+import { USER_INTERRUPT_LABEL } from "../../session/messages";
 import { Ellipsis, Hasher, type RenderCache, renderStatusLine, renderTreeList, truncateToWidth } from "../../tui";
 import type { ToolSession } from "..";
 import {
@@ -304,26 +305,38 @@ export function nothingToWaitForResult(session: ToolSession): AgentToolResult<Co
 }
 
 /** `cancel`: kill the named jobs; returns immediately with outcomes + snapshots. */
-export function executeCancel(
+export async function executeCancel(
 	session: ToolSession,
 	manager: AsyncJobManager,
 	ownerId: string | undefined,
 	ids: string[],
-): AgentToolResult<CoordinationDetails> {
+): Promise<AgentToolResult<CoordinationDetails>> {
 	const ownerFilter = ownerId ? { ownerId } : undefined;
 	const cancelOutcomes: CancelOutcome[] = [];
 	for (const id of ids) {
 		const existing = manager.getJob(id);
 		if (!existing || (ownerId && existing.ownerId !== ownerId)) {
-			cancelOutcomes.push({ id, status: "not_found", message: `Background job not found: ${id}` });
+			// No job by this id (or it belongs to another agent): a budget-aborted
+			// keep-alive subagent lives on as a jobless registration long after its
+			// job row is reaped, so let cancel reach the agent registration too.
+			cancelOutcomes.push(await cancelAgentRegistration(session, ownerId, id));
 			continue;
 		}
 		if (existing.status !== "running") {
-			cancelOutcomes.push({
-				id,
-				status: "already_completed",
-				message: `Background job ${id} is already ${existing.status}.`,
-			});
+			// The job row settled but may still be inside the retention window.
+			// The agent registration behind it (job id == agent id for task
+			// spawns) can outlive the row as an idle/parked zombie — try the
+			// registration kill before reporting the row as already done.
+			const regOutcome = await cancelAgentRegistration(session, ownerId, id);
+			cancelOutcomes.push(
+				regOutcome.status === "cancelled"
+					? regOutcome
+					: {
+							id,
+							status: "already_completed",
+							message: `Background job ${id} is already ${existing.status}.`,
+						},
+			);
 			continue;
 		}
 		const cancelled = manager.cancel(id, ownerFilter);
@@ -336,6 +349,52 @@ export function executeCancel(
 	return buildJobResult(session, manager, "cancel", visibleJobs(manager, ids, ownerId), cancelOutcomes);
 }
 
+/**
+ * Kill a non-job-backed agent registration named by `id`: abort any in-flight
+ * turn, then release it from the lifecycle (dispose session + unregister). This
+ * is the only kill path for a keep-alive subagent that was budget-aborted, went
+ * `idle`/`parked`, and outlived its job row — otherwise it is unstoppable short
+ * of a broker restart (issue #6315). Scoped to the caller's own descendants so
+ * cross-agent kills stay impossible; a bare test/SDK caller (no owner id) may
+ * target any sub. Never touches Main, the caller, or advisor transcripts.
+ */
+async function cancelAgentRegistration(
+	session: ToolSession,
+	ownerId: string | undefined,
+	id: string,
+): Promise<CancelOutcome> {
+	const registry = session.agentRegistry;
+	const ref = registry?.get(id);
+	if (ref?.kind !== "sub") {
+		return { id, status: "not_found", message: `Background job not found: ${id}` };
+	}
+	if (id === ownerId) {
+		return { id, status: "not_found", message: `Cannot cancel yourself (${id}).` };
+	}
+	if (ownerId && ref.parentId !== ownerId) {
+		return { id, status: "not_found", message: `Agent ${id} was not spawned by you and cannot be cancelled.` };
+	}
+	const lifecycle = session.agentLifecycle?.();
+	try {
+		if (ref.status === "running" && ref.session) {
+			await ref.session.abort({ reason: USER_INTERRUPT_LABEL });
+		}
+		if (lifecycle) {
+			await lifecycle.release(id);
+		} else {
+			await ref.session?.dispose();
+			registry?.unregister(id);
+		}
+	} catch (error) {
+		return {
+			id,
+			status: "already_completed",
+			message: `Agent ${id} could not be fully cancelled: ${error instanceof Error ? error.message : String(error)}.`,
+		};
+	}
+	return { id, status: "cancelled", message: `Cancelled agent ${id} (killed session, dropped registration).` };
+}
+
 /** `jobs`: read-only snapshot of every job plus the jobless running-agent roster. */
 export function executeJobsSnapshot(
 	session: ToolSession,

package/src/tools/image-gen.ts

@@ -27,6 +27,7 @@ import { settings } from "../config/settings";
 import type { CustomTool } from "../extensibility/custom-tools/types";
 import { ohMyPiXAIUserAgent, resolveXAIHttpCredentials } from "../lib/xai-http";
 import imageGenDescription from "../prompts/tools/image-gen.md" with { type: "text" };
+import { AUTO_IMAGE_PROVIDER_ORDER, type ImageProvider, isImageProviderId } from "./image-providers";
 import { resolveReadPath } from "./path-utils";
 
 const DEFAULT_MODEL = "gemini-3-pro-image-preview";
@@ -44,7 +45,7 @@ const DEFAULT_ANTIGRAVITY_ENDPOINT_SANDBOX = "https://daily-cloudcode-pa.sandbox
 const IMAGE_SYSTEM_INSTRUCTION =
 	"You are an AI image generator. Generate images based on user descriptions. Focus on creating high-quality, visually appealing images that match the user's request.";
 
-export type ImageProvider = "antigravity" | "gemini" | "openai" | "openai-codex" | "openrouter" | "xai";
+export type { ImageProvider } from "./image-providers";
 export type ImageProviderPreference = ImageProvider | "auto";
 
 interface ImageApiKey {
@@ -57,17 +58,8 @@ interface ImageApiKey {
 const COMMON_IMAGE_ASPECT_RATIOS = ["1:1", "3:4", "4:3", "9:16", "16:9"] as const;
 const XAI_IMAGE_ASPECT_RATIOS = [...COMMON_IMAGE_ASPECT_RATIOS, "3:2", "2:3"] as const;
 const COMMON_IMAGE_ASPECT_RATIO_SET = new Set<string>(COMMON_IMAGE_ASPECT_RATIOS);
-const IMAGE_PROVIDER_CHOICES = [
-	"auto",
-	"antigravity",
-	"gemini",
-	"openai",
-	"openai-codex",
-	"openrouter",
-	"xai",
-] as const;
-const IMAGE_PROVIDER_PREFERENCES = new Set<string>(IMAGE_PROVIDER_CHOICES);
-const AUTO_IMAGE_PROVIDER_ORDER = ["openai", "openai-codex", "antigravity", "xai", "openrouter", "gemini"] as const;
+const IMAGE_PROVIDER_REQUEST_CHOICES = ["auto", ...AUTO_IMAGE_PROVIDER_ORDER] as const;
+const IMAGE_PROVIDER_PREFERENCES = new Set<string>(IMAGE_PROVIDER_REQUEST_CHOICES);
 
 const responseModalitySchema = type('"IMAGE" | "TEXT"');
 
@@ -81,8 +73,8 @@ const inputImageSchema = type({
 });
 
 const imageProviderSchema = type
-	.enumerated(...IMAGE_PROVIDER_CHOICES)
-	.describe("image provider for this request; overrides the providers.image setting (default: use the setting)");
+	.enumerated(...IMAGE_PROVIDER_REQUEST_CHOICES)
+	.describe("image provider for this request; overrides the providers.imageOrder setting (default: use the setting)");
 
 export const imageGenSchema = type({
 	subject: type("string").describe("main subject"),
@@ -447,16 +439,16 @@ function extractOpenRouterImageUrls(message: OpenRouterMessage | undefined): str
 	return urls;
 }
 
-/** Preferred provider set via settings (default: auto) */
-let preferredImageProvider: ImageProviderPreference = "auto";
+/** Configured provider priority set via `providers.imageOrder` (default: none). */
+let configuredImageProviderOrder: readonly ImageProvider[] = [];
 
 export function isImageProviderPreference(value: unknown): value is ImageProviderPreference {
 	return typeof value === "string" && IMAGE_PROVIDER_PREFERENCES.has(value);
 }
 
-/** Set the preferred image provider from settings */
-export function setPreferredImageProvider(provider: ImageProviderPreference): void {
-	preferredImageProvider = provider;
+/** Set the configured image-provider priority from settings; invalid IDs are dropped. */
+export function setImageProviderOrder(providers: readonly string[]): void {
+	configuredImageProviderOrder = providers.filter(isImageProviderId);
 }
 function assertImageAspectRatioSupported(provider: ImageProvider, aspectRatio: ImageGenParams["aspect_ratio"]): void {
 	if (!aspectRatio || provider === "xai" || COMMON_IMAGE_ASPECT_RATIO_SET.has(aspectRatio)) {
@@ -624,19 +616,19 @@ function activeImageProvider(model: Model | undefined): Exclude<ImageProviderPre
 	}
 }
 
-function imageProviderOrder(
-	activeModel: Model | undefined,
-	preference: ImageProviderPreference = preferredImageProvider,
-): Array<Exclude<ImageProviderPreference, "auto">> {
-	const providers: Array<Exclude<ImageProviderPreference, "auto">> = [];
-	const added = new Set<Exclude<ImageProviderPreference, "auto">>();
-	const add = (provider: Exclude<ImageProviderPreference, "auto"> | null): void => {
+function imageProviderOrder(activeModel: Model | undefined, requested?: ImageProviderPreference): ImageProvider[] {
+	const providers: ImageProvider[] = [];
+	const added = new Set<ImageProvider>();
+	const add = (provider: ImageProvider | null): void => {
 		if (!provider || added.has(provider)) return;
 		added.add(provider);
 		providers.push(provider);
 	};
 
-	if (preference !== "auto") add(preference);
+	// Per-request provider wins, then the configured priority list, then the
+	// active session's provider, then the built-in auto order.
+	if (requested !== undefined && requested !== "auto") add(requested);
+	for (const provider of configuredImageProviderOrder) add(provider);
 	add(activeImageProvider(activeModel));
 	for (const provider of AUTO_IMAGE_PROVIDER_ORDER) add(provider);
 	return providers;
@@ -1109,7 +1101,7 @@ export const imageGenTool: CustomTool<typeof imageGenSchema, ImageGenToolDetails
 	async execute(_toolCallId, params, _onUpdate, ctx, signal) {
 		return untilAborted(signal, async () => {
 			const sessionId = ctx.sessionManager.getSessionId();
-			const providerOrder = imageProviderOrder(ctx.model, params.provider ?? preferredImageProvider);
+			const providerOrder = imageProviderOrder(ctx.model, params.provider);
 			const cwd = ctx.sessionManager.getCwd();
 			const requestSignal = ptree.combineSignals(signal, IMAGE_TIMEOUT);
 			const fetchImpl = ctx.fetch ?? fetch;

package/src/tools/image-providers.ts

@@ -0,0 +1,50 @@
+/**
+ * Image Generation Providers
+ *
+ * Leaf module (no runtime deps) shared by the image_gen tool, the settings
+ * schema, and settings migrations — mirrors `web/search/types.ts` so the
+ * provider list, auto order, and settings choices never drift apart.
+ */
+
+/** Image generation backends, in settings/tool vocabulary. */
+export type ImageProvider = "antigravity" | "gemini" | "openai" | "openai-codex" | "openrouter" | "xai";
+
+/** Auto-resolution fallback order when no configured entry or session provider matches. */
+export const AUTO_IMAGE_PROVIDER_ORDER: readonly ImageProvider[] = [
+	"openai",
+	"openai-codex",
+	"antigravity",
+	"xai",
+	"openrouter",
+	"gemini",
+];
+
+/** Settings choices for `providers.imageOrder` (labels shared with the retired single-preference enum). */
+export const IMAGE_PROVIDER_CHOICES = [
+	{
+		value: "openai",
+		label: "OpenAI",
+		description: "OPENAI_API_KEY (gpt-image-2) or active GPT model; falls back to a connected Codex subscription",
+	},
+	{
+		value: "openai-codex",
+		label: "OpenAI Codex (ChatGPT)",
+		description: "Uses a connected Codex / ChatGPT subscription — no OPENAI_API_KEY needed",
+	},
+	{
+		value: "antigravity",
+		label: "Antigravity",
+		description: "Requires google-antigravity OAuth",
+	},
+	{
+		value: "xai",
+		label: "xAI Grok Imagine",
+		description: "Requires xAI Grok OAuth or XAI_API_KEY",
+	},
+	{ value: "gemini", label: "Gemini", description: "Requires GEMINI_API_KEY" },
+	{ value: "openrouter", label: "OpenRouter", description: "Requires OPENROUTER_API_KEY" },
+] as const satisfies ReadonlyArray<{ value: ImageProvider; label: string; description: string }>;
+
+export function isImageProviderId(value: unknown): value is ImageProvider {
+	return typeof value === "string" && AUTO_IMAGE_PROVIDER_ORDER.includes(value as ImageProvider);
+}

package/src/tools/index.ts

@@ -20,11 +20,13 @@ 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";
 import type { CustomMessage } from "../session/messages";
 import type { UsageStatistics } from "../session/session-entries";
+import type { SessionManager } from "../session/session-manager";
 import type { ToolChoiceQueue } from "../session/tool-choice-queue";
 import { TaskTool } from "../task";
 import type { AgentOutputManager } from "../task/output-manager";
@@ -143,6 +145,8 @@ export interface DeferredDiagnosticsEntry {
 export interface ToolSession {
 	/** Current working directory */
 	cwd: string;
+	/** Additional workspace directories beyond cwd (multi-root), forwarded to subagents. */
+	additionalDirectories?: string[];
 	/** Whether UI is available */
 	hasUI: boolean;
 	/**
@@ -214,6 +218,8 @@ export interface ToolSession {
 	getEvalSessionId?: () => string | null;
 	/** Get session file */
 	getSessionFile: () => string | null;
+	/** Parent session journal used by tools that persist runtime lifecycle state. */
+	sessionManager?: Pick<SessionManager, "appendCustomEntry" | "ensureOnDisk" | "flush" | "getBranch" | "getEntries">;
 	/** Get eval kernel owner ID for session-scoped retained-kernel cleanup. */
 	getEvalKernelOwnerId?: () => string | null;
 	/** Reject new eval work once session disposal has started. */
@@ -238,6 +244,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). */
@@ -510,6 +518,9 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 				if (!requestedTools.includes(name)) requestedTools.push(name);
 			}
 		}
+		if (session.settings.get("memory.backend") === "mnemopi" && !requestedTools.includes("memory_edit")) {
+			requestedTools.push("memory_edit");
+		}
 		// Auto-learn tools are gated by `autolearn.enabled` but, like the memory
 		// tools above, must also be force-included into an explicit requestedTools
 		// list so a restricted top-level session whose controller/guidance is
@@ -553,6 +564,7 @@ export async function createTools(session: ToolSession, toolNames?: string[]): P
 		if (name === "retain" || name === "recall" || name === "reflect") {
 			return ["hindsight", "mnemopi"].includes(session.settings.get("memory.backend") ?? "");
 		}
+		if (name === "memory_edit") return session.settings.get("memory.backend") === "mnemopi";
 		if (name === "manage_skill") return session.settings.get("autolearn.enabled") && (session.taskDepth ?? 0) === 0;
 		if (name === "learn") {
 			return (

package/src/tools/path-utils.ts

@@ -2,10 +2,11 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import * as url from "node:url";
-import { isEnoent, isEnotdir, stripWindowsExtendedLengthPathPrefix } from "@oh-my-pi/pi-utils";
+import { glob } from "@oh-my-pi/pi-natives";
+import { isEnoent, isEnotdir, stripWindowsExtendedLengthPathPrefix, untilAborted } from "@oh-my-pi/pi-utils";
 import type { Skill } from "../extensibility/skills";
 import { InternalUrlRouter, type LocalProtocolOptions } from "../internal-urls";
-import { ToolError } from "./tool-errors";
+import { ToolAbortError, ToolError } from "./tool-errors";
 
 const UNICODE_SPACES = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
 // A single line-range chunk: `N`, `N-M`, `N+K`, or open-ended `N-`. `..` is
@@ -1132,6 +1133,52 @@ export function resolveReadPath(filePath: string, cwd: string): string {
 	return resolved;
 }
 
+const WORKSPACE_SUFFIX_TIMEOUT_MS = 5000;
+
+function escapeGlobMetachars(value: string): string {
+	return value.replace(/[*?[{]/g, "[$&]");
+}
+
+/**
+ * Find a unique workspace entry whose trailing path matches a missing authored path.
+ * Returns `null` for no match, ambiguity, timeout, or scan failure.
+ */
+export async function findUniqueWorkspaceSuffix(
+	rawPath: string,
+	cwd: string,
+	signal?: AbortSignal,
+): Promise<{ absolutePath: string; displayPath: string } | null> {
+	const normalized = rawPath.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+	if (!normalized) return null;
+
+	const timeoutSignal = AbortSignal.timeout(WORKSPACE_SUFFIX_TIMEOUT_MS);
+	const combinedSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+
+	let matches: string[];
+	try {
+		const result = await untilAborted(combinedSignal, () =>
+			glob({
+				pattern: `**/${escapeGlobMetachars(normalized)}`,
+				path: cwd,
+				hidden: true,
+			}),
+		);
+		matches = result.matches.map(match => match.path);
+	} catch (error) {
+		if (error instanceof Error && error.name === "AbortError") {
+			if (!signal?.aborted) return null;
+			throw new ToolAbortError();
+		}
+		return null;
+	}
+
+	if (matches.length !== 1) return null;
+	return {
+		absolutePath: path.resolve(cwd, matches[0]),
+		displayPath: matches[0],
+	};
+}
+
 // =============================================================================
 // Tool-scope resolution (search/ast tools)
 // =============================================================================