@estebanforge/pi-antigravity-bridge 1.7.10 → 1.7.12

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+## [1.7.12] - 2026-10-12
+
+### Fixed
+
+- **Unpolled escalated results are re-delivered instead of stranding.** Delivery of an escalated bridge call depends on the model polling `bridge_poll_result`, and the model sometimes ends its turn after the `STILL RUNNING` ack instead — observed live with `ask_user_question`: the user's answer settled into the escalation registry, the bridge printed a human-only `[bridge] ... available via bridge_poll_result` note, and the conversation dead-ended (`git_commit` worked only because the model happened to poll). The ack itself licensed stopping with a promise the bridge did not implement ("if you stop polling, the bridge re-delivers the result in a later turn"). Three changes close it: the ack now forbids ending the turn while a call is unresolved; the escalation registry tracks delivery (`markDelivered` when a poll returns a terminal answer, `stampConversation` at turn end so first-turn parks — which return before the provider's `store.set` — still know their conversation, first stamp wins) and exposes a single-use registry-wide sweep for done-but-undelivered results; and the provider runs that sweep at every turn boundary — the toolResult pass when the turn is dead, after a live turn's outcome, and any later pass, so a strand cannot outlive the next one — re-delivering as a late prompt in the stamped conversation through the existing `buildLateResultPrompt` path. A result whose conversation is unknowable settles quietly and stays pollable instead of prompting a brand-new conversation, and a delivery whose `driver.run` fails to start releases its claim for the next pass. Claims are single-use and entries stay pollable, so a compliant model sees no change; late delivery stays text-only on this path (image blocks are dropped, same as dead-park late delivery).
+
+## [1.7.11] - 2026-10-10
+
+### Added
+
+- AskAntigravity prompts now carry a `[TIME BUDGET]` notice matching the resolved timeout (default 10 minutes), placed before the plan-mode guard banners so the safety constraints stay the last text the model reads. `timeoutMinutes` values that cannot arm a real timer (non-positive, non-finite, above the 35791-minute ceiling) are rejected with a clear error instead of arming an instant-kill watchdog.
+
+### Changed
+
+- **AskAntigravity dedup onto `pi-ask-shared` (behavior-preserving).** The tool's copy of the agy model grammar, tiered alias resolution, plan-mode guard prompts, prompt assembly, and argv construction now imports the shared peer adapter (new dependency `@estebanforge/pi-ask-shared`); `src/discovery.ts` is deleted — its conversation-bind technique (snapshot/diff + /proc FD scan, including the `onAmbiguous` hook, now upstream in the shared adapter) was the last consumer. The process block is deliberately kept bridge-local: it settles on close AND exit, leaves stdout/stderr uncapped, and threads the MCP-entry suppression release into cleanup — all three diverge from the shared `runProcess` contract on purpose. Shared `newConversationId` gained the `onAmbiguous` callback and exports `procTreeOpenDbResolver` (both absorbed from discovery.ts; `conversationDbPath` was unused and died with the module).
+
 ## [1.7.10] - 2026-10-07
 
 ### Added

package/extensions/index.ts

@@ -434,6 +434,10 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 			outcome.status === "OK" ? "info" : "warn",
 		);
 		roundTrips.failAll(FAIL_REASON_TURN_END);
+		// Stamp live escalations with the ended turn's conversation: the park
+		// pass returns before the provider's store.set, so a first-turn park
+		// has no other record of where its result must be re-delivered.
+		if (outcome.conversationId) roundTrips.stampConversation(outcome.conversationId);
 	};
 	streamDriver.onTurnEnd = onTurnEnd;
 	acpDriver.onTurnEnd = onTurnEnd;
@@ -817,7 +821,15 @@ export default async function (pi: ExtensionAPI): Promise<void> {
 			if (name === POLL_TOOL_NAME) {
 				const wanted = typeof args.callId === "string" ? args.callId : "";
 				mcpLog("poll-tool", { callId: wanted });
-				return Promise.resolve(formatPollAnswer(wanted, roundTrips.poll(wanted)));
+				const view = roundTrips.poll(wanted);
+				// A terminal answer means the model RECEIVED the result; mark it
+				// so the redelivery path never double-delivers. poll() itself
+				// stays pure (internal peeks must not mark). Accepted gap: the
+				// mark fires when the poll ANSWERS, not when the HTTP response
+				// lands; a drop inside that one-write window would mark a result
+				// the model never saw.
+				if (view && view.state !== "running") roundTrips.markDelivered(wanted);
+				return Promise.resolve(formatPollAnswer(wanted, view));
 			}
 			if (name !== ACTIVATE_SKILL_TOOL_NAME) {
 				// A cached MCP catalog is not authorization. An inactive/hidden tool

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estebanforge/pi-antigravity-bridge",
-  "version": "1.7.10",
+  "version": "1.7.12",
   "description": "Gemini provider for Pi on the Antigravity ACP server (official Google ACP) or the stream-json agy CLI. Use antigravity/* models in Pi. Full /model picker support. Models runs Pi's tools. ToS safe to use.",
   "keywords": [
     "pi-package",
@@ -54,6 +54,7 @@
     }
   },
   "dependencies": {
+    "@estebanforge/pi-ask-shared": "^0.1.2",
     "@modelcontextprotocol/sdk": "^1.29.0"
   }
 }

package/src/ask-tool.ts

@@ -21,10 +21,21 @@ import { Text } from "@earendil-works/pi-tui";
 import { contentText, type ThinkingLevel } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 import {
+	buildAgyArgs,
+	buildFinalPrompt,
+	buildTimeBudgetNotice,
+	MAX_TIMEOUT_MINUTES,
 	CONVERSATIONS_DIR,
+	CONV_ID_RE,
+	filterHiddenModels,
+	mergeCatalog,
 	newConversationId,
+	parseModelLine,
+	resolveAgyModel,
 	snapshotConversations,
-} from "./discovery.js";
+	type ModelEntry,
+	type Mode,
+} from "@estebanforge/pi-ask-shared";
 import { loadConfig, type AgyMode, type ThinkingTier } from "./config.js";
 import { redactText } from "./redact.js";
 import { acquireBridgeSuppression } from "./mcp-registration.js";
@@ -33,49 +44,6 @@ import { sweepStaleWebAgents, webAgentsRoot } from "./web-tools.js";
 
 // --- Constants -------------------------------------------------------------
 
-const DEFAULT_TIMEOUT_MIN = 10;
-const GRACE_AFTER_TIMEOUT_MS = 5000;
-const STATUS_INTERVAL_MS = 1000;
-const STATUS_TAIL_CHARS = 160;
-
-// renderCall / renderResult preview limits (match pi-claude-bridge).
-const PREVIEW_MAX_CHARS = 1000;
-const PREVIEW_MAX_LINES = 6;
-const DISCOVERY_POLL_ATTEMPTS = 5;
-const DISCOVERY_POLL_MS = 100;
-
-// Per-family fallback tier when none is specified and no config default.
-const FAMILY_DEFAULT_TIER: Record<Family, ThinkingTier> = {
-	flash: "medium",
-	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.
-// Live catalog entries win on case-insensitive full-string equality; the
-// overlay resolves the alias when agy doesn't list it. Names are agy's stable
-// slugs (the same ids `agy models` prints and `--model` accepts). Claude ships
-// tiered like Gemini now, so the overlay carries the full tier spread.
-const STATIC_ALIAS_OVERLAY: ReadonlyArray<ModelEntry> = [
-	{ full: "claude-sonnet-5-5-low", family: "other", version: null, tier: "low" },
-	{ full: "claude-sonnet-5-5-medium", family: "other", version: null, tier: "medium" },
-	{ full: "claude-sonnet-5-5-high", family: "other", version: null, tier: "high" },
-	{ full: "claude-opus-5-5-low", family: "other", version: null, tier: "low" },
-	{ full: "claude-opus-5-5-medium", family: "other", version: null, tier: "medium" },
-	{ full: "claude-opus-5-5-high", family: "other", version: null, tier: "high" },
-];
-const STATIC_SHORT_ALIAS: ReadonlyMap<string, string> = new Map([
-	["sonnet", "claude-sonnet-5-5"],
-	["opus", "claude-opus-5-5"],
-]);
-
-// agy conversation ids are UUID DB-stems. First char must be alphanumeric so a
-// leading-dash value can't misbind on agy's arg parser; hyphens allowed in the
-// body (real UUIDs contain them).
-const CONV_ID_RE = /^[A-Za-z0-9][A-Za-z0-9-]{0,127}$/;
-
 const AGY_DESCRIPTION = `Delegate a self-contained sub-task to Google Antigravity. agy is the CLI for Gemini, so this tool is reached under three equivalent names the user may use interchangeably: **gemini**, **antigravity**, and **agy**. When the user says "ask gemini", "ask antigravity", "ask agy", or otherwise refers to any of these, call THIS tool. agy runs its OWN tool loop: it can read, write, edit, and execute inside the workspace, then returns its final answer. Use for a second opinion from a different model family, Gemini-specific reasoning, or isolated sub-tasks you do not need to drive step-by-step. Provide a complete, self-contained task description; agy will not see this conversation.
 
 TWO MODES (you choose):
@@ -93,223 +61,28 @@ THINKING LEVEL (params: thinking, effort - SYNONYMS for one knob):
 - Values (pi vocabulary): minimal|low|medium|high|xhigh|max. Clamped to agy's low|medium|high; unknown values fall back to low. "peer review on high thinking" -> thinking: "high".
 - An explicit level beats a tier embedded in model ("flash high") and the configured default. Omit both for the configured default.`;
 
-// --- Types -----------------------------------------------------------------
-
-type Family = "flash" | "pro" | "other";
-
-interface ModelEntry {
-	full: string; // exact agy slug, e.g. "gemini-3.6-flash-medium"
-	family: Family;
-	version: string | null; // "3.6"
-	tier: ThinkingTier | null;
-}
-
-/** Argv-facing model resolution: the exact --model slug plus an optional
- *  --effort tier. Gemini bases split the tier out (the base slug alone is
- *  invalid without --effort); fixed-thinking families keep agy's exact slug
- *  and carry no effort. */
-interface ResolvedModel {
-	model: string;
-	effort?: ThinkingTier;
-}
-
-// --- Version helpers -------------------------------------------------------
-
-/** Descending numeric version compare (3.10 > 3.9, not lexical). */
-function compareVersionsDesc(a: string, b: string): number {
-	const pa = a.split(".").map(Number);
-	const pb = b.split(".").map(Number);
-	for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
-		const da = pa[i] ?? 0;
-		const db = pb[i] ?? 0;
-		if (da !== db) return db - da;
-	}
-	return 0;
-}
-
-// --- Model catalog ---------------------------------------------------------
-
-function mergeCatalog(live: ModelEntry[]): ModelEntry[] {
-	const seen = new Set(live.map((e) => e.full.toLowerCase()));
-	const merged = [...live];
-	for (const entry of STATIC_ALIAS_OVERLAY) {
-		if (!seen.has(entry.full.toLowerCase())) merged.push(entry);
-	}
-	return merged;
-}
-
-function parseModelLine(line: string): ModelEntry | null {
-	// agy prints TWO columns: "<slug>  <display label>". --model takes only the
-	// slug (col 1), so split it off; the label is display-only and must never
-	// reach --model. A bare-slug line (no whitespace) splits to itself.
-	const full = line.trim().split(/\s+/)[0] ?? "";
-	if (!full) return null;
-	const lower = full.toLowerCase();
-	const family: Family = lower.includes("flash")
-		? "flash"
-		: lower.includes("pro")
-			? "pro"
-			: "other";
-	const versionMatch = lower.match(/(\d+\.\d+)/);
-	const version = versionMatch ? versionMatch[1] : null;
-	const tierMatch = lower.match(/-(low|medium|high)$/);
-	const tier = tierMatch ? (tierMatch[1] as ThinkingTier) : null;
-	return { full, family, version, tier };
-}
-
-function nearestTier(available: ThinkingTier[], preferred: ThinkingTier): ThinkingTier {
-	if (available.includes(preferred)) return preferred;
-	const sorted = [...available].sort((a, b) => {
-		const da = Math.abs(TIER_RANK[a] - TIER_RANK[preferred]);
-		const db = Math.abs(TIER_RANK[b] - TIER_RANK[preferred]);
-		return da !== db ? da - db : TIER_RANK[b] - TIER_RANK[a];
-	});
-	return sorted[0] ?? preferred;
-}
-
-/** Build the argv-facing resolution from a picked catalog entry. Gemini and
- *  Claude bases (slugs starting "gemini-"/"claude-") accept a separate
- *  --effort, so split the tier suffix out of the slug: the base alone
- *  (claude-sonnet-5-5) is what --model wants, and the tier goes to --effort
- *  (agy rejects a bare base: "requires --effort"). Only unverified families
- *  keep agy's exact slug whole, so an unknown suffix can never trigger an
- *  unsupported --effort. */
-function toResolved(full: string, tier: ThinkingTier | null): ResolvedModel {
-	if (tier && /^(gemini|claude)-/.test(full.toLowerCase())) {
-		return { model: full.replace(/-(low|medium|high)$/, ""), effort: tier };
-	}
-	return { model: full };
-}
-
-/** Resolve a tiered base id - a short-alias target ("claude-sonnet-5-5") or a
- *  bare base slug the provider itself advertises - to the catalog variant
- *  nearest the requested tier. A bare base alone is invalid upstream
- *  ("requires --effort"), so the pick always rides the split in toResolved;
- *  with no variants in the catalog, the overlay/exact entry or the raw base
- *  passes through unchanged. */
-function resolveTieredBase(
-	base: string,
-	entries: ModelEntry[],
-	defaultThinking: ThinkingTier,
-	preferredTier: ThinkingTier | undefined,
-): ResolvedModel {
-	const needle = base.toLowerCase();
-	const variants = entries.filter((e) => e.full.toLowerCase().startsWith(`${needle}-`));
-	if (variants.length > 0) {
-		const tiers = variants.map((e) => e.tier).filter((t): t is ThinkingTier => t !== null);
-		const preferred =
-			preferredTier ??
-			(tiers.includes(defaultThinking) ? defaultThinking : FAMILY_DEFAULT_TIER.other);
-		const chosen = nearestTier(tiers, preferred);
-		const picked = variants.find((e) => e.tier === chosen) ?? variants[0];
-		return toResolved(picked.full, picked.tier);
-	}
-	const fromCatalog = entries.find((e) => e.full.toLowerCase() === needle);
-	return toResolved(fromCatalog?.full ?? base, fromCatalog?.tier ?? null);
-}
-
-/** Resolve a friendly alias / partial name to an argv-facing {model, effort?}.
- *  Returns null only when the family is unrecognized; the caller then passes
- *  the raw input straight to agy. */
-export function resolveModel(
-	input: string,
-	entries: ModelEntry[],
-	defaultThinking: ThinkingTier,
-	/** Explicit thinking param (thinking/effort). Beats a tier embedded in
-	 *  the alias ("flash high") and the configured default; clamped to the
-	 *  family's real tiers, ignored for fixed-thinking families. */
-	preferredTier?: ThinkingTier,
-): ResolvedModel | null {
-	const lower = input.toLowerCase().trim();
-
-	const exact = entries.find((e) => e.full.toLowerCase() === lower);
-	if (exact) return toResolved(exact.full, exact.tier);
-
-	if (STATIC_SHORT_ALIAS.has(lower)) {
-		return resolveTieredBase(
-			STATIC_SHORT_ALIAS.get(lower) as string,
-			entries,
-			defaultThinking,
-			preferredTier,
-		);
-	}
-
-	let family: Family | null = lower.includes("flash")
-		? "flash"
-		: lower.includes("pro")
-			? "pro"
-			: null;
-	const versionMatch = lower.match(/(\d+\.\d+)/);
-	const version = versionMatch ? versionMatch[1] : null;
-	const tierMatch = lower.match(/\b(low|medium|high)\b/);
-	const tier = tierMatch ? (tierMatch[1] as ThinkingTier) : null;
-
-	if (!family && (/gemini/.test(lower) || lower === "" || lower === "default")) {
-		family = "flash";
-	}
-	if (!family) {
-		// A bare base slug the provider itself advertises ("claude-sonnet-5-5",
-		// the id behind the antigravity/ entry in pi's picker) is invalid
-		// upstream without an effort: resolve it to the nearest tier variant
-		// exactly like the short aliases.
-		if (
-			entries.some((e) => e.full.toLowerCase().startsWith(`${lower}-`)) ||
-			entries.some((e) => e.full.toLowerCase() === lower)
-		) {
-			return resolveTieredBase(lower, entries, defaultThinking, preferredTier);
-		}
-		return null;
-	}
-
-	let candidates = entries.filter((e) => e.family === family);
-	if (candidates.length === 0) return null;
-
-	if (version) {
-		const versioned = candidates.filter((e) => e.version === version);
-		if (versioned.length > 0) candidates = versioned;
-	} else {
-		const aliases = candidates.filter((e) => e.version === null);
-		if (aliases.length > 0) {
-			candidates = aliases;
-		} else {
-			const versions = candidates
-				.map((e) => e.version)
-				.filter((v): v is string => v !== null)
-				.sort(compareVersionsDesc);
-			if (versions.length > 0) {
-				const top = versions[0];
-				const latest = candidates.filter((e) => e.version === top);
-				if (latest.length > 0) candidates = latest;
-			}
-		}
-	}
-
-	const familyTiers = new Set(
-		candidates.map((e) => e.tier).filter((t): t is ThinkingTier => t !== null),
-	);
-	if (familyTiers.size === 0) return toResolved(candidates[0].full, null);
-
-	const preferred =
-		preferredTier ??
-		tier ??
-		(familyTiers.has(defaultThinking) ? defaultThinking : FAMILY_DEFAULT_TIER[family]);
-	const chosenTier = nearestTier([...familyTiers], preferred);
-	const picked = candidates.find((e) => e.tier === chosenTier) ?? candidates[0];
-	return toResolved(picked.full, picked.tier);
-}
+const DEFAULT_TIMEOUT_MIN = 10;
+const GRACE_AFTER_TIMEOUT_MS = 5000;
+const STATUS_INTERVAL_MS = 1000;
+const STATUS_TAIL_CHARS = 160;
 
-/** Families dropped outright even while `agy models` still lists them (same
- *  policy as models.ts HIDDEN_FAMILY_RE): never offered, never resolved. */
-const HIDDEN_FAMILY_RE = /^gpt-oss-/;
+// renderCall / renderResult preview limits (match pi-claude-bridge).
+const PREVIEW_MAX_CHARS = 1000;
+const PREVIEW_MAX_LINES = 6;
+const DISCOVERY_POLL_ATTEMPTS = 5;
+const DISCOVERY_POLL_MS = 100;
 
-/** Parse raw `agy models` text into tool-catalog entries (all families, plus
- *  the static sonnet/opus overlay). Pure: no spawn. */
+/** Parse raw `agy models` text into tool-catalog entries: the shared line
+ *  grammar + hidden-family filter + static sonnet/opus overlay. Pure: no
+ *  spawn. */
 export function toolModelsFromRaw(raw: string): ModelEntry[] {
 	return mergeCatalog(
-		raw
-			.split("\n")
-			.map(parseModelLine)
-			.filter((e): e is ModelEntry => e !== null && !HIDDEN_FAMILY_RE.test(e.full)),
+		filterHiddenModels(
+			raw
+				.split("\n")
+				.map(parseModelLine)
+				.filter((e): e is ModelEntry => e !== null),
+		),
 	);
 }
 
@@ -325,56 +98,11 @@ function extraArgs(): string[] {
 	return raw ? raw.split(/\s+/).filter((s) => s.length > 0) : [];
 }
 
-// --- Prompt assembly -------------------------------------------------------
-
-/** Guard for plan runs backed by the restricted reviewer agent. Difference
- *  to PLAN_HEADLESS_GUARD: read commands are the intended analysis path
- *  here, so the guard forbids FILE MUTATION - by tool or by shell - and
- *  keeps the answer-from-material discipline. The agent is a damper, not
- *  enforcement (upstream #1181); a headless command attempt can still be
- *  auto-denied, which ends the run, so the guard steers toward view_file
- *  and staged material first. */
-export const AGENT_REVIEW_GUARD = [
-	"",
-	"--- Review constraints ---",
-	"- Read-only review. Do not create, modify, or delete any files, including through shell commands (no redirects, tee, rm, mv, git commit).",
-	"- Prefer the staged material and view_file for reading. If you run a read-only command (git log, git diff, rg, ls) and it comes back denied, the run ends without an answer: state what you could not check instead of retrying commands.",
-	"- Work from the material provided in this prompt; if information you need is missing, state exactly what is missing in your answer.",
-].join("\n");
-
-/** Appended to every headless plan-mode prompt. `agy -p` cannot answer
- *  permission prompts: in plan mode a run_command attempt is soft-denied and
- *  the turn ends AT the denial (exit 0, empty stdout, notice only on stderr -
- *  the empty-output branch in execute). Probed 2026-09-28 on agy 1.2.12:
- *  allow rules ARE consulted (a verbatim allow-listed `git log` runs), but
- *  --sandbox does NOT relax the command gate, so the only input every user
- *  is guaranteed is the prompt itself. The guard steers the model to answer
- *  from that material. accept-edits runs keep their tools and never get it. */
-export const PLAN_HEADLESS_GUARD = [
-	"",
-	"--- Headless session constraints ---",
-	"- Do not run shell commands. Command execution is denied in this session, and any attempt ends the session immediately with no answer.",
-	"- Work only from the material provided in this prompt.",
-	"- If information you need is missing, state exactly what is missing in your answer instead of trying to fetch it.",
-].join("\n");
-
-/** Assemble the prompt sent to agy: digest marker first (existing behavior),
- *  then the caller's prompt, then the plan-mode guard last - the position
- *  the model reads with the most recency. No user-config mutation: this is
- *  the only plan-mode lever the tool itself owns. */
-export function buildFinalPrompt(
-	prompt: string,
-	mode: AgyMode,
-	digest: boolean,
-	/** True when the restricted reviewer agent is staged: its empty edit
-	 *  toolset is a damper (the CLI does not enforce review-only, upstream
-	 *  #1181), so the prompt may ALLOW read-only commands. */
-	agentDamper = false,
-): string {
-	let out = digest ? `(Use compact digests, not full file contents.)\n${prompt}` : prompt;
-	if (mode === "plan") out += agentDamper ? AGENT_REVIEW_GUARD : PLAN_HEADLESS_GUARD;
-	return out;
-}
+// --- Prompt assembly: shared peer adapter ----------------------------------
+// PLAN_HEADLESS_GUARD / AGENT_REVIEW_GUARD / buildFinalPrompt live in
+// pi-ask-shared (peers/antigravity.ts); the bridge inherits the identical
+// guard discipline. Re-exported for the bridge's own tests.
+export { AGENT_REVIEW_GUARD, buildFinalPrompt, PLAN_HEADLESS_GUARD } from "@estebanforge/pi-ask-shared";
 
 // --- Plan-mode reviewer agent ----------------------------------------------
 
@@ -505,7 +233,7 @@ export async function registerAskAntigravityTool(
 				}),
 			),
 			timeoutMinutes: Type.Optional(
-				Type.Number({ description: `Hard cap on the agy run in minutes. Default ${DEFAULT_TIMEOUT_MIN}.` }),
+				Type.Number({ description: `Hard cap on the agy run in minutes. Default ${DEFAULT_TIMEOUT_MIN}. Fractional minutes allowed; must be above 0 and at most ${MAX_TIMEOUT_MINUTES}. The prompt carries a matching [TIME BUDGET] notice.` }),
 			),
 			includeContext: Type.Optional(
 				Type.Boolean({
@@ -527,7 +255,7 @@ export async function registerAskAntigravityTool(
 			const requestedModel = (args.model as string | undefined)?.trim() || cfg.defaultModel;
 			const thinkingArg = (args.thinking as string | undefined) ?? (args.effort as string | undefined);
 			const resolved =
-				resolveModel(
+				resolveAgyModel(
 					requestedModel,
 					entries,
 					cfg.defaultThinking,
@@ -674,7 +402,7 @@ export async function registerAskAntigravityTool(
 				? toAgyEffort(thinkingArg as ThinkingLevel, AGY_EFFORT_ORDER)
 				: undefined;
 			const resolved =
-				resolveModel(requestedModel, entries, config.defaultThinking, preferredTier) ?? {
+				resolveAgyModel(requestedModel, entries, config.defaultThinking, preferredTier) ?? {
 					model: requestedModel,
 				};
 
@@ -696,11 +424,19 @@ export async function registerAskAntigravityTool(
 			}
 
 			const timeoutMin = params.timeoutMinutes ?? DEFAULT_TIMEOUT_MIN;
+			if (!(timeoutMin > 0 && Number.isFinite(timeoutMin) && timeoutMin <= MAX_TIMEOUT_MINUTES)) {
+				// timeoutMinutes: 0 would arm runProcess's watchdog with a 0ms
+				// timeout (Node clamps to 1ms) and kill the peer instantly.
+				return {
+					content: [{ type: "text", text: `timeoutMinutes must be a positive number of minutes up to ${MAX_TIMEOUT_MINUTES} (for example 0.5 for 30 seconds).` }],
+					details: emptyDetails(requestedModel, resolved.model),
+				};
+			}
 
 			const rawConvId = params.conversationId;
 			const isContinuation =
 				typeof rawConvId === "string" && rawConvId.length > 0 && CONV_ID_RE.test(rawConvId);
-			const snapshot = isContinuation ? null : snapshotConversations();
+			const snapshot = isContinuation ? null : snapshotConversations(CONVERSATIONS_DIR);
 
 			const mode: AgyMode =
 				(params.mode as AgyMode | undefined) ?? (config.mode === "plan" ? "plan" : "accept-edits");
@@ -721,8 +457,13 @@ export async function registerAskAntigravityTool(
 			}
 			const useDigest: boolean =
 				typeof params.digest === "boolean" ? params.digest : mode === "plan";
+			// Budget notice into the prompt BEFORE buildFinalPrompt: the plan-mode
+			// guard banners must stay the final text (last-read recency), so the
+			// notice can't go after them. The builder itself stays notice-free so
+			// callers can't double-wrap.
+			const budget = buildTimeBudgetNotice(timeoutMin * 60_000);
 			const finalPrompt: string = buildFinalPrompt(
-				params.prompt,
+				budget ? `${params.prompt}\n\n${budget}` : params.prompt,
 				mode,
 				useDigest,
 				reviewerAgent !== null,
@@ -751,45 +492,27 @@ export async function registerAskAntigravityTool(
 				? `The full pi conversation context (as markdown) is at: ${contextFile}\nRead that file first for context, then do the task below.\n\n---\n\n${finalPrompt}`
 				: finalPrompt;
 
-			const args: string[] = ["--add-dir", cwd];
 			log?.(
 				"ask-start",
 				{ model: resolved.model, thinking: resolved.effort ?? config.defaultThinking, mode, digest: useDigest, continue: isContinuation, timeoutMin },
 				"info",
 			);
-			const extraRaw = extraArgs();
-			// Fail-closed on every plan run: AGY_EXTRA_ARGS lands before the mode
-			// flags, so an env-injected skip flag would re-arm exactly what the
-			// never-flag-on-plan rule withholds (upstream #1181: an auto-approved
-			// plan run is write-capable). The reviewer agent is a damper, not a
-			// license for the flag.
-			const extra =
-				mode === "plan"
-					? extraRaw.filter((a) => !a.startsWith("--dangerously-skip-permissions"))
-					: extraRaw;
-			if (extra.length) args.push(...extra);
-			if (resolved.model) args.push("--model", resolved.model);
-			if (resolved.effort) args.push("--effort", resolved.effort);
-			args.push("--mode", mode);
-			if (reviewerAgent) args.push("--agent", reviewerAgent.name);
-			// Honor the shared permissions setting (same knob as the provider).
-			// accept-edits: the flag keeps commands from hanging on an
-			// unanswerable prompt in -p mode. Plan runs NEVER get the flag: it
-			// auto-approves every permission request, and the CLI does not gate
-			// writes under plan mode (upstream
-			// google-antigravity/antigravity-cli#1181, probed 2026-10-07), so an
-			// auto-approved plan run is a write-capable run. The reviewer agent's
-			// toolset is a damper, not a guarantee; the 2026-09-28 "safe with the
-			// restricted toolset" probe predates the #1181 evidence. Without the
-			// flag, command attempts fail visibly (headless auto-deny) instead of
-			// running approved.
-			if (config.skipPermissions !== false && mode !== "plan") {
-				args.push("--dangerously-skip-permissions");
-			}
-			if (isContinuation) args.push("--conversation", rawConvId as string);
-			args.push("--print-timeout", `${timeoutMin}m`);
-			if (contextFile) args.push("--add-dir", askContextDir());
-			args.push("-p", effectivePrompt);
+			// Build argv via the shared peer adapter (see buildAgyArgs there for
+			// the flag-order contract and the fail-closed plan-run rules). The
+			// bridge's permissions gate is truthy (`!== false`), so an unset
+			// config counts as enabled - same knob as the provider.
+			const args = buildAgyArgs({
+				cwd,
+				resolved,
+				mode,
+				reviewerAgentName: reviewerAgent?.name ?? null,
+				skipPermissions: config.skipPermissions !== false,
+				conversationId: isContinuation ? (rawConvId as string) : null,
+				timeoutMinutes: timeoutMin,
+				addDirs: contextFile ? [askContextDir()] : [],
+				extraArgs: extraArgs(),
+				prompt: effectivePrompt,
+			});
 
 			const details: AgyDetails = {
 				model: requestedModel,

package/src/provider.ts

@@ -433,6 +433,14 @@ export interface PollView {
 	isError?: boolean;
 	reason?: string;
 	images?: Array<{ data: string; mimeType: string }>;
+	/** A terminal result the model already received via a poll. Set only by
+	 *  markDelivered (the real poll path); poll() stays pure so internal
+	 *  peeks (escalatedNames) never mark. */
+	delivered?: boolean;
+	/** The agy conversation this call belongs to. Stamped at turn end so an
+	 *  unpolled result can be re-delivered to the right conversation
+	 *  (first-turn parks never reach the provider's store.set). */
+	conversationId?: string;
 }
 
 /** Escalated bridge calls. Bounded: past the cap, oldest settled entries
@@ -443,8 +451,11 @@ export class EscalationRegistry {
 		// Soft cap: only settled entries evict. Evicting a RUNNING call would
 		// strand its result (settle becomes a no-op, poll reports unknown), so
 		// saturating the cap with in-flight calls grows the map instead.
+		// Delivered entries evict first: an undelivered result still has a
+		// recovery path (redelivery), a delivered one only serves late polls.
 		while (this.#calls.size > MAX_PARK_TOMBSTONES) {
-			const victim = [...this.#calls.entries()].find(([, e]) => e.state !== "running")?.[0];
+			const settled = [...this.#calls.entries()].filter(([, e]) => e.state !== "running");
+			const victim = (settled.find(([, e]) => e.delivered) ?? settled[0])?.[0];
 			if (victim === undefined) break;
 			this.#calls.delete(victim);
 		}
@@ -473,6 +484,63 @@ export class EscalationRegistry {
 		const e = this.#calls.get(callId);
 		return e ? { ...e } : undefined;
 	}
+
+	/** Record that the model received this terminal result (the real poll
+	 *  path calls this when the view is not running). Running entries and
+	 *  unknown ids are a no-op. */
+	markDelivered(callId: string): boolean {
+		const e = this.#calls.get(callId);
+		if (!e || e.state === "running") return false;
+		e.delivered = true;
+		return true;
+	}
+
+	/** Single-use claim of a done-but-undelivered result: returns the view
+	 *  and marks it delivered in one step, so a later pass can never deliver
+	 *  it twice. The entry stays pollable for a late model poll. Failed
+	 *  escalations are excluded: their pending entry is gone, so the
+	 *  tombstone path is their single delivery channel. */
+	claimUndelivered(callId: string): (PollView & { callId: string }) | undefined {
+		const e = this.#calls.get(callId);
+		if (!e || e.state !== "done" || e.delivered) return undefined;
+		e.delivered = true;
+		return { ...e, callId };
+	}
+
+	/** Registry-wide sweep: claim every done-but-undelivered result. A
+	 *  toolResult is consumed by its own pass (resolve deletes the pending
+	 *  entry), so a strand that survives its first pass can only be found
+	 *  here, not in a later pass's results. Failed escalations stay with the
+	 *  tombstone path. */
+	claimAllUndelivered(): Array<PollView & { callId: string }> {
+		const out: Array<PollView & { callId: string }> = [];
+		for (const [callId, e] of this.#calls) {
+			const claimed = e.state === "done" && !e.delivered ? { ...e, callId } : undefined;
+			if (claimed) {
+				e.delivered = true;
+				out.push(claimed);
+			}
+		}
+		return out;
+	}
+
+	/** Release a claim whose delivery failed to start (driver.run threw): the
+	 *  result returns to the undelivered pool for the next recovery pass. */
+	unclaim(callId: string): void {
+		const e = this.#calls.get(callId);
+		if (e && e.state === "done") e.delivered = false;
+	}
+
+	/** Stamp every running escalation with the ended turn's conversation id
+	 *  (extensions fire this from onTurnEnd). First stamp wins: the ended
+	 *  turn is the conversation the call was made in; a later turn-end (the
+	 *  call can outlive several turns while a human answers) must not
+	 *  re-route the delivery. Entries that escalate later stay unstamped. */
+	stampConversation(conversationId: string): void {
+		for (const e of this.#calls.values()) {
+			if (e.state === "running") e.conversationId ??= conversationId;
+		}
+	}
 }
 
 export function formatEscalatedAck(e: BridgeEscalation): BridgeCallResultShape {
@@ -483,7 +551,7 @@ export function formatEscalatedAck(e: BridgeEscalation): BridgeCallResultShape {
 				text: [
 					`STILL RUNNING: the pi tool "${e.name}" has not finished yet.`,
 					`Call ${POLL_TOOL_NAME} with callId "${e.callId}" to get the result. Poll again if it still reports running; you may do other work between polls.`,
-					"This is not an error and nothing is lost: if you stop polling, the bridge re-delivers the result in a later turn.",
+					"Do NOT end your turn while this call is unresolved: keep polling until it reports done or failed. Ending the turn strands the result.",
 				].join("\n"),
 			},
 		],
@@ -621,6 +689,36 @@ export class ToolRoundTrips {
 		return this.#escalations.poll(callId);
 	}
 
+	/** Mark a terminal escalated result as received by the model. Only the
+	 *  real poll path (extensions) calls this; poll() stays pure. */
+	markDelivered(callId: string): boolean {
+		return this.#escalations.markDelivered(callId);
+	}
+
+	/** Single-use claim of a settled-but-undelivered escalated result (the
+	 *  model ended its turn instead of polling). */
+	claimUndelivered(callId: string): (PollView & { callId: string }) | undefined {
+		return this.#escalations.claimUndelivered(callId);
+	}
+
+	/** Registry-wide sweep for done-but-undelivered results: a toolResult is
+	 *  consumed by its own pass, so multi-pass strands are only findable
+	 *  here. */
+	claimAllUndelivered(): Array<PollView & { callId: string }> {
+		return this.#escalations.claimAllUndelivered();
+	}
+
+	/** Release a claim whose delivery failed to start. */
+	unclaim(callId: string): void {
+		this.#escalations.unclaim(callId);
+	}
+
+	/** Stamp running escalations with the ended turn's conversation id so an
+	 *  unpolled result can be re-delivered to the right conversation. */
+	stampConversation(conversationId: string): void {
+		this.#escalations.stampConversation(conversationId);
+	}
+
 	/** Wire the approval park (mcp-server handle.approvals). The extension
 	 *  assigns this AFTER the shadow tools are registered; see onApproval. */
 	set approvalPark(api: ApprovalParkApi | undefined) {
@@ -902,6 +1000,9 @@ export function collectToolResults(
 }
 
 export interface LateToolResult {
+	/** Escalated results only: the registry callId, so a failed delivery can
+	 *  unclaim it. Tombstone-borne results have none (already consumed). */
+	callId?: string;
 	name: string;
 	reason: string;
 	text: string;
@@ -909,12 +1010,12 @@ export interface LateToolResult {
 }
 
 /** Frame late tool results so agy treats them as the results its bridge calls
- *  never received (the round-trip died while the pi tool was still running,
- *  e.g. agy's ~180s MCP client timeout on tools/call). */
+ *  never received: a park whose round-trip died while the pi tool ran, or an
+ *  escalated result the model never polled. The reason carries the framing. */
 export function buildLateResultPrompt(late: LateToolResult[], userPrompt?: string): string {
 	const blocks = late.map((r) =>
 		[
-			`pi tool "${r.name}": the bridge round-trip expired before this result reached you (${r.reason}).`,
+			`pi tool "${r.name}": ${r.reason}.`,
 			r.isError ? "The tool reported an error:" : "Result:",
 			r.text.trim() || "(no output)",
 		].join("\n"),
@@ -1194,28 +1295,67 @@ async function runTurnDriver(
 		deps.log?.("late-result-deferred", { count: deps.roundTrips.deadIds.length }, "info");
 	}
 
-	let handle: TurnHandle;
+	// Stranded escalated results: done but never delivered — the model ended
+	// its turn instead of polling bridge_poll_result (observed live 2026-10:
+	// the model stopped after the STILL RUNNING ack on an ask_user_question
+	// and the user's answer stranded in the registry). The sweep is
+	// registry-wide: a toolResult is consumed by its own pass, so a strand
+	// that survives its first pass is only findable here. Claims are
+	// single-use; entries stay pollable for a late model poll.
+	let redeliveryConversation: string | undefined;
+	const collectStranded = (): LateToolResult[] =>
+		deps.roundTrips.claimAllUndelivered().map((view) => {
+			redeliveryConversation ??= view.conversationId;
+			deps.log?.("escalated-redelivery", { tool: view.name, callId: view.callId }, "info");
+			return {
+				callId: view.callId,
+				name: view.name,
+				reason: "you never received this result: you ended your turn without calling bridge_poll_result",
+				text: view.text ?? "(no output)",
+				isError: view.isError ?? false,
+			};
+		});
+
+	const entry = entries.find((e) => e.id === model.id) ?? null;
+	const agyModel = entry?.full ?? model.id;
+	const effort = entry?.efforts?.length ? toAgyEffort(options?.reasoning, entry.efforts) : undefined;
+
+	let handle: TurnHandle | undefined;
 	// Name of the carrier agent staged for THIS turn's fresh conversation, if
 	// any. Recorded into stagedAgentByConversation once the outcome binds the
 	// conversation id, so later gate-closed turns pass the same agent.
 	let stagedAgentName: string | undefined;
-	if (isContinuation) {
-		const active = deps.driver.reentry();
-		if (!active) {
-			// Escalated calls have no turn to re-enter BY DESIGN: agy already
-			// got the poll handle and the result lives in the registry. Settle
-			// quietly instead of erroring the turn.
-			if (escalatedNames.length > 0) {
-				appendText(stream, blocks, `[bridge] ${escalatedNames.join(", ")} finished; the result is available via ${POLL_TOOL_NAME}.`);
-				finalize(stream, blocks, "stop");
+	const active = isContinuation ? deps.driver.reentry() : null;
+	if (active) {
+		handle = active;
+	} else {
+		// Dead turn: claim NOW (single-use). A live turn claims after outcome
+		// instead — claiming here would eat the post-outcome recovery.
+		late.push(...collectStranded());
+		if (isContinuation && late.length === 0) {
+			if (escalatedNames.length === 0) {
+				deps.log?.("turn-error", { reason: "tool-result-no-active-turn" }, "warn");
+				finalize(stream, blocks, "error", "tool result arrived but no antigravity turn is running");
 				return;
 			}
-			deps.log?.("turn-error", { reason: "tool-result-no-active-turn" }, "warn");
-			finalize(stream, blocks, "error", "tool result arrived but no antigravity turn is running");
+			// Escalated results, all already delivered through polls: the model
+			// has them in context. Settle quietly instead of erroring.
+			appendText(stream, blocks, `[bridge] ${escalatedNames.join(", ")} finished; the result is available via ${POLL_TOOL_NAME}.`);
+			finalize(stream, blocks, "stop");
 			return;
 		}
-		handle = active;
-	} else {
+		if (isContinuation && late.length > 0 && redeliveryConversation === undefined && !existing?.conversationId) {
+			// The owning turn ended before binding a conversation (no stamp, no
+			// store record): a context-free late prompt would hit a brand-new
+			// agy conversation that never asked the question. Release the
+			// claims and settle quietly; the result stays pollable and a later
+			// pass with a bound conversation can still sweep it.
+			for (const l of late) if (l.callId) deps.roundTrips.unclaim(l.callId);
+			appendText(stream, blocks, `[bridge] ${escalatedNames.join(", ")} finished, but no conversation is bound to re-deliver into; the result stays available via ${POLL_TOOL_NAME}.`);
+			finalize(stream, blocks, "stop");
+			return;
+		}
+		// Fresh pass, or a stranded escalated result being re-delivered.
 		const prompt = extractUserPrompt(context);
 		const images = extractImages(context);
 		// An image-only message (no text) is valid on the ACP engine; only fail
@@ -1226,9 +1366,6 @@ async function runTurnDriver(
 			finalize(stream, blocks, "error", "No user message to send to agy.");
 			return;
 		}
-		const entry = entries.find((e) => e.id === model.id) ?? null;
-		const agyModel = entry?.full ?? model.id;
-		const effort = entry?.efforts?.length ? toAgyEffort(options?.reasoning, entry.efforts) : undefined;
 		const watermark = existing?.lastMessageCount ?? 0;
 		// Late turns re-open the conversation with a synthetic prompt; the digest
 		// would re-send context agy already holds, so skip it.
@@ -1293,7 +1430,7 @@ async function runTurnDriver(
 				skipPermissions: config.skipPermissions,
 				timeoutMin: config.turnTimeoutMin,
 				inactivityMin: config.inactivityTimeoutMin,
-				conversationId: existing?.conversationId ?? null,
+				conversationId: redeliveryConversation ?? existing?.conversationId ?? null,
 				prompt: fullPrompt,
 				images: images.length > 0 ? images : undefined,
 				agent,
@@ -1307,6 +1444,10 @@ async function runTurnDriver(
 			});
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
+			// Release stranded claims: the delivery never started, so the next
+			// pass must find them undelivered (tombstone-borne items have no
+			// callId and stay consumed, as before).
+			for (const l of late) if (l.callId) deps.roundTrips.unclaim(l.callId);
 			deps.log?.("turn-error", { reason: "driver-start-failed", error: msg }, "error");
 			finalize(stream, blocks, "error", `agy failed to start: ${msg}`);
 			return;
@@ -1324,13 +1465,16 @@ async function runTurnDriver(
 		roster: deps.roster,
 	};
 
-	for (;;) {
-		const activity = await handle.next();
-		if (!activity) break;
-		if (consumeActivity(stream, blocks, activity, diffCtx, cwd, feats) === "parked") return;
-	}
+	const drainTurn = async (h: TurnHandle): Promise<"parked" | undefined> => {
+		for (;;) {
+			const activity = await h.next();
+			if (!activity) break;
+			if (consumeActivity(stream, blocks, activity, diffCtx, cwd, feats) === "parked") return "parked";
+		}
+	};
+	if ((await drainTurn(handle)) === "parked") return;
 
-	const outcome = await handle.outcome;
+	let outcome = await handle.outcome;
 	// Issue #2 recovery paths. agy's stream-json prompt path silently drops an
 	// over-cap turn (SUCCESS, empty response, zero usage, NO model step) and a
 	// dropped turn leaves the conversation permanently unresponsive, so both
@@ -1374,6 +1518,43 @@ async function runTurnDriver(
 		);
 		return;
 	}
+	// Gap closer: the result landed while the turn was still live (reentry
+	// above), the turn ended, and the model never polled. Same strand, same
+	// fix: sweep and deliver as a late run in the same conversation. Single
+	// shot: claims are single-use, so a re-delivered strand cannot reappear
+	// here; a late run that parks hands recovery to the next pi pass.
+	if (isContinuation && outcome.status === "OK" && !outcome.aborted) {
+		const more = collectStranded();
+		if (more.length > 0) {
+			const conv = redeliveryConversation ?? outcome.conversationId ?? existing?.conversationId ?? null;
+			deps.log?.("escalated-redelivery-turn", { tools: more.map((s) => s.name), conversation: conv }, "info");
+			try {
+				const lateHandle = await deps.driver.run({
+					cwd,
+					model: agyModel,
+					effort,
+					mode: config.mode,
+					skipPermissions: config.skipPermissions,
+					timeoutMin: config.turnTimeoutMin,
+					inactivityMin: config.inactivityTimeoutMin,
+					conversationId: conv,
+					prompt: buildLateResultPrompt(more),
+					agent: config.agent ?? (conv ? stagedAgentByConversation.get(conv) : undefined),
+					signal: options?.signal,
+				});
+				if ((await drainTurn(lateHandle)) === "parked") return;
+				outcome = await lateHandle.outcome;
+			} catch (err) {
+				// Release the claims so the next pass can retry the delivery.
+				for (const l of more) if (l.callId) deps.roundTrips.unclaim(l.callId);
+				deps.log?.(
+					"turn-error",
+					{ reason: "redelivery-start-failed", error: err instanceof Error ? err.message : String(err) },
+					"error",
+				);
+			}
+		}
+	}
 	if (outcome.conversationId) {
 		// A different id than the stored one means the driver recreated the
 		// conversation under us (ACP session-load fallback, stream-json CLI

package/src/discovery.ts

@@ -1,199 +0,0 @@
-// Discover the agy conversation id that `agy -p` creates but never prints.
-//
-// agy's print mode writes its steps to a fresh SQLite DB at
-// ~/.gemini/antigravity-cli/conversations/<uuid>.db. It does NOT echo the id.
-// The only reliable bind is to snapshot the *.db stems in that dir before
-// spawn, then diff after: exactly one new file = ours. If several appear we
-// refuse to bind (can't tell which is ours)  -  same approach as antigravity-acp
-// (scan.ts), agy-acp (scan.ts), and pi-ask-antigravity.
-//
-// CONCURRENCY: when another agy (or subagent) starts in parallel, more than
-// one new .db can land in the dir during our turn. mtime filtering does NOT
-// disambiguate two *active* concurrent runs (both DBs are >= turn-start), and
-// prompt-content matching is fragile (the user-message step_type 98 payload
-// is undocumented and deeply nested; a field-number shift would silently
-// misbind). The authoritative signal is which candidate .db OUR spawned agy
-// process tree holds open right now  -  resolved via /proc/<pid>/fd on Linux.
-// When that signal is unavailable (no pid, non-Linux, process already exited,
-// or the scan itself is ambiguous) we fail safe to null, preserving the
-// original "refuse to bind" behavior rather than guessing.
-
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-
-/** Default conversations dir. Override with AGY_CONVERSATIONS_DIR. */
-export const CONVERSATIONS_DIR =
-	process.env.AGY_CONVERSATIONS_DIR ||
-	path.join(os.homedir(), ".gemini", "antigravity-cli", "conversations");
-
-/** Snapshot the set of conversation ids (*.db stems) currently on disk.
- *  Empty set (not throw) when the dir is missing  -  agy will create it. */
-export function snapshotConversations(dir: string = CONVERSATIONS_DIR): Set<string> {
-	const out = new Set<string>();
-	let entries: string[];
-	try {
-		entries = fs.readdirSync(dir);
-	} catch {
-		return out;
-	}
-	for (const f of entries) {
-		if (f.endsWith(".db")) out.add(f.slice(0, -3));
-	}
-	return out;
-}
-
-/** Resolve which of the `candidates` DB ids is held open by the process tree
- *  rooted at `rootPid`. Used to disambiguate concurrent agy runs.
- *
- *  Returns the single matching id, or null when none / several are open, when
- *  /proc is unavailable, or when reading fails. Injectable so tests can stub
- *  it without touching the filesystem. */
-export type OpenDbResolver = (
-	rootPid: number,
-	dir: string,
-	candidates: Set<string>,
-) => string | null;
-
-/** Read pid + ppid from /proc/<pid>/stat. Returns null when the entry is gone
- *  (process exited) or unparseable. comm may contain spaces and parens, so we
- *  split on the LAST ')' rather than naively tokenizing. */
-function readProcStat(pid: number): { pid: number; ppid: number } | null {
-	let raw: string;
-	try {
-		raw = fs.readFileSync(`/proc/${pid}/stat`, "utf8");
-	} catch {
-		return null;
-	}
-	const closeParen = raw.lastIndexOf(")");
-	if (closeParen < 0) return null;
-	// After "pid (comm)" come: state ppid pgrp session ...
-	const fields = raw.slice(closeParen + 2).trim().split(/\s+/);
-	const ppid = Number(fields[1]);
-	if (!Number.isFinite(ppid)) return null;
-	return { pid, ppid };
-}
-
-/** Collect rootPid and every descendant pid by walking /proc/<pid>/stat
- *  parent links. Single pass over /proc building a pid->ppid map, then
- *  iterated to closure. */
-function collectDescendants(rootPid: number): Set<number> {
-	const out = new Set<number>([rootPid]);
-	let entries: string[];
-	try {
-		entries = fs.readdirSync("/proc");
-	} catch {
-		return out;
-	}
-	const ppidOf = new Map<number, number>();
-	for (const e of entries) {
-		if (!/^\d+$/.test(e)) continue;
-		const s = readProcStat(Number(e));
-		if (s) ppidOf.set(s.pid, s.ppid);
-	}
-	let changed = true;
-	while (changed) {
-		changed = false;
-		for (const [pid, ppid] of ppidOf) {
-			if (out.has(pid)) continue;
-			if (out.has(ppid)) {
-				out.add(pid);
-				changed = true;
-			}
-		}
-	}
-	return out;
-}
-
-/** Linux /proc implementation of OpenDbResolver. Scans every FD symlink in
- *  the root process's tree and returns the one candidate .db that is open.
- *  Non-authoritative when zero or >1 candidates are open  -  caller fails safe. */
-export const procTreeOpenDbResolver: OpenDbResolver = (rootPid, dir, candidates) => {
-	if (candidates.size <= 1) return null; // nothing to disambiguate
-	if (process.platform !== "linux") return null; // /proc/<pid>/fd is Linux-only
-	const dirResolved = safeRealpath(dir);
-	const tree = collectDescendants(rootPid);
-	const found = new Set<string>();
-	for (const pid of tree) {
-		let fds: string[];
-		try {
-			fds = fs.readdirSync(`/proc/${pid}/fd`);
-		} catch {
-			continue; // process gone or fd dir unreadable
-		}
-		for (const fd of fds) {
-			let target: string;
-			try {
-				target = fs.readlinkSync(`/proc/${pid}/fd/${fd}`);
-			} catch {
-				continue;
-			}
-			// agy also holds .db-wal / .db-shm open; only the base .db matters.
-			const base = path.basename(target);
-			if (!base.endsWith(".db")) continue;
-			if (dirResolved && safeRealpath(path.dirname(target)) !== dirResolved) continue;
-			const id = base.slice(0, -3);
-			if (candidates.has(id)) found.add(id);
-		}
-	}
-	if (found.size === 1) return [...found][0] ?? null;
-	return null;
-};
-
-/** fs.realpathSync that swallows ENOENT (dir may not be canonicalized yet). */
-function safeRealpath(p: string): string | null {
-	try {
-		return fs.realpathSync(p);
-	} catch {
-		return null;
-	}
-}
-
-/** Options for {@link newConversationId}. */
-export interface BindOptions {
-	/** Pid of the spawned agy (the process we want to bind to). When set and
-	 *  multiple candidate DBs exist, the process-tree FD resolver tries to
-	 *  pick ours. Omit to keep the legacy fail-safe behavior. */
-	pid?: number;
-	/** Override resolver (tests). Defaults to the Linux /proc scanner. */
-	resolveOpenDb?: OpenDbResolver;
-	/** Invoked when the snapshot is ambiguous (more than one new DB since
-	 *  `before`) and the resolver could not authoritatively pick ours. Lets a
-	 *  caller bound its retry budget to the genuinely-ambiguous case only, so
-	 *  the ordinary "agy hasn't created its DB yet" wait is not counted
-	 *  against it. Not invoked when there is nothing new yet, or when exactly
-	 *  one new DB binds, or when the resolver succeeds. */
-	onAmbiguous?: () => void;
-}
-
-/** Find the conversation id created since `before`. Returns null when none
- *  appeared, or when several appeared and we cannot authoritatively tie one
- *  to our process. Pass `opts.pid` to enable concurrent-run disambiguation. */
-export function newConversationId(
-	dir: string,
-	before: Set<string>,
-	opts: BindOptions = {},
-): string | null {
-	const after = snapshotConversations(dir);
-	const created = [...after].filter((id) => !before.has(id));
-	if (created.length === 0) return null;
-	if (created.length === 1) return created[0] ?? null;
-	// Ambiguous: more than one new DB since the snapshot. Try to authoritatively
-	// identify ours via the spawned process's open files. Fail safe to null
-	// (refuse to bind) when the resolver can't pick exactly one.
-	if (opts.pid !== undefined) {
-		const resolve = opts.resolveOpenDb ?? procTreeOpenDbResolver;
-		const hit = resolve(opts.pid, dir, new Set(created));
-		if (hit && created.includes(hit)) return hit;
-	}
-	opts.onAmbiguous?.();
-	return null;
-}
-
-/** Path to the DB file for a given conversation id. */
-export function conversationDbPath(
-	id: string,
-	dir: string = CONVERSATIONS_DIR,
-): string {
-	return path.join(dir, `${id}.db`);
-}