@sleep2agi/commhub-server 0.9.0-preview.8 → 0.9.0-preview.80

package/src/report-status-host-schema.test.ts

@@ -0,0 +1,211 @@
+// report_status 的 host 遥测 schema 必须接受 agent-node **声明会发**的 null。
+//
+// 来源不是推理，是 #1225 复现容器里量到的一次真崩：`--network none` 里
+// agent-node 一启动就死在
+//   MCP error -32602: Invalid input: expected string, received null at host.ip
+// 而 register() 是 `await callCommHub("report_status", …)` 且没有 catch ——
+// 于是**整个节点进程当场退出**，和 runtime 无关（opencode/claude/codex 一样）。
+//
+// 触发条件不是"容器"，是"这台机器没有非回环 IPv4"：
+// agent-node 的 firstNonInternalIPv4()（host-telemetry.ts:48-59）在那种机器上
+// 返回 null，而 HostTelemetry 的类型本来就写着 `ip: string | null`。
+//
+// 🔴 这里断言的是 **schema 本身**，不是 handler。直接调 handler 会绕过 zod ——
+//    而缺陷恰恰只存在于 zod 那一层，绕过去就永远绿。
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools } from "./tools.js";
+
+function captureToolSchemas(): Record<string, any> {
+  const mcp = new McpServer({ name: "schema-probe", version: "0" }) as any;
+  const schemas: Record<string, any> = {};
+  const origTool = mcp.tool.bind(mcp);
+  mcp.tool = (name: string, desc: string, schema: any, handler: any) => {
+    schemas[name] = schema;
+    return origTool(name, desc, schema, handler);
+  };
+  registerTools(mcp, undefined, null, null, null, false, "tok_schema_probe");
+  return schemas;
+}
+
+const schemas = captureToolSchemas();
+
+describe("report_status host telemetry schema", () => {
+  test("前提：抓到的确实是 report_status 的 host 形状", () => {
+    expect(schemas.report_status).toBeTruthy();
+    expect(schemas.report_status.host).toBeTruthy();
+  });
+
+  test("🔴 host.ip = null 必须被接受（没有非回环 IPv4 的机器就是发 null）", () => {
+    const host = schemas.report_status.host;
+    const parsed = host.parse({ hostname: "boxy", ip: null });
+    expect(parsed.ip).toBeNull();
+  });
+
+  test("🔴 host.hostname = null 同样被接受（与 ip 同为字符串字段，一起对齐）", () => {
+    const host = schemas.report_status.host;
+    expect(host.parse({ hostname: null, ip: "10.0.0.2" }).hostname).toBeNull();
+  });
+
+  test("agent-node 那条完整心跳负载整体过 schema", () => {
+    // 形状抄自 agent-node/src/host-telemetry.ts 的 HostTelemetry：
+    // 没有网络、没有 /proc 时每一项都可能是 null。
+    const full = {
+      hostname: "unknown", ip: null,
+      cpu_load_1min: null, cpu_cores: null,
+      mem_total_gb: null, mem_used_gb: null, mem_avail_gb: null,
+      disk_total_gb: null, disk_used_gb: null, disk_avail_gb: null,
+    };
+    expect(() => schemas.report_status.host.parse(full)).not.toThrow();
+  });
+
+  test("放宽的只有 null —— 类型错的值仍然被拒", () => {
+    const host = schemas.report_status.host;
+    expect(() => host.parse({ ip: 12345 })).toThrow();
+    expect(() => host.parse({ ip: "x".repeat(201) })).toThrow();
+  });
+
+  test("整条 report_status 负载（不只是 host 子对象）也接受 ip=null", () => {
+    const full = z.object(schemas.report_status);
+    expect(() => full.parse({
+      resume_id: "probe-resume", alias: "probe-node", status: "idle",
+      host: { hostname: "unknown", ip: null },
+    })).not.toThrow();
+  });
+});
+
+/* #1545 —— `create_capability_observed_ms_ago` 的**验证宽度**本身就是判据。
+ *
+ * 这一格是纯诊断信息(那个 can_create_nodes 是多久以前测出来的)。zod 对象里
+ * 任何一个**已知字段**验证失败,整份 report_status 都会被拒 —— 不是丢掉这一格。
+ * 所以给它加 `.int()/.min()/.max()` 等于:一台节点发了个奇怪的诊断数字,
+ * 就在 hub 上整个失联。**#1225/#1498 已经用 host.ip 演过一遍这件事了。**
+ *
+ * 消毒在读取处(`/api/host-supervisors`),不在这里。 */
+describe("#1545 create_capability_observed_ms_ago —— schema 必须收得宽", () => {
+  const caps = () => schemas.report_status.config_snapshot;
+
+  test("前提:抓到的确实是 config_snapshot 形状,且它接受 daemon_capabilities", () => {
+    expect(caps()).toBeTruthy();
+    const parsed = caps().parse({
+      flags: {}, config_update_capable: false, peer_reply_inbox_capable: true,
+      daemon_capabilities: { can_create_nodes: true },
+    });
+    expect(parsed.daemon_capabilities.can_create_nodes).toBe(true);
+  });
+
+  test("正常值:透传", () => {
+    const parsed = caps().parse({
+      flags: {}, config_update_capable: false, peer_reply_inbox_capable: true,
+      daemon_capabilities: { can_create_nodes: true, create_capability_observed_ms_ago: 0 },
+    });
+    expect(parsed.daemon_capabilities.create_capability_observed_ms_ago).toBe(0);
+  });
+
+  test("null 必须被接受(显式「我没测过」和「我不发这一格」都要能表达)", () => {
+    const parsed = caps().parse({
+      flags: {}, config_update_capable: false, peer_reply_inbox_capable: true,
+      daemon_capabilities: { can_create_nodes: true, create_capability_observed_ms_ago: null },
+    });
+    expect(parsed.daemon_capabilities.create_capability_observed_ms_ago).toBeNull();
+  });
+
+  /* 🔴 这四个值**一个都不许让整份 report 被拒**。它们在读取侧会被当成「没报」,
+   *    但那是读取侧的事 —— 这一层的职责只有一个:别把节点踢下线。 */
+  test.each([
+    ["负数", -1],
+    ["非整数", 1234.5678],
+    ["超过一年", 400 * 24 * 60 * 60 * 1000],
+    ["NaN", Number.NaN],
+  ])("怪值不得拒掉整份 report_status:%s", (_label, value) => {
+    expect(() => caps().parse({
+      flags: {}, config_update_capable: false, peer_reply_inbox_capable: true,
+      daemon_capabilities: { can_create_nodes: false,
+        create_nodes_blocked_reason: "anet_bin_source",
+        create_capability_observed_ms_ago: value },
+    })).not.toThrow();
+  });
+
+  /* 🔴 反向锚:上面那组「不抛」如果只是因为**这个 key 压根没被 schema 看见**,
+   * 它们会一样绿。所以这里证明 schema 确实在看它:喂一个非数字,值必须**被改写成
+   * null**(而不是原样穿过去)。原样穿过去 = key 被忽略,那组测试就什么也没测。 */
+  test("反向锚:非数字被改写成 null(不是原样穿过)⇒ 证明 schema 确实在看这个 key", () => {
+    const parsed = caps().parse({
+      flags: {}, config_update_capable: false, peer_reply_inbox_capable: true,
+      daemon_capabilities: { can_create_nodes: true, create_capability_observed_ms_ago: "0" },
+    });
+    expect(parsed.daemon_capabilities.create_capability_observed_ms_ago).toBeNull();
+    expect(parsed.daemon_capabilities.create_capability_observed_ms_ago).not.toBe("0");
+  });
+});
+
+/* 🔴 #1545 —— 把 `host:` 上方那段方框注释里的表**钉住**。
+ *
+ * 那段注释说的是:这份 schema 的子对象一半 strict 一半不 strict,而「往里加一个
+ * hub 还不认识的键」的后果完全相反 —— 非 strict 静默丢弃(节点活着、字段蒸发),
+ * strict 拒掉整份 report(节点当场失联,#1225 的形状)。
+ *
+ * 注释会烂。这组测试的作用**不是禁止改 strict**(两种都各有其位),而是:谁改了,
+ * 谁就会在这里撞红,从而**被迫连注释一起改**。所以断言写成「和注释里那张表一致」,
+ * 而不是「必须是某个值」。 */
+describe("#1545 report_status 子对象的 strict 分布(注释里那张表的可执行副本)", () => {
+  const rs = () => schemas.report_status;
+  const UNKNOWN = { __hub_does_not_know_this_key__: 1 };
+
+  function acceptsUnknownKey(schema: any, base: object): "dropped" | "rejected" {
+    try {
+      const parsed = schema.parse({ ...base, ...UNKNOWN });
+      return "__hub_does_not_know_this_key__" in parsed ? "rejected" /* 不可能:留着说明它根本没被处理 */ : "dropped";
+    } catch { return "rejected"; }
+  }
+
+  const SIDE_THREAD = {
+    supported: true, runtime: "codex", runtimeVersion: "1.0",
+    topology: "native-exact-fork", evidenceRevision: "r1",
+  };
+  const SNAP_BASE = { flags: {}, config_update_capable: false, peer_reply_inbox_capable: true };
+
+  test.each([
+    ["host", () => rs().host, {}, "dropped"],
+    ["process_telemetry", () => rs().process_telemetry, {}, "dropped"],
+    ["config_snapshot", () => rs().config_snapshot, SNAP_BASE, "dropped"],
+    ["external_schedules", () => rs().external_schedules, { schedules: [] }, "rejected"],
+  ])("%s → 未知键被 %s", (_name, get, base, expected) => {
+    expect(acceptsUnknownKey(get(), base)).toBe(expected as string);
+  });
+
+  test("daemon_capabilities(嵌在 config_snapshot 里)→ 未知键被丢弃,不拒整份", () => {
+    const parsed: any = rs().config_snapshot.parse({
+      ...SNAP_BASE,
+      daemon_capabilities: { can_create_nodes: true, ...UNKNOWN },
+    });
+    expect(parsed.daemon_capabilities.can_create_nodes).toBe(true);
+    expect("__hub_does_not_know_this_key__" in parsed.daemon_capabilities).toBe(false);
+  });
+
+  test("side_thread_capability(同一个 config_snapshot 里)→ 未知键拒掉**整份**", () => {
+    expect(() => rs().config_snapshot.parse({
+      ...SNAP_BASE,
+      side_thread_capability: { ...SIDE_THREAD, ...UNKNOWN },
+    })).toThrow();
+    // 反向锚:去掉那个未知键必须过 —— 否则上面那条可能是被别的必填字段拒的,
+    // 和 strict 无关。
+    expect(() => rs().config_snapshot.parse({
+      ...SNAP_BASE, side_thread_capability: SIDE_THREAD,
+    })).not.toThrow();
+  });
+
+  /* 分母自证:上面这张表**两侧都有**。如果哪天全变成 dropped(或全 rejected),
+   * 那段注释描述的「不对称」就不存在了,而这条会先红。 */
+  test("这张表确实是不对称的(两种后果各至少一个)", () => {
+    const results = [
+      acceptsUnknownKey(rs().host, {}),
+      acceptsUnknownKey(rs().process_telemetry, {}),
+      acceptsUnknownKey(rs().config_snapshot, SNAP_BASE),
+      acceptsUnknownKey(rs().external_schedules, { schedules: [] }),
+    ];
+    expect(results.filter(r => r === "dropped").length).toBeGreaterThan(0);
+    expect(results.filter(r => r === "rejected").length).toBeGreaterThan(0);
+  });
+});

package/src/report-status-resume-id-handover.test.ts

@@ -0,0 +1,150 @@
+// 同一 alias 换 resume_id 上报时,hub 的 report_status 走的是「DELETE 旧行 + INSERT 新行」,
+// ON CONFLICT 里的 COALESCE 一次都不会触发 —— 上报里没带的描述性列(version / agent /
+// hostname / 遥测 / registered_at)全部变 NULL。
+//
+// 2026-09-04 DEV 真机(hub 日志):
+//   12:46:47 grok-v1 (sdk-n_6c)  → report_status: working       version=2.5.0-preview.64
+//   12:46:53 grok-v1 (grok-cli)  → report_status: working       ← TUI 的 MCP 上报,不带 version
+//   12:46:54 grok-v1 (sdk-n_6c)  → report_status: idle          ← 又换回来,也不带 version
+// 结果:version=NULL、registered_at 被改成 12:46:54。舰队里 grok 3/10、claude 5/15 有 version,
+// codex 34/34 有 —— 差别就是有没有第二个上报者。
+//
+// 判据:换 resume_id 之后,只有一行;上报了的列以上报为准,没上报的列从被替换的那行接手。
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { db } from "./db.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools } from "./tools.js";
+
+const NET_ID = "net_handover";
+const USER_ID = "u_handover";
+const NODE_ID = "n_handover";
+const ALIAS = "grok-handover";
+const TOK_ID = "tok_handover";
+const RESUME_SDK = `sdk-${NODE_ID}`;
+const RESUME_CLI = `grok-cli-${NODE_ID}`;
+const OLD_REGISTERED_AT = "2026-01-02 03:04:05";
+
+type ToolHandler = (args: any, extra?: any) => Promise<{ content: Array<{ type: "text"; text: string }> }>;
+
+function cleanup() {
+  for (const [sql, params] of [
+    ["DELETE FROM agent_telemetry WHERE network_id = ?1", [NET_ID]],
+    ["DELETE FROM sessions WHERE network_id = ?1", [NET_ID]],
+    ["DELETE FROM nodes WHERE network_id = ?1", [NET_ID]],
+    ["DELETE FROM api_tokens WHERE network_id = ?1", [NET_ID]],
+    ["DELETE FROM network_members WHERE network_id = ?1", [NET_ID]],
+    ["DELETE FROM networks WHERE network_id = ?1", [NET_ID]],
+    ["DELETE FROM users WHERE user_id = ?1", [USER_ID]],
+  ] as const) {
+    try { db.run(sql, params as any); } catch {}
+  }
+}
+beforeEach(cleanup);
+afterAll(cleanup);
+
+function seed() {
+  db.run(`INSERT INTO users (user_id, username, password_hash, role, created_at) VALUES (?1, ?2, 'x', 'user', datetime('now'))`, [USER_ID, USER_ID]);
+  db.run(`INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?2, ?3, datetime('now'))`, [NET_ID, NET_ID, USER_ID]);
+  db.run(`INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, 'owner', datetime('now'))`, [USER_ID, NET_ID]);
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, hostname, created_at, updated_at, lifecycle_state)
+     VALUES (?1, ?2, ?3, ?4, ?5, datetime('now'), datetime('now'), 'active')`,
+    [NODE_ID, ALIAS, ALIAS, NET_ID, "dev-box"],
+  );
+  // agent-node 自己注册的那行:带 version / agent / hostname / 遥测 / 早就存在的 registered_at
+  db.run(
+    `INSERT INTO sessions (resume_id, alias, status, node_id, network_id, version, agent, hostname, server, project_dir,
+                           cpu_cores, mem_total_gb, disk_total_gb, registered_at, updated_at, last_seen_at)
+     VALUES (?1, ?2, 'working', ?3, ?4, '2.5.0-preview.64', 'agent-node:grok-build-cli', 'dev-box', 'dev-box', '/home/x/proj',
+             8, 61.4, 500, ?5, datetime('now'), datetime('now'))`,
+    [RESUME_SDK, ALIAS, NODE_ID, NET_ID, OLD_REGISTERED_AT],
+  );
+  db.run(
+    `INSERT INTO api_tokens (token_id, user_id, network_id, scope, name, token_hash, expires_at, revoked_at)
+     VALUES (?1, ?2, ?3, 'network', ?4, ?5, NULL, NULL)`,
+    [TOK_ID, USER_ID, NET_ID, `node:${ALIAS}`, `hash_${TOK_ID}`],
+  );
+}
+
+function buildHandlers(): Record<string, ToolHandler> {
+  const server = new McpServer({ name: "test", version: "0" }) as any;
+  const tools: Record<string, ToolHandler> = {};
+  const origTool = server.tool.bind(server);
+  server.tool = (name: string, _desc: string, _schema: any, handler: ToolHandler) => { tools[name] = handler; return origTool(name, _desc, _schema, handler); };
+  const origRegisterTool = server.registerTool?.bind(server);
+  if (origRegisterTool) {
+    server.registerTool = (name: string, _cfg: any, handler: ToolHandler) => { tools[name] = handler; return origRegisterTool(name, _cfg, handler); };
+  }
+  registerTools(server, undefined, NET_ID, USER_ID, ALIAS, true, TOK_ID);
+  return tools;
+}
+
+async function call(handler: ToolHandler, args: any): Promise<any> {
+  const r = await handler(args);
+  return JSON.parse(r.content[0]!.text);
+}
+
+type Row = { resume_id: string; status: string; version: string | null; agent: string | null; hostname: string | null;
+  cpu_cores: number | null; mem_total_gb: number | null; registered_at: string; task: string | null };
+function rows(): Row[] {
+  return db.all("SELECT resume_id, status, version, agent, hostname, cpu_cores, mem_total_gb, registered_at, task FROM sessions WHERE alias = ?1 AND network_id = ?2", [ALIAS, NET_ID]) as Row[];
+}
+
+describe("report_status: 同 alias 换 resume_id 时,描述性列从被替换的那行接手", () => {
+  test("第二个上报者(grok-cli)不带 version/agent/遥测 → 这些列保留,status/task 以本次为准,仍只有一行", async () => {
+    seed();
+    const tools = buildHandlers();
+    const r = await call(tools.report_status!, { resume_id: RESUME_CLI, alias: ALIAS, status: "working", task: "PING 已收到", network_id: NET_ID });
+    expect(r.ok, JSON.stringify(r)).toBe(true);
+    const all = rows();
+    expect(all.length).toBe(1);
+    const row = all[0]!;
+    expect(row.resume_id).toBe(RESUME_CLI);
+    expect(row.status).toBe("working");
+    expect(row.task).toBe("PING 已收到");
+    expect(row.version).toBe("2.5.0-preview.64");
+    expect(row.agent).toBe("agent-node:grok-build-cli");
+    expect(row.hostname).toBe("dev-box");
+    expect(row.cpu_cores).toBe(8);
+    expect(row.mem_total_gb).toBe(61.4);
+    expect(row.registered_at).toBe(OLD_REGISTERED_AT);
+  });
+
+  test("上报里带了的列以上报为准(version 变了就用新的)", async () => {
+    seed();
+    const tools = buildHandlers();
+    const r = await call(tools.report_status!, { resume_id: RESUME_CLI, alias: ALIAS, status: "idle", version: "9.9.9", hostname: "other-box", network_id: NET_ID });
+    expect(r.ok, JSON.stringify(r)).toBe(true);
+    const row = rows()[0]!;
+    expect(rows().length).toBe(1);
+    expect(row.version).toBe("9.9.9");
+    expect(row.hostname).toBe("other-box");
+    expect(row.agent).toBe("agent-node:grok-build-cli");
+  });
+
+  test("再换回原 resume_id(sdk)也不丢:两个上报者轮流说话,version 始终在", async () => {
+    seed();
+    const tools = buildHandlers();
+    await call(tools.report_status!, { resume_id: RESUME_CLI, alias: ALIAS, status: "working", network_id: NET_ID });
+    const r = await call(tools.report_status!, { resume_id: RESUME_SDK, alias: ALIAS, status: "idle", network_id: NET_ID });
+    expect(r.ok, JSON.stringify(r)).toBe(true);
+    const all = rows();
+    expect(all.length).toBe(1);
+    expect(all[0]!.resume_id).toBe(RESUME_SDK);
+    expect(all[0]!.status).toBe("idle");
+    expect(all[0]!.version).toBe("2.5.0-preview.64");
+    expect(all[0]!.registered_at).toBe(OLD_REGISTERED_AT);
+  });
+
+  test("没有别的行可接手时(全新 alias)行为不变:INSERT 一行,registered_at 取 now", async () => {
+    seed();
+    db.run("DELETE FROM sessions WHERE network_id = ?1", [NET_ID]);
+    const tools = buildHandlers();
+    const r = await call(tools.report_status!, { resume_id: RESUME_SDK, alias: ALIAS, status: "idle", network_id: NET_ID });
+    expect(r.ok, JSON.stringify(r)).toBe(true);
+    const all = rows();
+    expect(all.length).toBe(1);
+    expect(all[0]!.version).toBeNull();
+    expect(all[0]!.registered_at).not.toBe(OLD_REGISTERED_AT);
+  });
+});

package/src/require-explicit-test-db.ts

@@ -0,0 +1,9 @@
+// #434: real-server integration tests must know their DB before importing
+// auth/db/server modules. Setting COMMHUB_DB in beforeAll is too late because
+// ESM dependencies have already evaluated the db singleton.
+if (!process.env.COMMHUB_DB) {
+  throw new Error(
+    "explicit_test_database_required: run `cd server && bun run test`, " +
+    "or set COMMHUB_DB to an isolated temporary path before running this file",
+  );
+}

package/src/requirement-events-http.test.ts

@@ -0,0 +1,257 @@
+// 任务动态(#429)—— HTTP 集成测试(真实 Bun.serve,临时库;PG 梯子上用 COMMHUB_TEST_PG_URL 原样再跑一遍)。
+//   写路径    —— 新建 / PATCH 的每个字段 / 勾子任务 / 标签改名 / 删项目 / 删卡,各记字段级流水:谁、旧值 → 新值
+//   同一事务  —— 流水写不进去,那次改动也不生效
+//   可见范围  —— 与列表相同:scoped 成员只看到看得见的卡(删掉的按墓碑);Agent 受限成员看不见的节点被隐去
+//   翻页      —— limit / next_cursor / since / requirement_id;参数不合法 400;capability `events`
+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-requirement-events-"));
+process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+
+const PW = "EventsPassw0rd!x";
+let BASE = "";
+let hub: any = null;
+let NET = "";
+let admin = { token: "", id: "" };
+let member = { token: "", id: "" };
+let scoped = { token: "", id: "" };
+let restricted = { token: "", id: "" };
+let nodeToken = "";
+let NODE = "";
+
+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 = async (t: string, card: Record<string, unknown>) => {
+  const r = await send(t, "POST", "/api/requirements", { network_id: NET, ...card });
+  expect(r.status).toBe(201);
+  return r.body.requirement as { id: string; seq: number };
+};
+const patch = (t: string, id: string, p: Record<string, unknown>) => send(t, "PATCH", `/api/requirements/${id}?network_id=${NET}`, p);
+const events = (t: string, qs = "") => send(t, "GET", `/api/requirements/events?network_id=${NET}${qs}`);
+const of = (list: any[], id: string) => list.filter(e => e.requirement_id === id);
+const user = (id: string) => ({ kind: "user", id });
+
+beforeAll(async () => {
+  process.env.HOST = "127.0.0.1";
+  const { register, createNetworkTokenForNode } = await import("./auth.js");
+  const { db } = await import("./db.js");
+  const a = register(`ev_admin_${Date.now()}`, 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 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) => {
+    const r = await send(admin.token, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role: "member" });
+    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 };
+  };
+  const stamp = Date.now();
+  member = await mk(`ev_member_${stamp}`);
+  scoped = await mk(`ev_scoped_${stamp}`);
+  restricted = await mk(`ev_restricted_${stamp}`);
+  db.run("UPDATE network_members SET task_access = 'all', agent_access = 'all' WHERE network_id = ?1 AND user_id = ?2", [NET, member.id]);
+  db.run("UPDATE network_members SET task_access = 'scoped' WHERE network_id = ?1 AND user_id = ?2", [NET, scoped.id]);
+  // 看全部任务,但一个 Agent 都没授权:所有节点对他隐去
+  db.run("UPDATE network_members SET task_access = 'all', agent_access = 'granted' WHERE network_id = ?1 AND user_id = ?2", [NET, restricted.id]);
+  NODE = `n_ev_${stamp}`;
+  db.run("INSERT INTO nodes (node_id, node_name, alias, network_id) VALUES (?1, ?2, ?3, ?4)", [NODE, "ev-node", "ev-node", NET]);
+  const ntok = createNetworkTokenForNode(admin.id, NET, "ev-node");
+  expect(ntok.ok).toBe(true);
+  nodeToken = ntok.token!;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("requirement events", () => {
+  test("capability `events` is advertised", async () => {
+    const r = await send(admin.token, "GET", `/api/requirements?network_id=${NET}`);
+    expect(r.body.capabilities).toContain("events");
+  });
+
+  test("create records one `created` event with the actor, title and seq", async () => {
+    const card = await create(member.token, { name: "动态示例一" });
+    const r = await events(admin.token, `&requirement_id=${card.id}`);
+    expect(r.status).toBe(200);
+    expect(r.body.events.length).toBe(1);
+    const [e] = r.body.events;
+    expect(e).toMatchObject({ kind: "created", field: null, actor: user(member.id), title: "动态示例一", seq: card.seq, new: { title: "动态示例一", column: "pool" } });
+    expect(typeof e.id).toBe("string");
+    expect(Date.parse(e.at)).toBeGreaterThan(0);
+  });
+
+  test("a PATCH records one event per changed field, old → new; unchanged fields and no-op PATCHes record nothing", async () => {
+    const card = await create(admin.token, { name: "动态示例二", priority: "normal", tags: ["UI"] });
+    const r1 = await patch(member.token, card.id, {
+      column: "doing", priority: "high", due: "2026-10-03", name: "动态示例二(改)", tags: ["UI", "后端"],
+      agent_owner: { kind: "node", id: NODE }, participants: [user(admin.id)], assignee: "",
+    });
+    expect(r1.status).toBe(200);
+    const list = of((await events(admin.token)).body.events, card.id);
+    const byField = Object.fromEntries(list.filter((e: any) => e.kind === "changed").map((e: any) => [e.field, e]));
+    expect(Object.keys(byField).sort()).toEqual(["agent_owner", "column", "due", "participants", "priority", "tags", "title"]);
+    expect(byField.column).toMatchObject({ old: "pool", new: "doing", actor: user(member.id) });
+    expect(byField.priority).toMatchObject({ old: "normal", new: "high" });
+    expect(byField.due).toMatchObject({ old: null, new: "2026-10-03" });
+    expect(byField.title).toMatchObject({ old: "动态示例二", new: "动态示例二(改)" });
+    expect(byField.tags).toMatchObject({ old: ["UI"], new: ["UI", "后端"] });
+    expect(byField.agent_owner).toMatchObject({ old: null, new: { kind: "node", id: NODE } });
+    expect(byField.participants).toMatchObject({ old: [], new: [user(admin.id)] });
+    // every event of that PATCH carries the card's title after the change
+    expect(new Set(list.filter((e: any) => e.kind === "changed").map((e: any) => e.title))).toEqual(new Set(["动态示例二(改)"]));
+    const before = list.length;
+    expect((await patch(member.token, card.id, { priority: "high", column: "doing" })).status).toBe(200);
+    expect(of((await events(admin.token)).body.events, card.id).length).toBe(before);
+    // archive / unarchive, description (length only, never the text), move to done
+    await patch(member.token, card.id, { description: "一段描述" });
+    await patch(member.token, card.id, { column: "done" });
+    await patch(member.token, card.id, { archived: true });
+    const later = of((await events(admin.token)).body.events, card.id).slice(0, 3);
+    expect(later.map((e: any) => e.field)).toEqual(["archived", "column", "description"]);
+    expect(later[0]).toMatchObject({ old: false, new: true });
+    expect(later[1]).toMatchObject({ old: "doing", new: "done" });
+    expect(later[2]).toMatchObject({ old: { chars: 0 }, new: { chars: 4 } });
+    expect(JSON.stringify(later[2])).not.toContain("一段描述");
+  });
+
+  test("checklist: ticking an item is `checklist_item` (repeat is a no-op); adding items is `checklist`", async () => {
+    const card = await create(admin.token, { name: "动态示例三", checklist: [{ id: "a", text: "第一项" }, { id: "b", text: "第二项" }] });
+    const tick = (done: boolean) => send(member.token, "PATCH", `/api/requirements/${card.id}/checklist/a?network_id=${NET}`, { done });
+    expect((await tick(true)).status).toBe(200);
+    expect((await tick(true)).status).toBe(200);
+    let list = of((await events(admin.token)).body.events, card.id);
+    const ticks = list.filter((e: any) => e.field === "checklist_item");
+    expect(ticks.length).toBe(1);
+    expect(ticks[0]).toMatchObject({ old: { id: "a", text: "第一项", done: false }, new: { id: "a", text: "第一项", done: true }, actor: user(member.id) });
+    // a PATCH that only flips one item's done is also `checklist_item`
+    await patch(member.token, card.id, { checklist: [{ id: "a", text: "第一项", done: true }, { id: "b", text: "第二项", done: true }] });
+    await patch(member.token, card.id, { checklist: [{ id: "a", text: "第一项", done: true }, { id: "b", text: "第二项", done: true }, { id: "c", text: "第三项" }] });
+    list = of((await events(admin.token)).body.events, card.id);
+    expect(list[0]).toMatchObject({ field: "checklist", old: { total: 2, done: 2 }, new: { total: 3, done: 2 } });
+    expect(list[1]).toMatchObject({ field: "checklist_item", new: { id: "b", done: true } });
+  });
+
+  test("the actor of a node token is the node", async () => {
+    const card = await create(admin.token, { name: "动态示例四" });
+    expect((await patch(nodeToken, card.id, { column: "doing" })).status).toBe(200);
+    const [e] = of((await events(nodeToken)).body.events, card.id);
+    expect(e).toMatchObject({ field: "column", actor: { kind: "node", id: NODE } });
+  });
+
+  test("tag rename, project delete and card delete each record per-card events", async () => {
+    const p = await send(admin.token, "POST", `/api/requirements/projects?network_id=${NET}`, { name: `动态项目-${Date.now()}` });
+    expect(p.status).toBe(201);
+    const card = await create(admin.token, { name: "动态示例五", tags: ["旧标签"], project_id: p.body.project.id });
+    expect((await send(admin.token, "POST", `/api/requirements/tags/ops?network_id=${NET}`, { op: "rename", from: "旧标签", to: "新标签" })).status).toBe(200);
+    expect((await send(admin.token, "DELETE", `/api/requirements/projects/${p.body.project.id}?network_id=${NET}`)).status).toBe(200);
+    expect((await send(admin.token, "DELETE", `/api/requirements/${card.id}?network_id=${NET}`)).status).toBe(200);
+    const list = of((await events(admin.token)).body.events, card.id);
+    expect(list.slice(0, 3).map((e: any) => [e.kind, e.field])).toEqual([["deleted", null], ["changed", "project"], ["changed", "tags"]]);
+    expect(list[0]).toMatchObject({ title: "动态示例五", seq: expect.any(Number), actor: user(admin.id) });
+    expect(list[1]).toMatchObject({ old: p.body.project.id, new: null });
+    expect(list[2]).toMatchObject({ old: ["旧标签"], new: ["新标签"] });
+  });
+
+  test("the write and its events are one transaction: no events table → the PATCH fails and the card is unchanged", async () => {
+    const { db } = await import("./db.js");
+    const card = await create(admin.token, { name: "动态示例六", priority: "low" });
+    db.exec("ALTER TABLE requirement_events RENAME TO requirement_events_away");
+    try {
+      const r = await patch(admin.token, card.id, { priority: "high" });
+      expect(r.status).toBeGreaterThanOrEqual(500);
+    } finally {
+      db.exec("ALTER TABLE requirement_events_away RENAME TO requirement_events");
+    }
+    const now = await send(admin.token, "GET", `/api/requirements/${card.id}?network_id=${NET}`);
+    expect(now.body.requirement.priority).toBe("low");
+  });
+
+  test("a scoped member sees events only for cards they can see — deleted ones by their tombstone", async () => {
+    const mine = await create(scoped.token, { name: "动态示例七(scoped 自己建的)" });
+    const theirs = await create(admin.token, { name: "动态示例八(scoped 看不见)" });
+    const joined = await create(admin.token, { name: "动态示例九(scoped 是参与人)", participants: [user(scoped.id)] });
+    await patch(admin.token, mine.id, { priority: "high" });
+    await patch(admin.token, theirs.id, { priority: "high" });
+    await send(admin.token, "DELETE", `/api/requirements/${joined.id}?network_id=${NET}`);
+    const seen = (await events(scoped.token, "&limit=500")).body.events;
+    expect(of(seen, mine.id).length).toBe(2);
+    expect(of(seen, theirs.id).length).toBe(0);
+    expect(of(seen, joined.id).map((e: any) => e.kind)).toEqual(["deleted", "created"]);
+    // a filter on a card they cannot see answers like a card with no events
+    expect((await events(scoped.token, `&requirement_id=${theirs.id}`)).body.events).toEqual([]);
+  });
+
+  test("an agent-restricted member: hidden nodes are masked, and an event that only differs by a hidden node is dropped", async () => {
+    const card = await create(admin.token, { name: "动态示例十" });
+    await patch(nodeToken, card.id, { priority: "high" });
+    await patch(admin.token, card.id, { agent_owner: { kind: "node", id: NODE } });
+    await patch(admin.token, card.id, { participants: [user(admin.id), { kind: "node", id: NODE }] });
+    const seen = of((await events(restricted.token)).body.events, card.id);
+    const all = of((await events(admin.token)).body.events, card.id);
+    expect(all.map((e: any) => e.field)).toEqual(["participants", "agent_owner", "priority", null]);
+    expect(seen.map((e: any) => e.field)).toEqual(["participants", "priority", null]);
+    expect(seen[0]).toMatchObject({ old: [], new: [user(admin.id)] });
+    expect(seen[1]).toMatchObject({ field: "priority", actor: null });
+    expect(JSON.stringify(seen)).not.toContain(NODE);
+  });
+
+  test("paging: newest first, limit + next_cursor without overlap; since; bad params 400", async () => {
+    const card = await create(admin.token, { name: "动态示例十一" });
+    for (const priority of ["high", "low", "lowest", "normal"]) await patch(admin.token, card.id, { priority });
+    const q = `&requirement_id=${card.id}`;
+    const p1 = await events(admin.token, `${q}&limit=2`);
+    expect(p1.body.events.length).toBe(2);
+    expect(p1.body.has_more).toBe(true);
+    expect(p1.body.events[0].new).toBe("normal");
+    const p2 = await events(admin.token, `${q}&limit=2&cursor=${p1.body.next_cursor}`);
+    const p3 = await events(admin.token, `${q}&limit=2&cursor=${p2.body.next_cursor}`);
+    const ids = [...p1.body.events, ...p2.body.events, ...p3.body.events].map((e: any) => e.id);
+    expect(new Set(ids).size).toBe(5);
+    expect(p3.body.has_more).toBe(false);
+    expect(p3.body.next_cursor).toBe(null);
+    expect(ids.map(Number)).toEqual([...ids.map(Number)].sort((a, b) => b - a));
+    // since = server_time of an earlier read → only what came after
+    const t = p1.body.server_time;
+    await patch(admin.token, card.id, { priority: "high" });
+    const after = await events(admin.token, `${q}&since=${encodeURIComponent(t)}`);
+    // since is inclusive (>=): an event written in the same millisecond as server_time comes back again,
+    // and clients dedupe by id. Only the events not already seen must be exactly the new one.
+    expect(after.body.events.every((e: any) => Date.parse(e.at) >= Date.parse(t))).toBe(true);
+    const seen = new Set(ids);
+    expect(after.body.events.filter((e: any) => !seen.has(e.id)).map((e: any) => e.new)).toEqual(["high"]);
+    for (const bad of ["&limit=0", "&limit=501", "&limit=x", "&since=nope", "&cursor=abc", "&cursor=0"]) {
+      expect((await events(admin.token, bad)).status).toBe(400);
+    }
+  });
+
+  test("migration is idempotent and leaves the rows alone", async () => {
+    const { db } = await import("./db.js");
+    const { ensureRequirementEvents } = await import("./requirement-events.js");
+    const n = Number(db.get<{ n: number }>("SELECT COUNT(*) AS n FROM requirement_events")!.n);
+    ensureRequirementEvents(db);
+    ensureRequirementEvents(db);
+    expect(Number(db.get<{ n: number }>("SELECT COUNT(*) AS n FROM requirement_events")!.n)).toBe(n);
+    expect(n).toBeGreaterThan(0);
+  });
+});