@oh-my-pi/pi-coding-agent 16.1.19 → 16.1.21

package/src/mcp/manager.ts

@@ -1229,8 +1229,15 @@ export class MCPManager {
 				const tokenUrl = material?.tokenUrl;
 				const clientId = material?.clientId;
 				const clientSecret = material?.clientSecret;
-				const resource =
-					material?.resource ?? (config.type === "http" || config.type === "sse" ? config.url : undefined);
+				// `authorizationUrl` only lives on the embedded credential form;
+				// legacy `MCPAuthConfig` rows never carried it. Required to filter
+				// same-origin resource indicators on refresh when the authorize and
+				// token endpoints sit on different origins (issue #3502 review
+				// follow-up).
+				const authorizationUrl = material && "authorizationUrl" in material ? material.authorizationUrl : undefined;
+				const resourceIsFallback =
+					!material?.resource && (config.type === "http" || config.type === "sse") && Boolean(config.url);
+				const resource = material?.resource ?? (resourceIsFallback ? config.url : undefined);
 				// Proactive refresh: 5-minute buffer before expiry
 				// Force refresh: on 401/403 auth errors (revoked tokens, clock skew, missing expires)
 				const REFRESH_BUFFER_MS = 5 * 60_000;
@@ -1244,6 +1251,7 @@ export class MCPManager {
 							clientId,
 							clientSecret,
 							resource,
+							{ authorizationUrl, stripSameOriginResource: resourceIsFallback },
 						);
 						// Spread the old credential first so embedded refresh material survives rotation.
 						const refreshedCredential: MCPStoredOAuthCredential = {
@@ -1252,7 +1260,8 @@ export class MCPManager {
 							tokenUrl,
 							clientId,
 							clientSecret,
-							resource,
+							resource: resourceIsFallback ? undefined : resource,
+							authorizationUrl,
 						};
 						await this.#authStorage.set(credentialId, refreshedCredential);
 						credential = refreshedCredential;

package/src/mcp/oauth-flow.ts

@@ -62,6 +62,14 @@ export interface MCPStoredOAuthCredential extends OAuthCredential {
 	clientId?: string;
 	clientSecret?: string;
 	resource?: string;
+	/**
+	 * Authorization-server URL (the issuer the grant was minted against). Used
+	 * to filter same-origin resource indicators on refresh: RFC 8414 lets the
+	 * authorize and token endpoints sit on different origins, so refresh
+	 * cannot infer the original auth-server origin from `tokenUrl` alone.
+	 * Unset on legacy credentials minted before issue #3502's fix.
+	 */
+	authorizationUrl?: string;
 }
 
 const DEFAULT_PORT = 3000;
@@ -169,6 +177,42 @@ function resolveResourceUri(resource: string | undefined): string | undefined {
 	return trimmed;
 }
 
+interface ResourceIndicatorFilterOptions {
+	/** Strip any resource URL on the same origin as the authorization server. */
+	stripSameOriginResource?: boolean;
+}
+
+/**
+ * Drop a redundant fallback resource indicator relative to {@link serverUrl}.
+ *
+ * Provider-advertised resource indicators are authoritative even when they are
+ * origin-only (`https://gateway.example.com`) or path-scoped same-origin
+ * (`https://gateway.example.com/my-service/mcp`): servers can use either form
+ * as the audience they require for the grant.
+ *
+ * Plane is stricter for OMP-synthesized fallback resources (e.g. using the
+ * configured server URL `https://mcp.plane.so/http/mcp` as `resource`), so
+ * fallback callers opt into `stripSameOriginResource`. Provider-advertised
+ * `oauth.resource` values and authorization-URL `?resource=` values keep the
+ * preserving default.
+ */
+function filterResourceIndicator(
+	resource: string | undefined,
+	serverUrl: string,
+	options: ResourceIndicatorFilterOptions = {},
+): string | undefined {
+	if (!resource) return undefined;
+	try {
+		const origin = new URL(serverUrl).origin;
+		const parsedResource = new URL(resource);
+		if (parsedResource.origin !== origin) return resource;
+		if (options.stripSameOriginResource) return undefined;
+	} catch {
+		// Malformed serverUrl will fail elsewhere; fall through.
+	}
+	return resource;
+}
+
 export interface MCPOAuthConfig {
 	/** Authorization endpoint URL */
 	authorizationUrl: string;
@@ -197,6 +241,13 @@ export interface MCPOAuthConfig {
 	callbackPath?: string;
 	/** MCP resource URI for RFC 8707 resource indicators */
 	resource?: string;
+	/**
+	 * True when `resource` was synthesized from the server URL fallback rather
+	 * than advertised by OAuth/protected-resource metadata. Fallback resources
+	 * are stripped when same-origin with the authorization server; advertised
+	 * path-scoped resources are preserved.
+	 */
+	stripSameOriginResource?: boolean;
 	/** Fetch implementation for token exchange and discovery requests. */
 	fetch?: FetchImpl;
 }
@@ -219,8 +270,8 @@ export class MCPOAuthFlow extends OAuthCallbackFlow {
 		super(ctrl, resolveCallbackOptions(config));
 		this.#resolvedClientId = this.#resolveClientId(config);
 		this.#fetch = config.fetch ?? ctrl.fetch ?? fetch;
-		this.#resource = resolveResourceUri(
-			config.resource ?? this.#resourceFromAuthorizationUrl(config.authorizationUrl),
+		this.#resource = this.#filterResourceIndicator(
+			resolveResourceUri(config.resource ?? this.#resourceFromAuthorizationUrl(config.authorizationUrl)),
 		);
 	}
 
@@ -246,6 +297,15 @@ export class MCPOAuthFlow extends OAuthCallbackFlow {
 	get resource(): string | undefined {
 		return this.#resource;
 	}
+	/**
+	 * Authorization-server URL the flow used. Persist alongside the credential
+	 * so refresh can filter same-origin resource indicators against the issuer's
+	 * origin even when `tokenUrl` lives on a different origin (RFC 8414 permits
+	 * the split).
+	 */
+	get authorizationUrl(): string {
+		return this.config.authorizationUrl;
+	}
 
 	async generateAuthUrl(state: string, redirectUri: string): Promise<{ url: string; instructions?: string }> {
 		if (!this.#resolvedClientId) {
@@ -271,7 +331,20 @@ export class MCPOAuthFlow extends OAuthCallbackFlow {
 		}
 		const existingResource = params.get("resource")?.trim();
 		if (existingResource) {
-			this.#resource = resolveResourceUri(existingResource);
+			// A resource already embedded in the provider's authorization URL is
+			// provider-authored, not OMP's server-URL fallback. Preserve same-host
+			// values here even when the caller marked its separate
+			// `config.resource` as fallback; gateway-hosted MCP servers can use
+			// origin-only or path-scoped values as the token audience.
+			const filtered = filterResourceIndicator(resolveResourceUri(existingResource), this.config.authorizationUrl);
+			if (filtered) {
+				this.#resource = filtered;
+			} else {
+				// Defensive path for future policy additions: when filtering says
+				// "omit", drop it from both authorize and token requests.
+				params.delete("resource");
+				this.#resource = undefined;
+			}
 		} else if (this.#resource) {
 			params.set("resource", this.#resource);
 		}
@@ -395,6 +468,17 @@ export class MCPOAuthFlow extends OAuthCallbackFlow {
 		}
 	}
 
+	/**
+	 * Drop redundant resource indicators for this authorization server.
+	 * Provider-advertised path-scoped values are preserved; fallback server-URL
+	 * values opt into same-origin stripping via `stripSameOriginResource`.
+	 */
+	#filterResourceIndicator(resource: string | undefined): string | undefined {
+		return filterResourceIndicator(resource, this.config.authorizationUrl, {
+			stripSameOriginResource: this.config.stripSameOriginResource,
+		});
+	}
+
 	/**
 	 * Try OAuth dynamic client registration when provider requires a client_id.
 	 */
@@ -507,6 +591,26 @@ export class MCPOAuthFlow extends OAuthCallbackFlow {
 	}
 }
 
+/**
+ * Options for {@link refreshMCPOAuthToken}. Carried via the trailing object
+ * so positional callers keep working.
+ */
+export interface RefreshMCPOAuthTokenOptions {
+	fetch?: FetchImpl;
+	/**
+	 * Authorization-server URL the original grant was minted against. Used to
+	 * filter same-origin resource indicators on refresh. Defaults to `tokenUrl`'s
+	 * origin when omitted for legacy credentials.
+	 */
+	authorizationUrl?: string;
+	/**
+	 * True when the refresh `resource` was synthesized from the server URL
+	 * fallback because the credential/auth material carried no resource.
+	 * Preserved advertised resources leave this false/undefined.
+	 */
+	stripSameOriginResource?: boolean;
+}
+
 /**
  * Refresh an MCP OAuth token using the standard refresh_token grant.
  * Returns updated credentials; preserves the old refresh token if the server doesn't rotate it.
@@ -516,17 +620,27 @@ export async function refreshMCPOAuthToken(
 	refreshToken: string,
 	clientId?: string,
 	clientSecret?: string,
-	resourceOrOpts?: string | { fetch?: FetchImpl },
-	opts?: { fetch?: FetchImpl },
+	resourceOrOpts?: string | RefreshMCPOAuthTokenOptions,
+	opts?: RefreshMCPOAuthTokenOptions,
 ): Promise<OAuthCredentials> {
-	const fetchImpl: FetchImpl = (typeof resourceOrOpts === "string" ? opts?.fetch : resourceOrOpts?.fetch) ?? fetch;
+	const optsFromTrailing = typeof resourceOrOpts === "string" ? opts : resourceOrOpts;
+	const fetchImpl: FetchImpl = optsFromTrailing?.fetch ?? fetch;
 	const resource = typeof resourceOrOpts === "string" ? resourceOrOpts : undefined;
+	// Filter against the authorization-server origin when known (RFC 8414
+	// permits authorize/token endpoints on separate origins). Fall back to
+	// `tokenUrl` for legacy credentials minted before the issuer was persisted
+	// — same-origin servers (the common case) still match correctly.
+	const filterAnchor = optsFromTrailing?.authorizationUrl ?? tokenUrl;
 	const params = new URLSearchParams({
 		grant_type: "refresh_token",
 		refresh_token: refreshToken,
 	});
 	if (clientId) params.set("client_id", clientId);
-	const resolvedResource = resolveResourceUri(resource);
+	// Drop redundant indicators so refresh stays consistent with the initial
+	// grant; see {@link filterResourceIndicator} for context.
+	const resolvedResource = filterResourceIndicator(resolveResourceUri(resource), filterAnchor, {
+		stripSameOriginResource: optsFromTrailing?.stripSameOriginResource,
+	});
 	if (resolvedResource) params.set("resource", resolvedResource);
 	if (clientSecret) params.set("client_secret", clientSecret);
 

package/src/mcp/transports/stdio.ts

@@ -340,6 +340,10 @@ export class StdioTransport implements MCPTransport {
 			platform: process.platform,
 		});
 
+		// Spawn in a new session (detached → setsid) so the MCP process tree has
+		// no controlling terminal. Otherwise terminal job-control signals (Ctrl+Z
+		// SIGTSTP, background-read SIGTTIN) can stop stdio servers such as
+		// chrome-devtools-mcp and leave our read loop blocked on silent pipes.
 		this.#process = spawn({
 			cmd: spawnCommand.cmd,
 			cwd,
@@ -348,6 +352,7 @@ export class StdioTransport implements MCPTransport {
 			stdout: "pipe",
 			stderr: "pipe",
 			windowsHide: spawnCommand.windowsHide,
+			detached: true,
 		});
 
 		this.#connected = true;

package/src/modes/components/chat-transcript-builder.ts

@@ -83,6 +83,7 @@ export class ChatTranscriptBuilder {
 	#pendingUsage: Usage | undefined;
 	#lastAssistantUsage: Usage | undefined;
 	#waitingPoll: ToolExecutionComponent | null = null;
+	#todoSnapshot: ToolExecutionComponent | null = null;
 	#expandables: Array<{ setExpanded(expanded: boolean): void }> = [];
 	#expanded = false;
 
@@ -128,6 +129,7 @@ export class ChatTranscriptBuilder {
 		this.#pendingUsage = undefined;
 		this.#lastAssistantUsage = undefined;
 		this.#waitingPoll = null;
+		this.#todoSnapshot = null;
 		this.#expandables = [];
 		this.container.dispose();
 		this.container.clear();
@@ -153,6 +155,24 @@ export class ChatTranscriptBuilder {
 		previous.seal();
 	}
 
+	#resolveTodoSnapshot(nextToolName?: string): void {
+		const previous = this.#todoSnapshot;
+		if (!previous) return;
+		if (!previous.isDisplaceableBlock()) {
+			this.#todoSnapshot = null;
+			return;
+		}
+		if (previous.canBeDisplacedBy(nextToolName)) {
+			this.#todoSnapshot = null;
+			this.container.removeChild(previous);
+			previous.seal();
+			return;
+		}
+		if (nextToolName !== undefined) return;
+		this.#todoSnapshot = null;
+		previous.seal();
+	}
+
 	#ensureReadGroup(): ReadToolGroupComponent {
 		if (!this.#readGroup) {
 			this.#readGroup = new ReadToolGroupComponent({
@@ -189,6 +209,7 @@ export class ChatTranscriptBuilder {
 			case "developer": {
 				// A user prompt closes the poll-displacement window, same as the live path.
 				if (message.role === "user") this.#resolveWaitingPoll();
+				if (message.role === "user") this.#resolveTodoSnapshot();
 				const textContent = message.role === "user" ? userMessageText(message) : "";
 				if (textContent) {
 					const isSynthetic = message.role === "developer" ? true : (message.synthetic ?? false);
@@ -345,6 +366,16 @@ export class ChatTranscriptBuilder {
 		this.#pendingTools.delete(message.toolCallId);
 		if (message.toolName === "job" && pending instanceof ToolExecutionComponent && pending.isDisplaceableBlock()) {
 			this.#waitingPoll = pending;
+		} else if (
+			message.toolName === "todo" &&
+			pending instanceof ToolExecutionComponent &&
+			pending.canBeDisplacedBy("todo")
+		) {
+			// A successful todo result supersedes the prior live snapshot. Failed
+			// follow-ups return false from canBeDisplacedBy("todo"), so the
+			// last-good panel stays on screen.
+			this.#resolveTodoSnapshot("todo");
+			this.#todoSnapshot = pending;
 		}
 	}
 

package/src/modes/components/custom-editor.test.ts

@@ -5,6 +5,8 @@ import {
 	CustomEditor,
 	extractBracketedImagePastePaths,
 	extractBracketedPastePaths,
+	extractImagePathFromText,
+	extractPastePathsFromText,
 	SPACE_HOLD_MECHANICAL_RUN,
 	SPACE_HOLD_RELEASE_MS,
 	SPACE_REPEAT_MAX_GAP_MS,
@@ -88,6 +90,22 @@ describe("CustomEditor bracketed path paste", () => {
 		]);
 	});
 
+	it("strips `file://` URLs to the local filesystem path before loading the image", () => {
+		// macOS / Ghostty / iTerm2 sometimes forward the pasteboard's
+		// `public.file-url` representation when the user does Finder→Copy
+		// then Cmd+V. Without decoding, `loadImageInput` would try to read a
+		// literal `file:///…` path and fail.
+		expect(extractBracketedImagePastePaths(bracketedPaste("file:///Users/me/Pictures/photo.png"))).toEqual([
+			"/Users/me/Pictures/photo.png",
+		]);
+	});
+
+	it("percent-decodes spaces inside `file://` URLs", () => {
+		expect(extractBracketedImagePastePaths(bracketedPaste("file:///Users/me/My%20Pictures/photo.png"))).toEqual([
+			"/Users/me/My Pictures/photo.png",
+		]);
+	});
+
 	it("extracts explicit non-image paths without classifying them as image paths", () => {
 		expect(extractBracketedPastePaths(bracketedPaste("/tmp/report.csv"))).toEqual(["/tmp/report.csv"]);
 		expect(extractBracketedImagePastePaths(bracketedPaste("/tmp/report.csv"))).toBeUndefined();
@@ -107,6 +125,68 @@ describe("CustomEditor bracketed path paste", () => {
 	});
 });
 
+describe("extractImagePathFromText (issue #3506)", () => {
+	it("returns the path when the text is a single image file path", () => {
+		expect(extractImagePathFromText("/tmp/screenshot.png")).toBe("/tmp/screenshot.png");
+		expect(extractImagePathFromText("/Users/me/Pictures/photo.jpeg")).toBe("/Users/me/Pictures/photo.jpeg");
+		expect(extractImagePathFromText("C:\\Users\\me\\img.gif")).toBe("C:\\Users\\me\\img.gif");
+	});
+
+	it("ignores surrounding whitespace from a clipboard read", () => {
+		expect(extractImagePathFromText("  /tmp/photo.webp\n")).toBe("/tmp/photo.webp");
+	});
+
+	it("returns undefined for a bare filename (no explicit directory)", () => {
+		// Mirrors the bracketed-paste contract: a bare `.png` filename is
+		// almost always a project-relative reference the user wants as text,
+		// not a clipboard-anchored attachment.
+		expect(extractImagePathFromText("icon.png")).toBeUndefined();
+	});
+
+	it("returns undefined for non-image extensions", () => {
+		expect(extractImagePathFromText("/tmp/report.csv")).toBeUndefined();
+		expect(extractImagePathFromText("/tmp/notes.txt")).toBeUndefined();
+	});
+
+	it("returns undefined when the text contains anything beyond a single path", () => {
+		expect(extractImagePathFromText("see /tmp/screenshot.png")).toBeUndefined();
+		expect(extractImagePathFromText("/tmp/a.png /tmp/b.png")).toBeUndefined();
+	});
+
+	it("returns undefined for empty/whitespace-only input", () => {
+		expect(extractImagePathFromText("")).toBeUndefined();
+		expect(extractImagePathFromText("   ")).toBeUndefined();
+	});
+
+	it("decodes a `file://` URL to its filesystem path", () => {
+		expect(extractImagePathFromText("file:///Users/me/Pictures/photo.png")).toBe("/Users/me/Pictures/photo.png");
+	});
+
+	it("recovers a single anchored image path containing unescaped spaces (macOS screenshot name)", () => {
+		const macScreenshot = "/Users/me/Desktop/Screenshot 2026-06-25 at 1.23.45 PM.png";
+		expect(extractImagePathFromText(macScreenshot)).toBe(macScreenshot);
+		expect(extractImagePathFromText("~/Pictures/Cleanshot 2026-06-25 at 12.00.png")).toBe(
+			"~/Pictures/Cleanshot 2026-06-25 at 12.00.png",
+		);
+		expect(extractImagePathFromText("C:\\Users\\me\\My Pictures\\img with space.jpg")).toBe(
+			"C:\\Users\\me\\My Pictures\\img with space.jpg",
+		);
+	});
+
+	it("does not hijack prose that happens to contain a path-shaped fragment", () => {
+		// The whole-text branch is gated on ABSOLUTE_PATH_PREFIX_REGEX, so a
+		// non-anchored prefix ("see ...") never triggers it.
+		expect(extractImagePathFromText("see /Users/me/Desktop/Screenshot 1.png")).toBeUndefined();
+	});
+});
+
+describe("extractPastePathsFromText", () => {
+	it("delegates to the same logic the bracketed variant uses for path detection", () => {
+		expect(extractPastePathsFromText("/tmp/a.png /tmp/b.png")).toEqual(["/tmp/a.png", "/tmp/b.png"]);
+		expect(extractPastePathsFromText("just text")).toBeUndefined();
+	});
+});
+
 describe("CustomEditor space-hold push-to-talk", () => {
 	beforeAll(async () => {
 		await initTheme();

package/src/modes/components/custom-editor.ts

@@ -1,3 +1,4 @@
+import { fileURLToPath } from "node:url";
 import type { ImageContent } from "@oh-my-pi/pi-ai";
 import { addKeyAliases, canonicalKeyId, Editor, type KeyId, parseKey, parseKittySequence } from "@oh-my-pi/pi-tui";
 import type { AppKeybinding } from "../../config/keybindings";
@@ -66,6 +67,14 @@ const SHELL_ESCAPED_PATH_CHAR_REGEX = /\\([\\\s'"()[\]{}&;<>|?*!$`])/g;
 const URI_SCHEME_REGEX = /^[a-z][a-z0-9+.-]*:/i;
 const FILE_URI_REGEX = /^file:\/\//i;
 const WINDOWS_DRIVE_PATH_REGEX = /^[a-z]:[\\/]/i;
+/**
+ * Whole-string anchor for paths that are unambiguously absolute. Restricts the
+ * "treat the entire clipboard text as one path" branch of
+ * {@link extractImagePathFromText} to inputs that start with a clearly-anchored
+ * filesystem prefix, so prose containing a path-shaped fragment (e.g.
+ * "see /tmp/x.png") never hijacks the smart fallback.
+ */
+const ABSOLUTE_PATH_PREFIX_REGEX = /^(?:\/|~\/|file:\/\/|\\\\|[A-Za-z]:[\\/])/;
 
 /** Max gap (ms) between two spaces for the later one to count as OS key auto-repeat rather than a
  *  deliberate press. OS auto-repeat is fast; a deliberate tap (even a fast one) is slower. */
@@ -105,6 +114,20 @@ function normalizePastedPath(path: string): string {
 	const last = trimmed[trimmed.length - 1];
 	const unquoted =
 		trimmed.length > 1 && (first === '"' || first === "'") && last === first ? trimmed.slice(1, -1) : trimmed;
+	// `file://` URL → local filesystem path. Mirrors Codex's
+	// `normalize_pasted_path` (codex-rs/tui/src/clipboard_paste.rs) so a
+	// pasteboard whose text representation is a `file:///Users/…/img.png`
+	// URL — common when terminals forward the macOS pasteboard's
+	// `public.file-url` representation — loads as the file itself rather
+	// than failing in `loadImageInput` with a literal-`file://` path.
+	if (FILE_URI_REGEX.test(unquoted)) {
+		try {
+			return fileURLToPath(unquoted);
+		} catch {
+			// Malformed file URL: drop through to the shell-unescape branch
+			// so the caller can still reject it as a non-explicit path.
+		}
+	}
 	return unquoted.replace(SHELL_ESCAPED_PATH_CHAR_REGEX, "$1");
 }
 
@@ -161,12 +184,15 @@ function splitPastedPathSegments(payload: string): string[] | undefined {
 	return segments.length > 0 ? segments : undefined;
 }
 
-export function extractBracketedPastePaths(data: string): string[] | undefined {
-	if (!data.startsWith(BRACKETED_PASTE_START)) return undefined;
-	const endIndex = data.indexOf(BRACKETED_PASTE_END, BRACKETED_PASTE_START.length);
-	if (endIndex === -1 || endIndex + BRACKETED_PASTE_END.length !== data.length) return undefined;
-
-	const pasted = data.slice(BRACKETED_PASTE_START.length, endIndex).trim();
+/**
+ * Extract whitespace/quoted-separated path-like segments from `payload`.
+ * Shared backend of {@link extractBracketedPastePaths} and {@link extractPastePathsFromText}.
+ * Returns the segments only when EVERY segment looks like an explicit path
+ * (`/`, `\`, drive letter, or `file://`); otherwise undefined so the caller
+ * falls back to a plain text paste.
+ */
+function extractExplicitPathSegments(payload: string): string[] | undefined {
+	const pasted = payload.trim();
 	if (!pasted) return undefined;
 
 	const segments = splitPastedPathSegments(pasted);
@@ -181,6 +207,23 @@ export function extractBracketedPastePaths(data: string): string[] | undefined {
 	return paths;
 }
 
+/**
+ * Extract image-or-other file paths from plain (un-bracketed) clipboard text.
+ * Mirrors {@link extractBracketedPastePaths} for terminals/handlers that
+ * already stripped the `\x1b[200~`…`\x1b[201~` markers (e.g. clipboard text
+ * read directly via `pbpaste`/PowerShell).
+ */
+export function extractPastePathsFromText(text: string): string[] | undefined {
+	return extractExplicitPathSegments(text);
+}
+
+export function extractBracketedPastePaths(data: string): string[] | undefined {
+	if (!data.startsWith(BRACKETED_PASTE_START)) return undefined;
+	const endIndex = data.indexOf(BRACKETED_PASTE_END, BRACKETED_PASTE_START.length);
+	if (endIndex === -1 || endIndex + BRACKETED_PASTE_END.length !== data.length) return undefined;
+	return extractExplicitPathSegments(data.slice(BRACKETED_PASTE_START.length, endIndex));
+}
+
 export function extractBracketedImagePastePaths(data: string): string[] | undefined {
 	const paths = extractBracketedPastePaths(data);
 	return paths?.every(isImagePath) ? paths : undefined;
@@ -191,6 +234,43 @@ export function extractBracketedImagePastePath(data: string): string | undefined
 	return paths?.length === 1 ? paths[0] : undefined;
 }
 
+/**
+ * Return a single image file path when `text` is exactly one explicit path
+ * pointing at a supported image extension (`.png`, `.jpg`/`.jpeg`, `.gif`,
+ * `.webp`). Used by the keybind-driven clipboard image paste path so a
+ * clipboard whose only payload is an image file (e.g. Finder `Cmd+C` on
+ * macOS) attaches the image instead of pasting the path as literal text.
+ *
+ * Two-stage detection:
+ *
+ * 1. Splitter pass (shared with the bracketed-paste handler) — handles
+ *    quoted paths, shell-escaped spaces, and unambiguous single tokens.
+ *    Returns the single image path when it parses cleanly; explicitly
+ *    returns `undefined` when the splitter found multiple segments (so
+ *    ambiguous multi-path clipboard text like `/tmp/a.png /tmp/b.png`
+ *    still falls through to the text fallback instead of being mis-loaded
+ *    as one giant path).
+ * 2. Whole-text-as-path pass — only reached when the splitter failed
+ *    (every segment must look like an explicit path; an unescaped space in
+ *    a real path breaks that). Restricted to inputs anchored by
+ *    {@link ABSOLUTE_PATH_PREFIX_REGEX} so prose containing a path-shaped
+ *    fragment ("see /tmp/x.png") never hijacks the smart fallback. This
+ *    is what recovers macOS screenshot filenames like
+ *    `/Users/me/Desktop/Screenshot 2026-06-25 at 1.23.45 PM.png`.
+ */
+export function extractImagePathFromText(text: string): string | undefined {
+	const paths = extractPastePathsFromText(text);
+	if (paths?.length === 1 && isImagePath(paths[0])) return paths[0];
+	if (paths !== undefined) return undefined;
+	const trimmed = text.trim();
+	if (!trimmed || /[\r\n]/.test(trimmed) || !ABSOLUTE_PATH_PREFIX_REGEX.test(trimmed)) return undefined;
+	const wholePath = normalizePastedPath(trimmed);
+	if (wholePath && isExplicitPastedPath(wholePath) && isImagePath(wholePath)) {
+		return wholePath;
+	}
+	return undefined;
+}
+
 /**
  * Custom editor that handles configurable app-level shortcuts for coding-agent.
  */