@oh-my-pi/pi-coding-agent 15.11.1 → 15.11.3

package/src/session/agent-session.ts

@@ -171,7 +171,7 @@ import { GoalRuntime } from "../goals/runtime";
 import type { Goal, GoalModeState } from "../goals/state";
 import type { HindsightSessionState } from "../hindsight/state";
 import { type LocalProtocolOptions, resolveLocalUrlToPath } from "../internal-urls";
-import type { IrcMessage } from "../irc/bus";
+import { IrcBus, type IrcMessage } from "../irc/bus";
 import { resolveMemoryBackend } from "../memory-backend";
 import { getMnemopiSessionState, type MnemopiSessionState, setMnemopiSessionState } from "../mnemopi/state";
 import { containsOrchestrate, ORCHESTRATE_NOTICE } from "../modes/orchestrate";
@@ -185,6 +185,7 @@ import type { PlanModeState } from "../plan-mode/state";
 import autoContinuePrompt from "../prompts/system/auto-continue.md" with { type: "text" };
 import eagerTodoPrompt from "../prompts/system/eager-todo.md" with { type: "text" };
 import emptyStopRetryTemplate from "../prompts/system/empty-stop-retry.md" with { type: "text" };
+import ircAutoReplyTemplate from "../prompts/system/irc-autoreply.md" with { type: "text" };
 import ircIncomingTemplate from "../prompts/system/irc-incoming.md" with { type: "text" };
 import planModeActivePrompt from "../prompts/system/plan-mode-active.md" with { type: "text" };
 import planModeReferencePrompt from "../prompts/system/plan-mode-reference.md" with { type: "text" };
@@ -298,6 +299,7 @@ export type AgentSessionEvent =
 
 /** Listener function for agent session events */
 export type AgentSessionEventListener = (event: AgentSessionEvent) => void;
+export type CommandMetadataChangedListener = () => void | Promise<void>;
 export type AsyncJobSnapshotItem = Pick<AsyncJob, "id" | "type" | "status" | "label" | "startTime">;
 
 const EMPTY_STOP_MAX_RETRIES = 3;
@@ -884,6 +886,7 @@ export class AgentSession {
 	/** Last (enable, providerId) tuple resolved by `#syncAppendOnlyContext` — used to skip no-op invalidations. */
 	#lastAppendOnlyResolution?: { enable: boolean; providerId: string | undefined };
 	#eventListeners: AgentSessionEventListener[] = [];
+	#commandMetadataChangedListeners: CommandMetadataChangedListener[] = [];
 
 	/** Tracks pending steering messages for UI display. Removed when delivered.
 	 *  Entry shape: `{ text }` for plain-text steers (user-message dequeue
@@ -3034,6 +3037,27 @@ export class AgentSession {
 		};
 	}
 
+	subscribeCommandMetadataChanged(listener: CommandMetadataChangedListener): () => void {
+		this.#commandMetadataChangedListeners.push(listener);
+		return () => {
+			const index = this.#commandMetadataChangedListeners.indexOf(listener);
+			if (index !== -1) {
+				this.#commandMetadataChangedListeners.splice(index, 1);
+			}
+		};
+	}
+
+	#notifyCommandMetadataChanged(): void {
+		const listeners = [...this.#commandMetadataChangedListeners];
+		for (const listener of listeners) {
+			try {
+				void listener();
+			} catch (err) {
+				logger.error("Command metadata listener threw", { err });
+			}
+		}
+	}
+
 	/**
 	 * Temporarily disconnect from agent events.
 	 * User listeners are preserved and will receive events again after resubscribe().
@@ -3189,7 +3213,7 @@ export class AgentSession {
 		this.setHindsightSessionState(undefined);
 		hindsightState?.dispose();
 		const mnemopiState = setMnemopiSessionState(this, undefined);
-		mnemopiState?.dispose();
+		await mnemopiState?.dispose();
 		this.#disconnectFromAgent();
 		if (this.#unsubscribeAppendOnly) {
 			this.#unsubscribeAppendOnly();
@@ -4350,9 +4374,15 @@ export class AgentSession {
 		return [...this.#customCommands, ...this.#mcpPromptCommands];
 	}
 
+	/** MCP prompt commands only, for command-list metadata. */
+	get mcpPromptCommands(): ReadonlyArray<LoadedCustomCommand> {
+		return this.#mcpPromptCommands;
+	}
+
 	/** Update the MCP prompt commands list. Called when server prompts are (re)loaded. */
 	setMCPPromptCommands(commands: LoadedCustomCommand[]): void {
 		this.#mcpPromptCommands = commands;
+		this.#notifyCommandMetadataChanged();
 	}
 
 	// =========================================================================
@@ -4465,12 +4495,16 @@ export class AgentSession {
 		return { ...message, content: normalized } as T;
 	}
 
+	#magicKeywordEnabled(keyword: "orchestrate" | "ultrathink" | "workflow"): boolean {
+		return this.settings.get("magicKeywords.enabled") && this.settings.get(`magicKeywords.${keyword}`);
+	}
+
 	#createMagicKeywordNotices(text: string): CustomMessage[] {
 		const timestamp = Date.now();
 		const turnBudget = parseTurnBudget(text);
 		this.sessionManager.beginTurnBudget(turnBudget?.total ?? null, turnBudget?.hard ?? false);
 		const keywordNotices: CustomMessage[] = [];
-		if (containsUltrathink(text)) {
+		if (this.#magicKeywordEnabled("ultrathink") && containsUltrathink(text)) {
 			keywordNotices.push({
 				role: "custom",
 				customType: "ultrathink-notice",
@@ -4480,7 +4514,7 @@ export class AgentSession {
 				timestamp,
 			});
 		}
-		if (containsOrchestrate(text)) {
+		if (this.#magicKeywordEnabled("orchestrate") && containsOrchestrate(text)) {
 			keywordNotices.push({
 				role: "custom",
 				customType: "orchestrate-notice",
@@ -4490,7 +4524,7 @@ export class AgentSession {
 				timestamp,
 			});
 		}
-		if (containsWorkflow(text)) {
+		if (this.#magicKeywordEnabled("workflow") && containsWorkflow(text)) {
 			keywordNotices.push({
 				role: "custom",
 				customType: "workflow-notice",
@@ -5921,7 +5955,7 @@ export class AgentSession {
 		if (!model?.reasoning) return;
 
 		let resolved: Effort | undefined;
-		if (containsUltrathink(promptText)) {
+		if (this.#magicKeywordEnabled("ultrathink") && containsUltrathink(promptText)) {
 			// The user explicitly asked for maximum thinking; bypass the classifier
 			// and jump straight to the highest auto-supported level for this model.
 			resolved = clampAutoThinkingEffort(model, Effort.XHigh);
@@ -9118,11 +9152,20 @@ export class AgentSession {
 	 *   → "woken".
 	 *
 	 * Never blocks on the recipient's turn: the wake turn is fire-and-forget.
+	 *
+	 * When the sender expects a reply (`send await:true`) and this session is
+	 * mid-turn with async execution disabled, the next step boundary may be
+	 * gated on the sender's own batch finishing (blocking task spawns), so a
+	 * real reply turn can never happen in time. In that case an ephemeral
+	 * side-channel auto-reply is generated from the current context (the old
+	 * `respondAsBackground` path) and sent back over the bus on this agent's
+	 * behalf.
 	 */
-	async deliverIrcMessage(msg: IrcMessage): Promise<"injected" | "woken"> {
+	async deliverIrcMessage(msg: IrcMessage, opts?: { expectsReply?: boolean }): Promise<"injected" | "woken"> {
 		if (this.#isDisposed) {
 			throw new Error("Recipient session is disposed.");
 		}
+		const autoReply = (opts?.expectsReply ?? false) && this.isStreaming && !this.settings.get("async.enabled");
 		const record: CustomMessage = {
 			role: "custom",
 			customType: "irc:incoming",
@@ -9130,6 +9173,7 @@ export class AgentSession {
 				from: msg.from,
 				message: msg.body,
 				replyTo: msg.replyTo ?? "",
+				autoReplied: autoReply,
 			}),
 			display: true,
 			details: { id: msg.id, from: msg.from, message: msg.body, ...(msg.replyTo ? { replyTo: msg.replyTo } : {}) },
@@ -9139,6 +9183,7 @@ export class AgentSession {
 		void this.#emitSessionEvent({ type: "irc_message", message: record });
 		if (this.isStreaming) {
 			this.#pendingIrcAsides.push(record);
+			if (autoReply) void this.#runIrcAutoReply(msg);
 			return "injected";
 		}
 		// Idle: same wake primitive the yield queue uses for async-result
@@ -9149,6 +9194,50 @@ export class AgentSession {
 		return "woken";
 	}
 
+	/**
+	 * Generate and deliver an ephemeral auto-reply to `msg` on this agent's
+	 * behalf: a no-tools side-channel turn over the current history (same
+	 * pipeline as `/btw`), recorded into this session as an `irc:autoreply`
+	 * aside so the model knows what was said for it, and sent back to the
+	 * sender as a regular bus message (`replyTo: msg.id`) so their parked
+	 * `wait`/`await:true` resolves. Failures only log — the sender then hits
+	 * its normal wait timeout.
+	 */
+	async #runIrcAutoReply(msg: IrcMessage): Promise<void> {
+		try {
+			const { replyText } = await this.runEphemeralTurn({
+				promptText: prompt.render(ircAutoReplyTemplate, {
+					from: msg.from,
+					message: msg.body,
+					replyTo: msg.replyTo ?? "",
+				}),
+			});
+			const body = replyText.trim();
+			if (!body || this.#isDisposed) return;
+			const record: CustomMessage = {
+				role: "custom",
+				customType: "irc:autoreply",
+				content: `[IRC you → \`${msg.from}\` (auto)]\n\n${body}`,
+				display: true,
+				details: { to: msg.from, body, replyTo: msg.id },
+				attribution: "agent",
+				timestamp: Date.now(),
+			};
+			void this.#emitSessionEvent({ type: "irc_message", message: record });
+			// Asides drain at the next step boundary; anything left over is
+			// flushed at the start of the next prompt (#flushPendingIrcAsides).
+			this.#pendingIrcAsides.push(record);
+			// `from` must be the id the sender addressed (msg.to) so their
+			// from-filtered waiter matches.
+			const receipt = await IrcBus.global().send({ from: msg.to, to: msg.from, body, replyTo: msg.id });
+			if (receipt.outcome === "failed") {
+				logger.warn("IRC auto-reply delivery failed", { to: msg.from, error: receipt.error });
+			}
+		} catch (error) {
+			logger.warn("IRC auto-reply turn failed", { from: msg.from, error: String(error) });
+		}
+	}
+
 	/**
 	 * Emit an IRC relay observation event on this session for UI rendering only.
 	 * Does not persist the record to history. Called by the IrcBus to surface

package/src/slash-commands/available-commands.ts

@@ -0,0 +1,105 @@
+import type { AvailableCommand } from "@agentclientprotocol/sdk";
+import type { SkillsSettings } from "../config/settings";
+import type { LoadedCustomCommand } from "../extensibility/custom-commands";
+import type { ExtensionRunner } from "../extensibility/extensions";
+import { getSkillSlashCommandName, type Skill } from "../extensibility/skills";
+import { type FileSlashCommand, loadSlashCommands } from "../extensibility/slash-commands";
+import { ACP_BUILTIN_RESERVED_NAMES, isAcpBuiltinShadowedName } from "./acp-builtins";
+import { BUILTIN_SLASH_COMMANDS_INTERNAL } from "./builtin-registry";
+
+export type AvailableSlashCommandSource = "builtin" | "skill" | "extension" | "custom" | "mcp_prompt" | "file";
+
+export interface InternalAvailableSlashCommand {
+	name: string;
+	aliases?: string[];
+	description?: string;
+	input?: { hint: string };
+	subcommands?: Array<{ name: string; description?: string; usage?: string }>;
+	source: AvailableSlashCommandSource;
+}
+
+export interface AvailableCommandsSession {
+	readonly extensionRunner?: ExtensionRunner;
+	readonly customCommands: ReadonlyArray<LoadedCustomCommand>;
+	readonly mcpPromptCommands?: ReadonlyArray<LoadedCustomCommand>;
+	readonly skills: ReadonlyArray<Skill>;
+	readonly skillsSettings?: SkillsSettings;
+	setSlashCommands(slashCommands: FileSlashCommand[]): void;
+	sessionManager: { getCwd(): string };
+}
+
+export async function buildAvailableSlashCommands(
+	session: AvailableCommandsSession,
+	loadFileCommands: (cwd: string) => Promise<FileSlashCommand[]> = cwd => loadSlashCommands({ cwd }),
+): Promise<InternalAvailableSlashCommand[]> {
+	const commands: InternalAvailableSlashCommand[] = [];
+	const seenNames = new Set<string>();
+	const appendCommand = (command: InternalAvailableSlashCommand): void => {
+		if (seenNames.has(command.name)) return;
+		seenNames.add(command.name);
+		commands.push(command);
+	};
+
+	for (const command of BUILTIN_SLASH_COMMANDS_INTERNAL) {
+		if (!command.handle) continue;
+		const hint = command.acpInputHint ?? command.inlineHint;
+		appendCommand({
+			name: command.name,
+			aliases: command.aliases,
+			description: command.acpDescription ?? command.description,
+			input: hint ? { hint } : undefined,
+			subcommands: command.subcommands,
+			source: "builtin",
+		});
+	}
+
+	if (session.skillsSettings?.enableSkillCommands) {
+		for (const skill of session.skills) {
+			appendCommand({
+				name: getSkillSlashCommandName(skill),
+				description: skill.description || `Run ${skill.name} skill`,
+				input: { hint: "arguments" },
+				source: "skill",
+			});
+		}
+	}
+
+	const runner = session.extensionRunner;
+	if (runner) {
+		for (const command of runner.getRegisteredCommands(ACP_BUILTIN_RESERVED_NAMES)) {
+			if (isAcpBuiltinShadowedName(command.name)) continue;
+			appendCommand({
+				name: command.name,
+				description: command.description ?? "(extension command)",
+				input: { hint: "arguments" },
+				source: "extension",
+			});
+		}
+	}
+
+	for (const command of session.customCommands) {
+		const source: AvailableSlashCommandSource = command.path?.startsWith("mcp:") ? "mcp_prompt" : "custom";
+		appendCommand({
+			name: command.command.name,
+			description: command.command.description,
+			input: { hint: "arguments" },
+			source,
+		});
+	}
+
+	const fileCommands = await loadFileCommands(session.sessionManager.getCwd());
+	session.setSlashCommands(fileCommands);
+	for (const command of fileCommands) {
+		appendCommand({ name: command.name, description: command.description, source: "file" });
+	}
+
+	return commands;
+}
+
+export function toAcpAvailableCommands(commands: readonly InternalAvailableSlashCommand[]): AvailableCommand[] {
+	return commands.map(command => ({
+		name: command.name,
+		description: command.description ?? "",
+		input: command.input,
+	}));
+}

package/src/tools/bash.ts

@@ -368,7 +368,11 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 	readonly loadMode = "essential";
 	readonly description: string;
 	readonly parameters: BashToolSchema;
-	readonly concurrency = "exclusive";
+	// Non-pty calls run alongside each other (the executor isolates overlapping
+	// runs on the same shell session); pty takes over the terminal UI and must
+	// run alone.
+	readonly concurrency = (args: Partial<BashToolInput>): "shared" | "exclusive" =>
+		args.pty === true ? "exclusive" : "shared";
 	readonly strict = true;
 	readonly #asyncEnabled: boolean;
 	readonly #autoBackgroundEnabled: boolean;

package/src/tools/browser/attach.ts

@@ -1,6 +1,6 @@
 import * as net from "node:net";
 import { Process, ProcessStatus } from "@oh-my-pi/pi-natives";
-import type { Browser, Page } from "puppeteer-core";
+import { type Browser, type Page, TargetType } from "puppeteer-core";
 import { ToolError, throwIfAborted } from "../tool-errors";
 
 const ATTACH_TARGET_SKIP_PATTERN =
@@ -119,22 +119,41 @@ export async function findReusableCdp(
 }
 
 /**
- * Pick the best page target on an attached browser. Without a matcher, prefer
- * a page that doesn't look like a helper window (devtools, request handler,
- * background pages); with a matcher, return the first url+title substring hit.
+ * Pick the best page target on an attached browser. Prefer discoverable page
+ * targets first so Chromium/Edge attach flows that hide pages from
+ * `browser.pages()` can still return a usable tab.
  */
 export async function pickElectronTarget(browser: Browser, matcher?: string): Promise<Page> {
-	const pages = await browser.pages();
-	if (!pages.length) {
+	const discoveredPages = await Promise.all(
+		browser.targets().map(async target => {
+			if (target.type() !== TargetType.PAGE) return null;
+			return await target.page().catch(() => null);
+		}),
+	);
+	const usablePages = discoveredPages.filter((page): page is Page => page !== null);
+	if (usablePages.length > 0) {
+		return pickPageFromList(usablePages, matcher);
+	}
+
+	const fallbackPages = await browser.pages();
+	if (!fallbackPages.length) {
 		throw new ToolError("No page targets available on the attached browser");
 	}
-	const enriched = await Promise.all(
+	return pickPageFromList(fallbackPages, matcher);
+}
+
+async function enrichPages(pages: Page[]): Promise<Array<{ page: Page; url: string; title: string }>> {
+	return await Promise.all(
 		pages.map(async page => ({
 			page,
 			url: page.url(),
 			title: ((await page.title().catch(() => "")) ?? "").trim(),
 		})),
 	);
+}
+
+async function pickPageFromList(pages: Page[], matcher?: string): Promise<Page> {
+	const enriched = await enrichPages(pages);
 	if (matcher) {
 		const needle = matcher.toLowerCase();
 		const hit = enriched.find(p => p.url.toLowerCase().includes(needle) || p.title.toLowerCase().includes(needle));

package/src/tools/browser/registry.ts

@@ -58,6 +58,16 @@ export async function acquireBrowser(kind: BrowserKind, opts: AcquireBrowserOpti
 	return handle;
 }
 
+export function normalizeConnectedCdpUrl(rawCdpUrl: string): string {
+	const cdpUrl = rawCdpUrl.replace(/\/+$/, "");
+	if (/^wss?:\/\//i.test(cdpUrl)) {
+		throw new ToolError(
+			"browser app.cdp_url must be the HTTP CDP discovery endpoint (for example http://127.0.0.1:9222), not a ws:// browser websocket URL.",
+		);
+	}
+	return cdpUrl;
+}
+
 async function openBrowserHandle(kind: BrowserKind, opts: AcquireBrowserOptions): Promise<BrowserHandle> {
 	if (kind.kind === "headless") {
 		const browser = await launchHeadlessBrowser({ headless: kind.headless, viewport: opts.viewport });
@@ -70,7 +80,7 @@ async function openBrowserHandle(kind: BrowserKind, opts: AcquireBrowserOptions)
 		};
 	}
 	if (kind.kind === "connected") {
-		const cdpUrl = kind.cdpUrl.replace(/\/+$/, "");
+		const cdpUrl = normalizeConnectedCdpUrl(kind.cdpUrl);
 		await waitForCdp(cdpUrl, 5_000, opts.signal);
 		const puppeteer = await loadPuppeteer();
 		const browser = await puppeteer.connect({

package/src/tools/irc.ts

@@ -234,7 +234,15 @@ export class IrcTool implements AgentTool<typeof ircSchema, IrcDetails> {
 			// through the bus unfiltered so parked recipients are revived.
 			const targets = isBroadcast ? registry.listVisibleTo(senderId).map(ref => ref.id) : [to];
 			const receipts = await Promise.all(
-				targets.map(target => bus.send({ from: senderId, to: target, body: message, replyTo: params.replyTo })),
+				targets.map(target =>
+					bus.send(
+						{ from: senderId, to: target, body: message, replyTo: params.replyTo },
+						// Awaited sends mark the sender as blocked on an answer so a
+						// busy recipient that cannot reach a step boundary (async
+						// disabled) auto-replies instead of stranding the sender.
+						params.await ? { expectsReply: true } : undefined,
+					),
+				),
 			);
 
 			const lines: string[] = [];
@@ -457,13 +465,14 @@ function callMeta(args: IrcRenderArgs | undefined): string[] {
 
 /**
  * Display-only transcript card for live IRC traffic: `irc:incoming` DMs
- * delivered to this session and `irc:relay` observations of agent↔agent
+ * delivered to this session, `irc:autoreply` side-channel replies sent on
+ * this session's behalf, and `irc:relay` observations of agent↔agent
  * traffic. Shares the tool renderer's glyph + quote-border conventions so
  * cards and `irc` tool output look identical in the transcript.
  */
 export function createIrcMessageCard(
 	card: {
-		kind: "incoming" | "relay";
+		kind: "incoming" | "autoreply" | "relay";
 		from?: string;
 		to?: string;
 		body?: string;
@@ -477,9 +486,12 @@ export function createIrcMessageCard(
 	const title =
 		card.kind === "incoming"
 			? `IRC ${uiTheme.nav.back} ${from}`
-			: `IRC ${from} ${uiTheme.nav.selected} ${card.to?.trim() || "?"}`;
+			: card.kind === "autoreply"
+				? `IRC ${uiTheme.nav.selected} ${card.to?.trim() || "?"}`
+				: `IRC ${from} ${uiTheme.nav.selected} ${card.to?.trim() || "?"}`;
 	const body = card.body ?? "";
 	const meta: string[] = [];
+	if (card.kind === "autoreply") meta.push("auto");
 	if (card.replyTo) meta.push("reply");
 	const age = messageAge(card.timestamp);
 	if (age) meta.push(age);

package/src/tools/job.ts

@@ -449,17 +449,21 @@ export const jobToolRenderer = {
 		const counts = { completed: 0, failed: 0, cancelled: 0, running: 0 };
 		for (const job of jobs) counts[job.status]++;
 
+		// The title already carries the running count, so meta lists only the
+		// settled categories — "waiting on 19 of 19 · 19 running" read awkward.
 		const meta: string[] = [];
 		if (counts.completed > 0) meta.push(uiTheme.fg("success", `${counts.completed} done`));
 		if (counts.failed > 0) meta.push(uiTheme.fg("error", `${counts.failed} failed`));
 		if (counts.cancelled > 0) meta.push(uiTheme.fg("warning", `${counts.cancelled} cancelled`));
-		if (counts.running > 0) meta.push(uiTheme.fg("accent", `${counts.running} running`));
 
 		const headerIcon: ToolUIStatus = counts.failed > 0 ? "warning" : counts.running > 0 ? "info" : "success";
+		const jobsNoun = jobs.length === 1 ? "job" : "jobs";
 		const description =
 			counts.running > 0
-				? `waiting on ${counts.running} of ${jobs.length}`
-				: `${jobs.length} ${jobs.length === 1 ? "job" : "jobs"} settled`;
+				? counts.running === jobs.length
+					? `waiting on ${jobs.length} ${jobsNoun}`
+					: `waiting on ${counts.running} of ${jobs.length} ${jobsNoun}`
+				: `${jobs.length} ${jobsNoun} settled`;
 
 		const header = renderStatusLine(
 			{

package/src/tools/path-utils.ts

@@ -398,6 +398,11 @@ export function formatPathRelativeToCwd(
 export function stripOuterDoubleQuotes(input: string): string {
 	return input.startsWith('"') && input.endsWith('"') && input.length > 1 ? input.slice(1, -1) : input;
 }
+function normalizePathSeparators(input: string): string {
+	if (isInternalUrlPath(input)) return input;
+	if (!input.includes("\\")) return input;
+	return input.replace(/\\/g, "/");
+}
 
 export function normalizePathLikeInput(input: string): string {
 	return stripOuterDoubleQuotes(input.trim());
@@ -582,19 +587,20 @@ export interface ResolvedMultiFindPattern {
 	targets: ResolvedFindTarget[];
 	scopePath: string;
 }
-
-/**
- * Split a user path into a base path + glob pattern for tools that delegate to
- * APIs accepting separate `path` and `glob` arguments.
- */
 export function parseSearchPath(filePath: string): ParsedSearchPath {
-	const normalizedPath = filePath.replace(/\\/g, "/");
-	if (!hasGlobPathChars(normalizedPath)) {
-		return { basePath: filePath };
+	const normalizedPath = normalizePathSeparators(filePath);
+	const segments = normalizedPath.split("/");
+	let firstGlobIndex = -1;
+	for (let i = 0; i < segments.length; i++) {
+		if (hasGlobPathChars(segments[i])) {
+			firstGlobIndex = i;
+			break;
+		}
 	}
 
-	const segments = normalizedPath.split("/");
-	const firstGlobIndex = segments.findIndex(segment => hasGlobPathChars(segment));
+	if (firstGlobIndex === -1) {
+		return { basePath: normalizedPath };
+	}
 
 	if (firstGlobIndex <= 0) {
 		return { basePath: ".", glob: normalizedPath };
@@ -617,7 +623,7 @@ export async function parseSearchPathPreferringLiteral(filePath: string, cwd: st
 	if (!hasGlobPathChars(filePath) || isInternalUrlPath(filePath)) return parseSearchPath(filePath);
 	try {
 		await fs.promises.stat(resolveToCwd(filePath, cwd));
-		return { basePath: filePath };
+		return { basePath: normalizePathSeparators(filePath) };
 	} catch {
 		return parseSearchPath(filePath);
 	}
@@ -632,7 +638,8 @@ export async function parseSearchPathPreferringLiteral(filePath: string, cwd: st
 //   /abs/path/**/\*.ts -> { basePath: "/abs/path", globPattern: "**/*.ts", hasGlob: true }
 //   src/app -> { basePath: "src/app", globPattern: "**/*", hasGlob: false }
 export function parseFindPattern(pattern: string): ParsedFindPattern {
-	const segments = pattern.split("/");
+	const normalizedPattern = normalizePathSeparators(pattern);
+	const segments = normalizedPattern.split("/");
 	let firstGlobIndex = -1;
 	for (let i = 0; i < segments.length; i++) {
 		if (hasGlobPathChars(segments[i])) {
@@ -642,14 +649,14 @@ export function parseFindPattern(pattern: string): ParsedFindPattern {
 	}
 
 	if (firstGlobIndex === -1) {
-		return { basePath: pattern, globPattern: "**/*", hasGlob: false };
+		return { basePath: normalizedPattern, globPattern: "**/*", hasGlob: false };
 	}
 
 	if (firstGlobIndex === 0) {
-		const needsRecursive = !pattern.startsWith("**/");
+		const needsRecursive = !normalizedPattern.startsWith("**/");
 		return {
 			basePath: ".",
-			globPattern: needsRecursive ? `**/${pattern}` : pattern,
+			globPattern: needsRecursive ? `**/${normalizedPattern}` : normalizedPattern,
 			hasGlob: true,
 		};
 	}
@@ -722,6 +729,7 @@ async function resolveSearchPathItems(
 	pathItems: string[],
 	cwd: string,
 	suffixGlob?: string,
+	fanOutFileItems = false,
 ): Promise<ResolvedMultiSearchPath | undefined> {
 	if (pathItems.length < 1) {
 		return undefined;
@@ -753,14 +761,27 @@ async function resolveSearchPathItems(
 		}
 		return relativeBasePath === "." ? path.basename(item.absoluteBasePath) : relativeBasePath;
 	});
-	const rootPath = path.parse(commonBasePath).root;
-	const isDegenerateRoot = commonBasePath === rootPath && parsedItems.length > 1;
-	const targets = isDegenerateRoot
-		? parsedItems.map(item => ({
-				basePath: item.absoluteBasePath,
-				glob: item.parsedPath.glob ? combineSearchGlobs(item.parsedPath.glob, suffixGlob) : suffixGlob,
-			}))
-		: undefined;
+	// A single walk rooted at the common ancestor is only safe when that
+	// ancestor is itself one of the requested scopes (e.g. `.` + `src/foo.ts`):
+	// the walk then covers exactly what the caller asked for. When the common
+	// ancestor is an unrequested parent (`.` + `~/.gitconfig` → `$HOME`, or
+	// disjoint trees → `/`), a collapsed walk traverses every unrelated sibling
+	// under it — fan out into per-item targets so each scan stays bounded to a
+	// requested path.
+	const commonIsRequestedScope = parsedItems.some(item => item.absoluteBasePath === commonBasePath);
+	// Walkers prune `.git` unconditionally and honor gitignore, so a plain-file
+	// item folded into a directory walk's glob union (`.` + `.git/config`) can
+	// silently never match. Callers that dedupe overlapping results opt in via
+	// `fanOutFileItems` to get explicit file targets, which bypass the walker.
+	const demotesFileItem =
+		fanOutFileItems && !allExactFiles && parsedItems.some(item => !item.parsedPath.glob && item.stat.isFile());
+	const targets =
+		parsedItems.length > 1 && (!commonIsRequestedScope || demotesFileItem)
+			? parsedItems.map(item => ({
+					basePath: item.absoluteBasePath,
+					glob: item.parsedPath.glob ? combineSearchGlobs(item.parsedPath.glob, suffixGlob) : suffixGlob,
+				}))
+			: undefined;
 
 	return {
 		basePath: commonBasePath,
@@ -775,8 +796,9 @@ export async function resolveExplicitSearchPaths(
 	pathItems: string[],
 	cwd: string,
 	suffixGlob?: string,
+	fanOutFileItems = false,
 ): Promise<ResolvedMultiSearchPath | undefined> {
-	return resolveSearchPathItems([...new Set(pathItems)], cwd, suffixGlob);
+	return resolveSearchPathItems([...new Set(pathItems)], cwd, suffixGlob, fanOutFileItems);
 }
 
 async function resolveFindPatternItems(
@@ -921,6 +943,10 @@ export interface ToolScopeOptions {
 	trackImmutableSources?: boolean;
 	/** Honor `exactFilePaths` from {@link resolveExplicitSearchPaths} (search-only). */
 	surfaceExactFilePaths?: boolean;
+	/** Fan plain-file entries out into per-target scans instead of folding them
+	 * into a directory walk's glob union (search-only: the caller must dedupe
+	 * matches from overlapping targets). */
+	fanOutFileTargets?: boolean;
 	/** Extra hint appended to "Path not found" when stat fails and the user supplied multiple paths. */
 	multipathStatHint?: string;
 	/** Calling session's settings — forwarded to the internal-URL router so caller-aware handlers (issue://, pr://) honor it. */
@@ -1017,7 +1043,12 @@ export async function resolveToolSearchScope(opts: ToolScopeOptions): Promise<To
 		globFilter = parsedPath.glob;
 		scopePath = formatPathRelativeToCwd(searchPath, cwd);
 	} else {
-		const multiSearchPath = await resolveExplicitSearchPaths(effectivePaths, cwd);
+		const multiSearchPath = await resolveExplicitSearchPaths(
+			effectivePaths,
+			cwd,
+			undefined,
+			opts.fanOutFileTargets === true,
+		);
 		if (!multiSearchPath) {
 			throw new ToolError("`paths` must contain at least one path or glob");
 		}