@sleep2agi/commhub-server 0.9.0-preview.42 → 0.9.0-preview.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.42",
+  "version": "0.9.0-preview.43",
   "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and MCP tools (17 collaboration-core + node/provider ops tools; authoritative list: docs-site/docs/api/mcp-tools.md).",
   "type": "module",
   "main": "src/index.ts",

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

@@ -0,0 +1,266 @@
+// #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();
+  });
+});

package/src/create-node-blocked-gate.test.ts

@@ -0,0 +1,231 @@
+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";
+
+// #1353 Fix ① — hub gates create_node dispatch on the daemon's
+// self-reported can_create_nodes bit. Before this, daemon reported
+// can_create_nodes=false (via #1371 + #1377) → hub stored it → nothing
+// read it → dispatch returned {ok:true, request_id} and pushed a
+// doorbell to a daemon that had already told hub it couldn't create
+// nodes. That's the exact "在线但静默失败" case the issue title reports.
+//
+// Vincent 2026-08-28 comment on #1353:
+//   "daemon 侧确知不可用时,hub 应当**拒绝派发**并返回可操作的错误,
+//    而不是发一个注定失败的 doorbell"
+//
+// 🔴 Pre-#1371 daemons (preview.55 and earlier) don't report the field
+// at all. That must NOT fail-closed — the guard is "known-blocked",
+// not "unknown-treated-as-blocked". Tested explicitly below.
+
+const NET = "net_1353_gate";
+const USER_ID = "u_1353_admin";
+const DAEMON_ID = "node_1353_daemon";
+const DAEMON_ALIAS = "gate-daemon";
+const DAEMON_TOK = "tok_1353_daemon";
+
+interface ToolHandler { (args: any, extra?: any): Promise<{ content: Array<{ type: "text"; text: string }> }>; }
+interface Reply { ok?: boolean; error?: string; blocked_reason?: string; request_id?: string; [k: string]: unknown; }
+
+function cleanup() {
+  try { db.run("DELETE FROM node_create_requests WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM audit_log 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", [USER_ID]); } catch {}
+}
+beforeEach(cleanup);
+afterAll(cleanup);
+
+function seed(snapshot: object | string | null) {
+  db.run(
+    `INSERT INTO users (user_id, username, password_hash, role, created_at)
+     VALUES (?1, ?2, 'x', 'user', datetime('now'))`,
+    [USER_ID, USER_ID],
+  );
+  db.run(
+    `INSERT OR REPLACE INTO networks (network_id, network_name, owner_id, created_at)
+     VALUES (?1, ?1, ?2, datetime('now'))`,
+    [NET, USER_ID],
+  );
+  db.run(
+    `INSERT INTO network_members (user_id, network_id, role, joined_at)
+     VALUES (?1, ?2, 'admin', datetime('now'))`,
+    [USER_ID, NET],
+  );
+  const snap = snapshot === null
+    ? null
+    : (typeof snapshot === "string" ? snapshot : JSON.stringify(snapshot));
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, config_snapshot, hostname, created_at, updated_at, lifecycle_state)
+     VALUES (?1, ?2, ?3, ?4, ?5, ?6, datetime('now'), datetime('now'), 'active')`,
+    [DAEMON_ID, DAEMON_ALIAS, DAEMON_ALIAS, NET, snap, `host-${DAEMON_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_TOK, USER_ID, NET, `node:${DAEMON_ALIAS}`, `hash_${DAEMON_TOK}`],
+  );
+}
+
+function tools(): Record<string, ToolHandler> {
+  const server = new McpServer({ name: "test", version: "0" }) as any;
+  const out: Record<string, ToolHandler> = {};
+  const origTool = server.tool.bind(server);
+  server.tool = (name: string, _desc: string, _schema: any, handler: ToolHandler) => {
+    out[name] = handler;
+    return origTool(name, _desc, _schema, handler);
+  };
+  const origRegisterTool = server.registerTool?.bind(server);
+  if (origRegisterTool) {
+    server.registerTool = (name: string, _cfg: any, handler: ToolHandler) => {
+      out[name] = handler;
+      return origRegisterTool(name, _cfg, handler);
+    };
+  }
+  registerTools(
+    server, undefined,
+    /* enforceNetworkId */ NET,
+    /* enforceUserId */ USER_ID,
+    /* callerAlias */ null,
+    /* callerTokenIsNetwork */ true,
+    /* callerTokenId */ null,
+  );
+  return out;
+}
+
+async function call(handler: ToolHandler, args: any): Promise<Reply> {
+  const r = await handler(args);
+  return JSON.parse(r.content[0].text) as Reply;
+}
+
+const spec = {
+  name: "child-1353",
+  runtime: "claude-agent-sdk",
+  model: "claude-sonnet-4-5",
+  flags: {},
+};
+
+describe("#1353 Fix ① — hub gates create_node on daemon-reported can_create_nodes", () => {
+  test("🔴 witnessed-red: blocked daemon (can_create_nodes=false + reason) → refuse with reason, NO dispatch", async () => {
+    seed({
+      role: "host_supervisor",
+      daemon_capabilities: {
+        runtimes_supported: ["claude-agent-sdk"],
+        can_create_nodes: false,
+        create_nodes_blocked_reason: "anet_bin_permission",
+      },
+    });
+    const t = tools();
+    const r = await call(t.create_node, { daemon_node_id: DAEMON_ID, node_spec: spec });
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe("daemon_cannot_create_nodes");
+    expect(r.blocked_reason).toBe("anet_bin_permission");
+    // No request row inserted — hub must refuse BEFORE dispatch.
+    const rows = db.get<{ n: number }>(
+      "SELECT COUNT(*) AS n FROM node_create_requests WHERE daemon_node_id = ?1",
+      DAEMON_ID,
+    );
+    expect(rows?.n).toBe(0);
+  });
+
+  test("blocked daemon with each of the 4 reason codes surfaces that specific code", async () => {
+    const codes = ["anet_bin_identity", "anet_bin_source", "anet_bin_shape", "anet_bin_permission"];
+    for (const code of codes) {
+      cleanup();
+      seed({
+        role: "host_supervisor",
+        daemon_capabilities: {
+          runtimes_supported: ["claude-agent-sdk"],
+          can_create_nodes: false,
+          create_nodes_blocked_reason: code,
+        },
+      });
+      const r = await call(tools().create_node, { daemon_node_id: DAEMON_ID, node_spec: spec });
+      expect(r.error).toBe("daemon_cannot_create_nodes");
+      expect(r.blocked_reason).toBe(code);
+    }
+  });
+
+  test("blocked with .40-shape 'anet_bin_pin_unresolved' reason surfaces that literal (backcompat)", async () => {
+    // The Zod enum in tools.ts still accepts this coarse pre-#1377 code
+    // because agent-node@2.5.0-preview.40 daemons in the wild still emit
+    // it. If we ever swallow it into "unknown", those daemons' user
+    // messages get worse than they already are.
+    seed({
+      role: "host_supervisor",
+      daemon_capabilities: {
+        runtimes_supported: ["claude-agent-sdk"],
+        can_create_nodes: false,
+        create_nodes_blocked_reason: "anet_bin_pin_unresolved",
+      },
+    });
+    const r = await call(tools().create_node, { daemon_node_id: DAEMON_ID, node_spec: spec });
+    expect(r.blocked_reason).toBe("anet_bin_pin_unresolved");
+  });
+
+  test("blocked with NO reason field → fallback 'anet_bin_unknown' (defensive)", async () => {
+    seed({
+      role: "host_supervisor",
+      daemon_capabilities: {
+        runtimes_supported: ["claude-agent-sdk"],
+        can_create_nodes: false,
+        // no create_nodes_blocked_reason
+      },
+    });
+    const r = await call(tools().create_node, { daemon_node_id: DAEMON_ID, node_spec: spec });
+    expect(r.error).toBe("daemon_cannot_create_nodes");
+    expect(r.blocked_reason).toBe("anet_bin_unknown");
+  });
+
+  test("can_create_nodes=true daemon dispatches normally (gate must not false-positive on healthy daemon)", async () => {
+    seed({
+      role: "host_supervisor",
+      daemon_capabilities: {
+        runtimes_supported: ["claude-agent-sdk"],
+        can_create_nodes: true,
+      },
+    });
+    const r = await call(tools().create_node, { daemon_node_id: DAEMON_ID, node_spec: spec });
+    // Doesn't matter whether downstream dispatch succeeds — the point
+    // is that THIS gate did not reject. If reject, r.error would be
+    // "daemon_cannot_create_nodes".
+    expect(r.error).not.toBe("daemon_cannot_create_nodes");
+  });
+
+  test("🔴 pre-#1371 compat: snapshot with NO can_create_nodes field passes through (must NOT fail-closed)", async () => {
+    // preview.10 through preview.55 daemons never report this field.
+    // If we fail-closed on undefined we silently break every in-flight
+    // daemon that hasn't upgraded. Guard is "known-blocked", not
+    // "unknown-treated-as-blocked".
+    seed({
+      role: "host_supervisor",
+      daemon_capabilities: {
+        runtimes_supported: ["claude-agent-sdk"],
+        // no can_create_nodes at all
+      },
+    });
+    const r = await call(tools().create_node, { daemon_node_id: DAEMON_ID, node_spec: spec });
+    expect(r.error).not.toBe("daemon_cannot_create_nodes");
+  });
+
+  test("pre-#1371 compat: snapshot with no daemon_capabilities at all → passes through", async () => {
+    seed({ role: "host_supervisor" });
+    const r = await call(tools().create_node, { daemon_node_id: DAEMON_ID, node_spec: spec });
+    expect(r.error).not.toBe("daemon_cannot_create_nodes");
+  });
+
+  test("pre-#1371 compat: NULL config_snapshot passes through (very old daemon shape)", async () => {
+    seed(null);
+    const r = await call(tools().create_node, { daemon_node_id: DAEMON_ID, node_spec: spec });
+    expect(r.error).not.toBe("daemon_cannot_create_nodes");
+  });
+
+  test("malformed config_snapshot: permissive fallthrough (mirrors runtimes_supported catch), no crash", async () => {
+    seed("{not json");
+    const r = await call(tools().create_node, { daemon_node_id: DAEMON_ID, node_spec: spec });
+    expect(r.error).not.toBe("daemon_cannot_create_nodes");
+  });
+});

package/src/db.ts

@@ -63,7 +63,7 @@ db.exec(`
   -- 部分索引 acked=0 若「近期」读含已 ack 行则用不上)。P1 只落表。
   CREATE TABLE IF NOT EXISTS user_inbox (
     message_id    TEXT PRIMARY KEY,
-    network_id    TEXT,
+    network_id    TEXT NOT NULL,
     user_id       TEXT NOT NULL,
     from_session  TEXT,
     kind          TEXT NOT NULL DEFAULT 'info',
@@ -681,6 +681,81 @@ function migrateNodeCreateRequestsModelNullable() {
   });
 }
 migrateNodeCreateRequestsModelNullable();
+
+// #1493 — 把 user_inbox.network_id 升到 **schema 级 NOT NULL**(belt-and-suspenders,
+// 叠在 send_desktop_message 的代码级三闸之上:canWrite / `!effectiveNetId` return /
+// getUserNetworkRole,tools.ts)。「不产生 network_id=NULL 孤儿」现是代码级保证 + #1492
+// 三道测试;schema 级约束让**任何**未来绕过那三闸写 NULL 的回归在 INSERT 处直接被
+// 数据库拒(而非产出 scoped-unreadable 的静默孤儿)。
+//
+// SQLite 不能 `ALTER COLUMN ADD NOT NULL` → 建新表→copy→drop→rename(与本文件既有
+// recreate-table 迁移同范式);新库的 CREATE 已直接 NOT NULL,迁移检测到就跳过(幂等)。
+function migrateUserInboxNetworkIdNotNull() {
+  if (db.dialect === "postgres") {
+    try { db.exec("ALTER TABLE user_inbox ALTER COLUMN network_id SET NOT NULL"); } catch {}
+    return;
+  }
+  let createSql: string | undefined;
+  try {
+    createSql = db.get<{ sql: string }>("SELECT sql FROM sqlite_master WHERE type = 'table' AND name = 'user_inbox'")?.sql;
+  } catch { return; }
+  if (!createSql) return;                                       // 表不存在:上面的 CREATE 已建成 NOT NULL 新表
+  if (/network_id\s+TEXT\s+NOT\s+NULL/i.test(createSql)) return; // 已是 NOT NULL → 幂等跳过
+
+  // 🔴 迁移前守卫:存量若有 network_id IS NULL 行(按代码级三闸理应 0)→ **大声 warn +
+  // 跳过迁移**(列暂保持可空),hub 照常启动。fail-safe,不 throw(SDK马 review #1516):
+  //   · 这条 NOT NULL 是 belt-and-suspenders,代码级三闸(#1492 三测钉着)已挡新 NULL;
+  //     为一条冗余保险带让**整个舰队的 hub** boot 期停摆,代价与收益不成比例;
+  //   · 生产这个 COUNT 没人量过,而 #1493 第一条原则就是"没量过的数不要动手"——只要生产
+  //     有一行历史 NULL,throw 就把升级变成停机;
+  //   · fail-closed 的真正目的(不盲目清空、不 COALESCE 猜网络)用 warn+skip 一样达到。
+  // ⚠ 校正:本文件既有迁移(migrateNodeCreateRequestsModelNullable 内部 catch{}+return;
+  //   migrateSessionsNetworkAliasUnique 全函数 throw 0 次)都**不**在 boot 期打死 hub——
+  //   "顶层无 try/catch"是真前提,但"所以 throw 符合惯例"是没验的推论(SDK马 量出),撤回。
+  // 孤儿行仍有明确运维信号,三闸仍生效;等人工量过、清干净,下次启动幂等判据自动完成迁移。
+  const nullCount = db.get<{ n: number }>("SELECT COUNT(*) AS n FROM user_inbox WHERE network_id IS NULL")?.n ?? 0;
+  if (nullCount > 0) {
+    console.error(
+      `[migrate #1493] user_inbox 有 ${nullCount} 行 network_id IS NULL —— 与 send_desktop_message ` +
+      `的代码级三闸矛盾,可能存在更早的写路径漏洞;已**跳过** NOT NULL 迁移(列暂保持可空),` +
+      `hub 正常启动。请人工排查这些孤儿行来源、清理后下次启动会自动完成迁移(不要盲目清空)。`,
+    );
+    return;
+  }
+
+  db.transaction(() => {
+    db.exec("DROP TABLE IF EXISTS user_inbox_migrated");
+    db.exec(`
+      CREATE TABLE user_inbox_migrated (
+        message_id    TEXT PRIMARY KEY,
+        network_id    TEXT NOT NULL,
+        user_id       TEXT NOT NULL,
+        from_session  TEXT,
+        kind          TEXT NOT NULL DEFAULT 'info',
+        title         TEXT,
+        content       TEXT NOT NULL,
+        severity      TEXT NOT NULL DEFAULT 'info',
+        meta_json     TEXT,
+        acked         INTEGER NOT NULL DEFAULT 0,
+        created_at    TEXT NOT NULL DEFAULT (datetime('now')),
+        acked_at      TEXT
+      )
+    `);
+    db.exec(`
+      INSERT INTO user_inbox_migrated
+        (message_id, network_id, user_id, from_session, kind, title, content, severity, meta_json, acked, created_at, acked_at)
+      SELECT
+        message_id, network_id, user_id, from_session, kind, title, content, severity, meta_json, acked, created_at, acked_at
+      FROM user_inbox
+    `);
+    db.exec("DROP TABLE user_inbox");
+    db.exec("ALTER TABLE user_inbox_migrated RENAME TO user_inbox");
+  });
+}
+migrateUserInboxNetworkIdNotNull();
+// 迁移会 drop 掉旧表上的 idx_user_inbox_user_acked → 重建(IF NOT EXISTS;未迁移时 no-op)。
+db.exec(`CREATE INDEX IF NOT EXISTS idx_user_inbox_user_acked ON user_inbox(user_id, acked, created_at);`);
+
 db.exec(`
   CREATE INDEX IF NOT EXISTS idx_ncr_daemon_status ON node_create_requests(daemon_node_id, status);
   CREATE INDEX IF NOT EXISTS idx_ncr_network ON node_create_requests(network_id);

package/src/server.ts

@@ -3135,16 +3135,41 @@ return Bun.serve({
       const daemons = sqlRows
         .map(r => {
           let snapRole: string | null = null;
+          // #1353 Fix ② — surface daemon self-reported create-node
+          // capability so dashboard's "选服务器" picker can filter or
+          // dim broken daemons instead of listing them as online.
+          // Fix ① (hub-side dispatch gate, PR #1510) refuses the
+          // request but the picker still lists the daemon and the user
+          // finds out only after clicking. Exposing the fact one layer
+          // earlier lets the picker never surface the daemon in the
+          // first place.
+          //
+          // 🔴 Pre-#1371 daemons don't report either field. Leave the
+          // response keys UNDEFINED in that case (not `false`, not
+          // `null`) — mirrors the Fix ① rule "known-blocked, NOT
+          // unknown-treated-as-blocked". Emitting a fabricated `false`
+          // would silently start dimming every daemon that hasn't
+          // upgraded past preview.55.
+          let snapCanCreate: boolean | undefined;
+          let snapBlockedReason: string | undefined;
           if (r.config_snapshot) {
             try {
               const parsed = typeof r.config_snapshot === "string" ? JSON.parse(r.config_snapshot) : r.config_snapshot;
               snapRole = typeof parsed?.role === "string" ? parsed.role : null;
+              const caps = parsed?.daemon_capabilities;
+              if (caps && typeof caps.can_create_nodes === "boolean") {
+                snapCanCreate = caps.can_create_nodes;
+              }
+              if (caps && typeof caps.create_nodes_blocked_reason === "string"
+                  && caps.create_nodes_blocked_reason.length > 0) {
+                snapBlockedReason = caps.create_nodes_blocked_reason;
+              }
             } catch { /* malformed */ }
           }
-          return { row: r, role: snapRole };
+          return { row: r, role: snapRole, canCreate: snapCanCreate, blockedReason: snapBlockedReason };
         })
         .filter(({ role }) => role === "host_supervisor")
-        .map(({ row: r }) => {
+        .map(({ row: r, canCreate, blockedReason }) => {
           let online = false;
           let lastSeenAt: string | null = null;
           if (r.session_last_seen) {
@@ -3174,7 +3199,7 @@ return Bun.serve({
             telemetry.mem_gb = r.session_mem_total_gb ?? null;
             telemetry.ip_internal = r.session_ip ?? null;
           }
-          return {
+          const out: Record<string, unknown> = {
             daemon_node_id: r.node_id,
             alias: r.alias,
             hostname: r.hostname,
@@ -3184,6 +3209,20 @@ return Bun.serve({
             allowed_secret_keys: secrets,
             host_telemetry: telemetry,
           };
+          // #1353 Fix ② — only emit the two capability keys when the
+          // daemon actually reported them. Undefined vs. false is a
+          // real distinction here (see Fix ② comment above).
+          if (typeof canCreate === "boolean") {
+            out.can_create_nodes = canCreate;
+            // Blocked reason only meaningful when blocked. Some legacy
+            // shapes could carry a reason without can_create_nodes=false
+            // (defensive fallback in Fix ①); mirror the same choice —
+            // don't confuse consumers with a reason on a healthy daemon.
+            if (canCreate === false && blockedReason) {
+              out.create_nodes_blocked_reason = blockedReason;
+            }
+          }
+          return out;
         });
       return withCors(req, Response.json({ ok: true, daemons, count: daemons.length }));
     }

package/src/tools.ts

@@ -3207,6 +3207,41 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "cross_network_node" }) }] };
       }
 
+      // #1353 Fix ① — daemon self-declared "I can't create nodes right now"
+      // is now a dispatch-time gate, not just a stored fact. Before this,
+      // daemon reported `daemon_capabilities.can_create_nodes=false` (via
+      // #1371 + #1377), hub stored it in config_snapshot, and then no
+      // consumer read it — dispatch still returned `{ok:true, request_id}`
+      // and pushed an SSE doorbell to the broken daemon. That's the exact
+      // "在线但静默失败" case the issue title reports.
+      //
+      // Vincent's own 2026-08-28 comment on #1353 authorizes this shape:
+      // "daemon 侧确知不可用时,hub 应当**拒绝派发**并返回可操作的错误,
+      //  而不是发一个注定失败的 doorbell".
+      //
+      // 🔴 Pre-#1371 compat: a daemon that has NOT reported
+      // `can_create_nodes` at all leaves the field UNDEFINED in the
+      // snapshot. Do NOT fail-closed on undefined — that would silently
+      // start rejecting every daemon on the old (preview.10 through .55
+      // roughly) shape. Only `=== false` gates; `=== true` and `undefined`
+      // both pass through (new-guard-matches-existing-stance).
+      try {
+        const snap = daemon.config_snapshot ? JSON.parse(daemon.config_snapshot) : null;
+        const caps = snap?.daemon_capabilities;
+        if (caps && caps.can_create_nodes === false) {
+          const reason: string = (typeof caps.create_nodes_blocked_reason === "string"
+            && caps.create_nodes_blocked_reason.length > 0)
+            ? caps.create_nodes_blocked_reason
+            : "anet_bin_unknown";
+          return { content: [{ type: "text" as const, text: JSON.stringify({
+            ok: false,
+            error: "daemon_cannot_create_nodes",
+            blocked_reason: reason,
+            daemon_node_id,
+          }) }] };
+        }
+      } catch { /* malformed snapshot: permissive, mirrors L3230 fallthrough */ }
+
       // Read daemon's host_supervisor capability + allowlist from its
       // last reported config_snapshot. PR3 (#338) canonical path is
       // `daemon_capabilities.runtimes_supported` (RFC-026 §9.3).

package/src/user-inbox-netid-notnull.test.ts

@@ -0,0 +1,122 @@
+// #1493 — user_inbox.network_id 升 schema 级 NOT NULL(belt-and-suspenders)。
+//
+// 「不产生 NULL 孤儿」原是代码级三闸(#1492 证不可达)。schema 级 NOT NULL 让**任何**
+// 未来绕过那三闸写 NULL 的回归在 INSERT 处被 DB 直接拒,而不是产出 scoped-unreadable
+// 的静默孤儿。生产 hub 已在 preview.41、user_inbox 有真实行 → 迁移必须:① 新库直接
+// NOT NULL;② 存量库无损重建(建新表→copy→drop→rename);③ 迁移前若发现 NULL 行(理应
+// 为 0)fail-closed 停下,不静默丢。
+//
+// 后两条要预置「旧 schema(nullable)」的库 → 用 bun:sqlite 手造库 + 子进程 import db.js
+// 触发迁移(与 boot-side-effect.test.ts 同款子进程范式)。
+
+import { describe, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { mkdtempSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { db } from "./db.js";
+
+const OLD_SCHEMA = `CREATE TABLE user_inbox (
+  message_id TEXT PRIMARY KEY, network_id TEXT, user_id TEXT NOT NULL, from_session TEXT,
+  kind TEXT NOT NULL DEFAULT 'info', title TEXT, content TEXT NOT NULL,
+  severity TEXT NOT NULL DEFAULT 'info', meta_json TEXT, acked INTEGER NOT NULL DEFAULT 0,
+  created_at TEXT NOT NULL DEFAULT (datetime('now')), acked_at TEXT)`;
+
+/** 预置一个「旧 schema(network_id 可空)」的库文件,可选带若干行。返回文件路径。 */
+function seedOldDb(rows: Array<{ mid: string; net: string | null; user: string }>): string {
+  const file = join(mkdtempSync(join(tmpdir(), "anet-1493-")), "hub.db");
+  const raw = new Database(file);
+  raw.exec(OLD_SCHEMA);
+  for (const r of rows) {
+    raw.run("INSERT INTO user_inbox (message_id, network_id, user_id, content) VALUES (?1, ?2, ?3, 'body')",
+      [r.mid, r.net, r.user]);
+  }
+  raw.close();
+  return file;
+}
+
+/** 子进程里 import db.js(触发迁移),回读一段结果。返回 {exitCode, stdout, stderr}。 */
+function bootWithDb(file: string, probe: string) {
+  const script = `
+    process.env.COMMHUB_DB = ${JSON.stringify(file)};
+    const { db } = await import("./src/db.js");
+    ${probe}
+    process.exit(0);
+  `;
+  const child = Bun.spawnSync({
+    cmd: ["bun", "-e", script],
+    cwd: `${import.meta.dir}/..`,
+    env: { ...process.env, COMMHUB_DB: file },
+    timeout: 20_000,
+  });
+  return {
+    exitCode: child.exitCode,
+    stdout: new TextDecoder().decode(child.stdout),
+    stderr: new TextDecoder().decode(child.stderr),
+  };
+}
+
+describe("#1493 user_inbox.network_id NOT NULL (belt-and-suspenders)", () => {
+  test("new DB: network_id is NOT NULL and rejects a NULL insert", () => {
+    const col = db.all<{ name: string; notnull: number }>("PRAGMA table_info(user_inbox)").find(c => c.name === "network_id");
+    expect(col?.notnull).toBe(1);
+    // 绕过代码闸直接写 NULL → DB 拒(这正是 belt-and-suspenders 的价值)
+    expect(() => db.run(
+      "INSERT INTO user_inbox (message_id, user_id, content) VALUES (?1, ?2, ?3)",
+      [`dm_nn_${Date.now()}`, "u_nn", "hi"],
+    )).toThrow(/NOT NULL/i);
+  });
+
+  test("migration: old nullable table with valid rows → rebuilt NOT NULL, rows preserved, index recreated", () => {
+    const file = seedOldDb([
+      { mid: "dm_1", net: "net_a", user: "u_1" },
+      { mid: "dm_2", net: "net_b", user: "u_2" },
+    ]);
+    const r = bootWithDb(file, `
+      const col = db.all("PRAGMA table_info(user_inbox)").find(c => c.name === "network_id");
+      const rows = db.get("SELECT COUNT(*) AS n FROM user_inbox").n;
+      const idx = db.get("SELECT COUNT(*) AS n FROM sqlite_master WHERE type='index' AND name='idx_user_inbox_user_acked'").n;
+      let nullRejected = false;
+      try { db.run("INSERT INTO user_inbox (message_id, user_id, content) VALUES ('dm_z','u_z','x')"); }
+      catch { nullRejected = true; }
+      console.log("RESULT:" + JSON.stringify({ notnull: col.notnull, rows, idx, nullRejected }));
+    `);
+    expect(r.exitCode).toBe(0);
+    const m = r.stdout.match(/RESULT:(\{.*\})/);
+    expect(m).not.toBeNull();
+    const out = JSON.parse(m![1]);
+    expect(out.notnull).toBe(1);      // 迁移后 NOT NULL
+    expect(out.rows).toBe(2);          // 两行无损保留
+    expect(out.idx).toBe(1);           // 索引重建
+    expect(out.nullRejected).toBe(true);
+  });
+
+  test("migration guard: old table with a network_id IS NULL row → fail-safe (warn + skip, hub boots, data intact)", () => {
+    const file = seedOldDb([
+      { mid: "dm_ok", net: "net_a", user: "u_1" },
+      { mid: "dm_orphan", net: null, user: "u_2" },   // 理应不可达;若真出现 → warn+跳过,不停机
+    ]);
+    const r = bootWithDb(file, `
+      const col = db.all("PRAGMA table_info(user_inbox)").find(c => c.name === "network_id");
+      const rows = db.get("SELECT COUNT(*) AS n FROM user_inbox").n;
+      console.log("RESULT:" + JSON.stringify({ notnull: col.notnull, rows }));
+    `);
+    expect(r.exitCode).toBe(0);                          // hub 照常启动(fail-safe,不停机)
+    expect(r.stderr).toMatch(/migrate #1493/);            // 大声 warn(明确运维信号)
+    expect(r.stderr).toMatch(/network_id IS NULL/);
+    const m = r.stdout.match(/RESULT:(\{.*\})/);
+    expect(m).not.toBeNull();
+    const out = JSON.parse(m![1]);
+    expect(out.notnull).toBe(0);                          // 迁移被跳过 → 列暂保持可空
+    expect(out.rows).toBe(2);                             // 数据没丢(没盲目清空)
+  });
+
+  test("idempotent: booting an already-migrated (NOT NULL) DB twice is a no-op", () => {
+    const file = seedOldDb([{ mid: "dm_a", net: "net_a", user: "u_1" }]);
+    const r1 = bootWithDb(file, `console.log("RESULT:" + db.all("PRAGMA table_info(user_inbox)").find(c=>c.name==="network_id").notnull);`);
+    expect(r1.exitCode).toBe(0);
+    const r2 = bootWithDb(file, `console.log("RESULT:" + db.all("PRAGMA table_info(user_inbox)").find(c=>c.name==="network_id").notnull);`);
+    expect(r2.exitCode).toBe(0);
+    expect(r2.stdout).toContain("RESULT:1");              // 第二次仍 NOT NULL、不炸
+  });
+});

package/src/user-inbox-read-http.test.ts

@@ -16,7 +16,7 @@ let base = "";
 let adminToken = "", aToken = "", bToken = "";
 const MASTER_TOKEN = "legacy-master-token-for-test";
 let aUserId = "", bUserId = "", aNet = "", bNet = "";
-let adminUserId = "";
+let adminUserId = "", adminNet = "";
 
 const get = async (path: string, token: string) => {
   const r = await fetch(`${base}${path}`, { headers: { Authorization: `Bearer ${token}` } });
@@ -56,6 +56,7 @@ beforeAll(async () => {
   expect(admin.ok).toBe(true);
   adminToken = admin.token!;
   adminUserId = db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", `ui_admin_${stamp}`)!.user_id;
+  adminNet = admin.network_id!;
 
   const a = register(`ui_a_${stamp}`, "UiA-Strong-1!");
   const b = register(`ui_b_${stamp}`, "UiB-Strong-1!");
@@ -88,12 +89,18 @@ beforeAll(async () => {
   // A 自己的、但落在 A 不是成员的 network 上的行（例如 A 被移出该网后的遗留）。
   // 它是 addNetworkScope 这次调用的唯一 witnessed-red 对象：user_id 过滤对它无效。
   seedMessage("dm_a_foreign_net", aUserId, bNet, "A 在外网的遗留私信");
-  // network_id 为 NULL 的行。**写路径产不出这种行** —— send_desktop_message 有
-  // 三道闸（canWrite / `if (!effectiveNetId)` / targetRole），拆掉任意一道都还有
-  // 别的挡着，见 desktop-message-seam.test.ts 的两条孤儿断言。这里是手写夹具，
-  // 用来钉「万一库里有这种行（历史数据、将来的第二个写入方），谁读得到」。
-  seedMessage("dm_a_nonet", aUserId, null as any, "A 的无网络私信");
-  seedMessage("dm_admin_nonet", adminUserId, null as any, "admin 的无网络私信");
+  // #1493 —— network_id 升到 schema 级 NOT NULL 后,「network_id 为 NULL 的行」已
+  // **schema 级不可能**(写路径原本三闸挡、现在 DB 直接拒)。原先手播的 dm_a_nonet /
+  // dm_admin_nonet 两条 NULL 夹具随之删除:
+  //   · dm_a_nonet(证"受网络限制成员读不到 NULL 行")—— 网络 scope 隔离已由下面
+  //     dm_a_foreign_net(A 自己的行、落在 A 非成员的网)覆盖,不丢覆盖。
+  //   · dm_admin_nonet 重锚到 admin **自己网络**的非 NULL 行 dm_admin_own,保住
+  //     "admin(scope 助手 no-op)仍只读自己的、不绕过 user_id 过滤"这条覆盖。
+  seedMessage("dm_admin_own", adminUserId, adminNet, "admin 自己网络里的私信");
+  // #1493 SDK马 建议:用**非 NULL** 行补回"admin(scope 助手 no-op)能读到别网的自己的行"
+  // 这维覆盖(原先靠 NULL 行,现 NULL 不可能)。对照 dm_a_foreign_net(受限成员读不到),
+  // 两边都不依赖 NULL。
+  seedMessage("dm_admin_foreign_net", adminUserId, bNet, "admin 在别网的自己的私信");
   seedMessage("dm_a_read", aUserId, aNet, "A 已读的一条", undefined, 1);
   seedMessage("dm_a_secret", aUserId, aNet,
     "凭据在正文里 ntok_abcdef123456", JSON.stringify({ k: "ghp_" + "A".repeat(24) }));
@@ -139,20 +146,16 @@ describe("#1459 ① P3 GET /api/messages?scope=user", () => {
     expect(row.meta_json).toContain("ghp_***redacted***");
   });
 
-  // NULL 网络行的可见性**取决于调用者的 scope，不取决于行本身**：
-  //   受网络限制的成员 → addNetworkScope 生成 `network_id IN (...)`，NULL 不匹配 ⇒ 读不到
-  //   admin（resolveRestNetworkScope 给 networkIds=null，助手是 no-op） ⇒ 读得到
-  // 两条一起才说明"NULL 读不到"是 scope 造成的，不是 user_id 过滤造成的。
-  test("NULL 网络行：受网络限制的成员读不到", async () => {
-    const { body } = await get("/api/messages?scope=user", aToken);
-    expect(body.messages.map((m: any) => m.message_id)).not.toContain("dm_a_nonet");
-  });
-
-  test("NULL 网络行：scope 为 no-op 的调用者（admin）读得到自己的那条", async () => {
+  // #1493 后 NULL 网络行不可能,原"受网络限制成员读不到 NULL 行"一测删除——
+  // 网络 scope 隔离已由上面 dm_a_foreign_net(承重断言,test 112 line 121)覆盖。
+  // admin 一测重锚到非 NULL:验 admin(scope 助手 no-op)**仍只读自己的、不绕过 user_id 过滤**。
+  test("admin(scope 助手 no-op)仍受 user_id 限制：只读自己的、不读别人的", async () => {
     const { body } = await get("/api/messages?scope=user", adminToken);
     const ids = body.messages.map((m: any) => m.message_id);
-    expect(ids).toContain("dm_admin_nonet");
-    expect(ids).not.toContain("dm_a1");   // 仍然只读自己的：admin 不绕过 user_id 过滤
+    expect(ids).toContain("dm_admin_own");            // 读得到自己的
+    expect(ids).toContain("dm_admin_foreign_net");     // scope 助手 no-op → 跨网也读得到自己的
+    expect(ids).not.toContain("dm_a1");                // 承重:admin 不绕过 user_id 过滤读别人的
+    expect(body.messages.every((m: any) => m.user_id === adminUserId)).toBe(true);
   });
 
   test("unread 是未读数而非总数（A：4 条里 3 条未读）", async () => {

package/src/user-inbox-schema.test.ts

@@ -37,8 +37,9 @@ describe("#1459 user_inbox schema (P1)", () => {
     const mid = `dm_def_${Date.now()}`;
     try {
       db.run(
-        `INSERT INTO user_inbox (message_id, user_id, content) VALUES (?1, ?2, ?3)`,
-        [mid, "u_def_1459", "body"],
+        // #1493 后 network_id 是 NOT NULL,补上(本测试只验其它列的默认值)
+        `INSERT INTO user_inbox (message_id, network_id, user_id, content) VALUES (?1, ?2, ?3, ?4)`,
+        [mid, "net_def_1459", "u_def_1459", "body"],
       );
       const row = db.get<{ acked: number; kind: string; severity: string }>(
         "SELECT acked, kind, severity FROM user_inbox WHERE message_id = ?1", mid,