@bastani/atomic 0.9.9 → 0.9.10-alpha.1

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

@@ -7,6 +7,7 @@ import {
   SUBAGENT_RESULT_INTERCOM_DELIVERY_EVENT,
   SUBAGENT_RESULT_INTERCOM_EVENT,
   SUBAGENT_TERMINAL_ORDERING_BARRIER_EVENT,
+  SUBAGENT_SUPERVISOR_AUTHORIZATION_EVENT,
   getErrorMessage,
   parseSubagentIntercomPayload,
   parseSubagentResultBarrier,
@@ -21,36 +22,60 @@ interface SubagentRelayDeps {
   runtimeContext(): ExtensionContext | null;
   getLiveContext(ctx?: ExtensionContext | null, generation?: number): ExtensionContext | null;
   currentSessionTargetMatches(to: string, resolvedTo?: string | null, activeClient?: IntercomClient): boolean;
-  sendIncomingMessage(entry: { from: SessionInfo; message: Message; bodyText: string }, delivery: "trigger" | "followUp", generation?: number): void;
+  sendIncomingMessage(entry: { from: SessionInfo; message: Message; bodyText: string }, delivery: "trigger" | "followUp", generation?: number): unknown;
   ensureConnected(reason: "background"): Promise<IntercomClient>;
+  authorizeSupervisorChild?(childName: string): Promise<import("./broker/client.js").SupervisorAuthorization>;
   resolveSessionTarget(activeClient: IntercomClient, nameOrId: string): Promise<string | null>;
+  homeGroup?(): string;
+}
+
+async function dispatchRelayFallback(
+  pi: ExtensionAPI,
+  prefix: Array<{ customType: string; content: string; display: boolean; details?: unknown }>,
+  terminalMessage: { customType: string; content: string; display: boolean; details?: unknown },
+): Promise<void> {
+  let delivered = 0;
+  try {
+    for (const message of prefix) {
+      await pi.sendMessage(message, { deliverAs: "steer" });
+      delivered += 1;
+    }
+    await pi.sendMessage(terminalMessage, { triggerTurn: true });
+  } catch (error) {
+    const failure = new Error(error instanceof Error ? error.message : String(error), { cause: error });
+    Object.assign(failure, { terminalPreludeDelivered: delivered });
+    throw failure;
+  }
 }
 
 export function registerSubagentRelay(pi: ExtensionAPI, deps: SubagentRelayDeps): void {
   const { getLiveContext, currentSessionTargetMatches, sendIncomingMessage, ensureConnected, resolveSessionTarget } = deps;
   const localDeliveries = new DeliveredMessageCache();
+  const localDeliveriesInFlight = new Map<string, { signature: string; completion: Promise<void> }>();
   function deliverLocalSubagentRelayMessage(
     sender: "subagent-control" | "subagent-result",
     status: string,
     messageText: string,
     terminalBarrier?: { runId: string; terminalId?: string; sourceSessionTargets: string[] },
-  ): void {
+  ): Promise<void> {
     const now = Date.now();
     const entry = {
       from: {
         id: sender, name: sender, cwd: deps.runtimeContext()?.cwd ?? process.cwd(),
-        model: sender, pid: process.pid, startedAt: now, lastActivity: now, status,
+        model: sender, pid: process.pid, startedAt: now, lastActivity: now, status, group: deps.homeGroup?.(),
       },
       message: { id: randomUUID(), timestamp: now, content: { text: messageText } },
       bodyText: messageText,
     };
     let dispatched = false;
+    let completion: Promise<void> | undefined;
     if (terminalBarrier) {
       const payload = {
         ...terminalBarrier,
         terminalAt: now,
         source: "result-relay" as const,
         dispatch: (prefix: Array<{ customType: string; content: string; display: boolean; details?: unknown }>) => {
+          dispatched = true;
           const terminalMessage = {
             customType: "intercom_message",
             content: `**📨 From ${sender}** (${entry.from.cwd})\n\n${messageText}`,
@@ -58,18 +83,19 @@ export function registerSubagentRelay(pi: ExtensionAPI, deps: SubagentRelayDeps)
             details: entry,
           };
           if (typeof pi.sendMessages === "function") {
-            pi.sendMessages([...prefix, terminalMessage], { triggerTurn: true });
-          } else {
-            for (const message of prefix) pi.sendMessage(message, { deliverAs: "steer" });
-            pi.sendMessage(terminalMessage, { triggerTurn: true });
+            return pi.sendMessages([...prefix, terminalMessage], { triggerTurn: true });
           }
-          dispatched = true;
+          return dispatchRelayFallback(pi, prefix, terminalMessage);
         },
       };
+      Object.defineProperty(payload, "terminalOwner", { value: pi });
       pi.events.emit(SUBAGENT_TERMINAL_ORDERING_BARRIER_EVENT, payload);
       emitGlobalTerminalOrderingBarrier(payload);
+      completion = (payload as typeof payload & { completion?: Promise<void> }).completion;
     }
-    if (!dispatched) sendIncomingMessage(entry, "trigger");
+    if (completion) return completion;
+    if (!dispatched) return Promise.resolve(sendIncomingMessage(entry, "trigger")).then(() => {});
+    return Promise.resolve();
   }
   function recordSubagentDeliveryError(entryType: string, to: string, message: string, error: unknown): void {
     pi.appendEntry(entryType, {
@@ -90,10 +116,10 @@ export function registerSubagentRelay(pi: ExtensionAPI, deps: SubagentRelayDeps)
   function acknowledgeResult(options: { acknowledge?: boolean }, requestId: string | undefined, delivered: boolean, error?: unknown): void {
     if (options.acknowledge) emitResultDelivery(requestId, delivered, error);
   }
-  function deliverLocal(
+  async function deliverLocal(
     parsed: ReturnType<typeof parseSubagentIntercomPayload> & {},
     options: { sender: "subagent-control" | "subagent-result"; status: string; errorEntryType: string; acknowledge?: boolean; terminalBarrier?: { runId: string; terminalId?: string; sourceSessionTargets: string[] } },
-  ): void {
+  ): Promise<void> {
     try {
       const signature = buildSendSignature(parsed.to, { text: parsed.message });
       const match = parsed.requestId ? localDeliveries.lookup(parsed.requestId, signature) : "miss";
@@ -101,7 +127,27 @@ export function registerSubagentRelay(pi: ExtensionAPI, deps: SubagentRelayDeps)
         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, options.terminalBarrier);
+        const pending = parsed.requestId ? localDeliveriesInFlight.get(parsed.requestId) : undefined;
+        if (pending && pending.signature !== signature) {
+          await pending.completion;
+          throw new Error(`Intercom message ID '${parsed.requestId}' was already delivered with a different target or payload`);
+        }
+        let delivery = pending?.completion;
+        if (!delivery && parsed.requestId) {
+          const deferred = Promise.withResolvers<void>();
+          delivery = deferred.promise;
+          void delivery.catch(() => {});
+          localDeliveriesInFlight.set(parsed.requestId, { signature, completion: delivery });
+          try {
+            void deliverLocalSubagentRelayMessage(options.sender, options.status, parsed.message, options.terminalBarrier).then(deferred.resolve, deferred.reject);
+          } catch (error) {
+            deferred.reject(error);
+          }
+          void delivery.finally(() => { localDeliveriesInFlight.delete(parsed.requestId!); }).catch(() => {});
+        } else if (!delivery) {
+          delivery = deliverLocalSubagentRelayMessage(options.sender, options.status, parsed.message, options.terminalBarrier);
+        }
+        await delivery;
         if (parsed.requestId) localDeliveries.record(parsed.requestId, signature);
       }
       acknowledgeResult(options, parsed.requestId, true);
@@ -137,7 +183,7 @@ export function registerSubagentRelay(pi: ExtensionAPI, deps: SubagentRelayDeps)
         return;
       }
       if (currentSessionTargetMatches(parsed.to)) {
-        deliverLocal(parsed, { ...options, terminalBarrier });
+        await deliverLocal(parsed, { ...options, terminalBarrier });
         return;
       }
       if (!deps.runtimeStarted()) {
@@ -170,7 +216,7 @@ export function registerSubagentRelay(pi: ExtensionAPI, deps: SubagentRelayDeps)
         return;
       }
       if (currentSessionTargetMatches(parsed.to, target, activeClient)) {
-        deliverLocal(parsed, { ...options, terminalBarrier });
+        await deliverLocal(parsed, { ...options, terminalBarrier });
         return;
       }
 
@@ -200,6 +246,13 @@ export function registerSubagentRelay(pi: ExtensionAPI, deps: SubagentRelayDeps)
       }
     })();
   }
+  pi.events.on(SUBAGENT_SUPERVISOR_AUTHORIZATION_EVENT, (payload) => {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) return;
+    const request = payload as { childName?: unknown; completion?: Promise<unknown> };
+    const childName = typeof request.childName === "string" ? request.childName.trim() : "";
+    if (!childName || request.completion || !deps.authorizeSupervisorChild) return;
+    request.completion = deps.authorizeSupervisorChild(childName);
+  });
   pi.events.on(SUBAGENT_CONTROL_INTERCOM_EVENT, (payload) => {
     relaySubagentIntercomPayload(payload, {
       sender: "subagent-control",

package/dist/builtin/intercom/supervisor-authorization-registry.ts

@@ -0,0 +1,22 @@
+import { randomUUID } from "node:crypto";
+import type { IntercomClient, SupervisorAuthorization } from "./broker/client.js";
+
+/** Parent-runtime cache used to restore broker capabilities after reconnects. */
+export class SupervisorAuthorizationRegistry {
+  private readonly byCapability = new Map<string, SupervisorAuthorization>();
+  readonly ownerToken = randomUUID();
+
+  async authorize(childName: string, connect: () => Promise<IntercomClient>): Promise<SupervisorAuthorization> {
+    const client = await connect();
+    const authorization = await client.authorizeSupervisorChild(childName.trim());
+    this.byCapability.set(authorization.capability, authorization);
+    return authorization;
+  }
+
+  async restore(client: IntercomClient): Promise<void> {
+    for (const [capability, existing] of this.byCapability) {
+      const authorization = await client.authorizeSupervisorChild(existing.childName, capability);
+      this.byCapability.set(capability, authorization);
+    }
+  }
+}

package/dist/builtin/intercom/terminal-ordering-barrier.ts

@@ -5,6 +5,9 @@ import type { InboundIdleQueue } from "./inbound-idle-queue.js";
 export { SUBAGENT_TERMINAL_ORDERING_BARRIER_EVENT } from "./intercom-utils.js";
 
 const GLOBAL_BARRIER_HANDLER = "__atomicTerminalOrderingBarrierHandler";
+const GLOBAL_BARRIER_REGISTRY = "__atomicTerminalOrderingBarrierRegistry";
+const terminalOwnerIds = new WeakMap<object, number>();
+let nextTerminalOwnerId = 1;
 
 export interface OrderedTerminalPreludeMessage {
   customType: "intercom_message";
@@ -18,15 +21,17 @@ export interface TerminalOrderingBarrier {
   terminalId: string;
   terminalAt: number;
   source: "background-notify" | "result-relay";
+  owner?: object;
   sourceSessionTargets: string[];
-  dispatch?(prefix: OrderedTerminalPreludeMessage[]): void;
+  dispatch?(prefix: OrderedTerminalPreludeMessage[]): unknown;
 }
 
 interface TerminalOrderingBarrierOptions {
   queue: InboundIdleQueue;
   toMessage?(entry: InboundMessageEntry): OrderedTerminalPreludeMessage;
-  deliver(entry: InboundMessageEntry, mode: "prelude"): void;
+  deliver(entry: InboundMessageEntry, mode: "prelude"): unknown;
   onDrain?(): void;
+  isCurrent?(): boolean;
 }
 
 function parseBarrier(value: unknown): TerminalOrderingBarrier | null {
@@ -41,23 +46,67 @@ function parseBarrier(value: unknown): TerminalOrderingBarrier | null {
     .map((target) => target.trim())
     .filter(Boolean);
   if (sourceSessionTargets.length === 0) return null;
+  const owner = record.terminalOwner && typeof record.terminalOwner === "object" ? record.terminalOwner : undefined;
   const terminalId = typeof record.terminalId === "string" && record.terminalId
     ? record.terminalId : `${record.source}:${record.terminalAt}`;
   return {
     runId: record.runId,
     terminalId,
     terminalAt: record.terminalAt,
+    ...(owner ? { owner } : {}),
     source: record.source,
     sourceSessionTargets,
     ...(typeof record.dispatch === "function"
-      ? { dispatch: record.dispatch as (prefix: OrderedTerminalPreludeMessage[]) => void }
+      ? { dispatch: record.dispatch as (prefix: OrderedTerminalPreludeMessage[]) => unknown }
       : {}),
   };
 }
 
+interface GlobalBarrierRegistration {
+  handle: (payload: unknown) => void;
+  isCurrent: () => boolean;
+}
+type GlobalBarrierRegistry = GlobalBarrierRegistration[] & { previousHandler?: unknown };
+
+function globalBarrierRegistry(): GlobalBarrierRegistry {
+  const globals = globalThis as Record<string, unknown>;
+  const current = globals[GLOBAL_BARRIER_REGISTRY];
+  if (Array.isArray(current)) return current as GlobalBarrierRegistry;
+  const registry = [] as GlobalBarrierRegistry;
+  registry.previousHandler = globals[GLOBAL_BARRIER_HANDLER];
+  globals[GLOBAL_BARRIER_REGISTRY] = registry;
+  return registry;
+}
+
 export function emitGlobalTerminalOrderingBarrier(value: unknown): void {
-  const handler = (globalThis as Record<string, unknown>)[GLOBAL_BARRIER_HANDLER];
-  if (typeof handler === "function") (handler as (payload: unknown) => void)(value);
+  const registry = globalBarrierRegistry();
+  for (let index = registry.length - 1; index >= 0; index -= 1) {
+    const registration = registry[index];
+    if (!registration?.isCurrent()) continue;
+    registration.handle(value);
+    return;
+  }
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<void> {
+  return (typeof value === "object" || typeof value === "function")
+    && value !== null
+    && typeof (value as { then?: unknown }).then === "function";
+}
+
+function terminalRollbackIndex(error: unknown, fallback: number): number {
+  if (!error || typeof error !== "object") return fallback;
+  const value = (error as { terminalPreludeDelivered?: unknown }).terminalPreludeDelivered;
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : fallback;
+}
+
+function terminalOwnerId(owner: object | undefined): number {
+  if (!owner) return 0;
+  const existing = terminalOwnerIds.get(owner);
+  if (existing) return existing;
+  const id = nextTerminalOwnerId++;
+  terminalOwnerIds.set(owner, id);
+  return id;
 }
 
 /** Claims accepted same-child messages before terminal delivery. */
@@ -66,46 +115,116 @@ export function registerTerminalOrderingBarrier(
   options: TerminalOrderingBarrierOptions,
 ): () => void {
   const drainedTargetsByTerminal = new Map<string, Set<string>>();
+  const inFlightByTerminal = new Map<string, Promise<void>>();
   const handle = (value: unknown): void => {
+    if (options.isCurrent?.() === false) return;
     const barrier = parseBarrier(value);
     if (!barrier) return;
-    const terminalKey = `${barrier.runId}\0${barrier.terminalId}`;
+    const envelope = value as { completion?: Promise<void> };
+    if (envelope.completion) return;
+    const terminalKey = `${terminalOwnerId(barrier.owner)}:${barrier.runId}\0${barrier.terminalId}`;
+    const currentOwner = inFlightByTerminal.get(terminalKey);
+    if (currentOwner) { envelope.completion = currentOwner; return; }
     const drainedTargets = drainedTargetsByTerminal.get(terminalKey) ?? new Set<string>();
     const pendingTargets = barrier.sourceSessionTargets.filter((target) => !drainedTargets.has(target));
     if (pendingTargets.length === 0) return;
     const claim = options.queue.claimOrdinarySourceTargets(barrier.runId, pendingTargets, barrier.terminalAt);
+    const ownership = Promise.withResolvers<void>();
+    void ownership.promise.catch(() => {});
+    inFlightByTerminal.set(terminalKey, ownership.promise);
+    const failOwnership = (error: unknown): void => {
+      if (inFlightByTerminal.get(terminalKey) === ownership.promise) inFlightByTerminal.delete(terminalKey);
+      ownership.reject(error);
+    };
+    const finish = (): void => {
+      if ((barrier.dispatch && options.toMessage) || claim.entries.length > 0) {
+        for (const target of pendingTargets) drainedTargets.add(target);
+        drainedTargetsByTerminal.set(terminalKey, drainedTargets);
+      }
+      if (drainedTargetsByTerminal.size > 1_000) {
+        const oldestKey = drainedTargetsByTerminal.keys().next().value;
+        if (oldestKey !== undefined) drainedTargetsByTerminal.delete(oldestKey);
+      }
+      if (claim.entries.length > 0) options.onDrain?.();
+      if (inFlightByTerminal.get(terminalKey) === ownership.promise) inFlightByTerminal.delete(terminalKey);
+      ownership.resolve();
+    };
+    const observe = (completion: Promise<void>): void => {
+      envelope.completion = ownership.promise;
+      void completion.then(() => {}, (error) => {
+        failOwnership(error);
+        if (envelope.completion === ownership.promise) delete envelope.completion;
+      });
+    };
     if (barrier.dispatch && options.toMessage) {
+      let dispatched: unknown;
+      let dispatchedAsync: boolean;
       try {
-        barrier.dispatch(claim.entries.map(options.toMessage));
+        dispatched = barrier.dispatch(claim.entries.map(options.toMessage));
+        dispatchedAsync = isPromiseLike(dispatched);
       } catch (error) {
-        claim.rollbackFrom(0);
+        claim.rollbackFrom(terminalRollbackIndex(error, 0));
+        failOwnership(error);
         throw error;
       }
-    } else {
-      for (let index = 0; index < claim.entries.length; index++) {
+      if (dispatchedAsync) {
+        observe(Promise.resolve(dispatched).then(finish, (error) => {
+          claim.rollbackFrom(terminalRollbackIndex(error, 0));
+          throw error;
+        }));
+        return;
+      }
+      finish();
+      return;
+    }
+    for (let index = 0; index < claim.entries.length; index++) {
+      let delivered: unknown;
+      let deliveredAsync: boolean;
+      try {
+        delivered = options.deliver(claim.entries[index]!, "prelude");
+        deliveredAsync = isPromiseLike(delivered);
+      } catch (error) {
+        claim.rollbackFrom(index);
+        failOwnership(error);
+        throw error;
+      }
+      if (!deliveredAsync) continue;
+      observe((async (): Promise<void> => {
+        let current = index;
         try {
-          options.deliver(claim.entries[index]!, "prelude");
+          await delivered;
+          for (current = index + 1; current < claim.entries.length; current++) {
+            await options.deliver(claim.entries[current]!, "prelude");
+          }
+          finish();
         } catch (error) {
-          claim.rollbackFrom(index);
+          claim.rollbackFrom(current);
           throw error;
         }
-      }
-    }
-    if ((barrier.dispatch && options.toMessage) || claim.entries.length > 0) {
-      for (const target of pendingTargets) drainedTargets.add(target);
-      drainedTargetsByTerminal.set(terminalKey, drainedTargets);
+      })());
+      return;
     }
-    if (drainedTargetsByTerminal.size > 1_000) {
-      const oldestKey = drainedTargetsByTerminal.keys().next().value;
-      if (oldestKey !== undefined) drainedTargetsByTerminal.delete(oldestKey);
-    }
-    if (claim.entries.length > 0) options.onDrain?.();
+    finish();
   };
-  (globalThis as Record<string, unknown>)[GLOBAL_BARRIER_HANDLER] = handle;
+  const globals = globalThis as Record<string, unknown>;
+  const registry = globalBarrierRegistry();
+  const registration = { handle, isCurrent: () => options.isCurrent?.() !== false };
+  registry.push(registration);
+  globals[GLOBAL_BARRIER_HANDLER] = emitGlobalTerminalOrderingBarrier;
   const unsubscribe = pi.events.on(SUBAGENT_TERMINAL_ORDERING_BARRIER_EVENT, handle);
+  let registered = true;
   return () => {
+    if (!registered) return;
+    registered = false;
     unsubscribe();
-    const globals = globalThis as Record<string, unknown>;
-    if (globals[GLOBAL_BARRIER_HANDLER] === handle) delete globals[GLOBAL_BARRIER_HANDLER];
+    const index = registry.indexOf(registration);
+    if (index >= 0) registry.splice(index, 1);
+    if (registry.length === 0) {
+      if (globals[GLOBAL_BARRIER_HANDLER] === emitGlobalTerminalOrderingBarrier) {
+        if (typeof registry.previousHandler === "function") globals[GLOBAL_BARRIER_HANDLER] = registry.previousHandler;
+        else delete globals[GLOBAL_BARRIER_HANDLER];
+      }
+      if (globals[GLOBAL_BARRIER_REGISTRY] === registry) delete globals[GLOBAL_BARRIER_REGISTRY];
+    }
   };
 }

package/dist/builtin/intercom/types.ts

@@ -7,6 +7,8 @@ export interface SessionInfo {
   startedAt: number;
   lastActivity: number;
   status?: string;
+  /** Session's intercom group; undefined is treated as the shared "default" group. */
+  group?: string;
 }
 
 export interface Message {
@@ -14,6 +16,8 @@ export interface Message {
   timestamp: number;
   replyTo?: string;
   expectsReply?: boolean;
+  /** Actionable remote failure for a correlated ask reply. */
+  replyError?: string;
   source?: {
     subagentRunId: string;
     subagentAgent?: string;
@@ -31,18 +35,27 @@ export interface Attachment {
   content: string;
   language?: string;
 }
+/** Broker capability metadata binding a child registration to its supervisor. */
+export interface SupervisorRegistration {
+  capability: string;
+  supervisorSessionId: string;
+}
+
 
 export type ClientMessage =
-  | { type: "register"; session: Omit<SessionInfo, "id"> }
+  | { type: "register"; session: Omit<SessionInfo, "id">; supervisor?: SupervisorRegistration; supervisorOwnerToken?: string }
   | { type: "unregister" }
-  | { type: "list"; requestId: string }
-  | { type: "send"; to: string; message: Message; attemptId?: string }
+  | { type: "list"; requestId: string; group?: string }
+  | { type: "authorize_supervisor"; requestId: string; childName: string; capability?: string }
+  | { type: "send" | "supervisor_send"; to: string; message: Message; attemptId?: string }
   | { type: "presence"; name?: string; status?: string; model?: string };
 
 export type BrokerMessage =
-  | { type: "registered"; sessionId: string }
+  | { type: "registered"; sessionId: string; supervisorSessionId?: string }
+  | { type: "registration_failed"; reason: string }
   | { type: "sessions"; requestId: string; sessions: SessionInfo[] }
-  | { type: "message"; from: SessionInfo; message: Message }
+  | { type: "supervisor_authorized"; requestId: string; capability: string; supervisorSessionId: string; childName: string }
+  | { type: "message"; from: SessionInfo; message: Message; channel?: "supervisor" }
   | { type: "presence_update"; session: SessionInfo }
   | { type: "session_joined"; session: SessionInfo }
   | { type: "session_left"; sessionId: string }

package/dist/builtin/intercom/workflow-reply-tracker.ts

@@ -0,0 +1,19 @@
+import type { ExtensionContext } from "@bastani/atomic";
+import { ReplyTracker } from "./reply-tracker.js";
+
+const WORKFLOW_REPLY_TRACKER_STATE = "intercom.reply-tracker";
+
+/** Reuses one reply-correlation ledger across workflow model-fallback sessions. */
+export function bindWorkflowReplyTracker(ctx: ExtensionContext, current: ReplyTracker): ReplyTracker {
+  const state = ctx.orchestrationContext?.messageAdmission?.extensionState;
+  if (!state) return current;
+  const shared = state.get(WORKFLOW_REPLY_TRACKER_STATE);
+  if (shared instanceof ReplyTracker) return shared;
+  state.set(WORKFLOW_REPLY_TRACKER_STATE, current);
+  return current;
+}
+
+/** A retiring fallback session must not clear the still-open generation ledger. */
+export function preserveWorkflowReplyTracker(ctx: ExtensionContext | null): boolean {
+  return ctx?.orchestrationContext?.messageAdmission?.isOpen() === true;
+}

package/dist/builtin/intercom/workflow-stage-admission.ts

@@ -0,0 +1,43 @@
+import type { ExtensionContext } from "@bastani/atomic";
+
+export type WorkflowStageFirstRefusalDisposition = "delivered" | "unclaimed" | "abandoned";
+export type WorkflowStageAdmissionBarrier = () => Promise<void>;
+
+/**
+ * boundary rather than Intercom's idle queue. A busy-stage delivery enters that
+ * boundary synchronously, then waits inside it while the exact foreground
+ * subagent owner receives first refusal. This prevents terminal close from
+ * sealing the generation during the detach handshake and dropping the message.
+ */
+export function admitWorkflowStageInbound(
+	ctx: Pick<ExtensionContext, "orchestrationContext"> & Partial<Pick<ExtensionContext, "isIdle">>,
+	deliver: (admissionBarrier?: WorkflowStageAdmissionBarrier) => void | Promise<void>,
+	firstRefusal?: () => Promise<WorkflowStageFirstRefusalDisposition>,
+	onAdmissionFailure?: (error: Error) => Promise<void>,
+): false | Promise<void> {
+	if (ctx.orchestrationContext?.kind !== "workflow-stage") return false;
+	try {
+		let busy = false;
+		try {
+			busy = ctx.isIdle?.() === false;
+		} catch {
+			// A retiring context is handled by the generation check in delivery.
+		}
+		if (!busy || !firstRefusal) return Promise.resolve(deliver());
+		let firstRefusalPromise: Promise<void> | undefined;
+		const admissionBarrier: WorkflowStageAdmissionBarrier = () => {
+			firstRefusalPromise ??= (async () => {
+				const disposition = await firstRefusal();
+				if (disposition === "abandoned") {
+					const failure = new Error("Workflow stage retired during foreground-owner admission");
+					await onAdmissionFailure?.(failure);
+					throw failure;
+				}
+			})();
+			return firstRefusalPromise;
+		};
+		return Promise.resolve(deliver(admissionBarrier));
+	} catch (error) {
+		return Promise.reject(error);
+	}
+}

package/dist/builtin/intercom/workflow-stage-delivery-failure.ts

@@ -0,0 +1,77 @@
+import type { IntercomClient } from "./broker/client.js";
+import type { InboundMessageAdmission, InboundMessageReservation } from "./inbound-message-admission.js";
+import type { InboundMessageEntry } from "./intercom-utils.js";
+import type { IntercomContext, ReplyTracker } from "./reply-tracker.js";
+
+/** Sends an exact-thread tool error when destination-side stage admission fails. */
+export async function sendWorkflowStageDeliveryFailure(
+  entry: InboundMessageEntry,
+  failure: Error,
+  tracker: ReplyTracker,
+  currentClient: () => IntercomClient | null,
+  isCurrent: () => boolean,
+  prefix: string,
+): Promise<boolean> {
+  const client = currentClient();
+  if (!client?.isConnected() || !isCurrent()) return false;
+  const actionable = `${prefix}: ${failure.message}`;
+  try {
+    const result = await client.send(entry.from.id, {
+      text: actionable,
+      replyTo: entry.message.id,
+      replyError: actionable,
+    });
+    if (!result.delivered) return false;
+    tracker.markReplied(entry.message.id);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Builds the target-side rejection path for an open workflow-stage delivery. */
+export function createWorkflowStageDeliveryFailureHandler(input: {
+  entry: InboundMessageEntry;
+  admission: InboundMessageAdmission;
+  reservation: InboundMessageReservation;
+  tracker: ReplyTracker;
+  replyContext: IntercomContext;
+  currentClient: () => IntercomClient | null;
+  commit: () => void;
+}): (error: unknown) => Promise<void> {
+  let settlement: Promise<void> | undefined;
+  return (error) => {
+    settlement ??= settleOpenStageDeliveryFailure(input, error);
+    return settlement;
+  };
+}
+
+async function settleOpenStageDeliveryFailure(
+  input: {
+    entry: InboundMessageEntry;
+    admission: InboundMessageAdmission;
+    reservation: InboundMessageReservation;
+    tracker: ReplyTracker;
+    replyContext: IntercomContext;
+    currentClient: () => IntercomClient | null;
+    commit: () => void;
+  },
+  error: unknown,
+): Promise<void> {
+  const failure = error instanceof Error ? error : new Error(String(error));
+  input.tracker.forgetIncomingMessage(input.replyContext);
+  if (input.entry.message.expectsReply !== true) {
+    input.admission.release(input.reservation, failure);
+    return;
+  }
+  const delivered = await sendWorkflowStageDeliveryFailure(
+    input.entry,
+    failure,
+    input.tracker,
+    input.currentClient,
+    () => input.currentClient()?.isConnected() === true,
+    "Running workflow stage could not admit intercom ask",
+  );
+  if (delivered) input.commit();
+  else input.admission.release(input.reservation, failure);
+}

package/dist/builtin/mcp/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.10-alpha.1] - 2026-07-19
+
+### Added
+
+- Added validated per-server MCP tool-call inactivity timeouts for local and remote servers, with progress-aware timer resets, user-readable timeout errors, and preserved host cancellation.
+
+### Fixed
+
+- Fixed collapsed MCP results showing a malformed or unavailable expand shortcut when `app.tools.expand` is remapped or unbound.
+- Preserved credential-specific `baseUrl` overrides for MCP sampling requests so enterprise/provider-owned endpoints are used alongside dynamic API keys and headers ([#1875](https://github.com/bastani-inc/atomic/issues/1875)).
+
 ## [0.9.9] - 2026-07-15
 
 ### Changed