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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.43",
+  "version": "0.9.0-preview.44",
   "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

@@ -264,3 +264,87 @@ describe("#1353 Fix ② — /api/host-supervisors surfaces can_create_nodes + bl
     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/create-node-blocked-gate.test.ts

@@ -31,6 +31,7 @@ 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 {}
@@ -39,6 +40,18 @@ function cleanup() {
 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)
@@ -229,3 +242,115 @@ describe("#1353 Fix ① — hub gates create_node on daemon-reported can_create_
     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/report-status-host-schema.test.ts

@@ -74,3 +74,138 @@ describe("report_status host telemetry schema", () => {
     })).not.toThrow();
   });
 });
+
+/* #1545 —— `create_capability_observed_ms_ago` 的**验证宽度**本身就是判据。
+ *
+ * 这一格是纯诊断信息(那个 can_create_nodes 是多久以前测出来的)。zod 对象里
+ * 任何一个**已知字段**验证失败,整份 report_status 都会被拒 —— 不是丢掉这一格。
+ * 所以给它加 `.int()/.min()/.max()` 等于:一台节点发了个奇怪的诊断数字,
+ * 就在 hub 上整个失联。**#1225/#1498 已经用 host.ip 演过一遍这件事了。**
+ *
+ * 消毒在读取处(`/api/host-supervisors`),不在这里。 */
+describe("#1545 create_capability_observed_ms_ago —— schema 必须收得宽", () => {
+  const caps = () => schemas.report_status.config_snapshot;
+
+  test("前提:抓到的确实是 config_snapshot 形状,且它接受 daemon_capabilities", () => {
+    expect(caps()).toBeTruthy();
+    const parsed = caps().parse({
+      flags: {}, config_update_capable: false, peer_reply_inbox_capable: true,
+      daemon_capabilities: { can_create_nodes: true },
+    });
+    expect(parsed.daemon_capabilities.can_create_nodes).toBe(true);
+  });
+
+  test("正常值:透传", () => {
+    const parsed = caps().parse({
+      flags: {}, config_update_capable: false, peer_reply_inbox_capable: true,
+      daemon_capabilities: { can_create_nodes: true, create_capability_observed_ms_ago: 0 },
+    });
+    expect(parsed.daemon_capabilities.create_capability_observed_ms_ago).toBe(0);
+  });
+
+  test("null 必须被接受(显式「我没测过」和「我不发这一格」都要能表达)", () => {
+    const parsed = caps().parse({
+      flags: {}, config_update_capable: false, peer_reply_inbox_capable: true,
+      daemon_capabilities: { can_create_nodes: true, create_capability_observed_ms_ago: null },
+    });
+    expect(parsed.daemon_capabilities.create_capability_observed_ms_ago).toBeNull();
+  });
+
+  /* 🔴 这四个值**一个都不许让整份 report 被拒**。它们在读取侧会被当成「没报」,
+   *    但那是读取侧的事 —— 这一层的职责只有一个:别把节点踢下线。 */
+  test.each([
+    ["负数", -1],
+    ["非整数", 1234.5678],
+    ["超过一年", 400 * 24 * 60 * 60 * 1000],
+    ["NaN", Number.NaN],
+  ])("怪值不得拒掉整份 report_status:%s", (_label, value) => {
+    expect(() => caps().parse({
+      flags: {}, config_update_capable: false, peer_reply_inbox_capable: true,
+      daemon_capabilities: { can_create_nodes: false,
+        create_nodes_blocked_reason: "anet_bin_source",
+        create_capability_observed_ms_ago: value },
+    })).not.toThrow();
+  });
+
+  /* 🔴 反向锚:上面那组「不抛」如果只是因为**这个 key 压根没被 schema 看见**,
+   * 它们会一样绿。所以这里证明 schema 确实在看它:喂一个非数字,值必须**被改写成
+   * null**(而不是原样穿过去)。原样穿过去 = key 被忽略,那组测试就什么也没测。 */
+  test("反向锚:非数字被改写成 null(不是原样穿过)⇒ 证明 schema 确实在看这个 key", () => {
+    const parsed = caps().parse({
+      flags: {}, config_update_capable: false, peer_reply_inbox_capable: true,
+      daemon_capabilities: { can_create_nodes: true, create_capability_observed_ms_ago: "0" },
+    });
+    expect(parsed.daemon_capabilities.create_capability_observed_ms_ago).toBeNull();
+    expect(parsed.daemon_capabilities.create_capability_observed_ms_ago).not.toBe("0");
+  });
+});
+
+/* 🔴 #1545 —— 把 `host:` 上方那段方框注释里的表**钉住**。
+ *
+ * 那段注释说的是:这份 schema 的子对象一半 strict 一半不 strict,而「往里加一个
+ * hub 还不认识的键」的后果完全相反 —— 非 strict 静默丢弃(节点活着、字段蒸发),
+ * strict 拒掉整份 report(节点当场失联,#1225 的形状)。
+ *
+ * 注释会烂。这组测试的作用**不是禁止改 strict**(两种都各有其位),而是:谁改了,
+ * 谁就会在这里撞红,从而**被迫连注释一起改**。所以断言写成「和注释里那张表一致」,
+ * 而不是「必须是某个值」。 */
+describe("#1545 report_status 子对象的 strict 分布(注释里那张表的可执行副本)", () => {
+  const rs = () => schemas.report_status;
+  const UNKNOWN = { __hub_does_not_know_this_key__: 1 };
+
+  function acceptsUnknownKey(schema: any, base: object): "dropped" | "rejected" {
+    try {
+      const parsed = schema.parse({ ...base, ...UNKNOWN });
+      return "__hub_does_not_know_this_key__" in parsed ? "rejected" /* 不可能:留着说明它根本没被处理 */ : "dropped";
+    } catch { return "rejected"; }
+  }
+
+  const SIDE_THREAD = {
+    supported: true, runtime: "codex", runtimeVersion: "1.0",
+    topology: "native-exact-fork", evidenceRevision: "r1",
+  };
+  const SNAP_BASE = { flags: {}, config_update_capable: false, peer_reply_inbox_capable: true };
+
+  test.each([
+    ["host", () => rs().host, {}, "dropped"],
+    ["process_telemetry", () => rs().process_telemetry, {}, "dropped"],
+    ["config_snapshot", () => rs().config_snapshot, SNAP_BASE, "dropped"],
+    ["external_schedules", () => rs().external_schedules, { schedules: [] }, "rejected"],
+  ])("%s → 未知键被 %s", (_name, get, base, expected) => {
+    expect(acceptsUnknownKey(get(), base)).toBe(expected as string);
+  });
+
+  test("daemon_capabilities(嵌在 config_snapshot 里)→ 未知键被丢弃,不拒整份", () => {
+    const parsed: any = rs().config_snapshot.parse({
+      ...SNAP_BASE,
+      daemon_capabilities: { can_create_nodes: true, ...UNKNOWN },
+    });
+    expect(parsed.daemon_capabilities.can_create_nodes).toBe(true);
+    expect("__hub_does_not_know_this_key__" in parsed.daemon_capabilities).toBe(false);
+  });
+
+  test("side_thread_capability(同一个 config_snapshot 里)→ 未知键拒掉**整份**", () => {
+    expect(() => rs().config_snapshot.parse({
+      ...SNAP_BASE,
+      side_thread_capability: { ...SIDE_THREAD, ...UNKNOWN },
+    })).toThrow();
+    // 反向锚:去掉那个未知键必须过 —— 否则上面那条可能是被别的必填字段拒的,
+    // 和 strict 无关。
+    expect(() => rs().config_snapshot.parse({
+      ...SNAP_BASE, side_thread_capability: SIDE_THREAD,
+    })).not.toThrow();
+  });
+
+  /* 分母自证:上面这张表**两侧都有**。如果哪天全变成 dropped(或全 rejected),
+   * 那段注释描述的「不对称」就不存在了,而这条会先红。 */
+  test("这张表确实是不对称的(两种后果各至少一个)", () => {
+    const results = [
+      acceptsUnknownKey(rs().host, {}),
+      acceptsUnknownKey(rs().process_telemetry, {}),
+      acceptsUnknownKey(rs().config_snapshot, SNAP_BASE),
+      acceptsUnknownKey(rs().external_schedules, { schedules: [] }),
+    ];
+    expect(results.filter(r => r === "dropped").length).toBeGreaterThan(0);
+    expect(results.filter(r => r === "rejected").length).toBeGreaterThan(0);
+  });
+});

package/src/server.ts

@@ -3152,6 +3152,12 @@ return Bun.serve({
           // upgraded past preview.55.
           let snapCanCreate: boolean | undefined;
           let snapBlockedReason: string | undefined;
+          // #1545 —— 见 report_status schema 里 create_capability_observed_ms_ago 的注释:
+          // 上报侧**故意收得宽**(无 int/min/max,免得一个诊断字段能让整份 report 被拒),
+          // 消毒放在这里。非有限数、负数、超过 1 年的一律当作「没报」——
+          // 🔴 不是 clamp 成边界值:clamp 会把一个坏值变成一个**看起来正常的年龄**,
+          //    而这一格存在的全部意义就是让人分辨新鲜和陈旧。
+          let snapObservedMsAgo: number | undefined;
           if (r.config_snapshot) {
             try {
               const parsed = typeof r.config_snapshot === "string" ? JSON.parse(r.config_snapshot) : r.config_snapshot;
@@ -3164,12 +3170,18 @@ return Bun.serve({
                   && caps.create_nodes_blocked_reason.length > 0) {
                 snapBlockedReason = caps.create_nodes_blocked_reason;
               }
+              const rawAge = caps?.create_capability_observed_ms_ago;
+              if (typeof rawAge === "number" && Number.isFinite(rawAge)
+                  && rawAge >= 0 && rawAge <= 365 * 24 * 60 * 60 * 1000) {
+                snapObservedMsAgo = rawAge;
+              }
             } catch { /* malformed */ }
           }
-          return { row: r, role: snapRole, canCreate: snapCanCreate, blockedReason: snapBlockedReason };
+          return { row: r, role: snapRole, canCreate: snapCanCreate, blockedReason: snapBlockedReason,
+            observedMsAgo: snapObservedMsAgo };
         })
         .filter(({ role }) => role === "host_supervisor")
-        .map(({ row: r, canCreate, blockedReason }) => {
+        .map(({ row: r, canCreate, blockedReason, observedMsAgo }) => {
           let online = false;
           let lastSeenAt: string | null = null;
           if (r.session_last_seen) {
@@ -3221,6 +3233,18 @@ return Bun.serve({
             if (canCreate === false && blockedReason) {
               out.create_nodes_blocked_reason = blockedReason;
             }
+            // #1545 —— 只在 daemon 真的报了这一格时才出现。
+            // 🔴 缺席**不能**当成 0:那等于替一个从不重算的旧 daemon 宣称
+            //    「这是刚测的」,正好朝「没问题」方向说谎。缺席就让它缺席,
+            //    读的人据此说「年龄未知」(与 can_create_nodes 本身
+            //    undefined-vs-false 的处理同一条规矩,见上面 #1353 Fix ②)。
+            //
+            // 语义:该能力值是在**这份 report 发出前 N 毫秒**测得的。
+            // 绝对年龄 = (now - last_seen_at) + create_capability_observed_ms_ago。
+            // 用节点自己的钟只量了「多久以前」,绝对时间全部由 hub 的钟出。
+            if (typeof observedMsAgo === "number") {
+              out.create_capability_observed_ms_ago = observedMsAgo;
+            }
           }
           return out;
         });

package/src/tools.ts

@@ -517,6 +517,28 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       model: z.string().max(200).optional().describe("AI model name"),
       node_name: z.string().max(200).optional().describe("Stable node display name (may differ from alias)"),
       network_id: z.string().max(200).optional().describe("Network this agent belongs to"),
+      // ╭─ 🔴 往 report_status 里加字段之前先读这一段(#1545 实测,zod 4.3.6)─────────╮
+      // │ **这份 schema 的子对象一半严一半松,而后果完全不同。**
+      // │
+      // │   非 strict:host / process_telemetry / config_snapshot / daemon_capabilities
+      // │   `.strict()`:external_schedules(含其 schedules[] 元素)
+      // │              side_thread_capability(含其 exactBoundary)
+      // │
+      // │ 往**非 strict** 的对象里加一个 hub 还不认识的键 ⇒ zod **静默丢弃**。
+      // │   节点不会掉线,但字段人间蒸发 —— 现场表现为「daemon 明明发了、hub 上没有」,
+      // │   排查起来和 daemon 侧 bug 一模一样。
+      // │ 往**strict** 的对象里加同一个键 ⇒ `unrecognized_keys`,**整份 report_status 被拒**。
+      // │   而 agent-node 的 register() 是 `await` 且无人 catch ⇒ **节点进程当场死掉**
+      // │   (#1225 就是这么全网躺倒的,见下面 host.ip 那段)。
+      // │
+      // │ 所以「新字段能不能 daemon 先发」**没有统一答案,取决于你往哪个子对象里加**:
+      // │   非 strict → 可以先发(会丢,不会死);strict → hub 必须先合,否则升级即失联。
+      // │
+      // │ 🔴 别把这条读成「strict 更危险、都改成非 strict」。两者各有其位:
+      // │   external_schedules / side_thread_capability 是**有界快照**,strict 挡的是
+      // │   「节点往里塞任意键」;daemon_capabilities 是**能力自述**,天然要向前兼容
+      // │   (旧 hub 见到新能力应当忽略而不是拒绝整份上报)。**加字段前先看清你在哪一边。**
+      // ╰──────────────────────────────────────────────────────────────────────────────╯
       host: z.object({
         // 🔴 `.nullable()` 不是防御性冗余,是**发送方声明的类型**:agent-node 的
         //    HostTelemetry 是 `ip: string | null`,`firstNonInternalIPv4()` 在没有
@@ -599,6 +621,11 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         // never saw them, max_concurrent_children stayed default + the
         // allowlists stayed unenforced. PR3 nit ① per 通信龙).
         // Soft caps avoid abuse via attacker daemon.
+        // 🔴 这个对象**故意不是 `.strict()`** —— 能力自述必须向前兼容:
+        //    旧 hub 见到新 daemon 报的新能力,应当忽略那一格,而不是拒掉整份 report
+        //    把节点踢下线。代价是新键在 hub 升级前会被**静默丢弃**(所以新字段仍然
+        //    应当 hub 先合)。同一份 schema 里 side_thread_capability / external_schedules
+        //    是 `.strict()` 的,后果不同 —— 见 `host:` 上方那段方框注释。
         daemon_capabilities: z.object({
           runtimes_supported: z.array(z.string().max(64)).max(16).optional(),
           allowed_secret_keys: z.array(z.string().max(64)).max(64).optional(),
@@ -636,6 +663,40 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
             "anet_bin_permission",
             "anet_bin_unknown",
           ]).optional(),
+          // #1545 —— 上面那一格**是什么时候测出来的**。
+          //
+          // 🔴 版本号一律带包名 + 完整版本:仓里三个包各自独立编号,裸的 `preview.NN`
+          //    同时是三个不同的时间点。此处曾写成「preview.67」——
+          //    那是 agent-network 的号,agent-node 根本没有 .67(npm 404,最高 .56)。
+          // 🔴 为什么必须有:**agent-node ≤ 2.5.0-preview.54** 的 `daemonCreateCapability()`
+          //    用一个进程级缓存(`_createCapCache`)只算一次。开机时 pin 坏 ⇒ 之后
+          //    永远上报 blocked(哪怕运维已经写好 path.conf);开机时好 ⇒ 之后把二进制
+          //    chmod 掉也**永远上报 ready**。后者是朝「没问题」方向说谎。
+          //    而 hub 这边,一个 3 秒前测的 blocked 和一个三周前测的 blocked,
+          //    在 `last_seen_at` 上长得一模一样 —— 心跳是新的,那一格不是。
+          //
+          // 🔴 为什么是「多久以前」(时长)而不是绝对时间戳:这个值来自**节点自己的钟**。
+          //    时钟偏移下,绝对时间戳会算出一个既可能"永远新鲜"也可能"来自 1970"的年龄,
+          //    而且错的方向不可预测。时长对偏移免疫 —— hub 用自己的钟在收到时换算。
+          //
+          // 🔴 为什么不加 `.min()/.max()/.int()`:**这几个约束都会让整条 report_status 被拒**
+          //    (zod 对象里任何一个已知字段验证失败 = 整份被拒,不是丢掉这一格),
+          //    而这一格是纯诊断信息,不值得拿一台节点的在线状态去换。
+          //    收得宽,**在读取处消毒**(见 /api/host-supervisors)。
+          //    这条不是我新立的:同一个 schema 上方 `anet_bin_pin_unresolved` 那条注释
+          //    记的就是同一次教训 —— 删一个 enum 值会让所有 .40 daemon 失联。
+          //
+          // 🔴 `.catch(null)` 不是装饰:光写 `z.number()` **仍然会拒 NaN**
+          //    (实测:`z.number().nullable().optional()` 对 NaN 抛),而那意味着
+          //    一次算错的时长能让整台节点在 hub 上失联 —— 正是 #1225 里 host.ip
+          //    那个形状。`.catch(null)` 让这一格**在任何输入下都不可能拒掉整份 report**:
+          //    合法数字透传,其余一律变 null(读取侧当作「没报」)。
+          //    类型仍然是 number 而不是 unknown —— 别给一个 attacker daemon
+          //    留下"往快照里塞任意大对象"的口子(同 schema 上方 soft cap 的立场)。
+          //
+          // 不上报这一格 ≠ 0。旧 daemon 压根不发,读的人必须能把
+          // 「刚测的」「很久以前测的」「不知道」分成三件事说。
+          create_capability_observed_ms_ago: z.number().nullable().catch(null).optional(),
         }).optional(),
       }).optional().describe("RFC-024 — masked node config snapshot"),
     },
@@ -3233,10 +3294,60 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
             && caps.create_nodes_blocked_reason.length > 0)
             ? caps.create_nodes_blocked_reason
             : "anet_bin_unknown";
+          // #1545 —— 光说 `blocked_reason` 不够:**那个判断是什么时候做出来的**
+          // 决定了下一步完全不同的两件事。
+          //   刚测的 blocked      ⇒ 去那台机器按 reason 修
+          //   三周前测的 blocked  ⇒ 那台 daemon 是**开机算一次就永久缓存**的旧版本
+          //                        (agent-node ≤ 2.5.0-preview.54),它可能早就好了 ——
+          //                        先重启/升级它,再谈修 pin
+          // 而在拒绝这一刻,用户正好在决定"去修哪台机器"。
+          //
+          // 🔴 年龄未知时给的是**显式 null + 一个说明为什么的枚举**,不是省略这两个键。
+          //    省略读起来像"没有这个问题",而调用方(常常是个 agent)会默认它是刚测的
+          //    —— 那是朝「更可信」方向撒谎,比不给更糟。
+          const rawAge = caps.create_capability_observed_ms_ago;
+          const reportedAgeOk = typeof rawAge === "number" && Number.isFinite(rawAge)
+            && rawAge >= 0 && rawAge <= 365 * 24 * 60 * 60 * 1000;
+          // 🔴 daemon 报的是「测完到**这份 report 发出**之间隔了多久」,不是「到现在」。
+          //    两者差一个心跳间隔(3 分钟),而对一个已经失联的 daemon 差多少都可能。
+          //    直接把它当成"多久以前测的"渲染,会**朝更新鲜的方向**低报 ——
+          //    正是这一格要防的那个方向。所以在这里补上心跳那一段:
+          //      绝对年龄 = (now − last_seen_at) + daemon 报的时长
+          //    hub 的钟出绝对时间,daemon 只提供时长(它自己的钟偏移污染不了这个数)。
+          //
+          //    这是冷路径(只有被拒时才走),多一次小查询不影响心跳路径。
+          let heartbeatAgeMs: number | null = null;
+          try {
+            const sess = db.get<{ last_seen_at: string | null }>(
+              "SELECT last_seen_at FROM sessions WHERE node_id = ?1 ORDER BY last_seen_at DESC LIMIT 1",
+              daemon_node_id,
+            );
+            const t = sess?.last_seen_at ? Date.parse(sess.last_seen_at) : NaN;
+            if (Number.isFinite(t)) heartbeatAgeMs = Math.max(0, Date.now() - t);
+          } catch { /* 取不到就是取不到 —— 下面如实说 unknown,不猜 0 */ }
+
+          // 🔴 三种取值,不能塌成两种:
+          //    known                      两半都有,可以给绝对年龄
+          //    unknown_legacy_daemon      那台 daemon 根本没报这一格(旧版本)
+          //    unknown_no_heartbeat_time  它报了,但 hub 这边没有可用的心跳时间
+          //                               ⇒ **补不出绝对年龄**,而不是"年龄是 0"
+          const ageKnown = reportedAgeOk && heartbeatAgeMs !== null;
           return { content: [{ type: "text" as const, text: JSON.stringify({
             ok: false,
             error: "daemon_cannot_create_nodes",
             blocked_reason: reason,
+            // 到**现在**为止,这个判断做出来有多久了(毫秒)。null = 补不出来。
+            capability_observed_ms_ago: ageKnown ? heartbeatAgeMs! + (rawAge as number) : null,
+            capability_age: ageKnown
+              ? "known"
+              : (reportedAgeOk ? "unknown_no_heartbeat_time" : "unknown_legacy_daemon"),
+            // 🔴 这里**不复制那张 code → 修法命令 的表**。它只有一个作者,在
+            //    `@sleep2agi/agent-network` 的 daemon-capability-display —— 抄一份到 hub,
+            //    两份就会各自漂移,而「hub 教的修法」和「CLI 教的修法」不一致时,
+            //    没有任何东西会红。这里只把人指到那一份。
+            //    (同 `blocked_reason` 是 z.enum 而不是自由文本的立场:hub 出**代码**,
+            //     渲染留给客户端。)
+            remediation_hint: "run `anet daemon list` where that daemon is configured — it prints the exact, paste-able fix command for this blocked_reason",
             daemon_node_id,
           }) }] };
         }