@band-ai/sdk 0.3.0 → 0.3.2

package/dist/adapters.cjs

@@ -1062,6 +1062,9 @@ var ACPClientHistoryConverter = class {
   convert(raw) {
     const roomToSession = {};
     for (const entry of raw) {
+      if (entry.message_type !== "task") {
+        continue;
+      }
       const metadataRaw = entry.metadata;
       if (!metadataRaw || typeof metadataRaw !== "object" || Array.isArray(metadataRaw)) {
         continue;
@@ -1069,7 +1072,7 @@ var ACPClientHistoryConverter = class {
       const metadata = metadataRaw;
       const sessionId = metadata.acp_client_session_id;
       const roomId = metadata.acp_client_room_id;
-      if (typeof sessionId === "string" && typeof roomId === "string" && sessionId && roomId) {
+      if (typeof sessionId === "string" && typeof roomId === "string" && sessionId && roomId && roomId === entry.room_id) {
         roomToSession[roomId] = sessionId;
       }
     }
@@ -1888,7 +1891,13 @@ function normalizeMcpServers(mcpServers) {
 // src/adapters/acp/client.ts
 var BandACPClient = class {
   sessionChunks = /* @__PURE__ */ new Map();
-  permissionHandlers = /* @__PURE__ */ new Map();
+  permissionHandler;
+  // The handler is connection-scoped and required at construction, so it is
+  // already in place before the agent process is spawned: there is no window
+  // in which a `session/request_permission` has nowhere to go.
+  constructor(permissionHandler) {
+    this.permissionHandler = permissionHandler;
+  }
   async sessionUpdate(params) {
     const chunk = toCollectedChunk(params.update);
     if (!chunk) {
@@ -1899,26 +1908,12 @@ var BandACPClient = class {
     this.sessionChunks.set(params.sessionId, existing);
   }
   async requestPermission(params) {
-    const handler = this.permissionHandlers.get(params.sessionId);
-    if (handler) {
-      return handler(params);
-    }
-    return {
-      outcome: {
-        outcome: "cancelled"
-      }
-    };
+    return this.permissionHandler(params);
   }
-  setPermissionHandler(sessionId, handler) {
-    if (!handler) {
-      this.permissionHandlers.delete(sessionId);
-      return;
-    }
-    this.permissionHandlers.set(sessionId, handler);
-  }
-  resetSession(sessionId) {
+  // Named for the one thing it clears: collected chunks are per-turn, and a
+  // per-turn caller must not be able to reach anything with a longer life.
+  resetChunks(sessionId) {
     this.sessionChunks.delete(sessionId);
-    this.permissionHandlers.delete(sessionId);
   }
   getCollectedText(sessionId) {
     return this.getCollectedChunks(sessionId).filter((chunk) => chunk.chunkType === "text").map((chunk) => chunk.content).join("");
@@ -2162,13 +2157,21 @@ var ACPClientAdapter = class extends SimpleAdapter {
   clientCapabilities;
   connectionFactory;
   roomToSession = /* @__PURE__ */ new Map();
+  sessionToRoom = /* @__PURE__ */ new Map();
   roomTools = /* @__PURE__ */ new Map();
   activeSessions = /* @__PURE__ */ new Set();
   bootstrappedSessions = /* @__PURE__ */ new Set();
   pendingPermissions = /* @__PURE__ */ new Map();
+  sessionsInFlight = /* @__PURE__ */ new Map();
+  roomTurnLocks = /* @__PURE__ */ new Map();
+  // Bumped each time a room starts a *new* establishment (never on a
+  // coalesced reuse) and whenever a room is torn down. An establishment
+  // captures its own value at the start; if the room has moved on by the
+  // time it would link/activate a session, it was superseded and must not.
+  roomGeneration = /* @__PURE__ */ new Map();
   resolvePermission;
+  resolveSessionMode;
   permissionTimeoutMs;
-  requestedPermissionMode;
   logger;
   backend = null;
   backendPromise = null;
@@ -2197,13 +2200,10 @@ var ACPClientAdapter = class extends SimpleAdapter {
     this.clientCapabilities = options.clientCapabilities;
     this.connectionFactory = options.connectionFactory ?? createSubprocessConnection;
     this.resolvePermission = options.resolvePermission;
+    this.resolveSessionMode = options.resolveSessionMode;
     this.logger = options.logger ?? new NoopLogger();
     this.permissionTimeoutMs = options.permissionTimeoutMs ?? DEFAULT_PERMISSION_TIMEOUT_MS;
-    this.requestedPermissionMode = options.requestedPermissionMode;
-    if (this.requestedPermissionMode !== void 0 && this.requestedPermissionMode.length === 0) {
-      throw new ValidationError("requestedPermissionMode must be a non-empty mode id, got an empty string");
-    }
-    if (this.resolvePermission && (!Number.isFinite(this.permissionTimeoutMs) || this.permissionTimeoutMs <= 0)) {
+    if ((this.resolvePermission || this.resolveSessionMode) && (!Number.isFinite(this.permissionTimeoutMs) || this.permissionTimeoutMs <= 0)) {
       throw new ValidationError(`permissionTimeoutMs must be a positive finite number, got ${options.permissionTimeoutMs}`);
     }
   }
@@ -2222,17 +2222,16 @@ var ACPClientAdapter = class extends SimpleAdapter {
       this.rehydrate(history);
     }
     this.roomTools.set(context.roomId, tools);
+    await this.withRoomTurnLock(context.roomId, () => this.runTurn(message, tools, participantsMessage, contactsMessage, context));
+  }
+  async runTurn(message, tools, participantsMessage, contactsMessage, context) {
     const connection = await this.ensureConnection();
     const client = this.client;
     if (!client) {
       throw new Error("ACP client was not initialized");
     }
     const sessionId = await this.getOrCreateSession(context.roomId, connection);
-    client.resetSession(sessionId);
-    client.setPermissionHandler(
-      sessionId,
-      (params) => this.handlePermissionRequest(tools, context.roomId, params)
-    );
+    client.resetChunks(sessionId);
     const content = replaceUuidMentions(message.content, mentionSubjectsFromMetadata(message.metadata));
     const messageWithContext = [...systemUpdateParts(participantsMessage, contactsMessage), content].join("\n\n");
     const promptText = this.bootstrappedSessions.has(sessionId) ? messageWithContext : `${this.buildSystemContext(context.roomId, message)}
@@ -2265,15 +2264,28 @@ ${messageWithContext}`;
       acp_client_room_id: context.roomId
     });
   }
+  // A per-room async mutex: `fn` for a given `roomId` never overlaps another
+  // call for that same room, while different rooms stay fully concurrent.
+  // The tracked tail (`this.roomTurnLocks`) always settles — via the
+  // trailing `.catch` — so one turn's failure can't wedge every later turn
+  // for the room; the real result/rejection is still `run`, returned to this
+  // call's own caller.
+  async withRoomTurnLock(roomId, fn) {
+    const previous = this.roomTurnLocks.get(roomId) ?? Promise.resolve();
+    const run = previous.then(fn, fn);
+    this.roomTurnLocks.set(roomId, run.catch(() => void 0));
+    return run;
+  }
   async onCleanup(roomId) {
-    const sessionId = this.roomToSession.get(roomId);
-    this.roomToSession.delete(roomId);
+    const sessionId = this.unlinkRoom(roomId);
     this.roomTools.delete(roomId);
+    this.sessionsInFlight.delete(roomId);
+    this.roomTurnLocks.delete(roomId);
+    this.nextRoomGeneration(roomId);
     if (sessionId) {
       this.activeSessions.delete(sessionId);
       this.bootstrappedSessions.delete(sessionId);
-      this.client?.setPermissionHandler(sessionId, void 0);
-      this.cancelPendingPermissions(sessionId);
+      this.cancelPendingPermissions(sessionId, "room-closed");
     }
   }
   async onRuntimeStop() {
@@ -2285,8 +2297,14 @@ ${messageWithContext}`;
     this.activeSessions.clear();
     this.bootstrappedSessions.clear();
     this.roomToSession.clear();
+    this.sessionToRoom.clear();
     this.roomTools.clear();
-    this.cancelAllPendingPermissions();
+    this.sessionsInFlight.clear();
+    this.roomTurnLocks.clear();
+    for (const roomId of this.roomGeneration.keys()) {
+      this.nextRoomGeneration(roomId);
+    }
+    this.cancelAllPendingPermissions("adapter-stopped");
     this.client = null;
     this.connection = null;
     if (this.backend) {
@@ -2303,9 +2321,65 @@ ${messageWithContext}`;
   rehydrate(history) {
     for (const [roomId, sessionId] of Object.entries(history.roomToSession)) {
       if (!this.roomToSession.has(roomId)) {
-        this.roomToSession.set(roomId, sessionId);
-      }
+        this.linkSession(roomId, sessionId);
+      }
+    }
+  }
+  // The only writer of both session maps, so they cannot drift: replacing a
+  // room's session drops the old session's route, and a session id already
+  // routed to another room is refused rather than silently re-pointed — two
+  // rooms sharing one session id would make its permission requests
+  // unattributable. Returns whether the link was made — a caller that goes
+  // on to activate/configure/prompt a session regardless of a `false` here
+  // would use a session this room was refused, not just fail to route its
+  // permissions.
+  linkSession(roomId, sessionId) {
+    const routedRoomId = this.sessionToRoom.get(sessionId);
+    if (routedRoomId !== void 0 && routedRoomId !== roomId) {
+      this.safeWarn("refusing to route one ACP session to a second room", {
+        sessionId,
+        roomId,
+        routedRoomId
+      });
+      return false;
+    }
+    const replacedSessionId = this.roomToSession.get(roomId);
+    if (replacedSessionId !== void 0 && replacedSessionId !== sessionId) {
+      this.sessionToRoom.delete(replacedSessionId);
+    }
+    this.roomToSession.set(roomId, sessionId);
+    this.sessionToRoom.set(sessionId, roomId);
+    return true;
+  }
+  nextRoomGeneration(roomId) {
+    const next = (this.roomGeneration.get(roomId) ?? 0) + 1;
+    this.roomGeneration.set(roomId, next);
+    return next;
+  }
+  isCurrentGeneration(roomId, generation) {
+    return this.roomGeneration.get(roomId) === generation;
+  }
+  // The installed ACP SDK's `sendRequest` never rejects a pending call when
+  // its connection closes (no server response ever arrives to reject it
+  // with) — so a session-establishment RPC in flight when the subprocess
+  // dies would otherwise hang forever, wedging the room's `sessionsInFlight`
+  // entry along with it. Racing every such RPC against the connection's own
+  // `closed` promise gives it a real, prompt failure instead.
+  raceAgainstConnectionClose(connection, operation) {
+    let reject = () => void 0;
+    const closedRejection = new Promise((_resolve, rejectFn) => {
+      reject = rejectFn;
+    });
+    void connection.closed.then(() => reject(new Error("ACP connection closed while a session operation was still in flight")));
+    return Promise.race([operation, closedRejection]);
+  }
+  unlinkRoom(roomId) {
+    const sessionId = this.roomToSession.get(roomId);
+    this.roomToSession.delete(roomId);
+    if (sessionId !== void 0) {
+      this.sessionToRoom.delete(sessionId);
     }
+    return sessionId;
   }
   async ensureConnection() {
     if (this.connection && !this.connection.signal.aborted) {
@@ -2326,7 +2400,7 @@ ${messageWithContext}`;
   }
   async spawnConnection() {
     const acp = await acpModule.get();
-    const client = new BandACPClient();
+    const client = new BandACPClient((params) => this.routePermissionRequest(params));
     const handle = await this.connectionFactory(client, {
       command: this.command,
       cwd: this.cwd,
@@ -2352,6 +2426,7 @@ ${messageWithContext}`;
         this.connectionHandle = null;
         this.connectionState = null;
         this.activeSessions.clear();
+        this.cancelAllPendingPermissions("connection-lost");
       }
     });
     return connection;
@@ -2361,69 +2436,140 @@ ${messageWithContext}`;
     if (existingSessionId && this.activeSessions.has(existingSessionId)) {
       return existingSessionId;
     }
+    const inFlight = this.sessionsInFlight.get(roomId);
+    if (inFlight) {
+      return inFlight;
+    }
+    const generation = this.nextRoomGeneration(roomId);
+    const establishing = this.establishSession(roomId, existingSessionId, connection, generation);
+    establishing.finally(() => {
+      if (this.sessionsInFlight.get(roomId) === establishing) {
+        this.sessionsInFlight.delete(roomId);
+      }
+    }).catch(() => void 0);
+    this.sessionsInFlight.set(roomId, establishing);
+    return establishing;
+  }
+  async establishSession(roomId, existingSessionId, connection, generation) {
     const mcpServers = await this.buildSessionMcpServers();
     if (existingSessionId) {
       const restored = await this.tryRestoreSession(connection, existingSessionId, mcpServers);
       if (restored.ok) {
+        this.linkOrAbandon(roomId, existingSessionId, generation);
         this.activeSessions.add(existingSessionId);
         this.bootstrappedSessions.add(existingSessionId);
-        await this.applyRequestedPermissionMode(connection, existingSessionId, restored.modes);
+        await this.configureSessionMode(roomId, existingSessionId, restored.modes, connection);
         return existingSessionId;
       }
     }
-    const created = await connection.newSession({
+    const created = await this.raceAgainstConnectionClose(connection, connection.newSession({
       cwd: this.cwd,
       mcpServers
-    });
-    this.roomToSession.set(roomId, created.sessionId);
+    }));
+    this.linkOrAbandon(roomId, created.sessionId, generation);
     this.activeSessions.add(created.sessionId);
-    await this.applyRequestedPermissionMode(connection, created.sessionId, created.modes);
+    await this.configureSessionMode(roomId, created.sessionId, created.modes, connection);
     return created.sessionId;
   }
-  async tryRestoreSession(connection, sessionId, mcpServers) {
-    const capabilities = this.connectionState?.agentCapabilities;
-    const params = { cwd: this.cwd, mcpServers, sessionId };
-    const restore = capabilities?.loadSession ? () => connection.loadSession(params) : capabilities?.sessionCapabilities?.resume ? () => connection.unstable_resumeSession(params) : null;
-    if (!restore) {
-      return { ok: false };
+  // The single gate an establishment must pass before it's allowed to claim
+  // the room: it must still be the room's current generation (not
+  // superseded by a teardown or a fresher establishment while this one was
+  // awaiting an RPC), and its session id must not already belong to another
+  // room. Either failure throws — this establishment cannot silently
+  // continue to activate, configure, and prompt a session it has no right
+  // to use for this room.
+  linkOrAbandon(roomId, sessionId, generation) {
+    if (!this.isCurrentGeneration(roomId, generation)) {
+      throw new Error(`ACP session establishment for room "${roomId}" was superseded before it could be linked`);
     }
-    try {
-      const restored = await restore();
-      return { ok: true, modes: restored?.modes };
-    } catch {
-      return { ok: false };
+    if (!this.linkSession(roomId, sessionId)) {
+      throw new Error(`ACP session "${sessionId}" could not be linked to room "${roomId}": already routed elsewhere`);
     }
   }
   // Best-effort: never throws, so a mode switch going wrong can't take a
   // session establishment down with it.
-  async applyRequestedPermissionMode(connection, sessionId, modes) {
-    const requestedModeId = this.requestedPermissionMode;
-    if (!requestedModeId || !modes || modes.currentModeId === requestedModeId) {
+  async configureSessionMode(roomId, sessionId, modes, connection) {
+    if (!this.resolveSessionMode || !modes) {
       return;
     }
     const availableModes = Array.isArray(modes.availableModes) ? modes.availableModes : [];
-    if (!availableModes.some((mode) => mode?.id === requestedModeId)) {
-      this.safeWarn("requested permission mode is not advertised by this session", {
+    if (availableModes.length === 0) {
+      return;
+    }
+    const selectedModeId = await this.resolveSessionModeManually(
+      (signal) => this.resolveSessionMode({
+        roomId,
+        sessionId,
+        currentModeId: modes.currentModeId,
+        modes: availableModes
+      }, signal),
+      connection.signal
+    );
+    if (!selectedModeId || selectedModeId === modes.currentModeId) {
+      return;
+    }
+    if (!availableModes.some((mode) => mode?.id === selectedModeId)) {
+      this.safeWarn("resolveSessionMode selected a mode id this session does not advertise", {
         sessionId,
-        requestedModeId,
+        selectedModeId,
         availableModeIds: availableModes.map((mode) => mode?.id)
       });
       return;
     }
     try {
       await withTimeout(
-        connection.setSessionMode({ sessionId, modeId: requestedModeId }),
+        connection.setSessionMode({ sessionId, modeId: selectedModeId }),
         SET_SESSION_MODE_TIMEOUT_MS,
         `setSessionMode did not respond within ${SET_SESSION_MODE_TIMEOUT_MS}ms`
       );
     } catch (error) {
-      this.safeWarn("failed to switch session into the requested permission mode", {
+      this.safeWarn("failed to switch session into the selected mode", {
         sessionId,
-        requestedModeId,
+        selectedModeId,
         error: String(error)
       });
     }
   }
+  async resolveSessionModeManually(resolver, signal) {
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    signal.addEventListener("abort", abort, { once: true });
+    let timer;
+    try {
+      const cancelled = new Promise((resolve) => {
+        controller.signal.addEventListener("abort", () => resolve(void 0), { once: true });
+      });
+      const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(void 0), this.permissionTimeoutMs);
+      });
+      return await Promise.race([
+        Promise.resolve().then(() => resolver(controller.signal)).catch((error) => {
+          this.safeWarn("resolveSessionMode threw; preserving the harness default", { error: String(error) });
+          return void 0;
+        }),
+        timeout,
+        cancelled
+      ]);
+    } finally {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", abort);
+      controller.abort();
+    }
+  }
+  async tryRestoreSession(connection, sessionId, mcpServers) {
+    const capabilities = this.connectionState?.agentCapabilities;
+    const params = { cwd: this.cwd, mcpServers, sessionId };
+    const restore = capabilities?.loadSession ? () => connection.loadSession(params) : capabilities?.sessionCapabilities?.resume ? () => connection.unstable_resumeSession(params) : null;
+    if (!restore) {
+      return { ok: false };
+    }
+    try {
+      const restored = await this.raceAgainstConnectionClose(connection, restore());
+      return { ok: true, modes: restored?.modes };
+    } catch {
+      return { ok: false };
+    }
+  }
   async buildSessionMcpServers() {
     const mcpServers = [...this.mcpServers];
     if (!this.enableMcpTools) {
@@ -2531,6 +2677,36 @@ ${messageWithContext}`;
       "All Band MCP tool calls must include room_id."
     ].join("\n");
   }
+  // The connection's single permission entry point, and total by
+  // construction: every path resolves, nothing throws, and a request that
+  // can't be attributed to a live room is cancelled *and* warned rather than
+  // silently declined. `activeSessions` is the gate that keeps a dead
+  // session from raising a live prompt — `roomToSession` deliberately
+  // outlives a dropped connection so the session can be restored later.
+  async routePermissionRequest(params) {
+    const isActive = this.activeSessions.has(params.sessionId);
+    const roomId = isActive ? this.sessionToRoom.get(params.sessionId) : void 0;
+    const tools = roomId === void 0 ? void 0 : this.roomTools.get(roomId);
+    if (roomId === void 0 || !tools) {
+      this.safeWarn("cancelling a permission request that maps to no live room", {
+        sessionId: params.sessionId,
+        toolName: params.toolCall?.title,
+        sessionActive: isActive,
+        roomId
+      });
+      return { outcome: { outcome: "cancelled" } };
+    }
+    try {
+      return await this.handlePermissionRequest(tools, roomId, params);
+    } catch (error) {
+      this.safeWarn("permission handling failed; cancelling the request", {
+        sessionId: params.sessionId,
+        roomId,
+        error: String(error)
+      });
+      return { outcome: { outcome: "cancelled" } };
+    }
+  }
   async handlePermissionRequest(tools, roomId, params) {
     const toolName = params.toolCall.title ?? "unknown";
     const autoSelection = this.resolvePermission ? void 0 : choosePermissionOption(params.options);
@@ -2538,28 +2714,52 @@ ${messageWithContext}`;
     if (controller) {
       this.trackPending(params.sessionId, controller);
     }
-    const [, chosenId] = await Promise.all([
-      // This is the room's only "a permission request is pending" signal,
-      // and the only one other room participants ever see — started
-      // immediately rather than serialized in front of a manual wait that
-      // can take up to `permissionTimeoutMs`.
+    let requestEventFailed = false;
+    const [, resolvedChosenId] = await Promise.all([
+      // Started immediately rather than serialized in front of a manual
+      // wait that can take up to `permissionTimeoutMs`.
       tools.sendEvent(`Permission requested: ${toolName}`, "tool_call", {
         permission_request: true,
         tool_name: toolName,
         tool_call_id: params.toolCall.toolCallId,
         acp_session_id: params.sessionId,
         auto_allowed: autoSelection !== void 0 && autoSelection !== null
+      }).catch((error) => {
+        requestEventFailed = true;
+        this.safeWarn("failed to post the permission-requested event; cancelling the request", {
+          roomId,
+          sessionId: params.sessionId,
+          error: String(error)
+        });
+        if (controller) {
+          this.abandon(controller, "no-answer");
+        }
       }),
-      controller ? this.resolveManually(params.sessionId, params, controller) : Promise.resolve(autoSelection?.optionId)
+      controller ? this.resolveManually(roomId, params, controller) : Promise.resolve(autoSelection?.optionId)
     ]);
-    return this.toResponse(chosenId, params.options);
+    const chosenId = requestEventFailed ? void 0 : resolvedChosenId;
+    const response = this.toResponse(chosenId, params.options, { roomId, sessionId: params.sessionId });
+    if (controller && !controller.signal.aborted) {
+      this.abandon(controller, response.outcome.outcome === "selected" ? "settled" : "no-answer");
+    }
+    return response;
   }
   // `undefined`, or an id absent from this request's own `options` (a buggy
   // or stale caller), both map to `cancelled` — never silently treated as a
   // deny. A real match, reject-kind options included, maps to `selected`.
-  toResponse(chosenId, options) {
-    const matched = chosenId !== void 0 && options.some((option) => option.optionId === chosenId);
-    return matched ? { outcome: { outcome: "selected", optionId: chosenId } } : { outcome: { outcome: "cancelled" } };
+  toResponse(chosenId, options, context) {
+    if (chosenId === void 0) {
+      return { outcome: { outcome: "cancelled" } };
+    }
+    if (!options.some((option) => option.optionId === chosenId)) {
+      this.safeWarn("resolvePermission chose an option this request does not offer", {
+        ...context,
+        chosenId,
+        optionIds: options.map((option) => option.optionId)
+      });
+      return { outcome: { outcome: "cancelled" } };
+    }
+    return { outcome: { outcome: "selected", optionId: chosenId } };
   }
   // A caller-supplied `Logger` isn't guaranteed to be synchronous or
   // non-throwing. Every best-effort warning in this file routes through here
@@ -2573,40 +2773,55 @@ ${messageWithContext}`;
     } catch {
     }
   }
-  // Races the caller-supplied resolver against a timeout and against
-  // `controller`'s own abort signal — aborted externally by
-  // `cancelPendingPermissions`/`cancelAllPendingPermissions` (fired from
-  // `onCleanup`/`stop()` below) when a room or the whole adapter tears down
-  // while this is still pending. `controller` is the same object tracked in
-  // `pendingPermissions` by the caller, so there is exactly one cancellation
-  // channel here, not a second hand-rolled one alongside it.
-  async resolveManually(sessionId, params, controller) {
-    let timer;
-    const cancelled = new Promise((resolve) => {
+  // Races the caller-supplied resolver against `controller`'s abort signal,
+  // which is the request's single termination channel: the timeout below
+  // fires it with `"timeout"`, and `cancelPendingPermissions` /
+  // `cancelAllPendingPermissions` fire it with the reason their caller
+  // supplies. `controller` is the same object tracked in `pendingPermissions`,
+  // so there is exactly one cancellation channel here, not a second
+  // hand-rolled one alongside it.
+  async resolveManually(roomId, params, controller) {
+    const abandoned = new Promise((resolve) => {
       controller.signal.addEventListener("abort", () => resolve(void 0));
     });
+    const timer = setTimeout(() => this.abandon(controller, "timeout"), this.permissionTimeoutMs);
     try {
-      const timeout = new Promise((resolve) => {
-        timer = setTimeout(() => resolve(void 0), this.permissionTimeoutMs);
-      });
       return await Promise.race([
         // `resolvePermission` is caller-supplied; nothing guarantees it's
         // `async` or otherwise well-behaved. `Promise.resolve().then(...)`
         // normalizes a synchronous throw the same way it normalizes a
         // rejected promise, so both land in the `.catch` below rather than
         // escaping this race uncaught.
-        Promise.resolve().then(() => this.resolvePermission(params, controller.signal)).catch((error) => {
+        Promise.resolve().then(() => this.resolvePermission({ ...params, roomId }, controller.signal)).then((chosenId) => this.discardLateAnswer(chosenId, controller, roomId, params.sessionId)).catch((error) => {
           this.safeWarn("resolvePermission threw; treating as no answer", { error: String(error) });
           return void 0;
         }),
-        timeout,
-        cancelled
+        abandoned
       ]);
     } finally {
       clearTimeout(timer);
-      this.untrackPending(sessionId, controller);
-      controller.abort();
+      this.untrackPending(params.sessionId, controller);
+    }
+  }
+  // An answer that lands after the request was given up on can no longer be
+  // honoured — the response has already gone back to the agent. It is dropped
+  // either way; warning is what makes "my click did nothing" explicable.
+  discardLateAnswer(chosenId, controller, roomId, sessionId) {
+    if (!controller.signal.aborted || chosenId === void 0) {
+      return chosenId;
     }
+    this.safeWarn("resolvePermission answered after the request was abandoned; discarding", {
+      roomId,
+      sessionId,
+      chosenId,
+      reason: String(controller.signal.reason)
+    });
+    return void 0;
+  }
+  // The only place a permission's controller is ever aborted, so every
+  // `signal.reason` a consumer can observe comes from the documented union.
+  abandon(controller, reason) {
+    controller.abort(reason);
   }
   trackPending(sessionId, controller) {
     const pending = this.pendingPermissions.get(sessionId) ?? /* @__PURE__ */ new Set();
@@ -2620,14 +2835,14 @@ ${messageWithContext}`;
       this.pendingPermissions.delete(sessionId);
     }
   }
-  cancelPendingPermissions(sessionId) {
+  cancelPendingPermissions(sessionId, reason) {
     for (const controller of this.pendingPermissions.get(sessionId) ?? []) {
-      controller.abort();
+      this.abandon(controller, reason);
     }
   }
-  cancelAllPendingPermissions() {
+  cancelAllPendingPermissions(reason) {
     for (const sessionId of this.pendingPermissions.keys()) {
-      this.cancelPendingPermissions(sessionId);
+      this.cancelPendingPermissions(sessionId, reason);
     }
   }
   async flushChunks(input) {