@bastani/atomic 0.9.5-alpha.9 → 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.9",
+  "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,33 @@ 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

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

@@ -67,6 +67,10 @@ Precedence is:
 
 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" })
 ```

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;
+}

package/dist/builtin/mcp/caller-wait.ts

@@ -0,0 +1,50 @@
+/**
+ * Race one caller's cancellation against a shared producer without forwarding
+ * cancellation to, or otherwise taking ownership of, that producer.
+ */
+export function waitForCaller<T>(
+  getSharedPromise: () => Promise<T>,
+  signal?: AbortSignal,
+): Promise<T> {
+  signal?.throwIfAborted();
+  const sharedPromise = getSharedPromise();
+  if (!signal) return sharedPromise;
+
+  return new Promise<T>((resolve, reject) => {
+    let callerSettled = false;
+    const finishCaller = (settle: () => void): void => {
+      if (callerSettled) return;
+      callerSettled = true;
+      signal.removeEventListener("abort", onAbort);
+      settle();
+    };
+    const onAbort = (): void => finishCaller(() => reject(signal.reason));
+
+    signal.addEventListener("abort", onAbort, { once: true });
+    void sharedPromise.then(
+      (value) => finishCaller(() => resolve(value)),
+      (error) => finishCaller(() => reject(error)),
+    );
+    if (signal.aborted) onAbort();
+  });
+}
+
+/**
+ * Race caller cancellation while retaining responsibility for a value that may
+ * be produced after the caller has gone away.
+ */
+export async function waitForCallerWithLateCleanup<T>(
+  getSharedPromise: () => Promise<T>,
+  signal: AbortSignal | undefined,
+  cleanupLate: (value: T) => void | Promise<void>,
+): Promise<T> {
+  const sharedPromise = getSharedPromise();
+  try {
+    return await waitForCaller(() => sharedPromise, signal);
+  } catch (error) {
+    if (signal?.aborted) {
+      void sharedPromise.then(cleanupLate, () => undefined);
+    }
+    throw error;
+  }
+}