@sleep2agi/commhub-server 0.9.0-preview.146 → 0.9.0-preview.148

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.146",
+  "version": "0.9.0-preview.148",
   "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/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/requirement-tag-ops-http.test.ts

@@ -208,7 +208,7 @@ describe("改名 / 合并 / 删除 / 颜色", () => {
     const t0 = new Date().toISOString();
     const r = await op(admin.token, { op: "rename", from: "UI", to: "界面" });
     expect(r.status).toBe(200);
-    expect(r.body).toEqual({ ok: true, op: "rename", affected: 4 });
+    expect(r.body).toEqual({ ok: true, op: "rename", affected: 4, reparented: 0 });
     expect(cardTags("visible")).toEqual(["界面", "交互", "bug"]);
     expect(cardTags("hidden")).toEqual(["界面", "secret"]);
     expect(cardTags("archived")).toEqual(["界面", "旧"]);
@@ -237,7 +237,7 @@ describe("改名 / 合并 / 删除 / 颜色", () => {
   test("合并:多个来源进一个新标签;目标没颜色就继承来源的;来源颜色行删掉", async () => {
     expect((await op(admin.token, { op: "color", tag: "旧", color: "#16a34a" })).status).toBe(200);
     const r = await op(admin.token, { op: "merge", from: ["bug", "旧", "secret", "不存在"], to: "杂项" });
-    expect(r.body).toEqual({ ok: true, op: "merge", affected: 3 });
+    expect(r.body).toEqual({ ok: true, op: "merge", affected: 3, reparented: 0 });
     expect(cardTags("visible")).toEqual(["界面", "杂项"]);
     expect(cardTags("hidden")).toEqual(["界面", "杂项"]);
     expect(cardTags("archived")).toEqual(["界面", "杂项"]);
@@ -253,7 +253,7 @@ describe("改名 / 合并 / 删除 / 颜色", () => {
 
   test("删除:从每张卡上拿掉(卡保留),颜色行删掉,审计带 affected", async () => {
     const r = await op(admin.token, { op: "delete", tag: "界面" });
-    expect(r.body).toEqual({ ok: true, op: "delete", affected: 4 });
+    expect(r.body).toEqual({ ok: true, op: "delete", affected: 4, reparented: 0 });
     expect(cardTags("visible")).toEqual([]);
     expect(cardTags("both")).toEqual(["TMWork"]);
     expect(db.get("SELECT COUNT(*) AS n FROM requirements WHERE network_id = ?1", NET).n).toBe(5);

package/src/requirement-tag-tree-http.test.ts

@@ -0,0 +1,275 @@
+// 标签树(POST /api/requirements/tags/create + GET /api/requirements/tags 的 nodes + ops 维护层级)
+// —— HTTP 集成测试(真实 Bun.serve,私有端口,临时库)。
+//
+// 场景:Hub 管理员 admin 的网络 NET,另一个不相干的网络 NET2。成员:
+//   carol —— task_access='all' 的老成员(能管标签);
+//   alice —— scoped 成员(不能管);
+//   vic   —— viewer;
+//   nodeToken —— 节点令牌。
+//
+// 正向:建根标签、建子标签并回读 parent_id/depth;0 任务的子标签能在 nodes 里读到;父只在卡片上出现过时
+//       补登记成顶层(parent_registered=true)且子标签仍挂在它下面;改名 / 合并 / 删除让层级跟着动。
+// 反向:重名 409、父不存在 404(不 root fallback)、超过 4 层 400、scoped / viewer / 节点令牌 403 且一行都不写、
+//       同名标签在别的网络互不相干、坏参数 400、原子性(重名失败后不留半条节点)。
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-tag-tree-"));
+let BASE = "";
+let hub: any = null;
+let db: any = null;
+const PW = "TagTreePassw0rd!x";
+let NET = "";
+let NET2 = "";
+let admin = { token: "", id: "" };
+let other = { token: "", id: "" };
+let alice = { token: "", id: "" };
+let carol = { token: "", id: "" };
+let vic = { token: "", id: "" };
+let nodeToken = "";
+
+type R = { status: number; body: any };
+async function send(token: string, method: string, path: string, payload?: unknown): Promise<R> {
+  const res = await fetch(`${BASE}${path}`, {
+    method,
+    headers: { ...(token ? { Authorization: `Bearer ${token}` } : {}), "Content-Type": "application/json" },
+    body: payload === undefined ? undefined : JSON.stringify(payload),
+  });
+  const text = await res.text();
+  let body: any = null;
+  try { body = JSON.parse(text); } catch {}
+  return { status: res.status, body };
+}
+
+const create = (token: string, payload: unknown, net = NET) => send(token, "POST", `/api/requirements/tags/create?network_id=${net}`, payload);
+const tagsOf = (token: string, net = NET) => send(token, "GET", `/api/requirements/tags?network_id=${net}`);
+const op = (token: string, payload: unknown, net = NET) => send(token, "POST", `/api/requirements/tags/ops?network_id=${net}`, payload);
+const nodesOf = async (token = admin.token, net = NET): Promise<Record<string, { parent: string | null; depth: number; count: number; registered: boolean }>> => {
+  const r = await tagsOf(token, net);
+  expect(r.status).toBe(200);
+  return Object.fromEntries((r.body.nodes ?? []).map((n: any) => [n.name, { parent: n.parent_id, depth: n.depth, count: n.count, registered: n.registered }]));
+};
+const nodeRows = (net = NET) => db.all("SELECT name, parent_name FROM network_tag_nodes WHERE network_id = ?1 ORDER BY name", [net]);
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+  process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+  process.env.HOST = "127.0.0.1";
+  ({ db } = await import("./db.js"));
+  const { createNetworkTokenForNode, register } = await import("./auth.js");
+  const stamp = Date.now();
+  const a = register(`tt_admin_${stamp}`, PW, undefined, "Admin");
+  expect(a.ok).toBe(true);
+  admin = { token: a.token!, id: a.user!.user_id };
+  NET = a.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [admin.id]);
+  const b = register(`tt_other_${stamp}`, PW, undefined, "Other");
+  expect(b.ok).toBe(true);
+  other = { token: b.token!, id: b.user!.user_id };
+  NET2 = b.network_id!;
+  const ntok = createNetworkTokenForNode(admin.id, NET, "tag-node");
+  expect(ntok.ok).toBe(true);
+  nodeToken = ntok.token!;
+
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+
+  const mk = async (username: string, role: string) => {
+    const r = await send(admin.token, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role });
+    expect(r.status).toBe(200);
+    const login = await send("", "POST", "/api/auth/login", { username, password: PW });
+    expect(login.status).toBe(200);
+    return { token: login.body.token as string, id: login.body.user.user_id as string };
+  };
+  alice = await mk(`tt_alice_${stamp}`, "member");
+  carol = await mk(`tt_carol_${stamp}`, "member");
+  vic = await mk(`tt_vic_${stamp}`, "viewer");
+  db.run("UPDATE network_members SET task_access = 'scoped' WHERE network_id = ?1 AND user_id = ?2", [NET, alice.id]);
+  db.run("UPDATE network_members SET task_access = 'all' WHERE network_id = ?1 AND user_id = ?2", [NET, carol.id]);
+
+  // 一张只有 legacy 标签的卡:它的标签没有节点行 —— 用来验证「拿在用标签当父」时补登记。
+  const card = await send(admin.token, "POST", "/api/requirements", { network_id: NET, name: "legacy", tags: ["legacy"] });
+  expect(card.status).toBe(201);
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("capability 与权限", () => {
+  test("列表 capabilities 带 tag_tree(旧客户端忽略)", async () => {
+    const r = await send(admin.token, "GET", `/api/requirements?network_id=${NET}`);
+    expect(r.body.capabilities).toContain("tag_tree");
+  });
+
+  test("scoped / viewer / 节点令牌 403,且一行节点都不写", async () => {
+    for (const token of [alice.token, vic.token, nodeToken]) {
+      const r = await create(token, { name: "被拒" });
+      expect(r.status).toBe(403);
+    }
+    expect(nodeRows()).toEqual([]);
+  });
+
+  test("网络管理员与 task_access='all' 的老成员能建", async () => {
+    const r = await create(carol.token, { name: "carol建的" });
+    expect(r.status).toBe(201);
+    expect(r.body.tag).toEqual({ name: "carol建的", parent_id: null, depth: 1 });
+    const del = await op(admin.token, { op: "delete", tag: "carol建的" });
+    expect(del.status).toBe(200);
+  });
+});
+
+describe("建根标签与子标签", () => {
+  test("建根标签:201,parent_id=null,depth=1", async () => {
+    const r = await create(admin.token, { name: "需求" });
+    expect(r.status).toBe(201);
+    expect(r.body).toMatchObject({ ok: true, tag: { name: "需求", parent_id: null, depth: 1 }, parent_registered: false });
+  });
+
+  test("0 任务的标签也能在 nodes 里读到(count=0,registered=true)", async () => {
+    const nodes = await nodesOf();
+    expect(nodes["需求"]).toEqual({ parent: null, depth: 1, count: 0, registered: true });
+    // tags(卡片上出现过的)保持旧语义:0 任务的标签不在里面
+    const t = await tagsOf(admin.token);
+    expect(t.body.tags).not.toContain("需求");
+  });
+
+  test("建子标签:回读 parent_id / depth / count=0", async () => {
+    const r = await create(admin.token, { name: "前端", parent_id: "需求" });
+    expect(r.status).toBe(201);
+    expect(r.body.tag).toEqual({ name: "前端", parent_id: "需求", depth: 2 });
+    const nodes = await nodesOf();
+    expect(nodes["前端"]).toEqual({ parent: "需求", depth: 2, count: 0, registered: true });
+  });
+
+  test("三代:第 3 层 depth=3;超过 MAX_TAG_DEPTH 的第 4 层子标签 400", async () => {
+    const l3 = await create(admin.token, { name: "按钮", parent_id: "前端" });
+    expect(l3.status).toBe(201);
+    expect(l3.body.tag.depth).toBe(3);
+    const l4 = await create(admin.token, { name: "主按钮", parent_id: "按钮" });
+    expect(l4.status).toBe(201);
+    expect(l4.body.tag.depth).toBe(4);
+    const l5 = await create(admin.token, { name: "太深了", parent_id: "主按钮" });
+    expect(l5.status).toBe(400);
+    expect(l5.body.error).toBe("tag_depth_exceeded");
+    expect(nodeRows().some((r: any) => r.name === "太深了")).toBe(false);
+  });
+
+  test("重名 409:已登记的、卡片上在用的、有颜色行的都算重名;失败不留半条", async () => {
+    expect((await create(admin.token, { name: "需求" })).body.error).toBe("tag_exists");
+    expect((await create(admin.token, { name: "legacy" })).body.error).toBe("tag_exists");
+    // 只有颜色行、没有卡片也没有节点的名字也算存在(直接写库构造这种历史状态)
+    db.run("INSERT INTO network_tags (network_id, name, color, updated_at) VALUES (?1, ?2, ?3, ?4)", [NET, "有颜色的", "#112233", new Date().toISOString()]);
+    const colored = await create(admin.token, { name: "有颜色的" });
+    expect(colored.body.error).toBe("tag_exists");
+    const before = nodeRows();
+    expect(before.map((r: any) => r.name)).not.toContain("有颜色的");
+  });
+
+  test("父不存在 404 tag_parent_not_found —— 不会静默建到根上", async () => {
+    const r = await create(admin.token, { name: "孤儿", parent_id: "不存在的父" });
+    expect(r.status).toBe(404);
+    expect(r.body.error).toBe("tag_parent_not_found");
+    expect(nodeRows().some((row: any) => row.name === "孤儿")).toBe(false);
+  });
+
+  test("父只在卡片上出现过:补登记成顶层节点(parent_registered=true),子标签仍挂在它下面", async () => {
+    const r = await create(admin.token, { name: "legacy子", parent_id: "legacy" });
+    expect(r.status).toBe(201);
+    expect(r.body.parent_registered).toBe(true);
+    expect(r.body.tag).toEqual({ name: "legacy子", parent_id: "legacy", depth: 2 });
+    const nodes = await nodesOf();
+    expect(nodes["legacy"]).toMatchObject({ parent: null, depth: 1 });
+    expect(nodes["legacy子"]).toMatchObject({ parent: "legacy", depth: 2 });
+  });
+
+  test("坏参数 400:空名 / 太长 / 控制字符 / parent_id 不是字符串", async () => {
+    expect((await create(admin.token, { name: "" })).body.error).toBe("invalid_tag");
+    expect((await create(admin.token, { name: "一二三四五六七八九十一二三四五六七八九十多" })).body.error).toBe("invalid_tag");
+    expect((await create(admin.token, { name: "换\n行" })).body.error).toBe("invalid_tag");
+    const bad = await create(admin.token, { name: "正常", parent_id: 42 });
+    expect(bad.status).toBe(400);
+    expect(bad.body.error).toBe("invalid_tag_parent_id");
+    expect((await create(admin.token, {})).body.error).toBe("invalid_tag");
+  });
+
+  test("别的网络同名互不相干:NET2 里能再建「需求」,NET 的树不受影响", async () => {
+    const r = await create(other.token, { name: "需求" }, NET2);
+    expect(r.status).toBe(201);
+    expect(r.body.tag.depth).toBe(1);
+    expect((await nodesOf(admin.token, NET2))["需求"]).toMatchObject({ parent: null, depth: 1 });
+    expect((await nodesOf(admin.token, NET))["前端"]).toMatchObject({ parent: "需求", depth: 2 });
+  });
+
+  test("受限成员的 nodes 只含他看得见的标签(登记过但没有可见卡的名字不外泄)", async () => {
+    const r = await tagsOf(alice.token);
+    expect(r.status).toBe(200);
+    expect(r.body.nodes).toEqual([]);
+    expect(r.body.can_manage).toBe(false);
+  });
+});
+
+describe("改名 / 合并 / 删除让层级跟着动", () => {
+  test("rename:节点与子节点的 parent 一起改,深度不变", async () => {
+    const r = await op(admin.token, { op: "rename", from: "需求", to: "需求池" });
+    expect(r.status).toBe(200);
+    const nodes = await nodesOf();
+    expect(nodes["需求池"]).toMatchObject({ parent: null, depth: 1 });
+    expect(nodes["前端"]).toMatchObject({ parent: "需求池", depth: 2 });
+    expect(nodes["按钮"]).toMatchObject({ parent: "前端", depth: 3 });
+    expect(nodes["需求"]).toBeUndefined();
+  });
+
+  test("rename 到已存在的节点 = 合并:来源的子节点挂到目标,且不会自环", async () => {
+    await create(admin.token, { name: "临时" });
+    await create(admin.token, { name: "临时子", parent_id: "临时" });
+    const r = await op(admin.token, { op: "rename", from: "临时", to: "需求池" });
+    expect(r.status).toBe(200);
+    const nodes = await nodesOf();
+    expect(nodes["临时子"]).toMatchObject({ parent: "需求池", depth: 2 });
+    // 目标是来源的子孙时不能自环:把「前端」并到它的子节点「按钮」上
+    await op(admin.token, { op: "rename", from: "前端", to: "按钮" });
+    const after = await nodesOf();
+    expect(after["按钮"].parent).not.toBe("按钮");
+    expect(nodeRows().every((row: any) => row.name !== row.parent_name)).toBe(true);
+  });
+
+  test("merge:来源节点的子节点挂到目标,来源节点删掉", async () => {
+    await create(admin.token, { name: "源A" });
+    await create(admin.token, { name: "源A子", parent_id: "源A" });
+    await create(admin.token, { name: "目标B" });
+    const r = await op(admin.token, { op: "merge", from: ["源A"], to: "目标B" });
+    expect(r.status).toBe(200);
+    expect(r.body.reparented).toBe(1);
+    const nodes = await nodesOf();
+    expect(nodes["源A"]).toBeUndefined();
+    expect(nodes["源A子"]).toMatchObject({ parent: "目标B", depth: 2 });
+  });
+
+  test("delete:子节点挂到被删节点的父(没有父就成根),不丢层级", async () => {
+    const before = await nodesOf();
+    const r = await op(admin.token, { op: "delete", tag: "按钮" });
+    expect(r.status).toBe(200);
+    const nodes = await nodesOf();
+    // 「按钮」的父是「需求池」(rename 之后),所以「主按钮」挂到「需求池」
+    expect(nodes["主按钮"].parent).toBe(before["按钮"].parent);
+    expect(nodes["按钮"]).toBeUndefined();
+  });
+
+  test("0 任务的节点也能上色,改名时颜色跟着走(#tag/ops 不再只认卡片)", async () => {
+    await create(admin.token, { name: "上色前" });
+    const c = await op(admin.token, { op: "color", tag: "上色前", color: "#ABCDEF" });
+    expect(c.status).toBe(200);
+    expect((await tagsOf(admin.token)).body.colors["上色前"]).toBe("#abcdef");
+    const r = await op(admin.token, { op: "rename", from: "上色前", to: "上色后" });
+    expect(r.status).toBe(200);
+    const after = await tagsOf(admin.token);
+    expect(after.body.colors["上色后"]).toBe("#abcdef");
+    expect(after.body.colors["上色前"]).toBeUndefined();
+  });
+});

package/src/requirement-tag-tree.ts

@@ -0,0 +1,97 @@
+// 标签树(父子标签)。标签本身仍然只是卡片 tags_json 里的字符串(见 requirement-tags.ts);
+// 这里只多存两件事:
+//   ① 谁挂在谁下面 —— network_tag_nodes(network_id, name, parent_name);
+//   ② 创建过但还没有任何卡片用的标签 —— 否则 0 任务的子标签在 GET /tags 里读不到(它只会数卡片)。
+// 语义:网络内标签名就是 id(没有 tag_id),parent_name 指向父标签名;改名时父引用跟着改。
+// 深度上限 MAX_TAG_DEPTH(含根)。父不存在 = 报错,不静默挂到根上。
+import { tagName } from "./requirement-tags.js";
+
+/** 最多 4 层(顶层是第 1 层)。比子需求(5 层)浅一层:侧栏要一屏放得下父子孙。 */
+export const MAX_TAG_DEPTH = 4;
+
+/** 客户端用这个 capability 判断 Hub 有没有「创建标签 / 父标签」;没有就灰掉入口,别调用。 */
+export const TAG_TREE_CAPABILITY = "tag_tree";
+
+export type TagNodeRow = { name: string; parent_name: string | null };
+
+export type TagNodePublic = {
+  name: string;
+  parent_id: string | null;
+  depth: number;
+  /** 这张标签是不是「登记过」的节点(create 建的、或被 create 当父补登记的)。false = 只在卡片上出现过。 */
+  registered: boolean;
+};
+
+export type CreateTagInput = { name: string; parent: string | null };
+
+/**
+ * POST /api/requirements/tags/create 的 body:
+ *   { "name": "子标签", "parent_id": null | "父标签名" }
+ * parent_id 缺省/null = 建在根上;给了字符串就必须是网络里已存在的标签 —— 不存在回 404,
+ * **绝不**悄悄建到根上(客户端要预选父标签,静默 root fallback 会让 UI 显示的和实际存的不一致)。
+ */
+export function parseCreateTag(body: Record<string, unknown>): CreateTagInput | { error: string } {
+  const name = tagName(body.name);
+  if (!name) return { error: "invalid_tag" };
+  const rawParent = body.parent_id;
+  if (rawParent === undefined || rawParent === null) return { name, parent: null };
+  if (typeof rawParent !== "string") return { error: "invalid_tag_parent_id" };
+  const parent = tagName(rawParent);
+  if (!parent) return { error: "invalid_tag_parent_id" };
+  if (parent === name) return { error: "tag_parent_cycle" };
+  return { name, parent };
+}
+
+/** 从 name 往上数几层(顶层 = 1)。链上有环(历史脏数据)返回 Infinity,调用方据此拒绝。 */
+export function tagDepth(name: string, parentOf: Map<string, string | null>): number {
+  let depth = 1;
+  let cur = parentOf.get(name) ?? null;
+  const seen = new Set<string>([name]);
+  while (cur) {
+    if (seen.has(cur)) return Number.POSITIVE_INFINITY;
+    seen.add(cur);
+    depth++;
+    cur = parentOf.get(cur) ?? null;
+  }
+  return depth;
+}
+
+/** child 是不是 ancestor 的子孙(用于改名时的防环判断)。 */
+export function isDescendant(child: string, ancestor: string, parentOf: Map<string, string | null>): boolean {
+  let cur: string | null = parentOf.get(child) ?? null;
+  const seen = new Set<string>();
+  while (cur) {
+    if (cur === ancestor) return true;
+    if (seen.has(cur)) return false;
+    seen.add(cur);
+    cur = parentOf.get(cur) ?? null;
+  }
+  return false;
+}
+
+/**
+ * GET /api/requirements/tags 的 nodes:
+ * 登记过的节点 ∪ 调用者看得见的在用标签(后者 parent_id = null、registered = false,
+ * 老 Hub 上就是一堆平标签,升级后不会突然消失)。
+ */
+export function buildTagNodes(registered: TagNodeRow[], inUse: string[]): TagNodePublic[] {
+  const parentOf = new Map<string, string | null>();
+  const isRegistered = new Set<string>();
+  for (const row of registered) {
+    parentOf.set(row.name, row.parent_name ?? null);
+    isRegistered.add(row.name);
+  }
+  for (const name of inUse) if (!parentOf.has(name)) parentOf.set(name, null);
+  const nodes: TagNodePublic[] = [];
+  for (const [name, parent] of parentOf) {
+    const depth = tagDepth(name, parentOf);
+    nodes.push({
+      name,
+      parent_id: parent,
+      // 环/脏数据不给客户端 NaN/Infinity:按顶层展示,写接口仍然会拒绝往里挂。
+      depth: Number.isFinite(depth) ? depth : 1,
+      registered: isRegistered.has(name),
+    });
+  }
+  return nodes.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}

package/src/requirements-errors.ts

@@ -34,6 +34,14 @@ const ENTRIES: Record<string, Entry> = {
   not_found: { message: 'No such task, project or route.', hint: 'Check the id; requirements_list / projects_list return the ids you can use.' },
   project_not_found: { field: 'id', message: 'No project with that id in this network.', hint: 'Call projects_list to get project ids (proj_…).' },
   tag_not_found: { field: 'tag', message: 'No task in this network carries that tag.', hint: 'Tags are free text on tasks; list the ones in use from requirements_list (view=summary shows each task’s tags).' },
+  // 标签树(POST /api/requirements/tags/create):父标签是**标签名**不是 req_… id,所以用自己的错误码,
+  // 不借用任务父需求的 parent_not_found / invalid_parent_id(那两句文案会让调用方去查 req id)。
+  tag_exists: { field: 'name', message: 'This network already has a tag with that name (on a task, with a colour, or as a registered node).', hint: 'Pick another name, or rename / merge the existing tag with POST /api/requirements/tags/ops.' },
+  tag_parent_not_found: { field: 'parent_id', message: 'No tag named that in this network.', hint: 'Create the parent first (parent_id: null), or read GET /api/requirements/tags → nodes for the names that exist.' },
+  invalid_tag_parent_id: { field: 'parent_id', message: 'parent_id must be a tag name in this network, or null for the root.', hint: 'Tag names are 1–20 characters; read GET /api/requirements/tags → nodes for the names that exist.' },
+  tag_parent_cycle: { field: 'parent_id', message: 'A tag cannot be its own parent.', hint: 'Pass a different parent, or null for the root.' },
+  tag_depth_exceeded: { field: 'parent_id', message: 'Tags nest at most 4 levels (the root counts as level 1).', hint: 'Attach the tag to a higher-level tag.' },
+  invalid_tag: { field: 'name', message: 'Tag names are 1–20 characters after trimming, with no control characters.', hint: 'Shorten the name, or remove line breaks.' },
   checklist_item_not_found: { field: 'item_id', message: 'This task has no checklist item with that id.', hint: 'Item ids (ck_…) are in requirements_get → checklist[].id.' },
   // ── 权限 ──
   user_token_required: { message: 'This operation is for people only: a node token can read projects and read / create / update tasks, but cannot manage projects or delete tasks.', hint: 'Use an existing project (projects_list), or ask a person to create / change the project in the app (任务 → 管理项目).' },

package/src/requirements-http.test.ts

@@ -373,7 +373,7 @@ describe("requirements stay on the hub", () => {
     expect((await api(ownerToken, path, { method: "PATCH", body: JSON.stringify({ due: "" }) })).body.requirement.due).toBe("");
     const listed = await api(ownerToken, "/api/requirements");
     expect(listed.body.capabilities).toContain("due_datetime");
-    expect(listed.body.capabilities).toEqual(["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements", "tags", "priority_lowest", "start_date", "requirement_seq", "search", "paging", "completed_at", "stats", "tag_status_snapshot", "tag_ops", "list_summary", "changes", "events", "last_event", "column_abandoned"]);
+    expect(listed.body.capabilities).toEqual(["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements", "tags", "priority_lowest", "start_date", "requirement_seq", "search", "paging", "completed_at", "stats", "tag_status_snapshot", "tag_ops", "tag_tree", "list_summary", "changes", "events", "last_event", "column_abandoned"]);
   });
 
   test("sub-requirements: parent_id in the same network, no cycles, ≤ 5 levels, child counts, filters, delete detaches children", async () => {

package/src/requirements-migrate.ts

@@ -59,6 +59,27 @@ export function ensureNetworkTags(database: DbAdapter): void {
   `);
 }
 
+/**
+ * 标签树(父子标签)。标签名就是 id,parent_name 指向同网络的父标签名;没有 parent 行 = 顶层。
+ * 只存「登记过的节点」:卡片上出现但没登记过的标签(老数据)仍然是平标签,不改写任何 cards_json。
+ * 建标签、改名 / 合并 / 删除时维护这里(见 requirements.ts 的 handleTagCreate / handleTagOp)。
+ * IF NOT EXISTS:重复执行无副作用。
+ */
+export function ensureNetworkTagNodes(database: DbAdapter): void {
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS network_tag_nodes (
+      network_id      TEXT NOT NULL,
+      name            TEXT NOT NULL,
+      parent_name     TEXT,
+      created_at      TEXT NOT NULL,
+      updated_at      TEXT NOT NULL,
+      created_by_json TEXT,
+      PRIMARY KEY (network_id, name)
+    );
+    CREATE INDEX IF NOT EXISTS idx_network_tag_nodes_parent ON network_tag_nodes(network_id, parent_name);
+  `);
+}
+
 /**
  * 删掉的卡留一条墓碑,给 GET /api/requirements?changes=1 报「这些 id 没了」(按 updated_since 增量同步的客户端
  * 否则永远不知道一张卡被删了)。连同判断可见性要用的列一起存:受限成员只收到他本来看得见的卡的删除。

package/src/requirements.ts

@@ -8,6 +8,7 @@ import { db, logAudit } from "./db.js";
 import { resolveNodeCaller } from "./create-node.js";
 import { markGzipReusable } from "./http-gzip.js";
 import { applyTagOp, normalizeTags, parseTagOp, storedTags, type TagOp } from "./requirement-tags.js";
+import { buildTagNodes, MAX_TAG_DEPTH, parseCreateTag, TAG_TREE_CAPABILITY, tagDepth, type TagNodeRow } from "./requirement-tag-tree.js";
 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";
@@ -20,7 +21,7 @@ import { notifyLeaderDeleted, notifyParticipantChange } from "./requirement-noti
 import { departmentCardsFor, departmentSubtree } from "./department-heads.js";
 import { dueReminderTimezone, dueWithinSql, ensureDueReminders, overdueSql } from "./requirement-due-reminders.js";
 import { diffRequirement, ensureRequirementEvents, eventPublic, recordRequirementEvents, type EventRow } from "./requirement-events.js";
-import { ensureNetworkTags, ensureRequirementCompletedAt, ensureRequirementIndexes, ensureRequirementProjects, ensureRequirementSeq, ensureRequirementTombstones, migrateRequirementAgentOwners, migrateRequirementColumnCheck, migrateRequirementPriorityCheck, nextRequirementSeq } from "./requirements-migrate.js";
+import { ensureNetworkTagNodes, ensureNetworkTags, ensureRequirementCompletedAt, ensureRequirementIndexes, ensureRequirementProjects, ensureRequirementSeq, ensureRequirementTombstones, migrateRequirementAgentOwners, migrateRequirementColumnCheck, migrateRequirementPriorityCheck, nextRequirementSeq } from "./requirements-migrate.js";
 
 // 启动迁移:旧库里节点当负责人的卡,节点挪到 agent_owner(列由 db.ts 的加列循环加上)。
 // 放在这里而不是 db.ts:db.ts 每多一行,文档里钉着的行号就漂一次。
@@ -32,6 +33,7 @@ ensureRequirementIndexes(db);
 ensureRequirementSeq(db);
 ensureRequirementCompletedAt(db);
 ensureNetworkTags(db);
+ensureNetworkTagNodes(db);
 ensureRequirementTombstones(db);
 ensureRequirementEvents(db);
 ensureDueReminders(db);
@@ -474,7 +476,9 @@ async function handleTagOp(ctx: RequirementsRequestContext): Promise<Response> {
     );
     const colorOf = (name: string) => db.get<{ color: string }>("SELECT color FROM network_tags WHERE network_id = ?1 AND name = ?2", networkId, name)?.color ?? null;
     const sources = op.op === "rename" ? [op.from] : op.op === "merge" ? op.from : [op.tag];
-    const known = cards.some(card => storedTags(card.tags_json).some(tag => sources.includes(tag))) || sources.some(tag => colorOf(tag) !== null);
+    // 「存在」= 有卡片在用 / 有颜色行 / 是登记过的树节点。最后一种让 0 任务的标签也能改名、合并、删除、上色。
+    const nodeExists = (name: string) => !!db.get<{ x: number }>("SELECT 1 AS x FROM network_tag_nodes WHERE network_id = ?1 AND name = ?2", networkId, name);
+    const known = cards.some(card => storedTags(card.tags_json).some(tag => sources.includes(tag))) || sources.some(tag => colorOf(tag) !== null || nodeExists(tag));
     if (!known) return null;
     if (op.op === "color") {
       if (op.color === null) db.run("DELETE FROM network_tags WHERE network_id = ?1 AND name = ?2", [networkId, op.tag]);
@@ -490,11 +494,12 @@ async function handleTagOp(ctx: RequirementsRequestContext): Promise<Response> {
       affected++;
     }
     moveTagColors(networkId, op, colorOf, now);
-    return { affected };
+    const reparented = maintainTagTree(networkId, op, now);
+    return { affected, reparented };
   });
   if (!result) return jsonError("tag_not_found", 404);
   if (ctx.auth) logAudit(ctx.auth.userId, ctx.auth.username || null, `requirement_tag_${op.op}`, "requirement_tag", op.op === "rename" || op.op === "merge" ? op.to : op.tag, JSON.stringify({ ...op, affected: result.affected }).slice(0, 1000), undefined, networkId);
-  return Response.json({ ok: true, op: op.op, affected: result.affected });
+  return Response.json({ ok: true, op: op.op, affected: result.affected, reparented: result.reparented });
 }
 
 /** 改名 / 合并:目标没有颜色就继承第一个有颜色的来源;来源的颜色行删掉。删除:删颜色行。 */
@@ -508,6 +513,115 @@ function moveTagColors(networkId: string, op: TagOp, colorOf: (name: string) =>
   for (const tag of sources) db.run("DELETE FROM network_tags WHERE network_id = ?1 AND name = ?2", [networkId, tag]);
 }
 
+/**
+ * 标签改名 / 合并 / 删除时让树跟着动(与卡片改写同一个事务):
+ *   rename —— 节点改名,子节点的 parent_name 一起改;目标已有节点时按合并处理(并把「目标自己是来源的子节点」这种情况挂到来源的父上,避免自环)。
+ *   merge  —— 来源节点的子节点挂到目标,来源节点删掉。
+ *   delete —— 被删节点的子节点挂到它的父(没有父就成根);不删子节点、不丢层级。
+ * 返回被改挂的节点数(客户端能报「N 个子标签已上移」)。
+ */
+function maintainTagTree(networkId: string, op: TagOp, now: string): number {
+  if (op.op === "color") return 0;
+  const rows = db.all<TagNodeRow>("SELECT name, parent_name FROM network_tag_nodes WHERE network_id = ?1", networkId);
+  if (!rows.length) return 0;
+  const parentOf = new Map(rows.map(row => [row.name, row.parent_name ?? null]));
+  if (op.op === "rename") {
+    if (!parentOf.has(op.from)) return 0;
+    const fromParent = parentOf.get(op.from) ?? null;
+    if (!parentOf.has(op.to)) {
+      db.run("UPDATE network_tag_nodes SET name = ?1, updated_at = ?2 WHERE network_id = ?3 AND name = ?4", [op.to, now, networkId, op.from]);
+      const moved = db.run("UPDATE network_tag_nodes SET parent_name = ?1, updated_at = ?2 WHERE network_id = ?3 AND parent_name = ?4", [op.to, now, networkId, op.from]);
+      return moved.changes ?? 0;
+    }
+    // 目标已有节点 —— 合并。目标若正好是来源的子孙,直接挂过去会自环,改挂到来源的父。
+    let moved = 0;
+    for (const row of rows) {
+      if (row.parent_name !== op.from) continue;
+      const nextParent = row.name === op.to ? fromParent : op.to;
+      db.run("UPDATE network_tag_nodes SET parent_name = ?1, updated_at = ?2 WHERE network_id = ?3 AND name = ?4", [nextParent, now, networkId, row.name]);
+      moved++;
+    }
+    db.run("DELETE FROM network_tag_nodes WHERE network_id = ?1 AND name = ?2", [networkId, op.from]);
+    return moved;
+  }
+  if (op.op === "merge") {
+    let moved = 0;
+    for (const source of op.from) {
+      if (!parentOf.has(source)) continue;
+      const children = rows.filter(row => row.parent_name === source);
+      const res = db.run("UPDATE network_tag_nodes SET parent_name = ?1, updated_at = ?2 WHERE network_id = ?3 AND parent_name = ?4", [op.to, now, networkId, source]);
+      moved += res.changes ?? children.length;
+      db.run("DELETE FROM network_tag_nodes WHERE network_id = ?1 AND name = ?2", [networkId, source]);
+    }
+    return moved;
+  }
+  // delete
+  const row = parentOf.has(op.tag) ? rows.find(item => item.name === op.tag)! : null;
+  if (!row) return 0;
+  const res = db.run("UPDATE network_tag_nodes SET parent_name = ?1, updated_at = ?2 WHERE network_id = ?3 AND parent_name = ?4", [row.parent_name ?? null, now, networkId, op.tag]);
+  db.run("DELETE FROM network_tag_nodes WHERE network_id = ?1 AND name = ?2", [networkId, op.tag]);
+  return res.changes ?? 0;
+}
+
+/** 网络里所有卡片上出现过的标签(**不分可见范围**)。写操作按整个网络判重,否则同名标签会被拆成两半。 */
+function networkTagNames(networkId: string): Set<string> {
+  const names = new Set<string>();
+  for (const row of db.all<{ tags_json: string | null }>(
+    "SELECT tags_json FROM requirements WHERE network_id = ?1 AND tags_json IS NOT NULL AND tags_json <> '[]'", networkId,
+  )) {
+    for (const tag of storedTags(row.tags_json)) names.add(tag);
+  }
+  return names;
+}
+
+type CreateTagOutcome =
+  | { error: "tag_exists" | "tag_parent_not_found" | "tag_depth_exceeded" }
+  | { name: string; parent: string | null; depth: number; parentRegistered: boolean };
+
+/** POST /api/requirements/tags/create —— 建标签(可带父)。原子、整网络判重、父不存在就报错。 */
+async function handleTagCreate(ctx: RequirementsRequestContext): Promise<Response> {
+  const networkId = resolveRestWriteNetworkId(ctx.scope, ctx.auth, ctx.isAdmin);
+  if (!networkId) return jsonError("network_id_required", 400);
+  // 与改名 / 合并 / 删除同一把锁:整网写,只给不受任务范围限制的人。
+  if (!canManageTags(ctx, networkId)) return jsonError("permission_denied", 403);
+  let body: Record<string, unknown>;
+  try { body = await bodyObject(ctx.req); } catch { return jsonError("invalid_json", 400); }
+  const input = parseCreateTag(body);
+  if ("error" in input) return jsonError(input.error, 400);
+  const now = new Date().toISOString();
+  const actor = JSON.stringify(actorOf(ctx));
+  const result = db.transaction<CreateTagOutcome>(() => {
+    const nodes = db.all<TagNodeRow>("SELECT name, parent_name FROM network_tag_nodes WHERE network_id = ?1", networkId);
+    const parentOf = new Map(nodes.map(row => [row.name, row.parent_name ?? null]));
+    const used = networkTagNames(networkId);
+    const hasColor = (name: string) => !!db.get<{ x: number }>("SELECT 1 AS x FROM network_tags WHERE network_id = ?1 AND name = ?2", networkId, name);
+    const exists = (name: string) => parentOf.has(name) || used.has(name) || hasColor(name);
+    // 重名 = 409:不「复用」已有标签(复用会让 UI 以为新建成功,实际改了别的分支的标签)。
+    if (exists(input.name)) return { error: "tag_exists" };
+    let parentRegistered = false;
+    if (input.parent) {
+      // 父不存在 = 404。**不**把子标签建到根上:客户端预选了父,存成根会让回读的层级和表单不一致。
+      if (!exists(input.parent)) return { error: "tag_parent_not_found" };
+      if (!parentOf.has(input.parent)) {
+        // 父此前只在卡片上出现过(老数据):登记成顶层节点。父本来就没有父,这不是把子标签降级到根。
+        db.run("INSERT INTO network_tag_nodes (network_id, name, parent_name, created_at, updated_at, created_by_json) VALUES (?1, ?2, NULL, ?3, ?3, ?4)", [networkId, input.parent, now, actor]);
+        parentOf.set(input.parent, null);
+        parentRegistered = true;
+      }
+      if (tagDepth(input.parent, parentOf) + 1 > MAX_TAG_DEPTH) return { error: "tag_depth_exceeded" };
+    }
+    db.run("INSERT INTO network_tag_nodes (network_id, name, parent_name, created_at, updated_at, created_by_json) VALUES (?1, ?2, ?3, ?4, ?4, ?5)", [networkId, input.name, input.parent, now, actor]);
+    parentOf.set(input.name, input.parent);
+    return { name: input.name, parent: input.parent, depth: tagDepth(input.name, parentOf), parentRegistered };
+  });
+  if ("error" in result) {
+    const status = result.error === "tag_exists" ? 409 : result.error === "tag_parent_not_found" ? 404 : 400;
+    return jsonError(result.error, status);
+  }
+  if (ctx.auth) logAudit(ctx.auth.userId, ctx.auth.username || null, "requirement_tag_create", "requirement_tag", result.name, JSON.stringify({ parent_id: result.parent, depth: result.depth }).slice(0, 1000), undefined, networkId);
+  return Response.json({ ok: true, tag: { name: result.name, parent_id: result.parent, depth: result.depth }, parent_registered: result.parentRegistered }, { status: 201 });
+}
+
 function toPublic(row: Row) {
   return {
     owner: row.owner_json ? JSON.parse(row.owner_json) : null,
@@ -726,7 +840,7 @@ export const COMMENT_MAX_CHARS = 4000;
 const NODE_TOKEN_OPERATIONS: ReadonlySet<string> = new Set<string>(["read", "create", "patch", "checklist_item", "comment", "upsert", "projects_read"]);
 function operationOf(req: Request, url: URL): string {
   if (/^\/api\/requirements\/projects(\/|$)/.test(url.pathname)) return req.method === "GET" ? "projects_read" : "projects_write";
-  if (url.pathname === "/api/requirements/tags/ops") return "tags_write";
+  if (url.pathname === "/api/requirements/tags/ops" || url.pathname === "/api/requirements/tags/create") return "tags_write";
   if (req.method === "GET") return "read";
   if (/^\/api\/requirements\/[^/]+\/checklist\/[^/]+$/.test(url.pathname)) return "checklist_item";
   if (/^\/api\/requirements\/[^/]+\/comments$/.test(url.pathname)) return "comment";
@@ -770,7 +884,7 @@ function ifNoneMatchHits(header: string | null, etag: string): boolean {
 // list_summary:GET 认 view=summary(不带描述正文与子任务条目,见 toSummary);changes:GET 认 changes=1 + updated_since
 // (改过的卡含归档的,加上 deleted 墓碑与 server_time,见 listChanges)。
 // events:GET /api/requirements/events —— 字段级的改动流水(谁、何时、旧值 → 新值,requirement-events.ts)。
-export const REQUIREMENT_CAPABILITIES = ["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements", "tags", "priority_lowest", "start_date", "requirement_seq", "search", "paging", "completed_at", "stats", "tag_status_snapshot", "tag_ops", "list_summary", "changes", "events", "last_event", "column_abandoned"] as const;
+export const REQUIREMENT_CAPABILITIES = ["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements", "tags", "priority_lowest", "start_date", "requirement_seq", "search", "paging", "completed_at", "stats", "tag_status_snapshot", "tag_ops", TAG_TREE_CAPABILITY, "list_summary", "changes", "events", "last_event", "column_abandoned"] as const;
 
 // ── 子需求 ──
 // parent_id:同一网络里的另一张卡;不能成环;最多 5 层(顶层是第 1 层)。删父卡 = 子卡保留、parent_id 置空。
@@ -1559,15 +1673,22 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
     const tagSql = addTaskVisibilityScope("SELECT tags_json FROM requirements WHERE network_id=?1", tagParams, taskCaller(ctx));
     const rows = db.all<{ tags_json: string | null }>(tagSql, ...tagParams);
     // counts:调用者看得见的卡里(含归档)每个标签用了几张;colors:只回这些标签的颜色(看不见的卡上的标签不外泄)。
-    // can_manage:这个调用者能不能用 /tags/ops。旧 App 只读 tags,多出的字段忽略。
+    // can_manage:这个调用者能不能用 /tags/ops /tags/create。旧 App 只读 tags,多出的字段忽略。
     const counts: Record<string, number> = {};
     for (const row of rows) for (const tag of storedTags(row.tags_json)) counts[tag] = (counts[tag] ?? 0) + 1;
     const tags = Object.keys(counts).sort();
+    const manageable = canManageTags(ctx, networkId);
+    // nodes:标签树。登记过的节点(create 建的,含 0 任务)∪ 调用者看得见的在用标签。
+    // 受限成员只拿得到「看得见的名字」:登记过但一张可见卡都没有的标签不外泄(与 counts / colors 同一口径)。
+    const registeredRows = db.all<TagNodeRow>("SELECT name, parent_name FROM network_tag_nodes WHERE network_id = ?1", networkId);
+    const visibleRegistered = manageable ? registeredRows : registeredRows.filter(row => counts[row.name] > 0);
+    const nodeNames = new Set([...registeredRows.map(row => row.name), ...tags]);
     const colors: Record<string, string> = {};
     for (const row of db.all<{ name: string; color: string }>("SELECT name, color FROM network_tags WHERE network_id = ?1", networkId)) {
-      if (counts[row.name]) colors[row.name] = row.color;
+      if (counts[row.name] || (manageable && nodeNames.has(row.name))) colors[row.name] = row.color;
     }
-    return Response.json({ ok: true, networkId, tags, counts, colors, can_manage: canManageTags(ctx, networkId) });
+    const nodes = buildTagNodes(visibleRegistered, tags).map(node => ({ ...node, count: counts[node.name] ?? 0, color: colors[node.name] ?? null }));
+    return Response.json({ ok: true, networkId, tags, counts, colors, nodes, can_manage: manageable });
   }
 
   if (url.pathname === "/api/requirements/tags/ops") {
@@ -1575,6 +1696,12 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
     return handleTagOp(ctx);
   }
 
+  // 建标签(可带 parent_id)。原子:节点 + 审计在一个事务里;父不存在 404,绝不安静建到根上。
+  if (url.pathname === "/api/requirements/tags/create") {
+    if (req.method !== "POST") return jsonError("not_found", 404);
+    return handleTagCreate(ctx);
+  }
+
   // 仪表盘聚合(requirements-stats.ts):一个网络、调用者看得见的卡(与列表同一个可见范围),含归档的卡 ——
   // 完成的卡常被归档,不算它们「今天完成了多少」就会偏少。
   if (url.pathname === "/api/requirements/stats" && req.method === "GET") {

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/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?.();
+  }
+});