macro-agent 0.1.12 → 0.2.0

package/src/dispatch/permission-overlay.ts

@@ -0,0 +1,89 @@
+/**
+ * Permission Overlay Registry
+ *
+ * Process-singleton map of `agentId → Permissions` for in-flight
+ * dispatches. The `PreToolUse` hook installed at spawn time consults
+ * this registry on every tool call. Dispatch consumers (e.g., the
+ * mail-inbound-reuse-consumer) set the overlay when claiming an
+ * in-flight dispatch and clear it on resolution.
+ *
+ * Why a registry rather than a per-spawn argument:
+ *   - The session is created with permissive rules at boot. The
+ *     dispatch's narrower deny rules need to apply at *call time*, not
+ *     at spawn time, because the agent already exists when the dispatch
+ *     arrives. The hook closure captures `agentId` and reads the
+ *     registry per-call so updates propagate without recreating the
+ *     session.
+ *
+ * Semantics:
+ *   - Intersection-only: the overlay can ADD denies to a session but
+ *     cannot grant new allows. If the session was spawned with broad
+ *     permissions and the overlay says `allow: [Read]`, the session's
+ *     other tools still work — the overlay only tightens.
+ *   - Single overlay per agent: `mail-inbound-reuse-consumer` already
+ *     enforces one in-flight dispatch per agent (`recipient_busy`
+ *     reject), so overwriting is safe.
+ *
+ * @module dispatch/permission-overlay
+ */
+
+export interface OverlayPermissions {
+  allow?: string[];
+  deny?: string[];
+  ask?: string[];
+}
+
+const overlays = new Map<string, OverlayPermissions>();
+
+/**
+ * Apply a permission overlay for an agent. Subsequent tool calls by
+ * that agent flow through the `PreToolUse` hook, which consults this
+ * registry. Overwrites any prior overlay for the same agent.
+ */
+export function setPermissionOverlay(
+  agentId: string,
+  perms: OverlayPermissions,
+): void {
+  overlays.set(agentId, perms);
+}
+
+/**
+ * Remove the active overlay for an agent. Subsequent tool calls fall
+ * back to the session's static permission rules.
+ */
+export function clearPermissionOverlay(agentId: string): void {
+  overlays.delete(agentId);
+}
+
+/**
+ * Read the current overlay for an agent. Returns `undefined` when no
+ * overlay is in effect — the hook treats that as pass-through.
+ */
+export function getPermissionOverlay(
+  agentId: string,
+): OverlayPermissions | undefined {
+  return overlays.get(agentId);
+}
+
+/**
+ * Clear all overlays. Used as defense-in-depth when a fresh consumer
+ * starts (process startup); also exposed for test isolation.
+ */
+export function clearAllPermissionOverlays(): void {
+  overlays.clear();
+}
+
+/**
+ * Test helper — alias for `clearAllPermissionOverlays`. Kept distinct
+ * so it's grep-able for "test-only" cleanup paths.
+ */
+export function _resetForTest(): void {
+  overlays.clear();
+}
+
+/**
+ * Test helper — number of overlays currently active.
+ */
+export function _sizeForTest(): number {
+  return overlays.size;
+}

package/src/dispatch/permissions-handler.ts

@@ -0,0 +1,112 @@
+/**
+ * `x-dispatch/permissions.set` and `x-dispatch/permissions.clear` MAP
+ * notification handlers — runtime-agnostic wire shape, macro-agent-specific
+ * implementation.
+ *
+ * Called by OpenHive's orchestrator on the ACP+reuse dispatch path to apply
+ * per-dispatch loadout deny/allow rules to a long-lived agent's session at
+ * runtime, without recreating the session. The handler invokes
+ * `setPermissionOverlay` (resp. `clearPermissionOverlay`); the prompt
+ * iterator in `agent-manager-v2.ts` enforces the overlay against
+ * `permission_request` ACP session updates.
+ *
+ * See `docs/PERMISSION_OVERLAY_ACP_DESIGN.md` for the four-process flow
+ * diagram and rationale. The mail+reuse path uses the same overlay
+ * registry but sets/clears it directly from `mail-inbound-reuse-consumer`
+ * (which has a clean entry point on swarm side); ACP+reuse needs this MAP
+ * wire because the dispatch's prompt arrives through the ACP server with
+ * no equivalent consumer to bracket.
+ *
+ * Wire shape (set):
+ *
+ *   request:  { agent_id: string, deny?: string[], allow?: string[] }
+ *   response: { ok: true } | { ok: false, error: string }
+ *
+ * Wire shape (clear):
+ *
+ *   request:  { agent_id: string }
+ *   response: { ok: true } | { ok: false, error: string }
+ *
+ * Notification-pair pattern matches the existing `x-dispatch/spawn-agent`
+ * handler (the MAP SDK's AgentConnection doesn't expose
+ * setRequestHandler, so we use notifications with correlation_ids).
+ */
+
+import {
+  setPermissionOverlay,
+  clearPermissionOverlay,
+} from "./permission-overlay.js";
+
+export interface PermissionsSetRequest {
+  agent_id: string;
+  deny?: string[];
+  allow?: string[];
+}
+
+export interface PermissionsClearRequest {
+  agent_id: string;
+}
+
+export type PermissionsResponse =
+  | { ok: true }
+  | { ok: false; error: string };
+
+/**
+ * Handle `x-dispatch/permissions.set.request`. Sets the per-agent overlay
+ * registry entry that the prompt iterator consults when answering
+ * `permission_request` session updates.
+ *
+ * Idempotent: re-setting on the same agent overwrites the prior overlay.
+ * Safe: returns an error response (rather than throwing) for malformed
+ * params or unknown agents — the orchestrator should log and proceed.
+ */
+export function handlePermissionsSet(
+  params: PermissionsSetRequest,
+  log: (msg: string) => void = console.log,
+): PermissionsResponse {
+  if (!params || typeof params.agent_id !== "string" || params.agent_id === "") {
+    return { ok: false, error: "x-dispatch/permissions.set: missing or invalid 'agent_id'" };
+  }
+  if (params.deny !== undefined && !Array.isArray(params.deny)) {
+    return { ok: false, error: "x-dispatch/permissions.set: 'deny' must be an array of strings" };
+  }
+  if (params.allow !== undefined && !Array.isArray(params.allow)) {
+    return { ok: false, error: "x-dispatch/permissions.set: 'allow' must be an array of strings" };
+  }
+
+  const overlay = {
+    ...(params.deny ? { deny: params.deny } : {}),
+    ...(params.allow ? { allow: params.allow } : {}),
+  };
+  setPermissionOverlay(params.agent_id, overlay);
+  log(
+    `[x-dispatch/permissions.set] agent=${params.agent_id} ` +
+      `deny=${params.deny?.length ?? 0} allow=${params.allow?.length ?? 0}`,
+  );
+  return { ok: true };
+}
+
+/**
+ * Handle `x-dispatch/permissions.clear.request`. Removes any overlay set
+ * on the named agent. Idempotent: clearing a non-existent overlay is a
+ * no-op success. Always paired with a prior `set` from the same dispatch;
+ * the orchestrator must guarantee `clear` runs even on dispatch failure.
+ */
+export function handlePermissionsClear(
+  params: PermissionsClearRequest,
+  log: (msg: string) => void = console.log,
+): PermissionsResponse {
+  if (!params || typeof params.agent_id !== "string" || params.agent_id === "") {
+    return { ok: false, error: "x-dispatch/permissions.clear: missing or invalid 'agent_id'" };
+  }
+  clearPermissionOverlay(params.agent_id);
+  log(`[x-dispatch/permissions.clear] agent=${params.agent_id}`);
+  return { ok: true };
+}
+
+export const X_DISPATCH_PERMISSIONS_METHODS = {
+  SET_REQUEST: "x-dispatch/permissions.set.request",
+  SET_RESPONSE: "x-dispatch/permissions.set.response",
+  CLEAR_REQUEST: "x-dispatch/permissions.clear.request",
+  CLEAR_RESPONSE: "x-dispatch/permissions.clear.response",
+} as const;

package/src/dispatch/spawn-agent-handler.ts

@@ -0,0 +1,160 @@
+/**
+ * `x-dispatch/spawn-agent` MAP request handler — runtime-agnostic wire shape,
+ * macro-agent-specific implementation.
+ *
+ * Called by OpenHive's orchestrator when ACP-routing a dispatch with
+ * `lifecycle: 'fresh'` — the hub asks the swarm to spawn a fresh agent
+ * with the materialized loadout's structured fields applied to its spawn
+ * config. The handler returns the spawned agent's id; the orchestrator
+ * then attaches an ACP stream via the existing `findAcpAgentInfo` path.
+ *
+ * Wire shape — canonical (swarm-dispatch's `RemoteSpawnRequest`):
+ *
+ *   request:
+ *     {
+ *       role: string,
+ *       capabilities_required: string[],     // e.g. ["acp"]
+ *       lifecycle: "fresh" | "reuse",
+ *       cwd?: string,
+ *       fullAutonomous?: boolean,
+ *       consumer_extensions?: {
+ *         openhive?: { loadout?: WireLoadout },   // OpenHive payload
+ *       }
+ *     }
+ *
+ *   response:
+ *     { agentId: string }
+ *
+ * Legacy shape support: pre-Tier-2 callers passed `loadout` at the top
+ * level (not under consumer_extensions). The handler accepts both for
+ * one release window — `consumer_extensions.openhive.loadout` is read
+ * first; falls back to top-level `loadout`.
+ *
+ * Symmetric with the mail path: both routes use `loadoutToSpawnOptions`
+ * to translate the wire-level loadout into macro-agent's spawn options.
+ */
+
+import type { AgentManager } from "../agent/agent-manager.js";
+import { loadoutToSpawnOptions, type WireLoadout } from "./loadout-translation.js";
+
+export interface SpawnAgentRequest {
+  role: string;
+  /** Optional cwd; defaults to the swarm's process.cwd() via agentManager. */
+  cwd?: string;
+  capabilities_required?: string[];
+  lifecycle?: "fresh" | "reuse";
+  /**
+   * @deprecated — pre-Tier-2 top-level loadout slot. Newer callers ship
+   * the loadout under `consumer_extensions.openhive.loadout`. Both
+   * shapes are accepted for one release window.
+   */
+  loadout?: WireLoadout;
+  /** Canonical consumer-extension namespace (Tier 2+). */
+  consumer_extensions?: {
+    openhive?: { loadout?: WireLoadout };
+    [otherConsumer: string]: unknown;
+  };
+  fullAutonomous?: boolean;
+  /** Optional initial task description; defaults to a placeholder so the
+   *  agent's session has *something* to render until the orchestrator's
+   *  ACP `session/prompt` arrives. */
+  task?: string;
+}
+
+export interface SpawnAgentResponse {
+  agentId: string;
+}
+
+export interface SpawnAgentHandlerDeps {
+  agentManager: AgentManager;
+  /**
+   * Optional barrier called after spawn so the spawned agent's
+   * lifecycle-bridge has had time to register its `protocols: ['acp']`
+   * capability with the hub before this handler returns. Without this
+   * the orchestrator's subsequent `findAcpAgentInfo` would race the
+   * registration and return null.
+   *
+   * Returns true once the agent is registered and ACP-capable; false on
+   * timeout. Implementations typically wait on a Promise resolved by
+   * the lifecycle-bridge's `agent.registered` callback.
+   */
+  waitForAcpRegistration?: (
+    agentId: string,
+    timeoutMs?: number,
+  ) => Promise<boolean>;
+  /** Optional logger; defaults to console.log. */
+  log?: (msg: string) => void;
+}
+
+const DEFAULT_REGISTRATION_TIMEOUT_MS = 5_000;
+
+export async function handleDispatchSpawnAgent(
+  params: SpawnAgentRequest,
+  deps: SpawnAgentHandlerDeps,
+): Promise<SpawnAgentResponse> {
+  const { agentManager, waitForAcpRegistration, log = console.log } = deps;
+
+  if (!params.role) {
+    throw new Error("x-dispatch/spawn-agent: missing 'role'");
+  }
+  if (params.lifecycle && params.lifecycle !== "fresh") {
+    throw new Error(
+      `x-dispatch/spawn-agent: lifecycle='${params.lifecycle}' not supported by this handler — ` +
+        `'reuse' is handled hub-side via findAcpAgentInfo, not via this method`,
+    );
+  }
+  // cwd is optional — agentManager.spawn defaults to its own defaultCwd
+  // (typically process.cwd() of the macro-agent process) when omitted.
+
+  // Loadout location: prefer the canonical consumer_extensions.openhive
+  // slot (Tier 2+); fall back to the top-level field (pre-Tier-2). Older
+  // hubs ship the loadout at the top level; newer hubs ship under
+  // consumer_extensions. Both work during the dual-listen window.
+  const loadout: WireLoadout | undefined =
+    params.consumer_extensions?.openhive?.loadout ?? params.loadout;
+
+  const fullAutonomous = params.fullAutonomous ?? true;
+  const spawnLoadoutOpts = loadoutToSpawnOptions(loadout, {
+    fullAutonomous,
+  });
+
+  log(
+    `[x-dispatch/spawn-agent] Spawning fresh ${params.role} cwd=${params.cwd} ` +
+      `permissions=${
+        spawnLoadoutOpts.permissions ? JSON.stringify(spawnLoadoutOpts.permissions) : "(none)"
+      } fullAutonomous=${fullAutonomous}`,
+  );
+
+  const spawned = await agentManager.spawn({
+    role: params.role,
+    ...(params.cwd ? { cwd: params.cwd } : {}),
+    parent: null,
+    // Mail-inbound and dispatch-spawned coordinators alike run under
+    // isolated settings so host-level Claude plugins don't auto-mount.
+    isolatedSettings: true,
+    task:
+      params.task ?? "Awaiting dispatch (created by dispatch/spawn-agent)",
+    ...spawnLoadoutOpts,
+  });
+
+  // Block until the lifecycle-bridge has registered ACP capabilities,
+  // otherwise the orchestrator's subsequent `findAcpAgentInfo` lookup
+  // races the registration and fails. Best-effort: a timeout returns
+  // anyway and the orchestrator will retry on its own poll.
+  if (waitForAcpRegistration) {
+    const ok = await waitForAcpRegistration(
+      spawned.id,
+      DEFAULT_REGISTRATION_TIMEOUT_MS,
+    ).catch(() => false);
+    if (!ok) {
+      log(
+        `[x-dispatch/spawn-agent] Warning: ACP registration not confirmed for ` +
+          `agent ${spawned.id} within ${DEFAULT_REGISTRATION_TIMEOUT_MS}ms; ` +
+          `orchestrator may need to retry.`,
+      );
+    }
+  }
+
+  log(`[x-dispatch/spawn-agent] Spawn complete agentId=${spawned.id}`);
+  return { agentId: spawned.id };
+}

package/src/lifecycle/handlers-v2.ts

@@ -16,6 +16,8 @@
 import type { InboxAdapter } from "../adapters/types.js";
 import type { TasksAdapter } from "../adapters/types.js";
 import type { AgentManager } from "../agent/agent-manager.js";
+import type { AgentStore } from "../agent/agent-store.js";
+import { getPermissionOverlay } from "../dispatch/permission-overlay.js";
 import type {
   LifecycleContext,
   DoneArgs,
@@ -47,6 +49,12 @@ export interface HandlerDepsV2 {
    * Without it, commits use raw git (legacy / null-workspace path).
    */
   workspaceManager?: WorkspaceManager;
+  /**
+   * Optional agent store. When provided, the done() summary is persisted in
+   * agent metadata for parentless agents (mail-inbound dispatch workers) so
+   * the dispatch reply bridge can forward it as a hub mail turn.
+   */
+  agentStore?: AgentStore;
 }
 
 // =============================================================================
@@ -210,6 +218,32 @@ async function handleWorkerDone(
     warnings.push("Failed to emit WORKER_DONE");
   }
 
+  // Step 3b: Persist `_lastSummary` to agent metadata when:
+  //   - Agent is parentless (mail-inbound fresh-spawn dispatch workers —
+  //     emitSignal is a no-op for parentless, so metadata is the only
+  //     reply-path channel), OR
+  //   - Agent is processing a dispatch (Phase 1 permission overlay set
+  //     for this agent → in-flight). Gives the mail-inbound-reuse-consumer
+  //     a metadata-side fallback for the reply summary that's
+  //     independent of whether the prompt iterator's update stream
+  //     races with ACP connection close. Applies to both parentless
+  //     AND parented in-flight agents (parented dispatch targets are
+  //     the typical mail+reuse setup).
+  const inDispatch = !!getPermissionOverlay(context.agentId);
+  if ((inDispatch || !context.parentId) && args.summary && deps.agentStore) {
+    try {
+      const existing = deps.agentStore.getAgent(context.agentId);
+      deps.agentStore.updateAgent(context.agentId, {
+        metadata: {
+          ...(existing?.metadata ?? {}),
+          _lastSummary: args.summary,
+        },
+      });
+    } catch {
+      // best effort — don't block termination
+    }
+  }
+
   // NOTE: Task transition is NOT done here — AgentManagerV2.terminate() handles
   // it to avoid double-transitioning.
 

package/src/map/__tests__/lifecycle-bridge.test.ts

@@ -363,4 +363,68 @@ describe("LifecycleBridge", () => {
       expect.objectContaining({ name: "agent-99" }),
     );
   });
+
+  // ── awaitRegistration() ─────────────────────────────────────────────
+
+  describe("awaitRegistration", () => {
+    it("returns true once map/agents/register completes (mapId populated)", async () => {
+      // Hub returns a MAP-assigned ULID for the registered agent.
+      conn.callExtension.mockResolvedValueOnce({ agent: { id: "map-ulid-A" } });
+
+      const { callback, awaitRegistration } = createLifecycleBridge(
+        conn,
+        {} as AgentStore,
+        scope,
+      );
+
+      callback({
+        type: "spawned",
+        agent: mockAgent({ id: "agent-A", role: "coordinator" }),
+      });
+
+      // The async register IIFE inside the bridge does waitForLocalMapId(~500ms)
+      // then resolves callExtension. Wait long enough for that to settle.
+      const ok = await awaitRegistration("agent-A", 2_000);
+      expect(ok).toBe(true);
+    });
+
+    it("returns false if timeout elapses before registration completes", async () => {
+      // Stall the registration call so mapId is never populated within the window.
+      let resolveExt: (value: unknown) => void = () => {};
+      conn.callExtension.mockImplementationOnce(
+        () =>
+          new Promise((resolve) => {
+            resolveExt = resolve;
+          }),
+      );
+
+      const { callback, awaitRegistration } = createLifecycleBridge(
+        conn,
+        {} as AgentStore,
+        scope,
+      );
+
+      callback({
+        type: "spawned",
+        agent: mockAgent({ id: "agent-B", role: "coordinator" }),
+      });
+
+      const ok = await awaitRegistration("agent-B", 200);
+      expect(ok).toBe(false);
+
+      // Cleanup the dangling promise so vitest doesn't warn about leaks.
+      resolveExt({ agent: { id: "map-ulid-late" } });
+    });
+
+    it("returns false for an agentId that was never spawned", async () => {
+      const { awaitRegistration } = createLifecycleBridge(
+        conn,
+        {} as AgentStore,
+        scope,
+      );
+
+      const ok = await awaitRegistration("never-spawned-agent", 150);
+      expect(ok).toBe(false);
+    });
+  });
 });

package/src/map/__tests__/mail-bridge.test.ts

@@ -0,0 +1,196 @@
+/**
+ * Unit tests for mail-bridge — verifies that hub `mail/turn.received`
+ * notifications are forwarded into the local inbox with the correct shape
+ * so createAgentInboxPort.onIncoming can classify them.
+ */
+
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { setupMailBridge, type MailBridgeConnection } from "../mail-bridge.js";
+
+// Minimal InboxAdapter mock that captures send() calls.
+function mockInboxAdapter() {
+  return {
+    registerAgent: vi.fn().mockResolvedValue(undefined),
+    send: vi.fn().mockResolvedValue("msg-001"),
+  };
+}
+
+// Minimal MAP connection mock.
+function mockConnection(): MailBridgeConnection & {
+  onNotification: ReturnType<typeof vi.fn>;
+  offNotification: ReturnType<typeof vi.fn>;
+  _fire: (params: unknown) => Promise<void>;
+} {
+  let registeredHandler: ((params: unknown) => void | Promise<void>) | null =
+    null;
+
+  const conn = {
+    onNotification: vi.fn((method: string, handler: (params: unknown) => void | Promise<void>) => {
+      if (method === "mail/turn.received") {
+        registeredHandler = handler;
+      }
+    }),
+    offNotification: vi.fn(),
+    _fire: async (params: unknown) => {
+      if (registeredHandler) await registeredHandler(params);
+    },
+  };
+  return conn;
+}
+
+describe("setupMailBridge", () => {
+  let conn: ReturnType<typeof mockConnection>;
+  let inbox: ReturnType<typeof mockInboxAdapter>;
+
+  beforeEach(() => {
+    conn = mockConnection();
+    inbox = mockInboxAdapter();
+  });
+
+  it("registers notification handler on 'mail/turn.received'", async () => {
+    await setupMailBridge({ connection: conn, inboxAdapter: inbox as any });
+    expect(conn.onNotification).toHaveBeenCalledWith(
+      "mail/turn.received",
+      expect.any(Function),
+    );
+  });
+
+  it("returns cleanup that calls offNotification", async () => {
+    const cleanup = await setupMailBridge({
+      connection: conn,
+      inboxAdapter: inbox as any,
+    });
+    cleanup();
+    expect(conn.offNotification).toHaveBeenCalledWith(
+      "mail/turn.received",
+      expect.any(Function),
+    );
+  });
+
+  it("drops non-JSON turns silently", async () => {
+    const logs: string[] = [];
+    await setupMailBridge({
+      connection: conn,
+      inboxAdapter: inbox as any,
+      log: (m) => logs.push(m),
+    });
+
+    await conn._fire({
+      conversation_id: "conv-1",
+      turn_id: "turn-1",
+      participant_id: "some-agent",
+      content_type: "text/plain",
+      content: "hello world",
+    });
+
+    expect(inbox.send).not.toHaveBeenCalled();
+    expect(logs.some((l) => l.includes("Dropping"))).toBe(true);
+  });
+
+  describe("with dispatcherAgentId", () => {
+    const DISPATCHER_ID = "dispatcher:host:1234:abc";
+
+    it("registers the dispatcher as inbox recipient", async () => {
+      await setupMailBridge({
+        connection: conn,
+        inboxAdapter: inbox as any,
+        dispatcherAgentId: DISPATCHER_ID,
+      });
+      expect(inbox.registerAgent).toHaveBeenCalledWith(
+        DISPATCHER_ID,
+        expect.objectContaining({ role: "dispatcher" }),
+      );
+    });
+
+    it("translates hub envelope { type, body } → { schema, data } and delivers to dispatcher", async () => {
+      await setupMailBridge({
+        connection: conn,
+        inboxAdapter: inbox as any,
+        dispatcherAgentId: DISPATCHER_ID,
+      });
+
+      const hubEnvelope = {
+        type: "x-dispatch/work",
+        body: { prompt: "do the thing", taskId: "task-123", role: "worker" },
+      };
+
+      await conn._fire({
+        conversation_id: "conv-1",
+        turn_id: "turn-1",
+        participant_id: "openhive:dispatcher",
+        content_type: "application/json",
+        content: JSON.stringify(hubEnvelope),
+        thread_id: "thread-abc",
+      });
+
+      expect(inbox.send).toHaveBeenCalledOnce();
+      const [from, to, content, opts] = inbox.send.mock.calls[0];
+
+      // Must deliver FROM the hub participant, TO the dispatcher
+      expect(from).toBe("openhive:dispatcher");
+      expect(to).toBe(DISPATCHER_ID);
+
+      // Content must carry top-level `schema` and `data`, plus `type: "data"`
+      // so agent-inbox's `normalizeContent` passes it through unchanged
+      // (without a `type`, the inbox wraps the payload as { type: "data",
+      // data: <original> }, burying `schema` and breaking downstream
+      // classifiers like swarm-dispatch's createAgentInboxPort).
+      expect(content).toMatchObject({
+        type: "data",
+        schema: "x-dispatch/work",
+        data: { prompt: "do the thing", taskId: "task-123", role: "worker" },
+      });
+      expect(content).not.toHaveProperty("body");
+
+      // Thread tag preserved
+      expect(opts?.threadTag).toBe("thread-abc");
+    });
+
+    it("passes through already-canonical { schema, data } payloads unchanged", async () => {
+      await setupMailBridge({
+        connection: conn,
+        inboxAdapter: inbox as any,
+        dispatcherAgentId: DISPATCHER_ID,
+      });
+
+      // Payload already in canonical shape (no 'body' key)
+      const canonical = {
+        schema: "x-dispatch/work",
+        data: { taskId: "t-99", prompt: "go", role: "worker" },
+      };
+
+      await conn._fire({
+        conversation_id: "conv-2",
+        turn_id: "turn-2",
+        participant_id: "openhive:dispatcher",
+        content_type: "application/json",
+        content: JSON.stringify(canonical),
+      });
+
+      expect(inbox.send).toHaveBeenCalledOnce();
+      const [, , content] = inbox.send.mock.calls[0];
+      expect(content).toMatchObject(canonical);
+    });
+  });
+
+  describe("without dispatcherAgentId (fallback mode)", () => {
+    it("delivers to BRIDGE_RECIPIENT_ID", async () => {
+      await setupMailBridge({
+        connection: conn,
+        inboxAdapter: inbox as any,
+      });
+
+      await conn._fire({
+        conversation_id: "conv-3",
+        turn_id: "turn-3",
+        participant_id: "openhive:dispatcher",
+        content_type: "application/json",
+        content: JSON.stringify({ schema: "x-dispatch/work", data: { taskId: "t-1" } }),
+      });
+
+      expect(inbox.send).toHaveBeenCalledOnce();
+      const [, to] = inbox.send.mock.calls[0];
+      expect(to).toBe("openhive-mail-bridge");
+    });
+  });
+});