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

package/package.json

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

@@ -133,6 +133,9 @@ for (const col of [
   // Project folder view — the same session answers files_list / file_read on the
   // rules-file doorbell (node-files.ts). Sticky, bound-token only, like above.
   { name: "files_capable", def: "INTEGER NOT NULL DEFAULT 0" },
+  // Node run-log view — the same session answers logs_tail on the rules-file
+  // doorbell (node-logs.ts). Sticky, bound-token only, like above.
+  { name: "logs_capable", def: "INTEGER NOT NULL DEFAULT 0" },
 ]) {
   try { db.exec(`ALTER TABLE sessions ADD COLUMN ${col.name} ${col.def}`); } catch {}
 }
@@ -972,7 +975,7 @@ db.exec(`
 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 '[]'"]) {
+for (const column of ["owner_json TEXT", "participants_json TEXT NOT NULL DEFAULT '[]'", "agent_owner_json TEXT", "description TEXT", "checklist_json TEXT", "project_id TEXT"]) {
   try { db.exec(`ALTER TABLE requirements ADD COLUMN ${column}`); } catch (e: any) { if (!/duplicate column|already exists/i.test(e?.message || "")) throw e; }
 }
 

package/src/node-logs-transport.test.ts

@@ -0,0 +1,263 @@
+// Node run-log view — tail_node_logs rides the rules-file queue + doorbell (op logs_tail).
+//
+// Hub-side contract verified here:
+//   1. report_status { logs_capable: true } is sticky and set only by the node's
+//      own token; /api/status-shaped rows expose it.
+//   2. The pulled request carries only the normalised filter JSON — no path field
+//      exists anywhere in the tool schema; unknown args are dropped.
+//   3. Who may ask: user logins only (node tokens refused); the network owner/admin,
+//      or the node's owner (nodes.owner_user_id). A member who does not own the
+//      node, a viewer, and a user of another network are refused before any row.
+//   4. Who may read: only the token that asked (like the project folder).
+//   5. Storage: the result is handed out ONCE — the first terminal read purges
+//      result_content and the filter JSON; the second read says content_purged.
+//      An unread terminal result is purged by the sweep after LOGS_CONTENT_TTL_MS.
+//   6. Own single-flight lane; logs acks may carry up to 1 MiB.
+//
+// 跑法：cd server && COMMHUB_DB=/tmp/logs-transport.db bun test src/node-logs-transport.test.ts
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { db } from "./db.js";
+import { registerTools } from "./tools.js";
+import { LOGS_CONTENT_TTL_MS, sweepNodeRequestContent } from "./node-request-retention.js";
+
+const NET = "net_logs_t";
+const OTHER_NET = "net_logs_t_other";
+const OWNER = "u_logs_net_owner";
+const MEMBER = "u_logs_member_owns_a";
+const MEMBER2 = "u_logs_member_plain";
+const VIEWER = "u_logs_viewer";
+const OUTSIDER = "u_logs_outsider";
+const NODE_A = "logs-node-a";
+const NODE_B = "logs-node-b";
+const NODE_A_ID = "node_logs_a";
+const NODE_B_ID = "node_logs_b";
+const T_A = "tok_logs_node_a";
+const T_B = "tok_logs_node_b";
+
+function cleanup() {
+  for (const net of [NET, OTHER_NET]) {
+    for (const t of ["node_rules_requests", "sessions", "nodes", "api_tokens", "network_members", "networks"]) {
+      try { db.run(`DELETE FROM ${t} WHERE network_id = ?1`, [net]); } catch {}
+    }
+  }
+  for (const u of [OWNER, MEMBER, MEMBER2, VIEWER, OUTSIDER]) {
+    try { db.run("DELETE FROM users WHERE user_id = ?1", [u]); } catch {}
+  }
+}
+
+function seedWorld() {
+  for (const u of [OWNER, MEMBER, MEMBER2, VIEWER, OUTSIDER]) {
+    db.run(`INSERT INTO users (user_id, username, password_hash, role, created_at) VALUES (?1, ?2, 'x', 'user', datetime('now'))`, [u, u]);
+  }
+  db.run(`INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?2, ?3, datetime('now'))`, [NET, NET, OWNER]);
+  db.run(`INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?2, ?3, datetime('now'))`, [OTHER_NET, OTHER_NET, OUTSIDER]);
+  const member = (u: string, net: string, role: string) =>
+    db.run(`INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, ?3, datetime('now'))`, [u, net, role]);
+  member(OWNER, NET, "owner");
+  member(MEMBER, NET, "member");
+  member(MEMBER2, NET, "member");
+  member(VIEWER, NET, "viewer");
+  member(OUTSIDER, OTHER_NET, "owner");
+  const node = (id: string, alias: string, owner: string | null) => db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, owner_user_id, created_at, updated_at) VALUES (?1, ?2, ?3, ?4, ?5, datetime('now'), datetime('now'))`,
+    [id, alias, alias, NET, owner],
+  );
+  node(NODE_A_ID, NODE_A, MEMBER);
+  node(NODE_B_ID, NODE_B, OWNER);
+  const tok = (id: string, alias: string, bound: string) => db.run(
+    `INSERT INTO api_tokens (token_id, user_id, network_id, scope, name, token_hash, expires_at, revoked_at, bound_node_id) VALUES (?1, ?2, ?3, 'network', ?4, ?5, NULL, NULL, ?6)`,
+    [id, OWNER, NET, `node:${alias}`, `hash_${id}`, bound],
+  );
+  tok(T_A, NODE_A, NODE_A_ID);
+  tok(T_B, NODE_B, NODE_B_ID);
+}
+
+type Identity = { net: string | null; user: string; alias: string; isNetworkToken: boolean; tokenId: string };
+const asOwner: Identity = { net: null, user: OWNER, alias: OWNER, isNetworkToken: false, tokenId: "tok_logs_owner_login" };
+const asOwnerOtherLogin: Identity = { ...asOwner, tokenId: "tok_logs_owner_login_2" };
+const asMember: Identity = { net: null, user: MEMBER, alias: MEMBER, isNetworkToken: false, tokenId: "tok_logs_member_login" };
+const asMember2: Identity = { net: null, user: MEMBER2, alias: MEMBER2, isNetworkToken: false, tokenId: "tok_logs_member2_login" };
+const asViewer: Identity = { net: null, user: VIEWER, alias: VIEWER, isNetworkToken: false, tokenId: "tok_logs_viewer_login" };
+const asOutsider: Identity = { net: null, user: OUTSIDER, alias: OUTSIDER, isNetworkToken: false, tokenId: "tok_logs_outsider_login" };
+const asA: Identity = { net: NET, user: OWNER, alias: NODE_A, isNetworkToken: true, tokenId: T_A };
+const asB: Identity = { net: NET, user: OWNER, alias: NODE_B, isNetworkToken: true, tokenId: T_B };
+
+async function connect(id: Identity) {
+  const server = new McpServer({ name: "logs-test", version: "1" });
+  registerTools(server, undefined, id.net, id.user, id.alias, id.isNetworkToken, id.tokenId);
+  const client = new Client({ name: "logs-client", version: "1" });
+  const [ct, st] = InMemoryTransport.createLinkedPair();
+  await server.connect(st);
+  await client.connect(ct);
+  const call = async (name: string, args: Record<string, unknown>) => {
+    const r: any = await client.callTool({ name, arguments: args });
+    const first = r.content?.[0];
+    if (!first || first.type !== "text") throw new Error(`no text result from ${name}: ${JSON.stringify(r).slice(0, 300)}`);
+    try { return JSON.parse(first.text); } catch { return { raw: first.text, isError: r.isError === true }; }
+  };
+  const close = async () => { await client.close(); await server.close(); };
+  return { call, close };
+}
+
+const rowCount = () => db.get<{ n: number }>("SELECT COUNT(*) AS n FROM node_rules_requests WHERE network_id = ?1", NET)!.n;
+const row = (id: string) => db.get<any>("SELECT op, content, result_content, content_purged_at FROM node_rules_requests WHERE request_id = ?1", id);
+const SAMPLE = JSON.stringify({ files: ["2026-09-29.log"], lines: [{ ts: 1, level: "info", text: "[10:00:00] [INFO ] [x] hello", key: "2026-09-29.log:0" }], truncated: false, matched: 1, now_ts: 2 });
+
+beforeEach(() => { cleanup(); seedWorld(); });
+afterAll(cleanup);
+
+describe("logs_capable", () => {
+  test("set by the node's own token, sticky, not settable by a user login", async () => {
+    const a = await connect(asA);
+    try {
+      await a.call("report_status", { resume_id: `sdk-${NODE_A_ID}`, alias: NODE_A, status: "idle", node_id: NODE_A_ID, logs_capable: true });
+      await a.call("report_status", { resume_id: `sdk-${NODE_A_ID}`, alias: NODE_A, status: "idle", node_id: NODE_A_ID });
+    } finally { await a.close(); }
+    expect(db.get<{ c: number }>("SELECT logs_capable AS c FROM sessions WHERE alias = ?1 AND network_id = ?2", NODE_A, NET)?.c).toBe(1);
+    const u = await connect(asOwner);
+    try {
+      await u.call("report_status", { resume_id: "user-logs-report", alias: NODE_B, status: "idle", network_id: NET, logs_capable: true });
+    } finally { await u.close(); }
+    expect(db.get<{ c: number }>("SELECT logs_capable AS c FROM sessions WHERE alias = ?1 AND network_id = ?2", NODE_B, NET)?.c ?? 0).toBe(0);
+  }, 20_000);
+});
+
+describe("round trip", () => {
+  test("the node pulls only the normalised filter JSON (no path), acks, the asker reads it once", async () => {
+    const u = await connect(asOwner);
+    const a = await connect(asA);
+    try {
+      const enq = await u.call("tail_node_logs", { node_id: NODE_A_ID, network_id: NET, lines: 99999 > 2000 ? 2000 : 1, level: "warn", grep: "boom", since_ts: 5, path: "/etc/passwd" });
+      expect(enq).toMatchObject({ ok: true, op: "logs_tail" });
+      const pulled = (await a.call("get_rules_file_request", {})).request;
+      expect(pulled.op).toBe("logs_tail");
+      expect(JSON.parse(pulled.content)).toEqual({ lines: 2000, level: "warn", grep: "boom", since_ts: 5 });
+      expect(pulled.content).not.toContain("passwd");
+      expect(await a.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", file_name: "logs", exists: true, content: SAMPLE })).toMatchObject({ ok: true, status: "done" });
+
+      const first = await u.call("get_rules_file_result", { request_id: enq.request_id, network_id: NET });
+      expect(first).toMatchObject({ ok: true, op: "logs_tail", status: "done", content: SAMPLE });
+      // Read-once: purged in the same call, including the filter JSON.
+      expect(row(enq.request_id)).toMatchObject({ result_content: null, content: null });
+      expect(row(enq.request_id).content_purged_at).toBeGreaterThan(0);
+      const second = await u.call("get_rules_file_result", { request_id: enq.request_id, network_id: NET });
+      expect(second.content).toBeUndefined();
+      expect(second.content_purged).toBe(true);
+    } finally { await u.close(); await a.close(); }
+  }, 20_000);
+
+  test("lines above 2000 are refused by the schema; bad level refused", async () => {
+    const u = await connect(asOwner);
+    try {
+      expect((await u.call("tail_node_logs", { node_id: NODE_A_ID, network_id: NET, lines: 2001 })).ok).not.toBe(true);
+      expect((await u.call("tail_node_logs", { node_id: NODE_A_ID, network_id: NET, level: "debug" })).ok).not.toBe(true);
+      expect(rowCount()).toBe(0);
+    } finally { await u.close(); }
+  }, 20_000);
+});
+
+describe("who may ask", () => {
+  test("node tokens are refused — for other nodes and for themselves", async () => {
+    const a = await connect(asA);
+    try {
+      expect(await a.call("tail_node_logs", { node_id: NODE_B_ID })).toMatchObject({ ok: false, error: "node_token_cannot_read_logs" });
+      expect(await a.call("tail_node_logs", { node_id: NODE_A_ID })).toMatchObject({ ok: false, error: "node_token_cannot_read_logs" });
+      expect(rowCount()).toBe(0);
+    } finally { await a.close(); }
+  }, 20_000);
+
+  test("node owner yes; plain member no; viewer no; network owner yes", async () => {
+    const m = await connect(asMember);
+    const m2 = await connect(asMember2);
+    const v = await connect(asViewer);
+    const o = await connect(asOwner);
+    try {
+      expect(await m.call("tail_node_logs", { node_id: NODE_A_ID, network_id: NET })).toMatchObject({ ok: true });
+      expect(await m.call("tail_node_logs", { node_id: NODE_B_ID, network_id: NET })).toMatchObject({ ok: false, error: "logs_permission_denied" });
+      expect(await m2.call("tail_node_logs", { node_id: NODE_A_ID, network_id: NET })).toMatchObject({ ok: false, error: "logs_permission_denied" });
+      expect((await v.call("tail_node_logs", { node_id: NODE_B_ID, network_id: NET })).ok).toBe(false);
+      expect(await o.call("tail_node_logs", { node_id: NODE_B_ID, network_id: NET })).toMatchObject({ ok: true });
+      expect(rowCount()).toBe(2);
+    } finally { await m.close(); await m2.close(); await v.close(); await o.close(); }
+  }, 20_000);
+
+  test("a user of another network is refused (cross network)", async () => {
+    const x = await connect(asOutsider);
+    try {
+      const r1 = await x.call("tail_node_logs", { node_id: NODE_A_ID, network_id: NET });
+      expect(r1.ok).toBe(false);
+      const r2 = await x.call("tail_node_logs", { node_id: NODE_A_ID, network_id: OTHER_NET });
+      expect(r2).toMatchObject({ ok: false, error: "cross_network_node" });
+      expect(rowCount()).toBe(0);
+    } finally { await x.close(); }
+  }, 20_000);
+});
+
+describe("who may read", () => {
+  test("only the login that asked; another login of the same user, node tokens and the serving node cannot", async () => {
+    const u = await connect(asOwner);
+    const other = await connect(asOwnerOtherLogin);
+    const b = await connect(asB);
+    const a = await connect(asA);
+    try {
+      const enq = await u.call("tail_node_logs", { node_id: NODE_A_ID, network_id: NET });
+      await a.call("get_rules_file_request", {});
+      await a.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", content: SAMPLE });
+      expect(await other.call("get_rules_file_result", { request_id: enq.request_id, network_id: NET })).toMatchObject({ ok: false, error: "request_not_found" });
+      expect(await b.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ ok: false, error: "request_not_found" });
+      expect(await a.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ ok: false, error: "request_not_found" });
+      // Those refusals did not consume the read-once result.
+      expect(await u.call("get_rules_file_result", { request_id: enq.request_id, network_id: NET })).toMatchObject({ status: "done", content: SAMPLE });
+    } finally { await u.close(); await other.close(); await b.close(); await a.close(); }
+  }, 20_000);
+
+  test("node B never pulls or acks node A's logs request", async () => {
+    const u = await connect(asOwner);
+    const a = await connect(asA);
+    const b = await connect(asB);
+    try {
+      const enq = await u.call("tail_node_logs", { node_id: NODE_A_ID, network_id: NET });
+      expect((await b.call("get_rules_file_request", {})).request).toBeNull();
+      expect(await b.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", content: "{\"forged\":true}" })).toMatchObject({ ignored: "unknown_or_foreign_request" });
+      expect((await a.call("get_rules_file_request", {})).request.request_id).toBe(enq.request_id);
+    } finally { await u.close(); await a.close(); await b.close(); }
+  }, 20_000);
+});
+
+describe("storage and lanes", () => {
+  test("an unread terminal result is purged by the sweep after the logs TTL; other ops keep theirs", async () => {
+    const u = await connect(asOwner);
+    const a = await connect(asA);
+    try {
+      const enq = await u.call("tail_node_logs", { node_id: NODE_A_ID, network_id: NET });
+      const rules = await u.call("read_node_rules_file", { node_id: NODE_A_ID, network_id: NET });
+      await a.call("get_rules_file_request", {});
+      await a.call("get_rules_file_request", {});
+      await a.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", content: SAMPLE });
+      await a.call("ack_rules_file_request", { request_id: rules.request_id, status: "done", content: "# rules" });
+      sweepNodeRequestContent(Date.now() + LOGS_CONTENT_TTL_MS - 5_000);
+      expect(row(enq.request_id).result_content).toBe(SAMPLE);
+      sweepNodeRequestContent(Date.now() + LOGS_CONTENT_TTL_MS + 5_000);
+      expect(row(enq.request_id)).toMatchObject({ result_content: null, content: null });
+      expect(row(rules.request_id).result_content).toBe("# rules");
+    } finally { await u.close(); await a.close(); }
+  }, 20_000);
+
+  test("own single-flight lane; a 1 MiB-class ack is accepted", async () => {
+    const u = await connect(asOwner);
+    const a = await connect(asA);
+    try {
+      expect(await u.call("list_node_files", { node_id: NODE_A_ID, network_id: NET })).toMatchObject({ ok: true });
+      const first = await u.call("tail_node_logs", { node_id: NODE_A_ID, network_id: NET });
+      expect(first).toMatchObject({ ok: true });
+      expect(await u.call("tail_node_logs", { node_id: NODE_A_ID, network_id: NET })).toMatchObject({ ok: false, error: "request_in_flight", existing_request_id: first.request_id });
+      await a.call("get_rules_file_request", {});
+      await a.call("get_rules_file_request", {});
+      const big = "x".repeat(700 * 1024);
+      expect(await a.call("ack_rules_file_request", { request_id: first.request_id, status: "done", content: big })).toMatchObject({ ok: true, status: "done" });
+    } finally { await u.close(); await a.close(); }
+  }, 20_000);
+});

package/src/node-request-retention.ts

@@ -29,6 +29,13 @@
 //      was just nulled (it would otherwise receive `content: ""` and write an
 //      empty rules file).
 //   3. Rows older than ROW_TTL_MS are deleted outright.
+//   4. Run logs (op = logs_tail) are stricter: read-once with NO grace — the
+//      first authorized terminal read purges them in the same call
+//      (purgeLogsResultNow), because the app never follows another request's
+//      logs result (it simply asks again) and a process log is the most
+//      sensitive thing on this queue. Unread terminal results are purged after
+//      LOGS_CONTENT_TTL_MS (the requester closed the page). The filter JSON in
+//      `content` (it can hold a user-typed grep) goes with it.
 //
 // Every statement is bounded (LIMIT via `request_id IN (SELECT … LIMIT n)` —
 // SQLite's UPDATE/DELETE … LIMIT needs a compile flag we don't control) and
@@ -44,13 +51,15 @@ export const CONTENT_GRACE_MS = 60_000;
 export const CONTENT_TTL_MS = 24 * 60 * 60 * 1000;
 export const ROW_TTL_MS = 30 * 24 * 60 * 60 * 1000;
 export const SWEEP_BATCH = 500;
+export const LOGS_CONTENT_TTL_MS = 5 * 60 * 1000;
 
 export type NodeRequestSweepResult = { timedOut: number; purged: number; deleted: number };
 
 // `content` is only a file body for op=write. For skill_read / file_read it is
 // the skill name / relative path the requester asked for — audit metadata, kept.
+// For logs_tail it is the filter JSON, which may carry a user-typed grep — purged.
 const PURGE_SET =
-  "result_content = NULL, content = CASE WHEN op = 'write' THEN NULL ELSE content END, content_purged_at = ?1";
+  "result_content = NULL, content = CASE WHEN op IN ('write', 'logs_tail') THEN NULL ELSE content END, content_purged_at = ?1";
 
 function purgeWhere(where: string, params: (string | number)[], now: number): number {
   const r = db.run(
@@ -77,6 +86,7 @@ export function sweepNodeRequestContent(now: number = Date.now()): NodeRequestSw
     // ?1 = now (PURGE_SET), ?2… = where params.
     out.purged += purgeWhere("first_read_at IS NOT NULL AND first_read_at <= ?2 AND status IN ('done', 'failed', 'timeout')", [now - CONTENT_GRACE_MS], now);
     out.purged += purgeWhere("created_at < ?2 AND status IN ('done', 'failed', 'timeout')", [ttlCutoff], now);
+    out.purged += purgeWhere("op = 'logs_tail' AND created_at < ?2 AND status IN ('done', 'failed', 'timeout')", [now - LOGS_CONTENT_TTL_MS], now);
   } catch (e: any) {
     console.log(`[commhub retention] node_rules_requests sweep failed: ${e?.message ?? e}`);
   }
@@ -102,3 +112,9 @@ export function noteTerminalResultRead(requestId: string, now: number = Date.now
   );
   return { purged: row?.content_purged_at != null };
 }
+
+/** Run-log results are read-once: called by get_rules_file_result right after it
+ *  handed a terminal logs_tail result to its (authorized) requester. */
+export function purgeLogsResultNow(requestId: string, now: number = Date.now()): void {
+  db.run(`UPDATE node_rules_requests SET ${PURGE_SET} WHERE request_id = ?2 AND op = 'logs_tail' AND content_purged_at IS NULL`, [now, requestId]);
+}

package/src/requirements-http.test.ts

@@ -72,9 +72,17 @@ describe("requirements stay on the hub", () => {
     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 }) });
+    // 负责人只能是人类,负责 Agent 只能是节点(参与人两种都行)。
+    const humanAsAgent = await api(ownerToken, path, { method: 'PATCH', body: JSON.stringify({ agent_owner: user }) });
+    expect(humanAsAgent.status).toBe(400);
+    expect(humanAsAgent.body.error).toBe('agent_owner_must_be_agent');
+    const agentAsOwner = await api(ownerToken, path, { method: 'PATCH', body: JSON.stringify({ owner: node }) });
+    expect(agentAsOwner.status).toBe(400);
+    expect(agentAsOwner.body.error).toBe('owner_must_be_human');
+    const changed = await api(ownerToken, path, { method: 'PATCH', body: JSON.stringify({ agent_owner: node }) });
     expect(changed.status).toBe(200);
-    expect(changed.body.requirement.owner).toEqual(node);
+    expect(changed.body.requirement.owner).toEqual(user);
+    expect(changed.body.requirement.agent_owner).toEqual(node);
     expect(changed.body.requirement.participants).toEqual([user, node]);
     expect(changed.body.requirement.column).toBe('pool');
     for (const token of [viewerToken, nodeToken]) {
@@ -85,13 +93,206 @@ describe("requirements stay on the hub", () => {
       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: [] }) });
+    const row = listed.body.requirements.find((row: any) => row.id === created.body.requirement.id);
+    expect(row.owner).toEqual(user);
+    expect(row.agent_owner).toEqual(node);
+    const cleared = await api(ownerToken, path, { method: 'PATCH', body: JSON.stringify({ owner: null, agent_owner: null, participants: [] }) });
     expect(cleared.status).toBe(200);
     expect(cleared.body.requirement.owner).toBeNull();
+    expect(cleared.body.requirement.agent_owner).toBeNull();
     expect(cleared.body.requirement.participants).toEqual([]);
   });
 
+  test("a card is created with a human owner and an agent owner; each role rejects the other kind", 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 OR IGNORE INTO nodes(node_id,node_name,alias,network_id) VALUES (?1,?2,?2,?3)', ['req-exec-node', 'req-exec-node', ownerNetwork]);
+    const human = { kind: 'user', id: ownerId };
+    const agent = { kind: 'node', id: 'req-exec-node' };
+    const both = await api(ownerToken, '/api/requirements', { method: 'POST', body: JSON.stringify({ name: '两个角色', owner: human, agent_owner: agent }) });
+    expect(both.status).toBe(201);
+    expect(both.body.requirement.owner).toEqual(human);
+    expect(both.body.requirement.agent_owner).toEqual(agent);
+    const plain = await api(ownerToken, '/api/requirements', { method: 'POST', body: JSON.stringify({ name: '都不填' }) });
+    expect(plain.body.requirement.agent_owner).toBeNull();
+    const wrongOwner = await api(ownerToken, '/api/requirements', { method: 'POST', body: JSON.stringify({ name: '节点当负责人', owner: agent }) });
+    expect(wrongOwner.status).toBe(400);
+    expect(wrongOwner.body.error).toBe('owner_must_be_human');
+    const wrongAgent = await api(ownerToken, '/api/requirements', { method: 'POST', body: JSON.stringify({ name: '人当负责 Agent', agent_owner: human }) });
+    expect(wrongAgent.status).toBe(400);
+    expect(wrongAgent.body.error).toBe('agent_owner_must_be_agent');
+    const foreign = await api(ownerToken, '/api/requirements', { method: 'POST', body: JSON.stringify({ name: '外网节点', agent_owner: { kind: 'node', id: 'foreign-person-node' } }) });
+    expect(foreign.status).toBe(400);
+    // 只改 agent_owner 是一次有效 PATCH(不是 empty_patch),其余字段不动
+    const path = `/api/requirements/${both.body.requirement.id}`;
+    const onlyAgent = await api(ownerToken, path, { method: 'PATCH', body: JSON.stringify({ agent_owner: null }) });
+    expect(onlyAgent.status).toBe(200);
+    expect(onlyAgent.body.requirement.agent_owner).toBeNull();
+    expect(onlyAgent.body.requirement.owner).toEqual(human);
+    expect(onlyAgent.body.requirement.name).toBe('两个角色');
+    const viewerWrite = await api(viewerToken, path, { method: 'PATCH', body: JSON.stringify({ agent_owner: agent }) });
+    expect(viewerWrite.status).toBe(403);
+  });
+
+  test("description (markdown) and checklist: create, replace-all PATCH, per-item done, limits", async () => {
+    const created = await api(ownerToken, "/api/requirements", {
+      method: "POST",
+      body: JSON.stringify({ name: "带描述和子任务", description: "## 目标\r\n- 一\n- 二", checklist: [{ id: "a", text: "写接口" }, { text: "写测试", done: true }] }),
+    });
+    expect(created.status).toBe(201);
+    const card = created.body.requirement;
+    expect(card.description).toBe("## 目标\n- 一\n- 二");
+    expect(card.checklist.length).toBe(2);
+    expect(card.checklist[0]).toEqual({ id: "a", text: "写接口", done: false });
+    expect(card.checklist[1].done).toBe(true);
+    expect(card.checklist[1].id).toMatch(/^ck_[0-9a-f]{16}$/);
+    const plain = await api(ownerToken, "/api/requirements", { method: "POST", body: JSON.stringify({ name: "什么都没有" }) });
+    expect(plain.body.requirement.description).toBe("");
+    expect(plain.body.requirement.checklist).toEqual([]);
+
+    const path = `/api/requirements/${card.id}`;
+    const b = card.checklist[1].id;
+    // 单项勾选:只动那一项,显式 done,重复请求结果一样
+    const done = await api(ownerToken, `${path}/checklist/a`, { method: "PATCH", body: JSON.stringify({ done: true }) });
+    expect(done.status).toBe(200);
+    expect(done.body.requirement.checklist.map((i: any) => i.done)).toEqual([true, true]);
+    const again = await api(ownerToken, `${path}/checklist/a`, { method: "PATCH", body: JSON.stringify({ done: true }) });
+    expect(again.body.requirement.checklist.map((i: any) => i.done)).toEqual([true, true]);
+    expect(again.body.requirement.name).toBe("带描述和子任务");
+    expect((await api(ownerToken, `${path}/checklist/${b}`, { method: "PATCH", body: JSON.stringify({ done: false }) })).body.requirement.checklist[1].done).toBe(false);
+    expect((await api(ownerToken, `${path}/checklist/missing`, { method: "PATCH", body: JSON.stringify({ done: true }) })).body.error).toBe("checklist_item_not_found");
+    expect((await api(ownerToken, `${path}/checklist/a`, { method: "PATCH", body: JSON.stringify({ done: "yes" }) })).status).toBe(400);
+    expect((await api(ownerToken, `${path}/checklist/a`, { method: "POST", body: JSON.stringify({ done: true }) })).status).toBe(404);
+    expect((await api(viewerToken, `${path}/checklist/a`, { method: "PATCH", body: JSON.stringify({ done: false }) })).status).toBe(403);
+    expect((await api(nodeToken, `${path}/checklist/a`, { method: "PATCH", body: JSON.stringify({ done: false }) })).body.error).toBe("user_token_required");
+    expect((await api(otherToken, `${path}/checklist/a`, { method: "PATCH", body: JSON.stringify({ done: false }) })).status).toBe(404);
+
+    // 整个替换:排序 / 增删;只改描述时清单不动;只改清单是有效 PATCH
+    const reordered = await api(ownerToken, path, { method: "PATCH", body: JSON.stringify({ checklist: [{ id: b, text: "写测试", done: false }, { id: "a", text: "写接口", done: true }, { id: "c", text: "发版" }] }) });
+    expect(reordered.status).toBe(200);
+    expect(reordered.body.requirement.checklist.map((i: any) => i.id)).toEqual([b, "a", "c"]);
+    const described = await api(ownerToken, path, { method: "PATCH", body: JSON.stringify({ description: "改过的描述" }) });
+    expect(described.body.requirement.description).toBe("改过的描述");
+    expect(described.body.requirement.checklist.length).toBe(3);
+    const cleared = await api(ownerToken, path, { method: "PATCH", body: JSON.stringify({ description: "", checklist: [] }) });
+    expect(cleared.body.requirement.description).toBe("");
+    expect(cleared.body.requirement.checklist).toEqual([]);
+
+    // 上限与坏输入整体拒绝,原值不变
+    const tooLong = await api(ownerToken, path, { method: "PATCH", body: JSON.stringify({ description: "x".repeat(20_001) }) });
+    expect(tooLong.body.error).toBe("invalid_description");
+    expect((await api(ownerToken, path, { method: "PATCH", body: JSON.stringify({ description: "x".repeat(20_000) }) })).status).toBe(200);
+    const many = Array.from({ length: 101 }, (_, i) => ({ id: `i${i}`, text: `第 ${i} 项` }));
+    expect((await api(ownerToken, path, { method: "PATCH", body: JSON.stringify({ checklist: many }) })).body.error).toBe("invalid_checklist");
+    expect((await api(ownerToken, path, { method: "PATCH", body: JSON.stringify({ checklist: many.slice(0, 100) }) })).status).toBe(200);
+    for (const bad of [[{ id: "a", text: "x" }, { id: "a", text: "y" }], [{ text: "  " }], [{ id: "有空格 的id", text: "x" }], [{ text: "x", done: 1 }], ["字符串"]]) {
+      expect((await api(ownerToken, path, { method: "PATCH", body: JSON.stringify({ checklist: bad }) })).body.error).toBe("invalid_checklist");
+    }
+    const listed = await api(ownerToken, "/api/requirements");
+    const row = listed.body.requirements.find((r: any) => r.id === card.id);
+    expect(row.checklist.length).toBe(100);
+    expect(row.description.length).toBe(20_000);
+    expect((await api(viewerToken, path, { method: "PATCH", body: JSON.stringify({ description: "越权" }) })).status).toBe(403);
+    expect((await api(nodeToken, path, { method: "PATCH", body: JSON.stringify({ description: "Agent 暂不能写" }) })).body.error).toBe("user_token_required");
+  });
+
+  test("projects: CRUD per network, project_id on cards, delete nulls references, archive keeps them", async () => {
+    const q = `?network_id=${ownerNetwork}`;
+    const empty = await api(ownerToken, `/api/requirements/projects${q}`);
+    expect(empty.status).toBe(200);
+    expect(empty.body.projects).toEqual([]); // 不预置任何项目
+    const legion = await api(ownerToken, `/api/requirements/projects${q}`, { method: "POST", body: JSON.stringify({ name: "军团项目" }) });
+    expect(legion.status).toBe(201);
+    expect(legion.body.project.name).toBe("军团项目");
+    expect(legion.body.project.color).toMatch(/^#[0-9a-fA-F]{6}$/);
+    expect(legion.body.project.archived).toBe(false);
+    const tmai = await api(ownerToken, `/api/requirements/projects${q}`, { method: "POST", body: JSON.stringify({ name: "TMAI", color: "#7c3aed" }) });
+    expect(tmai.body.project.color).toBe("#7c3aed");
+    expect((await api(ownerToken, `/api/requirements/projects${q}`, { method: "POST", body: JSON.stringify({ name: "TMAI" }) })).status).toBe(409);
+    for (const bad of [{ name: "  " }, { name: "x".repeat(41) }, { name: "色", color: "red" }, { name: "序", sort: 1.5 }]) {
+      expect((await api(ownerToken, `/api/requirements/projects${q}`, { method: "POST", body: JSON.stringify(bad) })).status).toBe(400);
+    }
+    const listed = await api(ownerToken, `/api/requirements/projects${q}`);
+    expect(listed.body.projects.map((p: any) => p.name)).toEqual(["军团项目", "TMAI"]);
+    // 权限:viewer 能读不能写;节点令牌一律拒绝;别的网络看不见、改不了
+    expect((await api(viewerToken, `/api/requirements/projects${q}`)).body.projects.length).toBe(2);
+    expect((await api(viewerToken, `/api/requirements/projects${q}`, { method: "POST", body: JSON.stringify({ name: "越权" }) })).status).toBe(403);
+    expect((await api(nodeToken, `/api/requirements/projects${q}`)).body.error).toBe("user_token_required");
+    expect((await api(otherToken, "/api/requirements/projects")).body.projects).toEqual([]);
+    expect((await api(otherToken, `/api/requirements/projects/${tmai.body.project.id}`, { method: "PATCH", body: JSON.stringify({ name: "抢" }) })).status).toBe(404);
+    const foreign = await api(otherToken, "/api/requirements/projects", { method: "POST", body: JSON.stringify({ name: "别人的项目" }) });
+    expect(foreign.status).toBe(201);
+
+    // 卡片上的 project_id:POST / PATCH / GET;别的网络的项目被拒
+    const card = await api(ownerToken, "/api/requirements", { method: "POST", body: JSON.stringify({ name: "有项目的卡", project_id: legion.body.project.id }) });
+    expect(card.status).toBe(201);
+    expect(card.body.requirement.project_id).toBe(legion.body.project.id);
+    const bare = await api(ownerToken, "/api/requirements", { method: "POST", body: JSON.stringify({ name: "没项目的卡" }) });
+    expect(bare.body.requirement.project_id).toBeNull();
+    expect((await api(ownerToken, "/api/requirements", { method: "POST", body: JSON.stringify({ name: "外网项目", project_id: foreign.body.project.id }) })).body.error).toBe("project_not_in_network");
+    const path = `/api/requirements/${card.body.requirement.id}`;
+    expect((await api(ownerToken, path, { method: "PATCH", body: JSON.stringify({ project_id: foreign.body.project.id }) })).body.error).toBe("project_not_in_network");
+    const moved = await api(ownerToken, path, { method: "PATCH", body: JSON.stringify({ project_id: tmai.body.project.id }) });
+    expect(moved.status).toBe(200);
+    expect(moved.body.requirement.project_id).toBe(tmai.body.project.id);
+    expect(moved.body.requirement.name).toBe("有项目的卡");
+
+    // 改名 / 改色 / 排序
+    const renamed = await api(ownerToken, `/api/requirements/projects/${tmai.body.project.id}${q}`, { method: "PATCH", body: JSON.stringify({ name: "TMAI 平台", color: "#0891b2", sort: -1 }) });
+    expect(renamed.body.project).toMatchObject({ name: "TMAI 平台", color: "#0891b2", sort: -1 });
+    expect((await api(ownerToken, `/api/requirements/projects/${tmai.body.project.id}${q}`, { method: "PATCH", body: JSON.stringify({ name: "军团项目" }) })).status).toBe(409);
+    expect((await api(ownerToken, `/api/requirements/projects${q}`)).body.projects[0].name).toBe("TMAI 平台");
+
+    // 归档:引用保留,但不能再被选
+    const archived = await api(ownerToken, `/api/requirements/projects/${tmai.body.project.id}${q}`, { method: "PATCH", body: JSON.stringify({ archived: true }) });
+    expect(archived.body.project.archived).toBe(true);
+    const kept = (await api(ownerToken, "/api/requirements")).body.requirements.find((r: any) => r.id === card.body.requirement.id);
+    expect(kept.project_id).toBe(tmai.body.project.id);
+    expect((await api(ownerToken, `/api/requirements/${bare.body.requirement.id}`, { method: "PATCH", body: JSON.stringify({ project_id: tmai.body.project.id }) })).body.error).toBe("project_archived");
+
+    // 删除:卡片一张不少,引用置空
+    await api(ownerToken, `/api/requirements/${bare.body.requirement.id}`, { method: "PATCH", body: JSON.stringify({ project_id: legion.body.project.id }) });
+    const before = (await api(ownerToken, "/api/requirements")).body.requirements.length;
+    expect((await api(viewerToken, `/api/requirements/projects/${legion.body.project.id}${q}`, { method: "DELETE" })).status).toBe(403);
+    const del = await api(ownerToken, `/api/requirements/projects/${legion.body.project.id}${q}`, { method: "DELETE" });
+    expect(del.status).toBe(200);
+    const after = (await api(ownerToken, "/api/requirements")).body.requirements;
+    expect(after.length).toBe(before);
+    expect(after.find((r: any) => r.id === bare.body.requirement.id).project_id).toBeNull();
+    expect((await api(ownerToken, `/api/requirements/projects${q}`)).body.projects.map((p: any) => p.name)).toEqual(["TMAI 平台"]);
+    // 清空卡片项目
+    expect((await api(ownerToken, path, { method: "PATCH", body: JSON.stringify({ project_id: null }) })).body.requirement.project_id).toBeNull();
+  });
+
+  test("due accepts date-only (all day) and an ISO datetime with offset, stored as UTC to the second", async () => {
+    const make = (due: unknown) => api(ownerToken, "/api/requirements", { method: "POST", body: JSON.stringify({ name: "期限", due }) });
+    const shanghai = await make("2026-10-01T18:30:45+08:00");
+    expect(shanghai.status).toBe(201);
+    expect(shanghai.body.requirement.due).toBe("2026-10-01T10:30:45Z");
+    expect((await make("2026-10-01T10:30:45Z")).body.requirement.due).toBe("2026-10-01T10:30:45Z");
+    expect((await make("2026-10-01T10:30Z")).body.requirement.due).toBe("2026-10-01T10:30:00Z");
+    expect((await make("2026-10-01T10:30:45.987-04:00")).body.requirement.due).toBe("2026-10-01T14:30:45Z");
+    // 跨日:东八区的 00:30 是 UTC 前一天
+    expect((await make("2026-10-01T00:30:00+08:00")).body.requirement.due).toBe("2026-09-30T16:30:00Z");
+    // 旧的全天值原样
+    const legacy = await make("2026-10-01");
+    expect(legacy.body.requirement.due).toBe("2026-10-01");
+    for (const bad of ["2026-10-01T18:30:45", "2026-10-01 18:30:45+08:00", "2026-02-30T10:00:00Z", "2026-10-01T24:00:00Z", "2026-10-01T10:60:00Z", "2026-10-01T10:00:61Z", "2026-10-01T10:00:00+15:00", "明天", "2026-10-1"]) {
+      const r = await make(bad);
+      expect(r.status).toBe(400);
+      expect(r.body.error).toBe("invalid_due");
+    }
+    const path = `/api/requirements/${legacy.body.requirement.id}`;
+    const patched = await api(ownerToken, path, { method: "PATCH", body: JSON.stringify({ due: "2026-12-31T23:59:59-08:00" }) });
+    expect(patched.body.requirement.due).toBe("2027-01-01T07:59:59Z");
+    expect((await api(ownerToken, path, { method: "PATCH", body: JSON.stringify({ due: "2026-12-31" }) })).body.requirement.due).toBe("2026-12-31");
+    expect((await api(ownerToken, path, { method: "PATCH", body: JSON.stringify({ due: "T" }) })).status).toBe(400);
+    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"]);
+  });
+
   test("owner creates a card in the pool", async () => {
     const created = await api(ownerToken, "/api/requirements", {
       method: "POST",
@@ -187,6 +388,51 @@ describe("requirements stay on the hub", () => {
     expect(bad.status).toBe(400);
   });
 
+  test("an existing card can change its text without dropping omitted fields", 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;
+    const created = await api(ownerToken, "/api/requirements", {
+      method: "POST",
+      body: JSON.stringify({
+        name: "旧标题",
+        priority: "low",
+        assignee: "node-a",
+        due: "2026-10-01",
+        column: "doing",
+        owner: { kind: "user", id: ownerId },
+      }),
+    });
+    expect(created.status).toBe(201);
+    const id = created.body.requirement.id;
+    const renamed = await api(ownerToken, `/api/requirements/${id}`, {
+      method: "PATCH",
+      body: JSON.stringify({ name: "新标题" }),
+    });
+    expect(renamed.status).toBe(200);
+    expect(renamed.body.requirement.name).toBe("新标题");
+    expect(renamed.body.requirement.priority).toBe("low");
+    expect(renamed.body.requirement.assignee).toBe("node-a");
+    expect(renamed.body.requirement.due).toBe("2026-10-01");
+    expect(renamed.body.requirement.column).toBe("doing");
+    expect(renamed.body.requirement.owner).toEqual({ kind: "user", id: ownerId });
+    const cleared = await api(ownerToken, `/api/requirements/${id}`, {
+      method: "PATCH",
+      body: JSON.stringify({ due: "", assignee: "", priority: "high" }),
+    });
+    expect(cleared.status).toBe(200);
+    expect(cleared.body.requirement.name).toBe("新标题");
+    expect(cleared.body.requirement.due).toBe("");
+    expect(cleared.body.requirement.assignee).toBe("");
+    expect(cleared.body.requirement.priority).toBe("high");
+    expect(cleared.body.requirement.owner).toEqual({ kind: "user", id: ownerId });
+    expect((await api(ownerToken, `/api/requirements/${id}`, { method: "PATCH", body: JSON.stringify({ name: "  " }) })).status).toBe(400);
+    expect((await api(ownerToken, `/api/requirements/${id}`, { method: "PATCH", body: JSON.stringify({ due: "2026-13-01" }) })).status).toBe(400);
+    expect((await api(viewerToken, `/api/requirements/${id}`, { method: "PATCH", body: JSON.stringify({ name: "越权" }) })).status).toBe(403);
+    expect((await api(otherToken, `/api/requirements/${id}`, { method: "PATCH", body: JSON.stringify({ name: "别人的" }) })).status).toBe(404);
+    const listed = await api(ownerToken, "/api/requirements");
+    expect(listed.body.requirements.find((row: { id: string }) => row.id === id).name).toBe("新标题");
+  });
+
   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);