@sleep2agi/commhub-server 0.9.0-preview.7 → 0.9.0-preview.71

package/src/config-apply-validate.test.ts

@@ -9,9 +9,11 @@ import { describe, expect, test } from "bun:test";
 import {
   ALLOWED_FLAGS,
   SECURITY_SENSITIVE_FLAGS,
+  EDITABLE_CHANNELS,
   isAllowedToChangeFlag,
   computeApplyMode,
   validatePatch,
+  narrowChannelsPatch,
 } from "./config-apply-validate";
 
 describe("ALLOWED_FLAGS — exact contract (no silent extension)", () => {
@@ -258,3 +260,93 @@ describe("validatePatch — combinations", () => {
     expect(r?.field).toBe("flags.maxTurns");
   });
 });
+
+// ── #260 P5 — channels support (restart-tier, non-security-sensitive) ─
+describe("EDITABLE_CHANNELS — mirrors agent-node runtime capability (cli.ts:671-676)", () => {
+  test("contains exactly telegram + feishu (channels agent-node actually forks workers for)", () => {
+    expect(EDITABLE_CHANNELS.size).toBe(2);
+    expect(EDITABLE_CHANNELS.has("telegram")).toBe(true);
+    expect(EDITABLE_CHANNELS.has("feishu")).toBe(true);
+  });
+  test("commhub is NOT editable — it's the RPC transport, not a per-node channel worker", () => {
+    expect(EDITABLE_CHANNELS.has("commhub")).toBe(false);
+  });
+  test("wechat is NOT editable — roadmap only on dashboard", () => {
+    expect(EDITABLE_CHANNELS.has("wechat")).toBe(false);
+  });
+});
+
+describe("narrowChannelsPatch — hostile input hygiene at the wire boundary", () => {
+  test("straight allow-listed input passes verbatim", () => {
+    expect(narrowChannelsPatch(["telegram", "feishu"])).toEqual(["telegram", "feishu"]);
+  });
+  test("empty array preserved — 'disable all editable channels' is a real state", () => {
+    expect(narrowChannelsPatch([])).toEqual([]);
+  });
+  test("non-array returns null (patch didn't touch channels)", () => {
+    expect(narrowChannelsPatch(undefined)).toBeNull();
+    expect(narrowChannelsPatch("telegram" as any)).toBeNull();
+    expect(narrowChannelsPatch({} as any)).toBeNull();
+  });
+  test("case-folded to lower", () => {
+    expect(narrowChannelsPatch(["FEISHU", "Telegram"])).toEqual(["feishu", "telegram"]);
+  });
+  test("duplicates deduped (Set)", () => {
+    expect(narrowChannelsPatch(["telegram", "telegram", "feishu", "TELEGRAM"])).toEqual(["telegram", "feishu"]);
+  });
+  test("unknown channel keys dropped silently (roadmap wechat, transport commhub, evil keys)", () => {
+    expect(narrowChannelsPatch(["wechat", "telegram", "evil-hacker", "commhub"])).toEqual(["telegram"]);
+  });
+  test("non-string entries dropped (numbers, objects, nulls)", () => {
+    expect(narrowChannelsPatch(["telegram", 42, {}, null, "feishu"] as any)).toEqual(["telegram", "feishu"]);
+  });
+  test("SQL-injection-shaped value dropped (not exact key match)", () => {
+    expect(narrowChannelsPatch(["telegram; drop table users;", "feishu"])).toEqual(["feishu"]);
+  });
+  test("whitespace around a key still trims to the key", () => {
+    expect(narrowChannelsPatch(["  feishu  "])).toEqual(["feishu"]);
+  });
+});
+
+describe("computeApplyMode — channels tier (restart)", () => {
+  test("channels-only patch → restart (boot forks per-channel workers)", () => {
+    expect(computeApplyMode(undefined, {}, ["feishu"])).toBe("restart");
+  });
+  test("empty-array channels → restart (still a state change)", () => {
+    expect(computeApplyMode(undefined, {}, [])).toBe("restart");
+  });
+  test("no channels key + no flags + no model → restart_only", () => {
+    expect(computeApplyMode(undefined, {}, undefined)).toBe("restart_only");
+  });
+  test("channels + hot-tier flag together stays restart (upgrade rules)", () => {
+    expect(computeApplyMode(undefined, { maxTurns: 5 }, ["telegram"])).toBe("restart");
+  });
+  test("channels + model → restart (model was already restart)", () => {
+    expect(computeApplyMode("gpt-5", {}, ["feishu"])).toBe("restart");
+  });
+});
+
+describe("validatePatch — channels defensive gate", () => {
+  test("valid channels array passes", () => {
+    expect(validatePatch(undefined, {}, ["telegram", "feishu"])).toBeNull();
+    expect(validatePatch(undefined, {}, [])).toBeNull();
+    expect(validatePatch(undefined, {}, ["telegram"])).toBeNull();
+  });
+  test("commhub rejected — RPC transport, not a per-node channel", () => {
+    const r = validatePatch(undefined, {}, ["commhub"]);
+    expect(r?.field).toBe("channels.commhub");
+  });
+  test("out-of-allowlist channel rejected (caller bypassed narrowing)", () => {
+    const r = validatePatch(undefined, {}, ["wechat"]);
+    expect(r?.field).toBe("channels.wechat");
+    expect(r?.reason).toMatch(/allowlist/);
+  });
+  test("non-string entry rejected", () => {
+    const r = validatePatch(undefined, {}, [42] as any);
+    expect(r?.field).toBe("channels");
+  });
+  test("non-array rejected", () => {
+    const r = validatePatch(undefined, {}, "telegram" as any);
+    expect(r?.field).toBe("channels");
+  });
+});

package/src/config-apply-validate.ts

@@ -57,6 +57,35 @@ export const RESTART_REQUIRED_FLAGS = new Set<string>([
   "timeout",
 ]);
 
+/**
+ * Channels the dashboard may enable/disable on a node via
+ * update_node_config. Intentionally narrow — the panel only exposes
+ * enable/disable, per-channel secrets stay in the node's local
+ * config.json (see #260 wire discipline).
+ *
+ * The list mirrors agent-node's actual runtime capability. See
+ * agent-node/src/cli.ts:671-676 — CHANNELS are parsed into per-type
+ * worker inits (initTelegramChannel + initFeishuChannel), and any
+ * other channel type triggers `process.exit(1)` at boot. So the
+ * hub-side allow-list here is telegram + feishu ONLY. `commhub` is
+ * the RPC transport that every node speaks unconditionally; treating
+ * it as a per-node channel would be a UX lie (toggle looks off but
+ * commhub is always on).
+ *
+ * Dashboard PR #31 currently includes `commhub` in its own
+ * EDITABLE_CHANNELS whitelist — that follow-up narrowing is filed for
+ * the next dashboard rally, and until then hub silently drops any
+ * `commhub` entry via narrowChannelsPatch.
+ *
+ * Not part of SECURITY_SENSITIVE_FLAGS (通信龙 P5 派工): flipping a
+ * channel on/off is a lifecycle-tier operation like `restart_node`, not
+ * a privilege elevation. Cross-tenant reach is already gated by SEC-1.
+ */
+export const EDITABLE_CHANNELS = new Set<string>([
+  "telegram",
+  "feishu",
+]);
+
 /**
  * Role-gate for the patch's flag set. SEC-2 enforcement lives here.
  *
@@ -99,22 +128,53 @@ export function isAllowedToChangeFlag(
 
 /**
  * Classify the patch's required apply mode. Empty patch (model + flags
- * both empty) → "restart_only" (used by restart_node tool). Any
- * restart-required field present → "restart". Otherwise → "hot".
+ * both empty, no channels) → "restart_only" (used by restart_node tool).
+ * Any restart-required field present, OR a channels change → "restart"
+ * (channels is restart-tier by design: the node reads its channel set
+ * once at boot in agent-node/src/cli.ts and forks per-channel workers
+ * from it, so a channel enable/disable takes effect on process restart
+ * only — see #260 P5 wire discipline). Otherwise → "hot".
  */
 export function computeApplyMode(
   model: string | undefined,
   flags: Record<string, unknown>,
+  channels?: string[] | undefined,
 ): "hot" | "restart" | "restart_only" {
-  const fieldCount = (model !== undefined ? 1 : 0) + Object.keys(flags).length;
+  const fieldCount = (model !== undefined ? 1 : 0) + Object.keys(flags).length + (channels !== undefined ? 1 : 0);
   if (fieldCount === 0) return "restart_only";
   if (model !== undefined) return "restart";
+  if (channels !== undefined) return "restart";
   for (const key of Object.keys(flags)) {
     if (RESTART_REQUIRED_FLAGS.has(key)) return "restart";
   }
   return "hot";
 }
 
+/**
+ * Narrow + allow-list `channels` from untrusted patch JSON. Returns the
+ * final channel key list (case-folded, deduped, in EDITABLE_CHANNELS
+ * order-preserving), OR null if the input isn't an array. Non-strings,
+ * unknown keys, empty strings, and duplicates are silently dropped —
+ * same fail-shape as the dashboard route's whitelist so the two sides
+ * behave identically end-to-end. Callers pass `undefined` through when
+ * the patch didn't include a channels key at all (a distinct case from
+ * `channels: []` which means "disable all editable channels").
+ */
+export function narrowChannelsPatch(raw: unknown): string[] | null {
+  if (!Array.isArray(raw)) return null;
+  const allow = EDITABLE_CHANNELS;
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const v of raw) {
+    if (typeof v !== "string") continue;
+    const key = v.trim().toLowerCase();
+    if (!allow.has(key) || seen.has(key)) continue;
+    seen.add(key);
+    out.push(key);
+  }
+  return out;
+}
+
 /**
  * Validate the patch shape — allowlist + per-field range / enum. Returns
  * null on pass, or `{ field, reason }` on reject. Caller wraps in error
@@ -123,12 +183,30 @@ export function computeApplyMode(
 export function validatePatch(
   model: string | undefined,
   flags: Record<string, unknown>,
+  channels?: string[] | undefined,
 ): { field: string; reason: string } | null {
   if (model !== undefined) {
     if (typeof model !== "string" || model.length === 0 || model.length > 200) {
       return { field: "model", reason: "must be a non-empty string ≤ 200 chars" };
     }
   }
+  if (channels !== undefined) {
+    // Zod already enforced string[], and narrowChannelsPatch dropped
+    // unknown keys before this point — but re-verify defensively so a
+    // future caller that skips narrowChannelsPatch can't smuggle
+    // unknown keys through validatePatch alone.
+    if (!Array.isArray(channels)) {
+      return { field: "channels", reason: "must be an array of strings" };
+    }
+    for (const c of channels) {
+      if (typeof c !== "string") {
+        return { field: "channels", reason: "must contain only strings" };
+      }
+      if (!EDITABLE_CHANNELS.has(c)) {
+        return { field: `channels.${c}`, reason: "not in editable channels allowlist" };
+      }
+    }
+  }
   for (const [key, val] of Object.entries(flags)) {
     if (!ALLOWED_FLAGS.has(key)) {
       return { field: `flags.${key}`, reason: "not in allowlist" };

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

@@ -0,0 +1,356 @@
+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 sessions 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);
+
+/** #1545 —— 可选:写一条 sessions 心跳行。
+ *  默认**不写**,这样既有那 9 条测试的行为逐字不变;
+ *  只有要断言绝对年龄的用例才显式给 `heartbeatAgoMs`。 */
+function seedHeartbeat(agoMs: number) {
+  const iso = new Date(Date.now() - agoMs).toISOString();
+  db.run(
+    `INSERT INTO sessions (alias, node_id, network_id, status, last_seen_at, updated_at)
+     VALUES (?1, ?2, ?3, 'idle', ?4, ?4)`,
+    [DAEMON_ALIAS, DAEMON_ID, NET, iso],
+  );
+}
+
+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");
+  });
+});
+
+/* #1545 —— 拒绝的时候还要说**那个判断是什么时候做出来的**。
+ *
+ * 为什么这一格落在拒绝路径上最要紧:用户被挡住的这一刻,正好在决定"去修哪台机器"。
+ *   刚测的 blocked      ⇒ 去那台机器按 reason 修
+ *   三周前测的 blocked  ⇒ 那台 daemon 是**开机算一次就永久缓存**的旧版本
+ *                        (agent-node ≤ 2.5.0-preview.54),它可能早就好了 —— 先重启/升级它
+ * 只给 `blocked_reason` 的话,这两种情况给用户的字**一模一样**。 */
+describe("#1545 拒绝文案带上「这个判断是多久以前做的」", () => {
+  const blockedSnap = (extra: object) => ({
+    role: "host_supervisor",
+    daemon_capabilities: {
+      can_create_nodes: false,
+      create_nodes_blocked_reason: "anet_bin_permission",
+      ...extra,
+    },
+  });
+
+  /* 🔴 报出去的是**到现在为止**的绝对年龄,不是 daemon 报的那个原始时长。
+   * daemon 报的是「测完到**这份 report 发出**」;直接透传会漏掉心跳那一段,
+   * **朝更新鲜的方向低报** —— 正是这一格要防的方向。
+   *   绝对年龄 = (now − last_seen_at) + daemon 报的时长 */
+  test("daemon 报了年龄 + 有心跳时间 → 补上心跳那一段,标记 known", async () => {
+    seed(blockedSnap({ create_capability_observed_ms_ago: 12_345 }));
+    seedHeartbeat(60_000);            // 上次心跳在 60s 前
+    const r = await call(tools().create_node, { daemon_node_id: DAEMON_ID, node_spec: spec });
+    expect(r.ok).toBe(false);
+    expect(r.blocked_reason).toBe("anet_bin_permission");
+    expect(r.capability_age).toBe("known");
+    // 允许 ±5s 的执行抖动;关键是它**明显大于** 12,345,即心跳那一段确实被加上了
+    const got = r.capability_observed_ms_ago as number;
+    expect(got).toBeGreaterThanOrEqual(12_345 + 60_000 - 5_000);
+    expect(got).toBeLessThanOrEqual(12_345 + 60_000 + 5_000);
+    // 🔴 反向锚:如果实现是"原样透传",这个数会恰好等于 12,345
+    expect(got).not.toBe(12_345);
+  });
+
+  /* 🔴 第三种 unknown,不能和「旧 daemon 没报」塌成同一个:
+   * 它报了,但 hub 这边没有可用的心跳时间 ⇒ **补不出绝对年龄**,而不是"年龄是 0"。 */
+  test("报了年龄但 hub 没有心跳时间 → unknown_no_heartbeat_time(不是 legacy,也不是 0)", async () => {
+    seed(blockedSnap({ create_capability_observed_ms_ago: 12_345 }));
+    // 故意不 seedHeartbeat
+    const r = await call(tools().create_node, { daemon_node_id: DAEMON_ID, node_spec: spec });
+    expect(r.capability_age).toBe("unknown_no_heartbeat_time");
+    expect(r.capability_observed_ms_ago).toBeNull();
+  });
+
+  /* 🔴 本组的重点:年龄未知时给的是**显式 null + 说明为什么的枚举**,
+   * 而不是省略这两个键。省略读起来像"没有这个问题",而调用方(常常是个 agent)
+   * 会默认它是刚测的 —— 那是朝「更可信」方向撒谎,比不给更糟。 */
+  test("🔴 daemon 没报年龄 → 两个键都在:null + unknown_legacy_daemon(不是省略)", async () => {
+    seed(blockedSnap({}));
+    seedHeartbeat(1_000);   // 心跳齐全 ⇒ 唯一缺的就是 daemon 没报那一格
+    const r = await call(tools().create_node, { daemon_node_id: DAEMON_ID, node_spec: spec });
+    expect(r.ok).toBe(false);
+    expect("capability_observed_ms_ago" in r).toBe(true);
+    expect(r.capability_observed_ms_ago).toBeNull();
+    expect(r.capability_age).toBe("unknown_legacy_daemon");
+    // 🔴 绝不能渲染成"刚测的"
+    expect(r.capability_observed_ms_ago).not.toBe(0);
+  });
+
+  test.each([
+    ["负数", -1],
+    ["超过一年", 400 * 24 * 60 * 60 * 1000],
+    ["非数字", "12"],
+    ["null", null],
+  ])("坏值当作没报(不 clamp 成一个看起来正常的年龄):%s", async (_l, v) => {
+    seed(blockedSnap({ create_capability_observed_ms_ago: v }));
+    // 🔴 必须给心跳:否则这几条会因为"没有心跳时间"而变成
+    //    unknown_no_heartbeat_time,**坏值那一维根本没被测到**
+    //    (夹具只该在被测的那一维上不合法)。
+    seedHeartbeat(1_000);
+    const r = await call(tools().create_node, { daemon_node_id: DAEMON_ID, node_spec: spec });
+    expect(r.capability_age).toBe("unknown_legacy_daemon");
+    expect(r.capability_observed_ms_ago).toBeNull();
+    // 分母自证:拒绝本身仍然发生了,不是因为整条路径没走到才"没有年龄"
+    expect(r.error).toBe("daemon_cannot_create_nodes");
+  });
+
+  test("边界:恰好一年被接受 ⇒ 上面那些不是因为恒判 unknown 才绿", async () => {
+    const oneYear = 365 * 24 * 60 * 60 * 1000;
+    seed(blockedSnap({ create_capability_observed_ms_ago: oneYear }));
+    seedHeartbeat(1_000);
+    const r = await call(tools().create_node, { daemon_node_id: DAEMON_ID, node_spec: spec });
+    expect(r.capability_age).toBe("known");
+    expect(r.capability_observed_ms_ago as number).toBeGreaterThanOrEqual(oneYear);
+  });
+
+  /* 🔴 hub 出**代码**,不出渲染好的修法命令 —— 那张 code → 命令 的表只有一个作者
+   * (@sleep2agi/agent-network 的 daemon-capability-display)。抄一份到 hub,
+   * 两份就会各自漂移,而「hub 教的修法」和「CLI 教的修法」不一致时没有任何东西会红。 */
+  test("🔴 hub 不返回具体修法命令,只把人指到那唯一一份", async () => {
+    seed(blockedSnap({ create_capability_observed_ms_ago: 0 }));
+    seedHeartbeat(1_000);
+    const r = await call(tools().create_node, { daemon_node_id: DAEMON_ID, node_spec: spec });
+    const blob = JSON.stringify(r);
+    for (const leaked of ["chmod go-w", "npm i -g", "readlink -f", "/etc/anet-daemon"]) {
+      expect(blob).not.toContain(leaked);
+    }
+    expect(String(r.remediation_hint)).toContain("anet daemon list");
+    // 正控:这四条不是恒真 —— 它们确实是那份表里的真实内容
+    expect("该二进制 group/other 可写。一行修:chmod go-w \"$(command -v anet)\"").toContain("chmod go-w");
+  });
+
+  test("健康 daemon 不受影响:正常派发,不带这两个键", async () => {
+    seed({ role: "host_supervisor", daemon_capabilities: { can_create_nodes: true } });
+    const r = await call(tools().create_node, { daemon_node_id: DAEMON_ID, node_spec: spec });
+    expect(r.ok).not.toBe(false);
+    expect("capability_age" in r).toBe(false);
+  });
+});

package/src/create-node-tool-schema.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from "bun:test";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools } from "./tools.js";
+
+type ToolHandler = (args: any) => Promise<any> | any;
+
+function captureSchemas(): Record<string, Record<string, any>> {
+  const server = new McpServer({ name: "test", version: "0" }) as any;
+  const schemas: Record<string, Record<string, any>> = {};
+  const origTool = server.tool.bind(server);
+  server.tool = (name: string, desc: string, schema: any, handler: ToolHandler) => {
+    schemas[name] = schema;
+    return origTool(name, desc, schema, handler);
+  };
+  registerTools(server, undefined, null, "u_schema_test", "schema-test", false, null);
+  return schemas;
+}
+
+describe("create_node MCP schema", () => {
+  test("model is optional on daemon create specs but empty strings stay invalid", () => {
+    const schemas = captureSchemas();
+    const nodeSpec = schemas.create_node.node_spec;
+
+    expect(nodeSpec.safeParse({
+      name: "child",
+      runtime: "claude-agent-sdk",
+    }).success).toBe(true);
+    expect(nodeSpec.safeParse({
+      name: "child",
+      runtime: "claude-agent-sdk",
+      model: null,
+    }).success).toBe(true);
+    expect(nodeSpec.safeParse({
+      name: "child",
+      runtime: "claude-agent-sdk",
+      model: "",
+    }).success).toBe(false);
+  });
+});