@oh-my-pi/pi-coding-agent 16.5.0 → 16.5.1

package/src/eval/js/context-manager.ts

@@ -1,6 +1,14 @@
-import { logger, Snowflake, workerHostEntry } from "@oh-my-pi/pi-utils";
+import { logger, postmortem, Snowflake, workerHostEntry } from "@oh-my-pi/pi-utils";
+import {
+	createWorkerHandle,
+	createWorkerSubprocess,
+	resolveWorkerSpawnCmd,
+	workerEnvFromParent,
+} from "../../subprocess/worker-client";
 import type { ToolSession } from "../../tools";
 import { ToolAbortError, ToolError } from "../../tools/tool-errors";
+import { safeSend as safeSendIpc } from "../../utils/ipc";
+import { shouldDetachKernel } from "../py/spawn-options";
 import { callSessionTool, type JsStatusEvent } from "./tool-bridge";
 import { WorkerCore } from "./worker-core";
 // Coding-agent binary/bundle workers route through the CLI entrypoint with a
@@ -24,7 +32,7 @@ export interface VmRunState {
 }
 
 interface WorkerHandle {
-	mode: "worker" | "inline";
+	mode: "process" | "worker" | "inline";
 	send(msg: WorkerInbound): void;
 	onMessage(handler: (msg: WorkerOutbound) => void): () => void;
 	onError(handler: (error: Error) => void): () => void;
@@ -57,16 +65,18 @@ const resettingSessions = new Map<string, Promise<void>>();
 // Worker startup (module-graph import + WorkerCore construction) is infrastructure
 // cost, not user compute. Floor it independently of Bun's 5s default per-test timeout
 // so a slow cold-start under load isn't aborted mid-init — terminating a still-
-// initializing Bun worker triggers the same kind of terminate-race that motivates
+// initializing eval runtime triggers the same kind of terminate-race that motivates
 // avoiding `vm.runInContext` (see shared/indirect-eval.ts), here surfacing as a
 // SIGILL/SIGSEGV. Callers that pass a larger per-cell budget still dominate.
 const WORKER_INIT_TIMEOUT_MS = 15_000;
 const WORKER_CLOSE_TIMEOUT_MS = 1_000;
+const JS_EVAL_PROCESS_ARG = "__omp_worker_js_eval_process";
 // Active graceful-close grace period before a worker that ack'd `close` but never
 // emitted its `close` event is force-terminated. Defaults to the production floor;
 // tests override it (and restore it) to exercise the close-timeout -> terminate
 // path without a real wall-clock wait.
 let workerCloseTimeoutMs: number = WORKER_CLOSE_TIMEOUT_MS;
+let useWorkerThreadForTests = false;
 
 /**
  * Test-only seam: override the graceful-close grace period (ms). Returns the
@@ -79,6 +89,13 @@ export function setWorkerCloseTimeoutMsForTests(ms: number): number {
 	return previous;
 }
 
+/** Test-only seam for the legacy Worker lifecycle mocks. */
+export function setJsEvalWorkerThreadForTests(enabled: boolean): boolean {
+	const previous = useWorkerThreadForTests;
+	useWorkerThreadForTests = enabled;
+	return previous;
+}
+
 export async function executeInVmContext(options: {
 	sessionKey: string;
 	sessionId: string;
@@ -144,9 +161,9 @@ export async function disposeAllVmContexts(): Promise<void> {
 }
 
 /**
- * Smoke probe: spawn the JS eval worker through the worker-host entry and prove
- * it answers the `init` handshake on a real worker thread (not the inline
- * fallback). Catches the silent worker-load and init-message-drop regressions
+ * Smoke probe: spawn the JS evaluator through the worker-host entry and prove
+ * it answers the `init` handshake in a real isolated subprocess (not the inline
+ * fallback). Catches silent process-load and init-message regressions
  * that otherwise strand every cell on the init timeout in a distribution build —
  * the failure mode that motivated `installWorkerInbox`. Wired into
  * `omp --smoke-test` so binary / source / tarball installs all exercise it.
@@ -163,8 +180,8 @@ export async function smokeTestJsEvalWorker(): Promise<void> {
 	};
 	try {
 		await initWorker(session, { cwd: process.cwd(), sessionId: "smoke" }, WORKER_INIT_TIMEOUT_MS);
-		if (worker.mode !== "worker") {
-			throw new Error("JS eval worker smoke fell back to the inline worker (real worker failed to start)");
+		if (worker.mode !== "process") {
+			throw new Error("JS eval worker smoke fell back from the isolated subprocess");
 		}
 	} finally {
 		await worker.terminate().catch(() => undefined);
@@ -237,10 +254,8 @@ async function acquireSession(sessionKey: string, snapshot: SessionSnapshot, tim
 	if (starting) return await starting;
 
 	const startup = (async (): Promise<JsSession> => {
-		// The message listener must be attached synchronously after `new Worker`:
-		// Bun drops messages posted before a listener exists, and WorkerCore emits
-		// `ready` from its constructor on load. `spawnJsWorker` + `initWorker` run with
-		// no intervening await, so `ready` can never race the attach.
+		// Attach the message listener before sending init. Both Bun Worker messages
+		// and subprocess IPC can arrive immediately after the evaluator loads.
 		const worker = spawnJsWorker();
 		const session: JsSession = {
 			sessionKey,
@@ -253,27 +268,29 @@ async function acquireSession(sessionKey: string, snapshot: SessionSnapshot, tim
 		// Init headroom is the fixed infrastructure floor; the caller's per-cell timeout
 		// dominates when larger so users can grant more by raising `timeout` on a cell.
 		const readyTimeoutMs = Math.max(WORKER_INIT_TIMEOUT_MS, timeoutMs ?? 0);
-		try {
-			await initWorker(session, snapshot, readyTimeoutMs);
-		} catch (error) {
-			// Worker-thread crash/load failures surface asynchronously via the worker
-			// `error` event — after `spawnJsWorker`'s synchronous try/catch already
-			// returned — so the only signal is the rejected handshake. Retry on the
-			// inline worker so a broken module graph fails fast instead of stalling
-			// every cell on the init timeout and then dying with exitCode 1.
-			await worker.terminate().catch(() => undefined);
-			if (worker.mode === "inline") throw error;
-			logger.warn("JS eval worker init failed; retrying with inline worker (no sync-loop guard)", {
-				error: error instanceof Error ? error.message : String(error),
-			});
-			const inline = spawnInlineWorker();
-			session.worker = inline;
-			session.state = "alive";
+		while (true) {
 			try {
 				await initWorker(session, snapshot, readyTimeoutMs);
-			} catch (inlineError) {
-				await inline.terminate().catch(() => undefined);
-				throw inlineError;
+				break;
+			} catch (error) {
+				// Runtime crash/load failures surface asynchronously via the runtime's
+				// error callback, after the synchronous spawn try/catch has returned.
+				// Preserve the full process -> Worker -> inline ladder for those failures.
+				const failed = session.worker;
+				await failed.terminate().catch(() => undefined);
+				if (failed.mode === "inline") throw error;
+				if (failed.mode === "process") {
+					logger.warn("JS eval subprocess init failed; retrying with a Bun Worker", {
+						error: error instanceof Error ? error.message : String(error),
+					});
+					session.worker = spawnBunWorker();
+				} else {
+					logger.warn("JS eval worker init failed; retrying with inline worker (no sync-loop guard)", {
+						error: error instanceof Error ? error.message : String(error),
+					});
+					session.worker = spawnInlineWorker();
+				}
+				session.state = "alive";
 			}
 		}
 		sessions.set(sessionKey, session);
@@ -480,6 +497,22 @@ async function raceWithTimeout<T>(promise: Promise<T>, timeoutMs: number, reason
 }
 
 function spawnJsWorker(): WorkerHandle {
+	if (!useWorkerThreadForTests) {
+		try {
+			return spawnJsProcess();
+		} catch (err) {
+			// Fall through to the Bun Worker rung: a worker thread still interrupts
+			// synchronous infinite loops via terminate(), which the inline fallback
+			// cannot.
+			logger.warn("JS eval subprocess spawn failed; falling back to a Bun Worker", {
+				error: err instanceof Error ? err.message : String(err),
+			});
+		}
+	}
+	return spawnBunWorker();
+}
+
+function spawnBunWorker(): WorkerHandle {
 	try {
 		const hostEntry = workerHostEntry();
 		const worker = hostEntry
@@ -494,6 +527,47 @@ function spawnJsWorker(): WorkerHandle {
 	}
 }
 
+function spawnJsProcess(): WorkerHandle {
+	const spawned = createWorkerSubprocess<WorkerOutbound>({
+		spawnCommand: resolveWorkerSpawnCmd(JS_EVAL_PROCESS_ARG),
+		env: workerEnvFromParent(),
+		exitLabel: "JS eval worker",
+		detached: shouldDetachKernel(process.platform),
+		reportCleanExit: true,
+		unref: false,
+	});
+	const base = createWorkerHandle<WorkerInbound, WorkerOutbound>(spawned, message =>
+		safeSendIpc(spawned.proc, message, "js-eval"),
+	);
+	return {
+		mode: "process",
+		send: message => base.send(message),
+		onMessage: handler => base.onMessage(handler),
+		onError: handler => base.onError(handler),
+		async close() {
+			const { promise, resolve } = Promise.withResolvers<boolean>();
+			let settled = false;
+			let timeout: NodeJS.Timeout | undefined;
+			let unsubscribe = (): void => {};
+			const finish = (value: boolean): void => {
+				if (settled) return;
+				settled = true;
+				if (timeout) clearTimeout(timeout);
+				unsubscribe();
+				resolve(value);
+			};
+			unsubscribe = base.onMessage(message => {
+				if (message.type !== "closed") return;
+				void base.terminate().finally(() => finish(true));
+			});
+			timeout = setTimeout(() => finish(false), workerCloseTimeoutMs);
+			base.send({ type: "close" });
+			return await promise;
+		},
+		terminate: () => base.terminate(),
+	};
+}
+
 function wrapBunWorker(worker: Worker): WorkerHandle {
 	return {
 		mode: "worker",
@@ -582,7 +656,10 @@ function spawnInlineWorker(): WorkerHandle {
 		},
 		close: () => {},
 	};
-	const core = new WorkerCore(workerTransport);
+	const core = new WorkerCore(workerTransport, {
+		mode: "inline",
+		interceptUnhandledRejections: postmortem.interceptUnhandledRejections,
+	});
 	return {
 		mode: "inline",
 		send: msg =>

package/src/eval/js/process-entry.ts

@@ -0,0 +1,27 @@
+import { WorkerCore } from "./worker-core";
+import type { WorkerInbound, WorkerOutbound } from "./worker-protocol";
+
+/** Start the JavaScript evaluator inside a subprocess IPC transport. */
+export function startJsEvalProcess(transport: {
+	send(message: WorkerOutbound): void;
+	onMessage(handler: (message: WorkerInbound) => void): () => void;
+}): void {
+	new WorkerCore(
+		{
+			send: message => transport.send(message),
+			onMessage: handler => transport.onMessage(handler),
+			// The parent owns process lifetime and kills the subprocess after the
+			// WorkerCore `closed` acknowledgement has crossed IPC.
+			close: () => {},
+		},
+		{
+			mode: "isolated",
+			// The subprocess starts with its real cwd at the worker-host entry dir
+			// (a `resolveWorkerSpawnCmd` requirement); mirror the session cwd so
+			// cell code using relative paths or spawning children resolves against
+			// the project instead of the install dir. Worker threads cannot pass
+			// this — `process.chdir` is unavailable there.
+			chdir: cwd => process.chdir(cwd),
+		},
+	);
+}

package/src/eval/js/shared/runtime.ts

@@ -6,7 +6,7 @@ import * as path from "node:path";
 import { Writable } from "node:stream";
 import * as util from "node:util";
 
-import { logger } from "@oh-my-pi/pi-utils";
+import * as logger from "@oh-my-pi/pi-utils/logger";
 
 import { createHelpers, type HelperBundle } from "./helpers";
 import { awaitMaybePromise, indirectEval } from "./indirect-eval";

package/src/eval/js/worker-core.ts

@@ -1,5 +1,3 @@
-import { isMainThread } from "node:worker_threads";
-import { postmortem } from "@oh-my-pi/pi-utils";
 import { ToolError } from "../../tools/tool-errors";
 import { JsRuntime, type RuntimeHooks } from "./shared/runtime";
 import type {
@@ -27,6 +25,23 @@ interface ActiveRun {
 
 type RunResult = Extract<WorkerOutbound, { type: "result" }>;
 
+export type WorkerCoreOptions =
+	| {
+			mode: "isolated";
+			/**
+			 * Mirror the session cwd onto the real process cwd so cell code using
+			 * `process.cwd()`, relative paths, or child processes without an explicit
+			 * `cwd` resolves against the project. Only the dedicated subprocess may
+			 * pass this: `process.chdir` is unavailable in Worker threads and would
+			 * mutate the host's own cwd on the inline fallback.
+			 */
+			chdir?: (cwd: string) => void;
+	  }
+	| {
+			mode: "inline";
+			interceptUnhandledRejections(handler: (reason: unknown) => boolean): () => void;
+	  };
+
 /** Finished-cell filenames retained for attributing rejections that surface after the run settled. */
 const RECENT_CELL_FILES_MAX = 256;
 
@@ -82,9 +97,11 @@ export class WorkerCore {
 	#recentCellFiles = new Set<string>();
 	#unsubscribe: () => void;
 	#uninstallRejectionGuard: () => void;
+	#options: WorkerCoreOptions;
 
-	constructor(transport: Transport) {
+	constructor(transport: Transport, options: WorkerCoreOptions) {
 		this.#transport = transport;
+		this.#options = options;
 		this.#unsubscribe = transport.onMessage(msg => this.#handle(msg));
 		this.#uninstallRejectionGuard = this.#installRejectionGuard();
 	}
@@ -98,8 +115,8 @@ export class WorkerCore {
 	 * without a usable stack, while anything else keeps its default fatality.
 	 */
 	#installRejectionGuard(): () => void {
-		if (isMainThread) {
-			return postmortem.interceptUnhandledRejections(reason => this.#consumeRejection(reason));
+		if (this.#options.mode === "inline") {
+			return this.#options.interceptUnhandledRejections(reason => this.#consumeRejection(reason));
 		}
 		const onRejection = (reason: unknown): void => {
 			if (this.#consumeRejection(reason)) return;
@@ -161,7 +178,7 @@ export class WorkerCore {
 				return true;
 			}
 		}
-		if (!isMainThread && this.#runs.size > 0) {
+		if (this.#options.mode === "isolated" && this.#runs.size > 0) {
 			// Dedicated eval worker: during a live run, a rejection without a cell
 			// frame (e.g. `Promise.reject("msg")` or a library-created reason) is
 			// still cell activity — nothing else runs user code in this realm.
@@ -206,7 +223,8 @@ export class WorkerCore {
 		}
 	}
 
-	#ensureRuntime(snapshot: SessionSnapshot): JsRuntime {
+	#ensureRuntime(snapshot: SessionSnapshot, currentRunId?: string): JsRuntime {
+		this.#syncProcessCwd(snapshot.cwd, currentRunId);
 		if (this.#runtime) {
 			this.#runtime.setCwd(snapshot.cwd);
 			return this.#runtime;
@@ -219,6 +237,41 @@ export class WorkerCore {
 		return this.#runtime;
 	}
 
+	#syncProcessCwd(cwd: string, currentRunId?: string): void {
+		if (this.#options.mode !== "isolated" || !this.#options.chdir) return;
+		try {
+			if (process.cwd() === cwd) return;
+		} catch {
+			// The current cwd was deleted; the chdir below is the recovery.
+		}
+		// Process cwd is realm-wide state. Moving it while another cell is mid-run
+		// would silently redirect that cell's `process.cwd()`, relative fs access,
+		// and child spawns, so keep it in place; this run still resolves against
+		// its own virtual cwd, and the next cell to start alone lands the move.
+		for (const runId of this.#runs.keys()) {
+			if (runId === currentRunId) continue;
+			this.#transport.send({
+				type: "log",
+				level: "warn",
+				msg: "JS eval subprocess kept its process cwd: other cells are mid-run",
+				meta: { cwd },
+			});
+			return;
+		}
+		try {
+			this.#options.chdir(cwd);
+		} catch (error) {
+			// `process.chdir` throws when the session cwd no longer exists; keep
+			// the cell on the runtime's virtual cwd instead of failing the run.
+			this.#transport.send({
+				type: "log",
+				level: "warn",
+				msg: "JS eval subprocess could not enter the session cwd",
+				meta: { cwd, error: errorPayload(error) },
+			});
+		}
+	}
+
 	async #runOne(runId: string, code: string, filename: string, snapshot: SessionSnapshot): Promise<void> {
 		const active: ActiveRun = { runId, filename, pendingTools: new Map(), floatingRejections: [] };
 		this.#runs.set(runId, active);
@@ -229,7 +282,7 @@ export class WorkerCore {
 		};
 		let result: RunResult;
 		try {
-			const runtime = this.#ensureRuntime(snapshot);
+			const runtime = this.#ensureRuntime(snapshot, runId);
 			runtime.setCwd(snapshot.cwd);
 			const value = await runtime.run(code, filename, hooks, { runId, cwd: snapshot.cwd });
 			runtime.displayValue(value, hooks);
@@ -263,7 +316,15 @@ export class WorkerCore {
 		const id = `tc-${active.runId}-${crypto.randomUUID()}`;
 		const { promise, resolve, reject } = Promise.withResolvers<unknown>();
 		active.pendingTools.set(id, { runId: active.runId, resolve, reject });
-		this.#transport.send({ type: "tool-call", id, runId: active.runId, name, args });
+		try {
+			this.#transport.send({ type: "tool-call", id, runId: active.runId, name, args });
+		} catch (error) {
+			// Non-serializable args (DataCloneError from postMessage / IPC send).
+			// No reply will ever arrive; fail this call instead of stranding a
+			// pending entry until close.
+			active.pendingTools.delete(id);
+			reject(error);
+		}
 		return await promise;
 	}
 

package/src/eval/js/worker-entry.ts

@@ -34,4 +34,4 @@ const transport: Transport = {
 	},
 };
 
-new WorkerCore(transport);
+new WorkerCore(transport, { mode: "isolated" });

package/src/eval/py/kernel.ts

@@ -23,7 +23,7 @@ import {
 	resolveExplicitPythonRuntime,
 	resolvePythonRuntime,
 } from "./runtime";
-import { hostHasInheritableConsole, shouldHideKernelWindow } from "./spawn-options";
+import { hostHasInheritableConsole, shouldDetachKernel, shouldHideKernelWindow } from "./spawn-options";
 
 export type {
 	KernelExecuteOptions,
@@ -193,6 +193,7 @@ export class PythonKernel extends BaseKernel {
 
 		const proc = Bun.spawn([runtime.pythonPath, "-u", scriptPath], {
 			cwd: options.cwd,
+			detached: shouldDetachKernel(process.platform),
 			env: spawnEnv,
 			stdin: "pipe",
 			stdout: "pipe",

package/src/eval/py/spawn-options.ts

@@ -40,6 +40,19 @@ export function shouldHideKernelWindow(opts: {
 	return !opts.hostHasInheritableConsole;
 }
 
+/**
+ * Keep eval kernels outside the host's POSIX terminal session.
+ *
+ * User code can start an interactive shell which calls `tcsetpgrp(3)`. If the
+ * kernel shares OMP's session, that shell can replace OMP as the controlling
+ * terminal's foreground process group and the host is then stopped by SIGTTIN
+ * on its next stdin read. Bun implements `detached: true` with `setsid(2)` on
+ * POSIX, making the kernel a session leader with no controlling terminal.
+ */
+export function shouldDetachKernel(platform: NodeJS.Platform): boolean {
+	return platform !== "win32";
+}
+
 /**
  * TTY-based fallback used when the Win32 console probe is unavailable.
  *

package/src/eval/py/tool-bridge.ts

@@ -15,6 +15,7 @@ export interface PyToolBridgeEntry {
 	toolSession: ToolSession;
 	signal?: AbortSignal;
 	emitStatus?: (event: JsStatusEvent) => void;
+	abortRequested?: () => boolean;
 }
 
 export interface PyToolBridgeInfo {
@@ -31,23 +32,21 @@ const registrations = new Map<string, PyToolBridgeEntry>();
 let serverPromise: Promise<BridgeServer> | null = null;
 
 /**
- * Forward a bridge call to {@link callSessionTool}, but resolve the HTTP request
- * the instant the cell's signal aborts instead of waiting for the tool/subagent
- * to fully tear down.
+ * Forward a bridge call to {@link callSessionTool} while respecting eval abort
+ * shielding.
  *
- * The kernel invokes this bridge with a *blocking* `urllib` request from a
- * worker thread (each `agent()` / `tool.*` call). When the cell is interrupted,
- * `parallel()`'s `ThreadPoolExecutor.__exit__` joins those worker threads
- * (`shutdown(wait=True)`), so they cannot unwind until their `urllib` call
- * returns — i.e. until this handler responds. A host-side `agent()` teardown
- * (aborting nested LLM streams + tools across a wide fan-out) routinely exceeds
- * the kernel's SIGINT escalation window, so the kernel was hard-killed and its
- * persistent state lost while the subagents were still winding down. Responding
- * immediately on abort lets the kernel raise through the blocked call and settle
- * cleanly (preserving state); the already-signaled call keeps tearing down in
- * the background, its eventual result/rejection swallowed.
+ * Python invokes this bridge with blocking `urllib` requests from worker threads
+ * (each `agent()` / `tool.*` call). The base executor defers the registered
+ * signal while a bridge call is already paused so in-flight subagents can finish
+ * and persist output instead of being orphaned. Once an abort has been requested,
+ * later bridge calls are rejected before starting; once the shielded signal
+ * finally aborts, this handler still resolves the HTTP request promptly so the
+ * kernel can unwind without being hard-killed.
  */
 async function callSessionToolPromptOnAbort(name: string, args: unknown, entry: PyToolBridgeEntry): Promise<unknown> {
+	if (entry.abortRequested?.()) {
+		throw new Error(`bridge call ${JSON.stringify(name)} aborted: eval cell was interrupted`);
+	}
 	const call = callSessionTool(name, args, {
 		session: entry.toolSession,
 		signal: entry.signal,

package/src/eval/rb/kernel.ts

@@ -16,7 +16,7 @@ import { $ } from "bun";
 import { Settings } from "../../config/settings";
 import { BaseKernel, getRemainingTimeMs, type KernelRuntimeEnv, type KernelStartOptions } from "../kernel-base";
 import type { KernelDisplayOutput } from "../py/display";
-import { hostHasInheritableConsole, shouldHideKernelWindow } from "../py/spawn-options";
+import { hostHasInheritableConsole, shouldDetachKernel, shouldHideKernelWindow } from "../py/spawn-options";
 import { RUBY_PRELUDE } from "./prelude";
 import RUNNER_SCRIPT from "./runner.rb" with { type: "text" };
 import {
@@ -186,6 +186,7 @@ export class RubyKernel extends BaseKernel<KernelExecuteOptions> {
 
 		const proc = Bun.spawn([runtime.rubyPath, scriptPath], {
 			cwd: options.cwd,
+			detached: shouldDetachKernel(process.platform),
 			env: spawnEnv,
 			stdin: "pipe",
 			stdout: "pipe",

package/src/extensibility/custom-tools/types.ts

@@ -23,6 +23,7 @@ import type { Settings } from "../../config/settings";
 import type { ExecOptions, ExecResult } from "../../exec/exec";
 import type { HookUIContext } from "../../extensibility/hooks/types";
 import type * as PiCodingAgent from "../../index";
+import type { LocalProtocolOptions } from "../../internal-urls/local-protocol";
 import type { Theme } from "../../modes/theme/theme";
 import type { ReadonlySessionManager } from "../../session/session-manager";
 import type { TodoItem } from "../../tools/todo";
@@ -96,6 +97,8 @@ export interface CustomToolContext {
 	settings?: Settings;
 	/** Fetch implementation for outbound HTTP; defaults to global fetch when omitted. */
 	fetch?: FetchImpl;
+	/** Calling session's `local://` root mapping for tools that bridge out of the OMP process. */
+	localProtocolOptions?: LocalProtocolOptions;
 	/** Whether to auto-approve all destructive tool operations (--auto-approve CLI flag) */
 	autoApprove?: boolean;
 }

package/src/extensibility/extensions/runner.ts

@@ -7,6 +7,7 @@ import type { KeyId } from "@oh-my-pi/pi-tui";
 import { logger } from "@oh-my-pi/pi-utils";
 import type { ModelRegistry } from "../../config/model-registry";
 import type { Settings } from "../../config/settings";
+import type { LocalProtocolOptions } from "../../internal-urls/local-protocol";
 import type { MemoryRuntimeContext } from "../../memory-backend";
 import { type Theme, theme } from "../../modes/theme/theme";
 import type { SessionManager } from "../../session/session-manager";
@@ -256,6 +257,7 @@ export class ExtensionRunner {
 		private readonly modelRegistry: ModelRegistry,
 		getMemory?: () => MemoryRuntimeContext | undefined,
 		private readonly settings?: Settings,
+		private readonly localProtocolOptions?: LocalProtocolOptions,
 	) {
 		this.#uiContext = noOpUIContext;
 		this.#getMemoryFn = getMemory;
@@ -538,6 +540,7 @@ export class ExtensionRunner {
 			hasPendingMessages: () => this.#hasPendingMessagesFn(),
 			shutdown: () => this.#shutdownHandler(),
 			getSystemPrompt: () => this.#getSystemPromptFn(),
+			localProtocolOptions: this.localProtocolOptions,
 			memory: this.#getMemoryFn?.(),
 		};
 	}

package/src/extensibility/extensions/types.ts

@@ -41,6 +41,7 @@ import type { PythonResult } from "../../eval/py/executor";
 import type { BashResult } from "../../exec/bash-executor";
 import type { ExecOptions, ExecResult } from "../../exec/exec";
 import type * as PiCodingAgent from "../../index";
+import type { LocalProtocolOptions } from "../../internal-urls/local-protocol";
 import type { MemoryRuntimeContext } from "../../memory-backend";
 import type { CustomEditor } from "../../modes/components/custom-editor";
 import type { Theme } from "../../modes/theme/theme";
@@ -420,6 +421,8 @@ export interface ExtensionContext {
 	sessionManager: ReadonlySessionManager;
 	/** Model registry for API key resolution */
 	modelRegistry: ModelRegistry;
+	/** Calling session's `local://` root mapping for external tool bridges. */
+	localProtocolOptions?: LocalProtocolOptions;
 	/** Current model (may be undefined) */
 	model: Model | undefined;
 	/** Read-only model query facade: list / current / resolve / family. */

package/src/extensibility/plugins/manager.ts

@@ -211,6 +211,16 @@ export class PluginManager {
 		}
 	}
 
+	async #removeDependencyEntry(pkgJsonPath: string, name: string): Promise<void> {
+		const pkgJson: { dependencies?: Record<string, string>; [key: string]: unknown } =
+			await Bun.file(pkgJsonPath).json();
+		if (!pkgJson.dependencies || !(name in pkgJson.dependencies)) {
+			return;
+		}
+		delete pkgJson.dependencies[name];
+		await Bun.write(pkgJsonPath, JSON.stringify(pkgJson, null, 2));
+	}
+
 	#collectInstalledNames(deps: Record<string, string>, config: PluginRuntimeConfig): Set<string> {
 		const installedNames = new Set<string>();
 		for (const name of Object.keys(deps)) {
@@ -450,6 +460,17 @@ export class PluginManager {
 		// validation throws.
 		let actualName: string | undefined;
 		try {
+			// Bun treats a dependency replacement from `repo#old-ref` to the same
+			// package at `repo`/`repo#new-ref` as a self-edge and bails with
+			// DependencyLoop. Remove only the stale manifest edge; rollback restores
+			// the original package.json and node_modules snapshot on failure.
+			if (gitSource && existingActualName) {
+				const installedSource = parseGitUrl(depsBefore[existingActualName] ?? "");
+				if (installedSource && installedSource.ref !== gitSource.ref) {
+					await this.#removeDependencyEntry(pkgJsonPath, existingActualName);
+				}
+			}
+
 			// Step 1: write the spec into plugins/package.json + node_modules.
 			const installProc = Bun.spawn(["bun", "install", packageInstallSpec], {
 				cwd: getPluginsDir(),