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

package/src/task-access.ts

@@ -7,10 +7,13 @@
 //               能改:负责人是我 / 我建的 / 项目授权 can_edit;能删:负责人是我 / 我建的;不能管项目。
 //               viewer 只看 ④,什么都不能改。
 // owner/admin 角色与 Hub 管理员不看这一列。节点令牌(Agent)不经过这里 —— 规则原样不动。
+// RFC-040(#455)再加两个来源,和上面的取并集、只加不减:部门项目授权(授权给我的部门或它的上级 ⇒ 同按人授权),
+// 负责人权力(我负责的部门子树里的卡:可看 / 可改 / 可删;viewer 当负责人不算)。见 department-heads.ts。
 //
 // 判定是 fail-closed 的:task_access 只有字面 'all' 才放开;role 只有 owner/admin 才豁免。
 
 import { db } from "./db.js";
+import { deleteDepartmentGrantsForProject, departmentGrantsForMember, headCardsFor, isDepartmentCard, type DepartmentCards } from "./department-heads.js";
 
 // ── 表结构(放在这里而不是 db.ts:db.ts 每多一行,文档里钉着的行号就漂一次) ──
 // ALTER 的 DEFAULT 'all' 让**升级前已有的**成员行全部落在旧语义 —— 升级不收窄任何人;新成员按下面的
@@ -96,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 };
+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);
@@ -111,26 +114,85 @@ function projectGrant(networkId: string, userId: string, projectId: string | nul
   return row ? { project_id: projectId, can_edit: row.can_edit === 1 } : null;
 }
 
-export type TaskCaller = { userId: string } | null;
+/** 部门项目授权(RFC-040):null = 部门没授权这个项目;否则 = can_edit。 */
+function departmentGrant(networkId: string, userId: string, projectId: string | null): boolean | null {
+  if (!projectId) return null;
+  const grants = departmentGrantsForMember(networkId, userId);
+  return grants.has(projectId) ? grants.get(projectId)! : null;
+}
+/** 这张卡是不是我负责的部门(含下级)的卡。 */
+function headOf(userId: string, row: CardRow): boolean {
+  const cards = headCardsFor(row.network_id, userId);
+  return !!cards && isDepartmentCard(cards, row);
+}
+
+/**
+ * 调用者。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;
   if (projectGrant(row.network_id, caller.userId, row.project_id)) return true;
+  if (departmentGrant(row.network_id, caller.userId, row.project_id) !== null) return true;
   if (m?.member_role === "viewer") return false;
-  return ownsCard(row, caller.userId) || createdCard(row, caller.userId) || participates(row, caller.userId);
+  return ownsCard(row, caller.userId) || createdCard(row, caller.userId) || participates(row, caller.userId) || headOf(caller.userId, row);
 }
 
 /** 能改这张卡吗(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;
   if (m?.member_role === "viewer") return false;
   if (ownsCard(row, caller.userId) || createdCard(row, caller.userId)) return true;
-  return projectGrant(row.network_id, caller.userId, row.project_id)?.can_edit === true;
+  if (projectGrant(row.network_id, caller.userId, row.project_id)?.can_edit === true) return true;
+  return departmentGrant(row.network_id, caller.userId, row.project_id) === true || headOf(caller.userId, row);
+}
+
+/**
+ * 这次能改,是不是**只**因为负责人身份(没有自己的 / 按人或部门授权的来源)。这种时候负责人只能把卡交给本部门的人
+ * (RFC-040 §1:改负责人只能改成本部门成员 / 其 Agent / 自己),返回本部门的人和节点;否则 null(不加限制)。
+ */
+export function headOnlyEditScope(caller: TaskCaller, row: CardRow): DepartmentCards | null {
+  if (!caller) return null;
+  const m = memberRow(caller.userId, row.network_id);
+  if (!scopedRow(m) || m?.member_role === "viewer") return null;
+  if (ownsCard(row, caller.userId) || createdCard(row, caller.userId)) return null;
+  if (projectGrant(row.network_id, caller.userId, row.project_id)?.can_edit === true) return null;
+  if (departmentGrant(row.network_id, caller.userId, row.project_id) === true) return null;
+  const cards = headCardsFor(row.network_id, caller.userId);
+  return cards && isDepartmentCard(cards, row) ? cards : null;
 }
 
 /**
@@ -142,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);
@@ -159,7 +221,15 @@ export function canDeleteTask(caller: TaskCaller, row: CardRow): boolean {
   const m = memberRow(caller.userId, row.network_id);
   if (!scopedRow(m)) return true;
   if (m?.member_role === "viewer") return false;
-  return ownsCard(row, caller.userId) || createdCard(row, caller.userId);
+  return ownsCard(row, caller.userId) || createdCard(row, caller.userId) || headOf(caller.userId, row);
+}
+
+/** 这次能删只因为负责人身份(RFC-040 Q4:记 requirement_deleted_by_leader + 私信卡的负责人)。 */
+export function deletesAsHeadOnly(caller: TaskCaller, row: CardRow): boolean {
+  if (!caller) return false;
+  const m = memberRow(caller.userId, row.network_id);
+  if (!scopedRow(m) || m?.member_role === "viewer") return false;
+  return !ownsCard(row, caller.userId) && !createdCard(row, caller.userId) && headOf(caller.userId, row);
 }
 
 /**
@@ -170,14 +240,16 @@ export function canDeleteTask(caller: TaskCaller, row: CardRow): boolean {
 export type TaskPermissions = { edit: boolean; delete: boolean; edit_fields?: readonly string[] };
 export function taskPermissionsResolver(caller: TaskCaller): (row: CardRow) => TaskPermissions | null {
   if (!caller) return () => null;
-  const cache = new Map<string, { scoped: boolean; viewer: boolean; grants: Map<string, boolean> }>();
+  const cache = new Map<string, { scoped: boolean; viewer: boolean; grants: Map<string, boolean>; deptGrants: Map<string, boolean>; head: DepartmentCards | null }>();
   const ctxFor = (networkId: string) => {
     let c = cache.get(networkId);
     if (!c) {
       const m = memberRow(caller.userId, networkId);
       const scoped = scopedRow(m);
+      const viewer = m?.member_role === "viewer";
       const grants = new Map<string, boolean>(scoped ? listProjectGrants(networkId, caller.userId).map((g) => [g.project_id, g.can_edit] as [string, boolean]) : []);
-      cache.set(networkId, c = { scoped, viewer: m?.member_role === "viewer", grants });
+      const deptGrants = scoped ? departmentGrantsForMember(networkId, caller.userId) : new Map<string, boolean>();
+      cache.set(networkId, c = { scoped, viewer, grants, deptGrants, head: scoped && !viewer ? headCardsFor(networkId, caller.userId) : null });
     }
     return c;
   };
@@ -185,8 +257,9 @@ export function taskPermissionsResolver(caller: TaskCaller): (row: CardRow) => T
     const c = ctxFor(row.network_id);
     if (!c.scoped) return null;
     if (c.viewer) return { edit: false, delete: false };
-    const mine = ownsCard(row, caller.userId) || createdCard(row, caller.userId);
-    const edit = mine || (row.project_id ? c.grants.get(row.project_id) === true : false);
+    const head = !!c.head && isDepartmentCard(c.head, row);
+    const mine = ownsCard(row, caller.userId) || createdCard(row, caller.userId) || head;
+    const edit = mine || (row.project_id ? c.grants.get(row.project_id) === true || c.deptGrants.get(row.project_id) === true : false);
     if (!edit && participates(row, caller.userId)) return { edit, delete: mine, edit_fields: PARTICIPANT_EDIT_FIELDS };
     return { edit, delete: mine };
   };
@@ -199,6 +272,7 @@ export function taskPermissionsResolver(caller: TaskCaller): (row: CardRow) => T
 export function projectUseResolver(caller: TaskCaller, networkId: string): (projectId: string) => boolean {
   if (!caller || !isTaskScoped(caller.userId, networkId)) return () => true;
   const editable = new Set(listProjectGrants(networkId, caller.userId).filter((g) => g.can_edit).map((g) => g.project_id));
+  for (const [projectId, canEdit] of departmentGrantsForMember(networkId, caller.userId)) if (canEdit) editable.add(projectId);
   return (projectId) => editable.has(projectId);
 }
 
@@ -206,7 +280,7 @@ export function projectUseResolver(caller: TaskCaller, networkId: string): (proj
 export function canUseProject(caller: TaskCaller, networkId: string, projectId: string | null): boolean {
   if (!caller || !projectId) return true;
   if (!isTaskScoped(caller.userId, networkId)) return true;
-  return projectGrant(networkId, caller.userId, projectId)?.can_edit === true;
+  return projectGrant(networkId, caller.userId, projectId)?.can_edit === true || departmentGrant(networkId, caller.userId, projectId) === true;
 }
 
 /**
@@ -214,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;
@@ -232,6 +314,16 @@ export function addTaskVisibilityScope(sql: string, params: unknown[], caller: T
     parts.push(`(network_id IN (${ph(members)}) AND (${mine} OR ${granted}))`);
   }
   if (viewers.length) parts.push(`(network_id IN (${ph(viewers)}) AND ${granted})`);
+  // RFC-040:部门项目授权(viewer 也有,和按人授权一样只给「看」)+ 负责人本部门的卡(viewer 没有)。只加析取项。
+  for (const s of scoped) {
+    const extra: string[] = [];
+    const deptProjects = [...departmentGrantsForMember(s.networkId, caller.userId).keys()];
+    if (deptProjects.length) extra.push(`project_id IN (${ph(deptProjects)})`);
+    const head = s.viewer ? null : headCardsFor(s.networkId, caller.userId);
+    if (head?.users.size) extra.push(`owner_json IN (${ph([...head.users].map((id) => JSON.stringify({ kind: "user", id })))})`);
+    if (head?.nodes.size) extra.push(`agent_owner_json IN (${ph([...head.nodes].map((id) => JSON.stringify({ kind: "node", id })))})`);
+    if (extra.length) parts.push(`(network_id = ?${params.push(s.networkId)} AND (${extra.join(" OR ")}))`);
+  }
   return `${sql} AND (${parts.join(" OR ")})`;
 }
 
@@ -240,7 +332,10 @@ export function addProjectVisibilityScope(sql: string, params: unknown[], caller
   if (!caller || !isTaskScoped(caller.userId, networkId)) return sql;
   const uid = params.push(caller.userId);
   const net = params.push(networkId);
-  return `${sql} AND project_id IN (SELECT project_id FROM network_member_project_grants WHERE user_id = ?${uid} AND network_id = ?${net})`;
+  const personal = `project_id IN (SELECT project_id FROM network_member_project_grants WHERE user_id = ?${uid} AND network_id = ?${net})`;
+  const deptProjects = [...departmentGrantsForMember(networkId, caller.userId).keys()];
+  if (!deptProjects.length) return `${sql} AND ${personal}`;
+  return `${sql} AND (${personal} OR project_id IN (${deptProjects.map((id) => `?${params.push(id)}`).join(", ")}))`;
 }
 
 export type ReplaceTaskGrantsResult =
@@ -302,6 +397,7 @@ export function deleteTaskGrantsForMember(networkId: string, userId: string): vo
 }
 export function deleteTaskGrantsForProject(projectId: string): void {
   db.run("DELETE FROM network_member_project_grants WHERE project_id = ?1", [projectId]);
+  deleteDepartmentGrantsForProject(projectId);
 }
 
 // 被拒的写入审计限频:同一 (用户, 卡) 每小时最多记一条,别让重试刷爆审计表。

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";
@@ -148,9 +149,9 @@ function scheduledReplyRecipient(taskId: string, networkId: string | null | unde
 // 方无影响，只是错误形态更一致）。
 const NODE_ID_ALIAS_FIELDS = {
   node_id: z.string().min(1).max(200).optional()
-    .describe("Target child node ID (canonical, #1281). The value create_node returns. Must be in caller's network."),
+    .describe("Child node id (as returned by create_node), in your network."),
   child_node_id: z.string().min(1).max(200).optional()
-    .describe("DEPRECATED alias for node_id (#1281): kept for back-compat with pre-unification clients; prefer node_id."),
+    .describe("Deprecated alias of node_id."),
 } as const;
 
 /** #1281 — 把 node_id / child_node_id 收敛成单一内部 id。两个都传且不等 ⇒
@@ -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
@@ -1639,7 +1698,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       network_id: z.string().max(200).optional().describe("Network scope"),
       parent_task_id: z.string().max(200).optional().describe("Parent task this dispatch is on behalf of. When the child task replies the hub will auto-chain the answer to the parent task's originator, so the user sees the final result even if the intermediate session ends."),
       meta: z.any().optional().describe("Optional structured task metadata, e.g. { attachments: [{ type, path, url, mime, name, size }] }."),
-      force: z.boolean().optional().describe("#460 — dispatch even when the target reports a degraded health layer (user tokens only; ignored for node tokens)"),
+      force: z.boolean().optional().describe("dispatch even if the target is degraded (user tokens only)"),
     },
     async ({ alias, task, priority, context, from_session: _fromIn, ttl_seconds, network_id: netId, parent_task_id: parentIn, meta, force }) => { const fromMismatch = fromIdentityMismatchReply(_fromIn); if (fromMismatch) return fromMismatch; const from_session = defaultFrom(_fromIn);
       const effectiveNetId = getNetworkId(netId);
@@ -1972,7 +2031,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       // `attachments` before this schema entry existed would see `ok:true`
       // and never learn the attachments were dropped. Validated by
       // validateAttachments (uploads.ts) — the same helper the REST path uses.
-      attachments: z.any().optional().describe("Optional attachment array; parity with send_task's meta.attachments. Each item: {type:'file', file_id, name?, mime?, size?}. Persisted into tasks.meta_json + inbox.meta_json."),
+      attachments: z.any().optional().describe("Attachments, like send_task's meta.attachments: [{type:'file', file_id, name?, mime?, size?}]."),
       // #507 — optional structured metadata (parity with send_task L837). If
       // both `attachments` (top-level) and `meta.attachments` are supplied,
       // top-level wins (same rule as REST /api/task L2101).
@@ -2359,7 +2418,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       task_id: z.string().min(1).max(200).describe("Task ID to retry"),
       from_session: z.string().max(200).optional(),
       network_id: z.string().max(200).optional().describe("Network scope (auto-resolved for single-network user tokens)"),
-      force: z.boolean().optional().describe("#460 — dispatch even when the target reports a degraded health layer (user tokens only; ignored for node tokens)"),
+      force: z.boolean().optional().describe("dispatch even if the target is degraded (user tokens only)"),
     },
     async ({ task_id, from_session: _fromIn, network_id: netId, force }) => { const fromMismatch = fromIdentityMismatchReply(_fromIn); if (fromMismatch) return fromMismatch; const from_session = defaultFrom(_fromIn);
       const effectiveNetId = getNetworkId(netId);
@@ -2578,7 +2637,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       new_alias: z.string().min(1).max(200).describe("Target agent alias"),
       from_session: z.string().max(200).optional(),
       network_id: z.string().max(200).optional().describe("Network scope (auto-resolved for single-network user tokens)"),
-      force: z.boolean().optional().describe("#460 — dispatch even when the target reports a degraded health layer (user tokens only; ignored for node tokens)"),
+      force: z.boolean().optional().describe("dispatch even if the target is degraded (user tokens only)"),
     },
     async ({ task_id, new_alias, from_session: _fromIn, network_id: netId, force }) => { const fromMismatch = fromIdentityMismatchReply(_fromIn); if (fromMismatch) return fromMismatch; const from_session = defaultFrom(_fromIn);
       const effectiveNetId = getNetworkId(netId);
@@ -3509,7 +3568,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     "Ask a node to send back its rules file (CLAUDE.md for claude nodes, AGENTS.md otherwise) from its working directory. No path argument by design. Poll get_rules_file_result with the returned request_id. app#225.",
     {
       ...NODE_ID_ALIAS_FIELDS,
-      alias: z.string().min(1).max(200).optional().describe("Target by alias instead of node_id — resolves to the node row, or to a session that reported rules_file_capable (claude-code sessions)."),
+      alias: z.string().min(1).max(200).optional().describe("Alias instead of node_id (a node, or a session reporting rules_file_capable)."),
       network_id: z.string().max(200).optional(),
     },
     async ({ node_id, child_node_id, alias, network_id }) => enqueueRulesFileRequest("read", { node_id, child_node_id, alias, network_id }),
@@ -3520,7 +3579,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     "Ask a node to overwrite its rules file (CLAUDE.md for claude nodes, AGENTS.md otherwise) in its working directory with `content`. No path argument by design. Poll get_rules_file_result with the returned request_id. app#225.",
     {
       ...NODE_ID_ALIAS_FIELDS,
-      alias: z.string().min(1).max(200).optional().describe("Target by alias instead of node_id — resolves to the node row, or to a session that reported rules_file_capable (claude-code sessions)."),
+      alias: z.string().min(1).max(200).optional().describe("Alias instead of node_id (a node, or a session reporting rules_file_capable)."),
       content: z.string().max(RULES_FILE_MAX_BYTES).describe("Full new file content (UTF-8). The node writes it atomically."),
       network_id: z.string().max(200).optional(),
     },
@@ -3532,7 +3591,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     "Ask a node to list the skills its runtime loads (name, scope project|user|system, display path, frontmatter description). Read-only; no path argument. Poll get_rules_file_result — content is JSON {skills:[…]}.",
     {
       ...NODE_ID_ALIAS_FIELDS,
-      alias: z.string().min(1).max(200).optional().describe("Target by alias instead of node_id — resolves to the node row, or to a session that reported skills_capable."),
+      alias: z.string().min(1).max(200).optional().describe("Alias instead of node_id (a node, or a session reporting skills_capable)."),
       network_id: z.string().max(200).optional(),
     },
     async ({ node_id, child_node_id, alias, network_id }) => enqueueRulesFileRequest("skills_list", { node_id, child_node_id, alias, network_id }),
@@ -3543,7 +3602,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     "Ask a node for one skill's SKILL.md by name. Read-only; the node resolves the name under its own runtime's skills roots — no path argument. Poll get_rules_file_result — content is JSON {name, scope, path_rel, description, content}.",
     {
       ...NODE_ID_ALIAS_FIELDS,
-      alias: z.string().min(1).max(200).optional().describe("Target by alias instead of node_id — resolves to the node row, or to a session that reported skills_capable."),
+      alias: z.string().min(1).max(200).optional().describe("Alias instead of node_id (a node, or a session reporting skills_capable)."),
       name: z.string().min(1).max(64).describe("Skill directory name, [A-Za-z0-9._-]."),
       network_id: z.string().max(200).optional(),
     },
@@ -3555,7 +3614,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     "Ask a node to list one directory level of its work dir (project folder view, read-only). `path` is relative to the work dir (default: the root); absolute paths and .. are refused. Poll get_rules_file_result — content is JSON {path, entries:[{name,type,size?,mtime?,hidden_reason?,no_descend?}], truncated, total}. User logins only.",
     {
       ...NODE_ID_ALIAS_FIELDS,
-      alias: z.string().min(1).max(200).optional().describe("Target by alias instead of node_id — resolves to the node row, or to a session that reported files_capable."),
+      alias: z.string().min(1).max(200).optional().describe("Alias instead of node_id (a node, or a session reporting files_capable)."),
       path: z.string().max(NODE_FILE_PATH_MAX).optional().describe("Directory relative to the node's work dir; omit or \"\" for the root."),
       network_id: z.string().max(200).optional(),
     },
@@ -3567,7 +3626,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     "Ask a node for one text file under its work dir (project folder view, read-only, 256 KiB cap; binary / too large → size only; secret-looking files → name only). `path` is relative to the work dir. Poll get_rules_file_result — content is JSON {path, name, kind, size?, mtime?, content?, hidden_reason?}. User logins only.",
     {
       ...NODE_ID_ALIAS_FIELDS,
-      alias: z.string().min(1).max(200).optional().describe("Target by alias instead of node_id — resolves to the node row, or to a session that reported files_capable."),
+      alias: z.string().min(1).max(200).optional().describe("Alias instead of node_id (a node, or a session reporting files_capable)."),
       path: z.string().min(1).max(NODE_FILE_PATH_MAX).describe("File path relative to the node's work dir."),
       network_id: z.string().max(200).optional(),
     },
@@ -3579,7 +3638,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     "Ask a node for the tail of its own agent-node run log (read-only, redacted on the node before it leaves). No path argument: the node reads only its own log directory. User logins only; the node's owner or a network owner/admin. Poll get_rules_file_result — content is JSON {files, lines:[{ts, level, text, key}], truncated, matched, now_ts}; it is handed out once and then purged.",
     {
       ...NODE_ID_ALIAS_FIELDS,
-      alias: z.string().min(1).max(200).optional().describe("Target by alias instead of node_id — resolves to the node row, or to a session that reported logs_capable."),
+      alias: z.string().min(1).max(200).optional().describe("Alias instead of node_id (a node, or a session reporting logs_capable)."),
       lines: z.number().int().min(1).max(LOGS_MAX_LINES).optional().describe("How many of the newest matching lines (default 500, max 2000)."),
       level: z.enum(["info", "warn", "error"]).optional().describe("Only lines of exactly this level."),
       grep: z.string().min(1).max(LOGS_GREP_MAX).optional().describe("Case-insensitive substring, matched after redaction."),
@@ -5844,9 +5903,11 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   // (requirements.ts personRef;找不到 / 别名对上多个 → 400 + hint)。给了 id 就只看 id。
   const reqPerson = z.object({
     kind: z.enum(["user", "node"]),
-    id: z.string().min(1).max(200).optional().describe("user_id / node_id (from requirements_people)"),
-    username: z.string().min(1).max(100).optional().describe("kind 'user' only: the member's username, resolved in the task's network"),
-    alias: z.string().min(1).max(200).optional().describe("kind 'node' only: the Agent's alias, resolved in the task's network"),
+    // #476 —— 这三格的说明不写在这里:reqPerson 在 3 个工具 × 3 个字段里展开,每份都复制一遍(~1.6 KB)。
+    // 写法在 owner / agent_owner / participants 的 describe 里各说一次。
+    id: z.string().min(1).max(200).optional(),
+    username: z.string().min(1).max(100).optional(),
+    alias: z.string().min(1).max(200).optional(),
   });
   const reqChecklistItem = z.object({ id: z.string().regex(/^[A-Za-z0-9_-]{1,40}$/).optional(), text: z.string().min(1).max(500), done: z.boolean().optional() });
   const reqFields = {
@@ -5859,9 +5920,9 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     description: z.string().max(20_000).optional().describe("markdown"),
     checklist: z.array(reqChecklistItem).max(100).optional().describe("replaces the whole list"),
     project_id: z.string().max(200).nullable().optional(),
-    owner: reqPerson.nullable().optional().describe("负责人 (a person): {kind:'user', id} or {kind:'user', username}; a node here is rejected with 400 owner_must_be_human — use agent_owner for nodes"),
-    agent_owner: reqPerson.nullable().optional().describe("负责 Agent: {kind:'node', id} or {kind:'node', alias}"),
-    participants: z.array(reqPerson).max(100).optional().describe("REPLACES the whole participant list ({kind, id}, {kind:'user', username} or {kind:'node', alias}) (omitted people are removed; [] clears it). To add or remove a few people without touching the others, use participants_add / participants_remove on requirements_update."),
+    owner: reqPerson.nullable().optional().describe("负责人 (a person): {kind:'user', id | username} (ids / usernames from requirements_people; names resolve in the task's network); a node is rejected with owner_must_be_human — use agent_owner"),
+    agent_owner: reqPerson.nullable().optional().describe("负责 Agent: {kind:'node', id | alias}"),
+    participants: z.array(reqPerson).max(100).optional().describe("REPLACES the whole list (written like owner / agent_owner; omitted people are removed, [] clears). To add or remove a few, use participants_add / participants_remove on requirements_update."),
     external_url: z.string().max(500).nullable().optional(),
     parent_id: z.string().regex(/^[A-Za-z0-9_-]{1,200}$/).nullable().optional().describe("parent requirement (same network, no cycles, ≤ 5 levels); null detaches"),
   };
@@ -5869,14 +5930,14 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   const REQ_WRITE_KEYS = [...Object.keys(reqFields), "external_ref", "archived"];
   // #475 —— status 是 column 的别名(列表的筛选参数就叫 status,Agent 写任务时也常这么写)。只在 MCP 这层换名,REST 不变;
   // 两个都给且不同 → 400 status_conflicts_with_column,不替调用方挑一个。
-  const reqStatus = z.enum(["pool", "doing", "done"]).optional().describe("alias of column (same values); if both are sent they must match");
+  const reqStatus = z.enum(["pool", "doing", "done"]).optional().describe("alias of column; must match it if both are sent");
   const withColumn = (args: Record<string, unknown>, call: (args: Record<string, unknown>) => Promise<{ content: { type: "text"; text: string }[] }>) => {
     if (args.status === undefined) return call(args);
     if (args.column !== undefined && args.column !== args.status) return Promise.resolve({ content: [{ type: "text" as const, text: JSON.stringify({ ...errorBody("status_conflicts_with_column"), status: 400 }) }] });
     return call({ ...args, column: args.status });
   };
-  const reqPeopleDelta = (verb: string) => z.array(reqPerson).max(100).optional().describe(`${verb} these people ${verb === "add" ? "to" : "from"} the participant list, keeping everyone else (atomic; ${verb === "add" ? "already present = no change" : "not present = no change"}). Cannot be combined with participants.`);
-  const REQ_ID_DESC = "requirement id (req_…) or its short number \"#N\" (e.g. \"#42\", per network; a user token that sees several networks must also pass network_id, else 409 ambiguous_seq)";
+  const reqPeopleDelta = (verb: string) => z.array(reqPerson).max(100).optional().describe(`${verb === "add" ? "Add to" : "Remove from"} the participant list, keeping the rest (atomic; not with participants).`);
+  const REQ_ID_DESC = "requirement id (req_…) or short number \"#N\" (per network; with several networks also pass network_id)";
 
   // #471 —— MCP 的列表默认省流:summary 视图 + 50 张一页(REST 的默认 full + 500 不变,App 靠它)。
   // 生产实测 122 张卡:旧默认(full、500)148 KB,summary 81 KB —— 一次调用就塞满 Agent 的上下文。
@@ -5894,6 +5955,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     external_ref: z.string().max(200).optional(),
     include_archived: z.boolean().optional(),
     parent_id: z.string().max(200).optional().describe("children of this requirement ('none' = top level)"),
+    department_id: z.string().max(64).optional().describe("owner (or its Agent's owner) in this department or below"),
     top_level: z.boolean().optional(), q: z.string().max(200).optional(),
     limit: z.number().int().min(1).max(1000).optional().describe(`page size, default ${REQ_LIST_MCP_DEFAULT_LIMIT}`),
     cursor: z.string().max(600).optional().describe("next_cursor from the previous page"),
@@ -5904,7 +5966,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   server.registerTool(
     "requirements_list",
     {
-      description: `List requirement tasks in your network. Defaults (MCP): view='summary' and ${REQ_LIST_MCP_DEFAULT_LIMIT} per page, newest first — about 0.5 KB per task, so a page stays small. has_more + next_cursor → pass cursor for the next page. Summary rows drop description and checklist bodies (has_description, checklist_count instead); for full text read one task with requirements_get, or pass view='full' (several KB per task — keep limit small). Filters: seq (the per-network short number shown as #N), status (pool/doing/done), project_id ('none' = no project), owner / agent_owner ('user:<id>' / 'node:<id>' / 'none'), tag (exact label), updated_since (ISO), external_ref, parent_id / top_level, include_archived; q = search title / description / owner, agent and participant names / project name / tags (space-separated terms are ANDed). limit ≤ 1000. Each task carries children {total, done}. changes=true (needs updated_since) returns only tasks changed since then, archived ones included, plus deleted ids and server_time to pass as the next updated_since. Unknown parameters are rejected (-32602) with the list of valid ones.`,
+      description: `List requirement tasks in your network, newest first. Defaults (MCP): view='summary' (no description / checklist bodies; has_description, checklist_count instead; ~0.5 KB per task) and ${REQ_LIST_MCP_DEFAULT_LIMIT} per page; has_more + next_cursor → pass cursor. Full text: requirements_get, or view='full' with a small limit (≤ 1000). Filters: seq (#N), status, project_id ('none'), owner / agent_owner ('user:<id>' / 'node:<id>' / 'none'), tag (exact), updated_since (ISO), external_ref, parent_id / top_level, department_id (owner in it or below), include_archived; q searches title / description / people / project / tags (terms ANDed). Rows carry children {total, done}. changes=true (with updated_since) returns only tasks changed since then, archived included, plus deleted ids and server_time for the next updated_since. Unknown parameters are rejected (-32602).`,
       // Strict: registerTool honours a constructed object's unknownKeys (server.tool() would strip them silently).
       inputSchema: z.strictObject(reqListShape, {
         error: (iss: any) => iss.code === "unrecognized_keys"
@@ -5914,7 +5976,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     },
     async (args: any) => {
       const q = new URLSearchParams();
-      for (const k of ["seq", "status", "project_id", "owner", "agent_owner", "tag", "updated_since", "external_ref", "parent_id", "q", "limit", "cursor", "view"] as const) if (args[k] !== undefined) q.set(k, String(args[k]));
+      for (const k of ["seq", "status", "project_id", "owner", "agent_owner", "tag", "updated_since", "external_ref", "parent_id", "department_id", "q", "limit", "cursor", "view"] as const) if (args[k] !== undefined) q.set(k, String(args[k]));
       if (!q.has("view")) q.set("view", "summary");
       if (!q.has("limit")) q.set("limit", String(REQ_LIST_MCP_DEFAULT_LIMIT));
       if (args.include_archived) q.set("include_archived", "1");
@@ -5935,7 +5997,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   server.registerTool(
     "requirements_people",
     {
-      description: "Look up the people in your network and the Agents they own, to fill task person fields. Each row: user_id, username, display_name (\"\" if not set), role, department {id, name} or null, agents [{node_id, alias}]; Agents with no owner in this network are listed in agents_without_owner (first page only). q filters by username / display name / department / Agent alias (case-insensitive substring). 50 people per page (limit ≤ 200); has_more + next_offset → pass offset. Agents you are not granted are left out. Person fields on requirements_create / requirements_update / requirements_upsert_by_external_ref accept {kind:'user', id} or {kind:'user', username} (owner, participants) and {kind:'node', id} or {kind:'node', alias} (agent_owner, participants), resolved in the task's own network only.",
+      description: "Look up the people in your network and the Agents they own, to fill task person fields. Each row: user_id, username, display_name (\"\" if not set), role, department {id, name} or null, agents [{node_id, alias}]; Agents with no owner in this network are listed in agents_without_owner (first page only). q filters by username / display name / department / Agent alias (case-insensitive substring). 50 people per page (limit ≤ 200); has_more + next_offset → pass offset. Agents you are not granted are left out. Task person fields take these ids, or {kind:'user', username} / {kind:'node', alias}.",
       inputSchema: z.strictObject(reqPeopleShape, {
         error: (iss: any) => iss.code === "unrecognized_keys"
           ? `unknown parameter(s): ${(iss.keys ?? []).join(", ")}; valid parameters: ${reqPeopleKeys.join(", ")}`
@@ -6020,17 +6082,27 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     async (args) => requirementsCall("PATCH", `/api/requirements/projects/${encodeURIComponent(args.id)}`, args.network_id, pick(args, ["name", "color", "sort", "archived"])),
   );
 
-  server.tool(
+  // #476 —— 不带 requirement_id 的全网动态默认 50 条(REST 默认 200 不变,App 走 REST);严格参数同 #471。
+  const REQ_EVENTS_NETWORK_DEFAULT_LIMIT = 50;
+  const reqEventsShape = {
+    network_id: z.string().max(200).optional(),
+    requirement_id: z.string().min(1).max(200).optional().describe(REQ_ID_DESC),
+    since: z.string().max(40).optional().describe("ISO; only events after it"),
+    limit: z.number().int().min(1).max(500).optional(),
+    cursor: z.string().max(20).optional().describe("next_cursor from the previous page (older events)"),
+  };
+  const reqEventsKeys = Object.keys(reqEventsShape);
+  server.registerTool(
     "requirements_events",
-    "Read the task activity timeline (the app's 动态): field-level changes — who, when, old → new — and comments (kind=comment, text in new.text; add one with requirements_comment), newest first. Pass requirement_id (req_… or \"#N\") for one task, or omit it for the whole network. since (ISO) = only changes after it; limit 1–500 (default 200); next_cursor → pass as cursor for the next page; server_time → use as the next since. Same visibility as requirements_list: tasks you can't see (and hidden Agents) are left out.",
     {
-      network_id: z.string().max(200).optional(),
-      requirement_id: z.string().min(1).max(200).optional(),
-      since: z.string().max(40).optional(),
-      limit: z.number().int().min(1).max(500).optional(),
-      cursor: z.string().max(20).optional(),
+      description: `Read the task activity timeline (the app's 动态), newest first: field-level changes (who, when, old → new) and comments (kind=comment, text in new.text; add one with requirements_comment). With requirement_id (req_… or "#N"): that task's events (limit default 200). Without it: the whole network, ${REQ_EVENTS_NETWORK_DEFAULT_LIMIT} per page by default. limit ≤ 500; next_cursor → pass as cursor for older events; server_time → use as the next since. Same visibility as requirements_list. Unknown parameters are rejected (-32602).`,
+      inputSchema: z.strictObject(reqEventsShape, {
+        error: (iss: any) => iss.code === "unrecognized_keys"
+          ? `unknown parameter(s): ${(iss.keys ?? []).join(", ")}; valid parameters: ${reqEventsKeys.join(", ")}`
+          : undefined,
+      }) as any,
     },
-    async (args) => {
+    async (args: any) => {
       let card = args.requirement_id;
       // "#N" → the card's id, resolved exactly like requirements_get (same scope; a card you can't see is a 404 here too).
       if (card && /^#\d+$/.test(card)) {
@@ -6043,6 +6115,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       if (card) q.set("requirement_id", card);
       if (args.since) q.set("since", args.since);
       if (args.limit !== undefined) q.set("limit", String(args.limit));
+      else if (!card) q.set("limit", String(REQ_EVENTS_NETWORK_DEFAULT_LIMIT));
       if (args.cursor) q.set("cursor", args.cursor);
       return requirementsCall("GET", `/api/requirements/events${q.size ? `?${q}` : ""}`, args.network_id);
     },