@aria-cli/tools 1.0.0

package/tests/definitions/messaging.test.ts

@@ -0,0 +1,1468 @@
+/**
+ * @aria/tools - messaging tool integration tests
+ *
+ * Tests the 4 messaging tool execute functions with REAL SQLite-backed
+ * MessageStore instances. No mocks for message storage — every assertion
+ * is verified against the actual database.
+ *
+ * Error-path tests (missing messageStore) remain as-is since those
+ * exercise tool behavior when no store is wired.
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { MESSAGING_TOOL_DEFINITIONS } from "../../src/definitions/messaging.js";
+import { MessageStore } from "@aria/memoria/storage";
+import type { ToolContext } from "../../src/types.js";
+
+// Resolve better-sqlite3 through @aria/memoria's dependency tree.
+// pnpm strict hoisting means it's only in memoria's node_modules.
+// We use createRequire pointed at memoria's package.json to access its deps.
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const memoriaDir = join(__dirname, "../../node_modules/@aria/memoria");
+const memoriaRequire = createRequire(join(memoriaDir, "package.json"));
+const Database = memoriaRequire("better-sqlite3");
+type DatabaseType = InstanceType<typeof Database>;
+
+// ── Helpers ────────────────────────────────────────────────────────────
+
+/** Find a tool by name from the definitions array */
+function findTool(name: string) {
+  const tool = MESSAGING_TOOL_DEFINITIONS.find((t) => t.name === name);
+  if (!tool) throw new Error(`Tool "${name}" not found in MESSAGING_TOOL_DEFINITIONS`);
+  return tool;
+}
+
+/** Create a real in-memory SQLite DB with the messages table and indexes */
+function createTestDb(): DatabaseType {
+  const db = new Database(":memory:");
+  db.pragma("journal_mode = WAL");
+  db.pragma("foreign_keys = ON");
+
+  db.exec(`CREATE TABLE IF NOT EXISTS messages (
+    id              TEXT PRIMARY KEY,
+    sender_id       TEXT NOT NULL,
+    sender_name     TEXT NOT NULL,
+    sender_type     TEXT NOT NULL CHECK (sender_type IN ('arion', 'worker', 'leader')),
+    recipient_id    TEXT NOT NULL,
+    recipient_name  TEXT NOT NULL,
+    reply_to        TEXT,
+    correlation_id  TEXT,
+    quest_id        TEXT,
+    type            TEXT NOT NULL,
+    content         TEXT NOT NULL,
+    metadata        TEXT,
+    priority        INTEGER DEFAULT 2 CHECK (priority >= 0 AND priority <= 4),
+    direction       TEXT NOT NULL CHECK (direction IN ('sent', 'received')),
+    read_at         INTEGER,
+    signature       TEXT,
+    created_at      INTEGER NOT NULL,
+    inbox_address_kind TEXT,
+    inbox_address_id   TEXT
+  )`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_messages_correlation ON messages(correlation_id)`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_messages_sender ON messages(sender_name)`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_messages_type ON messages(type)`);
+  db.exec(
+    `CREATE INDEX IF NOT EXISTS idx_messages_unread ON messages(direction, read_at) WHERE read_at IS NULL`,
+  );
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_messages_reply_to ON messages(reply_to)`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_messages_created ON messages(created_at)`);
+
+  return db;
+}
+
+/** Create a real ToolContext backed by a real MessageStore */
+function createRealContext(opts?: {
+  db?: DatabaseType;
+  mailbox?: ToolContext["mailbox"];
+  arion?: ToolContext["arion"];
+  runtimeId?: string;
+  networkControl?: ToolContext["networkControl"];
+}): { context: ToolContext; db: DatabaseType; store: MessageStore } {
+  const db = opts?.db ?? createTestDb();
+  const store = new MessageStore(db);
+  const runtimeId = opts?.runtimeId ?? opts?.arion?.id ?? "recipient-1";
+  const context = {
+    workingDir: "/tmp",
+    env: {},
+    confirm: async () => true,
+    messageStore: store,
+    mailbox: opts?.mailbox,
+    arion: opts?.arion,
+    networkControl: opts?.networkControl,
+    runtimeId,
+    nodeId: runtimeId,
+    inboxAddress: { kind: "node", nodeId: runtimeId },
+  } as ToolContext;
+  return { context, db, store };
+}
+
+/** Create a bare ToolContext with no messageStore (for error-path tests) */
+function createBareContext(): ToolContext {
+  return {
+    workingDir: "/tmp",
+    env: {},
+    confirm: async () => true,
+  } as ToolContext;
+}
+
+/** Helper to insert a message directly into the DB (bypass tool layer) */
+function insertMessage(
+  db: DatabaseType,
+  overrides: Partial<{
+    id: string;
+    sender_id: string;
+    sender_name: string;
+    sender_type: string;
+    recipient_id: string;
+    recipient_name: string;
+    reply_to: string | null;
+    correlation_id: string | null;
+    type: string;
+    content: string;
+    metadata: string | null;
+    priority: number;
+    direction: string;
+    read_at: number | null;
+    signature: string | null;
+    created_at: number;
+    inbox_address_kind: "client" | "node";
+    inbox_address_id: string;
+  }> = {},
+) {
+  const msg = {
+    id: `msg-${Math.random().toString(36).slice(2, 10)}`,
+    sender_id: "sender-1",
+    sender_name: "Alice",
+    sender_type: "arion",
+    recipient_id: "recipient-1",
+    recipient_name: "Bob",
+    reply_to: null,
+    correlation_id: null,
+    type: "finding",
+    content: "Default test content",
+    metadata: null,
+    priority: 2,
+    direction: "received",
+    read_at: null,
+    signature: null,
+    created_at: Date.now(),
+    inbox_address_kind: "node" as const,
+    inbox_address_id: "recipient-1",
+    ...overrides,
+  };
+
+  db.prepare(
+    `INSERT INTO messages (
+      id, sender_id, sender_name, sender_type,
+      recipient_id, recipient_name,
+      reply_to, correlation_id, type, content, metadata,
+      priority, direction, read_at, signature, created_at,
+      inbox_address_kind, inbox_address_id
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  ).run(
+    msg.id,
+    msg.sender_id,
+    msg.sender_name,
+    msg.sender_type,
+    msg.recipient_id,
+    msg.recipient_name,
+    msg.reply_to,
+    msg.correlation_id,
+    msg.type,
+    msg.content,
+    msg.metadata,
+    msg.priority,
+    msg.direction,
+    msg.read_at,
+    msg.signature,
+    msg.created_at,
+    msg.inbox_address_kind,
+    msg.inbox_address_id,
+  );
+
+  return msg;
+}
+
+// ── send_message ────────────────────────────────────────────────────────
+
+describe("messaging tools", () => {
+  describe("send_message", () => {
+    const tool = findTool("send_message");
+    let db: DatabaseType;
+
+    afterEach(() => {
+      db?.close();
+    });
+
+    it("returns error when messageStore is missing", async () => {
+      const ctx = createBareContext();
+      const result = await tool.execute({ to: "Bob", type: "finding", content: "Hello" }, ctx);
+
+      expect(result.success).toBe(false);
+      expect(result.message).toMatch(/[Mm]essage store not available/);
+    });
+
+    it("stores message in real DB when no mailbox", async () => {
+      const setup = createRealContext();
+      db = setup.db;
+
+      const result = await tool.execute(
+        { to: "Bob", type: "finding", content: "Hello Bob" },
+        setup.context,
+      );
+
+      expect(result.success).toBe(true);
+
+      // Verify directly in the real database
+      const rows = db.prepare("SELECT * FROM messages").all();
+      expect(rows).toHaveLength(1);
+
+      const row = rows[0] as Record<string, unknown>;
+      expect(row.direction).toBe("sent");
+      expect(row.content).toBe("Hello Bob");
+      expect(row.recipient_name).toBe("Bob");
+      expect(row.type).toBe("finding");
+    });
+
+    it("delivers via mailbox when available", async () => {
+      const mailbox = {
+        sendDurable: vi.fn().mockResolvedValue({
+          transport: "relay",
+          delivered: true,
+          queued: false,
+        }),
+        has: vi.fn().mockReturnValue(false),
+        hasByName: vi.fn().mockReturnValue(true),
+        resolveId: vi.fn((name: string) => (name === "Bob" ? "bob-id" : undefined)),
+      };
+      const setup = createRealContext({ mailbox });
+      db = setup.db;
+
+      const result = await tool.execute(
+        { to: "Bob", type: "finding", content: "Hello via mailbox" },
+        setup.context,
+      );
+
+      expect(result.success).toBe(true);
+      expect(mailbox.sendDurable).toHaveBeenCalledOnce();
+      expect(result.data).toHaveProperty("delivered", true);
+    });
+
+    it("fails closed when a unique peer display snapshot is supplied instead of a durable peer principal", async () => {
+      const mailbox = {
+        sendDurable: vi.fn().mockResolvedValue({
+          transport: "tunnel",
+          delivered: true,
+          queued: false,
+        }),
+        has: vi.fn().mockReturnValue(false),
+        hasByName: vi.fn().mockReturnValue(false),
+        resolveId: vi.fn(),
+      };
+      const networkControl = {
+        invite: vi.fn(),
+        revokePeer: vi.fn(),
+        listPeers: vi.fn(() => [
+          {
+            nodeId: "peer-bravo-1",
+            transportPublicKey: "wg-bravo-1",
+            displayNameSnapshot: "Bravo",
+            endpointHost: "10.0.0.22",
+            endpointPort: 51820,
+            controlEndpoint: null,
+            signingPublicKey: "signing-bravo-1",
+            status: "active" as const,
+            lastHandshake: null,
+            createdAt: Date.now(),
+          },
+        ]),
+        status: vi.fn(),
+      };
+      const setup = createRealContext({
+        mailbox: mailbox as ToolContext["mailbox"],
+        networkControl: networkControl as ToolContext["networkControl"],
+      });
+      db = setup.db;
+
+      const result = await tool.execute(
+        { to: "Bravo", type: "finding", content: "Hello via tunnel" },
+        setup.context,
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.message).toMatch(/display name|peer principal/i);
+      expect(mailbox.sendDurable).not.toHaveBeenCalled();
+    });
+
+    it("keeps local recipient fallback when no remote peer principal matches the input", async () => {
+      const networkControl = {
+        invite: vi.fn(),
+        revokePeer: vi.fn(),
+        listPeers: vi.fn(() => [
+          {
+            nodeId: "peer-bravo-1",
+            transportPublicKey: "wg-bravo-1",
+            displayNameSnapshot: "Bravo",
+            endpointHost: "10.0.0.22",
+            endpointPort: 51820,
+            controlEndpoint: null,
+            signingPublicKey: "signing-bravo-1",
+            status: "active" as const,
+            lastHandshake: null,
+            createdAt: Date.now(),
+          },
+        ]),
+        status: vi.fn(),
+      };
+      const setup = createRealContext({
+        networkControl: networkControl as ToolContext["networkControl"],
+      });
+      db = setup.db;
+
+      const result = await tool.execute(
+        { to: "Charlie", type: "finding", content: "Hello Charlie" },
+        setup.context,
+      );
+
+      expect(result.success).toBe(true);
+      const rows = db.prepare("SELECT recipient_id, recipient_name FROM messages").all() as Array<{
+        recipient_id: string;
+        recipient_name: string;
+      }>;
+      expect(rows).toEqual([
+        {
+          recipient_id: "Charlie",
+          recipient_name: "Charlie",
+        },
+      ]);
+    });
+
+    it("fails closed for attached-client senders when the recipient cannot be validated", async () => {
+      const setup = createRealContext();
+      db = setup.db;
+      setup.context.inboxAddress = { kind: "client", clientId: "client-self" };
+
+      const result = await tool.execute(
+        { to: "client-other", type: "finding", content: "Hello other client" },
+        setup.context,
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.message).toMatch(/exact .*clientId|list_clients|unknown recipient/i);
+      expect(db.prepare("SELECT * FROM messages").all()).toHaveLength(0);
+    });
+
+    it("keeps raw recipient ids valid when a mailbox is present but delivery falls back locally", async () => {
+      const mailbox = {
+        sendDurable: vi.fn().mockRejectedValue(new Error('Cannot route message to "ghost-peer"')),
+        has: vi.fn().mockReturnValue(false),
+        hasByName: vi.fn().mockReturnValue(false),
+      };
+      const networkControl = {
+        invite: vi.fn(),
+        revokePeer: vi.fn(),
+        listPeers: vi.fn(() => [
+          {
+            nodeId: "node-bravo",
+            transportPublicKey: "wg-bravo-1",
+            displayNameSnapshot: "Bravo",
+            endpointHost: "10.0.0.22",
+            endpointPort: 51820,
+            controlEndpoint: null,
+            signingPublicKey: "signing-bravo-1",
+            status: "active" as const,
+            lastHandshake: null,
+            createdAt: Date.now(),
+          },
+        ]),
+        status: vi.fn(),
+      };
+      const setup = createRealContext({
+        mailbox: mailbox as ToolContext["mailbox"],
+        networkControl: networkControl as ToolContext["networkControl"],
+      });
+      db = setup.db;
+
+      const result = await tool.execute(
+        { to: "ghost-peer", type: "finding", content: "Hello ghost" },
+        setup.context,
+      );
+
+      expect(result.success).toBe(true);
+      expect(result.message).toMatch(/stored locally|delivery failed/i);
+      expect(mailbox.sendDurable).toHaveBeenCalledOnce();
+      const rows = db
+        .prepare("SELECT recipient_id, recipient_name, direction, content FROM messages")
+        .all() as Array<{
+        recipient_id: string;
+        recipient_name: string;
+        direction: string;
+        content: string;
+      }>;
+      expect(rows).toEqual([
+        {
+          recipient_id: "ghost-peer",
+          recipient_name: "ghost-peer",
+          direction: "sent",
+          content: "Hello ghost",
+        },
+      ]);
+    });
+
+    it("accepts an explicit local recipient id when the mailbox registry confirms it", async () => {
+      const mailbox = {
+        sendDurable: vi.fn().mockResolvedValue({
+          transport: "in_process",
+          delivered: true,
+          queued: false,
+        }),
+        has: vi.fn((id: string) => id === "rex-id"),
+        hasByName: vi.fn().mockReturnValue(false),
+      };
+      const setup = createRealContext({
+        mailbox: mailbox as ToolContext["mailbox"],
+      });
+      db = setup.db;
+
+      const result = await tool.execute(
+        { to: "rex-id", type: "finding", content: "Hello Rex" },
+        setup.context,
+      );
+
+      expect(result.success).toBe(true);
+      expect(mailbox.sendDurable).toHaveBeenCalledWith(
+        expect.objectContaining({
+          recipient: expect.objectContaining({
+            id: "rex-id",
+            name: "rex-id",
+          }),
+        }),
+      );
+    });
+
+    it("resolves a local recipient alias to the canonical mailbox id before delivery", async () => {
+      const mailbox = {
+        sendDurable: vi.fn().mockResolvedValue({
+          transport: "in_process",
+          delivered: true,
+          queued: false,
+        }),
+        has: vi.fn().mockReturnValue(false),
+        hasByName: vi.fn((name: string) => name === "Rex display"),
+        resolveId: vi.fn((name: string) => (name === "Rex display" ? "rex-id" : undefined)),
+      };
+      const setup = createRealContext({
+        mailbox: mailbox as ToolContext["mailbox"],
+      });
+      db = setup.db;
+
+      const result = await tool.execute(
+        { to: "Rex display", type: "finding", content: "Hello alias" },
+        setup.context,
+      );
+
+      expect(result.success).toBe(true);
+      expect(mailbox.sendDurable).toHaveBeenCalledWith(
+        expect.objectContaining({
+          recipient: expect.objectContaining({
+            id: "rex-id",
+            name: "Rex display",
+          }),
+        }),
+      );
+    });
+
+    it("prefers a registered local alias over an invalid remote display snapshot match", async () => {
+      const mailbox = {
+        sendDurable: vi.fn().mockResolvedValue({
+          transport: "in_process",
+          delivered: true,
+          queued: false,
+        }),
+        has: vi.fn().mockReturnValue(false),
+        hasByName: vi.fn((name: string) => name === "Bravo"),
+        resolveId: vi.fn((name: string) => (name === "Bravo" ? "local-bravo-id" : undefined)),
+      };
+      const networkControl = {
+        invite: vi.fn(),
+        revokePeer: vi.fn(),
+        listPeers: vi.fn(() => [
+          {
+            nodeId: "node-bravo",
+            transportPublicKey: "wg-bravo-1",
+            displayNameSnapshot: "Bravo",
+            endpointHost: "10.0.0.22",
+            endpointPort: 51820,
+            controlEndpoint: null,
+            signingPublicKey: "signing-bravo-1",
+            status: "active" as const,
+            lastHandshake: null,
+            createdAt: Date.now(),
+          },
+        ]),
+        status: vi.fn(),
+      };
+      const setup = createRealContext({
+        mailbox: mailbox as ToolContext["mailbox"],
+        networkControl: networkControl as ToolContext["networkControl"],
+      });
+      db = setup.db;
+
+      const result = await tool.execute(
+        { to: "Bravo", type: "finding", content: "Hello local Bravo" },
+        setup.context,
+      );
+
+      expect(result.success).toBe(true);
+      expect(mailbox.sendDurable).toHaveBeenCalledWith(
+        expect.objectContaining({
+          recipient: expect.objectContaining({
+            id: "local-bravo-id",
+            name: "Bravo",
+          }),
+        }),
+      );
+    });
+
+    it("accepts an explicit remote nodeId while routing delivery by nodeId", async () => {
+      const mailbox = {
+        sendDurable: vi.fn().mockResolvedValue({
+          transport: "tunnel",
+          delivered: true,
+          queued: false,
+        }),
+      };
+      const networkControl = {
+        invite: vi.fn(),
+        revokePeer: vi.fn(),
+        listPeers: vi.fn(() => [
+          {
+            nodeId: "node-bravo",
+            transportPublicKey: "wg-bravo-1",
+            displayNameSnapshot: "Bravo",
+            endpointHost: "10.0.0.22",
+            endpointPort: 51820,
+            controlEndpoint: null,
+            signingPublicKey: "signing-bravo-1",
+            status: "active" as const,
+            lastHandshake: null,
+            createdAt: Date.now(),
+          },
+        ]),
+        status: vi.fn(),
+      };
+      const setup = createRealContext({
+        mailbox: mailbox as ToolContext["mailbox"],
+        networkControl: networkControl as ToolContext["networkControl"],
+      });
+      db = setup.db;
+
+      const result = await tool.execute(
+        { to: "node-bravo", type: "finding", content: "Hello via nodeId" },
+        setup.context,
+      );
+
+      expect(result.success).toBe(true);
+      expect(mailbox.sendDurable).toHaveBeenCalledWith(
+        expect.objectContaining({
+          recipient: expect.objectContaining({
+            id: "node-bravo",
+            name: "Bravo",
+          }),
+        }),
+      );
+    });
+
+    it("fails closed when a peer display snapshot is ambiguous", async () => {
+      const mailbox = {
+        sendDurable: vi.fn(),
+        has: vi.fn().mockReturnValue(false),
+        hasByName: vi.fn().mockReturnValue(false),
+        resolveId: vi.fn(),
+      };
+      const networkControl = {
+        invite: vi.fn(),
+        revokePeer: vi.fn(),
+        listPeers: vi.fn(() => [
+          {
+            nodeId: "peer-bravo-1",
+            transportPublicKey: "wg-bravo-1",
+            displayNameSnapshot: "Bravo",
+            endpointHost: "10.0.0.22",
+            endpointPort: 51820,
+            controlEndpoint: null,
+            signingPublicKey: "signing-bravo-1",
+            status: "active" as const,
+            lastHandshake: null,
+            createdAt: Date.now(),
+          },
+          {
+            nodeId: "peer-bravo-2",
+            transportPublicKey: "wg-bravo-2",
+            displayNameSnapshot: "Bravo",
+            endpointHost: "10.0.0.23",
+            endpointPort: 51820,
+            controlEndpoint: null,
+            signingPublicKey: "signing-bravo-2",
+            status: "active" as const,
+            lastHandshake: null,
+            createdAt: Date.now(),
+          },
+        ]),
+        status: vi.fn(),
+      };
+      const setup = createRealContext({
+        mailbox: mailbox as ToolContext["mailbox"],
+        networkControl: networkControl as ToolContext["networkControl"],
+      });
+      db = setup.db;
+
+      const result = await tool.execute(
+        { to: "Bravo", type: "finding", content: "Ambiguous hello" },
+        setup.context,
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.message).toMatch(/ambiguous/i);
+      expect(mailbox.sendDurable).not.toHaveBeenCalled();
+    });
+
+    it("fails closed when durable delivery to a known remote peer errors", async () => {
+      const mailbox = {
+        sendDurable: vi.fn().mockRejectedValue(new Error("Connection refused")),
+      };
+      const networkControl = {
+        invite: vi.fn(),
+        revokePeer: vi.fn(),
+        listPeers: vi.fn(() => [
+          {
+            nodeId: "peer-bravo-1",
+            transportPublicKey: "wg-bravo-1",
+            displayNameSnapshot: "Bravo",
+            endpointHost: "10.0.0.22",
+            endpointPort: 51820,
+            controlEndpoint: null,
+            signingPublicKey: "signing-bravo-1",
+            status: "active" as const,
+            lastHandshake: null,
+            createdAt: Date.now(),
+          },
+        ]),
+        status: vi.fn(),
+      };
+      const setup = createRealContext({
+        mailbox: mailbox as ToolContext["mailbox"],
+        networkControl: networkControl as ToolContext["networkControl"],
+      });
+      db = setup.db;
+
+      const result = await tool.execute(
+        { to: "peer-bravo-1", type: "finding", content: "Should fail closed" },
+        setup.context,
+      );
+
+      expect(result.success).toBe(false);
+      expect(result.message).toMatch(/delivery failed/i);
+      expect(result.data).toMatchObject({
+        to: "peer-bravo-1",
+        delivered: false,
+      });
+
+      const rows = db.prepare("SELECT * FROM messages").all();
+      expect(rows).toHaveLength(1);
+      expect((rows[0] as Record<string, unknown>).direction).toBe("sent");
+    });
+
+    it("surfaces queued tunnel sends instead of claiming delivery", async () => {
+      const mailbox = {
+        sendDurable: vi.fn().mockResolvedValue({
+          transport: "tunnel",
+          delivered: false,
+          queued: true,
+        }),
+        has: vi.fn().mockReturnValue(false),
+        hasByName: vi.fn().mockReturnValue(true),
+        resolveId: vi.fn((name: string) => (name === "Bob" ? "bob-id" : undefined)),
+      };
+      const setup = createRealContext({ mailbox: mailbox as ToolContext["mailbox"] });
+      db = setup.db;
+
+      const result = await tool.execute(
+        { to: "Bob", type: "finding", content: "Queued until tunnel connects" },
+        setup.context,
+      );
+
+      expect(result.success).toBe(true);
+      expect(mailbox.sendDurable).toHaveBeenCalledOnce();
+      expect(result.message).toMatch(/queued/i);
+      expect(result.data).toMatchObject({
+        delivered: false,
+        queued: true,
+        transport: "tunnel",
+      });
+    });
+
+    it("surfaces unacknowledged tunnel sends instead of claiming delivery", async () => {
+      const mailbox = {
+        sendDurable: vi.fn().mockResolvedValue({
+          transport: "tunnel",
+          delivered: false,
+          queued: true,
+          accepted: true,
+          deliveryState: "dispatching",
+          sessionState: "connected",
+          deliveryReadiness: "can_send_now",
+          queuedReason: "awaiting_remote_ack",
+        }),
+        has: vi.fn().mockReturnValue(false),
+        hasByName: vi.fn().mockReturnValue(true),
+        resolveId: vi.fn((name: string) => (name === "Bob" ? "bob-id" : undefined)),
+      };
+      const setup = createRealContext({ mailbox: mailbox as ToolContext["mailbox"] });
+      db = setup.db;
+
+      const result = await tool.execute(
+        { to: "Bob", type: "finding", content: "Waiting for remote persistence ack" },
+        setup.context,
+      );
+
+      expect(result.success).toBe(true);
+      expect(mailbox.sendDurable).toHaveBeenCalledOnce();
+      expect(result.message).toMatch(/awaiting/i);
+      expect(result.data).toMatchObject({
+        delivered: false,
+        queued: true,
+        transport: "tunnel",
+        deliveryState: "dispatching",
+        queuedReason: "awaiting_remote_ack",
+      });
+    });
+
+    it("falls back to local store on mailbox failure", async () => {
+      const mailbox = {
+        sendDurable: vi.fn().mockRejectedValue(new Error("Connection refused")),
+        has: vi.fn().mockReturnValue(false),
+        hasByName: vi.fn().mockReturnValue(true),
+        resolveId: vi.fn((name: string) => (name === "Bob" ? "bob-id" : undefined)),
+      };
+      const setup = createRealContext({ mailbox });
+      db = setup.db;
+
+      const result = await tool.execute(
+        { to: "Bob", type: "finding", content: "Fallback message" },
+        setup.context,
+      );
+
+      expect(result.success).toBe(true);
+      expect(result.message).toMatch(/delivery failed/);
+      expect(result.data).toHaveProperty("delivered", false);
+
+      // Verify it was stored locally in the real DB
+      const rows = db.prepare("SELECT * FROM messages").all();
+      expect(rows).toHaveLength(1);
+      expect((rows[0] as Record<string, unknown>).direction).toBe("sent");
+      expect((rows[0] as Record<string, unknown>).content).toBe("Fallback message");
+    });
+
+    it("sets version:1 on message sent via mailbox", async () => {
+      const mailbox = {
+        sendDurable: vi.fn().mockResolvedValue({
+          transport: "relay",
+          delivered: true,
+          queued: false,
+        }),
+        has: vi.fn().mockReturnValue(false),
+        hasByName: vi.fn().mockReturnValue(true),
+        resolveId: vi.fn((name: string) => (name === "Bob" ? "bob-id" : undefined)),
+      };
+      const setup = createRealContext({ mailbox });
+      db = setup.db;
+
+      await tool.execute({ to: "Bob", type: "quest", content: "Do something" }, setup.context);
+
+      // The message passed to mailbox.sendDurable should have version: 1
+      const sentMsg = mailbox.sendDurable.mock.calls[0][0];
+      expect(sentMsg.version).toBe(1);
+    });
+
+    it("generates UUID for message id", async () => {
+      const setup = createRealContext();
+      db = setup.db;
+
+      await tool.execute({ to: "Bob", type: "finding", content: "UUID test" }, setup.context);
+
+      const row = db.prepare("SELECT id FROM messages").get() as { id: string };
+      // UUID v4 format
+      expect(row.id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
+    });
+
+    it("uses arion context for sender when available", async () => {
+      const setup = createRealContext({
+        arion: { id: "rex-id", name: "Rex", emoji: "dog" },
+      });
+      db = setup.db;
+
+      await tool.execute({ to: "Bob", type: "finding", content: "From Rex" }, setup.context);
+
+      const row = db.prepare("SELECT sender_id, sender_name, sender_type FROM messages").get() as {
+        sender_id: string;
+        sender_name: string;
+        sender_type: string;
+      };
+      expect(row.sender_id).toBe("rex-id");
+      expect(row.sender_name).toBe("Rex");
+      expect(row.sender_type).toBe("arion");
+    });
+
+    it("uses the runtime-bound inbox identity when no arion context is active", async () => {
+      const setup = createRealContext();
+      db = setup.db;
+
+      await tool.execute({ to: "Bob", type: "finding", content: "From leader" }, setup.context);
+
+      const row = db.prepare("SELECT sender_id, sender_name, sender_type FROM messages").get() as {
+        sender_id: string;
+        sender_name: string;
+        sender_type: string;
+      };
+      expect(row.sender_id).toBe("recipient-1");
+      expect(row.sender_name).toBe("ARIA");
+      expect(row.sender_type).toBe("leader");
+    });
+
+    it("uses senderType from context when no arion (worker propagation)", async () => {
+      const setup = createRealContext();
+      db = setup.db;
+      // Simulate a worker context: no arion, senderType explicitly set to "worker"
+      setup.context.senderType = "worker";
+
+      await tool.execute(
+        { to: "Leader", type: "progress", content: "Task 50% done" },
+        setup.context,
+      );
+
+      const row = db.prepare("SELECT sender_type FROM messages").get() as {
+        sender_type: string;
+      };
+      expect(row.sender_type).toBe("worker");
+    });
+
+    it("includes replyTo and correlationId when provided", async () => {
+      const setup = createRealContext();
+      db = setup.db;
+
+      await tool.execute(
+        {
+          to: "Bob",
+          type: "answer",
+          content: "Yes",
+          replyTo: "msg-abc",
+          correlationId: "quest-xyz",
+        },
+        setup.context,
+      );
+
+      const row = db.prepare("SELECT reply_to, correlation_id FROM messages").get() as {
+        reply_to: string;
+        correlation_id: string;
+      };
+      expect(row.reply_to).toBe("msg-abc");
+      expect(row.correlation_id).toBe("quest-xyz");
+    });
+
+    it("defaults priority to 2 when not specified", async () => {
+      const setup = createRealContext();
+      db = setup.db;
+
+      await tool.execute(
+        { to: "Bob", type: "finding", content: "Default priority" },
+        setup.context,
+      );
+
+      const row = db.prepare("SELECT priority FROM messages").get() as { priority: number };
+      expect(row.priority).toBe(2);
+    });
+
+    it("respects explicit priority", async () => {
+      const setup = createRealContext();
+      db = setup.db;
+
+      await tool.execute(
+        { to: "Bob", type: "error", content: "Critical!", priority: 0 },
+        setup.context,
+      );
+
+      const row = db.prepare("SELECT priority FROM messages").get() as { priority: number };
+      expect(row.priority).toBe(0);
+    });
+
+    it("result data includes message id, to, and type", async () => {
+      const setup = createRealContext();
+      db = setup.db;
+
+      const result = await tool.execute(
+        { to: "Bob", type: "directive", content: "Do this" },
+        setup.context,
+      );
+
+      expect(result.data).toHaveProperty("id");
+      expect(result.data).toHaveProperty("to", "Bob");
+      expect(result.data).toHaveProperty("type", "directive");
+
+      // And the id in result.data should match what's in the DB
+      const row = db.prepare("SELECT id FROM messages").get() as { id: string };
+      expect((result.data as Record<string, unknown>).id).toBe(row.id);
+    });
+  });
+
+  // ── check_messages ──────────────────────────────────────────────────────
+
+  describe("check_messages", () => {
+    const tool = findTool("check_messages");
+    let db: DatabaseType;
+
+    afterEach(() => {
+      db?.close();
+    });
+
+    it("returns error when messageStore is missing", async () => {
+      const ctx = createBareContext();
+      const result = await tool.execute({}, ctx);
+
+      expect(result.success).toBe(false);
+      expect(result.message).toMatch(/[Mm]essage store not available/);
+    });
+
+    it("returns unread messages from real DB", async () => {
+      const setup = createRealContext();
+      db = setup.db;
+
+      // Insert messages directly into the DB
+      const now = Date.now();
+      insertMessage(db, {
+        id: "msg-1",
+        sender_name: "Alice",
+        type: "finding",
+        content: "Found it",
+        direction: "received",
+        created_at: now,
+      });
+      insertMessage(db, {
+        id: "msg-2",
+        sender_name: "Bob",
+        type: "question",
+        content: "How?",
+        direction: "received",
+        created_at: now + 100,
+      });
+
+      const result = await tool.execute({}, setup.context);
+
+      expect(result.success).toBe(true);
+      expect(result.message).toMatch(/2 message\(s\) received/);
+      expect(result.data).toHaveProperty("messages");
+      expect((result.data as { messages: unknown[] }).messages).toHaveLength(2);
+    });
+
+    it("auto-marks messages as read in the real DB", async () => {
+      const setup = createRealContext();
+      db = setup.db;
+
+      const now = Date.now();
+      insertMessage(db, {
+        id: "msg-1",
+        direction: "received",
+        created_at: now,
+      });
+      insertMessage(db, {
+        id: "msg-2",
+        direction: "received",
+        created_at: now + 100,
+      });
+
+      await tool.execute({}, setup.context);
+
+      // Verify read_at was set in the real DB
+      const rows = db.prepare("SELECT id, read_at FROM messages ORDER BY id").all() as Array<{
+        id: string;
+        read_at: number | null;
+      }>;
+      for (const row of rows) {
+        expect(row.read_at).not.toBeNull();
+        expect(row.read_at).toBeGreaterThan(0);
+      }
+    });
+
+    it("returns 'No unread messages' when inbox is empty", async () => {
+      const setup = createRealContext();
+      db = setup.db;
+
+      // Empty DB — no messages at all
+      const result = await tool.execute({}, setup.context);
+
+      expect(result.success).toBe(true);
+      expect(result.message).toMatch(/[Nn]o unread messages/);
+      expect((result.data as { messages: unknown[] }).messages).toEqual([]);
+    });
+
+    it("uses search with filters when unreadOnly=false", async () => {
+      const setup = createRealContext();
+      db = setup.db;
+
+      const now = Date.now();
+      insertMessage(db, {
+        id: "msg-alice-finding",
+        sender_name: "Alice",
+        type: "finding",
+        content: "Found a bug",
+        direction: "received",
+        created_at: now,
+      });
+      insertMessage(db, {
+        id: "msg-bob-question",
+        sender_name: "Bob",
+        type: "question",
+        content: "How does this work?",
+        direction: "received",
+        created_at: now + 100,
+      });
+
+      const result = await tool.execute(
+        { unreadOnly: false, from: "Alice", type: "finding", limit: 10 },
+        setup.context,
+      );
+
+      expect(result.success).toBe(true);
+      const messages = (result.data as { messages: Array<{ id: string }> }).messages;
+      expect(messages).toHaveLength(1);
+      expect(messages[0].id).toBe("msg-alice-finding");
+    });
+
+    it("defaults limit to 20 (does not return more)", async () => {
+      const setup = createRealContext();
+      db = setup.db;
+
+      // Insert 25 unread messages
+      const now = Date.now();
+      for (let i = 0; i < 25; i++) {
+        insertMessage(db, {
+          id: `msg-limit-${i}`,
+          direction: "received",
+          created_at: now + i,
+        });
+      }
+
+      const result = await tool.execute({}, setup.context);
+
+      expect(result.success).toBe(true);
+      const messages = (result.data as { messages: unknown[] }).messages;
+      expect(messages).toHaveLength(20);
+    });
+  });
+
+  // ── search_messages ──────────────────────────────────────────────────────
+
+  describe("search_messages", () => {
+    const tool = findTool("search_messages");
+    let db: DatabaseType;
+
+    afterEach(() => {
+      db?.close();
+    });
+
+    it("returns error when messageStore is missing", async () => {
+      const ctx = createBareContext();
+      const result = await tool.execute({ query: "test" }, ctx);
+
+      expect(result.success).toBe(false);
+      expect(result.message).toMatch(/[Mm]essage store not available/);
+    });
+
+    it("searches by content in real DB", async () => {
+      const setup = createRealContext();
+      db = setup.db;
+
+      const now = Date.now();
+      insertMessage(db, {
+        id: "msg-deploy-1",
+        content: "Deploying to production",
+        direction: "sent",
+        created_at: now,
+      });
+      insertMessage(db, {
+        id: "msg-deploy-2",
+        content: "Deploy succeeded",
+        direction: "received",
+        created_at: now + 100,
+      });
+      insertMessage(db, {
+        id: "msg-other",
+        content: "Reviewing the code",
+        direction: "sent",
+        created_at: now + 200,
+      });
+
+      const result = await tool.execute({ query: "deploy" }, setup.context);
+
+      expect(result.success).toBe(true);
+      // Case-insensitive LIKE match: "Deploying" and "Deploy" both match "deploy"
+      // Actually SQLite LIKE is case-insensitive for ASCII
+      const messages = (result.data as { messages: Array<{ id: string }> }).messages;
+      expect(messages).toHaveLength(2);
+      expect(messages.map((m) => m.id).sort()).toEqual(["msg-deploy-1", "msg-deploy-2"]);
+    });
+
+    it("filters by sender, type, correlationId, and after", async () => {
+      const setup = createRealContext();
+      db = setup.db;
+
+      const now = Date.now();
+      insertMessage(db, {
+        id: "msg-rex-progress",
+        sender_name: "Rex",
+        type: "progress",
+        content: "Parser work ongoing",
+        correlation_id: "quest-42",
+        direction: "received",
+        created_at: now + 100,
+      });
+      insertMessage(db, {
+        id: "msg-rex-finding",
+        sender_name: "Rex",
+        type: "finding",
+        content: "Parser bug found",
+        direction: "received",
+        created_at: now + 200,
+      });
+      insertMessage(db, {
+        id: "msg-alice-progress",
+        sender_name: "Alice",
+        type: "progress",
+        content: "Parser refactored",
+        direction: "sent",
+        created_at: now + 300,
+      });
+
+      const result = await tool.execute(
+        {
+          query: "Parser",
+          from: "Rex",
+          type: "progress",
+          correlationId: "quest-42",
+          limit: 5,
+        },
+        setup.context,
+      );
+
+      expect(result.success).toBe(true);
+      const messages = (result.data as { messages: Array<{ id: string }> }).messages;
+      expect(messages).toHaveLength(1);
+      expect(messages[0].id).toBe("msg-rex-progress");
+    });
+
+    it("defaults limit to 20", async () => {
+      const setup = createRealContext();
+      db = setup.db;
+
+      // Insert 25 messages all matching the query
+      const now = Date.now();
+      for (let i = 0; i < 25; i++) {
+        insertMessage(db, {
+          id: `msg-search-${i}`,
+          content: "searchable content here",
+          direction: "sent",
+          created_at: now + i,
+        });
+      }
+
+      const result = await tool.execute({ query: "searchable" }, setup.context);
+
+      const messages = (result.data as { messages: unknown[] }).messages;
+      expect(messages).toHaveLength(20);
+    });
+
+    it("returns found message count in message", async () => {
+      const setup = createRealContext();
+      db = setup.db;
+
+      const now = Date.now();
+      insertMessage(db, { id: "s1", content: "test data A", created_at: now, direction: "sent" });
+      insertMessage(db, {
+        id: "s2",
+        content: "test data B",
+        created_at: now + 1,
+        direction: "sent",
+      });
+      insertMessage(db, {
+        id: "s3",
+        content: "test data C",
+        created_at: now + 2,
+        direction: "sent",
+      });
+
+      const result = await tool.execute({ query: "test data" }, setup.context);
+
+      expect(result.message).toMatch(/3 message\(s\) found/);
+      expect((result.data as { messages: unknown[] }).messages).toHaveLength(3);
+    });
+
+    it("returns empty results gracefully", async () => {
+      const setup = createRealContext();
+      db = setup.db;
+
+      const result = await tool.execute({ query: "nonexistent" }, setup.context);
+
+      expect(result.success).toBe(true);
+      expect(result.message).toMatch(/0 message\(s\) found/);
+    });
+  });
+
+  // ── get_thread ──────────────────────────────────────────────────────────
+
+  describe("get_thread", () => {
+    const tool = findTool("get_thread");
+    let db: DatabaseType;
+
+    afterEach(() => {
+      db?.close();
+    });
+
+    it("returns error when messageStore is missing", async () => {
+      const ctx = createBareContext();
+      const result = await tool.execute({ messageId: "msg-1" }, ctx);
+
+      expect(result.success).toBe(false);
+      expect(result.message).toMatch(/[Mm]essage store not available/);
+    });
+
+    it("reconstructs a thread from real DB with reply_to chains", async () => {
+      const setup = createRealContext();
+      db = setup.db;
+
+      const now = Date.now();
+      // Create a 3-message thread: A -> B -> C
+      insertMessage(db, {
+        id: "msg-1",
+        sender_name: "Alice",
+        type: "question",
+        content: "How?",
+        reply_to: null,
+        direction: "sent",
+        created_at: now,
+      });
+      insertMessage(db, {
+        id: "msg-2",
+        sender_name: "Bob",
+        type: "answer",
+        content: "Like this",
+        reply_to: "msg-1",
+        direction: "received",
+        created_at: now + 100,
+      });
+      insertMessage(db, {
+        id: "msg-3",
+        sender_name: "Alice",
+        type: "answer",
+        content: "Thanks!",
+        reply_to: "msg-2",
+        direction: "sent",
+        created_at: now + 200,
+      });
+
+      // Get thread starting from the leaf
+      const result = await tool.execute({ messageId: "msg-3" }, setup.context);
+
+      expect(result.success).toBe(true);
+      expect(result.message).toMatch(/3 message\(s\)/);
+      const thread = (result.data as { thread: Array<{ id: string }> }).thread;
+      expect(thread).toHaveLength(3);
+      expect(thread[0].id).toBe("msg-1");
+      expect(thread[1].id).toBe("msg-2");
+      expect(thread[2].id).toBe("msg-3");
+    });
+
+    it("returns error for empty thread (nonexistent message)", async () => {
+      const setup = createRealContext();
+      db = setup.db;
+
+      const result = await tool.execute({ messageId: "nonexistent-msg" }, setup.context);
+
+      expect(result.success).toBe(false);
+      expect(result.message).toMatch(/[Nn]o thread found/);
+    });
+
+    it("error message includes the message ID", async () => {
+      const setup = createRealContext();
+      db = setup.db;
+
+      const result = await tool.execute({ messageId: "xyz-123" }, setup.context);
+
+      expect(result.message).toContain("xyz-123");
+    });
+
+    it("returns single message thread when no replies exist", async () => {
+      const setup = createRealContext();
+      db = setup.db;
+
+      insertMessage(db, {
+        id: "msg-solo",
+        content: "Solo message",
+        reply_to: null,
+        direction: "received",
+        created_at: Date.now(),
+      });
+
+      const result = await tool.execute({ messageId: "msg-solo" }, setup.context);
+
+      expect(result.success).toBe(true);
+      const thread = (result.data as { thread: Array<{ id: string }> }).thread;
+      expect(thread).toHaveLength(1);
+      expect(thread[0].id).toBe("msg-solo");
+    });
+
+    it("finds full thread from any message in the chain", async () => {
+      const setup = createRealContext();
+      db = setup.db;
+
+      const now = Date.now();
+      insertMessage(db, {
+        id: "msg-root",
+        content: "Root",
+        reply_to: null,
+        direction: "sent",
+        created_at: now,
+      });
+      insertMessage(db, {
+        id: "msg-reply",
+        content: "Reply",
+        reply_to: "msg-root",
+        direction: "received",
+        created_at: now + 100,
+      });
+
+      // Query from the root (not the leaf)
+      const result = await tool.execute({ messageId: "msg-root" }, setup.context);
+
+      expect(result.success).toBe(true);
+      const thread = (result.data as { thread: Array<{ id: string }> }).thread;
+      expect(thread).toHaveLength(2);
+      expect(thread[0].id).toBe("msg-root");
+      expect(thread[1].id).toBe("msg-reply");
+    });
+  });
+
+  // ── AgentRunner path integration: nodeId-only context ─────────────────
+
+  describe("AgentRunner inbox path (nodeId only, no inboxAddress)", () => {
+    /**
+     * This describe block tests the EXACT ToolContext shape that the AgentRunner
+     * path produces: nodeId is set, inboxAddress is NOT set. This exercises the
+     * resolveInboxAddress() fallback from context.nodeId.
+     *
+     * The standard createRealContext() sets context.inboxAddress directly, which
+     * bypasses resolveInboxAddress() entirely. These tests prove messages actually
+     * route through the nodeId path.
+     */
+
+    function createAgentRunnerContext(opts?: {
+      db?: DatabaseType;
+      mailbox?: ToolContext["mailbox"];
+      networkControl?: ToolContext["networkControl"];
+    }): { context: ToolContext; db: DatabaseType; store: MessageStore } {
+      const db = opts?.db ?? createTestDb();
+      const store = new MessageStore(db);
+      const nodeId = "node-test-runner";
+      // Deliberately NO inboxAddress — only nodeId, mimicking tool-executor.ts
+      const context = {
+        workingDir: "/tmp",
+        env: {},
+        confirm: async () => true,
+        messageStore: store,
+        mailbox: opts?.mailbox,
+        networkControl: opts?.networkControl,
+        nodeId,
+      } as ToolContext;
+      return { context, db, store };
+    }
+
+    let db: DatabaseType;
+
+    afterEach(() => {
+      db?.close();
+    });
+
+    it("send_message delivers through nodeId-only context (AgentRunner path)", async () => {
+      const tool = findTool("send_message");
+      const setup = createAgentRunnerContext();
+      db = setup.db;
+
+      const result = await tool.execute(
+        { to: "Bob", type: "finding", content: "Hello from runner" },
+        setup.context,
+      );
+
+      expect(result.success).toBe(true);
+
+      // Verify the message is in the DB with correct inbox address
+      const rows = db.prepare("SELECT * FROM messages").all() as Array<Record<string, unknown>>;
+      expect(rows).toHaveLength(1);
+      expect(rows[0].content).toBe("Hello from runner");
+      expect(rows[0].direction).toBe("sent");
+      expect(rows[0].inbox_address_kind).toBe("node");
+      expect(rows[0].inbox_address_id).toBe("node-test-runner");
+    });
+
+    it("check_messages reads through nodeId-only context (AgentRunner path)", async () => {
+      const tool = findTool("check_messages");
+      const setup = createAgentRunnerContext();
+      db = setup.db;
+
+      // Insert a message addressed to this node
+      insertMessage(db, {
+        id: "msg-runner-1",
+        sender_name: "Alice",
+        type: "finding",
+        content: "Found via runner",
+        direction: "received",
+        created_at: Date.now(),
+        inbox_address_kind: "node",
+        inbox_address_id: "node-test-runner",
+      });
+
+      const result = await tool.execute({}, setup.context);
+
+      expect(result.success).toBe(true);
+      const messages = (result.data as { messages: Array<{ id: string }> }).messages;
+      expect(messages).toHaveLength(1);
+      expect(messages[0].id).toBe("msg-runner-1");
+    });
+
+    it("throws descriptive error when NEITHER nodeId NOR inboxAddress is set", async () => {
+      const tool = findTool("send_message");
+      const dbt = createTestDb();
+      const store = new MessageStore(dbt);
+      const context = {
+        workingDir: "/tmp",
+        env: {},
+        confirm: async () => true,
+        messageStore: store,
+        // NO nodeId, NO inboxAddress — this is the wiring bug scenario
+      } as ToolContext;
+
+      try {
+        await tool.execute({ to: "Bob", type: "finding", content: "This should fail" }, context);
+        expect.fail("Should have thrown");
+      } catch (e) {
+        expect((e as Error).message).toContain("Inbox address not available");
+        expect((e as Error).message).toContain("wiring bug");
+        expect((e as Error).message).toContain("tool-executor.ts");
+      } finally {
+        dbt.close();
+      }
+    });
+  });
+});