@sleep2agi/commhub-server 0.9.0-preview.13 → 0.9.0-preview.131

package/src/alias-filter.ts

@@ -0,0 +1,42 @@
+// Parse the `filter_alias` argument of `get_all_status` into an exact-match
+// IN list.
+//
+// Why this exists at all: on a 222-session hub the unfiltered response is about
+// 259 KB — past what an MCP client accepts in one result. A caller who wanted
+// the status of three specific nodes could not get it from the tool, and had to
+// go around it to the REST API. The filter is the fix; this module is the part
+// of it worth pinning, because the interesting behaviour is what happens to the
+// inputs that are not a clean alias.
+//
+// Blank entries are DROPPED rather than matched. A trailing comma would
+// otherwise produce `alias = ''`, which matches no row — and "no rows" reads
+// exactly like "those nodes do not exist". The failure and the true answer
+// would be indistinguishable to the caller, which is the thing to avoid.
+
+export interface AliasFilter {
+  /** Exact aliases to match. Empty means "no alias filtering". */
+  aliases: string[];
+  /** SQL fragment to append, or "" when there is nothing to filter on. */
+  sql: string;
+}
+
+export function parseAliasFilter(raw: string | undefined | null): AliasFilter {
+  const aliases = (raw ?? "")
+    .split(",")
+    .map(a => a.trim())
+    .filter(Boolean);
+  return {
+    aliases,
+    sql: aliases.length > 0 ? ` AND alias IN (${aliases.map(() => "?").join(",")})` : "",
+  };
+}
+
+/**
+ * The same `alias IN (…)` clause with numbered placeholders, starting after `paramsSoFar` already-bound
+ * parameters. Use it when the query already carries numbered `?N` placeholders: the PG adapter numbers a bare
+ * `?` from $1 again, so mixing the two binds the aliases to the wrong slots (SQLite happens to number them right).
+ */
+export function numberedAliasInClause(aliases: string[], paramsSoFar: number): string {
+  if (aliases.length === 0) return "";
+  return ` AND alias IN (${aliases.map((_, i) => `?${paramsSoFar + i + 1}`).join(",")})`;
+}

package/src/api-host-supervisors-can-create-nodes.test.ts

@@ -0,0 +1,350 @@
+// #1353 Fix ② — /api/host-supervisors surfaces daemon's self-reported
+// can_create_nodes + create_nodes_blocked_reason so dashboard's
+// "选服务器" picker can filter or dim broken daemons.
+//
+// Fix ① (PR #1510) added the hub-side dispatch gate — daemon that
+// reports can_create_nodes=false gets refused with the reason. But
+// the dashboard picker still LISTS the daemon and the user finds out
+// only after clicking. This exposes the fact one layer earlier so the
+// picker never surfaces the daemon in the first place.
+//
+// 🔴 Pre-#1371 compat is the same shape as Fix ①: only include the
+// two keys when the daemon actually reported them. Old daemons (that
+// never report) get the same undefined-passthrough dashboard sees a
+// row WITHOUT the keys, not a row with can_create_nodes:false, so
+// the dashboard's own default UI doesn't silently dim every legacy
+// daemon.
+
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import "./require-explicit-test-db.js";
+import { register, login } from "./auth.js";
+import { db } from "./db.js";
+
+let BASE = "";
+let server: any = null;
+
+let userToken = "";
+let userNetworkId = "";
+let userId = "";
+
+beforeAll(async () => {
+  process.env.HOST = "127.0.0.1";
+  const suffix = `${Date.now()}_${Math.floor(Math.random() * 1000)}`;
+  const password = "BootstrapPw123Aa!";
+
+  // Seed admin so subsequent registrations aren't auto-admin (admin
+  // path skips resolveRestNetworkScope's default-network fallback —
+  // that would change our fixture's role/scope in ways unrelated to
+  // this fix).
+  const seed = register(`hsc_seed_${suffix}`, password, undefined, "seed");
+  if (!seed.ok) throw new Error("seed failed");
+  db.run("UPDATE users SET role = 'admin' WHERE username = ?1", [`hsc_seed_${suffix}`]);
+
+  const u = register(`hsc_u_${suffix}`, password, undefined, "seed");
+  if (!u.ok || !u.token) throw new Error("user register failed");
+  userToken = u.token;
+  userNetworkId = u.network_id ?? "";
+  userId = login(`hsc_u_${suffix}`, password).user!.user_id;
+
+  const { bootServer } = await import("./server.js");
+  server = bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${server.port}`;
+  await new Promise((r) => setTimeout(r, 100));
+});
+
+afterAll(() => {
+  try { server?.stop?.(true); } catch {}
+});
+
+function seedDaemon(alias: string, snapshotOverride: object | null): void {
+  const nodeId = `hsc_n_${alias}`;
+  const snap = snapshotOverride === null
+    ? null
+    : JSON.stringify(snapshotOverride);
+  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, alias, alias, "claude-agent-sdk", "claude-sonnet-4-5",
+     "/tmp/cfg.json", "[]", "test-host", "test-host", userNetworkId,
+     0, snap],
+  );
+  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)`,
+    [`hsc_t_${alias}`, `hash_${alias}`, userId, userNetworkId, `node:${alias}`, "network"],
+  );
+}
+
+function clearDaemons(): void {
+  db.run("DELETE FROM nodes WHERE network_id = ?1", [userNetworkId]);
+  db.run("DELETE FROM api_tokens WHERE network_id = ?1 AND name LIKE 'node:%'", [userNetworkId]);
+}
+
+async function listDaemons(): Promise<any[]> {
+  const res = await fetch(`${BASE}/api/host-supervisors`, {
+    headers: { "Authorization": `Bearer ${userToken}` },
+  });
+  const body = await res.json();
+  if (!body.ok) throw new Error("list failed: " + JSON.stringify(body));
+  return body.daemons;
+}
+
+function findDaemon(rows: any[], alias: string): any {
+  const d = rows.find(r => r.alias === alias);
+  if (!d) throw new Error(`daemon ${alias} not in response`);
+  return d;
+}
+
+describe("#1353 Fix ② — /api/host-supervisors surfaces can_create_nodes + blocked_reason", () => {
+  test("🔴 witnessed-red: blocked daemon → response carries can_create_nodes:false + blocked_reason", async () => {
+    clearDaemons();
+    seedDaemon("blocked-a", {
+      role: "host_supervisor",
+      daemon_capabilities: {
+        runtimes_supported: ["claude-agent-sdk"],
+        can_create_nodes: false,
+        create_nodes_blocked_reason: "anet_bin_permission",
+      },
+    });
+    const d = findDaemon(await listDaemons(), "blocked-a");
+    expect(d.can_create_nodes).toBe(false);
+    expect(d.create_nodes_blocked_reason).toBe("anet_bin_permission");
+  });
+
+  test("healthy daemon (can_create_nodes:true) → can_create_nodes:true, NO blocked_reason", async () => {
+    clearDaemons();
+    seedDaemon("healthy-a", {
+      role: "host_supervisor",
+      daemon_capabilities: {
+        runtimes_supported: ["claude-agent-sdk"],
+        can_create_nodes: true,
+      },
+    });
+    const d = findDaemon(await listDaemons(), "healthy-a");
+    expect(d.can_create_nodes).toBe(true);
+    // 🔴 defensive: dashboard's picker likely renders blocked_reason
+    // when present regardless of can_create_nodes value. Don't
+    // confuse it by shipping a stale reason on a healthy daemon.
+    expect(d.create_nodes_blocked_reason).toBeUndefined();
+  });
+
+  test("healthy daemon that ALSO reports stale blocked_reason → reason NOT emitted (defensive)", async () => {
+    // Belt-and-braces: even if a future daemon shape bug leaves a
+    // stale reason string in the snapshot after recovering, the REST
+    // response should not surface it when the daemon is currently OK.
+    clearDaemons();
+    seedDaemon("healthy-b", {
+      role: "host_supervisor",
+      daemon_capabilities: {
+        runtimes_supported: ["claude-agent-sdk"],
+        can_create_nodes: true,
+        create_nodes_blocked_reason: "anet_bin_permission",  // stale
+      },
+    });
+    const d = findDaemon(await listDaemons(), "healthy-b");
+    expect(d.can_create_nodes).toBe(true);
+    expect(d.create_nodes_blocked_reason).toBeUndefined();
+  });
+
+  test("🔴 pre-#1371 compat: daemon that never reports can_create_nodes → BOTH keys absent from response", async () => {
+    // Same "known-blocked, NOT unknown-treated-as-blocked" rule as
+    // Fix ①. A pre-#1371 daemon (preview.10 through ~preview.55) never
+    // reports these fields. The response for it must not fabricate a
+    // false value — the dashboard could reasonably render an
+    // explicit `false` as "dim / hide" which would silently start
+    // hiding every daemon that hasn't upgraded.
+    clearDaemons();
+    seedDaemon("legacy-a", {
+      role: "host_supervisor",
+      daemon_capabilities: {
+        runtimes_supported: ["claude-agent-sdk"],
+        // no can_create_nodes / create_nodes_blocked_reason
+      },
+    });
+    const d = findDaemon(await listDaemons(), "legacy-a");
+    expect("can_create_nodes" in d).toBe(false);
+    expect("create_nodes_blocked_reason" in d).toBe(false);
+  });
+
+  test("pre-#1371 compat: daemon with no daemon_capabilities at all → BOTH keys absent", async () => {
+    clearDaemons();
+    seedDaemon("legacy-b", { role: "host_supervisor" });
+    const d = findDaemon(await listDaemons(), "legacy-b");
+    expect("can_create_nodes" in d).toBe(false);
+    expect("create_nodes_blocked_reason" in d).toBe(false);
+  });
+
+  test("pre-#1371 compat: NULL config_snapshot (very old daemon) → BOTH keys absent, daemon does NOT crash the listing", async () => {
+    // A daemon that never called report_status leaves config_snapshot NULL.
+    // /api/host-supervisors filters by role from the snapshot, so a NULL
+    // snapshot drops from the list entirely — but if it did surface (via
+    // any future path), it must not crash the reducer.
+    clearDaemons();
+    seedDaemon("legacy-c", { role: "host_supervisor" });  // seed with something to be listable
+    const rows = await listDaemons();
+    // Just prove the list doesn't throw and the daemon is present with
+    // no capability keys.
+    const d = findDaemon(rows, "legacy-c");
+    expect("can_create_nodes" in d).toBe(false);
+  });
+
+  test("all 4 categorized reason codes round-trip through the REST response", async () => {
+    const codes = ["anet_bin_identity", "anet_bin_source", "anet_bin_shape", "anet_bin_permission"];
+    for (const code of codes) {
+      clearDaemons();
+      seedDaemon(`blocked-${code}`, {
+        role: "host_supervisor",
+        daemon_capabilities: {
+          runtimes_supported: ["claude-agent-sdk"],
+          can_create_nodes: false,
+          create_nodes_blocked_reason: code,
+        },
+      });
+      const d = findDaemon(await listDaemons(), `blocked-${code}`);
+      expect(d.can_create_nodes).toBe(false);
+      expect(d.create_nodes_blocked_reason).toBe(code);
+    }
+  });
+
+  test(".40-shape 'anet_bin_pin_unresolved' pre-#1377 code also passes through the REST response", async () => {
+    // The Zod enum still accepts this coarse pre-#1377 code (agent-node
+    // @2.5.0-preview.40 daemons in the wild emit it), and Fix ① surfaces
+    // it verbatim to callers; the REST surface must too, otherwise
+    // dashboard sees the daemon as "blocked with no reason".
+    clearDaemons();
+    seedDaemon("blocked-40shape", {
+      role: "host_supervisor",
+      daemon_capabilities: {
+        runtimes_supported: ["claude-agent-sdk"],
+        can_create_nodes: false,
+        create_nodes_blocked_reason: "anet_bin_pin_unresolved",
+      },
+    });
+    const d = findDaemon(await listDaemons(), "blocked-40shape");
+    expect(d.create_nodes_blocked_reason).toBe("anet_bin_pin_unresolved");
+  });
+
+  test("malformed config_snapshot: existing behavior (daemon drops from list due to role-filter) unchanged", async () => {
+    // The parse is wrapped in try/catch (existing behavior). A malformed
+    // snapshot means snapRole stays null → filter drops it. This just
+    // pins that our added parsing doesn't turn a malformed snapshot
+    // into a crash.
+    clearDaemons();
+    // Seed a legit daemon so the list has SOMETHING to prove no crash.
+    seedDaemon("healthy-c", {
+      role: "host_supervisor",
+      daemon_capabilities: { runtimes_supported: [] },
+    });
+    // Seed the malformed one — should be filtered out silently.
+    const nodeId = "hsc_n_malformed";
+    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, "malformed", "malformed", "claude-agent-sdk", "claude-sonnet-4-5",
+       "/tmp/cfg.json", "[]", "test-host", "test-host", userNetworkId,
+       0, "{not json"],
+    );
+    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)`,
+      ["hsc_t_malformed", "hash_malformed", userId, userNetworkId, "node:malformed", "network"],
+    );
+    const rows = await listDaemons();
+    // healthy-c is present; malformed is filtered out because
+    // snapRole stayed null.
+    expect(rows.find((r: any) => r.alias === "healthy-c")).toBeDefined();
+    expect(rows.find((r: any) => r.alias === "malformed")).toBeUndefined();
+  });
+});
+
+/* #1545 —— `can_create_nodes` 说的是「能不能」,这一组说的是「**那是什么时候测的**」。
+ *
+ * 为什么非要分开:agent-node ≤ 2.5.0-preview.54 用一个进程级缓存只算一次
+ * (`cli.ts` 的 `_createCapCache`)。开机时二进制好、之后被 chmod 掉 ⇒ 它会
+ * **永远上报 ready**。hub 这边,那条记录和一个 3 秒前刚测出来的 ready
+ * 在 `last_seen_at` 上一模一样 —— 心跳是新的,那一格不是。
+ *
+ * 🔴 缺席**不得**当成 0。把「没报」渲染成「刚测的」,正好朝「没问题」方向说谎,
+ *    而这正是 #1545 里比沉默更糟的那一半。
+ */
+describe("#1545 /api/host-supervisors —— can_create_nodes 的年龄", () => {
+  test("daemon 报了年龄 → 原样带出", async () => {
+    clearDaemons();
+    seedDaemon("age-fresh", {
+      role: "host_supervisor",
+      daemon_capabilities: {
+        can_create_nodes: false,
+        create_nodes_blocked_reason: "anet_bin_source",
+        create_capability_observed_ms_ago: 12,
+      },
+    });
+    const d = findDaemon(await listDaemons(), "age-fresh");
+    expect(d.create_capability_observed_ms_ago).toBe(12);
+  });
+
+  test("🔴 daemon 没报年龄 → 这一格必须**缺席**,不能是 0/null", async () => {
+    clearDaemons();
+    seedDaemon("age-absent", {
+      role: "host_supervisor",
+      daemon_capabilities: { can_create_nodes: true },
+    });
+    const d = findDaemon(await listDaemons(), "age-absent");
+    // 能力本身照常带出 —— 加年龄这一格不许把旧 daemon 的既有信息弄丢。
+    expect(d.can_create_nodes).toBe(true);
+    expect("create_capability_observed_ms_ago" in d).toBe(false);
+  });
+
+  /* 🔴 消毒**不是 clamp**:clamp 会把一个坏值变成一个看起来正常的年龄,
+   * 而这一格存在的全部意义就是让人分辨新鲜和陈旧。坏值一律当作「没报」。 */
+  test.each([
+    ["负数", -1],
+    ["超过一年", 400 * 24 * 60 * 60 * 1000],
+    ["null(schema 的 .catch 兜底值)", null],
+    ["字符串(直接写库,绕过 schema)", "12"],
+  ])("坏值当作没报,而不是 clamp 成边界:%s", async (label, value) => {
+    clearDaemons();
+    const alias = `age-bad-${String(label).slice(0, 4)}`;
+    seedDaemon(alias, {
+      role: "host_supervisor",
+      daemon_capabilities: {
+        can_create_nodes: true,
+        create_capability_observed_ms_ago: value,
+      },
+    });
+    const d = findDaemon(await listDaemons(), alias);
+    expect(d.can_create_nodes).toBe(true);           // 能力仍在
+    expect("create_capability_observed_ms_ago" in d).toBe(false);  // 年龄不在
+  });
+
+  /* 边界校准:上面用 400 天证明「太旧被丢」,这里用**刚好一年**证明门不是恒丢。
+   * 只验被丢那一侧的话,一个恒丢的实现能全绿通过。 */
+  test("边界:恰好一年被接受 ⇒ 上面那条不是因为恒丢才绿", async () => {
+    clearDaemons();
+    const oneYear = 365 * 24 * 60 * 60 * 1000;
+    seedDaemon("age-boundary", {
+      role: "host_supervisor",
+      daemon_capabilities: { can_create_nodes: true, create_capability_observed_ms_ago: oneYear },
+    });
+    const d = findDaemon(await listDaemons(), "age-boundary");
+    expect(d.create_capability_observed_ms_ago).toBe(oneYear);
+  });
+
+  test("年龄只在 can_create_nodes 存在时出现(旧 daemon 两格都没有)", async () => {
+    clearDaemons();
+    seedDaemon("age-legacy", {
+      role: "host_supervisor",
+      daemon_capabilities: { runtimes_supported: ["claude-agent-sdk"] },
+    });
+    const d = findDaemon(await listDaemons(), "age-legacy");
+    expect("can_create_nodes" in d).toBe(false);
+    expect("create_capability_observed_ms_ago" in d).toBe(false);
+  });
+});

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

@@ -0,0 +1,271 @@
+// #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 "./require-explicit-test-db.js";
+import { register, login, createNetwork } from "./auth.js";
+import { db } from "./db.js";
+
+// #438 corrective: private bootServer({ port: 0 }) instance (see
+// uploads-http.test.ts for rationale).
+let BASE = "";
+let server: any = null;
+
+// 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 = "";
+
+// 30s 而不是 bun 默认的 5s:这个 hook 跑 register()(KDF)+bootServer(),
+// 本机空载基线 ~620ms,而 2026-08-17 与 2026-08-31 两次 CI 上它被 5s 上限打死
+// (0 pass / 1 fail / Ran 1 test —— 见 #928、#1627)。5247ms 是**被截断的下界**,
+// 不是测量值,所以余量按基线的 ~48x 取,而不是按那个数取。
+beforeAll(async () => {
+  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));
+  // "First registered user is auto-admin" only holds when this suite has
+  // the DB to itself. In an aggregate run another suite registers first,
+  // the seed lands as a plain user, and paths 7/8 silently test the
+  // wrong role. Promote explicitly — resolveToken reads users.role at
+  // request time, so promotion after token issuance is effective.
+  db.run("UPDATE users SET role = 'admin' WHERE username = ?1", [`seed_admin_${suffix}`]);
+  // 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,
+  });
+
+  // server.ts is side-effect-free to import; boot a private instance.
+  const { bootServer } = await import("./server.js");
+  server = bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${server.port}`;
+  await new Promise((r) => setTimeout(r, 100));
+}, 30_000);
+
+// 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 { server?.stop?.(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);
+  });
+});