@sleep2agi/commhub-server 0.9.0-preview.0 → 0.9.0-preview.100

package/src/node-files-transport.test.ts

@@ -0,0 +1,344 @@
+// Project folder view — list_node_files / read_node_file ride the rules-file
+// queue + doorbell (ops files_list / file_read).
+//
+// Hub-side contract verified here:
+//   1. report_status { files_capable: true } is sticky and set only by the
+//      session's own node token (bound or legacy-unbound, same rule as skills).
+//   2. Both tools reach a session with no nodes row by alias; the pulled
+//      request carries the normalized RELATIVE path; results come back through
+//      get_rules_file_result.
+//   3. Absolute paths, `..`, `~`, drive letters, backslashes and NUL are refused
+//      before any request row exists (the node re-checks; this is the first wall).
+//   4. A node token may not enqueue a files op (it would read another node's
+//      disk), and only the token that asked may read a files result.
+//   5. A token bound to node A never pulls or acks node B's files request; an
+//      unbound legacy token falls back to its alias exactly as it does for skills.
+//   6. Its own single-flight lane; rules-capable-only sessions are refused.
+//   7. Files acks may carry up to 1 MiB (escaped JSON of a 256 KiB file); rules
+//      acks keep their 256 KiB cap.
+//
+// 跑法：cd server && COMMHUB_DB=/tmp/files-transport.db bun test src/node-files-transport.test.ts
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { db } from "./db.js";
+import { registerTools } from "./tools.js";
+
+const NET = "net_files_session";
+const OTHER_NET = "net_files_session_other";
+const USER = "u_files_session_owner";
+const SESSION_ALIAS = "files-session-cc";
+const SESSION_RESUME = "cc-files-session-1";
+const PEER_ALIAS = "files-session-peer";
+const NODE_A = "files-node-a";
+const NODE_B = "files-node-b";
+const NODE_A_ID = "node_files_a";
+const NODE_B_ID = "node_files_b";
+const LEGACY_ALIAS = "files-node-legacy";
+const LEGACY_ID = "node_files_legacy";
+const T_SESSION = "tok_files_session_cc";
+const T_PEER = "tok_files_session_peer";
+const T_OTHER_NET_SAME_ALIAS = "tok_files_session_other_net";
+const T_A = "tok_files_node_a";
+const T_B = "tok_files_node_b";
+const T_LEGACY = "tok_files_node_legacy";
+
+function cleanup() {
+  for (const net of [NET, OTHER_NET]) {
+    try { db.run("DELETE FROM node_rules_requests WHERE network_id = ?1", [net]); } catch {}
+    try { db.run("DELETE FROM rename_txn WHERE network_id = ?1", [net]); } catch {}
+    try { db.run("DELETE FROM sessions 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]); } catch {}
+}
+
+function seedWorld() {
+  db.run(`INSERT INTO users (user_id, username, password_hash, role, created_at) VALUES (?1, ?2, 'x', 'user', datetime('now'))`, [USER, USER]);
+  for (const net of [NET, OTHER_NET]) {
+    db.run(`INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?2, ?3, datetime('now'))`, [net, net, USER]);
+    db.run(`INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, 'owner', datetime('now'))`, [USER, net]);
+  }
+  const tok = (id: string, net: string, alias: string, bound: string | null = null) => db.run(
+    `INSERT INTO api_tokens (token_id, user_id, network_id, scope, name, token_hash, expires_at, revoked_at, bound_node_id) VALUES (?1, ?2, ?3, 'network', ?4, ?5, NULL, NULL, ?6)`,
+    [id, USER, net, `node:${alias}`, `hash_${id}`, bound],
+  );
+  const node = (id: string, alias: string) => db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, created_at, updated_at) VALUES (?1, ?2, ?3, ?4, datetime('now'), datetime('now'))`,
+    [id, alias, alias, NET],
+  );
+  node(NODE_A_ID, NODE_A);
+  node(NODE_B_ID, NODE_B);
+  node(LEGACY_ID, LEGACY_ALIAS);
+  tok(T_SESSION, NET, SESSION_ALIAS);
+  tok(T_PEER, NET, PEER_ALIAS);
+  tok(T_OTHER_NET_SAME_ALIAS, OTHER_NET, SESSION_ALIAS);
+  tok(T_A, NET, NODE_A, NODE_A_ID);
+  tok(T_B, NET, NODE_B, NODE_B_ID);
+  tok(T_LEGACY, NET, LEGACY_ALIAS, null);
+}
+
+type Identity = { net: string; alias: string; isNetworkToken: boolean; tokenId: string };
+const asUser: Identity = { net: NET, alias: USER, isNetworkToken: false, tokenId: "tok_files_session_user" };
+const asUserOtherLogin: Identity = { net: NET, alias: USER, isNetworkToken: false, tokenId: "tok_files_session_user_other_login" };
+const asSession: Identity = { net: NET, alias: SESSION_ALIAS, isNetworkToken: true, tokenId: T_SESSION };
+const asPeer: Identity = { net: NET, alias: PEER_ALIAS, isNetworkToken: true, tokenId: T_PEER };
+const asOtherNetSameAlias: Identity = { net: OTHER_NET, alias: SESSION_ALIAS, isNetworkToken: true, tokenId: T_OTHER_NET_SAME_ALIAS };
+const asA: Identity = { net: NET, alias: NODE_A, isNetworkToken: true, tokenId: T_A };
+const asB: Identity = { net: NET, alias: NODE_B, isNetworkToken: true, tokenId: T_B };
+const asLegacy: Identity = { net: NET, alias: LEGACY_ALIAS, isNetworkToken: true, tokenId: T_LEGACY };
+
+async function connect(id: Identity) {
+  const server = new McpServer({ name: "files-session-test", version: "1" });
+  registerTools(server, undefined, id.net, USER, id.alias, id.isNetworkToken, id.tokenId);
+  const client = new Client({ name: "files-session-client", version: "1" });
+  const [ct, st] = InMemoryTransport.createLinkedPair();
+  await server.connect(st);
+  await client.connect(ct);
+  const call = async (name: string, args: Record<string, unknown>) => {
+    const r: any = await client.callTool({ name, arguments: args });
+    const first = r.content?.[0];
+    if (!first || first.type !== "text") throw new Error(`no text result from ${name}: ${JSON.stringify(r).slice(0, 300)}`);
+    try { return JSON.parse(first.text); } catch { return { raw: first.text, isError: r.isError === true }; }
+  };
+  const close = async () => { await client.close(); await server.close(); };
+  return { call, close };
+}
+
+const capable = (alias: string, net = NET) =>
+  db.get<{ c: number }>("SELECT files_capable AS c FROM sessions WHERE alias = ?1 AND network_id = ?2", alias, net)?.c;
+const rowCount = () => db.get<{ n: number }>("SELECT COUNT(*) AS n FROM node_rules_requests WHERE network_id = ?1", NET)!.n;
+
+async function report(id: Identity, alias: string, resume: string, flags: Record<string, true>) {
+  const c = await connect(id);
+  try { return await c.call("report_status", { resume_id: resume, alias, status: "idle", agent: "claude-code", ...flags }); }
+  finally { await c.close(); }
+}
+const ALL_FLAGS = { rules_file_capable: true, skills_capable: true, files_capable: true } as const;
+
+beforeEach(() => { cleanup(); seedWorld(); });
+afterAll(cleanup);
+
+describe("files_capable is set only by the session's own node token", () => {
+  test("own token sets it; a later report without it does not clear it; a peer cannot set it", async () => {
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, ALL_FLAGS);
+    expect(capable(SESSION_ALIAS)).toBe(1);
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, {});
+    expect(capable(SESSION_ALIAS)).toBe(1);
+    const r = await report(asPeer, SESSION_ALIAS, SESSION_RESUME, ALL_FLAGS);
+    expect(r).toMatchObject({ ok: false });
+    // A user login cannot set it either.
+    await report(asUser, PEER_ALIAS, "cc-files-user-report", ALL_FLAGS);
+    expect(capable(PEER_ALIAS) ?? 0).toBe(0);
+  }, 20_000);
+
+  test("a stale process whose report is rewritten to a renamed alias does not grant that alias the flag", async () => {
+    const NEW_ALIAS = "files-session-renamed";
+    db.run(
+      `INSERT INTO rename_txn (txn_id, network_id, old_alias, new_alias, status, committed_at) VALUES ('txn_files_rename', ?1, ?2, ?3, 'committed', datetime('now'))`,
+      [NET, PEER_ALIAS, NEW_ALIAS],
+    );
+    // Token still carries the old alias; the hub rewrites the report to NEW_ALIAS.
+    const r = await report(asPeer, PEER_ALIAS, "cc-files-renamed", ALL_FLAGS);
+    expect(r.ok).toBe(true);
+    expect(db.get<{ n: number }>("SELECT COUNT(*) AS n FROM sessions WHERE alias = ?1 AND network_id = ?2", NEW_ALIAS, NET)!.n).toBe(1);
+    expect(capable(NEW_ALIAS)).toBe(0);
+  }, 20_000);
+});
+
+describe("list / read by alias reach a session with no nodes row", () => {
+  test("list: pulled request carries the normalized relative path; result comes back", async () => {
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, ALL_FLAGS);
+    const u = await connect(asUser);
+    const s = await connect(asSession);
+    try {
+      const enq = await u.call("list_node_files", { alias: SESSION_ALIAS, path: "./src//lib/" });
+      expect(enq).toMatchObject({ ok: true, op: "files_list" });
+      const pulled = await s.call("get_rules_file_request", {});
+      expect(pulled.request).toEqual({ request_id: enq.request_id, op: "files_list", content: "src/lib" });
+      const payload = JSON.stringify({ path: "src/lib", entries: [{ name: "a.ts", type: "file", size: 3, mtime: 1 }], truncated: false, total: 1 });
+      expect(await s.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", file_name: "files", exists: true, content: payload })).toMatchObject({ ok: true, status: "done" });
+      expect(await u.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ ok: true, op: "files_list", status: "done", content: payload });
+    } finally { await u.close(); await s.close(); }
+  }, 20_000);
+
+  test("list with no path targets the root (empty content)", async () => {
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, ALL_FLAGS);
+    const u = await connect(asUser);
+    const s = await connect(asSession);
+    try {
+      const enq = await u.call("list_node_files", { alias: SESSION_ALIAS });
+      expect((await s.call("get_rules_file_request", {})).request).toEqual({ request_id: enq.request_id, op: "files_list", content: "" });
+    } finally { await u.close(); await s.close(); }
+  }, 20_000);
+
+  test("read round trip", async () => {
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, ALL_FLAGS);
+    const u = await connect(asUser);
+    const s = await connect(asSession);
+    try {
+      const enq = await u.call("read_node_file", { alias: SESSION_ALIAS, path: "docs/README.md" });
+      expect(enq).toMatchObject({ ok: true, op: "file_read" });
+      expect((await s.call("get_rules_file_request", {})).request).toEqual({ request_id: enq.request_id, op: "file_read", content: "docs/README.md" });
+      const payload = JSON.stringify({ path: "docs/README.md", name: "README.md", kind: "text", size: 6, content: "# hi\n" });
+      await s.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", file_name: "README.md", exists: true, content: payload });
+      expect(await u.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ status: "done", content: payload });
+    } finally { await u.close(); await s.close(); }
+  }, 20_000);
+});
+
+describe("path validation happens before any row is written", () => {
+  test("absolute, .., ~, drive letters, backslashes, NUL, and an empty read path are refused", async () => {
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, ALL_FLAGS);
+    const u = await connect(asUser);
+    try {
+      const bad = ["/etc/passwd", "../outside", "a/../../b", "src/..", "~/.ssh/id_rsa", "C:/Windows", "a\\b", "..\\x", "a\u0000b", "x".repeat(1025)];
+      for (const path of bad) {
+        // Over-long paths are stopped by the zod schema (an MCP input error); the rest by invalid_path.
+        const r = await u.call("read_node_file", { alias: SESSION_ALIAS, path });
+        expect(r.ok).not.toBe(true);
+        if (path.length <= 1024) expect(r).toMatchObject({ ok: false, error: "invalid_path" });
+        const l = await u.call("list_node_files", { alias: SESSION_ALIAS, path });
+        expect(l.ok).not.toBe(true);
+      }
+      expect(await u.call("read_node_file", { alias: SESSION_ALIAS, path: "/" })).toMatchObject({ ok: false, error: "invalid_path" });
+      expect(await u.call("read_node_file", { alias: SESSION_ALIAS, path: "./" })).toMatchObject({ ok: false, error: "invalid_path" });
+      expect(rowCount()).toBe(0);
+    } finally { await u.close(); }
+  }, 20_000);
+});
+
+describe("who may ask, and who may read the answer", () => {
+  test("a node token cannot enqueue a files op on another node (or itself)", async () => {
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, ALL_FLAGS);
+    const a = await connect(asA);
+    try {
+      expect(await a.call("list_node_files", { alias: SESSION_ALIAS })).toMatchObject({ ok: false, error: "node_token_cannot_browse_files" });
+      expect(await a.call("read_node_file", { node_id: NODE_B_ID, path: ".env" })).toMatchObject({ ok: false, error: "node_token_cannot_browse_files" });
+      expect(await a.call("list_node_files", { node_id: NODE_A_ID })).toMatchObject({ ok: false, error: "node_token_cannot_browse_files" });
+      expect(rowCount()).toBe(0);
+    } finally { await a.close(); }
+  }, 20_000);
+
+  test("only the token that asked can read a files result; node tokens never can", async () => {
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, ALL_FLAGS);
+    const u = await connect(asUser);
+    const other = await connect(asUserOtherLogin);
+    const s = await connect(asSession);
+    const a = await connect(asA);
+    try {
+      const enq = await u.call("read_node_file", { alias: SESSION_ALIAS, path: "notes.txt" });
+      await s.call("get_rules_file_request", {});
+      await s.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", content: JSON.stringify({ path: "notes.txt", kind: "text", content: "x" }) });
+      expect(await u.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ ok: true, status: "done" });
+      expect(await other.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ ok: false, error: "request_not_found" });
+      expect(await a.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ ok: false, error: "request_not_found" });
+      // The serving session itself cannot read the stored result back through the client tool either.
+      expect(await s.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ ok: false, error: "request_not_found" });
+    } finally { await u.close(); await other.close(); await s.close(); await a.close(); }
+  }, 20_000);
+
+  test("rules/skills results stay readable by any writer of the network (unchanged)", async () => {
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, ALL_FLAGS);
+    const u = await connect(asUser);
+    const other = await connect(asUserOtherLogin);
+    try {
+      const enq = await u.call("list_node_skills", { alias: SESSION_ALIAS });
+      expect(await other.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ ok: true, status: "pending" });
+    } finally { await u.close(); await other.close(); }
+  }, 20_000);
+});
+
+describe("a token bound to node A cannot touch node B's files request", () => {
+  test("B's request: A pulls nothing, A's ack is ignored, B pulls and acks it", async () => {
+    const u = await connect(asUser);
+    const a = await connect(asA);
+    const b = await connect(asB);
+    try {
+      const enq = await u.call("read_node_file", { node_id: NODE_B_ID, path: "secret-plan.md" });
+      expect(enq).toMatchObject({ ok: true });
+      expect((await a.call("get_rules_file_request", {})).request).toBeNull();
+      expect(await a.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", content: "{\"forged\":true}" })).toMatchObject({ ok: true, ignored: "unknown_or_foreign_request" });
+      expect(await u.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ status: "pending" });
+      expect((await b.call("get_rules_file_request", {})).request).toEqual({ request_id: enq.request_id, op: "file_read", content: "secret-plan.md" });
+      expect(await b.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", content: "{}" })).toMatchObject({ ok: true, status: "done" });
+    } finally { await u.close(); await a.close(); await b.close(); }
+  }, 20_000);
+
+  test("same alias in another network neither pulls nor acks; a peer's ack is ignored", async () => {
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, ALL_FLAGS);
+    const u = await connect(asUser);
+    const other = await connect(asOtherNetSameAlias);
+    const peer = await connect(asPeer);
+    try {
+      const enq = await u.call("list_node_files", { alias: SESSION_ALIAS });
+      expect((await other.call("get_rules_file_request", {})).request).toBeNull();
+      expect(await other.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", content: "{}" })).toMatchObject({ ignored: "unknown_or_foreign_request" });
+      expect(await peer.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", content: "{}" })).toMatchObject({ ignored: "unknown_or_foreign_request" });
+      expect(await u.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ status: "pending" });
+    } finally { await u.close(); await other.close(); await peer.close(); }
+  }, 20_000);
+
+  test("an unbound legacy token gets what skills gives it: alias fallback pull + ack, and it can set its own flag", async () => {
+    const u = await connect(asUser);
+    const legacy = await connect(asLegacy);
+    try {
+      await report(asLegacy, LEGACY_ALIAS, `sdk-${LEGACY_ID}`, ALL_FLAGS);
+      expect(capable(LEGACY_ALIAS)).toBe(1);
+      const skills = await u.call("list_node_skills", { node_id: LEGACY_ID });
+      const files = await u.call("list_node_files", { node_id: LEGACY_ID, path: "src" });
+      expect(skills).toMatchObject({ ok: true });
+      expect(files).toMatchObject({ ok: true });
+      const first = (await legacy.call("get_rules_file_request", {})).request;
+      const second = (await legacy.call("get_rules_file_request", {})).request;
+      expect([first.request_id, second.request_id].sort()).toEqual([skills.request_id, files.request_id].sort());
+      expect(await legacy.call("ack_rules_file_request", { request_id: files.request_id, status: "done", content: "{}" })).toMatchObject({ ok: true, status: "done" });
+      expect(await legacy.call("ack_rules_file_request", { request_id: skills.request_id, status: "done", content: "{}" })).toMatchObject({ ok: true, status: "done" });
+    } finally { await u.close(); await legacy.close(); }
+  }, 20_000);
+});
+
+describe("lanes, capability gate and ack size", () => {
+  test("files has its own single-flight lane", async () => {
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, ALL_FLAGS);
+    const u = await connect(asUser);
+    try {
+      expect(await u.call("read_node_rules_file", { alias: SESSION_ALIAS })).toMatchObject({ ok: true });
+      expect(await u.call("list_node_skills", { alias: SESSION_ALIAS })).toMatchObject({ ok: true });
+      const list = await u.call("list_node_files", { alias: SESSION_ALIAS });
+      expect(list).toMatchObject({ ok: true });
+      expect(await u.call("read_node_file", { alias: SESSION_ALIAS, path: "a.txt" })).toMatchObject({ ok: false, error: "request_in_flight", existing_request_id: list.request_id });
+    } finally { await u.close(); }
+  }, 20_000);
+
+  test("rules+skills capable but not files capable → files_target_not_found, no row", async () => {
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, { rules_file_capable: true, skills_capable: true });
+    const u = await connect(asUser);
+    try {
+      expect(await u.call("list_node_files", { alias: SESSION_ALIAS })).toMatchObject({ ok: false, error: "files_target_not_found" });
+      expect(rowCount()).toBe(0);
+    } finally { await u.close(); }
+  }, 20_000);
+
+  test("a files ack may carry up to 1 MiB; a rules ack keeps its 256 KiB cap", async () => {
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, ALL_FLAGS);
+    const u = await connect(asUser);
+    const s = await connect(asSession);
+    try {
+      const big = JSON.stringify({ path: "big.txt", kind: "text", content: "\n".repeat(256 * 1024) });
+      expect(big.length).toBeGreaterThan(256 * 1024);
+      const f = await u.call("read_node_file", { alias: SESSION_ALIAS, path: "big.txt" });
+      const r = await u.call("read_node_rules_file", { alias: SESSION_ALIAS });
+      await s.call("get_rules_file_request", {});
+      await s.call("get_rules_file_request", {});
+      expect(await s.call("ack_rules_file_request", { request_id: f.request_id, status: "done", content: big })).toMatchObject({ ok: true, status: "done" });
+      expect(await s.call("ack_rules_file_request", { request_id: r.request_id, status: "done", content: "x".repeat(256 * 1024 + 1) })).toMatchObject({ ok: false, error: "content_too_large" });
+      const tooBig = await s.call("ack_rules_file_request", { request_id: r.request_id, status: "done", content: "x".repeat(1024 * 1024 + 1) });
+      expect(tooBig.ok).not.toBe(true);
+    } finally { await u.close(); await s.close(); }
+  }, 20_000);
+});

package/src/node-health-dispatch-http.test.ts

@@ -0,0 +1,279 @@
+// #460(#448 子项)—— 降级节点拒收新任务。
+//
+// 钉住:
+//   1. 新鲜健康报告说某层坏了(app_server.ok=false / tui.ok=false / model_auth revoked|expired)
+//      → REST /api/task 409、MCP send_task / retry_task / reassign_task 返回 node_degraded,带层、原因、修法;
+//      定时任务的这一次 run 记 failed + error_code=node_degraded,不建任务行。
+//   2. 不知道 = 放行:没有报告(老 agent-node)、报告过期(> TTL)、各层都 ok、某层没报 —— 与改动前逐字相同的成功路径。
+//   3. 逃生口 force=true 只对用户令牌生效;节点令牌带 force 照样被拒(不让 agent 绕过对另一个 agent 的健康判断)。
+//   4. 老客户端请求形状(不带 force)在健康 / 未知节点上完全照旧 —— 兼容回放。
+//
+// 跑法:cd server && COMMHUB_DB=/tmp/x.db bun test src/node-health-dispatch-http.test.ts
+//       PG:COMMHUB_TEST_PG_URL=… COMMHUB_PG_EXPERIMENTAL=1(tests/test2123-hub-postgres-ladder 里注册)
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createNetworkTokenForNode, register } from "./auth.js";
+import { db } from "./db.js";
+import { registerTools } from "./tools.js";
+import { clearNodeHealthStore, NODE_HEALTH_TTL_MS, recordNodeHealth } from "./node-health-store.js";
+import { degradedLayers } from "./node-health-guard.js";
+import { runDueScheduledTasks } from "./scheduled-tasks.js";
+
+const dir = mkdtempSync(join(tmpdir(), "anet-health-dispatch-"));
+const activeDbPath = process.env.COMMHUB_DB ?? (process.env.COMMHUB_TEST_PG_URL ? "postgres" : undefined);
+if (!activeDbPath) throw new Error("node-health-dispatch requires COMMHUB_DB (or COMMHUB_TEST_PG_URL) before module import");
+
+let server: any;
+let base = "";
+let ownerToken = "", ownerId = "", networkId = "";
+let peerNodeToken = "", peerNodeTokenId = "";
+const stamp = Date.now();
+const TARGET = `hd-target-${stamp}`;
+const TARGET_NODE = `n_hd_target_${stamp}`;
+const PEER = `hd-peer-${stamp}`;
+const PEER_NODE = `n_hd_peer_${stamp}`;
+let seq = 0;
+const text = (what: string) => `${what} #${++seq}`; // distinct content: the 5-minute dedup must not interfere
+
+async function api(token: string, path: string, init?: RequestInit) {
+  const res = await fetch(`${base}${path}`, {
+    ...init,
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...(init?.headers || {}) },
+  });
+  return { status: res.status, body: await res.json() as any };
+}
+const postTask = (token: string, extra: Record<string, unknown> = {}) =>
+  api(token, "/api/task", { method: "POST", body: JSON.stringify({ alias: TARGET, task: text("rest"), network_id: networkId, ...extra }) });
+
+async function mcpAs(identity: { net: string | null; user: string; alias: string; isNetworkToken: boolean; tokenId: string }) {
+  const s = new McpServer({ name: "health-dispatch", version: "1" });
+  registerTools(s, undefined, identity.net, identity.user, identity.alias, identity.isNetworkToken, identity.tokenId);
+  const client = new Client({ name: "health-dispatch-client", version: "1" });
+  const [ct, st] = InMemoryTransport.createLinkedPair();
+  await s.connect(st);
+  await client.connect(ct);
+  const call = async (name: string, args: Record<string, unknown>) => {
+    const r: any = await client.callTool({ name, arguments: args });
+    const raw = r.content?.[0]?.text ?? "null";
+    try { return JSON.parse(raw); } catch { return { raw }; }
+  };
+  return { call, close: async () => { await client.close(); await s.close(); } };
+}
+
+const DOWN_APP = { bridge: "ok" as const, app_server: { ok: false, rtt_ms: null, last_error: "connect ECONNREFUSED 127.0.0.1:4500" }, model_auth: "ok" as const };
+const HEALTHY = { bridge: "ok" as const, app_server: { ok: true, rtt_ms: 3, last_error: null }, tui: { ok: true, reason: "running" }, model_auth: "ok" as const };
+const setHealth = (h: any, at?: number) => recordNodeHealth(networkId, TARGET, h, at);
+const taskCount = () => db.get<{ n: number }>("SELECT COUNT(*) AS n FROM tasks WHERE to_name = ?1 AND network_id = ?2", TARGET, networkId)!.n;
+
+beforeAll(async () => {
+  process.env.COMMHUB_UPLOADS_DIR = join(dir, "uploads");
+  process.env.HOST = "127.0.0.1";
+  const owner = register(`hd_owner_${stamp}`, "HealthDispatchOwner123!", undefined, "seed");
+  ownerToken = owner.token!; ownerId = owner.user!.user_id; networkId = owner.network_id!;
+  for (const [nodeId, alias] of [[TARGET_NODE, TARGET], [PEER_NODE, PEER]]) {
+    db.run(`INSERT INTO nodes (node_id, node_name, alias, runtime, network_id, owner_user_id) VALUES (?1, ?2, ?2, 'codex-app-server', ?3, ?4)`, [nodeId, alias, networkId, ownerId]);
+    db.run(`INSERT INTO sessions (resume_id, alias, status, node_id, network_id) VALUES (?1, ?2, 'idle', ?3, ?4)`, [`r_${nodeId}`, alias, nodeId, networkId]);
+  }
+  const minted = createNetworkTokenForNode(ownerId, networkId, PEER, PEER_NODE);
+  peerNodeToken = minted.token!; peerNodeTokenId = minted.token_id!;
+  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(() => { server?.stop?.(true); clearNodeHealthStore(); });
+beforeEach(() => clearNodeHealthStore());
+
+describe("#460 which layers count as degraded", () => {
+  test("each failing layer is named; ok / missing layers are not", () => {
+    expect(degradedLayers(null)).toEqual([]);
+    expect(degradedLayers(HEALTHY)).toEqual([]);
+    expect(degradedLayers({ bridge: "ok", model_auth: "unknown" })).toEqual([]);
+    expect(degradedLayers(DOWN_APP).map(l => [l.layer, l.label])).toEqual([["app_server", "App Server 断开"]]);
+    expect(degradedLayers({ tui: { ok: false, reason: "sleep-placeholder" } }).map(l => [l.layer, l.reason, l.label])).toEqual([["tui", "sleep-placeholder", "TUI 被占位(sleep)"]]);
+    expect(degradedLayers({ model_auth: "revoked" }).map(l => l.label)).toEqual(["需要重新登录"]);
+    expect(degradedLayers({ model_auth: "expired" }).map(l => l.label)).toEqual(["登录已过期"]);
+    // 修法只指向本节点重新登录,不教人拷别人的凭据
+    expect(degradedLayers({ model_auth: "revoked" })[0].hint).toContain("不要拷别的节点的 auth.json");
+  });
+});
+
+describe("#460 REST /api/task", () => {
+  test("unknown health (old agent-node) → dispatched exactly as before", async () => {
+    const before = taskCount();
+    const r = await postTask(ownerToken);
+    expect(r.status).toBe(200);
+    expect(r.body.ok).toBe(true);
+    expect(taskCount()).toBe(before + 1);
+  });
+
+  test("healthy report → dispatched", async () => {
+    setHealth(HEALTHY);
+    expect((await postTask(ownerToken)).status).toBe(200);
+  });
+
+  test("App Server down → 409 node_degraded with layer, reason and hint; no task row", async () => {
+    setHealth(DOWN_APP);
+    const before = taskCount();
+    const r = await postTask(ownerToken);
+    expect(r.status).toBe(409);
+    expect(r.body.ok).toBe(false);
+    expect(r.body.error).toBe("node_degraded");
+    expect(r.body.alias).toBe(TARGET);
+    expect(r.body.layers.map((l: any) => l.layer)).toEqual(["app_server"]);
+    expect(r.body.layers[0].reason).toContain("ECONNREFUSED");
+    expect(r.body.message).toContain("App Server 断开");
+    expect(r.body.hint).toContain("force=true");
+    expect(r.body.force_allowed).toBe(true);
+    expect(typeof r.body.health_observed_ms_ago).toBe("number");
+    expect(taskCount()).toBe(before);
+  });
+
+  test("TUI gone and login revoked are refused too, all layers listed", async () => {
+    setHealth({ bridge: "ok", app_server: { ok: true, rtt_ms: 2, last_error: null }, tui: { ok: false, reason: "session-missing" }, model_auth: "revoked" });
+    const r = await postTask(ownerToken);
+    expect(r.status).toBe(409);
+    expect(r.body.layers.map((l: any) => l.layer)).toEqual(["tui", "model_auth"]);
+  });
+
+  test("expired login alone is refused", async () => {
+    setHealth({ bridge: "ok", model_auth: "expired" });
+    expect((await postTask(ownerToken)).body.error).toBe("node_degraded");
+  });
+
+  test("stale report (older than the TTL) = unknown → dispatched", async () => {
+    setHealth(DOWN_APP, Date.now() - NODE_HEALTH_TTL_MS - 1_000);
+    expect((await postTask(ownerToken)).status).toBe(200);
+  });
+
+  test("owner escape hatch: force=true with a user token dispatches", async () => {
+    setHealth(DOWN_APP);
+    const before = taskCount();
+    const r = await postTask(ownerToken, { force: true });
+    expect(r.status).toBe(200);
+    expect(taskCount()).toBe(before + 1);
+  });
+
+  test("a node token cannot force past another node's health", async () => {
+    setHealth(DOWN_APP);
+    const r = await api(peerNodeToken, "/api/task", { method: "POST", body: JSON.stringify({ alias: TARGET, task: text("node-force"), force: true }) });
+    expect(r.status).toBe(409);
+    expect(r.body.error).toBe("node_degraded");
+    expect(r.body.force_allowed).toBe(false);
+    expect(r.body.hint).not.toContain("force=true");
+  });
+
+  test("old-client request shapes are untouched on a healthy node (compat replay)", async () => {
+    setHealth(HEALTHY);
+    // the app's send (meta + client_request_id), a plain anet send, and a parent-linked dispatch
+    const shapes = [
+      { alias: TARGET, task: text("app"), network_id: networkId, priority: "normal", meta: { client_request_id: `cr_${stamp}_${seq}` } },
+      { alias: TARGET, task: text("anet"), network_id: networkId },
+      { alias: TARGET, task: text("ttl"), network_id: networkId, priority: "high", ttl_seconds: 600 },
+    ];
+    for (const shape of shapes) {
+      const r = await api(ownerToken, "/api/task", { method: "POST", body: JSON.stringify(shape) });
+      expect(r.status).toBe(200);
+      expect(r.body.ok).toBe(true);
+    }
+  });
+});
+
+describe("#460 MCP send_task / retry_task / reassign_task", () => {
+  const asOwner = () => ({ net: null, user: ownerId, alias: `hd_owner_${stamp}`, isNetworkToken: false, tokenId: "tok_hd_owner_login" });
+  const asPeerNode = () => ({ net: networkId, user: ownerId, alias: PEER, isNetworkToken: true, tokenId: peerNodeTokenId });
+
+  test("send_task from an agent to a degraded node → node_degraded (no queueing); force ignored for node tokens", async () => {
+    setHealth(DOWN_APP);
+    const peer = await mcpAs(asPeerNode());
+    try {
+      const before = taskCount();
+      const r = await peer.call("send_task", { alias: TARGET, task: text("mcp"), force: true });
+      expect(r.ok).toBe(false);
+      expect(r.error).toBe("node_degraded");
+      expect(r.force_allowed).toBe(false);
+      expect(taskCount()).toBe(before);
+    } finally { await peer.close(); }
+  });
+
+  test("send_task: unknown health → ok; owner force → ok", async () => {
+    const owner = await mcpAs(asOwner());
+    try {
+      expect((await owner.call("send_task", { alias: TARGET, task: text("mcp-unknown"), network_id: networkId })).ok).toBe(true);
+      setHealth({ bridge: "ok", model_auth: "revoked" });
+      expect((await owner.call("send_task", { alias: TARGET, task: text("mcp-refused"), network_id: networkId })).error).toBe("node_degraded");
+      expect((await owner.call("send_task", { alias: TARGET, task: text("mcp-forced"), network_id: networkId, force: true })).ok).toBe(true);
+    } finally { await owner.close(); }
+  });
+
+  test("retry_task and reassign_task onto a degraded node are refused", async () => {
+    const owner = await mcpAs(asOwner());
+    try {
+      const sent = await owner.call("send_task", { alias: PEER, task: text("to-peer"), network_id: networkId });
+      expect(sent.ok).toBe(true);
+      setHealth(DOWN_APP);
+      const re = await owner.call("reassign_task", { task_id: sent.task_id ?? sent.message_id, new_alias: TARGET, network_id: networkId });
+      expect(re.error).toBe("node_degraded");
+      const failed = await owner.call("send_task", { alias: TARGET, task: text("to-fail"), network_id: networkId, force: true });
+      const failedId = failed.task_id ?? failed.message_id;
+      db.run("UPDATE tasks SET status = 'failed' WHERE task_id = ?1", [failedId]);
+      const retry = await owner.call("retry_task", { task_id: failedId, network_id: networkId });
+      expect(retry.error).toBe("node_degraded");
+      clearNodeHealthStore();
+      expect((await owner.call("retry_task", { task_id: failedId, network_id: networkId })).ok).toBe(true);
+    } finally { await owner.close(); }
+  });
+});
+
+describe("#460 scheduled tasks", () => {
+  test("a due run on a degraded node fails with node_degraded and creates no task", async () => {
+    const created = await api(ownerToken, "/api/scheduled-tasks", {
+      method: "POST",
+      body: JSON.stringify({ network_id: networkId, name: `hd-schedule-${stamp}`, target_node_id: TARGET_NODE, task: text("scheduled"), timezone: "UTC", schedule: { type: "interval", every_seconds: 60 } }),
+    });
+    expect(created.status).toBe(201);
+    const scheduleId = created.body.schedule.schedule_id;
+    setHealth({ bridge: "ok", tui: { ok: false, reason: "pane-dead" }, model_auth: "ok" });
+    const before = taskCount();
+    db.run("UPDATE scheduled_tasks SET next_run_at = ?1 WHERE schedule_id = ?2", [new Date(Date.now() - 60_000).toISOString(), scheduleId]);
+    runDueScheduledTasks();
+    const run = db.get<{ status: string; error_code: string | null; error_message: string | null; task_id: string | null }>(
+      "SELECT status, error_code, error_message, task_id FROM scheduled_task_runs WHERE schedule_id = ?1 ORDER BY created_at DESC LIMIT 1", scheduleId);
+    expect(run?.status).toBe("failed");
+    expect(run?.error_code).toBe("node_degraded");
+    expect(run?.error_message).toContain("TUI 已退出");
+    expect(run?.task_id ?? null).toBeNull();
+    expect(taskCount()).toBe(before);
+  });
+});
+
+describe("#460 /api/status carries `degraded` only for degraded nodes", () => {
+  const row = async (light: boolean) => {
+    const r = await api(ownerToken, `/api/status?network_id=${encodeURIComponent(networkId)}${light ? "&light=1" : ""}`);
+    expect(r.status).toBe(200);
+    return r.body.sessions.find((x: any) => x.alias === TARGET);
+  };
+  test("unknown / healthy → no `degraded` key at all (light response bytes unchanged)", async () => {
+    expect("degraded" in (await row(true))).toBe(false);
+    setHealth(HEALTHY);
+    expect("degraded" in (await row(true))).toBe(false);
+    expect("degraded" in (await row(false))).toBe(false);
+  });
+  test("degraded → light and full rows list the failing layers with the app's labels", async () => {
+    setHealth({ bridge: "ok", app_server: { ok: false, rtt_ms: null, last_error: "refused" }, model_auth: "revoked" });
+    const want = [
+      { layer: "app_server", label: "App Server 断开", reason: "refused" },
+      { layer: "model_auth", label: "需要重新登录", reason: "revoked" },
+    ];
+    expect((await row(true)).degraded).toEqual(want);
+    expect((await row(false)).degraded).toEqual(want);
+  });
+  test("stale → no `degraded`", async () => {
+    setHealth(DOWN_APP, Date.now() - NODE_HEALTH_TTL_MS - 1_000);
+    expect("degraded" in (await row(true))).toBe(false);
+  });
+});