@sleep2agi/commhub-server 0.9.0-preview.91 → 0.9.0-preview.92

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.91",
+  "version": "0.9.0-preview.92",
   "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/node-permissions-http.test.ts

@@ -0,0 +1,258 @@
+// RFC-041 第一阶段(#487)—— 节点自己的权限:先记录、后执行。全部经真实 HTTP 入口(bootServer + fetch REST / /mcp / SSE)。
+//
+// 钉住:
+//   1. log(默认):正常模式的节点「本来会被拒」的写照常放行,只按 (节点, 路由, 原因, 小时) 合并记一行。
+//   2. 显式模式不看开关、立刻生效:只读写什么都拒、回复 / 心跳照常;受限只看只改派给它的卡,广播 / 订阅别人的推送都拒。
+//   3. enforce:同一组请求按规则拒(node_permission_denied + reason + hint),含只有人能做的事(human_only)。
+//   4. off:不判也不记(显式模式仍生效)。
+//   5. 改模式:节点主人 / 网络 owner、admin 能;别的成员 403、节点令牌 403、不在网络里 404。
+//   6. 报表:owner/admin 看到过去 7 天每个节点「本来会拦」的计数;成员 / 节点令牌 403。
+//   7. 每个注册的 MCP 工具都归了类(新工具忘了归类会红)。8. 记录有上限、会清理。
+//
+// 跑法:cd server && COMMHUB_DB=/tmp/x.db bun test src/node-permissions-http.test.ts
+//       PG:COMMHUB_TEST_PG_URL=… COMMHUB_PG_EXPERIMENTAL=1(tests/test2123-hub-postgres-ladder 里注册)
+import { afterAll, afterEach, beforeAll, 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 { addNetworkMember, createNetworkTokenForNode, register } from "./auth.js";
+import { replaceTaskGrants } from "./task-access.js";
+import { db } from "./db.js";
+import { NODE_TOOL_CLASS, pruneNodePermissionLog, __resetNodePermissionLogStateForTest } from "./node-permissions.js";
+import { registerTools } from "./tools.js";
+
+const activeDbPath = process.env.COMMHUB_DB ?? (process.env.COMMHUB_TEST_PG_URL ? "postgres" : undefined);
+if (!activeDbPath) throw new Error("node-permissions requires COMMHUB_DB (or COMMHUB_TEST_PG_URL) before module import");
+
+const stamp = Date.now();
+const PW = "NodePerm123!";
+let server: any, base = "", net = "";
+const user: Record<string, { id: string; token: string }> = {};
+const node: Record<string, { id: string; alias: string; token: string; tokenId: string }> = {};
+const card: Record<string, string> = {};
+
+async function call(token: string, method: string, path: string, body?: unknown) {
+  const r = await fetch(`${base}${path}`, {
+    method, headers: { Authorization: `Bearer ${token}`, ...(body === undefined ? {} : { "Content-Type": "application/json" }) },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  const text = await r.text();
+  let json: any = null; try { json = JSON.parse(text); } catch {}
+  return { status: r.status, body: json, text };
+}
+async function mcp(token: string, name: string, args: Record<string, unknown>): Promise<any> {
+  const r = await fetch(`${base}/mcp`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }),
+  });
+  const text = await r.text();
+  const data = text.split("\n").find((l) => l.startsWith("data: "));
+  const msg = JSON.parse(data ? data.slice(6) : text);
+  const inner = msg.result?.content?.[0]?.text;
+  try { return JSON.parse(inner); } catch { return { raw: inner ?? msg }; }
+}
+const sse = async (token: string, path: string) => {
+  const ac = new AbortController();
+  const r = await fetch(`${base}${path}`, { headers: { Authorization: `Bearer ${token}` }, signal: ac.signal });
+  const status = r.status;
+  const body = status === 200 ? null : await r.json().catch(() => null);
+  ac.abort();
+  return { status, body };
+};
+const logRows = (nodeId: string) => db.all<{ route: string; reason: string; hits: number | string }>(
+  "SELECT route, reason, hits FROM node_permission_log WHERE network_id = ?1 AND node_id = ?2 ORDER BY route, reason", net, nodeId);
+const hitsOf = (nodeId: string, route: string, reason: string) =>
+  Number(logRows(nodeId).find((r) => r.route === route && r.reason === reason)?.hits ?? 0);
+const attrsRev = (nodeId: string) => Number(db.get<{ r: number | string | null }>("SELECT attrs_revision AS r FROM nodes WHERE node_id = ?1", nodeId)?.r ?? 0);
+const setMode = (nodeKey: string, mode: string) => db.run("UPDATE nodes SET permission_mode = ?1 WHERE node_id = ?2", [mode, node[nodeKey].id]);
+const newCard = async (name: string, extra: Record<string, unknown> = {}) => {
+  const r = await call(user.boss.token, "POST", "/api/requirements", { name, network_id: net, ...extra });
+  expect(r.status).toBe(201);
+  return r.body.requirement.id as string;
+};
+
+beforeAll(async () => {
+  const boss = register(`np_boss_${stamp}`, PW); net = boss.network_id!; user.boss = { id: boss.user!.user_id, token: boss.token! };
+  for (const k of ["sco", "mem", "out"]) {
+    const u = register(`np_${k}_${stamp}`, PW); user[k] = { id: u.user!.user_id, token: u.token! };
+    if (k !== "out") expect(addNetworkMember(net, user[k].id, "member", user.boss.id, { agentAccess: "all" }).ok).toBe(true);
+  }
+  // sco:只看相关任务的成员(task_access=scoped)—— 他的节点在正常模式下会碰到「主人看不见」的卡。
+  expect(replaceTaskGrants({ networkId: net, userId: user.sco.id, taskAccess: "scoped", actorUserId: user.boss.id }).ok).toBe(true);
+  for (const [key, owner] of [["nN", "boss"], ["nR", "boss"], ["nRO", "boss"], ["nS", "sco"], ["other", "boss"]] as const) {
+    const alias = `${key.toLowerCase()}-${stamp}`, id = `n_np_${key.toLowerCase()}_${stamp}`;
+    const t = createNetworkTokenForNode(user[owner].id, net, alias, id);
+    expect(t.ok).toBe(true);
+    node[key] = { id, alias, token: t.token!, tokenId: t.token_id! };
+    db.run("INSERT INTO sessions (resume_id, alias, status, node_id, network_id) VALUES (?1, ?2, 'idle', ?3, ?4)", [`r_${id}`, alias, id, net]);
+  }
+  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}`;
+  card.assigned = await newCard("assigned to nR", { agent_owner: { kind: "node", id: node.nR.id } });
+  card.child = await newCard("child of assigned", { parent_id: card.assigned });
+  card.boss = await newCard("boss only");
+  card.scoPart = await newCard("sco participates", { participants: [{ kind: "user", id: user.sco.id }] });
+  setMode("nR", "restricted");
+  setMode("nRO", "readonly");
+}, 60_000);
+afterEach(() => { delete process.env.COMMHUB_NODE_PERMISSIONS; });
+afterAll(() => { server?.stop?.(true); });
+
+describe("log (default): never blocks a normal node, records would-be denials", () => {
+  test("a write beyond the owner's visibility goes through and is logged once per hour, hits merged", async () => {
+    const route = "PATCH /api/requirements/:id";
+    const before = hitsOf(node.nS.id, route, "beyond_owner_visibility");
+    expect((await call(node.nS.token, "PATCH", `/api/requirements/${card.boss}`, { description: "via scoped owner's node" })).status).toBe(200);
+    expect((await call(node.nS.token, "PATCH", `/api/requirements/${card.boss}`, { description: "again" })).status).toBe(200);
+    expect(hitsOf(node.nS.id, route, "beyond_owner_visibility")).toBe(before + 2);
+    expect(logRows(node.nS.id).filter((r) => r.route === route).length).toBe(1);
+  });
+
+  test("a list read that includes cards the owner cannot see is returned in full and logged", async () => {
+    const r = await call(node.nS.token, "GET", `/api/requirements?network_id=${net}`);
+    expect(r.status).toBe(200);
+    expect(r.body.requirements.map((x: any) => x.id)).toContain(card.boss);
+    expect(hitsOf(node.nS.id, "GET /api/requirements", "beyond_owner_visibility")).toBeGreaterThan(0);
+  });
+
+  test("human-only actions are logged, not blocked by this layer", async () => {
+    const r = await call(node.nN.token, "PUT", `/api/nodes/${node.other.id}/attrs`, { display_name: "renamed by a node", base_attrs_revision: attrsRev(node.other.id) });
+    expect(r.status).toBe(200);
+    expect(hitsOf(node.nN.id, "PUT /api/nodes/:id/attrs", "human_only")).toBe(1);
+    const p = await mcp(node.nN.token, "projects_create", { network_id: net, name: `p-${stamp}` });
+    expect(p.error).not.toBe("node_permission_denied");
+    expect(hitsOf(node.nN.id, "mcp:projects_create", "human_only")).toBe(1);
+  });
+
+  test("an all-access owner's normal node does its usual work with zero log rows", async () => {
+    expect((await mcp(node.nN.token, "send_task", { alias: node.other.alias, task: "hello" })).ok).toBe(true);
+    expect((await call(node.nN.token, "PATCH", `/api/requirements/${card.boss}`, { column: "doing" })).status).toBe(200);
+    expect(logRows(node.nN.id).filter((r) => r.reason !== "human_only")).toEqual([]);
+  });
+});
+
+describe("explicit modes are enforced immediately (even under log)", () => {
+  test("read-only: writes and dispatch refused with a hint; heartbeat, replies and reads still work", async () => {
+    const w = await call(node.nRO.token, "PATCH", `/api/requirements/${card.boss}`, { description: "nope" });
+    expect(w.status).toBe(403);
+    expect(w.body).toMatchObject({ error: "node_permission_denied", reason: "mode_readonly" });
+    expect(w.body.hint).toContain("read-only");
+    expect((await mcp(node.nRO.token, "send_task", { alias: node.other.alias, task: "x" })).reason).toBe("mode_readonly");
+    expect((await call(node.nRO.token, "POST", "/api/task", { alias: node.other.alias, task: "x", network_id: net })).body.reason).toBe("mode_readonly");
+    expect((await mcp(node.nRO.token, "report_status", { resume_id: `r_${node.nRO.id}`, alias: node.nRO.alias, status: "idle" })).ok).toBe(true);
+    const t = await mcp(node.nN.token, "send_task", { alias: node.nRO.alias, task: "please answer" });
+    const reply = await mcp(node.nRO.token, "send_reply", { in_reply_to: t.task_id ?? t.message_id, text: "done", status: "replied" });
+    expect(reply.ok).not.toBe(false);
+    expect((await call(node.nRO.token, "GET", `/api/requirements?network_id=${net}`)).status).toBe(200);
+  });
+
+  test("restricted: sees and edits only cards assigned to it (and their subtasks)", async () => {
+    const list = await call(node.nR.token, "GET", `/api/requirements?network_id=${net}`);
+    expect(list.body.requirements.map((x: any) => x.id).sort()).toEqual([card.assigned, card.child].sort());
+    expect((await call(node.nR.token, "GET", `/api/requirements/${card.boss}`)).status).toBe(404);
+    expect((await call(node.nR.token, "PATCH", `/api/requirements/${card.assigned}`, { column: "doing" })).status).toBe(200);
+    expect((await call(node.nR.token, "PATCH", `/api/requirements/${card.child}`, { column: "doing" })).status).toBe(200);
+    expect((await call(node.nR.token, "POST", `/api/requirements/${card.assigned}/comments`, { text: "progress" })).status).toBe(201);
+    const mine = await call(node.nR.token, "POST", "/api/requirements", { name: "mine", network_id: net, agent_owner: { kind: "node", id: node.nR.id } });
+    expect(mine.status).toBe(201);
+    const notMine = await call(node.nR.token, "POST", "/api/requirements", { name: "not mine", network_id: net });
+    expect(notMine.status).toBe(403);
+    expect(notMine.body.reason).toBe("mode_restricted_not_assigned");
+    const viaMcp = await mcp(node.nR.token, "requirements_list", { network_id: net });
+    expect((viaMcp.requirements ?? []).map((x: any) => x.id)).not.toContain(card.boss);
+  });
+
+  test("restricted: no broadcast, no network stream, no other session's stream; its own stream works", async () => {
+    expect((await mcp(node.nR.token, "broadcast", { message: "hi all" })).reason).toBe("mode_restricted_not_assigned");
+    expect((await call(node.nR.token, "POST", "/api/broadcast", { message: "hi", network_id: net })).body.reason).toBe("mode_restricted_not_assigned");
+    expect((await sse(node.nR.token, `/events/network/${net}`)).status).toBe(403);
+    expect((await sse(node.nR.token, `/events/${encodeURIComponent(node.other.alias)}?network_id=${net}`)).status).toBe(403);
+    expect((await sse(node.nR.token, `/events/${encodeURIComponent(node.nR.alias)}?network_id=${net}`)).status).toBe(200);
+  });
+});
+
+describe("enforce", () => {
+  test("the same requests that were only logged are refused with node_permission_denied", async () => {
+    process.env.COMMHUB_NODE_PERMISSIONS = "enforce";
+    // 主人看不见的卡:与不存在同一个 404(按主人的可见范围读)。
+    expect((await call(node.nS.token, "PATCH", `/api/requirements/${card.boss}`, { description: "now refused" })).status).toBe(404);
+    // 主人看得见(他是参与人)但改不了的卡:node_permission_denied。
+    const w = await call(node.nS.token, "PATCH", `/api/requirements/${card.scoPart}`, { description: "now refused" });
+    expect(w.status).toBe(403);
+    expect(w.body).toMatchObject({ error: "node_permission_denied", reason: "beyond_owner_visibility" });
+    const list = await call(node.nS.token, "GET", `/api/requirements?network_id=${net}`);
+    expect(list.body.requirements.map((x: any) => x.id)).not.toContain(card.boss);
+  });
+
+  test("human-only actions are denied (REST and MCP); a node can still write its own attrs", async () => {
+    process.env.COMMHUB_NODE_PERMISSIONS = "enforce";
+    const r = await call(node.nN.token, "PUT", `/api/nodes/${node.other.id}/attrs`, { display_name: "nope", base_attrs_revision: attrsRev(node.other.id) });
+    expect(r.status).toBe(403);
+    expect(r.body.reason).toBe("human_only");
+    expect((await mcp(node.nN.token, "projects_create", { network_id: net, name: `q-${stamp}` })).reason).toBe("human_only");
+    expect((await call(node.nN.token, "PUT", `/api/nodes/${node.nN.id}/attrs`, { display_name: "me", base_attrs_revision: attrsRev(node.nN.id) })).status).toBe(200);
+    expect((await mcp(node.nN.token, "send_task", { alias: node.other.alias, task: "still fine" })).ok).toBe(true);
+  });
+
+  test("off: nothing is evaluated or logged for normal nodes; explicit modes still apply", async () => {
+    process.env.COMMHUB_NODE_PERMISSIONS = "off";
+    const before = JSON.stringify(logRows(node.nS.id));
+    expect((await call(node.nS.token, "PATCH", `/api/requirements/${card.boss}`, { description: "off" })).status).toBe(200);
+    expect(JSON.stringify(logRows(node.nS.id))).toBe(before);
+    expect((await call(node.nRO.token, "PATCH", `/api/requirements/${card.boss}`, { description: "still read-only" })).status).toBe(403);
+  });
+});
+
+describe("PUT /api/nodes/:id/permission-mode", () => {
+  test("owner and network owner/admin can set it and it applies on the next request; others cannot", async () => {
+    expect((await call(user.boss.token, "PUT", `/api/nodes/${node.nN.id}/permission-mode`, { mode: "readonly" })).body).toMatchObject({ ok: true, permission_mode: "readonly", previous: "normal" });
+    expect((await call(node.nN.token, "PATCH", `/api/requirements/${card.boss}`, { description: "mode flip" })).body.reason).toBe("mode_readonly");
+    expect((await call(user.boss.token, "PUT", `/api/nodes/${node.nN.id}/permission-mode`, { mode: "normal" })).status).toBe(200);
+    expect((await call(node.nN.token, "PATCH", `/api/requirements/${card.boss}`, { description: "mode flip" })).status).toBe(200);
+    expect((await call(user.sco.token, "PUT", `/api/nodes/${node.nS.id}/permission-mode`, { mode: "restricted" })).status).toBe(200); // sco 是 nS 的主人
+    expect((await call(user.sco.token, "PUT", `/api/nodes/${node.nS.id}/permission-mode`, { mode: "normal" })).status).toBe(200);
+    expect((await call(user.mem.token, "PUT", `/api/nodes/${node.nN.id}/permission-mode`, { mode: "readonly" })).status).toBe(403);
+    expect((await call(node.nN.token, "PUT", `/api/nodes/${node.nN.id}/permission-mode`, { mode: "normal" })).body.error).toBe("user_token_required");
+    expect((await call(user.out.token, "PUT", `/api/nodes/${node.nN.id}/permission-mode`, { mode: "readonly" })).status).toBe(404);
+    expect((await call(user.boss.token, "PUT", `/api/nodes/${node.nN.id}/permission-mode`, { mode: "admin" })).status).toBe(400);
+    expect(db.get<{ n: number | string }>("SELECT COUNT(*) AS n FROM audit_log WHERE action = 'node_permission_mode_changed' AND target_id = ?1", node.nN.id)!.n).toBeTruthy();
+  });
+});
+
+describe("GET /api/networks/:id/node-permission-report", () => {
+  test("owner sees would-have-blocked counts per node; members and node tokens are refused", async () => {
+    const r = await call(user.boss.token, "GET", `/api/networks/${net}/node-permission-report`);
+    expect(r.status).toBe(200);
+    const nS = r.body.nodes.find((n: any) => n.node_id === node.nS.id);
+    expect(nS.by_reason.beyond_owner_visibility).toBeGreaterThanOrEqual(2);
+    expect(nS.alias).toBe(node.nS.alias);
+    expect(r.body.total).toBe(r.body.nodes.reduce((n: number, e: any) => n + e.total, 0));
+    expect((await call(user.mem.token, "GET", `/api/networks/${net}/node-permission-report`)).status).toBe(403);
+    expect((await call(node.nN.token, "GET", `/api/networks/${net}/node-permission-report`)).status).toBe(403);
+    expect((await call(user.boss.token, "GET", `/api/networks/${net}/node-permission-report?since=${encodeURIComponent(new Date(Date.now() + 3_600_000).toISOString())}`)).body.total).toBe(0);
+  });
+});
+
+describe("bookkeeping", () => {
+  test("every MCP tool a node can call has a permission class", async () => {
+    const s = new McpServer({ name: "np", version: "1" });
+    registerTools(s, undefined, net, user.boss.id, node.nN.alias, true, node.nN.tokenId);
+    const client = new Client({ name: "np-client", version: "1" });
+    const [ct, st] = InMemoryTransport.createLinkedPair();
+    await s.connect(st); await client.connect(ct);
+    const names = (await client.listTools()).tools.map((t) => t.name);
+    await client.close(); await s.close();
+    expect(names.length).toBeGreaterThan(50);
+    expect(names.filter((n) => !NODE_TOOL_CLASS[n])).toEqual([]);
+  });
+
+  test("log rows older than the retention window are pruned", () => {
+    const old = new Date(Date.now() - 40 * 86_400_000).toISOString().slice(0, 13);
+    db.run("INSERT INTO node_permission_log (network_id, node_id, route, reason, hour, hits) VALUES (?1, ?2, 'old', 'human_only', ?3, 5)", [net, node.nN.id, old]);
+    pruneNodePermissionLog();
+    __resetNodePermissionLogStateForTest();
+    expect(db.get("SELECT 1 AS hit FROM node_permission_log WHERE route = 'old'")).toBeFalsy();
+  });
+});

package/src/node-permissions.ts

@@ -0,0 +1,242 @@
+// RFC-041 第一阶段(board #487):节点(Agent)自己的权限 —— 先记录、后执行。
+//
+// 节点的权限 = 主人的权限 ∩ 节点的模式(nodes.permission_mode:normal 正常 / readonly 只读 / restricted 受限)。
+//
+//   • 模式是主人主动设的,**设了就立刻生效**(不看开关):只读的节点写什么都拒(mode_readonly);
+//     受限的节点只碰派给它的任务、派活只给主人授权的 Agent(mode_restricted_not_assigned / agent_not_granted_to_owner)。
+//   • 正常模式下的收紧(超出主人可见范围 beyond_owner_visibility、主人没被授权的 Agent agent_not_granted_to_owner、
+//     只有人能做的事 human_only)由 Hub 开关 COMMHUB_NODE_PERMISSIONS 决定:
+//       log(默认)—— 照常放行,只把「本来会被拒」按 (节点, 路由, 原因, 小时) 合并记进 node_permission_log;
+//       enforce   —— 记录并拒绝(REST 403 / MCP 错误 node_permission_denied + reason + hint);
+//       off       —— 不判也不记(显式模式仍然生效)。
+//
+// 判定的入口:REST(requirements.ts、/api/task、/api/broadcast、/api/nodes/:id 写)、MCP(tools.ts 按工具名包一层)、
+// SSE(/events/:session、/events/network/:id)。只对节点令牌(ntok_)生效;用户令牌一条不变。
+// 只增不改:nodes 多一列 permission_mode(默认 normal),新表 node_permission_log。回滚到上一版安全:旧代码不读它们。
+
+import { db } from "./db.js";
+import { canMessageAgent, type AgentRef } from "./agent-access.js";
+
+export type NodePermissionMode = "normal" | "readonly" | "restricted";
+export const NODE_PERMISSION_MODES: readonly NodePermissionMode[] = ["normal", "readonly", "restricted"];
+export type NodePermissionsFlag = "log" | "off" | "enforce";
+export type NodePermissionReason =
+  | "beyond_owner_visibility"
+  | "agent_not_granted_to_owner"
+  | "mode_readonly"
+  | "mode_restricted_not_assigned"
+  | "human_only"
+  | "owner_unknown";
+
+/** 显式模式的原因:不看开关,永远拒。 */
+const MODE_REASONS: ReadonlySet<NodePermissionReason> = new Set(["mode_readonly", "mode_restricted_not_assigned"]);
+
+try { db.exec("ALTER TABLE nodes ADD COLUMN permission_mode TEXT NOT NULL DEFAULT 'normal'"); } catch (e: any) {
+  if (!/duplicate column|already exists/i.test(e?.message || "")) throw e;
+}
+db.exec(`
+  CREATE TABLE IF NOT EXISTS node_permission_log (
+    network_id TEXT NOT NULL,
+    node_id    TEXT NOT NULL,
+    route      TEXT NOT NULL,
+    reason     TEXT NOT NULL,
+    hour       TEXT NOT NULL,
+    hits       INTEGER NOT NULL DEFAULT 1,
+    sample     TEXT,
+    PRIMARY KEY (network_id, node_id, route, reason, hour)
+  );
+  CREATE INDEX IF NOT EXISTS idx_node_permission_log_hour ON node_permission_log(network_id, hour);
+`);
+
+/** 开关。未设 / 写错 → log(安全的默认:只记不拦)。每次现读:测试和运维改环境变量后无需重启模块。 */
+export function nodePermissionsFlag(): NodePermissionsFlag {
+  const raw = (process.env.COMMHUB_NODE_PERMISSIONS ?? "").trim().toLowerCase();
+  return raw === "off" || raw === "enforce" ? raw : "log";
+}
+
+export type NodeIdentity = {
+  networkId: string;
+  /** 绑定的节点;老的未绑定令牌 = null(按「正常」判,记录时用 token:<token_id>)。 */
+  nodeId: string | null;
+  logKey: string;
+  aliases: string[];
+  ownerUserId: string | null;
+  mode: NodePermissionMode;
+};
+
+function normalizeMode(raw: unknown): NodePermissionMode {
+  return raw === "readonly" || raw === "restricted" ? raw : "normal";
+}
+
+/** 节点令牌 → 节点身份(一次带索引的查询)。不是节点令牌 / 查不到 → null。 */
+export function nodeIdentity(tokenId: string | null | undefined, networkId: string | null | undefined): NodeIdentity | null {
+  if (!tokenId || !networkId) return null;
+  const row = db.get<{ user_id: string | null; bound_node_id: string | null; name: string | null; owner_user_id: string | null; permission_mode: string | null; alias: string | null }>(
+    `SELECT t.user_id, t.bound_node_id, t.name, n.owner_user_id, n.permission_mode, n.alias
+       FROM api_tokens t LEFT JOIN nodes n ON n.node_id = t.bound_node_id
+      WHERE t.token_id = ?1 AND t.network_id = ?2`,
+    tokenId, networkId,
+  );
+  if (!row) return null;
+  const aliases = new Set<string>();
+  if (row.alias) aliases.add(row.alias);
+  if (row.name?.startsWith("node:")) aliases.add(row.name.slice(5));
+  return {
+    networkId,
+    nodeId: row.bound_node_id,
+    logKey: row.bound_node_id ?? `token:${tokenId}`,
+    aliases: [...aliases],
+    ownerUserId: row.owner_user_id || row.user_id || null,
+    mode: normalizeMode(row.permission_mode),
+  };
+}
+
+export type Verdict = { reason: NodePermissionReason; sample?: string } | null;
+
+/**
+ * 判一次:verdict=null → 放行;否则按原因和开关决定拒不拒,并记一行(off 时正常模式的原因不记)。
+ * 返回 true = 拒绝。
+ */
+export function nodeDecide(id: NodeIdentity, route: string, verdict: Verdict): boolean {
+  if (!verdict) return false;
+  const explicit = MODE_REASONS.has(verdict.reason);
+  const flag = nodePermissionsFlag();
+  if (!explicit && flag === "off") return false;
+  recordNodePermission(id, route, verdict.reason, verdict.sample);
+  return explicit || flag === "enforce";
+}
+
+const HINTS: Record<NodePermissionReason, string> = {
+  beyond_owner_visibility: "this node acts with its owner's permissions, and its owner cannot see or edit this; ask the owner for access, or assign the task to this node",
+  agent_not_granted_to_owner: "this Agent has not been granted to this node's owner; ask a network admin to grant it",
+  mode_readonly: "this node is in read-only mode; the node's owner can switch it to normal in the app",
+  mode_restricted_not_assigned: "this node is in restricted mode and only touches tasks assigned to it; assign the task to this node, or have the owner switch it to normal",
+  human_only: "only people can do this (members, projects, permissions, providers, secrets, other nodes); use a user token",
+  owner_unknown: "this node's owner is unknown; recreate the node token from the owner's account",
+};
+
+export function nodePermissionDeniedBody(reason: NodePermissionReason, route: string): { ok: false; error: "node_permission_denied"; reason: NodePermissionReason; route: string; hint: string } {
+  return { ok: false, error: "node_permission_denied", reason, route, hint: HINTS[reason] };
+}
+
+// ── 记录:按 (网络, 节点, 路由, 原因, 小时) 合并;有上限、会清理 ──
+export const LOG_RETENTION_DAYS = 30;
+export const LOG_MAX_ROWS = 20_000;
+const PRUNE_EVERY_MS = 60 * 60 * 1000;
+let lastPrune = 0;
+let logFull = false;
+
+function hourOf(now = new Date()): string {
+  return now.toISOString().slice(0, 13); // 2026-10-03T08
+}
+
+/** 清掉保留期外的行,并重新判断是否到了上限(到上限后只给已有的行加次数,不再新开行)。 */
+export function pruneNodePermissionLog(now = new Date()): void {
+  const cutoff = hourOf(new Date(now.getTime() - LOG_RETENTION_DAYS * 86_400_000));
+  db.run("DELETE FROM node_permission_log WHERE hour < ?1", [cutoff]);
+  const n = Number(db.get<{ n: number | string }>("SELECT COUNT(*) AS n FROM node_permission_log")?.n ?? 0);
+  logFull = n >= LOG_MAX_ROWS;
+  lastPrune = now.getTime();
+}
+
+export function recordNodePermission(id: NodeIdentity, route: string, reason: NodePermissionReason, sample?: string): void {
+  try {
+    const now = new Date();
+    if (now.getTime() - lastPrune > PRUNE_EVERY_MS) pruneNodePermissionLog(now);
+    const hour = hourOf(now);
+    const s = sample ? sample.slice(0, 200) : null;
+    const updated = db.run(
+      "UPDATE node_permission_log SET hits = hits + 1, sample = COALESCE(?6, sample) WHERE network_id = ?1 AND node_id = ?2 AND route = ?3 AND reason = ?4 AND hour = ?5",
+      [id.networkId, id.logKey, route.slice(0, 120), reason, hour, s],
+    );
+    if (Number(updated?.changes ?? 0) > 0 || logFull) return;
+    db.run(
+      `INSERT INTO node_permission_log (network_id, node_id, route, reason, hour, hits, sample) VALUES (?1, ?2, ?3, ?4, ?5, 1, ?6)
+       ON CONFLICT(network_id, node_id, route, reason, hour) DO UPDATE SET hits = node_permission_log.hits + 1`,
+      [id.networkId, id.logKey, route.slice(0, 120), reason, hour, s],
+    );
+  } catch (e) {
+    // 记录失败绝不影响请求本身。
+    console.error(`[node-permissions] log failed: ${(e as Error).message}`);
+  }
+}
+
+/** Test-only:让下一次记录先清理一遍,并可改上限判断。 */
+export function __resetNodePermissionLogStateForTest(): void { lastPrune = 0; logFull = false; }
+
+// ── 规则 ──
+
+/** 派活 / 发消息 / 重派给 target。发给自己永远可以。 */
+export function dispatchVerdict(id: NodeIdentity, target: AgentRef): Verdict {
+  if ((target.alias && id.aliases.includes(target.alias)) || (target.nodeId && id.nodeId && target.nodeId === id.nodeId)) return null;
+  const sample = target.alias ?? target.nodeId ?? undefined;
+  if (id.mode === "readonly") return { reason: "mode_readonly", sample };
+  if (!id.ownerUserId) return id.mode === "restricted" ? { reason: "mode_restricted_not_assigned", sample } : { reason: "owner_unknown" };
+  if (!canMessageAgent(id.ownerUserId, id.networkId, target)) {
+    // 受限是主人设的 → 必拒(模式原因);正常下是开关管的收紧。
+    return { reason: id.mode === "restricted" ? "mode_restricted_not_assigned" : "agent_not_granted_to_owner", sample };
+  }
+  return null;
+}
+
+/** 广播:只读 / 受限都不行(会发给没派给它、也未必授权的 Agent)。 */
+export function broadcastVerdict(id: NodeIdentity): Verdict {
+  if (id.mode === "readonly") return { reason: "mode_readonly" };
+  if (id.mode === "restricted") return { reason: "mode_restricted_not_assigned" };
+  if (!id.ownerUserId) return { reason: "owner_unknown" };
+  return null;
+}
+
+/** 一般的写(管节点、提交技能、探测模型…):只读 / 受限拒;正常放行(由各自的既有规则管)。 */
+export function writeVerdict(id: NodeIdentity, sample?: string): Verdict {
+  if (id.mode === "readonly") return { reason: "mode_readonly", sample };
+  if (id.mode === "restricted") return { reason: "mode_restricted_not_assigned", sample };
+  return null;
+}
+
+/** 只有人能做的事。只读 / 受限下报模式原因(那是主人设的、必拒);正常下报 human_only。 */
+export function humanOnlyVerdict(id: NodeIdentity, sample?: string): Verdict {
+  return writeVerdict(id, sample) ?? { reason: "human_only", sample };
+}
+
+/** 订阅别的会话 / 整个网络的推送流:受限不行;正常按主人能不能看到那个 Agent。 */
+export function streamVerdict(id: NodeIdentity, target: AgentRef | "network"): Verdict {
+  if (target !== "network" && ((target.alias && id.aliases.includes(target.alias)) || (target.nodeId && target.nodeId === id.nodeId))) return null;
+  if (id.mode === "restricted") return { reason: "mode_restricted_not_assigned", sample: target === "network" ? "network" : target.alias ?? undefined };
+  if (!id.ownerUserId) return { reason: "owner_unknown" };
+  if (target !== "network" && !canMessageAgent(id.ownerUserId, id.networkId, target)) {
+    return { reason: "beyond_owner_visibility", sample: target.alias ?? undefined };
+  }
+  return null;
+}
+
+// ── MCP:每个工具归一类(test 钉住「每个注册的工具都归了类」,新工具忘了归类会红) ──
+export type ToolClass = "always" | "read" | "dispatch" | "broadcast" | "requirements" | "node_write" | "human_only";
+export const NODE_TOOL_CLASS: Readonly<Record<string, ToolClass>> = {
+  // 回复 / 上报 / 自己的收件箱 / 生命周期协议(节点自己的请求)—— 任何模式都能做
+  report_status: "always", report_completion: "always", get_inbox: "always", ack_inbox: "always",
+  mark_tasks_runtime_submitted: "always", mark_tasks_consumed: "always", send_reply: "always", send_peer_reply: "always", send_ack: "always",
+  get_config_update: "always", ack_config_update: "always", get_rules_file_request: "always", ack_rules_file_request: "always", get_rules_file_result: "always",
+  get_create_request: "always", ack_create_request: "always", get_stop_request: "always", ack_stop_request: "always",
+  get_start_request: "always", ack_start_request: "always", get_probe_request: "always", ack_probe_request: "always",
+  list_my_pending_create_requests: "always", list_my_pending_lifecycle_requests: "always", list_my_children: "always",
+  send_desktop_message: "always", // 发给人的私信,不是派活
+  // 读
+  get_all_status: "read", get_session_status: "read", get_task: "read", list_tasks: "read", get_completions: "read",
+  list_skills: "read", get_skill: "read", list_host_supervisors: "read", list_network_secrets: "read", list_providers: "read",
+  get_probe_results: "read", read_node_rules_file: "read", list_node_skills: "read", read_node_skill: "read", list_node_files: "read",
+  read_node_file: "read", tail_node_logs: "read",
+  // 派活
+  send_task: "dispatch", send_message: "dispatch", retry_task: "dispatch", reassign_task: "dispatch", cancel_task: "dispatch",
+  broadcast: "broadcast",
+  // 任务看板:在 requirements.ts 里按卡判(REST 与 MCP 同一处)
+  requirements_list: "requirements", requirements_people: "requirements", requirements_get: "requirements", requirements_create: "requirements",
+  requirements_update: "requirements", requirements_checklist_toggle: "requirements", requirements_upsert_by_external_ref: "requirements",
+  requirements_events: "requirements", requirements_comment: "requirements", projects_list: "requirements",
+  // 写节点 / 技能 / 探测:只读、受限不行;正常由 RFC-036 等既有规则管
+  update_node_config: "node_write", write_node_rules_file: "node_write", restart_node: "node_write", create_node: "node_write",
+  stop_node: "node_write", delete_node: "node_write", start_node: "node_write", submit_skill: "node_write", probe_provider_model: "node_write",
+  // 只有人能做
+  upsert_network_secret: "human_only", upsert_provider: "human_only", update_provider: "human_only",
+  projects_create: "human_only", projects_update: "human_only", review_skill: "human_only",
+};

package/src/requirements.ts

@@ -10,9 +10,10 @@ import { applyTagOp, normalizeTags, parseTagOp, storedTags, type TagOp } from ".
 import { aggregateStats, parseStatsQuery, type StatsRow } from "./requirements-stats.js";
 import { addHumanNetworkScope, canRestWriteNetwork, canRestWriteNetworkAsHuman, resolveRestWriteNetworkId, type RestNetworkScope } from "./network-scope.js";
 import { isAgentRestricted, restrictedNetworkIds, visibleAgents } from "./agent-access.js";
+import { nodeDecide, nodeIdentity, nodePermissionDeniedBody, nodePermissionsFlag, type NodeIdentity, type Verdict } from "./node-permissions.js";
 import {
   addProjectVisibilityScope, addTaskVisibilityScope, canDeleteTask, canEditTask, deletesAsHeadOnly, headOnlyEditScope, canParticipantEditTask, canSeeTask, canUseProject, deleteTaskGrantsForProject, projectUseResolver,
-  isTaskScoped, PARTICIPANT_EDIT_FIELDS, shouldAuditDenied, taskPermissionsResolver, type TaskCaller,
+  cardAssignedToNode, isTaskScoped, PARTICIPANT_EDIT_FIELDS, shouldAuditDenied, taskPermissionsResolver, type TaskCaller,
 } from "./task-access.js";
 import { notifyLeaderDeleted, notifyParticipantChange } from "./requirement-notify.js";
 import { departmentCardsFor, departmentSubtree } from "./department-heads.js";
@@ -93,11 +94,67 @@ function jsonError(error: string, status: number, ctx?: ErrorContext): Response
 }
 
 // ── 任务的人员权限(RFC-038 §9,判定在 task-access.ts) ──
-// 节点令牌(Agent)、Hub 管理员、没有身份的旧全局令牌:不受任务权限约束(null)。
+// Hub 管理员、没有身份的旧全局令牌:不受任务权限约束(null)。
+// 节点令牌(RFC-041,#487):受限模式 → 按主人的权限且只碰派给它的卡;执行开关为 enforce → 按主人的权限;
+// 其余(默认 log 下的正常 / 只读节点)→ null,与以前一样(只读的写在 nodeTaskGate 里拒)。
 function taskCaller(ctx: RequirementsRequestContext): TaskCaller {
-  if (!ctx.auth || ctx.isNodeToken || ctx.isAdmin) return null;
+  if (!ctx.auth || ctx.isAdmin) return null;
+  if (ctx.isNodeToken) return nodeTaskCaller(ctx);
   return { userId: ctx.auth.userId };
 }
+
+const nodeIdentities = new WeakMap<RequirementsRequestContext, NodeIdentity | null>();
+function nodeIdent(ctx: RequirementsRequestContext): NodeIdentity | null {
+  if (!ctx.isNodeToken) return null;
+  if (!nodeIdentities.has(ctx)) nodeIdentities.set(ctx, nodeIdentity(ctx.auth?.tokenId, ctx.auth?.networkId));
+  return nodeIdentities.get(ctx) ?? null;
+}
+function nodeTaskCaller(ctx: RequirementsRequestContext): TaskCaller {
+  const id = nodeIdent(ctx);
+  if (!id?.ownerUserId) return null;
+  if (id.mode === "restricted") return { userId: id.ownerUserId, node: { id: id.logKey, only: true } };
+  if (nodePermissionsFlag() === "enforce") return { userId: id.ownerUserId, node: { id: id.logKey, only: false } };
+  return null;
+}
+
+/**
+ * RFC-041 —— 节点的一次任务写(建 / 改 / 勾检查项 / 评论 / upsert)先过这里。row=null 是新建(create 给出目标项目、
+ * 负责 Agent、父卡)。只读 → 必拒;受限 → 不是派给它的必拒;正常 → 主人看不见 / 改不了时按开关记录或拒。
+ */
+function nodeTaskGate(ctx: RequirementsRequestContext, route: string, row: Row | null, create?: { networkId: string; projectId: string | null; agentOwnerJson: string | null; parentId: string | null }): Response | null {
+  const id = nodeIdent(ctx);
+  if (!id) return null;
+  const sample = row ? `#${row.seq ?? "?"} ${row.requirement_id}` : create?.projectId ?? undefined;
+  let verdict: Verdict = null;
+  if (id.mode === "readonly") verdict = { reason: "mode_readonly", sample };
+  else if (id.mode === "restricted") {
+    const nodeRef = JSON.stringify({ kind: "node", id: id.logKey });
+    const parent = create?.parentId ? db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE requirement_id = ?1`, create.parentId) : undefined;
+    const assigned = row ? cardAssignedToNode(row, id.logKey) : create?.agentOwnerJson === nodeRef || (!!parent && cardAssignedToNode(parent, id.logKey));
+    if (!assigned) verdict = { reason: "mode_restricted_not_assigned", sample };
+  } else if (!id.ownerUserId) verdict = { reason: "owner_unknown", sample };
+  else {
+    const asOwner: TaskCaller = { userId: id.ownerUserId, node: { id: id.logKey, only: false } };
+    const ok = row ? canSeeTask(asOwner, row) && canEditTask(asOwner, row) : canUseProject(asOwner, create!.networkId, create!.projectId);
+    if (!ok) verdict = { reason: "beyond_owner_visibility", sample };
+  }
+  return nodeDecide(id, route, verdict) ? Response.json(nodePermissionDeniedBody(verdict!.reason, route), { status: 403 }) : null;
+}
+
+/** 正常模式的节点读到了主人看不见的卡:只记录(执行时 taskCaller 已按主人收窄,读不到)。主人不受任务范围限制时什么都不做。 */
+function nodeReadNote(ctx: RequirementsRequestContext, route: string, row: Row | null): void {
+  const id = nodeIdent(ctx);
+  if (!id?.ownerUserId || id.mode === "restricted" || nodePermissionsFlag() !== "log" || !isTaskScoped(id.ownerUserId, id.networkId)) return;
+  const asOwner: TaskCaller = { userId: id.ownerUserId };
+  if (row) {
+    if (!canSeeTask(asOwner, row)) nodeDecide(id, route, { reason: "beyond_owner_visibility", sample: `#${row.seq ?? "?"} ${row.requirement_id}` });
+    return;
+  }
+  const all = Number(db.get<{ n: number | string }>("SELECT COUNT(*) AS n FROM requirements WHERE network_id = ?1", id.networkId)?.n ?? 0);
+  const params: unknown[] = [id.networkId];
+  const seen = Number(db.get<{ n: number | string }>(addTaskVisibilityScope("SELECT COUNT(*) AS n FROM requirements WHERE network_id = ?1", params, asOwner), ...params)?.n ?? 0);
+  if (all > seen) nodeDecide(id, route, { reason: "beyond_owner_visibility", sample: `list: ${all - seen} card(s) the owner cannot see` });
+}
 /**
  * 看得见但没权限写:403,并按 (用户, 卡) 每小时最多记一条审计。
  * field:参与人改了参与人不能改的字段 —— 错误码不变(旧 App 照旧认 task_read_only),多带 field + 一句中文 message。
@@ -825,6 +882,8 @@ async function createRequirement(ctx: RequirementsRequestContext, body: Record<s
   const createdAt = new Date().toISOString();
   let people;
   try { people = assignments(body, networkId, undefined, hiddenNodeFilter(ctx, networkId), ctx.strictOwner === true); } catch (e) { return errorFrom(e); }
+  const nodeDenied = nodeTaskGate(ctx, "POST /api/requirements", null, { networkId, projectId, agentOwnerJson: people.agentOwnerJson, parentId });
+  if (nodeDenied) return nodeDenied;
   const actor = JSON.stringify(actorOf(ctx));
   try {
     // 领号、插入、记「新建」这条动态在同一个事务里:插入被唯一索引挡下时,号和动态一起回滚,不留空洞。
@@ -862,6 +921,8 @@ function patchRequirement(ctx: RequirementsRequestContext, row: Row, body: Recor
   if (!PATCH_FIELDS.some(k => Object.prototype.hasOwnProperty.call(body, k))) return jsonError("empty_patch", 400, { sent: Object.keys(body), writable: PATCH_FIELDS });
   const has = (k: string) => Object.prototype.hasOwnProperty.call(body, k);
   if (!canWrite(ctx, row.network_id)) return jsonError("permission_denied", 403);
+  const nodeDenied = nodeTaskGate(ctx, "PATCH /api/requirements/:id", row);
+  if (nodeDenied) return nodeDenied;
   const caller = taskCaller(ctx);
   if (!canEditTask(caller, row)) {
     // 参与人:只放状态和检查项;别的字段点名拒绝。不是参与人 → 与今天一样。
@@ -1299,6 +1360,7 @@ function rememberList(key: string, entry: ListCacheEntry): void {
 function listCacheAcl(ctx: RequirementsRequestContext): string | null {
   const caller = taskCaller(ctx);
   if (!caller) return `open:${ctx.isAdmin ? 1 : 0}:${ctx.isNodeToken ? 1 : 0}`;
+  if (caller.node) return null; // 按节点收窄的列表不缓存(模式随时可改)
   if (restrictedNetworkIds(caller.userId).length > 0) return null;
   const members = db.all<Record<string, unknown>>("SELECT * FROM network_members WHERE user_id = ?1 ORDER BY network_id", caller.userId);
   const networks = members.map(m => String(m.network_id));
@@ -1417,6 +1479,7 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
     if (changes && url.searchParams.get("updated_since") === null) return jsonError("updated_since_required", 400);
     // changes 模式:server_time 取在读表之前,下次拿它当 updated_since,读表期间的写入不会漏(>= 会重复回一次,客户端按 id 覆盖)。
     const serverTime = new Date().toISOString();
+    nodeReadNote(ctx, "GET /api/requirements", null);
     const cacheKey = changes || url.searchParams.get("q") ? null : listCacheKey(ctx);
     const acl = cacheKey ? listCacheAcl(ctx) : null;
     const generation = requirementsGeneration;
@@ -1470,7 +1533,11 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
       return Response.json({ ...data, created: true }, { status: 201 });
     }
     const { external_ref: _ref, network_id: _net, client_id: _client, ...patch } = body;
-    if (!PATCH_FIELDS.some(k => Object.prototype.hasOwnProperty.call(patch, k))) return Response.json({ ok: true, requirement: toPublicFor(ctx, existing), created: false });
+    if (!PATCH_FIELDS.some(k => Object.prototype.hasOwnProperty.call(patch, k))) {
+      // 没有要改的字段 = 读回这张卡:受限节点只能读派给它的(与列表同一个可见范围)。
+      if (!canSeeTask(taskCaller(ctx), existing)) return jsonError("upsert_not_allowed", 403);
+      return Response.json({ ok: true, requirement: toPublicFor(ctx, existing), created: false });
+    }
     const res = patchRequirement(ctx, existing, patch);
     if (res.status !== 200) return res;
     const data = await res.json() as Record<string, unknown>;
@@ -1491,6 +1558,8 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
     const row = scopedRow(ctx, decodeURIComponent(commentMatch[1]));
     if (row instanceof Response) return row;
     if (!canWrite(ctx, row.network_id)) return jsonError("permission_denied", 403);
+    const nodeDenied = nodeTaskGate(ctx, "POST /api/requirements/:id/comments", row);
+    if (nodeDenied) return nodeDenied;
     const at = new Date().toISOString();
     const event = db.transaction(() => {
       recordRequirementEvents(db, row, JSON.stringify(actorOf(ctx)), [{ kind: "comment", field: null, old: null, new: { text } }], at);
@@ -1508,6 +1577,8 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
     const row = scopedRow(ctx, decodeURIComponent(itemMatch[1]));
     if (row instanceof Response) return row;
     if (!canWrite(ctx, row.network_id)) return jsonError("permission_denied", 403);
+    const nodeDenied = nodeTaskGate(ctx, "PATCH /api/requirements/:id/checklist/:item", row);
+    if (nodeDenied) return nodeDenied;
     if (!canEditTask(taskCaller(ctx), row) && !canParticipantEditTask(taskCaller(ctx), row)) return taskDenied(ctx, row, "task_read_only");
     // 读-改-写在同一个同步段里完成(中间没有 await),同一进程里的两次勾选不会交错。
     const items = storedChecklist(row.checklist_json);
@@ -1533,6 +1604,7 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
   const id = decodeURIComponent(match[1]);
   if (req.method === "GET") {
     const row = scopedRow(ctx, id);
+    if (!(row instanceof Response)) nodeReadNote(ctx, "GET /api/requirements/:id", row);
     return row instanceof Response ? row : Response.json({ ok: true, requirement: toPublicFor(ctx, row) });
   }
   if (req.method === "DELETE") {

package/src/server.ts

@@ -24,6 +24,7 @@ import { restrictedMemberSeesFile, restrictedMemberAttachmentsDenied } from "./r
 import { dmParticipantSeesFile, listDmThread, listDmThreads, sendHumanDm } from "./human-dm.js";
 import { getTaskAccessMode, isTaskScoped, listProjectGrants, replaceTaskGrants, NEW_MEMBER_TASK_ACCESS } from "./task-access.js";
 import { canMessageAgent, isAgentRestricted, listAgentGrants, listGroupGrants, getAgentAccessMode, replaceAgentGrants, restrictedNetworkIds, usernameIsAgentAlias, listAgentGroups, createAgentGroup, updateAgentGroup, replaceAgentGroupMembers, deleteAgentGroup, usersGrantedGroup } from "./agent-access.js";
+import { broadcastVerdict, dispatchVerdict, humanOnlyVerdict, NODE_PERMISSION_MODES, nodeDecide, nodeIdentity, nodePermissionDeniedBody, nodePermissionsFlag, streamVerdict, writeVerdict, type NodeIdentity, type NodePermissionMode, type Verdict } from "./node-permissions.js";
 import { validateAvatarUrl } from "./avatar-validate.js";
 import { narrowTags, parseStoredTags, validateScalarAttr } from "./node-attrs-validate.js";
 import { daemonDefaultWorkdirRoot } from "./create-node-validate.js";
@@ -318,6 +319,18 @@ function countNetworkUploads(networkId: string): number {
   return count;
 }
 
+// RFC-041(#487):节点令牌的一次 REST 写 / 订阅先按 node-permissions.ts 判。用户令牌 → null(不判)。
+function restNodeDenied(req: Request, restAuth: { networkId: string | null; tokenId: string | null } | null, route: string, verdictOf: (id: NodeIdentity) => Verdict): Response | null {
+  if (!restAuth?.networkId) return null;
+  const id = nodeIdentity(restAuth.tokenId, restAuth.networkId);
+  if (!id) return null;
+  const verdict = verdictOf(id);
+  return nodeDecide(id, route, verdict) ? withCors(req, Response.json(nodePermissionDeniedBody(verdict!.reason, route), { status: 403 })) : null;
+}
+/** 写别的节点 = 只有人能做;写自己 = 只看模式。 */
+const nodeTargetVerdict = (targetNodeId: string) => (id: NodeIdentity): Verdict =>
+  id.nodeId && id.nodeId === targetNodeId ? writeVerdict(id, targetNodeId) : humanOnlyVerdict(id, targetNodeId);
+
 function userTokenRequired(req: Request): Response {
   return withCors(req, Response.json({ ok: false, error: "user_token_required", message: "this endpoint acts on a user account; node tokens cannot use it" }, { status: 403 }));
 }
@@ -1007,11 +1020,9 @@ return Bun.serve({
     //   1. legacy AUTH_TOKEN (master) → any network
     //   2/3. ntok_ / utok_ → must CURRENTLY be a member of the requested
     //        network. Membership is checked unconditionally — there is NO
-    //        token-bound-network shortcut. removeNetworkMember deletes the
-    //        membership row but does NOT revoke the user's ntok, so the
-    //        network_members lookup IS the revocation mechanism: an ntok
-    //        bound to this network whose owner was removed must lose the
-    //        stream (审查修复 per 通信龙 #461 review, finding 1).
+    //        token-bound-network shortcut (审查修复 per 通信龙 #461 review,
+    //        finding 1). Since #488 removeNetworkMember also revokes the
+    //        user's tokens and resolveToken refuses a non-member's ntok.
     const netEventsMatch = url.pathname.match(/^\/events\/network\/(.+)$/);
     if (netEventsMatch && req.method === "GET") {
       const authErr = requireAuth(req);
@@ -1028,6 +1039,8 @@ return Bun.serve({
       if (!observerRole) {
         return withCors(req, Response.json({ ok: false, error: "not a member of this network" }, { status: 403 }));
       }
+      const streamDenied = restNodeDenied(req, authCtx, "SSE /events/network/:id", (id) => streamVerdict(id, "network"));
+      if (streamDenied) return streamDenied;
       // 多用户 Agent 权限:受限成员只收到自己是一端的路由事件(自己发的 / 发给自己的),
       // 看不到网络里别人和各个 Agent 之间的流量。
       if (isAgentRestricted(authCtx.userId, observedNetId)) {
@@ -1103,6 +1116,11 @@ return Bun.serve({
         if (!session && authCtx.networkId !== scopedNetId) {
           return withCors(req, Response.json({ ok: false, error: "session not in requested network" }, { status: 403 }));
         }
+        const streamDenied = restNodeDenied(req, authCtx, "SSE /events/:session", (id) => streamVerdict(id, {
+          alias: sessionName,
+          nodeId: db.get<{ node_id: string | null }>("SELECT node_id FROM sessions WHERE alias = ?1 AND network_id = ?2", sessionName, scopedNetId)?.node_id ?? null,
+        }));
+        if (streamDenied) return streamDenied;
         return createSSEStream(sessionName, scopedNetId);
       }
 
@@ -2271,6 +2289,67 @@ return Bun.serve({
     // GET  /api/dm?network_id=&with=<user_id>[&limit&before]  → 双向会话记录(新的在前)
     // GET  /api/dm/threads?network_id=                       → 每个对方一行 + 未读数
     // 已读沿用 POST /api/messages/ack(私信就是收件人 user_inbox 里的行)。
+    // ── RFC-041(#487):节点自己的权限 —— 改模式、看「本来会拦」的报表。只给人(用户令牌)。 ──
+    const permModeMatch = url.pathname.match(/^\/api\/nodes\/([^/]+)\/permission-mode$/);
+    if (permModeMatch && req.method === "PUT") {
+      if (!restAuth) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
+      if (restAuth.networkId) return userTokenRequired(req);
+      let body: any;
+      try { body = await req.json(); } catch { return withCors(req, Response.json({ ok: false, error: "invalid_json" }, { status: 400 })); }
+      const mode = body?.mode;
+      if (!NODE_PERMISSION_MODES.includes(mode)) {
+        return withCors(req, Response.json({ ok: false, error: "invalid_permission_mode", message: `mode must be one of ${NODE_PERMISSION_MODES.join(", ")}` }, { status: 400 }));
+      }
+      const nodeRef = decodeURIComponent(permModeMatch[1]);
+      const node = db.get<{ node_id: string; network_id: string | null; owner_user_id: string | null; permission_mode: string | null }>(
+        "SELECT node_id, network_id, owner_user_id, permission_mode FROM nodes WHERE node_id = ?1", nodeRef);
+      const role = node?.network_id ? getUserNetworkRole(restAuth.userId, node.network_id) : null;
+      // 看不见这个节点(不在它的网络里)与不存在同一个 404。
+      if (!node || !node.network_id || (!role && !isAdmin)) return withCors(req, Response.json({ ok: false, error: "node_not_found" }, { status: 404 }));
+      // 节点主人、网络 owner / admin、Hub 管理员能改;部门负责人和别的成员不能(RFC-041 §2.3 / §2.4)。
+      if (!isAdmin && node.owner_user_id !== restAuth.userId && role !== "owner" && role !== "admin") {
+        return withCors(req, Response.json({ ok: false, error: "permission_denied", message: "only the node's owner or a network owner/admin can change its permission mode" }, { status: 403 }));
+      }
+      const previous = (node.permission_mode || "normal") as NodePermissionMode;
+      db.run("UPDATE nodes SET permission_mode = ?1 WHERE node_id = ?2", [mode, node.node_id]);
+      logAudit(restAuth.userId, restAuth.username, "node_permission_mode_changed", "node", node.node_id, JSON.stringify({ from: previous, to: mode }), getClientIP(req), node.network_id);
+      return withCors(req, Response.json({ ok: true, node_id: node.node_id, permission_mode: mode, previous }));
+    }
+    const permReportMatch = url.pathname.match(/^\/api\/networks\/([^/]+)\/node-permission-report$/);
+    if (permReportMatch && req.method === "GET") {
+      if (!restAuth) return withCors(req, Response.json({ ok: false, error: "auth required" }, { status: 401 }));
+      if (restAuth.networkId) return userTokenRequired(req);
+      const networkId = decodeURIComponent(permReportMatch[1]);
+      const role = getUserNetworkRole(restAuth.userId, networkId);
+      if (!isAdmin && role !== "owner" && role !== "admin") {
+        return withCors(req, Response.json({ ok: false, error: "permission_denied", message: "network owner/admin only" }, { status: 403 }));
+      }
+      const sinceRaw = url.searchParams.get("since");
+      const sinceMs = sinceRaw ? Date.parse(sinceRaw) : Date.now() - 7 * 86_400_000;
+      if (!Number.isFinite(sinceMs)) return withCors(req, Response.json({ ok: false, error: "invalid_since" }, { status: 400 }));
+      const sinceHour = new Date(sinceMs).toISOString().slice(0, 13);
+      const rows = db.all<{ node_id: string; route: string; reason: string; hits: number | string; sample: string | null; last_hour: string }>(
+        `SELECT node_id, route, reason, SUM(hits) AS hits, MAX(sample) AS sample, MAX(hour) AS last_hour
+           FROM node_permission_log WHERE network_id = ?1 AND hour >= ?2
+          GROUP BY node_id, route, reason ORDER BY node_id, route, reason`,
+        networkId, sinceHour);
+      const byNode = new Map<string, { node_id: string; alias: string | null; permission_mode: string; total: number; by_reason: Record<string, number>; routes: Array<{ route: string; reason: string; hits: number; sample: string | null; last_hour: string }> }>();
+      for (const r of rows) {
+        let entry = byNode.get(r.node_id);
+        if (!entry) {
+          const n = db.get<{ alias: string | null; permission_mode: string | null }>("SELECT alias, permission_mode FROM nodes WHERE node_id = ?1", r.node_id);
+          entry = { node_id: r.node_id, alias: n?.alias ?? null, permission_mode: n?.permission_mode || "normal", total: 0, by_reason: {}, routes: [] };
+          byNode.set(r.node_id, entry);
+        }
+        const hits = Number(r.hits);
+        entry.total += hits;
+        entry.by_reason[r.reason] = (entry.by_reason[r.reason] ?? 0) + hits;
+        entry.routes.push({ route: r.route, reason: r.reason, hits, sample: r.sample, last_hour: r.last_hour });
+      }
+      const nodes = [...byNode.values()].sort((a, b) => b.total - a.total || a.node_id.localeCompare(b.node_id));
+      return withCors(req, Response.json({ ok: true, network_id: networkId, since: new Date(sinceMs).toISOString(), mode: nodePermissionsFlag(), total: nodes.reduce((n, e) => n + e.total, 0), nodes }));
+    }
+
     if (url.pathname === "/api/dm" || url.pathname === "/api/dm/threads") {
       if (!restAuth || !requestToken(req).startsWith("utok_")) {
         return withCors(req, Response.json({ ok: false, error: "user_token_required" }, { status: 403 }));
@@ -3190,6 +3269,11 @@ return Bun.serve({
       }
       const canonical = resolveCanonicalAlias(taskNetId, body.alias);
       const targetAlias = canonical.alias;
+      const nodeDenied = restNodeDenied(req, restAuth, "POST /api/task", (id) => dispatchVerdict(id, {
+        alias: targetAlias,
+        nodeId: db.get<{ node_id: string | null }>("SELECT node_id FROM sessions WHERE alias = ?1 AND network_id = ?2", targetAlias, taskNetId)?.node_id ?? null,
+      }));
+      if (nodeDenied) return nodeDenied;
       const target = resolveRestDeliveryTarget(targetAlias, taskNetId);
       if (target.state === "not_found") {
         return withCors(req, Response.json({
@@ -3425,6 +3509,8 @@ return Bun.serve({
       if (!canRestWriteNetwork(restAuth, restScope.networkId, isAdmin)) {
         return withCors(req, Response.json({ ok: false, error: "permission_denied" }, { status: 403 }));
       }
+      const broadcastDenied = restNodeDenied(req, restAuth, "POST /api/broadcast", broadcastVerdict);
+      if (broadcastDenied) return broadcastDenied;
       let sql = "SELECT alias, node_id, network_id FROM sessions WHERE alias IS NOT NULL";
       const params: any[] = [];
       sql = addNetworkScope(sql, params, restScope);
@@ -3797,6 +3883,8 @@ return Bun.serve({
       if (!canRestWriteNetwork(restAuth, nodeNetId, isAdmin)) {
         return withCors(req, Response.json({ ok: false, error: "permission_denied" }, { status: 403 }));
       }
+      const nodeWriteDenied = restNodeDenied(req, restAuth, "DELETE /api/nodes/:id", nodeTargetVerdict(node.node_id));
+      if (nodeWriteDenied) return nodeWriteDenied;
 
       db.transaction(() => {
         db.run("DELETE FROM nodes WHERE node_id = ?1", [node.node_id]);
@@ -3907,6 +3995,8 @@ return Bun.serve({
       if (!canRestWriteNetwork(restAuth, nodeNetId, isAdmin)) {
         return withCors(req, Response.json({ ok: false, error: "permission_denied" }, { status: 403 }));
       }
+      const nodeWriteDenied = restNodeDenied(req, restAuth, "PUT /api/nodes/:id/attrs", nodeTargetVerdict(node.node_id));
+      if (nodeWriteDenied) return nodeWriteDenied;
 
       // Optimistic lock BEFORE any narrowing work, so a losing writer never
       // has side effects.
@@ -4006,6 +4096,8 @@ return Bun.serve({
       if (!canRestWriteNetwork(restAuth, nodeNetId, isAdmin)) {
         return withCors(req, Response.json({ ok: false, error: "permission_denied" }, { status: 403 }));
       }
+      const nodeWriteDenied = restNodeDenied(req, restAuth, "PUT /api/nodes/:id/avatar", nodeTargetVerdict(node.node_id));
+      if (nodeWriteDenied) return nodeWriteDenied;
 
       db.run(
         "UPDATE nodes SET avatar_url = ?1, updated_at = datetime('now') WHERE node_id = ?2",
@@ -4271,7 +4363,7 @@ return Bun.serve({
                         config_path, channels, server, hostname,
                         network_id, created_at, updated_at,
                         config_snapshot, lifecycle_state, avatar_url,
-                        display_name, team, tags, attrs_revision
+                        display_name, team, tags, attrs_revision, permission_mode
                  FROM nodes WHERE 1=1`;
       const params: any[] = [];
       sql = addAgentNetworkScope(sql, params, restScope, { alias: "alias", nodeId: "node_id" });

package/src/task-access.ts

@@ -99,7 +99,7 @@ export function listProjectGrants(networkId: string, userId: string): ProjectGra
 const likeEscape = (s: string) => s.replace(/[\\%_]/g, (c) => `\\${c}`);
 export const userRefPattern = (userId: string) => `%${likeEscape(`"kind":"user","id":"${userId}"`)}%`;
 
-type CardRow = { network_id: string; owner_json: string | null; participants_json: string | null; created_by: string | null; created_by_json: string | null; project_id: string | null; agent_owner_json?: string | null };
+type CardRow = { network_id: string; owner_json: string | null; participants_json: string | null; created_by: string | null; created_by_json: string | null; project_id: string | null; agent_owner_json?: string | null; parent_id?: string | null };
 const refIs = (json: string | null, userId: string) => !!json && json.includes(`"kind":"user","id":"${userId}"`);
 const ownsCard = (row: CardRow, userId: string) => refIs(row.owner_json, userId);
 const createdCard = (row: CardRow, userId: string) => refIs(row.created_by_json, userId) || (!row.created_by_json && row.created_by === userId);
@@ -126,10 +126,33 @@ function headOf(userId: string, row: CardRow): boolean {
   return !!cards && isDepartmentCard(cards, row);
 }
 
-export type TaskCaller = { userId: string } | null;
+/**
+ * 调用者。userId = 按谁的任务权限判;node(RFC-041,#487)= 节点令牌按**主人**的权限判时带上节点:
+ *   only=false(正常模式、执行开关打开)—— 主人能改的能改,另外「派给这个节点的」在主人看得见时也能改;
+ *   only=true (受限模式)—— 只看、只改派给这个节点的卡(负责 Agent / 参与人 / 它建的,及这些卡的子任务)。
+ */
+export type TaskCaller = { userId: string; node?: { id: string; only: boolean } } | null;
+
+export const nodeRefPattern = (nodeId: string) => `%${likeEscape(`"kind":"node","id":"${nodeId}"`)}%`;
+const nodeRefIs = (json: string | null | undefined, nodeId: string) => !!json && json.includes(`"kind":"node","id":"${nodeId}"`);
+const directlyAssigned = (row: Pick<CardRow, "agent_owner_json" | "participants_json" | "created_by_json">, nodeId: string) =>
+  nodeRefIs(row.agent_owner_json, nodeId) || nodeRefIs(row.participants_json, nodeId) || nodeRefIs(row.created_by_json, nodeId);
+
+/** 这张卡派给了这个节点吗:负责 Agent / 参与人有它 / 它建的,或者父卡是。 */
+export function cardAssignedToNode(row: CardRow, nodeId: string): boolean {
+  if (directlyAssigned(row, nodeId)) return true;
+  if (!row.parent_id) return false;
+  const parent = db.get<{ agent_owner_json: string | null; participants_json: string | null; created_by_json: string | null }>(
+    "SELECT agent_owner_json, participants_json, created_by_json FROM requirements WHERE requirement_id = ?1", row.parent_id);
+  return !!parent && directlyAssigned(parent, nodeId);
+}
 
 /** 看得见这张卡吗。caller=null(节点令牌 / 管理员 / 旧的全局令牌)恒为 true。 */
 export function canSeeTask(caller: TaskCaller, row: CardRow): boolean {
+  if (caller?.node?.only && !cardAssignedToNode(row, caller.node.id)) return false;
+  return canSeeTaskAsUser(caller, row);
+}
+function canSeeTaskAsUser(caller: TaskCaller, row: CardRow): boolean {
   if (!caller) return true;
   const m = memberRow(caller.userId, row.network_id);
   if (!scopedRow(m)) return true;
@@ -141,6 +164,13 @@ export function canSeeTask(caller: TaskCaller, row: CardRow): boolean {
 
 /** 能改这张卡吗(PATCH / 勾子任务)。只对看得见的卡调用。 */
 export function canEditTask(caller: TaskCaller, row: CardRow): boolean {
+  if (caller?.node) {
+    const assigned = cardAssignedToNode(row, caller.node.id) && canSeeTaskAsUser(caller, row);
+    return caller.node.only ? assigned : assigned || canEditTaskAsUser(caller, row);
+  }
+  return canEditTaskAsUser(caller, row);
+}
+function canEditTaskAsUser(caller: TaskCaller, row: CardRow): boolean {
   if (!caller) return true;
   const m = memberRow(caller.userId, row.network_id);
   if (!scopedRow(m)) return true;
@@ -174,7 +204,7 @@ export const PARTICIPANT_EDIT_FIELDS: readonly string[] = ["column", "checklist"
 
 /** 这个调用者是不是「只能以参与人身份改」这张卡(canEditTask 为 false、但他是卡上的参与人)。viewer 不算。 */
 export function canParticipantEditTask(caller: TaskCaller, row: CardRow): boolean {
-  if (!caller) return false;
+  if (!caller || caller.node) return false; // 参与人身份是人的;节点按 canEditTask 判
   const m = memberRow(caller.userId, row.network_id);
   if (!scopedRow(m) || m?.member_role === "viewer") return false;
   return participates(row, caller.userId);
@@ -258,6 +288,14 @@ export function canUseProject(caller: TaskCaller, networkId: string, projectId:
  * 追加在已经按网络过滤过的 `FROM requirements WHERE …` 后面。
  */
 export function addTaskVisibilityScope(sql: string, params: unknown[], caller: TaskCaller): string {
+  const scoped = addTaskVisibilityScopeAsUser(sql, params, caller);
+  if (!caller?.node?.only) return scoped;
+  // 受限节点:再只留派给它的卡(及其子任务)。
+  const pat = params.push(nodeRefPattern(caller.node.id));
+  const mine = (t: string) => `${t}agent_owner_json LIKE ?${pat} ESCAPE '\\' OR ${t}participants_json LIKE ?${pat} ESCAPE '\\' OR ${t}created_by_json LIKE ?${pat} ESCAPE '\\'`;
+  return `${scoped} AND (${mine("")} OR parent_id IN (SELECT p.requirement_id FROM requirements p WHERE ${mine("p.")}))`;
+}
+function addTaskVisibilityScopeAsUser(sql: string, params: unknown[], caller: TaskCaller): string {
   if (!caller) return sql;
   const scoped = taskScopedNetworks(caller.userId);
   if (!scoped.length) return sql;

package/src/tools.ts

@@ -12,7 +12,8 @@ import { assertNodeActive } from "./lifecycle-guard.js";
 import { pendingInboxCount } from "./inbox-count.js";
 import { getUserNetworkRole, createNetworkTokenForNode } from "./auth.js";
 import { addAgentNetworkScope, addNetworkScope, addOwnTrafficScope, canRestWriteNetwork, canRestWriteNetworkAsHuman, getUserNetworkIds, resolveRestNetworkScope, singleNetworkId, type RestNetworkScope } from "./network-scope.js";
-import { canMessageAgent, restrictedNetworkIds, RESTRICTED_MEMBER_TOOLS } from "./agent-access.js";
+import { canMessageAgent, restrictedNetworkIds, RESTRICTED_MEMBER_TOOLS, type AgentRef } from "./agent-access.js";
+import { broadcastVerdict, dispatchVerdict, humanOnlyVerdict, NODE_TOOL_CLASS, nodeDecide, nodeIdentity, nodePermissionDeniedBody, writeVerdict, type NodeIdentity, type Verdict } from "./node-permissions.js";
 import { restrictedMemberAttachmentsDenied } from "./restricted-files.js";
 import { errorBody } from "./requirements-errors.js";
 import { handleRequirementsRequest } from "./requirements.js";
@@ -200,11 +201,69 @@ function guardRestrictedMemberTools(server: McpServer, restrictedNets: string[],
   }
 }
 
+// RFC-041 第一阶段(#487):节点令牌的每个 MCP 工具先按 NODE_TOOL_CLASS 判一次(node-permissions.ts)。
+// log 模式下正常节点照常放行、只记录;显式的只读 / 受限模式立刻生效。requirements_* 在 requirements.ts 里按卡判。
+function guardNodePermissionTools(server: McpServer, tokenId: string, networkId: string): void {
+  const denied = (reason: Parameters<typeof nodePermissionDeniedBody>[0], route: string) => ({
+    content: [{ type: "text" as const, text: JSON.stringify(nodePermissionDeniedBody(reason, route)) }],
+  });
+  const taskTarget = (taskId: unknown): { to: AgentRef; from: string | null } | null => {
+    if (typeof taskId !== "string" || !taskId) return null;
+    const t = db.get<{ to_name: string | null; to_node_id: string | null; from_name: string | null }>(
+      "SELECT to_name, to_node_id, from_name FROM tasks WHERE task_id = ?1 AND network_id = ?2", taskId, networkId);
+    return t ? { to: { alias: t.to_name, nodeId: t.to_node_id }, from: t.from_name } : null;
+  };
+  const aliasTarget = (alias: unknown): AgentRef | null => {
+    if (typeof alias !== "string" || !alias.trim()) return null;
+    const canonical = resolveCanonicalAlias(networkId, alias.trim()).alias;
+    const session = db.get<{ node_id: string | null }>("SELECT node_id FROM sessions WHERE alias = ?1 AND network_id = ?2", canonical, networkId);
+    return { alias: canonical, nodeId: session?.node_id ?? null };
+  };
+  const verdictFor = (id: NodeIdentity, name: string, args: Record<string, unknown>): Verdict => {
+    switch (NODE_TOOL_CLASS[name]) {
+      case "dispatch": {
+        if (name === "retry_task" || name === "cancel_task") {
+          const t = taskTarget(args.task_id);
+          if (!t) return null; // 没这个任务:交给工具自己回 not found
+          if (name === "cancel_task" && t.from && id.aliases.includes(t.from)) return null; // 撤回自己派的
+          return dispatchVerdict(id, t.to);
+        }
+        const target = aliasTarget(name === "reassign_task" ? args.new_alias : args.alias);
+        return target ? dispatchVerdict(id, target) : null;
+      }
+      case "broadcast": return broadcastVerdict(id);
+      case "node_write": return writeVerdict(id, name);
+      case "human_only": return humanOnlyVerdict(id, name);
+      default: return null; // always / read / requirements(按卡判)/ 没归类的(test 保证没有)
+    }
+  };
+  const wrap = (name: string, handler: (...callArgs: any[]) => any) => async (...callArgs: any[]) => {
+    const cls = NODE_TOOL_CLASS[name];
+    if (cls && cls !== "always" && cls !== "read" && cls !== "requirements") {
+      const id = nodeIdentity(tokenId, networkId);
+      const args = callArgs[0] && typeof callArgs[0] === "object" ? callArgs[0] as Record<string, unknown> : {};
+      const verdict = id ? verdictFor(id, name, args) : null;
+      if (id && nodeDecide(id, `mcp:${name}`, verdict)) return denied(verdict!.reason, `mcp:${name}`);
+    }
+    return handler(...callArgs);
+  };
+  const anyServer = server as any;
+  for (const method of ["tool", "registerTool"] as const) {
+    const original = anyServer[method].bind(server);
+    anyServer[method] = (...regArgs: any[]) => {
+      const last = regArgs.length - 1;
+      if (typeof regArgs[0] === "string" && typeof regArgs[last] === "function") regArgs[last] = wrap(regArgs[0], regArgs[last]);
+      return original(...regArgs);
+    };
+  }
+}
+
 export function registerTools(server: McpServer, clientIP?: string, enforceNetworkId?: string | null, enforceUserId?: string | null, callerAlias?: string | null, callerTokenIsNetwork = false, callerTokenId?: string | null) {
   // 多用户 Agent 权限:用户令牌调用者在哪些网络里是受限成员(只看授权 Agent)。
   // 网络令牌不会走到这里 —— 受限成员的网络令牌在 resolveToken 就被拒了。
   const restrictedNets = enforceUserId && !callerTokenIsNetwork && !enforceNetworkId ? restrictedNetworkIds(enforceUserId) : [];
   if (restrictedNets.length) guardRestrictedMemberTools(server, restrictedNets, enforceUserId!);
+  if (callerTokenIsNetwork && callerTokenId && enforceNetworkId) guardNodePermissionTools(server, callerTokenId, enforceNetworkId);
   // Default from_session for outbound tools — extracted from the calling
   // token's binding (ntok_ → node alias, utok_ → username). Without this,
   // an agent's send_task call always claimed from='hub' and peer agents