@sleep2agi/commhub-server 0.9.0-preview.60 → 0.9.0-preview.64

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.60",
+  "version": "0.9.0-preview.64",
   "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/create-node-validate.ts

@@ -205,6 +205,40 @@ export function serializeEnvLocal(env: Record<string, string>): string {
   }).join("\n") + "\n";
 }
 
+// app「新建节点」工作目录 —— hub 只判**形状**(daemon 才知道那台机器的 $HOME、系统目录、
+// 目录里住没住别的节点,那几条在 agent-node/src/runtime/child-workdir.ts)。
+// 这里挡的是「根本不像一条路径」的输入,让它在派发前就失败,而不是占一个请求行再被 daemon 拒。
+export const MAX_WORKDIR_LEN = 1024;
+export function validateWorkdir(s: unknown): asserts s is string | undefined | null {
+  if (s === undefined || s === null) return;
+  if (typeof s !== "string") throw new ValidationError("workdir_invalid", { reason: "must be string" });
+  const v = s.trim();
+  if (v.length === 0 || v.length > MAX_WORKDIR_LEN) {
+    throw new ValidationError("workdir_invalid", { reason: `length 1..${MAX_WORKDIR_LEN}` });
+  }
+  if (/[\u0000-\u001f\u007f]/.test(v)) throw new ValidationError("workdir_invalid", { reason: "control character" });
+  const shapeOk = v.startsWith("/") || v === "~" || v.startsWith("~/") || /^[A-Za-z]:[\\/]/.test(v);
+  if (!shapeOk) {
+    throw new ValidationError("workdir_invalid", { reason: "must be absolute (/…, ~/…, or C:\\…)", value: v.slice(0, 80) });
+  }
+}
+
+/** daemon 自报的默认工作目录根(`daemon_capabilities.default_workdir_root`),消毒后返回;
+ *  没报 / 形状不对 = null。**非 null 即表示该 daemon 认 `node_spec.workdir`** ——
+ *  create_node 的「老 daemon 不收 workdir」门和 /api/host-supervisors 的透出共用这一个判据。 */
+export function daemonDefaultWorkdirRoot(configSnapshot: unknown): string | null {
+  try {
+    const snap = typeof configSnapshot === "string" ? JSON.parse(configSnapshot) : configSnapshot;
+    const v = (snap as any)?.daemon_capabilities?.default_workdir_root;
+    if (typeof v !== "string" || v.length === 0 || v.length > MAX_WORKDIR_LEN) return null;
+    if (/[\u0000-\u001f\u007f]/.test(v)) return null;
+    if (!(v.startsWith("/") || /^[A-Za-z]:[\\/]/.test(v))) return null;
+    return v;
+  } catch {
+    return null;
+  }
+}
+
 // §4.2.5 — channels fail-closed in P1.
 export function validateChannelsP1(channels: unknown): void {
   if (channels === undefined || channels === null) return;

package/src/create-node-workdir.test.ts

@@ -0,0 +1,254 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import "./require-explicit-test-db.js";
+import { db } from "./db.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools } from "./tools.js";
+import { daemonDefaultWorkdirRoot, validateWorkdir, ValidationError } from "./create-node-validate.js";
+import { addNetworkMember, login, register } from "./auth.js";
+
+// app「新建节点」工作目录 —— hub 这一层管三件事:
+//   ① node_spec.workdir 的**形状**(绝对 / ~/… / C:\…),派发前就拒
+//   ② daemon 没自报 default_workdir_root(= 老 daemon,会静默忽略 workdir)⇒ 拒,不派
+//   ③ 请求行存下 workdir,get_create_request 原样交给 daemon;不带就**不出现**这个键
+// 以及 /api/host-supervisors 只给 admin/owner 透出默认根(它是那台机器的家目录路径)。
+
+const NET = "net_workdir_gate";
+const USER_ID = "u_workdir_admin";
+const DAEMON_ID = "node_workdir_daemon";
+const DAEMON_ALIAS = "workdir-daemon";
+const DAEMON_TOK = "tok_workdir_daemon";
+const ROOT = "/home/user";
+
+interface ToolHandler { (args: any, extra?: any): Promise<{ content: Array<{ type: "text"; text: string }> }>; }
+interface Reply { ok?: boolean; error?: string; request_id?: string; node_spec?: any; [k: string]: unknown; }
+
+function cleanup() {
+  for (const t of ["node_create_requests", "audit_log", "nodes", "sessions", "api_tokens", "network_members"]) {
+    try { db.run(`DELETE FROM ${t} WHERE network_id = ?1`, [NET]); } catch {}
+  }
+  try { db.run("DELETE FROM networks WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM users WHERE user_id = ?1", [USER_ID]); } catch {}
+}
+beforeEach(cleanup);
+afterAll(cleanup);
+
+function seed(caps: Record<string, unknown>) {
+  db.run(`INSERT INTO users (user_id, username, password_hash, role, created_at) VALUES (?1, ?1, 'x', 'user', datetime('now'))`, [USER_ID]);
+  db.run(`INSERT OR REPLACE INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?1, ?2, datetime('now'))`, [NET, USER_ID]);
+  db.run(`INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, 'admin', datetime('now'))`, [USER_ID, NET]);
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, config_snapshot, hostname, created_at, updated_at, lifecycle_state)
+     VALUES (?1, ?2, ?2, ?3, ?4, 'host-x', datetime('now'), datetime('now'), 'active')`,
+    [DAEMON_ID, DAEMON_ALIAS, NET, JSON.stringify({ role: "host_supervisor", daemon_capabilities: { runtimes_supported: ["claude-agent-sdk"], ...caps } })],
+  );
+  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)`,
+    [DAEMON_TOK, USER_ID, NET, `node:${DAEMON_ALIAS}`, `hash_${DAEMON_TOK}`],
+  );
+}
+
+function tools(callerTokenId: string | null = null): Record<string, ToolHandler> {
+  const server = new McpServer({ name: "test", version: "0" }) as any;
+  const out: Record<string, ToolHandler> = {};
+  const origTool = server.tool.bind(server);
+  server.tool = (name: string, d: string, schema: any, handler: ToolHandler) => { out[name] = handler; return origTool(name, d, schema, handler); };
+  const origRegisterTool = server.registerTool?.bind(server);
+  if (origRegisterTool) {
+    server.registerTool = (name: string, cfg: any, handler: ToolHandler) => { out[name] = handler; return origRegisterTool(name, cfg, handler); };
+  }
+  registerTools(server, undefined, NET, USER_ID, null, true, callerTokenId);
+  return out;
+}
+
+async function call(h: ToolHandler, args: any): Promise<Reply> {
+  return JSON.parse((await h(args)).content[0].text) as Reply;
+}
+
+const baseSpec = { name: "wd-child", runtime: "claude-agent-sdk", model: "claude-sonnet-4-5", flags: {} };
+
+function rowCount(): number {
+  return db.get<{ n: number }>("SELECT COUNT(*) AS n FROM node_create_requests WHERE daemon_node_id = ?1", DAEMON_ID)?.n ?? -1;
+}
+
+describe("validateWorkdir — shape only", () => {
+  const ok = ["/home/user/proj", "/srv/x", "~", "~/proj", "C:\\Users\\alice\\proj", "D:/work", "  /padded  "];
+  for (const v of ok) test(`accepts ${JSON.stringify(v)}`, () => { expect(() => validateWorkdir(v)).not.toThrow(); });
+  test("accepts undefined / null (field omitted)", () => {
+    expect(() => validateWorkdir(undefined)).not.toThrow();
+    expect(() => validateWorkdir(null)).not.toThrow();
+  });
+  const bad: unknown[] = ["", "   ", "proj", "./proj", "../x", "~alice/x", "C:proj", "/a\nb", "/a\u0000b", "x".repeat(10) + "/", "/" + "a".repeat(1024), 42, {}];
+  for (const v of bad) {
+    test(`rejects ${JSON.stringify(v)?.slice(0, 40)}`, () => {
+      let code = "";
+      try { validateWorkdir(v); } catch (e) { code = (e as ValidationError).code; }
+      expect(code).toBe("workdir_invalid");
+    });
+  }
+});
+
+describe("daemonDefaultWorkdirRoot — sanitize the self-report", () => {
+  const snap = (v: unknown) => JSON.stringify({ daemon_capabilities: { default_workdir_root: v } });
+  test("absolute posix root passes through", () => { expect(daemonDefaultWorkdirRoot(snap(ROOT))).toBe(ROOT); });
+  test("windows root passes through", () => { expect(daemonDefaultWorkdirRoot(snap("C:\\Users\\alice"))).toBe("C:\\Users\\alice"); });
+  test("object snapshot (not string) also accepted", () => {
+    expect(daemonDefaultWorkdirRoot({ daemon_capabilities: { default_workdir_root: ROOT } })).toBe(ROOT);
+  });
+  for (const v of [undefined, null, "", "relative", "~/x", 7, "/a\nb", "/" + "a".repeat(1100)]) {
+    test(`not reported / malformed ${JSON.stringify(v)?.slice(0, 30)} → null`, () => {
+      expect(daemonDefaultWorkdirRoot(snap(v))).toBeNull();
+    });
+  }
+  test("null / garbage snapshot → null", () => {
+    expect(daemonDefaultWorkdirRoot(null)).toBeNull();
+    expect(daemonDefaultWorkdirRoot("{not json")).toBeNull();
+  });
+});
+
+describe("create_node + workdir", () => {
+  test("🔴 old daemon (no default_workdir_root) + workdir → workdir_not_supported_by_daemon, NO row", async () => {
+    seed({});
+    const r = await call(tools().create_node, { daemon_node_id: DAEMON_ID, node_spec: { ...baseSpec, workdir: `${ROOT}/wd-child` } });
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe("workdir_not_supported_by_daemon");
+    expect(rowCount()).toBe(0);
+  });
+
+  test("old daemon WITHOUT workdir still dispatches (no regression for existing callers)", async () => {
+    seed({});
+    const r = await call(tools().create_node, { daemon_node_id: DAEMON_ID, node_spec: baseSpec });
+    expect(r.ok).toBe(true);
+    const row = db.get<{ workdir: string | null }>("SELECT workdir FROM node_create_requests WHERE request_id = ?1", r.request_id);
+    expect(row?.workdir).toBeNull();
+  });
+
+  test("bad shape rejected before dispatch → workdir_invalid, NO row", async () => {
+    seed({ default_workdir_root: ROOT });
+    const r = await call(tools().create_node, { daemon_node_id: DAEMON_ID, node_spec: { ...baseSpec, workdir: "relative/dir" } });
+    expect(r.error).toBe("workdir_invalid");
+    expect(rowCount()).toBe(0);
+  });
+
+  test("new daemon + workdir → row stores it and get_create_request hands it to the daemon", async () => {
+    seed({ default_workdir_root: ROOT });
+    const wd = `${ROOT}/wd-child`;
+    const r = await call(tools().create_node, { daemon_node_id: DAEMON_ID, node_spec: { ...baseSpec, workdir: wd } });
+    expect(r.ok).toBe(true);
+    const row = db.get<{ workdir: string | null }>("SELECT workdir FROM node_create_requests WHERE request_id = ?1", r.request_id);
+    expect(row?.workdir).toBe(wd);
+    const g = await call(tools(DAEMON_TOK).get_create_request, { request_id: r.request_id });
+    expect(g.ok).toBe(true);
+    expect(g.node_spec.workdir).toBe(wd);
+    expect(g.node_spec.name).toBe(baseSpec.name);
+  });
+
+  test("workdir is trimmed before storage", async () => {
+    seed({ default_workdir_root: ROOT });
+    const r = await call(tools().create_node, { daemon_node_id: DAEMON_ID, node_spec: { ...baseSpec, workdir: `  ~/wd-child  ` } });
+    expect(r.ok).toBe(true);
+    const row = db.get<{ workdir: string | null }>("SELECT workdir FROM node_create_requests WHERE request_id = ?1", r.request_id);
+    expect(row?.workdir).toBe("~/wd-child");
+  });
+
+  test("new daemon WITHOUT workdir → get_create_request node_spec has NO workdir key (daemon keeps legacy layout)", async () => {
+    seed({ default_workdir_root: ROOT });
+    const r = await call(tools().create_node, { daemon_node_id: DAEMON_ID, node_spec: baseSpec });
+    expect(r.ok).toBe(true);
+    const g = await call(tools(DAEMON_TOK).get_create_request, { request_id: r.request_id });
+    expect(g.ok).toBe(true);
+    expect("workdir" in g.node_spec).toBe(false);
+  });
+
+  test("audit detail records the requested workdir", async () => {
+    seed({ default_workdir_root: ROOT });
+    const wd = `${ROOT}/wd-child`;
+    const r = await call(tools().create_node, { daemon_node_id: DAEMON_ID, node_spec: { ...baseSpec, workdir: wd } });
+    const a = db.get<{ detail: string }>(
+      "SELECT detail FROM audit_log WHERE target_id = ?1 AND action = 'create_node_dispatch_attempted'", r.request_id,
+    );
+    expect(JSON.parse(a?.detail || "{}").workdir).toBe(wd);
+  });
+
+  test("list_host_supervisors (MCP) surfaces default_workdir_root for admin", async () => {
+    seed({ default_workdir_root: ROOT });
+    const r = await call(tools().list_host_supervisors, {});
+    const d = (r as any).daemons.find((x: any) => x.daemon_node_id === DAEMON_ID);
+    expect(d.default_workdir_root).toBe(ROOT);
+  });
+
+  test("list_host_supervisors (MCP) omits the key for an old daemon", async () => {
+    seed({});
+    const r = await call(tools().list_host_supervisors, {});
+    const d = (r as any).daemons.find((x: any) => x.daemon_node_id === DAEMON_ID);
+    expect(d).toBeDefined();
+    expect("default_workdir_root" in d).toBe(false);
+  });
+});
+
+// ── REST /api/host-supervisors: admin sees the root, member does not ──────────
+let BASE = "";
+let server: any = null;
+let ownerTok = "", memberTok = "", restNet = "", ownerId = "";
+describe("/api/host-supervisors — default_workdir_root visibility", () => {
+  beforeAll(async () => {
+    process.env.HOST = "127.0.0.1";
+    const sfx = `${Date.now()}_${Math.floor(Math.random() * 1000)}`;
+    const pw = "BootstrapPw123Aa!";
+    const s = register(`wd_seed_${sfx}`, pw, undefined, "seed");
+    if (!s.ok) throw new Error("seed failed");
+    db.run("UPDATE users SET role = 'admin' WHERE username = ?1", [`wd_seed_${sfx}`]);
+    const o = register(`wd_owner_${sfx}`, pw, undefined, "seed");
+    if (!o.ok || !o.token) throw new Error("owner register failed");
+    ownerTok = o.token; restNet = o.network_id ?? "";
+    ownerId = login(`wd_owner_${sfx}`, pw).user!.user_id;
+    const m = register(`wd_member_${sfx}`, pw, undefined, "seed");
+    if (!m.ok || !m.token) throw new Error("member register failed");
+    memberTok = m.token;
+    const memberId = login(`wd_member_${sfx}`, pw).user!.user_id;
+    const add = addNetworkMember(restNet, memberId, "member");
+    if (!add.ok) throw new Error("add member failed: " + add.error);
+    const { bootServer } = await import("./server.js");
+    server = bootServer({ port: 0, hostname: "127.0.0.1" });
+    BASE = `http://127.0.0.1:${server.port}`;
+    for (const [alias, caps] of [["wd-new", { default_workdir_root: ROOT }], ["wd-old", {}]] as const) {
+      db.run(
+        `INSERT OR REPLACE INTO nodes (node_id, node_name, alias, runtime, model, config_path, channels, server, hostname, network_id, config_revision, config_snapshot)
+         VALUES (?1, ?2, ?2, 'claude-agent-sdk', 'm', '/tmp/cfg.json', '[]', 'h', 'h', ?3, 0, ?4)`,
+        [`wd_n_${alias}`, alias, restNet, JSON.stringify({ role: "host_supervisor", daemon_capabilities: caps })],
+      );
+      db.run(
+        `INSERT OR REPLACE INTO api_tokens (token_id, token_hash, user_id, network_id, name, scope) VALUES (?1, ?2, ?3, ?4, ?5, 'network')`,
+        [`wd_t_${alias}`, `hash_wd_${alias}`, ownerId, restNet, `node:${alias}`],
+      );
+    }
+  });
+  afterAll(() => {
+    try { server?.stop?.(true); } catch {}
+    try { db.run("DELETE FROM nodes WHERE network_id = ?1", [restNet]); } catch {}
+    try { db.run("DELETE FROM api_tokens WHERE network_id = ?1 AND name LIKE 'node:%'", [restNet]); } catch {}
+  });
+
+  async function list(tok: string): Promise<any[]> {
+    const res = await fetch(`${BASE}/api/host-supervisors?network_id=${encodeURIComponent(restNet)}`, { headers: { Authorization: `Bearer ${tok}` } });
+    const b = await res.json();
+    if (!b.ok) throw new Error("list failed: " + JSON.stringify(b));
+    return b.daemons;
+  }
+
+  test("owner sees default_workdir_root on the new daemon", async () => {
+    const d = (await list(ownerTok)).find(x => x.alias === "wd-new");
+    expect(d?.default_workdir_root).toBe(ROOT);
+  });
+  test("old daemon row has NO default_workdir_root key (app hides the row)", async () => {
+    const d = (await list(ownerTok)).find(x => x.alias === "wd-old");
+    expect(d).toBeDefined();
+    expect("default_workdir_root" in d).toBe(false);
+  });
+  test("🔴 member does NOT see the host's home path", async () => {
+    const rows = await list(memberTok);
+    const d = rows.find(x => x.alias === "wd-new");
+    expect(d).toBeDefined();
+    expect("default_workdir_root" in d).toBe(false);
+  });
+});

package/src/db.ts

@@ -733,6 +733,15 @@ function migrateNodeCreateRequestsModelNullable() {
 }
 migrateNodeCreateRequestsModelNullable();
 
+// app「新建节点」工作目录 —— 请求带的 node_spec.workdir(可空;空 = 落 daemon cwd 的老行为)。
+// 🔴 必须排在上面那个重建表迁移**之后**:它按显式列清单拷贝,排在前面的话,老库(model NOT NULL)
+//    第一次启动时这一列会被重建吞掉。
+try {
+  db.exec(`ALTER TABLE node_create_requests ADD COLUMN workdir TEXT`);
+} catch (e: any) {
+  if (!/duplicate column|already exists/i.test(e?.message || "")) throw e;
+}
+
 // #1493 — 把 user_inbox.network_id 升到 **schema 级 NOT NULL**(belt-and-suspenders,
 // 叠在 send_desktop_message 的代码级三闸之上:canWrite / `!effectiveNetId` return /
 // getUserNetworkRole,tools.ts)。「不产生 network_id=NULL 孤儿」现是代码级保证 + #1492
@@ -941,6 +950,32 @@ db.exec(`
     ON skillhub_skills(network_id, slug, version);
 `);
 
+// 需求池。长期卡片，按 network 隔离。不是 tasks。
+db.exec(`
+  CREATE TABLE IF NOT EXISTS requirements (
+    requirement_id TEXT PRIMARY KEY,
+    network_id     TEXT NOT NULL,
+    title          TEXT NOT NULL,
+    column_name    TEXT NOT NULL DEFAULT 'pool' CHECK(column_name IN ('pool', 'doing', 'done')),
+    priority       TEXT NOT NULL DEFAULT 'normal' CHECK(priority IN ('high', 'normal', 'low')),
+    due_on         TEXT,
+    assignee       TEXT,
+    client_id      TEXT,
+    issues_json    TEXT,
+    created_by     TEXT,
+    created_at     TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at     TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+  CREATE INDEX IF NOT EXISTS idx_requirements_network
+    ON requirements(network_id, created_at DESC);
+`);
+try { db.exec("ALTER TABLE requirements ADD COLUMN client_id TEXT"); } catch {}
+try { db.exec("ALTER TABLE requirements ADD COLUMN issues_json TEXT"); } catch {}
+db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_requirements_client ON requirements(network_id, client_id) WHERE client_id IS NOT NULL AND client_id != ''");
+for (const column of ["owner_json TEXT", "participants_json TEXT NOT NULL DEFAULT '[]'"]) {
+  try { db.exec(`ALTER TABLE requirements ADD COLUMN ${column}`); } catch (e: any) { if (!/duplicate column|already exists/i.test(e?.message || "")) throw e; }
+}
+
 // ── V3: licenses table ──
 db.exec(`
   CREATE TABLE IF NOT EXISTS licenses (

package/src/inbox-count-sse.test.ts

@@ -302,7 +302,7 @@ describe("#1440 broadcast delivery set", () => {
     expect(res.message_ids).toHaveLength(3);
     // #1440 ③ — `recipients` counted candidates, not deliveries, so it
     // disagreed with the documented invariant
-    // ("message_ids.length === recipients", docs-site/docs/api/rest.md)
+    // ("message_ids.length === recipients", docs-site/docs/api/rest-data.md)
     // exactly when a node was skipped. 4 sessions, 3 delivered.
     expect(res.recipients).toBe(res.message_ids.length);
     expect(res.recipients).toBe(3);

package/src/requirements-http.test.ts

@@ -0,0 +1,196 @@
+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-requirements-"));
+process.env.COMMHUB_DB = join(dir, "hub.db");
+
+let server: { port: number; stop?: (force?: boolean) => void };
+let base = "";
+let ownerToken = "";
+let viewerToken = "";
+let otherToken = "";
+let nodeToken = "";
+let ownerNetwork = "";
+
+async function api(token: string, path: string, init?: RequestInit) {
+  const res = await fetch(`${base}${path}`, {
+    ...init,
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...(init?.headers || {}) },
+  });
+  return { status: res.status, body: await res.json() as any };
+}
+
+beforeAll(async () => {
+  const { db } = await import("./db.js");
+  const { addNetworkMember, createNetworkTokenForNode, register } = await import("./auth.js");
+  const owner = register(`req_owner_${Date.now()}`, "RequirementsOwner123!", undefined, "seed");
+  expect(owner.ok).toBe(true);
+  ownerToken = owner.token!;
+  ownerNetwork = owner.network_id!;
+  const networkId = owner.network_id!;
+  const ownerId = db.get<{ owner_id: string }>("SELECT owner_id FROM networks WHERE network_id = ?1", networkId)!.owner_id;
+  const viewer = register(`req_viewer_${Date.now()}`, "RequirementsViewer123!", undefined, "seed");
+  expect(viewer.ok).toBe(true);
+  viewerToken = viewer.token!;
+  const viewerId = db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", viewer.user!.username)!.user_id;
+  addNetworkMember(networkId, viewerId, "viewer", ownerId);
+  const ntok = createNetworkTokenForNode(ownerId, networkId, "req-node");
+  expect(ntok.ok).toBe(true);
+  nodeToken = ntok.token!;
+  const other = register(`req_other_${Date.now()}`, "RequirementsOther123!", undefined, "seed");
+  expect(other.ok).toBe(true);
+  otherToken = other.token!;
+  const mod: any = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { server?.stop?.(true); } catch {}
+  try { rmSync(dir, { recursive: true, force: true }); } catch {}
+});
+
+describe("requirements stay on the hub", () => {
+  let id = "";
+
+  test("typed assignments validate network membership, preserve kinds and clear explicitly", async () => {
+    const { db } = await import('./db.js');
+    const ownerId = db.get<{ owner_id: string }>('SELECT owner_id FROM networks WHERE network_id=?1', ownerNetwork)!.owner_id;
+    db.run('INSERT INTO nodes(node_id,node_name,alias,display_name,network_id) VALUES (?1,?2,?2,?3,?4)', [ownerId, 'same-name', '自定义 Agent 名', ownerNetwork]);
+    db.run('INSERT INTO nodes(node_id,node_name,network_id) VALUES (?1,?2,?3)', ['foreign-person-node', 'foreign-node', 'other-network']);
+    const people = await api(ownerToken, `/api/requirements/people?network_id=${ownerNetwork}`);
+    expect(people.status).toBe(200);
+    expect(people.body.people.some((p: any) => p.id === ownerId && p.kind === 'user')).toBe(true);
+    expect(people.body.people.some((p: any) => p.id === ownerId && p.kind === 'node' && p.name === '自定义 Agent 名')).toBe(true);
+    expect(people.body.people.every((p: any) => p.networkId === ownerNetwork)).toBe(true);
+    const user = { kind: 'user', id: ownerId };
+    const node = { kind: 'node', id: ownerId };
+    const created = await api(ownerToken, '/api/requirements', { method: 'POST', body: JSON.stringify({ name: 'typed people', owner: user, participants: [user, node, user] }) });
+    expect(created.status).toBe(201);
+    expect(created.body.requirement.owner).toEqual(user);
+    expect(created.body.requirement.participants).toEqual([user, node]);
+    const path = `/api/requirements/${created.body.requirement.id}`;
+    const changed = await api(ownerToken, path, { method: 'PATCH', body: JSON.stringify({ owner: node }) });
+    expect(changed.status).toBe(200);
+    expect(changed.body.requirement.owner).toEqual(node);
+    expect(changed.body.requirement.participants).toEqual([user, node]);
+    expect(changed.body.requirement.column).toBe('pool');
+    for (const token of [viewerToken, nodeToken]) {
+      expect((await api(token, path, { method: 'PATCH', body: JSON.stringify({ owner: null, participants: [] }) })).status).toBe(403);
+    }
+    expect((await api(otherToken, path, { method: 'PATCH', body: JSON.stringify({ owner: null }) })).status).toBe(404);
+    for (const invalid of [{ kind: 'node', id: 'foreign-person-node' }, { kind: 'user', id: 'unknown' }, { kind: 'admin', id: ownerId }]) {
+      expect((await api(ownerToken, path, { method: 'PATCH', body: JSON.stringify({ participants: [invalid] }) })).status).toBe(400);
+    }
+    const listed = await api(ownerToken, '/api/requirements');
+    expect(listed.body.requirements.find((row: any) => row.id === created.body.requirement.id).owner).toEqual(node);
+    const cleared = await api(ownerToken, path, { method: 'PATCH', body: JSON.stringify({ owner: null, participants: [] }) });
+    expect(cleared.status).toBe(200);
+    expect(cleared.body.requirement.owner).toBeNull();
+    expect(cleared.body.requirement.participants).toEqual([]);
+  });
+
+  test("owner creates a card in the pool", async () => {
+    const created = await api(ownerToken, "/api/requirements", {
+      method: "POST",
+      body: JSON.stringify({ name: "多端同步", priority: "high", assignee: "node-a", due: "2026-10-01" }),
+    });
+    expect(created.status).toBe(201);
+    expect(created.body.requirement.column).toBe("pool");
+    expect(created.body.requirement.name).toBe("多端同步");
+    expect(created.body.requirement.assignee).toBe("node-a");
+    expect(created.body.requirement.due).toBe("2026-10-01");
+    id = created.body.requirement.id;
+  });
+
+  test("the same account reads it back", async () => {
+    const listed = await api(ownerToken, "/api/requirements");
+    expect(listed.status).toBe(200);
+    expect(listed.body.requirements.some((row: { id: string }) => row.id === id)).toBe(true);
+  });
+
+  test("moving a card is stored on the hub", async () => {
+    const moved = await api(ownerToken, `/api/requirements/${id}`, {
+      method: "PATCH",
+      body: JSON.stringify({ column: "doing" }),
+    });
+    expect(moved.status).toBe(200);
+    expect(moved.body.requirement.column).toBe("doing");
+  });
+
+  test("another network cannot see it", async () => {
+    const listed = await api(otherToken, "/api/requirements");
+    expect(listed.status).toBe(200);
+    expect(listed.body.requirements.some((row: { id: string }) => row.id === id)).toBe(false);
+  });
+
+  test("a viewer cannot add or move", async () => {
+    const denied = await api(viewerToken, "/api/requirements", {
+      method: "POST",
+      body: JSON.stringify({ name: "不行", network_id: ownerNetwork }),
+    });
+    expect(denied.status).toBe(403);
+    const move = await api(viewerToken, `/api/requirements/${id}`, {
+      method: "PATCH",
+      body: JSON.stringify({ column: "done" }),
+    });
+    expect(move.status).toBe(403);
+  });
+
+  test("a node token cannot use the board", async () => {
+    const denied = await api(nodeToken, "/api/requirements");
+    expect(denied.status).toBe(403);
+  });
+
+  test("the same client_id does not create a second card", async () => {
+    const first = await api(ownerToken, "/api/requirements", {
+      method: "POST",
+      body: JSON.stringify({ name: "迁移甲", client_id: "local_card_1", column: "doing" }),
+    });
+    expect(first.status).toBe(201);
+    expect(first.body.requirement.column).toBe("doing");
+    const again = await api(ownerToken, "/api/requirements", {
+      method: "POST",
+      body: JSON.stringify({ name: "迁移甲", client_id: "local_card_1", column: "done" }),
+    });
+    expect(again.status).toBe(200);
+    expect(again.body.requirement.id).toBe(first.body.requirement.id);
+    expect(again.body.requirement.column).toBe("doing");
+    const listed = await api(ownerToken, "/api/requirements");
+    const matches = listed.body.requirements.filter((row: { id: string }) => row.id === first.body.requirement.id);
+    expect(matches.length).toBe(1);
+  });
+
+  test("a card can bind a github issue and a bad link is rejected", async () => {
+    const created = await api(ownerToken, "/api/requirements", {
+      method: "POST",
+      body: JSON.stringify({
+        name: "绑 issue",
+        issues: [{ url: "https://github.com/sleep2agi/agent-network-app/issues/472", title: "picker" }],
+      }),
+    });
+    expect(created.status).toBe(201);
+    expect(created.body.requirement.issues).toEqual([
+      { repo: "sleep2agi/agent-network-app", number: 472, title: "picker" },
+    ]);
+    const moved = await api(ownerToken, `/api/requirements/${created.body.requirement.id}`, {
+      method: "PATCH",
+      body: JSON.stringify({ column: "doing" }),
+    });
+    expect(moved.body.requirement.issues[0].number).toBe(472);
+    const bad = await api(ownerToken, `/api/requirements/${created.body.requirement.id}`, {
+      method: "PATCH",
+      body: JSON.stringify({ issues: ["javascript:alert(1)"] }),
+    });
+    expect(bad.status).toBe(400);
+  });
+
+  test("empty name and a bad date are rejected", async () => {
+    const empty = await api(ownerToken, "/api/requirements", { method: "POST", body: JSON.stringify({ name: "  " }) });
+    expect(empty.status).toBe(400);
+    const date = await api(ownerToken, "/api/requirements", { method: "POST", body: JSON.stringify({ name: "日期", due: "2026-13-01" }) });
+    expect(date.status).toBe(400);
+  });
+});