@bastani/atomic 0.9.5-alpha.8 → 0.9.5

package/dist/builtin/intercom/lazy-heavy-proxy.ts

@@ -0,0 +1,114 @@
+import type {
+  AgentEndEvent, AgentStartEvent, ExtensionAPI, ExtensionContext, ExtensionHandler,
+  MessageRenderer, ModelSelectEvent, RegisteredCommand, SessionShutdownEvent,
+  SessionStartEvent, ToolDefinition, ToolExecutionEndEvent, ToolExecutionStartEvent,
+  TurnEndEvent, TurnStartEvent,
+} from "@bastani/atomic";
+
+type CapturedCommand = Omit<RegisteredCommand, "name" | "sourceInfo">;
+type CapturedShortcut = Parameters<ExtensionAPI["registerShortcut"]>[1];
+type EventHandler = Parameters<ExtensionAPI["events"]["on"]>[1];
+type EventPayload = Parameters<EventHandler>[0];
+const LIVE_EVENT_SUBSCRIPTIONS = new Set(["pi-intercom:detach-response"]);
+
+export type ToolRenderResultArgs = Parameters<NonNullable<ToolDefinition["renderResult"]>>;
+export type ForwardedEventMap = {
+  session_start: SessionStartEvent;
+  session_shutdown: SessionShutdownEvent;
+  turn_start: TurnStartEvent;
+  turn_end: TurnEndEvent;
+  agent_start: AgentStartEvent;
+  agent_end: AgentEndEvent;
+  tool_execution_start: ToolExecutionStartEvent;
+  tool_execution_end: ToolExecutionEndEvent;
+  model_select: ModelSelectEvent;
+};
+type LazyLifecycleEvent = keyof ForwardedEventMap;
+type ForwardedHandler<K extends LazyLifecycleEvent> = ExtensionHandler<ForwardedEventMap[K]>;
+type ForwardedHandlerMap = { [K in LazyLifecycleEvent]: ForwardedHandler<K>[] };
+type AnyForwardedHandler = { [K in LazyLifecycleEvent]: ForwardedHandler<K> }[LazyLifecycleEvent];
+export interface HeavyRuntimeReadiness {
+  enabled: boolean;
+  awaitAutomaticBrokerReady(): Promise<void>;
+  awaitForegroundBrokerReady(): Promise<void>;
+}
+
+export type CapturedHeavy = {
+  tools: Map<string, ToolDefinition>;
+  commands: Map<string, CapturedCommand>;
+  handlers: ForwardedHandlerMap;
+  shortcuts: Map<string, CapturedShortcut>;
+  eventHandlers: Map<string, EventHandler[]>;
+  runtimeReadiness?: HeavyRuntimeReadiness;
+};
+
+export function createForwardedHandlerMap(): ForwardedHandlerMap {
+  return {
+    session_start: [], session_shutdown: [], turn_start: [], turn_end: [], agent_start: [],
+    agent_end: [], tool_execution_start: [], tool_execution_end: [], model_select: [],
+  };
+}
+
+function addHandler<K extends LazyLifecycleEvent>(captured: CapturedHeavy, event: K, handler: ForwardedHandler<K>): void {
+  captured.handlers[event].push(handler);
+}
+
+function captureForwardedHandler(captured: CapturedHeavy, event: LazyLifecycleEvent, handler: AnyForwardedHandler): void {
+  switch (event) {
+    case "session_start": addHandler(captured, event, handler as ForwardedHandler<"session_start">); return;
+    case "session_shutdown": addHandler(captured, event, handler as ForwardedHandler<"session_shutdown">); return;
+    case "turn_start": addHandler(captured, event, handler as ForwardedHandler<"turn_start">); return;
+    case "turn_end": addHandler(captured, event, handler as ForwardedHandler<"turn_end">); return;
+    case "agent_start": addHandler(captured, event, handler as ForwardedHandler<"agent_start">); return;
+    case "agent_end": addHandler(captured, event, handler as ForwardedHandler<"agent_end">); return;
+    case "tool_execution_start": addHandler(captured, event, handler as ForwardedHandler<"tool_execution_start">); return;
+    case "tool_execution_end": addHandler(captured, event, handler as ForwardedHandler<"tool_execution_end">); return;
+    case "model_select": addHandler(captured, event, handler as ForwardedHandler<"model_select">);
+  }
+}
+
+function addEventHandler(captured: CapturedHeavy, event: string, handler: EventHandler): void {
+  const handlers = captured.eventHandlers.get(event) ?? [];
+  handlers.push(handler);
+  captured.eventHandlers.set(event, handlers);
+}
+
+export async function dispatchHandlers<K extends LazyLifecycleEvent>(
+  captured: CapturedHeavy, eventName: K, event: ForwardedEventMap[K], ctx: ExtensionContext,
+): Promise<void> {
+  for (const handler of captured.handlers[eventName]) await handler(event, ctx);
+}
+
+export async function dispatchEventHandlers(captured: CapturedHeavy, eventName: string, payload: EventPayload): Promise<void> {
+  for (const handler of captured.eventHandlers.get(eventName) ?? []) await handler(payload);
+}
+
+export function createHeavyProxy(pi: ExtensionAPI, captured: CapturedHeavy): ExtensionAPI {
+  return new Proxy(pi, {
+    get(target, prop, receiver) {
+      if (prop === "registerTool") return (tool: ToolDefinition) => captured.tools.set(tool.name, tool);
+      if (prop === "registerCommand") return (name: string, options: CapturedCommand) => captured.commands.set(name, options);
+      if (prop === "on") return (event: LazyLifecycleEvent, handler: AnyForwardedHandler) => captureForwardedHandler(captured, event, handler);
+      if (prop === "registerShortcut") return (shortcut: string, options: CapturedShortcut) => captured.shortcuts.set(shortcut, options);
+      if (prop === "registerMessageRenderer") return (customType: string, renderer: MessageRenderer) => pi.registerMessageRenderer(customType, renderer);
+      if (prop === "events") {
+        return new Proxy(pi.events, {
+          get(eventTarget, eventProp, eventReceiver) {
+            if (eventProp === "on") {
+              return (event: string, handler: EventHandler) => {
+                if (LIVE_EVENT_SUBSCRIPTIONS.has(event)) return pi.events.on(event, handler);
+                addEventHandler(captured, event, handler);
+                return () => {
+                  const handlers = captured.eventHandlers.get(event) ?? [];
+                  captured.eventHandlers.set(event, handlers.filter((candidate) => candidate !== handler));
+                };
+              };
+            }
+            return Reflect.get(eventTarget, eventProp, eventReceiver);
+          },
+        });
+      }
+      return Reflect.get(target, prop, receiver);
+    },
+  }) as ExtensionAPI;
+}

package/dist/builtin/intercom/lazy-subagent-ack.ts

@@ -0,0 +1,20 @@
+import type { ExtensionAPI } from "@bastani/atomic";
+
+const SUBAGENT_RESULT_INTERCOM_EVENT = "subagent:result-intercom";
+const SUBAGENT_RESULT_INTERCOM_DELIVERY_EVENT = "subagent:result-intercom-delivery";
+
+export function rejectLazyResultRelay(
+  pi: ExtensionAPI,
+  eventName: string,
+  payload: unknown,
+  error: unknown,
+): void {
+  if (eventName !== SUBAGENT_RESULT_INTERCOM_EVENT || !payload || typeof payload !== "object") return;
+  const requestId = (payload as { requestId?: unknown }).requestId;
+  if (typeof requestId !== "string") return;
+  pi.events.emit(SUBAGENT_RESULT_INTERCOM_DELIVERY_EVENT, {
+    requestId,
+    delivered: false,
+    error: error instanceof Error ? error.message : String(error),
+  });
+}

package/dist/builtin/intercom/lazy-tool-execution.ts

@@ -0,0 +1,39 @@
+import type { ExtensionCommandContext, ExtensionContext, ToolDefinition } from "@bastani/atomic";
+
+type CommandHandler = (args: string, ctx: ExtensionCommandContext) => void | Promise<void>;
+type ExecutableHeavy = {
+	tools: Map<string, ToolDefinition>;
+	commands: Map<string, { handler: CommandHandler }>;
+};
+
+export type HeavyHandle<THeavy extends ExecutableHeavy> = {
+	heavy: THeavy;
+	assertCurrent: () => void;
+};
+
+export async function executeHeavyTool<THeavy extends ExecutableHeavy>(
+	loadHeavy: (ctx?: ExtensionContext) => Promise<HeavyHandle<THeavy>>,
+	name: string,
+	args: Parameters<NonNullable<ToolDefinition["execute"]>>,
+): Promise<Awaited<ReturnType<NonNullable<ToolDefinition["execute"]>>>> {
+	const handle = await loadHeavy(args[4]);
+	handle.assertCurrent();
+	const tool = handle.heavy.tools.get(name);
+	if (!tool?.execute) throw new Error(`Intercom tool implementation not found: ${name}`);
+	const result = await tool.execute(...args);
+	handle.assertCurrent();
+	return result as Awaited<ReturnType<NonNullable<ToolDefinition["execute"]>>>;
+}
+
+export async function runHeavyCommand<THeavy extends ExecutableHeavy>(
+	loadHeavy: (ctx?: ExtensionContext) => Promise<HeavyHandle<THeavy>>,
+	args: string | undefined,
+	ctx: ExtensionCommandContext,
+): Promise<void> {
+	const handle = await loadHeavy(ctx);
+	handle.assertCurrent();
+	const command = handle.heavy.commands.get("intercom");
+	if (!command) throw new Error("Intercom command implementation not found");
+	await command.handler(args ?? "", ctx);
+	handle.assertCurrent();
+}

package/dist/builtin/intercom/lifecycle-lease.ts

@@ -0,0 +1,51 @@
+export interface LifecycleLease<TShutdown> {
+	readonly id: number;
+	readonly priorCleanup: Promise<void>;
+	retired: boolean;
+	shutdown: TShutdown | null;
+	cleanupBarrier: Promise<void>;
+}
+
+export function createLifecycleLease<TShutdown>(
+	id: number,
+	priorCleanup: Promise<void> = Promise.resolve(),
+): LifecycleLease<TShutdown> {
+	return { id, priorCleanup, retired: false, shutdown: null, cleanupBarrier: priorCleanup };
+}
+
+export function retireLifecycleLease<TShutdown>(lease: LifecycleLease<TShutdown>, shutdown: TShutdown): void {
+	if (lease.retired) return;
+	lease.retired = true;
+	lease.shutdown = shutdown;
+}
+
+export function retainSettledLifecycleCleanup<TShutdown>(
+	lease: LifecycleLease<TShutdown>,
+	cleanup: readonly (Promise<unknown> | null)[],
+): Promise<void> {
+	const previousCleanup = lease.cleanupBarrier;
+	const pendingCleanup = cleanup.filter((task): task is Promise<unknown> => task !== null);
+	lease.cleanupBarrier = Promise.allSettled([previousCleanup, ...pendingCleanup]).then(() => undefined);
+	return lease.cleanupBarrier;
+}
+
+export function assertCurrentLifecycleLease<TShutdown>(
+	current: LifecycleLease<TShutdown>,
+	expected: LifecycleLease<TShutdown>,
+	message: string,
+): void {
+	if (current !== expected || expected.retired) throw new Error(message);
+}
+
+/** Rejection-safe FIFO for lifecycle forwarding that must not overtake replay. */
+export class SerializedLifecycleForwarder {
+	private tail: Promise<void> = Promise.resolve();
+
+	get settled(): Promise<void> { return this.tail; }
+
+	enqueue<T>(operation: () => Promise<T>): Promise<T> {
+		const result = this.tail.then(operation, operation);
+		this.tail = result.then(() => undefined, () => undefined);
+		return result;
+	}
+}

package/dist/builtin/intercom/lifecycle.ts

@@ -33,11 +33,44 @@ interface LifecycleDeps {
   syncPresenceStatus(): void;
   syncPresenceIdentity(sessionId: string): void;
   currentStatus(): string;
+  restoreIntercomSessionIdEnv?(): void;
 }
 
 export function registerIntercomLifecycle(pi: ExtensionAPI, deps: LifecycleDeps): void {
-  pi.on("session_start", (_event, ctx) => {
+  let hasActiveSession = false;
+
+  async function cleanupRuntime(reason: string): Promise<void> {
+    deps.setRuntimeStarted(false);
+    deps.setShuttingDown(true);
+    deps.setDisposed(true);
+    deps.incrementRuntimeGeneration();
+    deps.clearStartupConnectTimer();
+    deps.clearReconnectTimer();
+    deps.rejectReplyWaiter(new Error(reason));
+    deps.replyTracker.reset();
+    deps.pendingIdleMessages.length = 0;
+    deps.clearInboundFlushTimer();
+    deps.setAgentRunning(false);
+    deps.activeTools.clear();
+    const activeClient = deps.client();
+    deps.setClient(null);
+    if (activeClient) {
+      try {
+        await activeClient.disconnect();
+      } catch (error) {
+        console.error(`Intercom failed to disconnect during ${reason.toLowerCase()}; continuing cleanup:`, error);
+      }
+    }
+    deps.restoreIntercomSessionIdEnv?.();
+    deps.setRuntimeContext(null);
+    deps.setCurrentSessionId(null);
+    deps.setSessionStartedAt(null);
+  }
+
+  pi.on("session_start", async (_event, ctx) => {
     if (!deps.config.enabled) return;
+    if (hasActiveSession) await cleanupRuntime("Session replaced");
+    hasActiveSession = true;
     deps.setShuttingDown(false);
     deps.setDisposed(false);
     deps.setRuntimeStarted(true);
@@ -63,25 +96,9 @@ export function registerIntercomLifecycle(pi: ExtensionAPI, deps: LifecycleDeps)
   });
 
   pi.on("session_shutdown", async () => {
-    deps.setShuttingDown(true);
-    deps.setDisposed(true);
-    deps.incrementRuntimeGeneration();
-    deps.clearStartupConnectTimer();
-    deps.clearReconnectTimer();
-    deps.rejectReplyWaiter(new Error("Session shutting down"));
-    deps.replyTracker.reset();
-    deps.pendingIdleMessages.length = 0;
-    deps.clearInboundFlushTimer();
-    deps.setAgentRunning(false);
-    deps.activeTools.clear();
-    const activeClient = deps.client();
-    if (activeClient) {
-      await activeClient.disconnect();
-      deps.setClient(null);
-    }
-    deps.setRuntimeContext(null);
-    deps.setCurrentSessionId(null);
-    deps.setSessionStartedAt(null);
+    if (!hasActiveSession) return;
+    hasActiveSession = false;
+    await cleanupRuntime("Session shutting down");
   });
 
   pi.on("turn_end", () => {

package/dist/builtin/intercom/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/intercom",
-  "version": "0.9.5-alpha.8",
+  "version": "0.9.5",
   "private": true,
   "description": "Atomic extension providing a private coordination channel between parent and child agent sessions. Fork of: https://github.com/nicobailon/pi-intercom",
   "contributors": [
@@ -18,10 +18,7 @@
     ".": "./index.ts"
   },
   "files": [
-    "index.ts",
-    "types.ts",
-    "config.ts",
-    "reply-tracker.ts",
+    "*.ts",
     "broker/**/*.ts",
     "ui/**/*.ts",
     "skills/**/*",
@@ -47,7 +44,7 @@
   },
   "peerDependencies": {
     "@bastani/atomic": "*",
-    "@earendil-works/pi-tui": "^0.80.3"
+    "@earendil-works/pi-tui": "^0.80.6"
   },
   "peerDependenciesMeta": {
     "@bastani/atomic": {

package/dist/builtin/intercom/reply-routing.ts

@@ -0,0 +1,17 @@
+import type { Message, SessionInfo } from "./types.js";
+
+export interface PendingReplyRoute {
+	from: string;
+	replyTo: string;
+	resolve(message: Message): void;
+}
+
+/** Routes only the exact sender/thread pair to a blocking tool waiter. */
+export function routeIncomingReply(waiter: PendingReplyRoute | null | undefined, from: SessionInfo, message: Message): boolean {
+	if (!waiter) return false;
+	const senderTarget = from.name || from.id;
+	const fromMatches = senderTarget.toLowerCase() === waiter.from.toLowerCase() || from.id === waiter.from;
+	if (!fromMatches || message.replyTo !== waiter.replyTo) return false;
+	waiter.resolve(message);
+	return true;
+}

package/dist/builtin/intercom/subagent-relay.ts

@@ -9,6 +9,8 @@ import {
   getErrorMessage,
   parseSubagentIntercomPayload,
 } from "./intercom-utils.js";
+import { DeliveredMessageCache } from "./broker/delivered-message-cache.js";
+import { buildSendSignature } from "./broker/send-signature.js";
 
 interface SubagentRelayDeps {
   runtimeGeneration(): number;
@@ -23,6 +25,7 @@ interface SubagentRelayDeps {
 
 export function registerSubagentRelay(pi: ExtensionAPI, deps: SubagentRelayDeps): void {
   const { getLiveContext, currentSessionTargetMatches, sendIncomingMessage, ensureConnected, resolveSessionTarget } = deps;
+  const localDeliveries = new DeliveredMessageCache();
   function deliverLocalSubagentRelayMessage(sender: "subagent-control" | "subagent-result", status: string, messageText: string): void {
     const now = Date.now();
     sendIncomingMessage({
@@ -60,6 +63,37 @@ export function registerSubagentRelay(pi: ExtensionAPI, deps: SubagentRelayDeps)
       ...(error ? { error: getErrorMessage(error) } : {}),
     });
   }
+  function acknowledgeResult(options: { acknowledge?: boolean }, requestId: string | undefined, delivered: boolean, error?: unknown): void {
+    if (options.acknowledge) emitResultDelivery(requestId, delivered, error);
+  }
+  function deliverLocal(
+    parsed: ReturnType<typeof parseSubagentIntercomPayload> & {},
+    options: { sender: "subagent-control" | "subagent-result"; status: string; errorEntryType: string; acknowledge?: boolean },
+  ): void {
+    try {
+      const signature = buildSendSignature(parsed.to, { text: parsed.message });
+      const match = parsed.requestId ? localDeliveries.lookup(parsed.requestId, signature) : "miss";
+      if (match === "conflict") {
+        throw new Error(`Intercom message ID '${parsed.requestId}' was already delivered with a different target or payload`);
+      }
+      if (match === "miss") {
+        deliverLocalSubagentRelayMessage(options.sender, options.status, parsed.message);
+        if (parsed.requestId) localDeliveries.record(parsed.requestId, signature);
+      }
+      acknowledgeResult(options, parsed.requestId, true);
+    } catch (error) {
+      try {
+        recordSubagentDeliveryError(options.errorEntryType, parsed.to, parsed.message, error);
+      } catch (recordError) {
+        console.error("Failed to record local subagent relay error:", recordError);
+      }
+      try {
+        acknowledgeResult(options, parsed.requestId, false, error);
+      } catch (ackError) {
+        console.error("Failed to acknowledge local subagent relay error:", ackError);
+      }
+    }
+  }
   function relaySubagentIntercomPayload(payload: unknown, options: {
     sender: "subagent-control" | "subagent-result";
     status: string;
@@ -73,11 +107,11 @@ export function registerSubagentRelay(pi: ExtensionAPI, deps: SubagentRelayDeps)
     void (async () => {
       const relayStillLive = () => !deps.runtimeStarted() || Boolean(getLiveContext(deps.runtimeContext(), relayGeneration));
       if (!relayStillLive()) {
+        acknowledgeResult(options, parsed.requestId, false);
         return;
       }
       if (currentSessionTargetMatches(parsed.to)) {
-        deliverLocalSubagentRelayMessage(options.sender, options.status, parsed.message);
-        if (options.acknowledge) emitResultDelivery(parsed.requestId, true);
+        deliverLocal(parsed, options);
         return;
       }
 
@@ -87,35 +121,47 @@ export function registerSubagentRelay(pi: ExtensionAPI, deps: SubagentRelayDeps)
         activeClient = await ensureConnected("background");
         target = await resolveSessionTarget(activeClient, parsed.to) ?? parsed.to;
       } catch (error) {
-        if (!relayStillLive()) return;
+        if (!relayStillLive()) {
+          acknowledgeResult(options, parsed.requestId, false, error);
+          return;
+        }
         recordSubagentDeliveryError(options.errorEntryType, parsed.to, parsed.message, error);
-        if (options.acknowledge) emitResultDelivery(parsed.requestId, false, error);
+        acknowledgeResult(options, parsed.requestId, false, error);
         return;
       }
 
       if (!relayStillLive()) {
+        acknowledgeResult(options, parsed.requestId, false);
         return;
       }
       if (currentSessionTargetMatches(parsed.to, target, activeClient)) {
-        deliverLocalSubagentRelayMessage(options.sender, options.status, parsed.message);
-        if (options.acknowledge) emitResultDelivery(parsed.requestId, true);
+        deliverLocal(parsed, options);
         return;
       }
 
       try {
-        const result = await activeClient.send(target, { text: parsed.message });
-        if (!relayStillLive()) return;
+        const result = await activeClient.send(target, {
+          text: parsed.message,
+          ...(parsed.requestId ? { messageId: parsed.requestId } : {}),
+        });
+        if (!relayStillLive()) {
+          acknowledgeResult(options, parsed.requestId, result.delivered);
+          return;
+        }
         if (!result.delivered) {
           const error = new Error(result.reason ?? "Session may not exist or has disconnected.");
           recordSubagentDeliveryError(options.errorEntryType, parsed.to, parsed.message, error);
-          if (options.acknowledge) emitResultDelivery(parsed.requestId, false, error);
+          acknowledgeResult(options, parsed.requestId, false, error);
           return;
         }
-        if (options.acknowledge) emitResultDelivery(parsed.requestId, true);
+        acknowledgeResult(options, parsed.requestId, true);
       } catch (error) {
-        if (!relayStillLive()) return;
+        if (!relayStillLive()) {
+          acknowledgeResult(options, parsed.requestId, false, error);
+          return;
+        }
         recordSubagentDeliveryError(options.errorEntryType, parsed.to, parsed.message, error);
-        if (options.acknowledge) emitResultDelivery(parsed.requestId, false, error);
+        acknowledgeResult(options, parsed.requestId, false, error);
       }
     })();
   }

package/dist/builtin/intercom/types.ts

@@ -31,7 +31,7 @@ export type ClientMessage =
   | { type: "register"; session: Omit<SessionInfo, "id"> }
   | { type: "unregister" }
   | { type: "list"; requestId: string }
-  | { type: "send"; to: string; message: Message }
+  | { type: "send"; to: string; message: Message; attemptId?: string }
   | { type: "presence"; name?: string; status?: string; model?: string };
 
 export type BrokerMessage =
@@ -42,5 +42,5 @@ export type BrokerMessage =
   | { type: "session_joined"; session: SessionInfo }
   | { type: "session_left"; sessionId: string }
   | { type: "error"; error: string }
-  | { type: "delivered"; messageId: string }
-  | { type: "delivery_failed"; messageId: string; reason: string };
+  | { type: "delivered"; messageId: string; attemptId?: string }
+  | { type: "delivery_failed"; messageId: string; reason: string; attemptId?: string };

package/dist/builtin/mcp/CHANGELOG.md

@@ -7,6 +7,44 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.5] - 2026-07-11
+
+### Changed
+
+- Aligned the MCP extension peer dependencies with upstream `pi-ai`/`pi-tui` `^0.80.6` as part of the consolidated Pi sync; no MCP source behavior changed ([#1703](https://github.com/bastani-inc/atomic/issues/1703)).
+- Improved startup responsiveness by keeping first-run/default lazy MCP metadata bootstrap out of `initializeMcp()`'s synchronous path. Cached direct tools and the MCP proxy still register immediately, explicit `eager`/`keep-alive` servers still connect during initialization, missing configured or `MCP_DIRECT_TOOLS`-selected direct-tool metadata is warmed in the background, and explicit proxy `search`, `describe`, and server-list requests hydrate cold-cache lazy server metadata on demand instead of broadening startup warmup. Warmed direct tools are registered live in the current session after metadata refresh rather than requiring restart. Cold-cache `describe` first narrows hydration to prefix-matched or explicitly requested servers, treats hyphen/underscore prefixes as aliases, and does not fan out to unrelated lazy servers after a prefix-directed miss; cold-cache proxy `search` intentionally hydrates all matching lazy servers so unscoped searches can see every configured tool.
+
+### Fixed
+
+- Replaced one-shot detached MCP startup with generation-safe, retryable single-flight initialization shared by background startup, proxy/direct tools, and readiness-critical commands. Initialization fast paths now validate the active context and exact session lease, commands retain the state they initialized across lazy module imports, and stale or unpublished state cannot execute or publish after shutdown, restart, or context disposal. Replacement startup normally waits for retired initialization plus state/OAuth cleanup, but bounded observed teardown prevents non-abortable SDK work from permanently poisoning later sessions while fencing late completion.
+- Made readiness, lazy-connection, manager-close, and UI-start waits caller-local across direct tools and proxy connect/call/search/describe/list paths. Pre-aborted calls start no producer; one aborted waiter rejects promptly with its exact reason; late shared failures stay observed; late UI runtimes are closed; and proxy modes plus metadata hydration revalidate session ownership after waits and before metadata mutation or SDK side effects.
+- Completed MCP Apps cancellation lifecycles for direct and proxy UI calls by emitting exactly one terminal `tool-cancelled` before session teardown, preserving the exact host abort reason over SDK wrappers, isolating notification failures, keeping success `tool-result` mutually exclusive, forwarding real cancellation events from reused runtimes, and observing asynchronous browser AppBridge send failures.
+- Aligned MCP tool result expansion hints with the CLI-wide `Ctrl+o` keybinding copy.
+- Fixed MCP background direct-tool warmup cancellation so stale in-flight connects are discarded before metadata/cache mutation, direct-tool refresh callbacks are guarded to the active session, completed warmups clear their active handle safely, and env-selected direct tool servers hydrate without forcing every lazy server eager.
+
+## [0.9.5-alpha.10] - 2026-07-11
+
+### Changed
+
+- Aligned the MCP extension peer dependencies with upstream `pi-ai`/`pi-tui` `^0.80.6` as part of the consolidated Pi sync; no MCP source behavior changed ([#1703](https://github.com/bastani-inc/atomic/issues/1703)).
+
+### Fixed
+
+- Replaced one-shot detached MCP startup with generation-safe, retryable single-flight initialization shared by background startup, proxy/direct tools, and readiness-critical commands. Initialization fast paths now validate the active context and exact session lease, commands retain the state they initialized across lazy module imports, and stale or unpublished state cannot execute or publish after shutdown, restart, or context disposal. Replacement startup normally waits for retired initialization plus state/OAuth cleanup, but bounded observed teardown prevents non-abortable SDK work from permanently poisoning later sessions while fencing late completion.
+- Made readiness, lazy-connection, manager-close, and UI-start waits caller-local across direct tools and proxy connect/call/search/describe/list paths. Pre-aborted calls start no producer; one aborted waiter rejects promptly with its exact reason; late shared failures stay observed; late UI runtimes are closed; and proxy modes plus metadata hydration revalidate session ownership after waits and before metadata mutation or SDK side effects.
+- Completed MCP Apps cancellation lifecycles for direct and proxy UI calls by emitting exactly one terminal `tool-cancelled` before session teardown, preserving the exact host abort reason over SDK wrappers, isolating notification failures, keeping success `tool-result` mutually exclusive, forwarding real cancellation events from reused runtimes, and observing asynchronous browser AppBridge send failures.
+
+## [0.9.5-alpha.9] - 2026-07-09
+
+### Changed
+
+- Improved startup responsiveness by keeping first-run/default lazy MCP metadata bootstrap out of `initializeMcp()`'s synchronous path. Cached direct tools and the MCP proxy still register immediately, explicit `eager`/`keep-alive` servers still connect during initialization, missing configured or `MCP_DIRECT_TOOLS`-selected direct-tool metadata is warmed in the background, and explicit proxy `search`, `describe`, and server-list requests hydrate cold-cache lazy server metadata on demand instead of broadening startup warmup. Warmed direct tools are registered live in the current session after metadata refresh rather than requiring restart. Cold-cache `describe` first narrows hydration to prefix-matched or explicitly requested servers, treats hyphen/underscore prefixes as aliases, and does not fan out to unrelated lazy servers after a prefix-directed miss; cold-cache proxy `search` intentionally hydrates all matching lazy servers so unscoped searches can see every configured tool.
+
+### Fixed
+
+- Aligned MCP tool result expansion hints with the CLI-wide `Ctrl+o` keybinding copy.
+- Fixed MCP background direct-tool warmup cancellation so stale in-flight connects are discarded before metadata/cache mutation, direct-tool refresh callbacks are guarded to the active session, completed warmups clear their active handle safely, and env-selected direct tool servers hydrate without forcing every lazy server eager.
+
 ## [0.9.4] - 2026-07-03
 
 ### Changed

package/dist/builtin/mcp/OAUTH.md

@@ -191,6 +191,7 @@ A Node.js HTTP server runs on `localhost` at path `/callback`:
 - Displays success/error HTML pages
 - Validates state parameter for CSRF protection
 - Has a 5-minute timeout for pending authorizations
+- Rejects and removes pending authorization waiters during session restart/shutdown before replacement-session startup continues
 
 ## Token Storage
 

package/dist/builtin/mcp/README.md

@@ -65,7 +65,11 @@ Precedence is:
 3. `.mcp.json`
 4. `.pi/mcp.json`
 
-Servers are **lazy by default** — they won't connect until you actually call one of their tools. The adapter caches tool metadata so search and describe work without live connections.
+Servers are **lazy by default** — they won't connect until you actually call one of their tools. The adapter caches tool metadata so search and describe work without live connections when a valid cache exists; on a cold cache, explicit proxy search/describe/server-list requests may connect lazy server(s) once to hydrate metadata on demand. `describe` narrows cold-cache hydration to an explicitly requested server or the server identified by the configured tool-name prefix before falling back to broader discovery. Unscoped `search` intentionally hydrates every configured lazy server that lacks cached metadata so the search can see all available tools.
+
+MCP startup and first-use calls share one initialization attempt per session. If background initialization fails, the next proxy, direct-tool, `/mcp`, or `/mcp-auth` use retries it; concurrent callers join that retry rather than starting duplicates, and a stale attempt cannot publish after session shutdown or context disposal. Replacement sessions normally wait for retired initialization, state, and OAuth cleanup; teardown uses a finite deadline so a non-abortable SDK producer cannot permanently block later sessions, while late settlement stays observed and fenced from publication. Shared lazy server connections and auto-authentication flows use the same caller-local cancellation rule: a pre-cancelled call starts nothing, while cancelling one waiter promptly rejects that call with its exact host reason without cancelling the producer needed by surviving callers. Session restart/shutdown deterministically rejects retired OAuth callers with retry guidance and clears old ownership before replacement authentication begins. Direct tools, proxy modes, metadata hydration, and readiness-critical commands revalidate the exact session lease after lifecycle-spanning waits and before SDK calls or state mutation; a UI runtime produced after caller cancellation is closed rather than orphaned. Direct and proxy resource/tool requests still forward the call's abort signal to the MCP SDK; protocol-level remote cancellation remains advisory.
+
+For MCP Apps tools, host cancellation sends one terminal `tool-cancelled` event after tool input and before session teardown, then rejects with the exact host abort reason even when the SDK wraps cancellation or the browser notification fails. A successful `tool-result` is mutually exclusive with that cancellation event. Non-UI tools and resource reads do not participate in the Apps lifecycle.
 
 ```
 mcp({ search: "screenshot" })
@@ -136,7 +140,7 @@ Pi-specific files are the write targets for imported or shared global servers wh
 
 ### Lifecycle Modes
 
-- **`lazy`** (default) — Don't connect at startup. Connect on first tool call. Disconnect after idle timeout. Cached metadata keeps search/list working without connections.
+- **`lazy`** (default) — Don't connect at startup. Connect on first tool call or explicit cold-cache proxy metadata request (`search`, `describe`, or `server` list). Disconnect after idle timeout. Cached metadata keeps search/list working without connections.
 - **`eager`** — Connect at startup but don't auto-reconnect if the connection drops. No idle timeout by default (set `idleTimeout` explicitly to enable).
 - **`keep-alive`** — Connect at startup. Auto-reconnect via health checks. No idle timeout. Use for servers you always need available.
 
@@ -232,7 +236,7 @@ To exclude specific tools while still using `directTools: true`, add `excludeToo
 
 Each direct tool costs ~150-300 tokens in the system prompt (name + description + schema). Good for targeted sets of 5-20 tools. For servers with 75+ tools, stick with the proxy or pick specific tools with a `string[]`.
 
-Direct tools register from the metadata cache in the Pi agent dir (`~/.pi/agent/mcp-cache.json` by default, or `$PI_CODING_AGENT_DIR/mcp-cache.json` when set), so no server connections are needed at startup. On the first session after adding `directTools` to a new server, the cache won't exist yet — tools fall back to proxy-only and the cache populates in the background. To force it: `/mcp reconnect <server>`.
+Direct tools register from the metadata cache in the Pi agent dir (`~/.pi/agent/mcp-cache.json` by default, or `$PI_CODING_AGENT_DIR/mcp-cache.json` when set), so no server connections are needed at startup when the cache is warm. On the first session after adding `directTools` to a new server, or when a child/subagent selects tools through `MCP_DIRECT_TOOLS`, the cache may not exist yet — tools fall back to proxy-only while the selected/configured direct-tool servers populate in the background, then the extension refreshes tool registration so the warmed direct tools become available in the current session. To force it immediately: `/mcp reconnect <server>`.
 
 When you change direct-tool toggles in `/mcp` or write new config through `/mcp setup`, the extension triggers Pi's normal reload flow automatically. That refreshes extensions, prompts, skills, and MCP tool registration in one shot, so newly configured direct tools can appear without a manual restart.
 
@@ -332,7 +336,7 @@ Prefer `.mcp.json` for project-local shared MCP config. Use `.pi/mcp.json` only
 | Connect | `mcp({ connect: "server-name" })` |
 | UI messages | `mcp({ action: "ui-messages" })` |
 
-MCP proxy and direct-tool results render compactly by default: long text shows the first three lines plus a `CTRL+O Expand` hint, while the full result remains available when expanded and is still returned unchanged to the model.
+MCP proxy and direct-tool results render compactly by default: long text shows the first three lines plus a `Ctrl+o Expand` hint, while the full result remains available when expanded and is still returned unchanged to the model.
 
 Search includes both MCP tools and Pi tools (from extensions). Pi tools appear first with `[pi tool]` prefix. Space-separated words are OR'd.
 
@@ -358,8 +362,8 @@ In interactive sessions, you can also authenticate from `/mcp` with `CTRL+A` or
 ## How It Works
 
 - One `mcp` tool in context (~200 tokens) instead of hundreds
-- Servers are lazy by default — they connect on first tool call, not at startup
-- Tool metadata is cached to disk so search/list/describe work without live connections
+- Servers are lazy by default — they connect on first tool call or explicit cold-cache proxy metadata request, not at startup
+- Tool metadata is cached to disk so search/list/describe work without live connections when the cache is valid; cold-cache explicit search/describe/server-list requests hydrate metadata on demand
 - Idle servers disconnect after 10 minutes (configurable), reconnect automatically on next use
 - npx-based servers resolve to direct binary paths, skipping the ~143 MB npm parent process
 - MCP server validates arguments, not the adapter

package/dist/builtin/mcp/apps-cancellation.ts

@@ -0,0 +1,32 @@
+import type { UiSessionRuntime } from "./ui-session.js";
+import { logger } from "./logger.js";
+
+function formatCancellationReason(signal: AbortSignal): string {
+  const reason = signal.reason;
+  return reason instanceof Error ? reason.message : String(reason);
+}
+
+export async function notifyUiCancellation(
+  uiSession: UiSessionRuntime | null,
+  reason: string,
+): Promise<void> {
+  if (!uiSession) return;
+  try {
+    await uiSession.sendToolCancelled(reason);
+  } catch (error) {
+    logger.error(
+      "Failed to notify MCP App about tool cancellation",
+      error instanceof Error ? error : new Error(String(error)),
+      { server: uiSession.serverName, tool: uiSession.toolName },
+    );
+  }
+}
+
+export async function rethrowHostAbortAfterUiCancellation(
+  signal: AbortSignal | undefined,
+  uiSession: UiSessionRuntime | null,
+): Promise<void> {
+  if (!signal?.aborted) return;
+  await notifyUiCancellation(uiSession, formatCancellationReason(signal));
+  signal.throwIfAborted();
+}

package/dist/builtin/mcp/call-tool-result.ts

@@ -0,0 +1,9 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+
+/**
+ * The SDK schema's inferred result also includes task handles, while these
+ * legacy adapter paths consume the terminal CallToolResult shape.
+ */
+export function asCallToolResult(result: object): CallToolResult {
+  return result as CallToolResult;
+}