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

package/src/task-lifecycle-watcher.test.ts

@@ -23,6 +23,10 @@ function sqliteUtcTimestamp(date: Date): string {
   return date.toISOString().slice(0, 19).replace("T", " ");
 }
 
+// 30s 而不是 bun 默认的 5s:这个 hook 跑 register()(KDF)+bootServer(),
+// 本机空载基线 ~620ms,而 2026-08-17 与 2026-08-31 两次 CI 上它被 5s 上限打死
+// (0 pass / 1 fail / Ran 1 test —— 见 #928、#1627)。5247ms 是**被截断的下界**,
+// 不是测量值,所以余量按基线的 ~48x 取,而不是按那个数取。
 beforeAll(async () => {
   const { register } = await import("./auth.js");
   const auth = register(`watcher_owner_${Date.now()}`, "WatcherOwner-Strong-1!", undefined, "watcher");
@@ -39,7 +43,7 @@ beforeAll(async () => {
   const mod = await import("./server.js");
   server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
   base = `http://127.0.0.1:${server.port}`;
-});
+}, 30_000);
 
 afterAll(() => {
   try { server?.stop(true); } catch {}

package/src/task-network-resolution-http.test.ts

@@ -46,6 +46,10 @@ function seedTarget(principal: Principal): void {
   );
 }
 
+// 30s 而不是 bun 默认的 5s:这个 hook 跑 register()(KDF)+bootServer(),
+// 本机空载基线 ~620ms,而 2026-08-17 与 2026-08-31 两次 CI 上它被 5s 上限打死
+// (0 pass / 1 fail / Ran 1 test —— 见 #928、#1627)。5247ms 是**被截断的下界**,
+// 不是测量值,所以余量按基线的 ~48x 取,而不是按那个数取。
 beforeAll(async () => {
   process.env.COMMHUB_DB = process.env.COMMHUB_DB || join(PRIVATE_DB_DIR, "hub.db");
   adminSingle = registerPrincipal("admin_single", true);
@@ -70,7 +74,7 @@ beforeAll(async () => {
   const mod: any = await import("./server.js");
   server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
   base = `http://127.0.0.1:${server.port}`;
-});
+}, 30_000);
 
 afterAll(() => {
   try { server?.stop?.(true); } catch {}

package/src/tasks-pagination-http.test.ts

@@ -28,6 +28,10 @@ function seedTask(
   );
 }
 
+// 30s 而不是 bun 默认的 5s:这个 hook 跑 register()(KDF)+bootServer(),
+// 本机空载基线 ~620ms,而 2026-08-17 与 2026-08-31 两次 CI 上它被 5s 上限打死
+// (0 pass / 1 fail / Ran 1 test —— 见 #928、#1627)。5247ms 是**被截断的下界**,
+// 不是测量值,所以余量按基线的 ~48x 取,而不是按那个数取。
 beforeAll(async () => {
   ({ db } = await import("./db.js"));
   ({ register } = await import("./auth.js"));
@@ -54,7 +58,7 @@ beforeAll(async () => {
   const mod = await import("./server.js");
   server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
   base = `http://127.0.0.1:${server.port}`;
-});
+}, 30_000);
 
 afterAll(() => {
   try { server?.stop(true); } catch {}

package/src/tools.ts

@@ -61,6 +61,7 @@ import {
 import { sharedSendDedup, buildDuplicateSendPayload } from "./send_dedup.js";
 import { clientRequestIdFromMeta, idempotentTaskId, idempotentTaskMatches, type StoredIdempotentTask } from "./task-idempotency.js";
 import { stampTaskAuthOrigin, type TaskAuthOrigin } from "./task-auth-origin.js";
+import { parseHubTimestamp } from "./hub-timestamp";
 
 function ts(): string {
   return new Date().toTimeString().slice(0, 8);
@@ -517,6 +518,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 +622,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 +664,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"),
     },
@@ -2426,9 +2488,12 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
           ],
         );
       });
-      // #1459 — pushUserEvent 在没有订阅者时静默 return，而这个工具既不写
-      // inbox、也没有任何 user 级回读路径（/api/messages 只 SELECT FROM inbox）。
-      // 也就是说用户 dashboard 关着的时候这条消息就永久没了。
+      // #1459 / #1563 — pushUserEvent 在没有订阅者时静默 return。
+      // 🔴 这段注释原先写「本工具既不写 inbox、也没有 user 级回读路径 ⇒ dashboard
+      //    关着时消息永久没了」。**那半句已经不成立** —— 上面 20 行就在
+      //    `INSERT INTO user_inbox`，且 `/api/messages?scope=user` 能回读
+      //    （desktop-message-seam.test.ts 有真实 send → 真实 GET 的端到端断言）。
+      //    留着它会把 debug 未读数的人直接带向错误的一层。
       //
       // 这里先把**丢失变可见**：`ok` 仍表示「请求被接受、审计已落库」，
       // 新增 `delivered` 表示「此刻真的有人收到」。判据取自订阅者注册表，
@@ -2937,6 +3002,240 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     },
   );
 
+  // ── app#225 — 节点规则文件（AGENTS.md / CLAUDE.md）远程读写 ──
+  //
+  // 形状照抄 RFC-024 config-apply：客户端调 read_node_rules_file /
+  // write_node_rules_file 落一行 node_rules_requests + 门铃 {type:"rules_file"}；
+  // 节点收到门铃后 get_rules_file_request 拉（和 get_config_update 同一道
+  // F-A 闸：网络 token + alias），做完 ack_rules_file_request 回报；客户端
+  // 轮询 get_rules_file_result。
+  //
+  // 🔴 安全（#225 验收第 5 条）：整条链路**没有路径参数**。文件名由节点按
+  // 自己的 RUNTIME 决定（claude → CLAUDE.md，其余 → AGENTS.md），目录固定是
+  // 节点进程的 cwd（agent-node/src/runtime/rules-file.ts）。hub 只传 op +
+  // content，客户端连文件名都指定不了，所以不存在「借路径参数写任意文件」。
+  // 读和写都要 canWrite：规则文件是节点行为的一部分，读它等于读节点配置。
+  const RULES_FILE_MAX_BYTES = 256 * 1024;
+  const RULES_REQUEST_STALE_MS = 60_000;
+
+  const enqueueRulesFileRequest = (
+    op: "read" | "write",
+    a: { node_id?: string; child_node_id?: string; network_id?: string; content?: string },
+  ) => {
+    const idArg = resolveNodeIdArg({ node_id: a.node_id, child_node_id: a.child_node_id });
+    if (!idArg.ok) return { content: [{ type: "text" as const, text: JSON.stringify(idArg) }] };
+    const nodeId = idArg.node_id;
+    const effectiveNetId = getNetworkId(a.network_id);
+    if (!canWrite(effectiveNetId)) return writeDeniedReply(effectiveNetId, `${op} rules file`);
+
+    const { row: node, sec1Ok } = resolveTargetNode(nodeId, effectiveNetId);
+    if (!node) {
+      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "node_not_found", node_id: nodeId }) }] };
+    }
+    if (!sec1Ok) {
+      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "cross_network_node", message: "node belongs to another network" }) }] };
+    }
+    if (op === "write") {
+      if (typeof a.content !== "string") {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "invalid_content", reason: "content must be a string" }) }] };
+      }
+      const bytes = Buffer.byteLength(a.content, "utf8");
+      if (bytes > RULES_FILE_MAX_BYTES) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "content_too_large", bytes, max_bytes: RULES_FILE_MAX_BYTES }) }] };
+      }
+    }
+
+    // 单飞 + 陈旧回收，同 update_node_config 的 F-B：节点掉线时旧行永远
+    // 非终态，不回收就把这个节点锁死。
+    const inFlight = db.get<{ request_id: string; created_at: number; pulled_at: number | null }>(
+      "SELECT request_id, created_at, pulled_at FROM node_rules_requests WHERE node_id = ?1 AND status IN ('pending', 'in_progress') ORDER BY created_at DESC LIMIT 1",
+      nodeId,
+    );
+    if (inFlight) {
+      const age = Date.now() - (inFlight.pulled_at ?? inFlight.created_at);
+      if (age <= RULES_REQUEST_STALE_MS) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "request_in_flight", existing_request_id: inFlight.request_id, age_ms: age }) }] };
+      }
+      db.run(
+        "UPDATE node_rules_requests SET status = 'timeout', acked_at = ?1, error = ?2 WHERE request_id = ?3",
+        [Date.now(), `superseded after ${age}ms (> ${RULES_REQUEST_STALE_MS}ms) — node did not answer`, inFlight.request_id],
+      );
+    }
+
+    const requestId = `rf_${uuidv4()}`;
+    const networkId = node.network_id || "default";
+    db.run(
+      `INSERT INTO node_rules_requests (request_id, node_id, network_id, op, content, status, created_at, created_by_token) VALUES (?1, ?2, ?3, ?4, ?5, 'pending', ?6, ?7)`,
+      [requestId, nodeId, networkId, op, op === "write" ? a.content! : null, Date.now(), callerTokenId || "unknown"],
+    );
+    pushEvent(node.alias, { type: "rules_file", request_id: requestId }, networkId);
+    return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, request_id: requestId, op }) }] };
+  };
+
+  server.tool(
+    "read_node_rules_file",
+    "Ask a node to send back its rules file (CLAUDE.md for claude nodes, AGENTS.md otherwise) from its working directory. No path argument by design. Poll get_rules_file_result with the returned request_id. app#225.",
+    { ...NODE_ID_ALIAS_FIELDS, network_id: z.string().max(200).optional() },
+    async ({ node_id, child_node_id, network_id }) => enqueueRulesFileRequest("read", { node_id, child_node_id, network_id }),
+  );
+
+  server.tool(
+    "write_node_rules_file",
+    "Ask a node to overwrite its rules file (CLAUDE.md for claude nodes, AGENTS.md otherwise) in its working directory with `content`. No path argument by design. Poll get_rules_file_result with the returned request_id. app#225.",
+    {
+      ...NODE_ID_ALIAS_FIELDS,
+      content: z.string().max(RULES_FILE_MAX_BYTES).describe("Full new file content (UTF-8). The node writes it atomically."),
+      network_id: z.string().max(200).optional(),
+    },
+    async ({ node_id, child_node_id, content, network_id }) => enqueueRulesFileRequest("write", { node_id, child_node_id, content, network_id }),
+  );
+
+  server.tool(
+    "get_rules_file_request",
+    "Node pulls its oldest pending rules-file request (called from agent-node when the SSE rules_file doorbell arrives). app#225.",
+    {},
+    async () => {
+      // 同 get_config_update 的 F-A 闸：必须是网络 token + alias。
+      if (!callerTokenIsNetwork || !enforceNetworkId) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "network_token_required" }) }] };
+      }
+      if (!callerAlias) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "alias_required" }) }] };
+      }
+      const node = db.get<any>(
+        "SELECT node_id FROM nodes WHERE alias = ?1 AND network_id = ?2",
+        callerAlias,
+        enforceNetworkId,
+      );
+      if (!node) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, request: null }) }] };
+      }
+      const req = db.get<any>(
+        "SELECT request_id, op, content FROM node_rules_requests WHERE node_id = ?1 AND status = 'pending' ORDER BY created_at ASC LIMIT 1",
+        node.node_id,
+      );
+      if (!req) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, request: null }) }] };
+      }
+      db.run(
+        "UPDATE node_rules_requests SET status = 'in_progress', pulled_at = ?1 WHERE request_id = ?2 AND status = 'pending'",
+        [Date.now(), req.request_id],
+      );
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify({
+            ok: true,
+            request: {
+              request_id: req.request_id,
+              op: req.op,
+              ...(req.op === "write" ? { content: req.content ?? "" } : {}),
+            },
+          }),
+        }],
+      };
+    },
+  );
+
+  server.tool(
+    "ack_rules_file_request",
+    "Node reports the outcome of a rules-file request — done (with content for reads) or failed (with error). app#225.",
+    {
+      request_id: z.string().min(1).max(200),
+      status: z.enum(["done", "failed"]),
+      file_name: z.string().max(64).optional(),
+      exists: z.boolean().optional(),
+      content: z.string().max(RULES_FILE_MAX_BYTES).optional(),
+      error: z.string().max(2000).optional(),
+    },
+    async ({ request_id: requestId, status, file_name: fileName, exists, content, error: ackError }) => {
+      if (!callerTokenIsNetwork || !enforceNetworkId) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "network_token_required" }) }] };
+      }
+      if (!callerAlias) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "alias_required" }) }] };
+      }
+      const node = db.get<any>(
+        "SELECT node_id FROM nodes WHERE alias = ?1 AND network_id = ?2",
+        callerAlias,
+        enforceNetworkId,
+      );
+      if (!node) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, ignored: "alias_unknown" }) }] };
+      }
+      const req = db.get<any>(
+        "SELECT request_id, node_id, status FROM node_rules_requests WHERE request_id = ?1",
+        requestId,
+      );
+      // 跨租户闸：只能 ack 自己的请求；别人的当不存在处理。
+      if (!req || req.node_id !== node.node_id) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, ignored: "unknown_or_foreign_request" }) }] };
+      }
+      if (req.status === "done" || req.status === "failed" || req.status === "timeout") {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, ignored: "already_terminal", current_status: req.status }) }] };
+      }
+      db.run(
+        `UPDATE node_rules_requests SET status = ?1, acked_at = ?2, file_name = ?3, file_exists = ?4, result_content = ?5, error = ?6 WHERE request_id = ?7`,
+        [
+          status,
+          Date.now(),
+          fileName ?? null,
+          typeof exists === "boolean" ? (exists ? 1 : 0) : null,
+          status === "done" ? (content ?? null) : null,
+          status === "failed" ? (ackError || "node reported failure without a reason") : null,
+          requestId,
+        ],
+      );
+      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, request_id: requestId, status }) }] };
+    },
+  );
+
+  server.tool(
+    "get_rules_file_result",
+    "Poll the outcome of a read_node_rules_file / write_node_rules_file request. Returns status pending|in_progress|done|failed|timeout, the file name the node used, and (for reads) the content. app#225.",
+    { request_id: z.string().min(1).max(200), network_id: z.string().max(200).optional() },
+    async ({ request_id: requestId, network_id: clientNetId }) => {
+      const effectiveNetId = getNetworkId(clientNetId);
+      if (!canWrite(effectiveNetId)) return writeDeniedReply(effectiveNetId, "read rules file result");
+      const row = db.get<any>(
+        "SELECT request_id, node_id, network_id, op, status, file_name, file_exists, result_content, error, created_at, pulled_at, acked_at FROM node_rules_requests WHERE request_id = ?1",
+        requestId,
+      );
+      // SEC-1：结果行的网络必须等于调用方作用域，否则当不存在。
+      if (!row || row.network_id !== (effectiveNetId || "default")) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "request_not_found", request_id: requestId }) }] };
+      }
+      let status: string = row.status;
+      const ageMs = Date.now() - (row.pulled_at ?? row.created_at);
+      if ((status === "pending" || status === "in_progress") && ageMs > RULES_REQUEST_STALE_MS) {
+        status = "timeout";
+        db.run(
+          "UPDATE node_rules_requests SET status = 'timeout', acked_at = ?1, error = ?2 WHERE request_id = ?3 AND status IN ('pending', 'in_progress')",
+          [Date.now(), `node did not answer within ${RULES_REQUEST_STALE_MS}ms (offline, or running an agent-node without app#225 support)`, requestId],
+        );
+        row.error = `node did not answer within ${RULES_REQUEST_STALE_MS}ms (offline, or running an agent-node without app#225 support)`;
+      }
+      return {
+        content: [{
+          type: "text" as const,
+          text: JSON.stringify({
+            ok: true,
+            request_id: row.request_id,
+            node_id: row.node_id,
+            op: row.op,
+            status,
+            file_name: row.file_name ?? null,
+            exists: row.file_exists === null || row.file_exists === undefined ? null : row.file_exists === 1,
+            ...(status === "done" && row.op === "read" ? { content: row.result_content ?? "" } : {}),
+            error: row.error ?? null,
+            age_ms: ageMs,
+          }),
+        }],
+      };
+    },
+  );
+
+
   server.tool(
     "restart_node",
     "Trigger a node restart without changing config. RFC-024 Vincent 2026-06-28 increment. Network-scoped (SEC-1); member+ role suffices (lifecycle ops are not privilege elevation).",
@@ -3233,10 +3532,63 @@ 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,
+            );
+            // #1650 — 这一列是 TEXT(`datetime('now')`),UTC 但不带时区标记。
+            //   Date.parse 会按**本机时区**解析,误差 = 主机偏移(生产 hub 在 UTC+8
+            //   时这个诊断数字整整偏 8 小时)。走 parseHubTimestamp 显式按 UTC 解。
+            const t = parseHubTimestamp(sess?.last_seen_at);
+            if (t !== null) 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,
           }) }] };
         }
@@ -3679,6 +4031,38 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     return row?.daemon_node_id ?? null;
   };
 
+  /**
+   * 为什么这里要分两种「解析不到 daemon」(#196 / app 仓)。
+   *
+   * `resolveDaemonForChild` 对两件完全不同的事都返回 `null`:
+   *   ① id 不以 `node_` 开头 —— 这个节点**根本不是 daemon 创建的**,
+   *      是有人在某台机器上直接 `anet node start` 起来的。hub 上没有任何
+   *      daemon 可以代它执行停止,**这条路径对它在概念上就不成立**。
+   *   ② id 以 `node_` 开头,但 `node_create_requests` 里查不到那一行 ——
+   *      它可能确实是 daemon 建的,只是记录缺失,这时「显式传 daemon_node_id」
+   *      是一条真的走得通的路。
+   *
+   * 🔴 原先两种情况打印同一句 `pass daemon_node_id explicitly`。对 ① 来说
+   *    **这句建议的前提是假的** —— 没有 daemon 可传,用户按它做只会走进死路。
+   *    2026-08-28 对生产 hub 实测:218 个节点里 **207 个**是 ① 这种。
+   *
+   * 信息在源头就存在(那个 `startsWith("node_")` 判断),只是被丢在了返回值里。
+   */
+  const explainUnresolvableDaemon = (child_node_id: string) =>
+    child_node_id.startsWith("node_")
+      ? {
+          ok: false, error: "daemon_not_resolvable",
+          message: "no node_create_requests row found for this child_node_id; pass daemon_node_id explicitly",
+        }
+      : {
+          ok: false, error: "not_daemon_managed",
+          message:
+            `node ${child_node_id} was not created by a daemon (it was started by hand with ` +
+            `\`anet node start\` on some machine), so no daemon on the Hub can stop it. ` +
+            `Run \`anet node stop <alias>\` on that machine instead. ` +
+            `Daemon-created children have ids beginning with \`node_\`; this one does not.`,
+        };
+
   const dispatchStopOrDelete = (args: DispatchArgs, clientNetId?: string | null) => {
     // §4.1 — SEC-1 trust-root join: resolve target node row WITHIN the
     // caller's scope. resolveReadScope returns 'denied' if the caller
@@ -3968,10 +4352,8 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       const child_node_id = idArg.node_id;
       const resolved = daemon_node_id ?? resolveDaemonForChild(child_node_id);
       if (!resolved) {
-        return { content: [{ type: "text" as const, text: JSON.stringify({
-          ok: false, error: "daemon_not_resolvable",
-          message: "no node_create_requests row found for this child_node_id; pass daemon_node_id explicitly",
-        }) }] };
+        return { content: [{ type: "text" as const,
+          text: JSON.stringify(explainUnresolvableDaemon(child_node_id)) }] };
       }
       const r = dispatchStopOrDelete(
         { action: "stop", child_node_id, daemon_node_id: resolved, force: force ?? false,
@@ -4000,10 +4382,8 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       const child_node_id = idArg.node_id;
       const resolved = daemon_node_id ?? resolveDaemonForChild(child_node_id);
       if (!resolved) {
-        return { content: [{ type: "text" as const, text: JSON.stringify({
-          ok: false, error: "daemon_not_resolvable",
-          message: "no node_create_requests row found for this child_node_id; pass daemon_node_id explicitly",
-        }) }] };
+        return { content: [{ type: "text" as const,
+          text: JSON.stringify(explainUnresolvableDaemon(child_node_id)) }] };
       }
       const r = dispatchStopOrDelete(
         { action: "delete", child_node_id, daemon_node_id: resolved, force: force ?? false,

package/src/uploads-http.test.ts

@@ -24,6 +24,10 @@ let server: any;
 let userToken = "";
 let userNetworkId = "";
 
+// 30s 而不是 bun 默认的 5s:这个 hook 跑 register()(KDF)+bootServer(),
+// 本机空载基线 ~620ms,而 2026-08-17 与 2026-08-31 两次 CI 上它被 5s 上限打死
+// (0 pass / 1 fail / Ran 1 test —— 见 #928、#1627)。5247ms 是**被截断的下界**,
+// 不是测量值,所以余量按基线的 ~48x 取,而不是按那个数取。
 beforeAll(async () => {
   // Bootstrap a real admin + token on the temp DB so the server can
   // resolve it via requireAuth (we don't want to short-circuit auth —
@@ -58,7 +62,7 @@ beforeAll(async () => {
   BASE = `http://127.0.0.1:${server.port}`;
   // Tiny settle so the listener is ready.
   await new Promise((r) => setTimeout(r, 100));
-});
+}, 30_000);
 
 afterAll(() => {
   try { server?.stop?.(true); } catch {}