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

package/src/departments.ts

@@ -11,6 +11,7 @@
 // 只有空部门(没有子部门、没有成员)能删;负责人必须是本网络成员;人离开网络后,作为负责人的引用读出来是 null。
 
 import { db, logAudit } from "./db.js";
+import { deleteDepartmentGrants, deleteDepartmentGrantsForNetwork } from "./department-heads.js";
 
 try { db.exec("ALTER TABLE network_members ADD COLUMN department_id TEXT"); } catch {}
 db.exec(`
@@ -210,7 +211,11 @@ export function deleteDepartment(networkId: string, id: string): Ok<{ deleted: s
   const children = db.get<{ n: number }>("SELECT COUNT(*) AS n FROM network_departments WHERE network_id = ?1 AND parent_id = ?2", networkId, id)?.n ?? 0;
   const members = db.get<{ n: number }>("SELECT COUNT(*) AS n FROM network_members WHERE network_id = ?1 AND department_id = ?2", networkId, id)?.n ?? 0;
   if (children || members) return { ...fail(409, "department_not_empty"), children, members };
-  db.run("DELETE FROM network_departments WHERE network_id = ?1 AND department_id = ?2", [networkId, id]);
+  // RFC-040:部门的项目授权(network_department_project_grants)和部门同一事务删掉。
+  db.transaction(() => {
+    db.run("DELETE FROM network_departments WHERE network_id = ?1 AND department_id = ?2", [networkId, id]);
+    deleteDepartmentGrants(networkId, id);
+  });
   return { ok: true, deleted: id };
 }
 
@@ -226,6 +231,7 @@ export function setMemberDepartment(networkId: string, userId: string, departmen
 /** 网络删掉时一起清(和项目授权同一时机调用)。 */
 export function deleteDepartmentsForNetwork(networkId: string): void {
   db.run("DELETE FROM network_departments WHERE network_id = ?1", [networkId]);
+  deleteDepartmentGrantsForNetwork(networkId);
 }
 
 export function auditDepartment(user: { user_id: string; username: string }, action: string, networkId: string, detail: string): void {

package/src/mcp-context-cost-http.test.ts

@@ -0,0 +1,117 @@
+// #476(#469 MCP 审计的最后一项)—— Hub MCP 面的上下文成本。
+//
+// 钉住:
+//   1. tools/list 的总字节有上限(TOOLS_LIST_MAX_BYTES):描述 / 参数说明不能悄悄长回去。每个工具也有上限,
+//      单条工具描述有上限。要加新工具 / 新说明,改这里的数字 —— 改的时候就会被看见。
+//   2. requirements_events 不带 requirement_id(全网动态)默认 50 条、从新到旧、next_cursor 翻更早的;
+//      带 requirement_id 的单卡调用不变(默认 200);REST /api/requirements/events 不变(默认 200,App 用它)。
+//   3. requirements_events 参数严格:不认识的参数 → -32602,列出能用的参数。
+//
+// 跑法:cd server && COMMHUB_DB=/tmp/x.db bun test src/mcp-context-cost-http.test.ts
+//       PG:COMMHUB_TEST_PG_URL=… COMMHUB_PG_EXPERIMENTAL=1(tests/test2123-hub-postgres-ladder 里注册)
+import { afterAll, 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 { register } from "./auth.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("mcp-context-cost requires COMMHUB_DB (or COMMHUB_TEST_PG_URL) before module import");
+
+/**
+ * tools/list 整份 JSON 的字节上限。#476 之前(main,含 #475)74 个工具 76,824 B;修剪后 71,399 B。
+ * 上限留 ~1.1 KB 余量;加工具或加说明超过它,就在这里改数字并在 PR 里说为什么。
+ */
+const TOOLS_LIST_MAX_BYTES = 72_500;
+/** 单个工具(名字 + 描述 + 输入 schema)的上限;最大的是 report_status(节点心跳,~8.4 KB 的遥测结构)。 */
+const TOOL_MAX_BYTES = 9_000;
+/** 单条工具描述的上限(说明写进参数的 describe,或者拆短)。 */
+const DESCRIPTION_MAX_BYTES = 1_000;
+const NETWORK_EVENTS = 80;
+
+let server: any;
+let base = "";
+let token = "", netId = "";
+let close: () => Promise<void>;
+let client: Client;
+const call = async (name: string, args: Record<string, unknown>) => {
+  const r: any = await client.callTool({ name, arguments: args });
+  const text = String(r.content?.[0]?.text ?? "");
+  return r.isError ? { mcpError: true, text } : { ...JSON.parse(text), _bytes: Buffer.byteLength(text, "utf8") };
+};
+let busyId = "";
+
+beforeAll(async () => {
+  const u = register(`ctx_${Date.now()}`, "CtxCost123!", undefined, "seed");
+  token = u.token!; netId = u.network_id!;
+  const s = new McpServer({ name: "ctx", version: "1" });
+  registerTools(s, undefined, null, u.user!.user_id, u.user!.username, false, "tok_user");
+  client = new Client({ name: "ctx-client", version: "1" });
+  const [ct, st] = InMemoryTransport.createLinkedPair();
+  await s.connect(st);
+  await client.connect(ct);
+  close = async () => { await client.close(); await s.close(); };
+  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}`;
+  // 一张卡上 60 条评论(单卡调用要能拿到 > 50 条),再加 20 张卡各一条
+  const busy = await call("requirements_create", { network_id: netId, name: "busy task" });
+  busyId = busy.requirement.id;
+  for (let i = 0; i < 60; i++) expect((await call("requirements_comment", { network_id: netId, id: busyId, text: `进展 ${i}:这一步完成了` })).ok).toBe(true);
+  for (let i = 0; i < NETWORK_EVENTS - 60; i++) {
+    const r = await call("requirements_create", { network_id: netId, name: `task ${i}` });
+    await call("requirements_comment", { network_id: netId, id: r.requirement.id, text: "已开始" });
+  }
+}, 120_000);
+afterAll(async () => { await close?.(); server?.stop?.(true); });
+
+describe("#476 tools/list size", () => {
+  test("total, per tool and per description stay under their ceilings", async () => {
+    const { tools } = await client.listTools();
+    const total = Buffer.byteLength(JSON.stringify({ tools }), "utf8");
+    const sizes = tools.map((t: any) => ({ name: t.name, all: Buffer.byteLength(JSON.stringify(t)), desc: Buffer.byteLength(t.description ?? "") }));
+    sizes.sort((a, b) => b.all - a.all);
+    console.log(`tools/list: ${tools.length} tools, ${total} B; largest ${sizes.slice(0, 3).map(x => `${x.name}=${x.all}`).join(", ")}`);
+    expect(total).toBeLessThanOrEqual(TOOLS_LIST_MAX_BYTES);
+    for (const x of sizes) {
+      expect(x.all, x.name).toBeLessThanOrEqual(TOOL_MAX_BYTES);
+      expect(x.desc, x.name).toBeLessThanOrEqual(DESCRIPTION_MAX_BYTES);
+    }
+  });
+});
+
+describe("#476 requirements_events defaults", () => {
+  test("network-wide: 50 newest by default, next_cursor pages older events", async () => {
+    const p1 = await call("requirements_events", { network_id: netId });
+    expect(p1.events.length).toBe(50);
+    expect(typeof p1.next_cursor).toBe("string");
+    const times = p1.events.map((e: any) => e.at ?? e.created_at);
+    expect([...times].sort().reverse()).toEqual(times);
+    const p2 = await call("requirements_events", { network_id: netId, cursor: p1.next_cursor });
+    const ids = new Set([...p1.events, ...p2.events].map((e: any) => e.id));
+    expect(ids.size).toBe(p1.events.length + p2.events.length);
+    console.log(`network events page of 50: ${p1._bytes} B`);
+    expect(p1._bytes).toBeLessThan(25_000);
+  });
+
+  test("an explicit limit still wins; one task's timeline keeps its old default (200)", async () => {
+    expect((await call("requirements_events", { network_id: netId, limit: 70 })).events.length).toBe(70);
+    const one = await call("requirements_events", { network_id: netId, requirement_id: busyId });
+    expect(one.events.filter((e: any) => e.kind === "comment").length).toBe(60);
+  });
+
+  test("REST GET /api/requirements/events is unchanged (default 200)", async () => {
+    const res = await fetch(`${base}/api/requirements/events?network_id=${netId}`, { headers: { Authorization: `Bearer ${token}` } });
+    const body = await res.json() as any;
+    expect(res.status).toBe(200);
+    expect(body.events.length).toBeGreaterThan(50);
+  });
+
+  test("unknown parameters → -32602 listing the valid ones", async () => {
+    const r = await call("requirements_events", { network_id: netId, task_id: busyId });
+    expect(r.mcpError).toBe(true);
+    expect(r.text).toContain("-32602");
+    expect(r.text).toContain("unknown parameter(s): task_id; valid parameters: network_id, requirement_id, since, limit, cursor");
+  });
+});

package/src/network-token-membership-http.test.ts

@@ -0,0 +1,139 @@
+// #488 —— 网络令牌只在它的用户还是这个网络的成员时有效(RFC-041 §1)。
+//
+// 以前:被移出网络的成员留下的节点令牌照样解析 —— MCP 每个工具都拒(not a member),REST 读却拿得到整个网络
+// (GET /api/status 返回全部名册)。受限成员的令牌本来就在 resolveToken 被拒,但 401 只写 unauthorized。
+//
+// 钉住:
+//   (i)   非成员的网络令牌:每个 REST GET 与 /mcp 都 401,reason = not_network_member(下面 GETS 是逐条探过的读路径)。
+//   (ii)  removeNetworkMember 在同一个事务里吊销这个人在该网络的令牌(revoked_at),别的网络的令牌不动。
+//   (iii) 受限成员的节点令牌:401 带 reason = node_owner_restricted + hint;不认识的令牌只有 unauthorized。
+//   成员的节点令牌、不受限的情况与以前完全一样。
+//
+// 跑法:cd server && COMMHUB_DB=/tmp/x.db bun test src/network-token-membership-http.test.ts
+//       PG:COMMHUB_TEST_PG_URL=… COMMHUB_PG_EXPERIMENTAL=1(tests/test2123-hub-postgres-ladder 里注册)
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { addNetworkMember, createNetworkTokenForNode, createNetwork, register, removeNetworkMember } from "./auth.js";
+import { replaceAgentGrants } from "./agent-access.js";
+import { db } from "./db.js";
+
+const activeDbPath = process.env.COMMHUB_DB ?? (process.env.COMMHUB_TEST_PG_URL ? "postgres" : undefined);
+if (!activeDbPath) throw new Error("network-token-membership requires COMMHUB_DB (or COMMHUB_TEST_PG_URL) before module import");
+
+const stamp = Date.now();
+const PW = "TokenMember123!";
+const OTHER = `other-${stamp}`; // 网络里别人的 Agent —— 出现在响应里 = 读到了不该读的
+let server: any, base = "", net = "", net2 = "", taskId = "";
+const tok: Record<string, string> = {};
+const ids: Record<string, string> = {};
+
+const get = (t: string, path: string) =>
+  fetch(`${base}${path}`, { headers: { Authorization: `Bearer ${t}` } })
+    .then(async (r) => ({ status: r.status, text: await r.text() }));
+const mcp = (t: string, name: string, args: Record<string, unknown>) =>
+  fetch(`${base}/mcp`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${t}`, "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 } }),
+  }).then(async (r) => ({ status: r.status, text: await r.text() }));
+
+// 拿网络令牌能调的 REST GET 读路径(server.ts 里 restScope 之后的每个 GET,加上之前自己解析令牌的 /api/auth/me、/api/networks)。
+const GETS = () => [
+  "/api/auth/me", "/api/networks",
+  `/api/status?network_id=${net}`, `/api/status?light=1`, "/api/servers", "/api/server/unknown/health", "/api/server/unknown/agents",
+  "/api/messages", "/api/messages?scope=user", "/api/stats", "/api/stats/sse", "/api/stats/routes", "/api/server-logs", "/api/audit-log",
+  "/api/task_events", "/api/nodes", `/api/nodes/${ids.other}/config`, "/api/node-create-requests", "/api/host-supervisors",
+  `/api/task/${taskId}`, "/api/tasks", "/api/completions", "/api/dm/threads", "/api/requirements",
+];
+
+beforeAll(async () => {
+  const boss = register(`tm_boss_${stamp}`, PW); net = boss.network_id!; ids.boss = boss.user!.user_id; tok.bossUser = boss.token!;
+  for (const k of ["exm", "rem", "mia", "stay"]) {
+    const u = register(`tm_${k}_${stamp}`, PW); ids[k] = u.user!.user_id;
+    expect(addNetworkMember(net, ids[k], "member", ids.boss, { agentAccess: "all" }).ok).toBe(true);
+    const t = createNetworkTokenForNode(ids[k], net, `${k}-${stamp}`, `n_tm_${k}_${stamp}`);
+    expect(t.ok).toBe(true);
+    tok[k] = t.token!;
+  }
+  // rem 在另一个网络里也有令牌 —— 被移出 net 时那枚不能被一起吊销。
+  const n2 = createNetwork(ids.rem, `tm-net2-${stamp}`); expect(n2.ok).toBe(true); net2 = n2.network_id!;
+  const t2 = createNetworkTokenForNode(ids.rem, net2, `rem2-${stamp}`, `n_tm_rem2_${stamp}`); tok.rem2 = t2.token!;
+
+  ids.other = `n_tm_other_${stamp}`;
+  db.run("INSERT INTO nodes (node_id, node_name, alias, network_id, owner_user_id) VALUES (?1, ?2, ?2, ?3, ?4)", [ids.other, OTHER, net, ids.boss]);
+  db.run("INSERT INTO sessions (resume_id, alias, status, node_id, network_id, server) VALUES (?1, ?2, 'idle', ?3, ?4, 'unknown')", [`r_${ids.other}`, OTHER, ids.other, net]);
+  taskId = `task_tm_${stamp}`;
+  db.run("INSERT INTO tasks (task_id, from_name, to_name, to_node_id, content, status, network_id) VALUES (?1, 'boss', ?2, ?3, 'secret plan', 'pending', ?4)", [taskId, OTHER, ids.other, net]);
+
+  // exm:老数据 —— 成员行没了,令牌还在(移出前的版本不吊销)。rem:走真实的 removeNetworkMember。
+  db.run("DELETE FROM network_members WHERE network_id = ?1 AND user_id = ?2", [net, ids.exm]);
+  expect(removeNetworkMember(net, ids.rem).ok).toBe(true);
+  // mia:铸完令牌后被收窄成只看授权的 Agent。
+  expect(replaceAgentGrants({ networkId: net, userId: ids.mia, grants: [], agentAccess: "granted", actorUserId: ids.boss }).ok).toBe(true);
+
+  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}`;
+}, 60_000);
+afterAll(() => { server?.stop?.(true); });
+
+describe("#488 (i) a network token whose user left the network", () => {
+  test("every REST GET read is 401 not_network_member and leaks nothing", async () => {
+    const leaks: string[] = [];
+    for (const path of GETS()) {
+      const r = await get(tok.exm, path);
+      if (r.status !== 401 || r.text.includes(OTHER) || r.text.includes("secret plan")) leaks.push(`${path} → ${r.status}`);
+      else expect(JSON.parse(r.text).reason).toBe("not_network_member");
+    }
+    expect(leaks).toEqual([]);
+  });
+
+  test("/mcp is 401 too, with the reason", async () => {
+    const r = await mcp(tok.exm, "get_all_status", {});
+    expect(r.status).toBe(401);
+    expect(JSON.parse(r.text).reason).toBe("not_network_member");
+    expect(JSON.parse(r.text).hint).toContain("no longer a member");
+  });
+});
+
+describe("#488 (ii) removeNetworkMember revokes the member's tokens for that network", () => {
+  test("revoked_at is set for that network only, and the token is rejected", async () => {
+    const rows = db.all<{ network_id: string; revoked_at: string | null }>("SELECT network_id, revoked_at FROM api_tokens WHERE user_id = ?1 AND network_id IS NOT NULL", ids.rem);
+    expect(rows.filter((r) => r.network_id === net).length).toBeGreaterThan(0);
+    expect(rows.filter((r) => r.network_id === net).every((r) => !!r.revoked_at)).toBe(true);
+    expect(rows.filter((r) => r.network_id === net2).every((r) => !r.revoked_at)).toBe(true);
+    expect((await get(tok.rem, `/api/status?network_id=${net}`)).status).toBe(401);
+    expect((await get(tok.rem2, "/api/status")).status).toBe(200);
+  });
+});
+
+describe("#488 (iii) a restricted owner's node token says why it is refused", () => {
+  test("401 with reason node_owner_restricted + hint on REST and /mcp", async () => {
+    for (const r of [await get(tok.mia, "/api/status"), await mcp(tok.mia, "report_status", { resume_id: "r", alias: `mia-${stamp}`, status: "idle" })]) {
+      expect(r.status).toBe(401);
+      const body = JSON.parse(r.text);
+      expect(body.reason).toBe("node_owner_restricted");
+      expect(body.hint).toContain("Agent access");
+    }
+    const me = await get(tok.mia, "/api/auth/me");
+    expect(me.status).toBe(401);
+    expect(JSON.parse(me.text).reason).toBe("node_owner_restricted");
+  });
+
+  test("an unknown token gets no reason (nothing to explain, nothing leaked)", async () => {
+    const r = await get("ntok_doesnotexist", "/api/status");
+    expect(r.status).toBe(401);
+    expect(JSON.parse(r.text)).toEqual({ error: "unauthorized" });
+  });
+});
+
+describe("#488 unchanged for members", () => {
+  test("an all-access member's node token reads and heartbeats as before", async () => {
+    const st = await get(tok.stay, `/api/status?network_id=${net}`);
+    expect(st.status).toBe(200);
+    expect(st.text).toContain(OTHER);
+    const hb = await mcp(tok.stay, "report_status", { resume_id: `r_stay_${stamp}`, alias: `stay-${stamp}`, status: "idle" });
+    expect(hb.status).toBe(200);
+    expect(hb.text).toContain('\\"ok\\":true');
+    expect((await get(tok.bossUser, `/api/task/${taskId}`)).status).toBe(200);
+  });
+});

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

@@ -11,10 +11,11 @@ import { aggregateStats, parseStatsQuery, type StatsRow } from "./requirements-s
 import { addHumanNetworkScope, canRestWriteNetwork, canRestWriteNetworkAsHuman, resolveRestWriteNetworkId, type RestNetworkScope } from "./network-scope.js";
 import { isAgentRestricted, restrictedNetworkIds, visibleAgents } from "./agent-access.js";
 import {
-  addProjectVisibilityScope, addTaskVisibilityScope, canDeleteTask, canEditTask, canParticipantEditTask, canSeeTask, canUseProject, deleteTaskGrantsForProject, projectUseResolver,
+  addProjectVisibilityScope, addTaskVisibilityScope, canDeleteTask, canEditTask, deletesAsHeadOnly, headOnlyEditScope, canParticipantEditTask, canSeeTask, canUseProject, deleteTaskGrantsForProject, projectUseResolver,
   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";
 
@@ -910,6 +911,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 +1053,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 +1078,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 +1194,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 +1221,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));
     }
@@ -1506,6 +1541,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 +1553,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",