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

package/src/extensibility/plugins/legacy-pi-compat.ts

@@ -1,4 +1,5 @@
 import * as fs from "node:fs";
+import { isBuiltin } from "node:module";
 import * as path from "node:path";
 import * as url from "node:url";
 import { isCompiledBinary } from "@oh-my-pi/pi-utils";
@@ -456,10 +457,11 @@ const TYPEBOX_IMPORT_SPECIFIER_REGEX = /((?:from\s+|import\s+|import\s*\(\s*)["'
 
 /**
  * Rewrite the extension-owned specifiers OMP must host-resolve — legacy
- * `@(scope)/pi-*`, bare TypeBox packages, and package `imports` aliases like
- * `#src/*` — to absolute `file://` URLs. Every other specifier (relative
- * siblings and third-party dependencies) is left untouched so Bun resolves it
- * natively from the extension's real on-disk location.
+ * `@(scope)/pi-*`, bare TypeBox packages, package `imports` aliases like
+ * `#src/*`, and extension-local bare dependencies — to absolute `file://` URLs
+ * or compiled-mode virtual specifiers. Relative siblings and built-in modules
+ * are left untouched so Bun resolves them from the extension's real on-disk
+ * location.
  */
 async function rewriteLegacyExtensionSource(source: string, importerPath: string): Promise<string> {
 	const withPi = rewriteLegacyPiImports(source);
@@ -474,7 +476,12 @@ async function rewriteLegacyExtensionSource(source: string, importerPath: string
 					`${prefix}${toImportSpecifier(TYPEBOX_SHIM_PATH)}${suffix}`,
 			)
 		: withPi;
-	return rewriteExtensionPackageImports(withTypeBox, importerPath);
+	return rewriteExtensionBareImports(await rewriteExtensionPackageImports(withTypeBox, importerPath), importerPath);
+}
+
+/** Test seam for compiled-binary legacy extension source rewriting. */
+export async function __rewriteLegacyExtensionSourceForTests(source: string, importerPath: string): Promise<string> {
+	return rewriteLegacyExtensionSource(source, importerPath);
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -688,6 +695,187 @@ async function rewriteExtensionPackageImports(source: string, importerPath: stri
 	return `${rewritten}${source.slice(lastIndex)}`;
 }
 
+const BARE_EXTENSION_IMPORT_SPECIFIER_REGEX = /((?:from\s+|import\s+|import\s*\(\s*)["'])([^"'()\s]+)(["'])/g;
+
+function isBareExtensionDependencySpecifier(specifier: string): boolean {
+	if (
+		specifier.startsWith(".") ||
+		specifier.startsWith("/") ||
+		specifier.startsWith("#") ||
+		specifier.startsWith("node:") ||
+		specifier.startsWith("bun:") ||
+		/^[a-z][a-z0-9+.-]*:/i.test(specifier)
+	) {
+		return false;
+	}
+	const packageName = specifier.startsWith("@") ? specifier.split("/").slice(0, 2).join("/") : specifier.split("/")[0];
+	return Boolean(packageName && !isBuiltin(packageName));
+}
+
+interface BarePackageSpecifier {
+	readonly name: string;
+	readonly subpath: string | null;
+}
+
+function splitBarePackageSpecifier(specifier: string): BarePackageSpecifier | null {
+	const parts = specifier.split("/");
+	if (specifier.startsWith("@")) {
+		const [scope, name, ...rest] = parts;
+		if (!scope || !name) return null;
+		return { name: `${scope}/${name}`, subpath: rest.length > 0 ? rest.join("/") : null };
+	}
+	const [name, ...rest] = parts;
+	if (!name) return null;
+	return { name, subpath: rest.length > 0 ? rest.join("/") : null };
+}
+
+async function findNodePackageRoot(packageName: string, importerPath: string): Promise<string | null> {
+	let dir = path.dirname(importerPath);
+	while (true) {
+		const candidate = path.join(dir, "node_modules", packageName);
+		if (await pathExists(path.join(candidate, "package.json"))) {
+			return candidate;
+		}
+		const parent = path.dirname(dir);
+		if (parent === dir) {
+			return null;
+		}
+		dir = parent;
+	}
+}
+
+async function readPackageManifest(packageRoot: string): Promise<Record<string, unknown> | null> {
+	try {
+		const manifest = await Bun.file(path.join(packageRoot, "package.json")).json();
+		return isRecord(manifest) ? manifest : null;
+	} catch {
+		return null;
+	}
+}
+
+async function resolvePackageExportTarget(
+	packageRoot: string,
+	target: string,
+	wildcard: string | null,
+): Promise<string | null> {
+	if (!target.startsWith("./")) {
+		return null;
+	}
+	const substituted = wildcard === null ? target : target.replaceAll("*", wildcard);
+	return resolveSourceModuleFile(path.resolve(packageRoot, substituted));
+}
+
+async function resolveNodePackageExport(
+	packageRoot: string,
+	subpath: string | null,
+	manifest: Record<string, unknown>,
+): Promise<string | null> {
+	const exportsField = manifest.exports;
+	const rootTarget = subpath === null ? selectPackageImportTarget(exportsField) : null;
+	if (rootTarget !== null && rootTarget !== PACKAGE_IMPORT_EXCLUDED) {
+		return resolvePackageExportTarget(packageRoot, rootTarget, null);
+	}
+	if (!isRecord(exportsField)) {
+		return null;
+	}
+
+	const exactKey = subpath === null ? "." : `./${subpath}`;
+	const exactTarget = selectPackageImportTarget(exportsField[exactKey]);
+	if (exactTarget !== null && exactTarget !== PACKAGE_IMPORT_EXCLUDED) {
+		return resolvePackageExportTarget(packageRoot, exactTarget, null);
+	}
+
+	for (const [key, entry] of Object.entries(exportsField)) {
+		const starIndex = key.indexOf("*");
+		if (starIndex === -1 || subpath === null) continue;
+		const prefix = key.slice(2, starIndex);
+		const suffix = key.slice(starIndex + 1);
+		if (!subpath.startsWith(prefix) || !subpath.endsWith(suffix)) {
+			continue;
+		}
+		const target = selectPackageImportTarget(entry);
+		if (target === null || target === PACKAGE_IMPORT_EXCLUDED) {
+			continue;
+		}
+		return resolvePackageExportTarget(
+			packageRoot,
+			target,
+			subpath.slice(prefix.length, subpath.length - suffix.length),
+		);
+	}
+	return null;
+}
+
+async function resolveNodePackageFallback(
+	packageRoot: string,
+	subpath: string | null,
+	manifest: Record<string, unknown>,
+): Promise<string | null> {
+	if (subpath !== null) {
+		return resolveSourceModuleFile(path.join(packageRoot, subpath));
+	}
+	for (const field of ["module", "main"]) {
+		const target = manifest[field];
+		if (typeof target === "string") {
+			const resolved = await resolveSourceModuleFile(path.resolve(packageRoot, target));
+			if (resolved) return resolved;
+		}
+	}
+	return resolveSourceModuleFile(path.join(packageRoot, "index"));
+}
+
+async function resolveNodePackageDependency(specifier: string, importerPath: string): Promise<string | null> {
+	const parsed = splitBarePackageSpecifier(specifier);
+	if (!parsed) return null;
+	const packageRoot = await findNodePackageRoot(parsed.name, importerPath);
+	if (!packageRoot) return null;
+	const manifest = await readPackageManifest(packageRoot);
+	if (!manifest) return null;
+	return (
+		(await resolveNodePackageExport(packageRoot, parsed.subpath, manifest)) ??
+		(await resolveNodePackageFallback(packageRoot, parsed.subpath, manifest))
+	);
+}
+
+async function resolveExtensionBareDependency(specifier: string, importerPath: string): Promise<string | null> {
+	if (!isBareExtensionDependencySpecifier(specifier)) {
+		return null;
+	}
+	try {
+		const resolved = Bun.resolveSync(specifier, path.dirname(importerPath));
+		if (resolved && resolved !== specifier && !resolved.startsWith("node:") && !resolved.startsWith("bun:")) {
+			return resolved;
+		}
+	} catch {
+		// Compiled binaries do not reliably resolve runtime extension node_modules.
+	}
+	return resolveNodePackageDependency(specifier, importerPath);
+}
+
+async function rewriteExtensionBareImports(source: string, importerPath: string): Promise<string> {
+	let rewritten = "";
+	let lastIndex = 0;
+	for (const match of source.matchAll(BARE_EXTENSION_IMPORT_SPECIFIER_REGEX)) {
+		const matchIndex = match.index;
+		if (matchIndex === undefined) continue;
+
+		const [fullMatch, prefix, specifier, suffix] = match;
+		if (!prefix || !specifier || !suffix) continue;
+
+		const resolved = await resolveExtensionBareDependency(specifier, importerPath);
+		if (!resolved) continue;
+
+		rewritten += source.slice(lastIndex, matchIndex);
+		rewritten += `${prefix}${toImportSpecifier(resolved)}${suffix}`;
+		lastIndex = matchIndex + fullMatch.length;
+	}
+
+	if (lastIndex === 0) {
+		return source;
+	}
+	return `${rewritten}${source.slice(lastIndex)}`;
+}
+
 function escapeRegExp(value: string): string {
 	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }

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/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();