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

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/observer-avatar-http.test.ts

@@ -159,8 +159,8 @@ describe("#461 GET /events/network/:id — auth", () => {
   test("membership removal revokes observer access — ntok exploit repro (通信龙 review finding 1)", async () => {
     // Exact repro of the review's exploit: add user C to network A, mint
     // an ntok BOUND to A, remove C from A — the same live ntok must lose
-    // the stream. network_members IS the revocation mechanism because
-    // removeNetworkMember does not revoke the user's tokens; the old
+    // the stream. (Before #488 network_members was the only revocation
+    // mechanism — removeNetworkMember did not revoke tokens; the old
     // `!role && authCtx.networkId !== observedNetId` OR-form let the
     // token's network binding bypass the membership check (utok would
     // not catch this: its authCtx.networkId is null, so only ntok
@@ -182,10 +182,12 @@ describe("#461 GET /events/network/:id — auth", () => {
 
     const removed = removeNetworkMember(memberNetworkId, outsiderUserId);
     expect(removed.ok).toBe(true);
-    // The review's failing probe: /events/network/A with the still-live
-    // network-bound token → must now be 403, not 200.
+    // The review's failing probe: /events/network/A with the network-bound
+    // token → must no longer be 200. Since #488 removeNetworkMember revokes
+    // the user's tokens for that network and resolveToken rejects a
+    // non-member's network token, so the token itself is refused (401).
     const afterRemoval = await fetch(`${BASE}/events/network/${memberNetworkId}`, { headers: auth(ntok) });
-    expect(afterRemoval.status).toBe(403);
+    expect(afterRemoval.status).toBe(401);
     // utok of the removed user is denied too.
     const utokAfter = await fetch(`${BASE}/events/network/${memberNetworkId}`, { headers: auth(outsiderToken) });
     expect(utokAfter.status).toBe(403);

package/src/requirement-notify.ts

@@ -132,3 +132,34 @@ export function notifyParticipantChange(input: { before: NoticeCard; after: Noti
   if (pending.size > 5_000) for (const [k, p] of pending) if (now - p.startedAt >= COALESCE_WINDOW_MS) pending.delete(k);
   return sent;
 }
+
+/**
+ * RFC-040 Q4:部门负责人(只凭负责人身份)删了本部门的一张卡 → 私信卡的负责人。
+ * 卡没有人类负责人时,私信负责 Agent 的主人(这张卡正是因为那个 Agent 才算「本部门的卡」)。
+ * 删的人就是收件人 / 收件人已不在网络 → 不发。返回收件人(测试用),没发 → null。
+ */
+export function notifyLeaderDeleted(input: { card: NoticeCard & { agent_owner_json?: string | null }; actorUserId: string }): string | null {
+  const { card, actorUserId } = input;
+  let target = userIdOf(parse(card.owner_json));
+  if (!target) {
+    const agent = parse(card.agent_owner_json ?? null) as { kind?: unknown; id?: unknown } | null;
+    if (agent?.kind === "node" && typeof agent.id === "string") {
+      target = db.get<{ owner_user_id: string | null }>("SELECT owner_user_id FROM nodes WHERE node_id = ?1 AND network_id = ?2", agent.id, card.network_id)?.owner_user_id ?? null;
+    }
+  }
+  if (!target || target === actorUserId) return null;
+  const user = db.get<{ username: string; display_name: string | null }>("SELECT username, display_name FROM users WHERE user_id = ?1", actorUserId);
+  if (!user) return null;
+  const actorName = user.display_name?.trim() || user.username;
+  const number = card.seq ? ` #${card.seq}` : "";
+  const sent = sendNoticeDm({
+    networkId: card.network_id,
+    targetUserId: target,
+    sender: { userId: actorUserId, username: user.username },
+    title: "任务删除",
+    metaJson: JSON.stringify({ task_notice: { requirement_id: card.requirement_id, seq: card.seq ?? null, network_id: card.network_id, deleted: true } }),
+    messageId: `dm_task_${uuidv4()}`,
+    text: `${actorName}(部门负责人)删除了你负责的任务${number}「${card.title}」`,
+  });
+  return sent ? target : null;
+}

package/src/requirements-errors.ts

@@ -48,6 +48,8 @@ const ENTRIES: Record<string, Entry> = {
   agent_owner_must_be_agent: { field: 'agent_owner', message: 'agent_owner (负责 Agent) must be a node.', hint: "Use agent_owner: {kind:'node', id}. To assign a person, use owner: {kind:'user', id}." },
   agent_owner_not_granted: { field: 'agent_owner', message: 'The current responsible Agent is one you are not granted, so you cannot replace or clear it.', hint: 'Leave agent_owner out of the patch.' },
   invalid_participants: { field: 'participants', message: 'participants must be an array of up to 100 persons {kind, id}; it replaces the whole list.', hint: 'Send the full list you want (read it first with requirements_get).' },
+  department_scope_denied: { field: 'owner', message: 'As a department head you can hand this task only to people in your department (or yourself) and to their Agents.', hint: 'Pick someone from your department, or ask an owner / admin to move it to another department.' },
+  department_not_found: { field: 'department_id', message: 'No department with that id in your network(s).', hint: 'Department ids come from GET /api/networks/{id}/departments.' },
   invalid_participants_delta: { field: 'participants_add', message: 'participants_add / participants_remove must each be an array of up to 100 persons ({kind, id}, {kind:"user", username} or {kind:"node", alias}).', hint: PERSON_IDS },
   participants_conflict: { field: 'participants', message: 'participants (replace the whole list) cannot be combined with participants_add / participants_remove.', hint: 'Use participants_add / participants_remove to change a few people, or participants alone to replace the list.' },
   participants_add_remove_overlap: { field: 'participants_remove', message: 'The same person is in both participants_add and participants_remove.', hint: 'Send each person in only one of the two lists.' },

package/src/requirements.ts

@@ -10,11 +10,13 @@ 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, canParticipantEditTask, canSeeTask, canUseProject, deleteTaskGrantsForProject, projectUseResolver,
-  isTaskScoped, PARTICIPANT_EDIT_FIELDS, shouldAuditDenied, taskPermissionsResolver, type TaskCaller,
+  addProjectVisibilityScope, addTaskVisibilityScope, canDeleteTask, canEditTask, deletesAsHeadOnly, headOnlyEditScope, canParticipantEditTask, canSeeTask, canUseProject, deleteTaskGrantsForProject, projectUseResolver,
+  cardAssignedToNode, isTaskScoped, PARTICIPANT_EDIT_FIELDS, shouldAuditDenied, taskPermissionsResolver, type TaskCaller,
 } from "./task-access.js";
-import { notifyParticipantChange } from "./requirement-notify.js";
+import { notifyLeaderDeleted, notifyParticipantChange } from "./requirement-notify.js";
+import { departmentCardsFor, departmentSubtree } from "./department-heads.js";
 import { diffRequirement, ensureRequirementEvents, eventPublic, recordRequirementEvents, type EventRow } from "./requirement-events.js";
 import { ensureNetworkTags, ensureRequirementCompletedAt, ensureRequirementIndexes, ensureRequirementProjects, ensureRequirementSeq, ensureRequirementTombstones, migrateRequirementAgentOwners, migrateRequirementPriorityCheck, nextRequirementSeq } from "./requirements-migrate.js";
 
@@ -92,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。
@@ -824,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 {
     // 领号、插入、记「新建」这条动态在同一个事务里:插入被唯一索引挡下时,号和动态一起回滚,不留空洞。
@@ -861,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)) {
     // 参与人:只放状态和检查项;别的字段点名拒绝。不是参与人 → 与今天一样。
@@ -910,6 +972,15 @@ function patchRequirement(ctx: RequirementsRequestContext, row: Row, body: Recor
   }
   let people;
   try { people = assignments(body, row.network_id, row, hiddenNodeFilter(ctx, row.network_id), ctx.strictOwner === true); } catch (e) { return errorFrom(e); }
+  // RFC-040:只凭负责人身份改这张卡时,负责人 / 负责 Agent 只能交给本部门的人(或自己)/ 本部门成员的 Agent,
+  // 不能把卡推出本部门(推出去等于替别的部门派活)。清空(null)不限制。
+  const headOnly = (has("owner") || has("agent_owner")) ? headOnlyEditScope(caller, row) : null;
+  if (headOnly) {
+    const owner = people.ownerJson ? JSON.parse(people.ownerJson) as PersonRef : null;
+    const agent = people.agentOwnerJson ? JSON.parse(people.agentOwnerJson) as PersonRef : null;
+    if (has("owner") && owner && owner.id !== caller!.userId && !headOnly.users.has(owner.id)) return jsonError("department_scope_denied", 403, { field: "owner" });
+    if (has("agent_owner") && agent && !headOnly.nodes.has(agent.id)) return jsonError("department_scope_denied", 403, { field: "agent_owner" });
+  }
   let projectId = row.project_id;
   if (has("project_id")) {
     try { projectId = projectRef(body.project_id, row.network_id); } catch (e) { return errorFrom(e); }
@@ -1043,6 +1114,23 @@ function listFilters(url: URL, sql: string, params: unknown[], ctx?: Requirement
   if (ref !== null) sql += ` AND external_ref = ?${params.push(ref)}`;
   const parent = q.get("parent_id");
   if (parent !== null) sql += parent === "none" ? " AND parent_id IS NULL" : ` AND parent_id = ?${params.push(parent)}`;
+  // RFC-040:department_id= —— 负责人是这个部门(含下级)的成员、或负责 Agent 归这些成员所有的卡。可见范围照旧由上面的
+  // addTaskVisibilityScope 管,这里只再收窄。部门按调用者看得见的网络找(部门 id 只在网络内唯一)。
+  const dept = q.get("department_id");
+  if (dept !== null) {
+    if (!dept || !/^[A-Za-z0-9_-]{1,64}$/.test(dept)) return jsonError("department_not_found", 400);
+    const networks = ctx ? departmentNetworks(ctx, dept) : [];
+    if (!networks.length) return jsonError("department_not_found", 400);
+    const parts: string[] = [];
+    for (const networkId of networks) {
+      const cards = departmentCardsFor(networkId, departmentSubtree(networkId, dept));
+      const ors: string[] = [];
+      if (cards.users.size) ors.push(`owner_json IN (${[...cards.users].map((id) => `?${params.push(JSON.stringify({ kind: "user", id }))}`).join(", ")})`);
+      if (cards.nodes.size) ors.push(`agent_owner_json IN (${[...cards.nodes].map((id) => `?${params.push(JSON.stringify({ kind: "node", id }))}`).join(", ")})`);
+      if (ors.length) parts.push(`(network_id = ?${params.push(networkId)} AND (${ors.join(" OR ")}))`);
+    }
+    sql += parts.length ? ` AND (${parts.join(" OR ")})` : " AND 1=0";
+  }
   if (q.get("top_level") === "1") sql += " AND parent_id IS NULL";
   // Explicit archived-only wins over the legacy include-all switch.
   // changes=1 看得见「被归档」这一改动:默认连归档的一起回(行上 archived: true),客户端据此把它移出看板。
@@ -1051,6 +1139,13 @@ function listFilters(url: URL, sql: string, params: unknown[], ctx?: Requirement
   return sql;
 }
 
+/** department_id 筛选:调用者作用域里有这个部门的网络。 */
+function departmentNetworks(ctx: RequirementsRequestContext, deptId: string): string[] {
+  const params: unknown[] = [deptId];
+  const sql = addHumanNetworkScope("SELECT DISTINCT network_id FROM network_departments WHERE department_id = ?1", params, ctx.scope);
+  return db.all<{ network_id: string }>(sql, ...params).map((r) => r.network_id);
+}
+
 const LIST_ORDER = " ORDER BY created_at DESC, requirement_id DESC";
 type LightRow = { requirement_id: string; seq?: number | null; network_id: string; created_at: string; title: string; description: string | null; assignee: string | null; tags_json: string | null; project_id: string | null; owner_json: string | null; agent_owner_json: string | null; participants_json: string | null };
 const parseRef = (json: string | null) => { try { return json ? JSON.parse(json) : null; } catch { return null; } };
@@ -1160,7 +1255,7 @@ function deletedSince(ctx: RequirementsRequestContext, sinceIso: string): string
 const EVENTS_PAGE_DEFAULT = 200;
 const EVENTS_PAGE_MAX = 500;
 const EVENTS_SCAN_MAX = 5000;
-type VisibilityRow = { 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 VisibilityRow = { 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 };
 
 function listEvents(ctx: RequirementsRequestContext): Response {
   const networkId = resolveRestWriteNetworkId(ctx.scope, ctx.auth, ctx.isAdmin);
@@ -1187,7 +1282,8 @@ function listEvents(ctx: RequirementsRequestContext): Response {
     let ok = seen.get(id);
     if (ok === undefined) {
       const cols = "network_id, owner_json, participants_json, created_by, created_by_json, project_id";
-      const row = db.get<VisibilityRow>(`SELECT ${cols} FROM requirements WHERE requirement_id = ?1`, id)
+      // agent_owner_json:负责人按「负责 Agent 归本部门成员」也认得这张卡(RFC-040);墓碑表没有这一列。
+      const row = db.get<VisibilityRow>(`SELECT ${cols}, agent_owner_json FROM requirements WHERE requirement_id = ?1`, id)
         ?? db.get<VisibilityRow>(`SELECT ${cols} FROM requirement_tombstones WHERE requirement_id = ?1`, id);
       seen.set(id, ok = !!row && row.network_id === networkId && canSeeTask(caller, row));
     }
@@ -1264,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));
@@ -1382,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;
@@ -1435,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>;
@@ -1456,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);
@@ -1473,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);
@@ -1498,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") {
@@ -1506,6 +1613,7 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
     if (row instanceof Response) return row;
     if (!canWrite(ctx, row.network_id)) return jsonError("permission_denied", 403);
     if (!canDeleteTask(taskCaller(ctx), row)) return taskDenied(ctx, row, "task_delete_denied");
+    const byLeader = deletesAsHeadOnly(taskCaller(ctx), row);
     // 子需求不跟着删:先解挂(变成顶层),再删父卡。
     const deletedAt = new Date().toISOString();
     db.transaction(() => {
@@ -1517,6 +1625,11 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
     });
     // 硬删除以前不留痕(RFC-038 §9.1):记下是谁删了哪张(标题 + 短号),卡本身已经没了。
     if (ctx.auth) logAudit(ctx.auth.userId, ctx.auth.username || null, "requirement_deleted", "requirement", row.requirement_id, JSON.stringify({ title: row.title, seq: row.seq ?? null }).slice(0, 1000), undefined, row.network_id);
+    // RFC-040 Q4:只凭部门负责人身份删的,另记一条并私信卡的负责人(人;没有就私信负责 Agent 的主人)。
+    if (byLeader && ctx.auth) {
+      const notified = notifyLeaderDeleted({ card: row, actorUserId: ctx.auth.userId });
+      logAudit(ctx.auth.userId, ctx.auth.username || null, "requirement_deleted_by_leader", "requirement", row.requirement_id, JSON.stringify({ title: row.title, seq: row.seq ?? null, owner: row.owner_json ? JSON.parse(row.owner_json) : null, agent_owner: row.agent_owner_json ? JSON.parse(row.agent_owner_json) : null, notified }).slice(0, 1000), undefined, row.network_id);
+    }
     return Response.json({ ok: true, deleted: row.requirement_id });
   }
   if (req.method !== "PATCH") return jsonError("not_found", 404);

package/src/rest-explicit-columns-http.test.ts

@@ -32,6 +32,8 @@ const GOLDEN_RESPONSE_KEYS = {
   authMeNetwork: [
     "network_id", "network_name", "owner_id", "description", "settings",
     "created_at", "updated_at", "visibility", "max_members", "member_role", "agent_access", "task_access",
+    // RFC-040(#455):不是列,是每次请求现算的「我负责的部门 + 全部下级」(department-heads.ts)。
+    "managed_department_ids",
   ],
   networkDetail: [
     "network_id", "network_name", "owner_id", "description", "settings",