@estebanforge/pi-antigravity-bridge 1.5.0 → 1.5.2

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.5.2] - 2026-09-15
+
+### 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
+
+- Delegated agy no longer sees the pi tool bridge. `AskAntigravity` spawns `agy -p`, and any agy on the machine discovers MCP servers from the global `~/.gemini/config/mcp_config.json`, which carries a live `pi-bridge-*` entry for every running pi session. A delegation could therefore connect to a host bridge and call tools (observed live: `memory_search`), which the round-trip store denies fail-closed with "no active antigravity turn" the moment no provider turn is streaming - a dead end for the delegation and an error toast in the host session. The bridge entries are now suppressed while a delegated agy starts: disabled before the spawn, re-enabled on process close or after a 5s grace, whichever lands first. Suppression is reference-counted, so overlapping delegations cannot re-enable early; session start re-enables any entries a crashed delegation left disabled. Foreign MCP servers in the file are never touched. Residual race, documented in code: another session's provider agy respawning inside the window reads the entries disabled and that process lacks bridge tools until its next recycle.
+- Real bridge tool-call failures now land on disk in default mode. The daily log records only errors, and `call-tool-fail` was logged at warn tier (toast only), so a failure like the one above left no durable trace. Genuine rejections now log at error tier; routine turn-end and shutdown aborts stay silent, with the reasons shared as constants between the emit sites and the log classifier so the two cannot drift.
+
+### Changed
+
+- README corrected: the bridge mechanism section described only the dir-scoped discovery and claimed the user's global agy config is never touched. Global per-pid registration shipped earlier and is now documented, along with the delegation suppression and its window.
+
 ## [1.5.0] - 2026-09-08
 
 ### Added

package/README.md

@@ -2,11 +2,16 @@
 
 A Gemini model provider **and** the `AskAntigravity` delegation tool for [pi](https://github.com/earendil-works/pi-coding-agent), built on Google's official Antigravity binaries: the `agy` CLI by default, or **Google's official ACP server** (opt-in). It registers `antigravity/gemini-*` models in pi's `/model` picker (streaming), and provides the `AskAntigravity` tool for one-shot delegation - the same combined shape as `pi-claude-bridge`.
 
-<img width="2566" height="1723" alt="SCR-20260903-sefo" src="https://github.com/user-attachments/assets/20f0c04c-d622-4b11-962a-3478f64570c2" align="center"/>
+<p>
+  <img width="1374" height="869" alt="image" src="https://github.com/user-attachments/assets/fdd6c1f0-5144-40ef-9371-77a94de50b76" align="center" />
+</p>
+<p>
+  <img width="1376" height="451" alt="SCR-20260908-mbox" src="https://github.com/user-attachments/assets/d105c8a7-1ace-42f7-8285-642150453761" align="center" />
+</p>
+<p>
+  <img width="1375" height="1342" alt="SCR-20260908-mbvc" src="https://github.com/user-attachments/assets/bb614c55-e0f8-4677-bb0e-6541071e91ef" align="center" />
+</p>
 
-<br/><br/>
-
-<img width="1272" height="842" alt="SCR-20260903-sfcu" src="https://github.com/user-attachments/assets/c483613b-10ff-4d2f-9893-027d84130ac6" align="center" />
 
 If you also have [`@estebanforge/pi-ask-antigravity`](https://github.com/EstebanForge/pi-ask-antigravity) installed, this bridge takes over: pi-ask-antigravity detects the bridge and registers nothing, so the `AskAntigravity` tool is never duplicated.
 
@@ -43,13 +48,13 @@ Residual limits (with or without the bridge):
 
 While agy is the active model it normally cannot see pi's universe of extensions: agentmemory, codegraph, web search, slack/asana, the `Ask*` delegations, and any other installed pi tool. This extension optionally bridges that gap.
 
-The bridge starts a localhost MCP server inside pi's process. `tools/list` returns pi's registered tools (built-in file/shell tools and `AskAntigravity` are filtered out), and a `tools/call` routes into pi's own tool loop via the round-trip described below. agy discovers the server through a per-invocation config: the bridge writes `.agents/mcp_config.json` into a bridge-controlled dir (`~/.pi/agent/antigravity-bridge/agy-mcp-<pid>/`) and the provider passes that dir as an extra `--add-dir` when it spawns agy. The user's global agy config (`~/.gemini/config/mcp_config.json`) is never touched, so standalone agy outside pi is unaffected.
+The bridge starts a localhost MCP server inside pi's process. `tools/list` returns pi's registered tools (built-in file/shell tools and `AskAntigravity` are filtered out), and a `tools/call` routes into pi's own tool loop via the round-trip described below. Discovery has two layers. The provider's agy gets a per-invocation config: the bridge writes `.agents/mcp_config.json` into a bridge-controlled dir (`~/.pi/agent/antigravity-bridge/agy-mcp-<pid>/`) and the driver passes that dir as an extra `--add-dir` when it spawns agy. A per-pid entry (`pi-bridge-<pid>`) is also registered in the user's global agy config (`~/.gemini/config/mcp_config.json`; foreign servers preserved, stale entries swept at start), so agy builds that read only the global config still find the bridge.
 
 **No patch required.** Bridge calls park in the provider's round-trip store; the provider ends the pi assistant message with a `toolUse` stop reason for the real pi tool, pi executes it in its own loop (native cards, permissions, hooks), and the toolResult completes the parked MCP response on the next stream call. This is the same mechanism tianzuo/pi-antigravity uses; upstream pi APIs only.
 
 **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`. The `AskAntigravity` tool spawns its own agy with just the workspace, so that inner agy starts plain (no pi tools) and cannot re-enter. `AskAntigravity` is also filtered from the exposed tool list. Standalone agy is unaffected because nothing is written to its global config.
+**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/ARCHITECTURE.md

@@ -27,7 +27,7 @@ src/config.ts         persisted runtime config (engine + acp block, bridgeTools,
 src/daily-log.ts      daily NDJSON support log (one file per day, 14-day retention, secret redaction, AGY_DEBUG verbose gate); fed by both drivers, the bridge, round-trips, /agy, and ask-tool
 src/ask-tool.ts       the AskAntigravity one-shot delegation tool (model/thinking defaults)
 src/mcp-server.ts     MCP tool bridge server: ferries tools/list + tools/call; calls park in the provider round-trip. Also the approval park: POST /approval (ticket early-ack) + GET /approval/<id>, fail-closed on timeout/unwired/close
-src/mcp-registration.ts registers/unregisters the bridge in ~/.gemini/config/mcp_config.json for the stream-json CLI (per-pid, atomic, stale sweep)
+src/mcp-registration.ts registers/unregisters the bridge in ~/.gemini/config/mcp_config.json for the stream-json CLI (per-pid, atomic, stale sweep) and flips our entries off around AskAntigravity spawns (refcounted; session start re-enables)
 src/approval-gate.ts  shadow tool factory (bash/write/edit): marker calls are ticket-verified approval round-trips, non-marker calls delegate; maps agy native tools onto the shadow surface
 src/approval-detect.ts third-party pi permission-extension detection; resolves approvals.gateMode auto (off until a gate extension exists)
 src/approval-hook.ts  merge-safe .agents/hooks.json staging (PreToolUse) + generated 0600 early-ack/poll hook script; staged timeout exceeds the park budget (hook timeouts soft-pass)

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.
+- `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,6 +72,7 @@ import { registerAskAntigravityTool, toolModelsFromRaw } from "../src/ask-tool.j
 import { startMcpServer, TOKEN_HEADER, type McpServerHandle } from "../src/mcp-server.js";
 import {
 	registerBridgeServer,
+	healBridgeSuppression,
 	sweepStaleBridgeServers,
 	unregisterBridgeServer,
 } from "../src/mcp-registration.js";
@@ -131,6 +132,12 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	const modelInput: Array<"text" | "image"> = engine === "acp" ? ["text", "image"] : ["text"];
 	const models = entries.map((e) => toPiModel(e, modelInput));
 
+	// failAll reasons the bridge treats as routine (turn end / shutdown
+	// sweep), not faults. Shared by the emitters below and the mcpLog
+	// classifier so the substring match cannot drift from the text.
+	const FAIL_REASON_TURN_END = "antigravity turn ended with an unresolved pi tool call";
+	const FAIL_REASON_SHUTDOWN = "antigravity session shut down";
+
 	// Daily file log: every sink below feeds ~/.pi/extensions-data/
 	// estebanforge/pi-antigravity-bridge/logs/<YYYY-MM-DD>.ndjson (see
 	// src/daily-log.ts). Fire-and-forget, secrets redacted, old days pruned.
@@ -140,14 +147,15 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 	// routine disk traffic), so a warn that never reaches the UI is lost.
 	// Every warn toasts here instead; AGY_DEBUG=1 restores the full file
 	// trail. Silent exceptions: deliberate aborts (pi already shows
-	// "Operation aborted"), connection exits (the turn's own error block
-	// carries real crashes), and call-tool-fail (same-instant duplicate of
-	// round-trip-fail). No UI (headless): warn text falls back to stderr.
+	// "Operation aborted") and connection exits (the turn's own error block
+	// carries real crashes). call-tool-fail needs no exclusion here: its tier
+	// is debug or error, never warn. No UI (headless): warn text falls back
+	// to stderr.
 	const rawFileLog = fileLog.log.bind(fileLog);
 	fileLog.log = (event, data, level) => {
 		rawFileLog(event, data, level);
 		if (level !== "warn") return;
-		if (event.startsWith("abort:") || event === "connection-exited" || event === "call-tool-fail") return;
+		if (event.startsWith("abort:") || event === "connection-exited") return;
 		const d = (data ?? {}) as Record<string, unknown>;
 		let text: string;
 		if (event === "round-trip-fail") {
@@ -341,7 +349,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 			{ status: outcome.status, error: outcome.error?.slice(0, 500), aborted: outcome.aborted },
 			outcome.status === "OK" ? "info" : "warn",
 		);
-		roundTrips.failAll("antigravity turn ended with an unresolved pi tool call");
+		roundTrips.failAll(FAIL_REASON_TURN_END);
 	};
 	streamDriver.onTurnEnd = onTurnEnd;
 	acpDriver.onTurnEnd = onTurnEnd;
@@ -593,18 +601,27 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 			// filters below only decide what reaches the user. Bridge calls
 			// start/end at info (one record per tool call, the fragile-path
 			// skeleton); list-tools and startup chatter stay verbose.
-			const level = failures.has(s)
-				? "warn"
-				: s === "call-tool" || s === "call-tool-ok"
+			// Routine abort traffic (failAll on turn end / session shutdown
+			// answers every parked call with an error) is not a fault: debug
+			// only. Any other call-tool-fail is a real rejection (e.g. "no
+			// active antigravity turn" from a client that should not see the
+			// bridge) and lands at error tier - default mode records errors
+			// only, so this is the sole durable trace of the incident.
+			const detail = (d as { msg?: string } | undefined)?.msg ?? "";
+			const routineAbort =
+				s === "call-tool-fail" &&
+				(detail.includes(FAIL_REASON_TURN_END) || detail.includes(FAIL_REASON_SHUTDOWN));
+			const level = !failures.has(s)
+				? s === "call-tool" || s === "call-tool-ok"
 					? "info"
-					: "debug";
+					: "debug"
+				: routineAbort
+					? "debug"
+					: s === "call-tool-fail"
+						? "error"
+						: "warn";
 			fileLog.log(s, d, level);
-			// Routine abort traffic: failAll fires on turn end / session shutdown
-			// and the bridge answers every parked call with an error. Not a fault.
-			if (s === "call-tool-fail") {
-				const detail = (d as { msg?: string } | undefined)?.msg ?? "";
-				if (detail.includes("unresolved pi tool call") || detail.includes("session shut down")) return;
-			}
+			if (routineAbort) return;
 			if (!failures.has(s)) return;
 			const msg = `[antigravity-bridge mcp] ${s}${d !== undefined ? " " + JSON.stringify(d) : ""}`;
 			if (ctx.hasUI) ctx.ui.notify(msg, "warning");
@@ -708,11 +725,12 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		);
 		if (r.ok && r.handle) {
 			mcpHandle = r.handle;
-			// Stream-json engine registration: the agy CLI discovers MCP servers
-			// from ~/.gemini/config/mcp_config.json (ACP uses session/new
-			// mcpServers instead; verified live 2026-09-07). Per-pid entry,
-			// removed at session_shutdown; stale entries swept at start.
+			// Stale entries swept at start; entries a crashed delegation left
+			// 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();
+			healBridgeSuppression();
 			registerBridgeServer({
 				pid: process.pid,
 				port: r.handle.port,
@@ -816,7 +834,7 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 		const h = mcpHandle;
 		mcpHandle = null;
 		await h?.close();
-		roundTrips.failAll("antigravity session shut down");
+		roundTrips.failAll(FAIL_REASON_SHUTDOWN);
 		// "recycle", NOT "shutdown": pi fires session_shutdown on /new, /resume
 		// and /fork (docs/extensions.md session lifecycle), not only on process
 		// exit. The drivers are process-lifetime singletons; closing them with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estebanforge/pi-antigravity-bridge",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "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

@@ -25,6 +25,7 @@ import {
 	snapshotConversations,
 } from "./discovery.js";
 import { loadConfig, type AgyMode, type ThinkingTier } from "./config.js";
+import { acquireBridgeSuppression } from "./mcp-registration.js";
 import { spawnAgyModelsRaw } from "./models.js";
 
 // --- Constants -------------------------------------------------------------
@@ -46,6 +47,7 @@ const FAMILY_DEFAULT_TIER: Record<Family, ThinkingTier> = {
 	pro: "high",
 	other: "medium",
 };
+
 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.
@@ -510,6 +512,22 @@ export async function registerAskAntigravityTool(
 			const binary = process.env.AGY_BIN || "agy";
 			let out = "";
 
+			// 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(() => {
 						const elapsed = Math.floor((Date.now() - start) / 1000);
@@ -592,6 +610,7 @@ export async function registerAskAntigravityTool(
 						if (watchdog) clearTimeout(watchdog);
 						if (sigkillTimer) clearTimeout(sigkillTimer);
 						if (signal) signal.removeEventListener("abort", onAbort);
+						restoreBridge();
 					};
 					const onAbort = () => killTree();
 
@@ -698,6 +717,9 @@ export async function registerAskAntigravityTool(
 				return { content: [{ type: "text", text: `failed to run agy: ${msg}` }], details };
 			}
 			finally {
+				// Belt and braces: cleanup() already restores on close/error; this
+				// covers paths that never reached the process (sync spawn throw).
+				restoreBridge();
 				if (contextFile) {
 					try {
 						fs.unlinkSync(contextFile);

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). */
@@ -93,6 +105,215 @@ export function unregisterBridgeServer(pid: number, configPath: string = mcpConf
 	return { wrote: true };
 }
 
+/** Flip `disabled` on every pi-bridge-* entry (foreign servers untouched).
+ *
+ *  (1) Delegation isolation: the global config is read by ANY agy on the
+ *  machine, so an `agy -p` we spawn ourselves (AskAntigravity) would discover
+ *  live bridge entries and call tools the round-trip store cannot serve
+ *  outside a live provider turn (fail-closed "no active antigravity turn",
+ *  observed live 2026-09-15). agy reads the config once at startup, so a
+ *  short suppression window around the spawn hides the bridge from it.
+ *
+ *  (2) Startup healing (disabled=false): clears entries a crashed delegation
+ *  left suppressed. */
+export function setBridgeEntriesDisabled(
+	disabled: boolean,
+	configPath: string = mcpConfigPath(),
+): { wrote: boolean; changed: number; reason?: string } {
+	const read = readConfig(configPath);
+	if (!read.ok) return { wrote: false, changed: 0, reason: read.reason };
+	let changed = 0;
+	for (const [name, entry] of Object.entries(read.config.mcpServers)) {
+		if (!/^pi-bridge-\d+$/.test(name)) continue;
+		if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+		const e = entry as { disabled?: unknown };
+		if ((e.disabled === true) === disabled) continue;
+		e.disabled = disabled;
+		changed++;
+	}
+	if (changed === 0) return { wrote: false, changed: 0 };
+	writeConfig(configPath, read.config);
+	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 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) {
+		// 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;
+		released = true;
+		const left = Math.max(0, (suppressionRefs.get(key) ?? 1) - 1);
+		if (left === 0) suppressionRefs.delete(key);
+		else suppressionRefs.set(key, left);
+		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 {