@sleep2agi/commhub-server 0.9.0-preview.145 → 0.9.0-preview.147

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.145",
+  "version": "0.9.0-preview.147",
   "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and MCP tools (17 collaboration-core + node/provider ops tools; authoritative list: docs-site/docs/api/mcp-tools.md).",
   "type": "module",
   "main": "src/index.ts",

package/src/departments-mcp.test.ts

@@ -0,0 +1,128 @@
+// #1894 —— 组织架构的 MCP 面：Agent 用 API 就能建部门、把 Agent 归进去，
+// 不用人手动点。这里跑的是真实的 in-process MCP transport（不是直接调函数），
+// 因为要验的正是「工具真的注册上、参数真的能过 schema、权限真的按 caller 判」。
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { db } from "./db.js";
+import { registerTools } from "./tools.js";
+
+const NET = "net_dept_mcp";
+const OWNER = "u_dept_mcp_owner";
+const OTHER = "u_dept_mcp_other";
+const AGENT_A = "n_dept_mcp_a";
+const AGENT_B = "n_dept_mcp_b";
+
+function cleanup() {
+  for (const [table, col] of [
+    ["audit_log", "network_id"], ["nodes", "network_id"], ["network_departments", "network_id"],
+    ["network_members", "network_id"], ["networks", "network_id"],
+  ] as const) {
+    try { db.run(`DELETE FROM ${table} WHERE ${col} = ?1`, [NET]); } catch {}
+  }
+  try { db.run("DELETE FROM users WHERE user_id IN (?1, ?2)", [OWNER, OTHER]); } catch {}
+}
+
+function seed() {
+  cleanup();
+  db.run("INSERT INTO users (user_id, username, password_hash, role, created_at) VALUES (?1, ?2, 'x', 'user', datetime('now'))", [OWNER, OWNER]);
+  db.run("INSERT INTO users (user_id, username, password_hash, role, created_at) VALUES (?1, ?2, 'x', 'user', datetime('now'))", [OTHER, OTHER]);
+  db.run("INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?2, ?3, datetime('now'))", [NET, NET, OWNER]);
+  db.run("INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, 'owner', datetime('now'))", [OWNER, NET]);
+  db.run("INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, 'member', datetime('now'))", [OTHER, NET]);
+  for (const [id, alias] of [[AGENT_A, "dept-agent-a"], [AGENT_B, "dept-agent-b"]] as const) {
+    db.run("INSERT INTO nodes (node_id, node_name, alias, network_id, created_at, updated_at) VALUES (?1, ?2, ?2, ?3, datetime('now'), datetime('now'))", [id, alias, NET]);
+  }
+}
+
+async function connect(callerUserId: string, alias = "dept-agent-a") {
+  const server = new McpServer({ name: "dept-mcp-test", version: "1" });
+  registerTools(server, undefined, NET, callerUserId, alias, true, null);
+  const client = new Client({ name: "dept-mcp-client", version: "1" });
+  const [ct, st] = InMemoryTransport.createLinkedPair();
+  await server.connect(st);
+  await client.connect(ct);
+  return { client, server };
+}
+
+type Result = { content: Array<{ type: string; text?: string }>; isError?: boolean };
+const json = (r: Result) => JSON.parse(String(r.content[0]?.text ?? "{}"));
+
+beforeEach(seed);
+afterAll(cleanup);
+
+describe("#1894 departments over MCP", () => {
+  test("owner can list, create, assign and read back the counts", async () => {
+    const { client, server } = await connect(OWNER);
+    try {
+      const before = json(await client.callTool({ name: "departments", arguments: { action: "list" } }) as Result);
+      expect(before.ok).toBe(true);
+      expect(before.unassigned_agents).toBe(2);
+
+      const created = json(await client.callTool({
+        name: "departments", arguments: { action: "create", name: "TMAI", department_id: "dept_test_tmai" },
+      }) as Result);
+      expect(created.ok).toBe(true);
+      expect(created.department.id).toBe("dept_test_tmai");
+
+      const child = json(await client.callTool({
+        name: "departments", arguments: { action: "create", name: "TMAI-内容", parent_id: "dept_test_tmai" },
+      }) as Result);
+      expect(child.ok).toBe(true);
+      expect(child.department.parent_id).toBe("dept_test_tmai");
+
+      const assigned = json(await client.callTool({
+        name: "departments", arguments: { action: "assign_agent", alias: "dept-agent-a", department_id: "dept_test_tmai" },
+      }) as Result);
+      expect(assigned.ok).toBe(true);
+      expect(assigned.node_id).toBe(AGENT_A);
+
+      const after = json(await client.callTool({ name: "departments", arguments: { action: "list" } }) as Result);
+      expect(after.unassigned_agents).toBe(1);
+      const tmai = after.departments.find((d: any) => d.id === "dept_test_tmai");
+      expect(tmai.agent_count).toBe(1);
+      const agent = after.agents.find((a: any) => a.node_id === AGENT_A);
+      expect(agent.department_id).toBe("dept_test_tmai");
+
+      // 清空归属同样要能通过 API 做
+      const cleared = json(await client.callTool({
+        name: "departments", arguments: { action: "assign_agent", node_id: AGENT_A, department_id: null },
+      }) as Result);
+      expect(cleared.ok).toBe(true);
+      expect(cleared.department_id).toBeNull();
+    } finally {
+      await server.close();
+    }
+  });
+
+  test("a plain member cannot write departments", async () => {
+    const { client, server } = await connect(OTHER, "dept-agent-b");
+    try {
+      const read = json(await client.callTool({ name: "departments", arguments: { action: "list" } }) as Result);
+      expect(read.ok).toBe(true);
+      const created = json(await client.callTool({
+        name: "departments", arguments: { action: "create", name: "不该被建出来" },
+      }) as Result);
+      expect(created.ok).toBe(false);
+      const assigned = json(await client.callTool({
+        name: "departments", arguments: { action: "assign_agent", node_id: AGENT_B, department_id: null },
+      }) as Result);
+      expect(assigned.ok).toBe(false);
+    } finally {
+      await server.close();
+    }
+  });
+
+  test("deleting a department that still has agents is refused", async () => {
+    const { client, server } = await connect(OWNER);
+    try {
+      json(await client.callTool({ name: "departments", arguments: { action: "create", name: "B 站", department_id: "dept_test_b" } }) as Result);
+      json(await client.callTool({ name: "departments", arguments: { action: "assign_agent", node_id: AGENT_B, department_id: "dept_test_b" } }) as Result);
+      const refused = json(await client.callTool({ name: "departments", arguments: { action: "delete", department_id: "dept_test_b" } }) as Result);
+      expect(refused.ok).toBe(false);
+    } finally {
+      await server.close();
+    }
+  });
+});

package/src/departments.ts

@@ -218,11 +218,14 @@ export function updateDepartment(networkId: string, id: string, body: Record<str
 }
 
 /** 只删空部门:有子部门 / 有成员 → 409(带数字,界面照着说)。 */
-export function deleteDepartment(networkId: string, id: string): Ok<{ deleted: string }> | (Fail & { children?: number; members?: number }) {
+export function deleteDepartment(networkId: string, id: string): Ok<{ deleted: string }> | (Fail & { children?: number; members?: number; agents?: number }) {
   if (!one(networkId, id)) return fail(404, "department_not_found");
   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 };
+  // #1894 —— Agent 的部门归属是 nodes.department_id（显式归属线）。以前只数人类成员，
+  // 于是「部门里还有 300 个 Agent」也能被删掉，留下指向不存在部门的悬空归属。
+  const agents = db.get<{ n: number }>("SELECT COUNT(*) AS n FROM nodes WHERE network_id = ?1 AND department_id = ?2", networkId, id)?.n ?? 0;
+  if (children || members || agents) return { ...fail(409, "department_not_empty"), children, members, agents };
   // RFC-040:部门的项目授权(network_department_project_grants)和部门同一事务删掉。
   groupTx(() => {
     db.run("DELETE FROM network_departments WHERE network_id = ?1 AND department_id = ?2", [networkId, id]);

package/src/health-redaction.test.ts

@@ -640,3 +640,46 @@ describe("#506 cross-network isolation of /health sse_sessions (same alias, two
     expect(keys.some((k) => k.startsWith(`${aNet}:`))).toBe(false);
   });
 });
+
+// #2149 —— 错误路径**不能回显凭据**。
+//
+// 背景：2026-10-23 TMA云鲸 对 CommHub MCP 做只读扫描时收到 502，代理生成的
+// 非 JSON 错误页把本次请求的鉴权相关头回显在正文里。那个 502 页很可能来自
+// 调用链上的代理（本仓没有 502 生成逻辑），但**这条防线必须在本仓也有**：
+// 任何 4xx/5xx 的响应体都不该把调用方递上来的 `Authorization` / `Cookie` /
+// query 里的 token 原样吐回去 —— 一旦有人写出这种错误文案，它就会进日志、
+// 进回执、进诊断归档。
+//
+// 做法是**注入一个形状像真凭据的 canary**，然后打一圈错误路径，断言响应正文
+// 里一次都不出现它。canary 用 `ntok_` 前缀，正是本仓 `redactTokens` 认得的形状。
+describe("#2149 error paths never echo credentials", () => {
+  const CANARY = "ntok_LEAKCANARY_0123456789abcdef";
+  const COOKIE = "session=COOKIELEAKCANARY0123456789";
+
+  const paths: Array<{ method: string; path: string; body?: string }> = [
+    { method: "GET", path: "/api/nope-not-a-route" },
+    { method: "GET", path: "/api/requirements" },
+    { method: "GET", path: "/api/nodes" },
+    { method: "POST", path: "/mcp", body: "{not json" },
+    { method: "POST", path: "/api/auth/login", body: JSON.stringify({ username: "nobody", password: "wrong-password-Aa1!" }) },
+    { method: "POST", path: "/api/auth/me/avatar/upload" },
+  ];
+
+  test("no 4xx/5xx body contains the presented token, cookie or query secret", async () => {
+    for (const c of paths) {
+      const res = await fetch(`${BASE}${c.path}${c.path.includes("?") ? "&" : "?"}access_token=${CANARY}`, {
+        method: c.method,
+        headers: {
+          authorization: `Bearer ${CANARY}`,
+          cookie: COOKIE,
+          "content-type": "application/json",
+        },
+        body: c.body,
+      });
+      const text = await res.text();
+      expect(text.includes(CANARY)).toBe(false);
+      expect(text.includes("LEAKCANARY")).toBe(false);
+      expect(text.includes("COOKIELEAKCANARY")).toBe(false);
+    }
+  });
+});

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

@@ -29,7 +29,11 @@ if (!activeDbPath) throw new Error("mcp-context-cost requires COMMHUB_DB (or COM
 // Hub #938 clone_node is audience both (60 tools / 58,169 B). OpenCode V2
 // catalog adds read_opencode_catalog and get_opencode_catalog on that user
 // list. Measured together: 62 tools / 59,409 B. Ceiling keeps ~401 B.
-const TOOLS_LIST_MAX_BYTES = 59_810;
+// #1894（2026-10-23）：新增 `departments` 一个工具（组织架构的 list/create/update/
+// delete/assign_agent 合并成一个，避免 5 个工具把上下文顶穿）。实测 63 个工具
+// 60,089 B，比原上限高 279 B —— 这是**有意的功能增长**，不是描述悄悄变长，
+// 所以显式抬到 60_500（留 411 B 余量）并在同一行写清理由。
+const TOOLS_LIST_MAX_BYTES = 60_500;
 /** 单个工具(名字 + 描述 + 输入 schema)的上限;最大的是 report_status(节点心跳,~8.4 KB 的遥测结构)。 */
 const TOOL_MAX_BYTES = 9_000;
 /** 单条工具描述的上限(说明写进参数的 describe,或者拆短)。 */

package/src/node-permissions.ts

@@ -269,6 +269,8 @@ export const NODE_TOOL_CLASS: Readonly<Record<string, ToolClass>> = {
   broadcast: "broadcast",
   // 任务看板:在 requirements.ts 里按卡判(REST 与 MCP 同一处)
   requirements_list: "requirements", requirements_people: "requirements", requirements_get: "requirements", requirements_create: "requirements",
+  // #1894 —— 组织架构：读是常规读，写由工具内部再判网络 owner/admin（普通成员/节点写会被拒并 audit）。
+  departments: "requirements",
   requirements_update: "requirements", requirements_checklist_toggle: "requirements", requirements_upsert_by_external_ref: "requirements",
   requirements_events: "requirements", requirements_comment: "requirements", projects_list: "requirements",
   // 定时任务(#733):在 schedule-agent.ts 里按排程判(范围 / 目标 = send_task 的 dispatchVerdict / 配额)

package/src/schedule-agent-mcp-http.test.ts

@@ -312,13 +312,23 @@ describe("old clients unaffected", () => {
 });
 
 describe("scheduler re-checks the creating node as it is now", () => {
+  // #2115 —— `at` 原来是 `now - 5s - random(0..1000ms)`：两次调用只要「晚的毫秒差」正好等于两个
+  // 随机值之差，算出的 `at` 就完全相同，于是第二次按 `scheduled_for = at` 读到的是**上一轮那行**
+  // （于是 test638 L2 并发聚合偶发「期望 creator_node_gone、得到 creator_node_readonly」）。
+  // 注释里说「随机」的人以为碰撞概率是 1/1000，其实是「随机差 == 时间差」，慢机器上时间差几十毫秒
+  // 就落在这个窗口里。改成单调递推：每次减 1s，任何两次调用都不可能相等。
+  let dueSeq = 0;
   const dueAndRun = async (id: string) => {
-    const at = new Date(Date.now() - 5_000 - Math.floor(Math.random() * 1000)).toISOString();
+    dueSeq += 1;
+    const at = new Date(Date.now() - 5_000 - dueSeq * 1_000).toISOString();
     db.run("UPDATE scheduled_tasks SET next_run_at = ?1 WHERE schedule_id = ?2", [at, id]);
     const { runDueScheduledTasks } = await import("./scheduled-tasks.js");
     runDueScheduledTasks();
-    return db.get<{ status: string; error_code: string | null; task_id: string | null }>(
-      "SELECT status, error_code, task_id FROM scheduled_task_runs WHERE schedule_id = ?1 AND scheduled_for = ?2", id, at)!;
+    const row = db.get<{ status: string; error_code: string | null; task_id: string | null }>(
+      "SELECT status, error_code, task_id FROM scheduled_task_runs WHERE schedule_id = ?1 AND scheduled_for = ?2", id, at);
+    // 把「这一轮根本没跑出 run 行」和「跑出了但结论不对」分开报 —— 前者是夹具问题，后者才是行为问题。
+    expect(row).toBeTruthy();
+    return row!;
   };
   test("owner changes to a user not granted the target: send_task denied, and so is every scheduled run", async () => {
     const id = (await create("a", { target_node_id: node.b.id })).schedule.schedule_id;

package/src/server.ts

@@ -99,7 +99,7 @@ import { handleSideThreadHttpRequest } from "./side-thread-http.js";
 import { createProductionSideThreadTransport } from "./side-thread-production.js";
 import { parseHubTimestamp } from "./hub-timestamp";
 import { logTaskRejection } from "./task-rejection-log.js";
-import { AVATAR_FIELD, avatarUrl, inspectAvatarImage, isMultipart, isValidAvatarVersion, MAX_AVATAR_BYTES } from "./user-avatar-image.js";
+import { AVATAR_FIELD, avatarUrl, inspectAvatarImage, isMultipart, isValidAvatarVersion, MAX_AVATAR_BYTES, MAX_AVATAR_STORAGE_BYTES } from "./user-avatar-image.js";
 
 const PORT = resolvePort(process.env.PORT);
 const HOST = process.env.HOST || "127.0.0.1";
@@ -1553,6 +1553,14 @@ return Bun.serve({
         return withCors(req, Response.json({ ok: false, error: "invalid_avatar_body", reason: "expected exactly one `file` part" }, { status: 400 }));
       }
       if (file.size > MAX_AVATAR_BYTES) return withCors(req, Response.json({ ok: false, error: "too_large" }, { status: 413 }));
+      // #2054 —— Hub-wide 总容量上界：公开注册可无限建账号，per-user 单条上限挡不住
+      // 「轮换账号把主库撑大」。这里在**写入前**用当前总量 + 本次大小判一次；
+      // 已存在的其他用户头像绝不删除（不回收别人的数据），只拒绝本次上传。
+      const storedBytes = db.get<{ total: number }>("SELECT COALESCE(SUM(bytes), 0) AS total FROM user_avatar_uploads")?.total ?? 0;
+      const ownBytes = db.get<{ bytes: number }>("SELECT bytes FROM user_avatar_uploads WHERE user_id = ?1", [resolved.user.user_id])?.bytes ?? 0;
+      if (storedBytes - ownBytes + file.size > MAX_AVATAR_STORAGE_BYTES) {
+        return withCors(req, Response.json({ ok: false, error: "avatar_storage_full" }, { status: 503 }));
+      }
       const bytes = new Uint8Array(await file.arrayBuffer());
       const check = inspectAvatarImage(bytes);
       if (!check.ok) return withCors(req, Response.json({ ok: false, error: "invalid_image", reason: check.reason }, { status: 400 }));

package/src/tool-audience-http.test.ts

@@ -207,7 +207,11 @@ describe("bytes per role (#476 ceilings stay meaningful per role)", () => {
   // tools. Measured on this combined tree: all 95 / 85,069 B; node 62 / 63,281 B
   // unchanged (protocol tools stay off the node list); user 62 / 59,409 B.
   // Ceilings keep about 400 B and nothing else.
-  const CEILINGS = { node: 63_700, user: 59_810, all: 85_500 } as const;
+  // #1894（2026-10-23）：新增一个 `departments` MCP 工具（list/create/update/delete/
+  // assign_agent 合并成一个，尽量小）。实测 node 64,112 B / user 60,117 B，比原上限
+  // 分别高 412 / 279 B —— 这是有意的功能增长（组织架构可由 Agent 直接调），不是文案偷偷变长。
+  // 留约 400 B 余量；再要加工具时请先合并动作或砍描述，别连续抬上限。
+  const CEILINGS = { node: 64_500, user: 60_500, all: 86_500 } as const;
   test("node / user / all", async () => {
     const node = await listTools(T.node_normal);
     const user = await listTools(T.owner);

package/src/tool-audience.ts

@@ -59,6 +59,8 @@ export const TOOL_AUDIENCE: Readonly<Record<string, ToolAudience>> = {
   upsert_network_secret: "both", list_network_secrets: "both", upsert_provider: "both", update_provider: "both",
   list_providers: "both", probe_provider_model: "both", get_probe_results: "both",
   requirements_list: "both", requirements_people: "both", requirements_get: "both", requirements_create: "both",
+  // #1894 —— 组织架构：人和 Agent 都能用（Agent 用它归部门，人用它看树）。
+  departments: "both",
   requirements_update: "both", requirements_checklist_toggle: "both", requirements_upsert_by_external_ref: "both",
   requirements_events: "both", requirements_comment: "both", projects_list: "both",
 };

package/src/tools-list-json-schema.test.ts

@@ -65,3 +65,30 @@ describe("#1756 tools/list", () => {
     } finally { await close(); }
   }, 20_000);
 });
+
+// #1075 / #2662 —— `node_secrets_capable` 是**节点自述**的一格，运行时把它放在
+// `config_snapshot` 里（agent-node/src/cli.ts:1894）。而 zod 对象默认**丢掉未声明
+// 的键**：只要 `config_snapshot` 的形状里没有这一条，节点上报得再好，到 Hub 也被
+// 静默剥掉 → 客户端「保存密钥」永远是灰的，日志里一个字都不会说。
+//
+// 所以钉在这里：`report_status.config_snapshot` 的形状里**必须有**这一格。
+// 剥掉它的方式有很多种（重写对象、加 .strict()、换 z.record），这条断言对它们都红。
+describe("#1075 node_secrets_capable survives report_status", () => {
+  test("config_snapshot's shape declares node_secrets_capable", async () => {
+    const { server, close } = await connect();
+    try {
+      const reg: Record<string, any> = (server as any)._registeredTools;
+      const shape = reg["report_status"]?.inputSchema?.shape ?? {};
+      const snapshotField = shape["config_snapshot"];
+      expect(snapshotField).toBeTruthy();
+      // config_snapshot 是 ZodOptional 包着 ZodObject：.unwrap() 之后才有 shape。
+      const unwrapped = (snapshotField as any)?.unwrap ? (snapshotField as any).unwrap() : snapshotField;
+      const inner = (unwrapped as any)?.shape ?? {};
+      expect(Object.keys(inner)).toContain("node_secrets_capable");
+      // 同族的另一格（daemon 级能力）也在这份形状里，顺手一起钉住。
+      expect(Object.keys(inner)).toContain("daemon_capabilities");
+    } finally {
+      await close();
+    }
+  });
+});

package/src/tools.ts

@@ -107,6 +107,7 @@ import { dispatchQueueInfo, queueDepthByNode, queueDepthKey } from "./task-queue
 import { parseHubTimestamp } from "./hub-timestamp";
 import { noteTerminalResultRead, purgeLogsResultNow, sweepNodeRequestContent } from "./node-request-retention.js";
 import { listTaskLateReplies } from "./task-late-replies.js";
+import { auditDepartment, createDepartment, deleteDepartment, listDepartments, setAgentDepartment, updateDepartment } from "./departments.js";
 
 function ts(): string {
   return new Date().toTimeString().slice(0, 8);
@@ -425,6 +426,96 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     content: [{ type: "text" as const, text: JSON.stringify(value) }],
   });
 
+  // ── #1894 组织架构：Agent 用 API 就能建部门、把 Agent 归进去（admin 2026-10-23：
+  // 不要靠人手动点）。写权限 = 网络 owner/admin（实测 `canWrite` 对普通成员也是 true，
+  // 口径太宽，所以这里显式判角色）；读权限 = 能读这个网络的人。
+  // 归属写的是 nodes.department_id，显式归属，绝不按负责人推断。
+  const deptReply = (value: Record<string, unknown>) => ({
+    content: [{ type: "text" as const, text: JSON.stringify(value) }],
+  });
+  const canManageDepartments = (netId: string | null): boolean => {
+    if (!netId) return false;
+    if (!enforceUserId) return canWrite(netId); // legacy open mode
+    const role = getUserNetworkRole(enforceUserId, netId);
+    return role === "owner" || role === "admin";
+  };
+  const deptFail = (result: any) =>
+    deptReply({ ok: false, error: result?.error ?? "department_failed", status: result?.status ?? 400, ...(result?.children || result?.members || result?.agents ? { children: result.children, members: result.members, agents: result.agents } : {}) });
+
+  server.tool(
+    "departments",
+    "Agent org structure: list / create / update / delete / assign_agent. Writes need network owner or admin; assign_agent sets nodes.department_id.",
+    {
+      action: z.enum(["list", "create", "update", "delete", "assign_agent"]),
+      department_id: z.string().max(64).nullable().optional(),
+      name: z.string().min(1).max(80).optional(),
+      parent_id: z.string().max(64).nullable().optional(),
+      node_id: z.string().max(200).optional(),
+      alias: z.string().max(200).optional(),
+      network_id: z.string().max(200).optional(),
+    },
+    async ({ action, department_id, name, parent_id, node_id, alias, network_id: clientNetId }) => {
+      const netId = getNetworkId(clientNetId);
+      if (!netId) return deptReply({ ok: false, error: "network_required" });
+      if (action === "list") {
+        if (!canManageDepartments(netId) && !canWriteHuman(netId)) return writeDeniedReply(netId, "read") as any;
+        const listed = listDepartments(netId);
+        const agents = db.all<{ node_id: string; alias: string; department_id: string | null }>(
+          "SELECT node_id, alias, department_id FROM nodes WHERE network_id = ?1 ORDER BY alias", netId,
+        );
+        const counts = new Map<string, number>();
+        let unassigned = 0;
+        for (const a of agents) {
+          if (a.department_id) counts.set(a.department_id, (counts.get(a.department_id) ?? 0) + 1);
+          else unassigned += 1;
+        }
+        return deptReply({
+          ok: true, network_id: netId, unassigned_agents: unassigned, agents,
+          departments: listed.departments.map((d) => ({ ...d, agent_count: counts.get(d.id) ?? 0 })),
+        });
+      }
+      if (!canManageDepartments(netId)) return writeDeniedReply(netId, "write") as any;
+      const actor = { user_id: enforceUserId || "node", username: callerAlias || "agent" };
+      if (action === "create") {
+        if (!name) return deptReply({ ok: false, error: "invalid_department_name" });
+        const result = createDepartment(netId, enforceUserId || callerAlias || "mcp", {
+          name, ...(parent_id ? { parent_id } : {}), ...(department_id ? { id: department_id } : {}),
+        }) as any;
+        if (result?.ok === false) return deptFail(result);
+        auditDepartment(actor, "department_create", netId, String(result.department?.id ?? ""));
+        return deptReply({ ok: true, department: result.department });
+      }
+      if (action === "update") {
+        if (!department_id) return deptReply({ ok: false, error: "department_required" });
+        const body: Record<string, unknown> = {};
+        if (name !== undefined) body.name = name;
+        if (parent_id !== undefined) body.parent_id = parent_id;
+        const result = updateDepartment(netId, department_id, body) as any;
+        if (result?.ok === false) return deptFail(result);
+        auditDepartment(actor, "department_update", netId, `id=${department_id}`);
+        return deptReply({ ok: true, department: result.department });
+      }
+      if (action === "delete") {
+        if (!department_id) return deptReply({ ok: false, error: "department_required" });
+        const result = deleteDepartment(netId, department_id) as any;
+        if (result?.ok === false) return deptFail(result);
+        auditDepartment(actor, "department_delete", netId, `id=${department_id}`);
+        return deptReply({ ok: true, deleted: department_id });
+      }
+      let target = node_id ?? "";
+      if (!target && alias) {
+        const row = db.get<{ node_id: string }>("SELECT node_id FROM nodes WHERE network_id = ?1 AND alias = ?2", netId, resolveCanonicalAlias(netId, alias).alias);
+        if (!row) return deptReply({ ok: false, error: "agent_not_found" });
+        target = row.node_id;
+      }
+      if (!target) return deptReply({ ok: false, error: "agent_required" });
+      const result = setAgentDepartment(netId, target, department_id === undefined ? null : department_id) as any;
+      if (result?.ok === false) return deptFail(result);
+      auditDepartment(actor, "department_assign_agent", netId, `${target} -> ${department_id ?? "null"}`);
+      return deptReply({ ok: true, node_id: result.node_id, department_id: result.department_id });
+    },
+  );
+
   // SkillHub is a network registry, not a public filesystem. Content is an
   // immutable SKILL.md snapshot; identity comes only from the authenticated
   // MCP principal (never from request fields).

package/src/user-avatar-image.ts

@@ -10,6 +10,13 @@ import { inflateSync } from "node:zlib";
 // 校验强度：结构（签名/chunk/CRC）+ 真实解码（IDAT 解压且扫描行长度与 IHDR 相符）。
 
 export const MAX_AVATAR_BYTES = 8 * 1024 * 1024;
+
+/**
+ * #2054 —— 单个 Hub 的头像总存储上界。公开注册可以持续创建账号，per-user 单条
+ * 上限（每人 1 条 × 8 MiB）挡不住轮换账号把主库撑大，所以再加一道总量边界。
+ * 超限时上传返回 503 `avatar_storage_full`；不回收/删除任何既有用户的头像。
+ */
+export const MAX_AVATAR_STORAGE_BYTES = 1024 * 1024 * 1024;
 /** 客户端会把图重编码到最长边 512；服务端独立复核这条上限。 */
 export const MAX_AVATAR_EDGE = 512;
 /** version 只允许 URL 安全字符，长度有界（避免拼路径时引入 `.`、`/`）。 */

package/src/user-avatar-upload-http.test.ts

@@ -292,3 +292,57 @@ test("image inspector: signature, shape and size limits", () => {
   expect(inspectAvatarImage(jpeg)).toEqual({ ok: false, reason: "not_png" });
   expect(inspectAvatarImage(Buffer.alloc(MAX_AVATAR_BYTES + 1))).toEqual({ ok: false, reason: "too_large" });
 });
+
+// #2054 —— Hub-wide 头像总容量上界：公开注册可无限建账号，per-user 单条上限挡不住
+// 轮换账号把主库撑大。这里在库里塞一条接近上界的行，断言上传被 503 拒绝，
+// 且**不删除**任何既有用户的头像（别人的数据不动），随后清掉该行恢复。
+test("account avatar upload: a hub-wide storage cap rejects the write and keeps existing rows", async () => {
+  const { MAX_AVATAR_STORAGE_BYTES } = await import("./user-avatar-image.js");
+  const victim = register("avcap_alice", "AvatarCap1!");
+  const uploader = register("avcap_bob", "AvatarCap1!");
+  expect(victim.ok && uploader.ok).toBe(true);
+
+  const { bootServer } = await import("./server.js");
+  const hub = bootServer({ port: 0, hostname: "127.0.0.1" });
+  const base = `http://127.0.0.1:${hub.port}`;
+  const upload = async (token: string, bytes: Buffer) => {
+    const form = new FormData();
+    form.append("file", new Blob([bytes], { type: "image/png" }), "a.png");
+    const res = await fetch(`${base}/api/auth/me/avatar/upload`, {
+      method: "POST", headers: { Authorization: `Bearer ${token}` }, body: form,
+    });
+    return { status: res.status, body: (await res.json().catch(() => null)) as any };
+  };
+
+  const filler = Buffer.from("filler-avatar-bytes");
+  try {
+    // 先让 bob 正常上传一次，证明上界不是「谁都不能传」。
+    const ok = await upload(uploader.token!, PNG_1X1);
+    expect(ok.status).toBe(200);
+
+    // 塞一条「别人已经占满」的行：总量逼到上界之上。
+    db.run(
+      "INSERT INTO user_avatar_uploads (user_id, version, png, bytes, width, height, updated_at) VALUES (?1, ?2, ?3, ?4, 1, 1, datetime('now'))",
+      [victim.user!.user_id, "capver", filler, MAX_AVATAR_STORAGE_BYTES],
+    );
+    const before = db.get<{ n: number }>("SELECT COUNT(*) AS n FROM user_avatar_uploads")!.n;
+
+    const blocked = await upload(uploader.token!, PNG_1X1);
+    expect(blocked.status).toBe(503);
+    expect(blocked.body.error).toBe("avatar_storage_full");
+
+    // 不回收别人的数据：行数与那条 filler 都还在。
+    const after = db.get<{ n: number }>("SELECT COUNT(*) AS n FROM user_avatar_uploads")!.n;
+    expect(after).toBe(before);
+    expect(db.get<any>("SELECT bytes FROM user_avatar_uploads WHERE user_id = ?1", [victim.user!.user_id])?.bytes)
+      .toBe(MAX_AVATAR_STORAGE_BYTES);
+    // 自己的额度要扣掉：上限全算在自己头上时，替换**自己**的头像不应被拒。
+    db.run("DELETE FROM user_avatar_uploads WHERE user_id = ?1", [victim.user!.user_id]);
+    db.run("UPDATE user_avatar_uploads SET bytes = ?1 WHERE user_id = ?2", [MAX_AVATAR_STORAGE_BYTES, uploader.user!.user_id]);
+    const replaced = await upload(uploader.token!, PNG_1X1);
+    expect(replaced.status).toBe(200);
+  } finally {
+    db.run("DELETE FROM user_avatar_uploads WHERE user_id = ?1", [victim.user!.user_id]);
+    hub.stop?.();
+  }
+});