@bastani/atomic 0.9.9 → 0.9.10

package/dist/builtin/intercom/broker/client-message-validation.ts

@@ -0,0 +1,39 @@
+import type { Attachment, Message, SessionInfo } from "../types.js";
+
+function isAttachment(value: unknown): value is Attachment {
+  if (typeof value !== "object" || value === null) return false;
+  const attachment = value as Record<string, unknown>;
+  if (attachment.type !== "file" && attachment.type !== "snippet" && attachment.type !== "context") return false;
+  if (typeof attachment.name !== "string" || typeof attachment.content !== "string") return false;
+  return attachment.language === undefined || typeof attachment.language === "string";
+}
+
+export function isMessage(value: unknown): value is Message {
+  if (typeof value !== "object" || value === null) return false;
+  const message = value as Record<string, unknown>;
+  if (typeof message.id !== "string" || typeof message.timestamp !== "number") return false;
+  if (message.replyTo !== undefined && typeof message.replyTo !== "string") return false;
+  if (message.expectsReply !== undefined && typeof message.expectsReply !== "boolean") return false;
+  if (message.replyError !== undefined && typeof message.replyError !== "string") return false;
+  if (typeof message.content !== "object" || message.content === null) return false;
+  const content = message.content as Record<string, unknown>;
+  if (typeof content.text !== "string") return false;
+  return content.attachments === undefined
+    || (Array.isArray(content.attachments) && content.attachments.every(isAttachment));
+}
+
+export function isSessionInfo(value: unknown): value is SessionInfo {
+  if (typeof value !== "object" || value === null) return false;
+  const session = value as Record<string, unknown>;
+  if (
+    typeof session.id !== "string"
+    || typeof session.cwd !== "string"
+    || typeof session.model !== "string"
+    || typeof session.pid !== "number"
+    || typeof session.startedAt !== "number"
+    || typeof session.lastActivity !== "number"
+  ) return false;
+  if (session.name !== undefined && typeof session.name !== "string") return false;
+  if (session.group !== undefined && typeof session.group !== "string") return false;
+  return session.status === undefined || typeof session.status === "string";
+}

package/dist/builtin/intercom/broker/client.ts

@@ -3,126 +3,65 @@ import net from "net";
 import { randomUUID } from "crypto";
 import { writeMessage, createMessageReader } from "./framing.js";
 import { getBrokerSocketPath } from "./paths.js";
-import type { SessionInfo, Message, Attachment } from "../types.js";
+import type { SessionInfo, Message, Attachment, SupervisorRegistration } from "../types.js";
 import { buildSendSignature, PendingSendRegistry } from "./pending-send-registry.js";
 import { readSubagentMessageSource } from "../source-ownership.js";
+import { isMessage, isSessionInfo } from "./client-message-validation.js";
 
 const BROKER_SOCKET = getBrokerSocketPath();
 
-interface SendOptions {
+export interface SendOptions {
   text: string;
   attachments?: Attachment[];
   replyTo?: string;
   expectsReply?: boolean;
+  replyError?: string;
   messageId?: string;
 }
 
-interface SendResult {
+export interface SendResult {
   id: string;
   delivered: boolean;
   reason?: string;
 }
 
-function toError(error: unknown): Error {
-  return error instanceof Error ? error : new Error(String(error));
-}
-
-function isAttachment(value: unknown): value is Attachment {
-  if (typeof value !== "object" || value === null) {
-    return false;
-  }
-
-  const attachment = value as Record<string, unknown>;
-
-  if (
-    attachment.type !== "file"
-    && attachment.type !== "snippet"
-    && attachment.type !== "context"
-  ) {
-    return false;
-  }
-
-  if (typeof attachment.name !== "string" || typeof attachment.content !== "string") {
-    return false;
-  }
-
-  return attachment.language === undefined || typeof attachment.language === "string";
+export interface SupervisorAuthorization extends SupervisorRegistration {
+  childName: string;
 }
 
-function isMessage(value: unknown): value is Message {
-  if (typeof value !== "object" || value === null) {
-    return false;
-  }
-
-  const message = value as Record<string, unknown>;
-
-  if (typeof message.id !== "string" || typeof message.timestamp !== "number") {
-    return false;
-  }
-
-  if (message.replyTo !== undefined && typeof message.replyTo !== "string") {
-    return false;
-  }
-
-  if (message.expectsReply !== undefined && typeof message.expectsReply !== "boolean") {
-    return false;
-  }
-
-  if (typeof message.content !== "object" || message.content === null) {
-    return false;
-  }
-
-  const content = message.content as Record<string, unknown>;
-  if (typeof content.text !== "string") {
-    return false;
-  }
-
-  return content.attachments === undefined
-    || (Array.isArray(content.attachments) && content.attachments.every(isAttachment));
+function toError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
 }
 
-function isSessionInfo(value: unknown): value is SessionInfo {
-  if (typeof value !== "object" || value === null) {
-    return false;
-  }
-
-  const session = value as Record<string, unknown>;
-
-  if (
-    typeof session.id !== "string"
-    || typeof session.cwd !== "string"
-    || typeof session.model !== "string"
-    || typeof session.pid !== "number"
-    || typeof session.startedAt !== "number"
-    || typeof session.lastActivity !== "number"
-  ) {
-    return false;
-  }
-
-  if (session.name !== undefined && typeof session.name !== "string") {
-    return false;
-  }
-
-  return session.status === undefined || typeof session.status === "string";
-}
 
 export class IntercomClient extends EventEmitter {
   private socket: net.Socket | null = null;
   private _sessionId: string | null = null;
+  private _supervisorSessionId: string | null = null;
   private pendingSends = new PendingSendRegistry();
   private pendingLists = new Map<string, { resolve: (sessions: SessionInfo[]) => void; reject: (e: Error) => void }>();
+  private pendingSupervisorAuthorizations = new Map<string, {
+    resolve: (authorization: SupervisorAuthorization) => void;
+    reject: (error: Error) => void;
+  }>();
   private disconnecting = false;
   private disconnectError: Error | null = null;
 
   private failPending(error: Error): void {
     this.pendingSends.rejectAll(error);
     for (const pending of this.pendingLists.values()) pending.reject(error);
+    for (const pending of this.pendingSupervisorAuthorizations.values()) pending.reject(error);
     this.pendingLists.clear();
+    this.pendingSupervisorAuthorizations.clear();
   }
 
   get sessionId(): string | null {
     return this._sessionId;
   }
+  get supervisorSessionId(): string | null {
+    return this._supervisorSessionId;
+  }
+
 
   isConnected(): boolean {
     const socket = this.socket;
@@ -146,7 +85,7 @@ export class IntercomClient extends EventEmitter {
     return socket;
   }
 
-  connect(session: Omit<SessionInfo, "id">): Promise<void> {
+  connect(session: Omit<SessionInfo, "id">, supervisor?: SupervisorRegistration, supervisorOwnerToken?: string): Promise<void> {
     if (this.socket) {
       return Promise.reject(new Error("Already connected"));
     }
@@ -176,6 +115,7 @@ export class IntercomClient extends EventEmitter {
         cleanupConnectionAttempt();
         resolve();
       };
+      const onRegistrationFailed = (error: Error) => onError(error);
       
       const onError = (err: Error) => {
         settled = true;
@@ -200,6 +140,7 @@ export class IntercomClient extends EventEmitter {
           this.socket = null;
         }
         this._sessionId = null;
+        this._supervisorSessionId = null;
         this.disconnectError = null;
         if (connectionEstablished && !wasDisconnecting) {
           this.emit("disconnected", disconnectError);
@@ -233,6 +174,7 @@ export class IntercomClient extends EventEmitter {
       
       const cleanupConnectionAttempt = () => {
         this.off("_registered", onRegistered);
+        this.off("_registration_failed", onRegistrationFailed);
         socket.off("error", onError);
         clearTimeout(timeout);
       };
@@ -249,9 +191,15 @@ export class IntercomClient extends EventEmitter {
       
       socket.on("error", onSocketError);
       this.once("_registered", onRegistered);
+      this.once("_registration_failed", onRegistrationFailed);
       
       try {
-        writeMessage(socket, { type: "register", session });
+        writeMessage(socket, {
+          type: "register",
+          session,
+          ...(supervisor ? { supervisor } : {}),
+          ...(supervisorOwnerToken ? { supervisorOwnerToken } : {}),
+        });
       } catch (error) {
         cleanupConnectionAttempt();
         cleanupSocketListeners();
@@ -271,13 +219,16 @@ export class IntercomClient extends EventEmitter {
 
     const brokerMessage = msg as { type: string } & Record<string, unknown>;
 
-    if (this._sessionId === null && brokerMessage.type !== "registered") {
+    if (this._sessionId === null
+      && brokerMessage.type !== "registered"
+      && brokerMessage.type !== "registration_failed") {
       throw new Error(`Received ${brokerMessage.type} before registered`);
     }
 
     switch (brokerMessage.type) {
       case "registered": {
-        if (typeof brokerMessage.sessionId !== "string") {
+        if (typeof brokerMessage.sessionId !== "string"
+          || (brokerMessage.supervisorSessionId !== undefined && typeof brokerMessage.supervisorSessionId !== "string")) {
           throw new Error("Invalid registered message");
         }
 
@@ -285,9 +236,17 @@ export class IntercomClient extends EventEmitter {
           throw new Error("Received duplicate registered message");
         }
         this._sessionId = brokerMessage.sessionId;
+        this._supervisorSessionId = typeof brokerMessage.supervisorSessionId === "string"
+          ? brokerMessage.supervisorSessionId
+          : null;
         this.emit("_registered", { type: "registered", sessionId: brokerMessage.sessionId });
         break;
       }
+      case "registration_failed": {
+        if (typeof brokerMessage.reason !== "string") throw new Error("Invalid registration_failed message");
+        this.emit("_registration_failed", new Error(brokerMessage.reason));
+        break;
+      }
       case "sessions": {
         const { requestId, sessions } = brokerMessage;
         if (typeof requestId !== "string" || !Array.isArray(sessions) || !sessions.every(isSessionInfo)) {
@@ -302,12 +261,24 @@ export class IntercomClient extends EventEmitter {
         pending.resolve(sessions);
         break;
       }
+      case "supervisor_authorized": {
+        const { requestId, capability, supervisorSessionId, childName } = brokerMessage;
+        if (typeof requestId !== "string" || typeof capability !== "string"
+          || typeof supervisorSessionId !== "string" || typeof childName !== "string") {
+          throw new Error("Invalid supervisor_authorized message");
+        }
+        const pending = this.pendingSupervisorAuthorizations.get(requestId);
+        if (!pending) return;
+        this.pendingSupervisorAuthorizations.delete(requestId);
+        pending.resolve({ capability, supervisorSessionId, childName });
+        break;
+      }
       case "message": {
-        const { from, message } = brokerMessage;
-        if (!isSessionInfo(from) || !isMessage(message)) {
+        const { from, message, channel } = brokerMessage;
+        if (!isSessionInfo(from) || !isMessage(message) || (channel !== undefined && channel !== "supervisor")) {
           throw new Error("Invalid message event");
         }
-        this.emit("message", from, message);
+        this.emit("message", from, message, channel);
         break;
       }
       case "delivered": {
@@ -400,7 +371,7 @@ export class IntercomClient extends EventEmitter {
       }
     });
   }
-  listSessions(): Promise<SessionInfo[]> {
+  listSessions(group?: string): Promise<SessionInfo[]> {
     let socket: net.Socket;
     try {
       socket = this.requireActiveSocket();
@@ -425,7 +396,7 @@ export class IntercomClient extends EventEmitter {
       }, 5000);
       this.pendingLists.set(requestId, { resolve: wrappedResolve, reject: wrappedReject });
       try {
-        writeMessage(socket, { type: "list", requestId });
+        writeMessage(socket, group === undefined ? { type: "list", requestId } : { type: "list", requestId, group });
       } catch (error) {
         clearTimeout(timeout);
         this.pendingLists.delete(requestId);
@@ -433,7 +404,45 @@ export class IntercomClient extends EventEmitter {
       }
     });
   }
+  authorizeSupervisorChild(childName: string, capability?: string): Promise<SupervisorAuthorization> {
+    let socket: net.Socket;
+    try {
+      socket = this.requireActiveSocket();
+    } catch (error) {
+      return Promise.reject(toError(error));
+    }
+    const normalizedChildName = childName.trim();
+    if (!normalizedChildName) return Promise.reject(new Error("Child session name is required"));
+    return new Promise((resolve, reject) => {
+      const requestId = randomUUID();
+      const timeout = setTimeout(() => {
+        if (!this.pendingSupervisorAuthorizations.delete(requestId)) return;
+        reject(new Error("Supervisor authorization timeout"));
+      }, 5000);
+      this.pendingSupervisorAuthorizations.set(requestId, {
+        resolve: (authorization) => { clearTimeout(timeout); resolve(authorization); },
+        reject: (error) => { clearTimeout(timeout); reject(error); },
+      });
+      try {
+        writeMessage(socket, capability
+          ? { type: "authorize_supervisor", requestId, childName: normalizedChildName, capability }
+          : { type: "authorize_supervisor", requestId, childName: normalizedChildName });
+      } catch (error) {
+        clearTimeout(timeout);
+        this.pendingSupervisorAuthorizations.delete(requestId);
+        reject(toError(error));
+      }
+    });
+  }
   send(to: string, options: SendOptions): Promise<SendResult> {
+    return this.sendFrame("send", to, options);
+  }
+
+  sendToSupervisor(to: string, options: SendOptions): Promise<SendResult> {
+    return this.sendFrame("supervisor_send", to, options);
+  }
+
+  private sendFrame(type: "send" | "supervisor_send", to: string, options: SendOptions): Promise<SendResult> {
     let socket: net.Socket;
     try {
       socket = this.requireActiveSocket();
@@ -448,17 +457,17 @@ export class IntercomClient extends EventEmitter {
       return Promise.reject(toError(error));
     }
     if (!acquired.owner) return acquired.attempt.promise;
-
     const message: Message = {
       id: messageId,
       timestamp: Date.now(),
       replyTo: options.replyTo,
       expectsReply: options.expectsReply,
+      replyError: options.replyError,
       source: readSubagentMessageSource(),
       content: { text: options.text, attachments: options.attachments },
     };
     try {
-      writeMessage(socket, { type: "send", to, message, attemptId: acquired.attempt.attemptId });
+      writeMessage(socket, { type, to, message, attemptId: acquired.attempt.attemptId });
     } catch (error) {
       this.pendingSends.reject(acquired.attempt, toError(error));
     }

package/dist/builtin/intercom/broker/group-isolation.ts

@@ -0,0 +1,28 @@
+import type { SessionInfo } from "../types.js";
+import { normalizeGroup } from "../group.js";
+import type { SupervisorChannelCache } from "./supervisor-channel.js";
+
+/** Two sessions share a group when their normalized group ids are equal. */
+export function sameGroup(a: SessionInfo, b: SessionInfo): boolean {
+  return normalizeGroup(a.group) === normalizeGroup(b.group);
+}
+
+export interface VerticalBypassInput {
+  /** Reply correlation id, when this send is a reply. */
+  replyTo?: string;
+  sender: SessionInfo;
+  target: SessionInfo;
+  supervisorCache: SupervisorChannelCache;
+}
+
+/**
+ * Only an exact reverse reply to a broker-recorded supervisor crossing may
+ * bypass peer-group isolation. Initial supervisor sends are authorized and
+ * routed separately; no client-authored marker reaches this decision point.
+ */
+export function isVerticalBypass(input: VerticalBypassInput): boolean {
+  if (input.replyTo) {
+    return input.supervisorCache.matchReply(input.replyTo, input.sender.id, input.target.id);
+  }
+  return false;
+}

package/dist/builtin/intercom/broker/send-handler.ts

@@ -3,10 +3,17 @@ import type { Attachment, BrokerMessage, Message, SessionInfo } from "../types.j
 import { resolveSessionTarget, sessionTargetFailureReason } from "../session-target.js";
 import { DeliveredMessageCache } from "./delivered-message-cache.js";
 import { buildMessageSendSignature } from "./send-signature.js";
+import { SupervisorChannelCache } from "./supervisor-channel.js";
+import { isVerticalBypass, sameGroup } from "./group-isolation.js";
+import { normalizeGroup } from "../group.js";
 
 export interface BrokerConnectedSession {
   socket: net.Socket;
   info: SessionInfo;
+  /** Broker-bound supervisor relationship established by a capability. */
+  supervisorId?: string;
+  /** Private issuer identity used to restore child capabilities after reconnects. */
+  supervisorOwnerToken?: string;
 }
 
 interface SendClientMessage extends Record<string, unknown> {
@@ -41,6 +48,7 @@ export function handleBrokerSend(
   sessions: Map<string, BrokerConnectedSession>,
   deliveredMessages: DeliveredMessageCache,
   write: (target: net.Socket, message: BrokerMessage) => void,
+  supervisorCache: SupervisorChannelCache = new SupervisorChannelCache(),
 ): void {
   const message = clientMessage.message;
   const messageId = isMessage(message) ? message.id : "unknown";
@@ -58,6 +66,11 @@ export function handleBrokerSend(
     write(socket, { type: "delivery_failed", messageId, attemptId, reason: "Invalid message format" });
     return;
   }
+  if (Object.prototype.hasOwnProperty.call(clientMessage, "channel")) {
+    write(socket, { type: "delivery_failed", messageId: message.id, attemptId, reason: "Invalid channel" });
+    return;
+  }
+  const supervisorSend = clientMessage.type === "supervisor_send";
 
   const signature = buildMessageSendSignature(clientMessage.to, message);
   const deliveredMatch = deliveredMessages.lookup(message.id, signature);
@@ -75,17 +88,38 @@ export function handleBrokerSend(
     return;
   }
 
-  const resolution = resolveSessionTarget(
-    Array.from(sessions.values(), (session) => session.info),
-    clientMessage.to,
-  );
+  const fromSession = currentId ? sessions.get(currentId) : undefined;
+  if (!fromSession) {
+    write(socket, { type: "delivery_failed", messageId: message.id, attemptId, reason: "Sender session not found" });
+    return;
+  }
+  const trimmedTo = clientMessage.to.trim();
+  if (supervisorSend && !fromSession.supervisorId) {
+    write(socket, { type: "delivery_failed", messageId: message.id, attemptId, reason: "Supervisor channel is not authorized" });
+    return;
+  }
+  if (supervisorSend && trimmedTo !== fromSession.supervisorId) {
+    write(socket, { type: "delivery_failed", messageId: message.id, attemptId, reason: "Supervisor target does not match the authorized relationship" });
+    return;
+  }
+
+
+  // Exact-id targeting always resolves against the full pool so a cross-group id
+  // is caught by the defense-in-depth group check below. Only a broker-authorized
+  // supervisor frame or an exact recorded reply may resolve across groups.
+  const exactIdTarget = sessions.get(trimmedTo);
+  const senderGroup = normalizeGroup(fromSession.info.group);
+  const reachableAcrossGroups = supervisorSend || Boolean(message.replyTo);
+  const candidates = reachableAcrossGroups
+    ? Array.from(sessions.values(), (session) => session.info)
+    : Array.from(sessions.values(), (session) => session.info).filter(
+        (info) => normalizeGroup(info.group) === senderGroup,
+      );
+  const resolution = exactIdTarget
+    ? ({ kind: "resolved", session: exactIdTarget.info } as const)
+    : resolveSessionTarget(candidates, trimmedTo);
   if (resolution.kind === "resolved") {
     const target = sessions.get(resolution.session.id);
-    const fromSession = currentId ? sessions.get(currentId) : undefined;
-    if (!fromSession) {
-      write(socket, { type: "delivery_failed", messageId: message.id, attemptId, reason: "Sender session not found" });
-      return;
-    }
     if (!target) {
       write(socket, { type: "delivery_failed", messageId: message.id, attemptId, reason: "Session not found" });
       return;
@@ -94,8 +128,26 @@ export function handleBrokerSend(
       write(socket, { type: "delivery_failed", messageId: message.id, attemptId, reason: "Cannot message the current session" });
       return;
     }
-    write(target.socket, { type: "message", from: fromSession.info, message });
+    const bypass = supervisorSend || isVerticalBypass({
+      replyTo: message.replyTo,
+      sender: fromSession.info,
+      target: target.info,
+      supervisorCache,
+    });
+    if (!bypass && !sameGroup(target.info, fromSession.info)) {
+      write(socket, {
+        type: "delivery_failed",
+        messageId: message.id,
+        attemptId,
+        reason: "Target session is in a different intercom group",
+      });
+      return;
+    }
+    write(target.socket, supervisorSend
+      ? { type: "message", from: fromSession.info, message, channel: "supervisor" }
+      : { type: "message", from: fromSession.info, message });
     deliveredMessages.record(message.id, signature);
+    if (supervisorSend) supervisorCache.record(message.id, fromSession.info.id, target.info.id);
     write(socket, { type: "delivered", messageId: message.id, attemptId });
     return;
   }

package/dist/builtin/intercom/broker/send-signature.ts

@@ -5,6 +5,7 @@ export interface LogicalSendOptions {
   attachments?: Attachment[];
   replyTo?: string;
   expectsReply?: boolean;
+  replyError?: string;
 }
 
 function normalizeAttachments(attachments: Attachment[] | undefined): Array<Record<string, string>> | undefined {
@@ -24,6 +25,7 @@ export function buildSendSignature(to: string, options: LogicalSendOptions): str
     attachments: normalizeAttachments(options.attachments) ?? [],
     replyTo: options.replyTo ?? null,
     expectsReply: options.expectsReply ?? false,
+    replyError: options.replyError ?? null,
   });
 }
 
@@ -33,5 +35,6 @@ export function buildMessageSendSignature(to: string, message: Message): string
     attachments: message.content.attachments,
     replyTo: message.replyTo,
     expectsReply: message.expectsReply,
+    replyError: message.replyError,
   });
 }

package/dist/builtin/intercom/broker/supervisor-channel.ts

@@ -0,0 +1,126 @@
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+
+const DEFAULT_TTL_MS = 10 * 60 * 1000;
+const DEFAULT_MAX_ENTRIES = 10_000;
+function capabilityMac(ownerToken: string, childName: string, nonce: string): Buffer {
+  return createHmac("sha256", ownerToken).update(`${nonce}\0${childName}`).digest();
+}
+
+function issueCapability(ownerToken: string, childName: string): string {
+  const nonce = randomUUID();
+  return `${nonce}.${capabilityMac(ownerToken, childName, nonce).toString("base64url")}`;
+}
+
+function ownsCapability(capability: string, ownerToken: string, childName: string): boolean {
+  const separator = capability.indexOf(".");
+  if (separator <= 0 || separator === capability.length - 1) return false;
+  const nonce = capability.slice(0, separator);
+  let supplied: Buffer;
+  try { supplied = Buffer.from(capability.slice(separator + 1), "base64url"); } catch { return false; }
+  const expected = capabilityMac(ownerToken, childName, nonce);
+  return supplied.length === expected.length && timingSafeEqual(supplied, expected);
+}
+
+
+interface SupervisorCrossing {
+  recordedAt: number;
+  fromId: string;
+  toId: string;
+}
+interface SupervisorAuthorizationRecord {
+  supervisorId: string;
+  childName: string;
+  ownerToken: string;
+  boundChildName?: string;
+}
+
+
+/**
+ * Bounded record of `contact_supervisor` vertical-channel crossings. It lets the
+ * broker permit a supervisor's reply back across peer-group isolation without
+ * opening a general "any replyTo bypasses isolation" hole: a reply is only
+ * allowed when it answers a recorded crossing in the exact opposite direction.
+ * Mirrors {@link DeliveredMessageCache} (TTL + max entries, insertion-ordered).
+ */
+export class SupervisorChannelCache {
+  private readonly crossings = new Map<string, SupervisorCrossing>();
+  private readonly authorizations = new Map<string, SupervisorAuthorizationRecord>();
+
+  constructor(
+    private readonly ttlMs = DEFAULT_TTL_MS,
+    private readonly maxEntries = DEFAULT_MAX_ENTRIES,
+  ) {}
+
+  /** Issue or restore a capability from an already registered supervisor socket. */
+  authorize(supervisorId: string, ownerToken: string, childName: string, requestedCapability?: string): string {
+    const capability = requestedCapability ?? issueCapability(ownerToken, childName);
+    if (!ownsCapability(capability, ownerToken, childName)) {
+      throw new Error("Invalid supervisor capability owner");
+    }
+    const existing = this.authorizations.get(capability);
+    if (existing && (existing.ownerToken !== ownerToken || existing.childName !== childName)) {
+      throw new Error("Supervisor capability is already owned by another relationship");
+    }
+    this.authorizations.delete(capability);
+    this.authorizations.set(capability, {
+      supervisorId,
+      childName,
+      ownerToken,
+      ...(existing?.boundChildName ? { boundChildName: existing.boundChildName } : {}),
+    });
+    while (this.authorizations.size > this.maxEntries) {
+      const oldest = this.authorizations.keys().next().value as string | undefined;
+      if (oldest === undefined) break;
+      this.authorizations.delete(oldest);
+    }
+    return capability;
+  }
+
+  /** Resolve a capability for its exact child, binding a dynamic slot on first use. */
+  claim(capability: string, childName: string): string | undefined {
+    const authorization = this.authorizations.get(capability);
+    if (!authorization) return undefined;
+    if (authorization.childName === "*") {
+      if (authorization.boundChildName && authorization.boundChildName !== childName) return undefined;
+      authorization.boundChildName = childName;
+    } else if (authorization.childName !== childName) {
+      return undefined;
+    }
+    return authorization.supervisorId;
+  }
+
+  /** Record a supervisor-channel crossing keyed by the outbound message id. */
+  record(messageId: string, fromId: string, toId: string, now = Date.now()): void {
+    this.prune(now);
+    this.crossings.delete(messageId);
+    this.crossings.set(messageId, { recordedAt: now, fromId, toId });
+    while (this.crossings.size > this.maxEntries) {
+      const oldest = this.crossings.keys().next().value as string | undefined;
+      if (oldest === undefined) break;
+      this.crossings.delete(oldest);
+    }
+  }
+
+  /**
+   * Return true when a reply (`send` with `replyTo`) answers a recorded crossing:
+   * the reply's target is the crossing's original sender AND the reply's sender is
+   * the crossing's original target. Prevents fabricated-replyTo cross-group sends.
+   */
+  matchReply(replyTo: string, replySenderId: string, replyTargetId: string, now = Date.now()): boolean {
+    this.prune(now);
+    const crossing = this.crossings.get(replyTo);
+    if (!crossing) return false;
+    if (now - crossing.recordedAt > this.ttlMs) {
+      this.crossings.delete(replyTo);
+      return false;
+    }
+    return crossing.fromId === replyTargetId && crossing.toId === replySenderId;
+  }
+
+  private prune(now: number): void {
+    for (const [messageId, crossing] of this.crossings) {
+      if (now - crossing.recordedAt <= this.ttlMs) break;
+      this.crossings.delete(messageId);
+    }
+  }
+}