@sleep2agi/commhub-server 0.9.0-preview.8 → 0.9.0-preview.80

package/src/lifecycle-guard.ts

@@ -0,0 +1,50 @@
+// RFC-027 §2.3 race-free invariant — shared helper for the inbox-
+// enqueue lifecycle guard.
+//
+// PR1.1 (#346) added an `assertNodeActive` helper inside the
+// registerTools() closure and applied it at the 6 INSERT INTO inbox
+// sites in server/src/tools.ts. PR1.1 review (通信龙 #346 ack) caught
+// that the closure scope made the helper unreachable from REST
+// handlers in server/src/index.ts — POST /api/task (:1631) and
+// POST /api/broadcast (:1706) are dashboard's "Dispatch" entry
+// points and bypassed the guard, leaving the §2.3 race open on the
+// REST path.
+//
+// PR1.2a (#346 follow-up) extracts the helper to this module so both
+// the MCP tools and the REST handlers can import the same code path,
+// per team rule (grep every write site before adding a guard): any SQL-level
+// guard's helper lives at module scope so every write site
+// (MCP + REST + internal db.ts helpers) can use it.
+//
+// Behaviour:
+//   - no nodes row for the alias → ok:true (brand-new alias allowed;
+//     could be the first INSERT for a child about to register)
+//   - lifecycle_state = 'active' OR NULL (pre-RFC-027 row) → ok:true
+//   - anything else (stopping / stopped / stop_failed / deleting) →
+//     ok:false + structured `node_not_active` reply
+//
+// COALESCE on the WHERE keeps NULL-network inbox rows / legacy nodes
+// rows correctly scoped (PR1 SF-5 lineage).
+
+import { db } from "./db.js";
+
+export type LifecycleGuardResult =
+  | { ok: true }
+  | { ok: false; error: "node_not_active"; lifecycle_state: string; alias: string };
+
+export function assertNodeActive(
+  sessionAlias: string,
+  networkId: string | null,
+): LifecycleGuardResult {
+  if (!sessionAlias) return { ok: true };
+  const row = db.get<{ lifecycle_state: string | null }>(
+    networkId
+      ? `SELECT lifecycle_state FROM nodes WHERE alias = ?1 AND COALESCE(network_id, ?2) = ?2 LIMIT 1`
+      : `SELECT lifecycle_state FROM nodes WHERE alias = ?1 LIMIT 1`,
+    ...(networkId ? [sessionAlias, networkId] : [sessionAlias]),
+  );
+  if (!row) return { ok: true };
+  const st = row.lifecycle_state ?? "active";
+  if (st === "active") return { ok: true };
+  return { ok: false, error: "node_not_active", lifecycle_state: st, alias: sessionAlias };
+}

package/src/mcp-route-label-http.test.ts

@@ -0,0 +1,120 @@
+// POST /mcp in /api/stats/routes carries the JSON-RPC method and, for tools/call, the tool name
+// ("POST /mcp tools/call report_status"). Production showed POST /mcp as the biggest route (15 req/s,
+// ~13% of a core) with no way to tell which tool. This suite pins, over real HTTP:
+//   - the labels (tools/call <name>, tools/list, batch) and that MCP responses are unchanged in kind;
+//   - arguments never reach the stats (a marker in arguments / a hostile tool name never shows up);
+//   - odd bodies still get the transport's own answers (invalid JSON → -32700, oversized → parsed by
+//     the transport itself) and are labelled "?";
+//   - unauthenticated /mcp stays plain "POST /mcp" (the body is never read before auth).
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-mcp-route-label-"));
+process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+
+const PW = "McpRouteLabelPassw0rd!";
+const MARKER = "zz-argument-marker-7f3a";
+let BASE = "";
+let hub: any = null;
+let admin = "";
+
+const MCP_HEADERS = { "Content-Type": "application/json", Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-03-26" };
+async function mcpRaw(token: string, body: string): Promise<{ status: number; text: string }> {
+  const res = await fetch(`${BASE}/mcp`, { method: "POST", headers: { ...(token ? { Authorization: `Bearer ${token}` } : {}), ...MCP_HEADERS }, body });
+  return { status: res.status, text: await res.text() };
+}
+function rpc(text: string): any {
+  const lines = text.split("\n").filter(x => x.startsWith("data:"));
+  return lines.length ? JSON.parse(lines.at(-1)!.slice(5).trim()) : JSON.parse(text);
+}
+async function routes(): Promise<{ text: string; keys: string[]; rows: any[] }> {
+  const res = await fetch(`${BASE}/api/stats/routes?minutes=5`, { headers: { Authorization: `Bearer ${admin}` } });
+  const text = await res.text();
+  const rows = JSON.parse(text).routes as any[];
+  return { text, keys: rows.map(r => r.route), rows };
+}
+
+beforeAll(async () => {
+  process.env.HOST = "127.0.0.1";
+  const { register } = await import("./auth.js");
+  const { db } = await import("./db.js");
+  const a = register(`mrl_admin_${Date.now()}`, PW);
+  admin = a.token!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [a.user!.user_id]);
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("POST /mcp route label", () => {
+  test("tools/call is labelled with the tool name and still answers normally", async () => {
+    const r = await mcpRaw(admin, JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "get_all_status", arguments: { note: MARKER } } }));
+    expect(r.status).toBe(200);
+    expect(rpc(r.text).result).toBeDefined();
+    const { keys } = await routes();
+    expect(keys).toContain("POST /mcp tools/call get_all_status");
+  });
+
+  test("tools/list and a batch get their own labels", async () => {
+    const list = await mcpRaw(admin, JSON.stringify({ jsonrpc: "2.0", id: 2, method: "tools/list" }));
+    expect(list.status).toBe(200);
+    expect(rpc(list.text).result.tools.length).toBeGreaterThan(10);
+    await mcpRaw(admin, JSON.stringify([{ jsonrpc: "2.0", id: 3, method: "tools/list" }]));
+    const { keys } = await routes();
+    expect(keys).toContain("POST /mcp tools/list");
+    expect(keys).toContain("POST /mcp batch");
+  });
+
+  test("arguments and hostile tool names never reach the stats", async () => {
+    await mcpRaw(admin, JSON.stringify({ jsonrpc: "2.0", id: 4, method: "tools/call", params: { name: `x ${MARKER}`, arguments: { a: MARKER } } }));
+    await mcpRaw(admin, JSON.stringify({ jsonrpc: "2.0", id: 5, method: "tools/call", params: { name: "n".repeat(500), arguments: {} } }));
+    await mcpRaw(admin, JSON.stringify({ jsonrpc: "2.0", id: 6, method: `tools/${MARKER} with spaces` }));
+    const { text, keys } = await routes();
+    expect(text).not.toContain(MARKER);
+    expect(text).not.toContain("n".repeat(65));
+    expect(keys).toContain("POST /mcp tools/call ?");
+    expect(keys).toContain("POST /mcp ?");
+    for (const k of keys) expect(k.length).toBeLessThan(200);
+  });
+
+  test("invalid JSON still gets the transport's parse error, labelled ?", async () => {
+    const r = await mcpRaw(admin, `{"jsonrpc":"2.0","method":"tools/list",`);
+    expect(r.status).toBe(400);
+    expect(rpc(r.text).error.code).toBe(-32700);
+    expect(rpc(r.text).error.message).toBe("Parse error: Invalid JSON");
+    const notRpc = await mcpRaw(admin, "null");
+    expect(notRpc.status).toBe(400);
+    expect(rpc(notRpc.text).error.code).toBe(-32700);
+  });
+
+  test("a body over the label limit is left to the transport and still works, labelled ?", async () => {
+    const { __resetRouteTimingForTest } = await import("./route-timing.js");
+    __resetRouteTimingForTest();
+    const padded = JSON.stringify({ jsonrpc: "2.0", id: 7, method: "tools/list" }).replace("{", "{" + " ".repeat(1024 * 1024 + 10));
+    const r = await mcpRaw(admin, padded);
+    expect(r.status).toBe(200);
+    expect(rpc(r.text).result.tools.length).toBeGreaterThan(10);
+    const { keys } = await routes();
+    expect(keys).toContain("POST /mcp ?");
+    expect(keys).not.toContain("POST /mcp tools/list");
+  });
+
+  test("unauthenticated /mcp is refused as before and not labelled", async () => {
+    const { __resetRouteTimingForTest } = await import("./route-timing.js");
+    __resetRouteTimingForTest();
+    const r = await mcpRaw("", JSON.stringify({ jsonrpc: "2.0", id: 8, method: "tools/list" }));
+    expect(r.status).toBe(401);
+    const { keys } = await routes();
+    expect(keys).toContain("POST /mcp");
+    expect(keys.filter(k => k.startsWith("POST /mcp "))).toEqual([]);
+  });
+});

package/src/mcp-write-network-resolution.test.ts

@@ -0,0 +1,429 @@
+// #517 — MCP write-path network resolution (utok single-network fallback).
+//
+// Root cause (issue #517): utok_ token rows are created with network_id=null
+// BY DESIGN (auth.ts login), and the MCP write path (tools.ts canWrite) had
+// no single-network fallback — unlike REST POST /api/task (server.ts), which
+// auto-resolves via singleNetworkId(restScope) when the user belongs to
+// exactly one network. Result: a utok node could READ everything
+// (resolveReadScope falls back to all memberships) but could not WRITE
+// anything, and the error mislabeled the failure as permission_denied.
+//
+// Fix under test:
+//  - getNetworkId falls back to the user's single membership via the SAME
+//    shared singleNetworkId/getUserNetworkIds used by REST (network-scope.ts)
+//  - canWrite delegates to the shared canRestWriteNetwork
+//  - the 7 write tools that had NO network_id input gain an optional one:
+//    send_message / send_reply / ack_inbox / send_ack / retry_task /
+//    cancel_task / reassign_task
+//  - writeDeniedReply names the REAL cause: network_id_required (0 or ≥2
+//    memberships) / access_denied (not a member of the requested network) /
+//    permission_denied (viewer role)
+//  - ntok_ (network-bound) behavior: ZERO change — pinned below
+//
+// Assertion discipline: error replies are asserted with toEqual (accepted
+// set == spec-allowed set, no not.toBe / toContain wideners).
+//
+// Run: COMMHUB_DB=/tmp/517-net-scope-test.db bun test src/mcp-write-network-resolution.test.ts
+
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { db, uuidv4 } from "./db.js";
+import { deleteNetwork } from "./auth.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools } from "./tools.js";
+
+const NET_A = "net_517_a";
+const NET_B = "net_517_b";
+const U_SINGLE = "u517_single";    // owner of NET_A only → fallback resolves
+const U_MULTI = "u517_multi";      // member of NET_A + NET_B → ambiguous
+const U_VIEWER = "u517_viewer";    // viewer of NET_A only → resolves, then role-denied
+const U_NONE = "u517_none";        // no memberships
+const U_OUTSIDER = "u517_outsider"; // member of NET_B only, targets NET_A
+const A1 = "peer-517-a1";
+const A2 = "peer-517-a2";
+const ALL_USERS = [U_SINGLE, U_MULTI, U_VIEWER, U_NONE, U_OUTSIDER];
+
+interface ToolHandler {
+  (args: any, extra?: any): Promise<{ content: Array<{ type: "text"; text: string }> }>;
+}
+interface Reply { ok?: boolean; error?: string; message?: string; [k: string]: unknown }
+
+function cleanup() {
+  for (const t of ["tasks", "inbox", "task_events"]) {
+    try { db.run(`DELETE FROM ${t} WHERE network_id IN (?1, ?2)`, [NET_A, NET_B]); } catch {}
+    try { db.run(`DELETE FROM ${t} WHERE content LIKE 'x517%'`); } catch {}
+  }
+  try { db.run("DELETE FROM sessions WHERE network_id IN (?1, ?2)", [NET_A, NET_B]); } catch {}
+  try { db.run("DELETE FROM nodes WHERE network_id IN (?1, ?2)", [NET_A, NET_B]); } catch {}
+  try { db.run("DELETE FROM network_members WHERE network_id IN (?1, ?2)", [NET_A, NET_B]); } catch {}
+  try { db.run("DELETE FROM networks WHERE network_id IN (?1, ?2)", [NET_A, NET_B]); } catch {}
+  for (const u of ALL_USERS) {
+    try { db.run("DELETE FROM users WHERE user_id = ?1", [u]); } catch {}
+  }
+}
+
+function seed() {
+  for (const u of ALL_USERS) {
+    db.run(
+      `INSERT INTO users (user_id, username, password_hash, role, created_at)
+       VALUES (?1, ?2, 'x', 'user', datetime('now'))`,
+      [u, u],
+    );
+  }
+  db.run(`INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?1, ?2, datetime('now'))`, [NET_A, U_SINGLE]);
+  db.run(`INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?1, ?2, datetime('now'))`, [NET_B, U_MULTI]);
+  const member = (u: string, net: string, role: string) =>
+    db.run(`INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, ?3, datetime('now'))`, [u, net, role]);
+  member(U_SINGLE, NET_A, "owner");
+  member(U_MULTI, NET_A, "member");
+  member(U_MULTI, NET_B, "owner");
+  member(U_VIEWER, NET_A, "viewer");
+  member(U_OUTSIDER, NET_B, "member");
+  for (const alias of [A1, A2]) {
+    db.run(
+      `INSERT INTO nodes (node_id, node_name, alias, network_id, hostname, created_at, updated_at, lifecycle_state)
+       VALUES (?1, ?2, ?2, ?3, ?4, datetime('now'), datetime('now'), 'active')`,
+      [`node_${alias}`, alias, NET_A, `host-${alias}`],
+    );
+    db.run(
+      `INSERT INTO sessions (resume_id, alias, status, node_id, network_id, updated_at, last_seen_at)
+       VALUES (?1, ?2, 'idle', ?3, ?4, datetime('now'), datetime('now'))`,
+      [`res_${alias}`, alias, `node_${alias}`, NET_A],
+    );
+  }
+}
+
+beforeEach(() => { cleanup(); seed(); });
+afterAll(cleanup);
+
+type HandlerMap = { tools: Record<string, ToolHandler>; schemas: Record<string, Record<string, unknown>> };
+
+function buildHandlers(opts: { netId?: string | null; userId?: string | null; alias?: string | null; isNetwork?: boolean }): HandlerMap {
+  const server = new McpServer({ name: "test", version: "0" }) as any;
+  const tools: Record<string, ToolHandler> = {};
+  const schemas: Record<string, Record<string, unknown>> = {};
+  const origTool = server.tool.bind(server);
+  server.tool = (name: string, _desc: string, schema: any, handler: ToolHandler) => {
+    tools[name] = handler;
+    schemas[name] = schema;
+    return origTool(name, _desc, schema, handler);
+  };
+  registerTools(
+    server,
+    undefined,
+    opts.netId ?? null,
+    opts.userId ?? null,
+    opts.alias ?? opts.userId ?? null,
+    opts.isNetwork ?? false,
+    null,
+  );
+  return { tools, schemas };
+}
+
+async function call(handler: ToolHandler, args: any): Promise<Reply> {
+  const r = await handler(args);
+  return JSON.parse(r.content[0].text) as Reply;
+}
+
+function makeTask(to: string, status: string, content: string, net: string | null = NET_A): string {
+  const id = uuidv4();
+  db.run(
+    `INSERT INTO tasks (task_id, from_name, to_name, priority, status, content, requires_response, created_at, network_id)
+     VALUES (?1, 'dispatcher', ?2, 'normal', ?3, ?4, 'reply', datetime('now'), ?5)`,
+    [id, to, status, content, net],
+  );
+  return id;
+}
+
+function makeInbox(to: string, content: string, net: string | null = NET_A): string {
+  const id = uuidv4();
+  db.run(
+    `INSERT INTO inbox (id, session_name, node_id, type, priority, content, from_session, network_id)
+     VALUES (?1, ?2, ?3, 'message', 'normal', ?4, 'dispatcher', ?5)`,
+    [id, to, `node_${to}`, content, net],
+  );
+  return id;
+}
+
+const taskRow = (content: string) =>
+  db.get<{ task_id: string; status: string; to_name: string; network_id: string | null }>(
+    "SELECT task_id, status, to_name, network_id FROM tasks WHERE content = ?1", content);
+const taskById = (id: string) =>
+  db.get<{ status: string; to_name: string; network_id: string | null }>(
+    "SELECT status, to_name, network_id FROM tasks WHERE task_id = ?1", id);
+const inboxRow = (content: string) =>
+  db.get<{ id: string; acked: number; network_id: string | null }>(
+    "SELECT id, acked, network_id FROM inbox WHERE content = ?1", content);
+
+// ─────────────────────────────────────────────────────────────────────
+// Group 1 — utok, single network, NO network_id argument anywhere.
+// The hub must auto-resolve to the user's only membership (REST parity
+// with server.ts POST /api/task → singleNetworkId fallback).
+// ─────────────────────────────────────────────────────────────────────
+describe("utok single-network auto-resolve (no network_id argument)", () => {
+  test("send_task resolves to the only membership", async () => {
+    const { tools } = buildHandlers({ userId: U_SINGLE });
+    const r = await call(tools["send_task"], { alias: A1, task: "x517 g1 send_task", priority: "normal" });
+    expect(r.ok).toBe(true);
+    expect(taskRow("x517 g1 send_task")?.network_id).toBe(NET_A);
+  });
+
+  test("send_message resolves to the only membership", async () => {
+    const { tools } = buildHandlers({ userId: U_SINGLE });
+    const r = await call(tools["send_message"], { alias: A1, message: "x517 g1 send_message" });
+    expect(r.ok).toBe(true);
+    expect(inboxRow("x517 g1 send_message")?.network_id).toBe(NET_A);
+  });
+
+  test("send_reply resolves to the only membership", async () => {
+    const { tools } = buildHandlers({ userId: U_SINGLE });
+    const t = makeTask(A1, "delivered", "x517 g1 send_reply parent");
+    const r = await call(tools["send_reply"], { alias: A1, text: "x517 g1 send_reply", in_reply_to: t, status: "replied" });
+    expect(r.ok).toBe(true);
+    expect(taskById(t)?.status).toBe("replied");
+  });
+
+  test("ack_inbox resolves to the only membership", async () => {
+    const { tools } = buildHandlers({ userId: U_SINGLE });
+    const ib = makeInbox(A1, "x517 g1 ack_inbox");
+    const r = await call(tools["ack_inbox"], { alias: A1, message_id: ib });
+    expect(r.ok).toBe(true);
+    expect(inboxRow("x517 g1 ack_inbox")?.acked).toBe(1);
+  });
+
+  test("send_ack resolves to the only membership", async () => {
+    const { tools } = buildHandlers({ userId: U_SINGLE });
+    const t = makeTask(A1, "delivered", "x517 g1 send_ack");
+    const r = await call(tools["send_ack"], { task_id: t });
+    expect(r.ok).toBe(true);
+    expect(taskById(t)?.status).toBe("acked");
+  });
+
+  test("retry_task resolves to the only membership", async () => {
+    const { tools } = buildHandlers({ userId: U_SINGLE });
+    const t = makeTask(A1, "failed", "x517 g1 retry_task");
+    const r = await call(tools["retry_task"], { task_id: t });
+    expect(r.ok).toBe(true);
+    expect(taskById(t)?.status).toBe("delivered");
+  });
+
+  test("cancel_task resolves to the only membership", async () => {
+    const { tools } = buildHandlers({ userId: U_SINGLE });
+    const t = makeTask(A1, "delivered", "x517 g1 cancel_task");
+    const r = await call(tools["cancel_task"], { task_id: t });
+    expect(r.ok).toBe(true);
+    expect(taskById(t)?.status).toBe("cancelled");
+  });
+
+  test("reassign_task resolves to the only membership", async () => {
+    const { tools } = buildHandlers({ userId: U_SINGLE });
+    const t = makeTask(A1, "delivered", "x517 g1 reassign_task");
+    const r = await call(tools["reassign_task"], { task_id: t, new_alias: A2 });
+    expect(r.ok).toBe(true);
+    expect(taskById(t)?.to_name).toBe(A2);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────
+// Group 2 — utok, MULTI network. Without network_id: precise
+// network_id_required error (not permission_denied). With explicit
+// network_id: every formerly param-less tool must thread it through.
+// One case per changed tool (通信龙 acceptance rule: 改了三个只测一个,
+// 剩下两个等于没验).
+// ─────────────────────────────────────────────────────────────────────
+describe("utok multi-network", () => {
+  test("send_task without network_id → exact network_id_required error", async () => {
+    const { tools } = buildHandlers({ userId: U_MULTI });
+    const r = await call(tools["send_task"], { alias: A1, task: "x517 g2 ambiguous", priority: "normal" });
+    expect(r).toEqual({
+      ok: false,
+      error: "network_id_required",
+      message: "user token spans 2 networks; pass network_id explicitly (see /api/auth/me networks[].network_id)",
+    });
+    expect(taskRow("x517 g2 ambiguous")).toBeNull();
+  });
+
+  test("send_message threads explicit network_id", async () => {
+    const { tools } = buildHandlers({ userId: U_MULTI });
+    const r = await call(tools["send_message"], { alias: A1, message: "x517 g2 send_message", network_id: NET_A });
+    expect(r.ok).toBe(true);
+    expect(inboxRow("x517 g2 send_message")?.network_id).toBe(NET_A);
+  });
+
+  test("send_reply threads explicit network_id", async () => {
+    const { tools } = buildHandlers({ userId: U_MULTI });
+    const t = makeTask(A1, "delivered", "x517 g2 send_reply parent");
+    const r = await call(tools["send_reply"], { alias: A1, text: "x517 g2 send_reply", in_reply_to: t, status: "replied", network_id: NET_A });
+    expect(r.ok).toBe(true);
+    expect(taskById(t)?.status).toBe("replied");
+  });
+
+  test("ack_inbox threads explicit network_id", async () => {
+    const { tools } = buildHandlers({ userId: U_MULTI });
+    const ib = makeInbox(A1, "x517 g2 ack_inbox");
+    const r = await call(tools["ack_inbox"], { alias: A1, message_id: ib, network_id: NET_A });
+    expect(r.ok).toBe(true);
+    expect(inboxRow("x517 g2 ack_inbox")?.acked).toBe(1);
+  });
+
+  test("send_ack threads explicit network_id", async () => {
+    const { tools } = buildHandlers({ userId: U_MULTI });
+    const t = makeTask(A1, "delivered", "x517 g2 send_ack");
+    const r = await call(tools["send_ack"], { task_id: t, network_id: NET_A });
+    expect(r.ok).toBe(true);
+    expect(taskById(t)?.status).toBe("acked");
+  });
+
+  test("retry_task threads explicit network_id", async () => {
+    const { tools } = buildHandlers({ userId: U_MULTI });
+    const t = makeTask(A1, "failed", "x517 g2 retry_task");
+    const r = await call(tools["retry_task"], { task_id: t, network_id: NET_A });
+    expect(r.ok).toBe(true);
+    expect(taskById(t)?.status).toBe("delivered");
+  });
+
+  test("cancel_task threads explicit network_id", async () => {
+    const { tools } = buildHandlers({ userId: U_MULTI });
+    const t = makeTask(A1, "delivered", "x517 g2 cancel_task");
+    const r = await call(tools["cancel_task"], { task_id: t, network_id: NET_A });
+    expect(r.ok).toBe(true);
+    expect(taskById(t)?.status).toBe("cancelled");
+  });
+
+  test("reassign_task threads explicit network_id", async () => {
+    const { tools } = buildHandlers({ userId: U_MULTI });
+    const t = makeTask(A1, "delivered", "x517 g2 reassign_task");
+    const r = await call(tools["reassign_task"], { task_id: t, new_alias: A2, network_id: NET_A });
+    expect(r.ok).toBe(true);
+    expect(taskById(t)?.to_name).toBe(A2);
+  });
+
+  test("all 7 formerly param-less write tools expose network_id in their input schema", () => {
+    const { schemas } = buildHandlers({ userId: U_MULTI });
+    for (const name of ["send_message", "send_reply", "ack_inbox", "send_ack", "retry_task", "cancel_task", "reassign_task"]) {
+      expect(Object.keys(schemas[name] ?? {})).toContain("network_id");
+    }
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────
+// Group 3 — precise causes replace the old catch-all message.
+// ─────────────────────────────────────────────────────────────────────
+describe("precise denial causes", () => {
+  test("utok with zero memberships → network_id_required naming the real cause", async () => {
+    const { tools } = buildHandlers({ userId: U_NONE });
+    const r = await call(tools["send_task"], { alias: A1, task: "x517 g3 none", priority: "normal" });
+    expect(r).toEqual({
+      ok: false,
+      error: "network_id_required",
+      message: "user token has no network memberships; join or create a network first",
+    });
+  });
+
+  test("utok explicitly targeting a network it is not a member of → access_denied", async () => {
+    const { tools } = buildHandlers({ userId: U_OUTSIDER });
+    const r = await call(tools["send_task"], { alias: A1, task: "x517 g3 outsider", priority: "normal", network_id: NET_A });
+    expect(r).toEqual({
+      ok: false,
+      error: "access_denied",
+      message: "access denied to requested network (not a member)",
+    });
+    expect(taskRow("x517 g3 outsider")).toBeNull();
+  });
+
+  test("viewer in a single network → permission_denied (send_task wording)", async () => {
+    const { tools } = buildHandlers({ userId: U_VIEWER });
+    const r = await call(tools["send_task"], { alias: A1, task: "x517 g3 viewer task", priority: "normal" });
+    expect(r).toEqual({
+      ok: false,
+      error: "permission_denied",
+      message: "Viewer role cannot send tasks",
+    });
+  });
+
+  test("viewer in a single network → permission_denied (generic write wording)", async () => {
+    const { tools } = buildHandlers({ userId: U_VIEWER });
+    const r = await call(tools["send_message"], { alias: A1, message: "x517 g3 viewer msg" });
+    expect(r).toEqual({
+      ok: false,
+      error: "permission_denied",
+      message: "Viewer role cannot write to this network",
+    });
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────
+// Group 3b — ghost memberships (PR #519 codex P2): deleteNetwork used to
+// leave network_members rows behind, so a stale membership to a deleted
+// network could (a) make a single-network user look multi-network, or
+// (b) auto-resolve a write INTO the deleted network, creating orphaned
+// rows. getUserNetworkIds now joins networks; deleteNetwork now removes
+// its membership rows.
+// ─────────────────────────────────────────────────────────────────────
+describe("ghost memberships (deleted networks)", () => {
+  const GHOST = "net_517_ghost";
+
+  test("membership to a deleted network does not break single-network auto-resolve", async () => {
+    // stale row: membership exists, networks row does not
+    db.run(`INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, 'owner', datetime('now'))`, [U_SINGLE, GHOST]);
+    const { tools } = buildHandlers({ userId: U_SINGLE });
+    const r = await call(tools["send_task"], { alias: A1, task: "x517 ghost still-single", priority: "normal" });
+    expect(r.ok).toBe(true);
+    expect(taskRow("x517 ghost still-single")?.network_id).toBe(NET_A);
+    db.run("DELETE FROM network_members WHERE network_id = ?1", [GHOST]);
+  });
+
+  test("sole membership pointing at a deleted network → no-membership error, no orphaned write", async () => {
+    db.run(`INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, 'owner', datetime('now'))`, [U_NONE, GHOST]);
+    const { tools } = buildHandlers({ userId: U_NONE });
+    const r = await call(tools["send_task"], { alias: A1, task: "x517 ghost orphan", priority: "normal" });
+    expect(r).toEqual({
+      ok: false,
+      error: "network_id_required",
+      message: "user token has no network memberships; join or create a network first",
+    });
+    expect(taskRow("x517 ghost orphan")).toBeNull();
+    db.run("DELETE FROM network_members WHERE network_id = ?1", [GHOST]);
+  });
+
+  test("deleteNetwork removes the network's membership rows (root cause)", () => {
+    const NET_DEL = "net_517_del";
+    db.run(`INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?1, ?2, datetime('now'))`, [NET_DEL, U_SINGLE]);
+    db.run(`INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, 'owner', datetime('now'))`, [U_SINGLE, NET_DEL]);
+    const res = deleteNetwork(U_SINGLE, NET_DEL);
+    expect(res.ok).toBe(true);
+    const left = db.get<{ cnt: number }>("SELECT COUNT(*) as cnt FROM network_members WHERE network_id = ?1", NET_DEL);
+    expect(left?.cnt).toBe(0);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────
+// Group 4 — ntok_ pins: network-bound tokens must see ZERO change.
+// ─────────────────────────────────────────────────────────────────────
+describe("ntok behavior pinned (zero change)", () => {
+  test("ntok send_task without network_id stays bound to token network", async () => {
+    const { tools } = buildHandlers({ netId: NET_A, userId: U_SINGLE, alias: A1, isNetwork: true });
+    const r = await call(tools["send_task"], { alias: A2, task: "x517 g4 ntok plain", priority: "normal" });
+    expect(r.ok).toBe(true);
+    expect(taskRow("x517 g4 ntok plain")?.network_id).toBe(NET_A);
+  });
+
+  test("ntok send_task ignores a client-supplied foreign network_id (enforced binding wins)", async () => {
+    const { tools } = buildHandlers({ netId: NET_A, userId: U_MULTI, alias: A1, isNetwork: true });
+    const r = await call(tools["send_task"], { alias: A2, task: "x517 g4 ntok override", priority: "normal", network_id: NET_B });
+    expect(r.ok).toBe(true);
+    expect(taskRow("x517 g4 ntok override")?.network_id).toBe(NET_A);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────
+// Group 5 — legacy global-token mode (no enforceUserId): the fallback
+// must NOT kick in; writes stay unscoped exactly as before.
+// ─────────────────────────────────────────────────────────────────────
+describe("legacy global-token mode pinned", () => {
+  test("send_message without auth context stays network-unscoped", async () => {
+    const { tools } = buildHandlers({ userId: null });
+    const r = await call(tools["send_message"], { alias: A1, message: "x517 g5 legacy" });
+    expect(r.ok).toBe(true);
+    expect(inboxRow("x517 g5 legacy")?.network_id).toBeNull();
+  });
+});