@estebanforge/pi-antigravity-bridge 1.5.1 → 1.5.3

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.5.3] - 2026-09-10
+
+### Fixed
+
+- **Parallel agy tool approvals no longer clobber each other.** The shadow-tool `GatePolicy` asked through pi's `ui.confirm`, but pi's TUI shows ONE extension dialog at a time and an overlapping call replaces the live dialog without settling it: with several agy bash/write/edit calls in flight, approvals were silently lost (the park timeout eventually resolved them as declines). The confirm now holds the same shared cross-extension dialog lock as the pi-*-me gates (`withDialogLock`, `Symbol.for("pi-me.dialog-lock")`), so approvals queue and render in turn; the park timeout still bounds each dialog and is held inside the lock. New `src/dialog-lock.ts` module plus contract tests (FIFO order, throw-release, shared key).
+
+## [1.5.2] - 2026-09-09
+
+### Fixed
+
+- Delegation suppression now spans the whole delegated run. The 1.5.1 suppression window ended after 5 seconds, but agy watches `mcp_config.json` and hot-reloads MCP servers on every file change (`ReloadMcpConfig` in the binary): the window's rewrite poked the live delegation into reconnecting, and a delegated peer review hit the fail-closed "no active antigravity turn" deny ~50 seconds in (observed live, reproduced on demand through `AskAntigravity`). The bridge entries are now hidden until the delegated process actually closes; the release fires on process close or error only, and a regression test pins "exactly one release, at close, never on a timer" with a fake `AGY_BIN` that outlives the old grace (plus the spawn-error route).
+- Suppression is coordinated across pi processes through a shared marker file (`suppression.json` in the bridge's extensions-data dir, `{pid: since}` per live delegation, 0600/0700, atomic rename). Release and the session-start heal re-enable the entries only when no live delegator remains, so two sessions delegating concurrently - or a second pi window opening mid-delegation, which the old blind heal did unconditionally - no longer un-hide each other's entries, and a session starting mid-delegation registers its own entry disabled. Dead delegators are pruned by pid liveness with a 24h age bound against pid reuse; re-enable decisions read the marker fresh at the flip, so a racing acquire keeps its suppression. The marker is coordination only (the disabled flags in `mcp_config.json` stay the gate), lives outside agy's watched config dir, and its writes are best-effort: a lost entry in the syscall-scale read-modify-write window degrades to the status-quo fail-closed deny, and any residual interleave is bounded and self-heals at the next release or heal.
+
+### Changed
+
+- README's recursion-safety paragraph, the DEVELOPMENT regression list, and the AGENTS.md module lines describe the shipped mechanism: whole-run suppression, cross-process marker, marker-aware heal and registration guard.
+
 ## [1.5.1] - 2026-09-15
 
 ### Fixed

package/README.md

@@ -54,7 +54,7 @@ The bridge starts a localhost MCP server inside pi's process. `tools/list` retur
 
 **Long calls don't die.** agy's MCP client abandons a `tools/call` request at a flat ~180s, which used to kill any pi tool that ran longer (a long peer review, a build, a commit preview waiting for you). A call still running after ~20 seconds now settles its HTTP request with a `STILL RUNNING` answer carrying a `callId` while pi keeps executing; agy fetches the result through the bridge-local `bridge_poll_result` tool and polls until it lands. Escalated calls get their own 30-minute budget, so human-gated tools can take as long as the human takes. Fast calls stay fully synchronous and never see any of this. If a park does fail (abort, timeout, recycle), the late result is re-routed to agy as a follow-up prompt in the same conversation instead of being lost.
 
-**Recursion safety.** Only the provider's agy receives the extra `--add-dir`. `AskAntigravity` is also filtered from the exposed tool list. Its delegated `agy -p` spawns with just the workspace, and while it starts the bridge suppresses its global per-pid entries: disabled before the spawn, re-enabled on process close or after a 5s grace (whichever lands first), refcounted across overlapping delegations, and re-enabled at every session start. The inner agy therefore sees no bridge and cannot re-enter pi. A hand-run agy outside pi that starts inside the seconds-wide window briefly misses the bridge; foreign servers in the global config are never touched.
+**Recursion safety.** Only the provider's agy receives the extra `--add-dir`. `AskAntigravity` is also filtered from the exposed tool list. Its delegated `agy -p` spawns with just the workspace, and for the whole delegated run the bridge hides its global per-pid entries: disabled before the spawn, released only on process close or error - agy watches the config and hot-reloads MCP servers on file changes, so a mid-run re-enable would poke the live delegation back into pi. A cross-process marker (`suppression.json` in the bridge's extensions-data dir) coordinates concurrent delegations: entries come back only when no live delegation remains, a session starting mid-delegation registers its own entry disabled, and the session-start heal re-enables only once the last delegator is gone (dead entries pruned by pid liveness with a 24h age bound). The inner agy therefore sees no bridge and cannot re-enter pi. Foreign servers in the global config are never touched.
 
 **Cost / fan-out.** Every registered pi tool except builtins (and `AskAntigravity`) is exposed, including other delegation tools like `AskClaude`/`AskCodex`. agy can therefore chain into other models via the bridge, which is a new cost/time fan-out vector that did not exist before this feature.
 

package/docs/DEVELOPMENT.md

@@ -98,7 +98,8 @@ Most "stuck" reports trace to one of:
 - `tests/acp-driver.test.ts` - the ACP driver over the fake server (`tests/helpers/fake-acp-server.mjs`, scenario-selected): happy flow, load-replay, permission auto-answer, Gate D abort (cancel probe, teardown, `cancelSupported` memory), the stale-exit race (a killed connection's late exit must not fail its replacement - `ACP_FAKE_SLOW_DEATH_MS`), auth errors, park/kickIdle timer pause with remaining budget.
 - `tests/acp-config.test.ts` - engine selection narrowing (`AGY_ENGINE`/`config.engine`), acp block parsing.
 - `tests/daily-log.test.ts` - the support log: day rotation, retention cutoff boundary, secret redaction (incl. header blocks), the 4 KB record cap, never-throw on a broken dir, and the two-tier gate (debug records dropped unless `AGY_DEBUG`).
-- `tests/mcp-registration.test.ts` - the `~/.gemini/config/mcp_config.json` registration for the stream-json CLI: exact agy entry shape, foreign servers preserved, corrupt config refused, atomic writes, stale-entry sweep, delegation suppression (`setBridgeEntriesDisabled` flip/restore/idempotence, refcounted `acquireBridgeSuppression`).
+- `tests/mcp-registration.test.ts` - the `~/.gemini/config/mcp_config.json` registration for the stream-json CLI: exact agy entry shape, foreign servers preserved, corrupt config refused, atomic writes, stale-entry sweep, delegation suppression (`setBridgeEntriesDisabled` flip/restore/idempotence, refcounted `acquireBridgeSuppression`) and the cross-process marker (concurrent two-session simulation, dead and stale delegator pruning, marker-aware `healBridgeSuppression`, the registration guard).
+- `tests/ask-tool-suppression.test.ts` - the AskAntigravity delegation path end-to-end over a fake `AGY_BIN` that outlives the old grace: exactly one suppression release, at process close, never on a timer.
 - `tests/engine-picker.test.ts` - first-run onboarding: picker gate (no config file + no AGY_ENGINE, fail-closed fs), option order (stream-json first), the ACP download/sign-in disclosure pins (intro + saved toast), agy binary detection (PATH scan, explicit path, fail-closed), missing-CLI toast copy.
 - `tests/provider-escalation.test.ts` - the early-ack + poll pipeline (escalation registry, poll views, late-delivery tombstones) and tool-result image forwarding on both engines.
 - `tests/approval-gate.test.ts` - the shadow tool factory: marker calls never execute, ticket verification denies forged/stale markers before the policy, denials throw, native-to-shadow mapping.

package/extensions/index.ts

@@ -72,7 +72,7 @@ import { registerAskAntigravityTool, toolModelsFromRaw } from "../src/ask-tool.j
 import { startMcpServer, TOKEN_HEADER, type McpServerHandle } from "../src/mcp-server.js";
 import {
 	registerBridgeServer,
-	setBridgeEntriesDisabled,
+	healBridgeSuppression,
 	sweepStaleBridgeServers,
 	unregisterBridgeServer,
 } from "../src/mcp-registration.js";
@@ -88,6 +88,7 @@ import {
 import { mapAgyToolToNative } from "../src/native-tools.js";
 import { Type } from "typebox";
 import { patchStatus, restorePatch } from "../src/patch-cleanup.js";
+import { withDialogLock } from "../src/dialog-lock.js";
 
 // Last UI seen (session_start / /agy commands). The ACP login URL arrives
 // via the driver log sink, which has no command context; the stash lets that
@@ -726,10 +727,11 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		if (r.ok && r.handle) {
 			mcpHandle = r.handle;
 			// Stale entries swept at start; entries a crashed delegation left
-			// suppressed are healed here (live bridges start every session
-			// enabled).
+			// suppressed are healed here - but only when no live delegation is in
+			// flight anywhere (marker-aware heal). A blind re-enable used to
+			// un-hide the bridge during another session's active delegation.
 			sweepStaleBridgeServers();
-			setBridgeEntriesDisabled(false);
+			healBridgeSuppression();
 			registerBridgeServer({
 				pid: process.pid,
 				port: r.handle.port,
@@ -807,7 +809,14 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 								: typeof params.path === "string"
 									? params.path
 									: JSON.stringify(stripMarkerFields(params)).slice(0, 200);
-						const ok = await extCtx.ui.confirm(`agy ${tool}?`, what, { timeout: APPROVAL_PARK_MS });
+						// Dialog lock: parallel agy tool approvals queue up instead of
+						// clobbering the live dialog (which silently loses the approval).
+						// Capture the narrowed method: TS drops the guard's narrowing
+						// inside the deferred closure.
+						const uiConfirm = extCtx.ui.confirm.bind(extCtx.ui);
+						const ok = await withDialogLock(() =>
+							uiConfirm(`agy ${tool}?`, what, { timeout: APPROVAL_PARK_MS }),
+						);
 						return ok ? { allow: true } : { allow: false, reason: `declined in pi (agy ${tool})` };
 					};
 					const handle = r.handle;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estebanforge/pi-antigravity-bridge",
-  "version": "1.5.1",
+  "version": "1.5.3",
   "description": "Gemini provider for Pi on the Antigravity ACP server (official Google ACP) or the stream-json agy CLI. antigravity/* models in Pi's /model picker, no-patch MCP bridge: agy runs Pi's tools. ToS safe to use.",
   "keywords": [
     "pi-package",

package/src/ask-tool.ts

@@ -48,14 +48,6 @@ const FAMILY_DEFAULT_TIER: Record<Family, ThinkingTier> = {
 	other: "medium",
 };
 
-/** Bridge-suppression grace for a delegated `agy -p`. The shared config stays
- *  disabled for min(process close, this): agy reads it once at startup, so
- *  this bound covers that read without staying disabled for the whole run.
- *  Residual race: a provider agy respawn in ANOTHER session landing inside
- *  the window reads the entries disabled and that process lacks bridge tools
- *  until its next recycle (session start heals the file). Fail-open past the
- *  window = status-quo behavior. */
-const BRIDGE_SUPPRESS_MS = 5000;
 const TIER_RANK: Record<ThinkingTier, number> = { low: 0, medium: 1, high: 2 };
 
 // Static alias overlay for non-Gemini models agy may or may not surface.
@@ -520,30 +512,21 @@ export async function registerAskAntigravityTool(
 			const binary = process.env.AGY_BIN || "agy";
 			let out = "";
 
-			// Delegation isolation: any agy on this machine reads the global
-			// mcp_config.json, so this spawned `agy -p` would discover live
-			// pi-bridge-* entries and call tools the host bridge cannot serve
-			// outside a live provider turn ("no active antigravity turn").
-			// Delegation isolation: any agy on this machine reads the global
-			// mcp_config.json, so this spawned `agy -p` would discover live
-			// pi-bridge-* entries and call tools the host bridge cannot serve
-			// outside a live provider turn ("no active antigravity turn").
-			// Window = min(close, grace): the release fires on process close or
-			// after BRIDGE_SUPPRESS_MS, whichever lands first. Refcounted, so an
-			// overlapping delegation cannot re-enable early. A refused config
-			// fail-opens to the status quo.
-			const releaseBridge = acquireBridgeSuppression();
-			let suppressTimer: ReturnType<typeof setTimeout> | undefined = setTimeout(
-				releaseBridge,
-				BRIDGE_SUPPRESS_MS,
-			);
-			const restoreBridge = (): void => {
-				if (suppressTimer) {
-					clearTimeout(suppressTimer);
-					suppressTimer = undefined;
-				}
-				releaseBridge();
-			};
+			// Delegation isolation: any agy on this machine discovers MCP servers
+			// from the global mcp_config.json, so this spawned `agy -p` would find
+			// live pi-bridge-* entries and call tools the host bridge cannot serve
+			// outside a live provider turn ("no active antigravity turn"). agy also
+			// WATCHES that file (ReloadMcpConfig): re-enabling mid-run pokes the live
+			// delegation to reconnect. The old 5s grace timer did exactly that -
+			// observed live 2026-09-09 as a call-tool-fail ~50s into a delegation -
+			// so the entries now stay hidden for the WHOLE delegated run. The release
+			// fires only on process close/error (cleanup + finally below); if pi
+			// itself dies first, session start heals the file
+			// (healBridgeSuppression in extensions/index.ts, marker-aware). Cross-
+			// process coordination rides the suppression marker in mcp-registration.
+			// Refcounted, so overlapping delegations in this process cannot release
+			// each other's window early. A refused config fail-opens to the status quo.
+			const restoreBridge = acquireBridgeSuppression();
 
 			const statusInterval = onUpdate
 				? setInterval(() => {

package/src/dialog-lock.ts

@@ -0,0 +1,48 @@
+// Process-wide FIFO lock for human-facing dialogs (confirm/editor/select).
+//
+// pi's interactive UI shows ONE extension dialog at a time; an overlapping
+// ctx.ui.* dialog call REPLACES the live dialog and the replaced promise
+// never settles, so parallel gated tool calls hang forever (or silently lose
+// their prompt). Holding this lock around each dialog serializes them: the
+// first renders, the rest appear in turn as each is answered.
+//
+// The lock is keyed via Symbol.for because ALL pi-* extensions run in the
+// SAME pi process and must share one queue: a per-module lock would still let
+// a dialog from one extension clobber a dialog from another in the same
+// parallel tool-call batch.
+const DIALOG_LOCK: unique symbol = Symbol.for("pi-me.dialog-lock");
+
+interface DialogQueue {
+  tail: Promise<void>;
+}
+
+function dialogQueue(): DialogQueue {
+  const host = globalThis as typeof globalThis & Record<symbol, unknown>;
+  const existing = host[DIALOG_LOCK] as DialogQueue | undefined;
+  if (existing) return existing;
+  const created: DialogQueue = { tail: Promise.resolve() };
+  host[DIALOG_LOCK] = created;
+  return created;
+}
+
+/**
+ * Run `run` while holding the cross-extension dialog lock. FIFO: each caller
+ * chains onto the queue tail synchronously (before its first await), so call
+ * order is the order the dialogs appear. Released in a finally block, so one
+ * throwing dialog can never wedge the queue for the callers behind it.
+ * NOT reentrant: calling it inside a held `run` self-deadlocks.
+ */
+export async function withDialogLock<T>(run: () => Promise<T>): Promise<T> {
+  const queue = dialogQueue();
+  const prev = queue.tail;
+  let release!: () => void;
+  queue.tail = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+  await prev;
+  try {
+    return await run();
+  } finally {
+    release();
+  }
+}

package/src/mcp-registration.ts

@@ -66,20 +66,32 @@ function writeConfig(file: string, config: McpConfig): void {
 }
 
 /** Register (or refresh) the bridge's per-pid server entry. Foreign servers
- *  in the file are preserved. */
+ *  in the file are preserved.
+ *
+ *  One shared guard for delegation isolation: while ANY live delegation is
+ *  in flight anywhere on the machine (per the suppression marker), a fresh
+ *  registration lands disabled - the delegated agy must not discover a new
+ *  bridge mid-run. The last release re-enables every entry again. */
 export function registerBridgeServer(
 	entry: { pid: number; port: number; token: string; tokenHeader: string },
 	configPath: string = mcpConfigPath(),
-): { wrote: boolean; reason?: string } {
+	opts: {
+		markerPath?: string;
+		isAlive?: (pid: number) => boolean;
+		now?: () => number;
+	} = {},
+): { wrote: boolean; disabled: boolean; reason?: string } {
+	const marker = readSuppressionMarker(opts.markerPath ?? suppressionMarkerPath());
+	const disabled = hasLiveDelegator(marker, opts.isAlive ?? pidAlive, (opts.now ?? Date.now)());
 	const read = readConfig(configPath);
-	if (!read.ok) return { wrote: false, reason: read.reason };
+	if (!read.ok) return { wrote: false, disabled, reason: read.reason };
 	read.config.mcpServers[bridgeServerName(entry.pid)] = {
-		disabled: false,
+		disabled,
 		headers: { [entry.tokenHeader]: entry.token },
 		serverUrl: `http://127.0.0.1:${entry.port}/mcp`,
 	} satisfies BridgeServerEntry;
 	writeConfig(configPath, read.config);
-	return { wrote: true };
+	return { wrote: true, disabled };
 }
 
 /** Remove the bridge's per-pid server entry (close path). */
@@ -124,19 +136,123 @@ export function setBridgeEntriesDisabled(
 	return { wrote: true, changed };
 }
 
+// --- Cross-process suppression marker --------------------------------------
+
+/** Shape of the shared delegator marker (suppression.json). Keyed by pi pid;
+ *  `since` is the acquire timestamp in ms since epoch. Coordination ONLY:
+ *  the disabled flags in mcp_config.json stay the actual gate. */
+export interface SuppressionMarker {
+	delegators: Record<string, { since: number }>;
+}
+
+/** Marker path, mirroring the extensions-data convention (src/config.ts
+ *  logsDir). Lives OUTSIDE ~/.gemini so agy's watched config dir stays
+ *  untouched. */
+export function suppressionMarkerPath(home: string = os.homedir()): string {
+	return path.join(
+		home,
+		".pi",
+		"extensions-data",
+		"estebanforge",
+		"pi-antigravity-bridge",
+		"suppression.json",
+	);
+}
+
+/** A SIGKILLed pi can leave its marker entry behind, and pid reuse could
+ *  keep kill(pid,0) answering forever. The age bound caps that wedge: a
+ *  delegation never legitimately runs this long, so an entry this old is
+ *  dead regardless of what the pid probe says. */
+const DELEGATOR_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+
+function readSuppressionMarker(file: string): SuppressionMarker {
+	try {
+		const parsed: unknown = JSON.parse(fs.readFileSync(file, "utf8"));
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { delegators: {} };
+		const delegators = (parsed as SuppressionMarker).delegators;
+		if (!delegators || typeof delegators !== "object" || Array.isArray(delegators)) {
+			return { delegators: {} };
+		}
+		return { delegators };
+	} catch {
+		// Missing or corrupt marker: fail-open to empty. Never worse than the
+		// pre-marker blind re-enable; the next write replaces the file.
+		return { delegators: {} };
+	}
+}
+
+function writeSuppressionMarker(file: string, marker: SuppressionMarker): void {
+	fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+	const tmp = `${file}.${process.pid}.tmp`;
+	fs.writeFileSync(tmp, JSON.stringify(marker, null, 2) + "\n", { mode: 0o600 });
+	fs.renameSync(tmp, file);
+}
+
+function delegatorLive(pid: string, entry: { since?: number } | undefined, isAlive: (pid: number) => boolean, now: number): boolean {
+	const n = Number(pid);
+	const since = typeof entry?.since === "number" ? entry.since : 0;
+	return Number.isFinite(n) && n > 0 && now - since < DELEGATOR_MAX_AGE_MS && isAlive(n);
+}
+
+function pruneDelegators(
+	marker: SuppressionMarker,
+	isAlive: (pid: number) => boolean,
+	now: number,
+): { kept: SuppressionMarker; pruned: string[] } {
+	const kept: SuppressionMarker = { delegators: {} };
+	const pruned: string[] = [];
+	for (const [pid, entry] of Object.entries(marker.delegators)) {
+		if (delegatorLive(pid, entry, isAlive, now)) kept.delegators[pid] = { since: entry.since };
+		else pruned.push(pid);
+	}
+	return { kept, pruned };
+}
+
+function hasLiveDelegator(marker: SuppressionMarker, isAlive: (pid: number) => boolean, now: number): boolean {
+	return Object.entries(marker.delegators).some(([pid, entry]) => delegatorLive(pid, entry, isAlive, now));
+}
+
+function bestEffortWriteMarker(file: string, marker: SuppressionMarker): void {
+	try {
+		writeSuppressionMarker(file, marker);
+	} catch {
+		// Coordination hint only; a failed write must never break a release or
+		// a heal. The disabled flags in mcp_config.json remain the gate.
+	}
+}
+
 const suppressionRefs = new Map<string, number>();
 
 /** Reference-counted suppression for a self-spawned agy process (AskAntigravity
- *  delegation). First acquire disables every pi-bridge-* entry, last release
- *  re-enables; nested acquires are free, so overlapping delegations in one
- *  process cannot clobber each other's window. Same-process only: delegations
- *  from two pi sessions still race on the shared file - accepted, fail-open
- *  to the status-quo error. */
-export function acquireBridgeSuppression(configPath: string = mcpConfigPath()): () => void {
-	const key = path.resolve(configPath);
+ *  delegation). First acquire disables every pi-bridge-* entry AND records
+ *  this process's pid in the shared suppression marker; last release removes
+ *  it and re-enables only when no LIVE delegator remains - so two pi sessions
+ *  delegating concurrently no longer re-enable each other's entries
+ *  (previously a same-process-only refcount raced on the shared file).
+ *  Nested acquires in one process are free. Residual race: concurrent
+ *  read-modify-write of the marker across processes is last-writer-wins
+ *  (atomic rename), and a syscall-scale interleave can still briefly re-open
+ *  the bridge during a live delegation; both are bounded, self-heal at the
+ *  next release/heal, and degrade to the status-quo fail-closed deny. */
+export function acquireBridgeSuppression(opts: SuppressionOptions = {}): () => void {
+	const configPath = opts.configPath ?? mcpConfigPath();
+	const markerPath = opts.markerPath ?? suppressionMarkerPath();
+	const pid = opts.pid ?? process.pid;
+	const isAlive = opts.isAlive ?? pidAlive;
+	const now = opts.now ?? Date.now;
+	const key = `${path.resolve(markerPath)}\u0000${pid}`;
 	const refs = (suppressionRefs.get(key) ?? 0) + 1;
 	suppressionRefs.set(key, refs);
-	if (refs === 1) setBridgeEntriesDisabled(true, configPath);
+	if (refs === 1) {
+		// Marker BEFORE the config flip: a session-start heal racing between
+		// the two writes reads an empty marker and would re-enable entries for
+		// a delegation that is about to go live. Recording first shrinks that
+		// window to the config flip itself.
+		const marker = readSuppressionMarker(markerPath);
+		marker.delegators[String(pid)] = { since: now() };
+		bestEffortWriteMarker(markerPath, marker);
+		setBridgeEntriesDisabled(true, configPath);
+	}
 	let released = false;
 	return () => {
 		if (released) return;
@@ -144,10 +260,60 @@ export function acquireBridgeSuppression(configPath: string = mcpConfigPath()):
 		const left = Math.max(0, (suppressionRefs.get(key) ?? 1) - 1);
 		if (left === 0) suppressionRefs.delete(key);
 		else suppressionRefs.set(key, left);
-		if (left === 0) setBridgeEntriesDisabled(false, configPath);
+		if (left === 0) {
+			const marker = readSuppressionMarker(markerPath);
+			delete marker.delegators[String(pid)];
+			const { kept } = pruneDelegators(marker, isAlive, now());
+			bestEffortWriteMarker(markerPath, kept);
+			// Re-read right before the flip: an acquire that raced us between
+			// the marker write and this read is already live and must keep its
+			// suppression (a stale snapshot here would re-enable over it).
+			const fresh = readSuppressionMarker(markerPath);
+			if (Object.keys(fresh.delegators).length === 0) {
+				setBridgeEntriesDisabled(false, configPath);
+			}
+		}
 	};
 }
 
+export interface SuppressionOptions {
+	/** Global mcp_config.json path (default: the real user config). */
+	configPath?: string;
+	/** Cross-process delegator marker path (default: suppression.json in the
+	 *  bridge's extensions-data dir). */
+	markerPath?: string;
+	/** Delegator identity; defaults to this process's pid. Injectable so tests
+	 *  can simulate two sessions in one process. */
+	pid?: number;
+	isAlive?: (pid: number) => boolean;
+	now?: () => number;
+}
+
+/** Session-start heal, marker-aware. Prunes dead or stale delegators, then
+ *  re-enables the entries ONLY when no live delegator remains. A blind
+ *  re-enable here used to un-hide the bridge during another session's active
+ *  delegation - a plain session start in a second window could reproduce the
+ *  fail-closed deny this file exists to prevent. */
+export function healBridgeSuppression(opts: SuppressionOptions = {}): {
+	pruned: string[];
+	reEnabled: boolean;
+	reason?: string;
+} {
+	const configPath = opts.configPath ?? mcpConfigPath();
+	const markerPath = opts.markerPath ?? suppressionMarkerPath();
+	const isAlive = opts.isAlive ?? pidAlive;
+	const now = opts.now ?? Date.now;
+	const marker = readSuppressionMarker(markerPath);
+	const { kept, pruned } = pruneDelegators(marker, isAlive, now());
+	if (pruned.length > 0) bestEffortWriteMarker(markerPath, kept);
+	// Decide on a FRESH read, not the pruned snapshot: an acquire that raced
+	// us after our write is already live and must keep its suppression.
+	const fresh = readSuppressionMarker(markerPath);
+	if (Object.keys(fresh.delegators).length > 0) return { pruned, reEnabled: false };
+	const flip = setBridgeEntriesDisabled(false, configPath);
+	return { pruned, reEnabled: flip.changed > 0, reason: flip.reason };
+}
+
 /** Default liveness probe: can the signal be delivered? */
 function pidAlive(pid: number): boolean {
 	try {