@sleep2agi/commhub-server 0.9.0-preview.2 → 0.9.0-preview.21

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.2",
-  "description": "CommHub Server \u2014 AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and 17 MCP tools.",
+  "version": "0.9.0-preview.21",
+  "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and 17 MCP tools.",
   "type": "module",
   "main": "src/index.ts",
   "bin": {

package/src/ack-create-request.test.ts

@@ -0,0 +1,331 @@
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { db } from "./db.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools } from "./tools.js";
+
+// RFC-026 §9.3 D2 / #338 PR3 — ack_create_request HANDLER tests.
+//
+// 通信龙 pre-review caught B1 + B2: my first cut of PR3 added a new daemon
+// ack status `runtime_capability_check_failed` to create-node-daemon.ts but
+// the hub's zod enum only accepted ["started", "failed", "rejected"] — the
+// new status was silently zod-rejected on the hub side and the daemon's
+// `.catch(()=>{})` swallowed the rejection. The PR body also claimed
+// `daemon_capability_lied` audit was written when in fact the action wasn't
+// in the audit enum and no insert ran.
+//
+// This handler-driven suite drives the registered MCP tool through
+// registerTools() so a daemon's exact ack shape (status + runtime field)
+// flows through the real zod schema + handler branch + audit insert. It
+// would have caught the lane-recurring "single component passes but cross-
+// component path stays broken" failure mode immediately.
+
+const NET = "net_ack_t";
+const DAEMON_NODE_ID = "node_ack_daemon";
+const DAEMON_ALIAS = "ack-daemon";
+const DAEMON_USER = "u_ack_owner";
+const DAEMON_TOKEN_ID = "tok_ack_daemon";
+const DAEMON_TOKEN_HASH = "hash_ack_daemon";
+
+interface ToolHandler { (args: any, extra?: any): Promise<{ content: Array<{ type: "text"; text: string }> }>; }
+interface AckReply { ok?: boolean; error?: string; status?: string; }
+
+function cleanup() {
+  try { db.run("DELETE FROM audit_log WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM node_create_requests WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM nodes WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM api_tokens WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM network_members WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM networks WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM users WHERE user_id = ?1", [DAEMON_USER]); } catch {}
+}
+
+beforeEach(cleanup);
+afterAll(cleanup);
+
+function seedDaemonWorld() {
+  db.run(
+    `INSERT INTO users (user_id, username, password_hash, role, created_at)
+     VALUES (?1, ?2, 'x', 'user', datetime('now'))`,
+    [DAEMON_USER, DAEMON_USER],
+  );
+  db.run(
+    `INSERT OR REPLACE INTO networks (network_id, network_name, owner_id, created_at)
+     VALUES (?1, ?2, ?3, datetime('now'))`,
+    [NET, NET, DAEMON_USER],
+  );
+  db.run(
+    `INSERT INTO network_members (user_id, network_id, role, joined_at)
+     VALUES (?1, ?2, 'owner', datetime('now'))`,
+    [DAEMON_USER, NET],
+  );
+  // daemon node — must exist for resolveCallerDaemonTokenBound to bind.
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, created_at, updated_at)
+     VALUES (?1, ?2, ?3, ?4, datetime('now'), datetime('now'))`,
+    [DAEMON_NODE_ID, DAEMON_ALIAS, DAEMON_ALIAS, NET],
+  );
+  // daemon ntok — bound to the daemon node via name='node:<alias>'.
+  db.run(
+    `INSERT INTO api_tokens (token_id, user_id, network_id, scope, name, token_hash, expires_at, revoked_at)
+     VALUES (?1, ?2, ?3, 'network', ?4, ?5, NULL, NULL)`,
+    [DAEMON_TOKEN_ID, DAEMON_USER, NET, `node:${DAEMON_ALIAS}`, DAEMON_TOKEN_HASH],
+  );
+}
+
+function seedCreateRequest(opts: {
+  request_id: string,
+  child_token_id?: string,
+  status?: "pending" | "delivered" | "succeeded" | "failed",
+  child_name?: string,
+  runtime?: string,
+}) {
+  const childName = opts.child_name ?? `child_${opts.request_id}`;
+  if (opts.child_token_id) {
+    db.run(
+      `INSERT INTO api_tokens (token_id, user_id, network_id, scope, name, token_hash, expires_at, revoked_at)
+       VALUES (?1, ?2, ?3, 'network', ?4, ?5, NULL, NULL)`,
+      [opts.child_token_id, DAEMON_USER, NET, `node:${childName}`, `hash_${opts.child_token_id}`],
+    );
+  }
+  db.run(
+    `INSERT INTO node_create_requests
+       (request_id, daemon_node_id, child_name, network_id, runtime, model, flags_json, env_keys, status, child_token_id, created_at, created_by_token)
+     VALUES (?1, ?2, ?3, ?4, ?5, 'x', '{}', '[]', ?6, ?7, ?8, ?9)`,
+    [
+      opts.request_id, DAEMON_NODE_ID, childName, NET,
+      opts.runtime ?? "claude-agent-sdk",
+      opts.status ?? "delivered",
+      opts.child_token_id ?? null,
+      Date.now(),
+      DAEMON_TOKEN_ID,
+    ],
+  );
+}
+
+/** Build a server with registerTools wired as if the daemon's ntok bound. */
+function buildAckHandler(): ToolHandler {
+  const server = new McpServer({ name: "test", version: "0" }) as any;
+  const tools: Record<string, ToolHandler> = {};
+  const origTool = server.tool.bind(server);
+  server.tool = (name: string, _desc: string, _schema: any, handler: ToolHandler) => {
+    tools[name] = handler;
+    return origTool(name, _desc, _schema, handler);
+  };
+  const origRegisterTool = server.registerTool?.bind(server);
+  if (origRegisterTool) {
+    server.registerTool = (name: string, _cfg: any, handler: ToolHandler) => {
+      tools[name] = handler;
+      return origRegisterTool(name, _cfg, handler);
+    };
+  }
+  registerTools(
+    server,
+    /* clientIP */ undefined,
+    /* enforceNetworkId */ NET,
+    /* enforceUserId */ DAEMON_USER,
+    /* callerAlias */ DAEMON_ALIAS,
+    /* callerTokenIsNetwork */ true,
+    /* callerTokenId */ DAEMON_TOKEN_ID,
+  );
+  const h = tools["ack_create_request"];
+  if (!h) throw new Error("ack_create_request tool not registered");
+  return h;
+}
+
+async function callAck(handler: ToolHandler, args: any): Promise<AckReply> {
+  const r = await handler(args);
+  return JSON.parse(r.content[0].text) as AckReply;
+}
+
+function readRequest(request_id: string) {
+  return db.get<{ status: string; error: string | null; acked_at: number | null }>(
+    `SELECT status, error, acked_at FROM node_create_requests WHERE request_id = ?1`,
+    request_id,
+  );
+}
+
+function readToken(token_id: string) {
+  return db.get<{ revoked_at: string | null }>(
+    `SELECT revoked_at FROM api_tokens WHERE token_id = ?1`,
+    token_id,
+  );
+}
+
+function readAuditRows(action: string, target_id: string) {
+  return db.all<{ action: string; network_id: string; target_id: string; detail: string }>(
+    `SELECT action, network_id, target_id, detail FROM audit_log
+     WHERE action = ?1 AND target_id = ?2 ORDER BY id DESC`,
+    [action, target_id],
+  );
+}
+
+describe("ack_create_request HANDLER — B1 schema accepts runtime_capability_check_failed", () => {
+  test("schema accepts runtime_capability_check_failed + runtime field (no zod reject)", async () => {
+    seedDaemonWorld();
+    const reqId = "cr_ack_b1_accept";
+    seedCreateRequest({ request_id: reqId });
+    const handler = buildAckHandler();
+    const reply = await callAck(handler, {
+      request_id: reqId,
+      status: "runtime_capability_check_failed",
+      error: "child died within 5000ms post-spawn",
+      runtime: "codex-sdk",
+    });
+    // PR3 v1 BUG: hub zod enum rejected this status → reply.ok=false /
+    // tool would even throw before getting here. Now must accept.
+    expect(reply.ok).toBe(true);
+    expect(reply.status).toBe("runtime_capability_check_failed");
+  });
+
+  test("request flips to terminal runtime_capability_check_failed status", async () => {
+    seedDaemonWorld();
+    const reqId = "cr_ack_b1_terminal";
+    seedCreateRequest({ request_id: reqId, status: "delivered" });
+    const handler = buildAckHandler();
+    await callAck(handler, {
+      request_id: reqId,
+      status: "runtime_capability_check_failed",
+      error: "boom",
+      runtime: "codex-sdk",
+    });
+    const row = readRequest(reqId);
+    expect(row?.status).toBe("runtime_capability_check_failed");
+    expect(row?.error).toBe("boom");
+    expect(row?.acked_at).toBeGreaterThan(0);
+  });
+
+  test("child ntok is revoked on capability-check-failed (same teardown as 'failed')", async () => {
+    seedDaemonWorld();
+    const reqId = "cr_ack_b1_revoke";
+    const childTok = "tok_ack_child_b1";
+    seedCreateRequest({ request_id: reqId, child_token_id: childTok });
+    expect(readToken(childTok)?.revoked_at).toBeNull();
+    const handler = buildAckHandler();
+    await callAck(handler, {
+      request_id: reqId,
+      status: "runtime_capability_check_failed",
+      runtime: "codex-sdk",
+    });
+    expect(readToken(childTok)?.revoked_at).not.toBeNull();
+  });
+});
+
+describe("ack_create_request HANDLER — B2 audit_log daemon_capability_lied", () => {
+  test("writes daemon_capability_lied audit row with runtime + daemon + error in detail", async () => {
+    seedDaemonWorld();
+    const reqId = "cr_ack_b2_audit";
+    seedCreateRequest({ request_id: reqId });
+    const handler = buildAckHandler();
+    await callAck(handler, {
+      request_id: reqId,
+      status: "runtime_capability_check_failed",
+      error: "OPENAI_API_KEY unset",
+      runtime: "codex-sdk",
+    });
+    const rows = readAuditRows("daemon_capability_lied", reqId);
+    // PR3 v1 BUG: action wasn't in auditCreateNode enum → 0 rows + no
+    // surface for ops to spot lying daemons. Now must write exactly 1.
+    expect(rows.length).toBe(1);
+    expect(rows[0].network_id).toBe(NET);
+    const detail = JSON.parse(rows[0].detail);
+    expect(detail.runtime).toBe("codex-sdk");
+    expect(detail.daemon_node_id).toBe(DAEMON_NODE_ID);
+    expect(detail.error).toBe("OPENAI_API_KEY unset");
+    expect(typeof detail.acked_at).toBe("number");
+  });
+
+  test("does NOT write daemon_capability_lied on generic 'failed' ack (status discriminates)", async () => {
+    seedDaemonWorld();
+    const reqId = "cr_ack_b2_no_audit_on_failed";
+    seedCreateRequest({ request_id: reqId });
+    const handler = buildAckHandler();
+    await callAck(handler, {
+      request_id: reqId,
+      status: "failed",
+      error: "child died immediately after spawn",
+    });
+    const rows = readAuditRows("daemon_capability_lied", reqId);
+    expect(rows.length).toBe(0);
+  });
+
+  test("does NOT write daemon_capability_lied on 'started' (happy path silence)", async () => {
+    seedDaemonWorld();
+    const reqId = "cr_ack_b2_no_audit_on_started";
+    seedCreateRequest({ request_id: reqId });
+    const handler = buildAckHandler();
+    await callAck(handler, { request_id: reqId, status: "started", child_pid: 12345 });
+    const rows = readAuditRows("daemon_capability_lied", reqId);
+    expect(rows.length).toBe(0);
+  });
+
+  test("runtime field nullable if daemon omitted it (older daemon back-compat)", async () => {
+    // Older daemon (preview.10 and earlier) wouldn't send `runtime`.
+    // The hub must still accept + audit, just with runtime=null.
+    seedDaemonWorld();
+    const reqId = "cr_ack_b2_nullable_runtime";
+    seedCreateRequest({ request_id: reqId });
+    const handler = buildAckHandler();
+    const reply = await callAck(handler, {
+      request_id: reqId,
+      status: "runtime_capability_check_failed",
+      error: "child died",
+    });
+    expect(reply.ok).toBe(true);
+    const rows = readAuditRows("daemon_capability_lied", reqId);
+    expect(rows.length).toBe(1);
+    const detail = JSON.parse(rows[0].detail);
+    expect(detail.runtime).toBeNull();
+  });
+
+  test("error string is truncated to 500 chars in audit detail (defense vs giant payload)", async () => {
+    seedDaemonWorld();
+    const reqId = "cr_ack_b2_trunc";
+    seedCreateRequest({ request_id: reqId });
+    const handler = buildAckHandler();
+    const giant = "x".repeat(900);
+    await callAck(handler, {
+      request_id: reqId,
+      status: "runtime_capability_check_failed",
+      error: giant,
+      runtime: "codex-sdk",
+    });
+    const rows = readAuditRows("daemon_capability_lied", reqId);
+    expect(rows.length).toBe(1);
+    const detail = JSON.parse(rows[0].detail);
+    expect(detail.error.length).toBe(500);
+  });
+});
+
+describe("ack_create_request HANDLER — pre-existing happy-path stays green (regression)", () => {
+  test("status='started' still flips acked_at without terminal teardown", async () => {
+    seedDaemonWorld();
+    const reqId = "cr_ack_started_regression";
+    const childTok = "tok_ack_child_started";
+    seedCreateRequest({ request_id: reqId, child_token_id: childTok });
+    const handler = buildAckHandler();
+    const reply = await callAck(handler, { request_id: reqId, status: "started", child_pid: 7777 });
+    expect(reply.ok).toBe(true);
+    expect(reply.status).toBe("awaiting_register");
+    const row = readRequest(reqId);
+    // 'started' doesn't flip to terminal; status stays 'delivered'.
+    expect(row?.status).toBe("delivered");
+    expect(row?.acked_at).toBeGreaterThan(0);
+    // child ntok is NOT revoked on 'started'.
+    expect(readToken(childTok)?.revoked_at).toBeNull();
+  });
+
+  test("status='failed' still revokes child + flips to failed (no audit_log daemon_capability_lied)", async () => {
+    seedDaemonWorld();
+    const reqId = "cr_ack_failed_regression";
+    const childTok = "tok_ack_child_failed";
+    seedCreateRequest({ request_id: reqId, child_token_id: childTok });
+    const handler = buildAckHandler();
+    const reply = await callAck(handler, { request_id: reqId, status: "failed", error: "fork failed" });
+    expect(reply.ok).toBe(true);
+    const row = readRequest(reqId);
+    expect(row?.status).toBe("failed");
+    expect(row?.error).toBe("fork failed");
+    expect(readToken(childTok)?.revoked_at).not.toBeNull();
+    expect(readAuditRows("daemon_capability_lied", reqId).length).toBe(0);
+  });
+});

package/src/api-host-supervisors-fallback.test.ts

@@ -0,0 +1,262 @@
+// #380 fix — REST /api/host-supervisors utok→default-network fallback.
+//
+// Before this patch the endpoint hard-4xxed when the client omitted the
+// `network_id` query param. The dashboard's create-node wizard was
+// reported as "hub 400" against a prod hub that had zero daemons AND was
+// being polled without the query — the frontend read that as "no
+// available servers" and blocked the wizard.
+//
+// Post-fix contract:
+//   - ntok caller                                → uses bound network (existing)
+//   - utok caller + `?network_id=...` verified   → uses that (existing)
+//   - utok caller + NO query + 1 accessible net  → fallback to that net (200)
+//   - utok caller + NO query + 2+ accessible net → 400, error=network_id_required_multi
+//   - utok caller + NO query + 0 accessible net  → 400, error=missing_network_id
+//
+// The multi-network case is the authz boundary — we refuse to guess
+// which network to list from (per 通信龙 spec "别 fallback 到错 network").
+//
+// Test pattern mirrors uploads-http.test.ts: bind the real Bun.serve
+// server on an ephemeral port with a temp DB, hit it with fetch().
+
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { register, login, createNetwork } from "./auth.js";
+import { db } from "./db.js";
+
+const SERVER_DB = mkdtempSync(join(tmpdir(), "anet-hs-fallback-db-")) + "/commhub.db";
+const PORT = 18000 + Math.floor(Math.random() * 1000);
+const BASE = `http://127.0.0.1:${PORT}`;
+
+// Three users:
+//   soloUser    — single accessible network (fallback should work)
+//   multiUser   — two accessible networks (fallback should refuse)
+//   orphanUser  — zero networks (fallback has nothing to derive)
+let soloToken = "", multiToken = "", orphanToken = "", adminToken = "";
+let soloNetworkId = "";
+let multiNetworkA = "", multiNetworkB = "";
+let soloDaemonAlias = "";
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB = SERVER_DB;
+  process.env.PORT = String(PORT);
+  process.env.HOST = "127.0.0.1";
+
+  const suffix = `${Date.now()}_${Math.floor(Math.random() * 1000)}`;
+  const password = "BootstrapPw123Aa!";
+
+  // Pre-register a first user so subsequent test users are NOT auto-admin.
+  // resolveRestNetworkScope's admin branch bypasses fallback (admin can
+  // legitimately query any network), which would make solo's no-query
+  // case a false-negative for our fix contract.
+  const seed = register(`seed_admin_${suffix}`, password, undefined, "seed");
+  if (!seed.ok || !seed.token) throw new Error("seed admin failed: " + JSON.stringify(seed));
+  // Save the admin token so path 7 can hit /api/host-supervisors as an
+  // admin directly (通信龙 review point 1: verify admin+no-query goes 400
+  // explicitly, not only implicitly via seed_admin's shadow presence).
+  adminToken = seed.token;
+
+  // Solo user — register() auto-creates a default network; nothing to add.
+  const solo = register(`solo_${suffix}`, password, undefined, "seed");
+  if (!solo.ok || !solo.token) throw new Error("solo register failed: " + JSON.stringify(solo));
+  soloToken = solo.token;
+  soloNetworkId = solo.network_id ?? "";
+  if (!soloNetworkId) throw new Error("solo default network missing");
+
+  // Multi user — register + create a second owned network.
+  const multi = register(`multi_${suffix}`, password, undefined, "seed");
+  if (!multi.ok || !multi.token) throw new Error("multi register failed: " + JSON.stringify(multi));
+  multiToken = multi.token;
+  multiNetworkA = multi.network_id ?? "";
+  if (!multiNetworkA) throw new Error("multi default network missing");
+  const authCtx = login(`multi_${suffix}`, password);
+  const secondNet: any = createNetwork(authCtx.user!.user_id, `multi_second_${suffix}`);
+  if (!secondNet.ok || !secondNet.network_id) throw new Error("multi second-net create failed: " + JSON.stringify(secondNet));
+  multiNetworkB = secondNet.network_id;
+
+  // Orphan user — register then delete membership in the default net so
+  // the user has zero networks. Direct DB manipulation is fine here;
+  // we're modeling an edge case the production API would never let a
+  // normal user hit (they'd always keep at least their default), but
+  // the endpoint contract still needs to be locked.
+  const orphan = register(`orphan_${suffix}`, password, undefined, "seed");
+  if (!orphan.ok || !orphan.token) throw new Error("orphan register failed: " + JSON.stringify(orphan));
+  orphanToken = orphan.token;
+  const orphanUserId = login(`orphan_${suffix}`, password).user!.user_id;
+  db.run("DELETE FROM network_members WHERE user_id = ?1", [orphanUserId]);
+
+  // 通信龙 review point 2: path-2's fallback response must land the
+  // daemon list *from soloNetworkId specifically*, not from the whole
+  // sessions/nodes table. The original test-2 asserted daemons was an
+  // array but a clean fixture (0 daemons in the DB) would trivially
+  // satisfy that. Insert:
+  //   (a) a host_supervisor daemon in soloNetworkId — should show up in
+  //       fallback response
+  //   (b) a host_supervisor daemon in multiNetworkA — should NOT show
+  //       up in solo's fallback (cross-tenant isolation lock)
+  soloDaemonAlias = `solo_daemon_${suffix}`;
+  seedHostSupervisorDaemon({
+    alias: soloDaemonAlias,
+    networkId: soloNetworkId,
+    userIdForToken: login(`solo_${suffix}`, password).user!.user_id,
+  });
+  seedHostSupervisorDaemon({
+    alias: `other_daemon_${suffix}`,
+    networkId: multiNetworkA,
+    userIdForToken: login(`multi_${suffix}`, password).user!.user_id,
+  });
+
+  // Import triggers Bun.serve at module load — this IS the server start.
+  await import("./index.js");
+  await new Promise((r) => setTimeout(r, 100));
+});
+
+// Insert a minimal `nodes` row + `api_tokens` row so the daemon shows up
+// in /api/host-supervisors' JOIN-then-role-filter query (index.ts
+// GET /api/host-supervisors handler, at the SELECT ... FROM nodes n ...
+// EXISTS (SELECT 1 FROM api_tokens ...) branch). The api_tokens row
+// with name='node:<alias>' + revoked_at IS NULL is the "still active"
+// witness — without it EXISTS drops the row.
+function seedHostSupervisorDaemon(opts: {
+  alias: string;
+  networkId: string;
+  userIdForToken: string;
+}) {
+  const nodeId = `n_test_${opts.alias}`;
+  db.run(
+    `INSERT OR REPLACE INTO nodes (
+       node_id, node_name, alias, runtime, model, config_path,
+       channels, server, hostname, network_id,
+       config_revision, config_snapshot
+     ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12)`,
+    [nodeId, opts.alias, opts.alias, "claude-agent-sdk", "claude-sonnet-4-5",
+     "/tmp/cfg.json", "[]", "test-host", "test-host", opts.networkId,
+     0, JSON.stringify({ role: "host_supervisor", daemon_capabilities: {} })],
+  );
+  db.run(
+    `INSERT OR REPLACE INTO api_tokens (
+       token_id, token_hash, user_id, network_id, name, scope
+     ) VALUES (?1, ?2, ?3, ?4, ?5, ?6)`,
+    [`tok_test_${opts.alias}`, `hash_test_${opts.alias}`,
+     opts.userIdForToken, opts.networkId, `node:${opts.alias}`, "network"],
+  );
+}
+
+afterAll(() => {
+  try { rmSync(SERVER_DB, { recursive: true, force: true }); } catch {}
+});
+
+async function get(path: string, token: string): Promise<{ status: number; body: any }> {
+  const res = await fetch(`${BASE}${path}`, {
+    headers: { "Authorization": `Bearer ${token}` },
+  });
+  const body = await res.json().catch(() => null);
+  return { status: res.status, body };
+}
+
+describe("#380 — /api/host-supervisors utok→default-network fallback", () => {
+  test("path 1 — utok with 1 network, WITH ?network_id → 200 (existing behavior)", async () => {
+    const r = await get(`/api/host-supervisors?network_id=${soloNetworkId}`, soloToken);
+    expect(r.status).toBe(200);
+    expect(r.body?.ok).toBe(true);
+    expect(Array.isArray(r.body?.daemons)).toBe(true);
+    expect(typeof r.body?.count).toBe("number");
+  });
+
+  test("path 2 — utok with 1 network, NO ?network_id → 200 (fallback lands AND scopes correctly)", async () => {
+    // This is the core #380 fix: dashboard forgot the query but the user
+    // only has one network anyway, so we can safely fall back to it.
+    //
+    // 通信龙 review point 2: harden the assertion beyond "daemons is an
+    // array". We seeded one daemon in soloNetworkId and one in
+    // multiNetworkA (multi user); the fallback response MUST include the
+    // solo one and NOT the multi one. Otherwise a future regression that
+    // wired the fallback to "all networks the user knows about" would
+    // slip through — cross-tenant leak.
+    const r = await get(`/api/host-supervisors`, soloToken);
+    expect(r.status).toBe(200);
+    expect(r.body?.ok).toBe(true);
+    expect(Array.isArray(r.body?.daemons)).toBe(true);
+
+    const aliases: string[] = r.body.daemons.map((d: any) => d.alias);
+    expect(aliases).toContain(soloDaemonAlias);
+    // Belt: nothing from the multi user's network snuck through.
+    expect(aliases.every((a: string) => !a.startsWith("other_daemon_"))).toBe(true);
+    // Every returned daemon's daemon_node_id should be one this user can
+    // legitimately see — locking the shape end-to-end.
+    for (const d of r.body.daemons) {
+      expect(typeof d.daemon_node_id).toBe("string");
+      expect(typeof d.alias).toBe("string");
+    }
+  });
+
+  test("path 3 — utok with 2 networks, NO ?network_id → 400 network_id_required_multi", async () => {
+    // Authz boundary: refuse to guess which network to list. Distinguishing
+    // error field lets the client tell the user "pick a network" vs
+    // "you're not in any networks".
+    const r = await get(`/api/host-supervisors`, multiToken);
+    expect(r.status).toBe(400);
+    expect(r.body?.ok).toBe(false);
+    expect(r.body?.error).toBe("network_id_required_multi");
+    expect(r.body?.memberships).toBe(2);
+  });
+
+  test("path 4 — utok with 2 networks, WITH ?network_id → 200 (explicit choice honored)", async () => {
+    const r = await get(`/api/host-supervisors?network_id=${multiNetworkA}`, multiToken);
+    expect(r.status).toBe(200);
+    expect(r.body?.ok).toBe(true);
+    const r2 = await get(`/api/host-supervisors?network_id=${multiNetworkB}`, multiToken);
+    expect(r2.status).toBe(200);
+    expect(r2.body?.ok).toBe(true);
+  });
+
+  test("path 5 — utok with 2 networks, WITH ?network_id (not a member) → denied by scope layer", async () => {
+    // Requesting a network the user isn't in must never leak — this is
+    // enforced upstream at resolveRestNetworkScope, but re-lock here.
+    const foreignNet = "net_absolutely_not_a_member";
+    const r = await get(`/api/host-supervisors?network_id=${foreignNet}`, multiToken);
+    expect(r.status).toBe(403);
+  });
+
+  test("path 7 — admin utok, NO ?network_id → 400 (admin can span every network; no cross-network guessing)", async () => {
+    // 通信龙 review point 1: the previous suite only asserted admin
+    // indirectly (seed_admin was created first so other test users
+    // weren't auto-admin). This test hits /api/host-supervisors with
+    // seed_admin's own utok — resolveRestNetworkScope's isAdmin branch
+    // returns networkIds:null, singleNetworkId returns null, endpoint
+    // 400s. The response distinguishes it from the multi-network case
+    // via `memberships` being absent-or-0 (admin doesn't populate
+    // scope.networkIds), so the client sees an explicit "you're admin,
+    // pass network_id" affordance.
+    const r = await get(`/api/host-supervisors`, adminToken);
+    expect(r.status).toBe(400);
+    expect(r.body?.ok).toBe(false);
+    // Not the multi-network error — admin path goes through the "no
+    // scope.networkIds" branch → memberships defaults to 0 (the ??
+    // coalesce in the handler). This asymmetry lets the client
+    // distinguish "you own too many" from "you can see all of them".
+    expect(r.body?.error).toBe("missing_network_id");
+  });
+
+  test("path 8 — admin utok, WITH explicit ?network_id → 200 (admin can inspect any network)", async () => {
+    // Complement to path 7: even without membership in a target network,
+    // admin can query it. Locks resolveRestNetworkScope's isAdmin =>
+    // {networkId: requested, networkIds: null} branch.
+    const r = await get(`/api/host-supervisors?network_id=${multiNetworkA}`, adminToken);
+    expect(r.status).toBe(200);
+    expect(r.body?.ok).toBe(true);
+    // The daemon we seeded in multiNetworkA must be reachable.
+    const aliases: string[] = r.body.daemons.map((d: any) => d.alias);
+    expect(aliases.some(a => a.startsWith("other_daemon_"))).toBe(true);
+  });
+
+  test("path 6 — utok with 0 networks, NO ?network_id → 400 missing_network_id (memberships=0)", async () => {
+    const r = await get(`/api/host-supervisors`, orphanToken);
+    expect(r.status).toBe(400);
+    expect(r.body?.ok).toBe(false);
+    expect(r.body?.error).toBe("missing_network_id");
+    expect(r.body?.memberships).toBe(0);
+  });
+});