@sleep2agi/commhub-server 0.9.0-preview.13 → 0.9.0-preview.131

package/src/requirements-status-participants-http.test.ts

@@ -0,0 +1,222 @@
+// #475(MCP 任务生命周期测试报告问题 6)—— Agent 写任务时两处常见的坑:
+//   - status 当 column 用(列表的筛选参数就叫 status):MCP 的 create / update / upsert 把 status 当 column 的别名,
+//     两个都给且不同 → 400 status_conflicts_with_column;REST 不变(仍是 empty_patch + 提示用 column)。
+//   - participants 是整体替换,Agent 想「加一个人」时把别人全删了:新增 participants_add / participants_remove,
+//     在当前列表上加减、同一次同步读改写里完成;加已有 = 不变,减不在的 = 不变。
+// 外加 #476 第 1 部分:项目工具的描述写明节点令牌只能读项目(行为本来就是 403 user_token_required)。
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { register, createNetworkTokenForNode } from "./auth.js";
+import { db } from "./db.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-req-status-part-"));
+let BASE = "";
+let hub: any = null;
+const PW = "ReqStatusPartPassw0rd!xyz";
+let NET = "";
+const U: Record<string, { token: string; id: string }> = {};
+
+async function rest(token: string, method: string, path: string, body?: unknown) {
+  const res = await fetch(`${BASE}${path}`, { method, headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" }, body: body === undefined ? undefined : JSON.stringify(body) });
+  const text = await res.text();
+  let json: any = null;
+  try { json = JSON.parse(text); } catch {}
+  return { status: res.status, body: json };
+}
+async function rpc(token: string, method: string, params: Record<string, unknown>) {
+  const res = await fetch(`${BASE}/mcp`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-03-26" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+  });
+  const raw = await res.text();
+  const lines = raw.split("\n").filter(x => x.startsWith("data:"));
+  return lines.length ? JSON.parse(lines.at(-1)!.slice(5).trim()) : JSON.parse(raw);
+}
+async function mcp(token: string, name: string, args: Record<string, unknown>): Promise<any> {
+  const out = await rpc(token, "tools/call", { name, arguments: args });
+  const text = out.result?.content?.[0]?.text ?? "";
+  try { return JSON.parse(text); } catch { return { raw: out, text }; }
+}
+const keys = (refs: { kind: string; id: string }[]) => refs.map(r => `${r.kind}:${r.id}`).sort();
+const row = (id: string) => db.get<{ column_name: string; participants_json: string; updated_at: string }>("SELECT column_name, participants_json, updated_at FROM requirements WHERE requirement_id = ?1", id)!;
+const participantEvents = (id: string) => db.get<{ n: number }>("SELECT COUNT(*) AS n FROM requirement_events WHERE requirement_id = ?1 AND field = 'participants'", id)!.n;
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+  process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+  process.env.HOST = "127.0.0.1";
+  const a = register(`sp_owner_${Date.now()}`, PW, undefined, "Owner");
+  U.owner = { token: a.token!, id: a.user!.user_id };
+  NET = a.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [U.owner.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 username = `sp_member_${Date.now()}`;
+  expect((await rest(U.owner.token, "POST", "/api/admin/users", { username, password: PW, network_id: NET, role: "member" })).status).toBe(200);
+  const login = await rest("", "POST", "/api/auth/login", { username, password: PW });
+  U.member = { token: login.body.token, id: login.body.user.user_id };
+  // #746 起新成员默认 scoped;这里测的是 'all' 成员的 REST 键,显式放宽。
+  expect((await rest(U.owner.token, "PUT", `/api/networks/${NET}/members/${U.member.id}/task-grants`, { task_access: "all" })).status).toBe(200);
+  for (const [k, alias] of [["nodeA", "示例-甲"], ["nodeB", "示例-乙"], ["nodeC", "示例-丙"]] as const) {
+    const nodeId = `node_sp_${k}`;
+    U[k] = { token: createNetworkTokenForNode(U.owner.id, NET, alias, nodeId).token!, id: nodeId };
+  }
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("status is an alias of column (MCP)", () => {
+  test("create / update / upsert with status land exactly where column would", async () => {
+    const viaStatus = (await mcp(U.nodeA.token, "requirements_create", { name: "示例:status 建", status: "doing" })).requirement;
+    const viaColumn = (await mcp(U.nodeA.token, "requirements_create", { name: "示例:column 建", column: "doing" })).requirement;
+    expect(viaStatus.column).toBe("doing");
+    expect(viaStatus.column).toBe(viaColumn.column);
+
+    const done = await mcp(U.nodeA.token, "requirements_update", { id: `#${viaStatus.seq}`, status: "done" });
+    expect(done.requirement.column).toBe("done");
+    expect(done.requirement.completedAt).toBeTruthy(); // same side effects as column=done
+    expect(row(viaStatus.id).column_name).toBe("done");
+
+    const same = await mcp(U.nodeA.token, "requirements_update", { id: viaColumn.id, status: "pool", column: "pool" });
+    expect(same.requirement.column).toBe("pool");
+
+    const up = await mcp(U.nodeA.token, "requirements_upsert_by_external_ref", { external_ref: "demo:status-alias-1", name: "示例:upsert", status: "doing" });
+    expect(up.created).toBe(true);
+    expect(up.requirement.column).toBe("doing");
+  });
+
+  test("status and column both sent and different → 400 status_conflicts_with_column with a hint; nothing written", async () => {
+    const card = (await mcp(U.nodeA.token, "requirements_create", { name: "示例:冲突", column: "pool" })).requirement;
+    const before = row(card.id);
+    const r = await mcp(U.nodeA.token, "requirements_update", { id: card.id, status: "doing", column: "done" });
+    expect(r.ok).toBe(false);
+    expect(r.status).toBe(400);
+    expect(r.error).toBe("status_conflicts_with_column");
+    expect(r.field).toBe("status");
+    expect(r.hint).toContain("only one");
+    expect(row(card.id)).toEqual(before);
+    const c = await mcp(U.nodeA.token, "requirements_create", { name: "示例:冲突建", status: "doing", column: "done" });
+    expect(c.error).toBe("status_conflicts_with_column");
+  });
+
+  test("a bad status value is a schema error (-32602), like a bad column", async () => {
+    const out = await rpc(U.nodeA.token, "tools/call", { name: "requirements_update", arguments: { id: "#1", status: "finished" } });
+    expect(String(out.error?.code ?? out.result?.content?.[0]?.text)).toMatch(/-32602|invalid/i);
+  });
+
+  test("REST is unchanged: status on PATCH is still not a writable field", async () => {
+    const card = (await mcp(U.nodeA.token, "requirements_create", { name: "示例:REST", column: "pool" })).requirement;
+    const r = await rest(U.member.token, "PATCH", `/api/requirements/${card.id}`, { status: "doing" });
+    expect(r.status).toBe(400);
+    expect(r.body.error).toBe("empty_patch");
+    expect(row(card.id).column_name).toBe("pool");
+  });
+});
+
+describe("participants_add / participants_remove", () => {
+  let card = { id: "", seq: 0 };
+  const node = (k: string) => ({ kind: "node", id: U[k].id });
+  const user = (k: string) => ({ kind: "user", id: U[k].id });
+
+  test("add keeps the people already there", async () => {
+    card = (await mcp(U.nodeA.token, "requirements_create", { name: "示例:参与人", participants: [user("member"), node("nodeA")] })).requirement;
+    const r = await mcp(U.nodeA.token, "requirements_update", { id: `#${card.seq}`, participants_add: [node("nodeB")] });
+    expect(keys(r.requirement.participants)).toEqual(keys([user("member"), node("nodeA"), node("nodeB")]));
+    expect(keys(JSON.parse(row(card.id).participants_json))).toEqual(keys([user("member"), node("nodeA"), node("nodeB")]));
+  });
+
+  test("add is idempotent: someone already there → same list, no participants event", async () => {
+    const events = participantEvents(card.id);
+    const r = await mcp(U.nodeA.token, "requirements_update", { id: card.id, participants_add: [node("nodeB"), node("nodeA")] });
+    expect(keys(r.requirement.participants)).toEqual(keys([user("member"), node("nodeA"), node("nodeB")]));
+    expect(participantEvents(card.id)).toBe(events);
+  });
+
+  test("remove drops only those people; removing someone absent (or no longer in the network) is a no-op", async () => {
+    const r = await mcp(U.nodeA.token, "requirements_update", { id: card.id, participants_remove: [user("member"), { kind: "user", id: "u_left_the_network" }] });
+    expect(r.ok).toBe(true);
+    expect(keys(r.requirement.participants)).toEqual(keys([node("nodeA"), node("nodeB")]));
+  });
+
+  test("add and remove in one call are applied together", async () => {
+    const r = await mcp(U.nodeA.token, "requirements_update", { id: card.id, participants_add: [node("nodeC"), user("member")], participants_remove: [node("nodeA")] });
+    expect(keys(r.requirement.participants)).toEqual(keys([node("nodeB"), node("nodeC"), user("member")]));
+  });
+
+  test("concurrent adds from two Agents both stick (no lost update)", async () => {
+    const fresh = (await mcp(U.owner.token, "requirements_create", { name: "示例:并发", participants: [user("owner")], network_id: NET })).requirement;
+    await Promise.all([
+      mcp(U.nodeA.token, "requirements_update", { id: fresh.id, participants_add: [node("nodeA")] }),
+      mcp(U.nodeB.token, "requirements_update", { id: fresh.id, participants_add: [node("nodeB")] }),
+      mcp(U.nodeC.token, "requirements_update", { id: fresh.id, participants_add: [node("nodeC")] }),
+    ]);
+    expect(keys(JSON.parse(row(fresh.id).participants_json))).toEqual(keys([user("owner"), node("nodeA"), node("nodeB"), node("nodeC")]));
+  });
+
+  test("name forms (#473): add by alias / username, remove by username", async () => {
+    const fresh = (await mcp(U.nodeA.token, "requirements_create", { name: "示例:按名字", participants: [node("nodeA")] })).requirement;
+    const memberName = db.get<{ username: string }>("SELECT username FROM users WHERE user_id = ?1", U.member.id)!.username;
+    const added = await mcp(U.nodeA.token, "requirements_update", { id: fresh.id, participants_add: [{ kind: "node", alias: "示例-乙" }, { kind: "user", username: memberName }] });
+    expect(keys(added.requirement.participants)).toEqual(keys([node("nodeA"), node("nodeB"), user("member")]));
+    const removed = await mcp(U.nodeA.token, "requirements_update", { id: fresh.id, participants_remove: [{ kind: "user", username: memberName }] });
+    expect(keys(removed.requirement.participants)).toEqual(keys([node("nodeA"), node("nodeB")]));
+  });
+
+  test("participants is still a full replace", async () => {
+    const r = await mcp(U.nodeA.token, "requirements_update", { id: card.id, participants: [node("nodeA")] });
+    expect(keys(r.requirement.participants)).toEqual(keys([node("nodeA")]));
+  });
+
+  test("bad combinations → 400 with hints, nothing written", async () => {
+    const before = row(card.id);
+    const both = await mcp(U.nodeA.token, "requirements_update", { id: card.id, participants: [], participants_add: [node("nodeB")] });
+    expect(both.status).toBe(400);
+    expect(both.error).toBe("participants_conflict");
+    expect(both.hint).toContain("participants_add");
+    const overlap = await mcp(U.nodeA.token, "requirements_update", { id: card.id, participants_add: [node("nodeB")], participants_remove: [node("nodeB")] });
+    expect(overlap.error).toBe("participants_add_remove_overlap");
+    const stranger = await mcp(U.nodeA.token, "requirements_update", { id: card.id, participants_add: [{ kind: "node", id: "node_not_here" }] });
+    expect(stranger.error).toBe("person_not_in_network");
+    expect(stranger.field).toBe("participants_add");
+    expect(row(card.id)).toEqual(before);
+  });
+
+  test("REST accepts the same keys (additive; old clients never send them)", async () => {
+    const r = await rest(U.member.token, "PATCH", `/api/requirements/${card.id}`, { participants_add: [user("member")] });
+    expect(r.status).toBe(200);
+    // the member has no grant on nodeA, so the response leaves it out — but the stored list keeps it
+    expect(keys(JSON.parse(row(card.id).participants_json))).toEqual(keys([node("nodeA"), user("member")]));
+    expect(keys(r.body.requirement.participants)).toEqual(keys([user("member")]));
+    // …and the member cannot remove an Agent they cannot see (same error as a node that does not exist)
+    const hidden = await rest(U.member.token, "PATCH", `/api/requirements/${card.id}`, { participants_remove: [node("nodeA")] });
+    expect(hidden.status).toBe(400);
+    expect(hidden.body.error).toBe("person_not_in_network");
+    expect(keys(JSON.parse(row(card.id).participants_json))).toEqual(keys([node("nodeA"), user("member")]));
+  });
+});
+
+describe("tool descriptions", () => {
+  test("participants says it replaces; projects tools say node tokens only read; node token project write → 403", async () => {
+    const tools = (await rpc(U.nodeA.token, "tools/list", {})).result.tools as any[];
+    const byName = new Map(tools.map(t => [t.name, t]));
+    const update = byName.get("requirements_update");
+    expect(update.description).toContain("REPLACES the whole list");
+    expect(update.inputSchema.properties.participants.description).toContain("REPLACES");
+    expect(Object.keys(update.inputSchema.properties)).toEqual(expect.arrayContaining(["status", "participants_add", "participants_remove"]));
+    // #478:节点令牌的 tools/list 里本来就没有 projects_create / projects_update(调了也是 403),那两条的说明从人的列表里读。
+    expect(byName.has("projects_create")).toBe(false);
+    const human = new Map(((await rpc(U.member.token, "tools/list", {})).result.tools as any[]).map(t => [t.name, t]));
+    expect(byName.get("projects_list").description).toMatch(/node \(Agent\) tokens can only read projects/i);
+    for (const name of ["projects_create", "projects_update"]) expect(human.get(name).description).toMatch(/node \(Agent\) tokens can only read projects/i);
+    const denied = await mcp(U.nodeA.token, "projects_create", { name: "示例项目" });
+    expect(denied.status).toBe(403);
+    expect(denied.error).toBe("user_token_required");
+  });
+});

package/src/requirements-upgrade-e2e.test.ts

@@ -0,0 +1,126 @@
+// 负责人 / 负责 Agent 拆分:一次性 Hub 进程的升级端到端。
+// 真起两次 `bun run src/index.ts`(HOME=临时目录、随机端口、绝不是 9200、独立库):
+//   第一次:注册、建节点、建一张「旧式」卡(owner 是节点 —— 用 SQL 写进去,因为新 Hub 已不接受);
+//          再把 agent_owner_json 列删掉,库回到 #2065 时代的样子。
+//   第二次:同一个库启动 = 升级。启动迁移把节点挪到 agent_owner,HTTP 读回;然后走一遍新规则。
+import { afterAll, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { spawn, type ChildProcess } from "node:child_process";
+
+const home = mkdtempSync(join(tmpdir(), "anet-req-agent-owner-e2e-"));
+const dbFile = join(home, "hub.db");
+const port = 20000 + Math.floor(Math.random() * 20000);
+if (port === 9200) throw new Error("9200 is the production hub port");
+const base = `http://127.0.0.1:${port}`;
+const serverDir = resolve(import.meta.dir, "..");
+let proc: ChildProcess | null = null;
+
+async function startHub() {
+  proc = spawn("bun", ["run", "src/index.ts"], {
+    cwd: serverDir,
+    env: { PATH: process.env.PATH || "", HOME: home, COMMHUB_DB: dbFile, COMMHUB_SERVER: "1", PORT: String(port), HOST: "127.0.0.1" },
+    stdio: ["ignore", "ignore", "pipe"],
+  });
+  let err = "";
+  proc.stderr?.on("data", d => { err += String(d); });
+  for (let i = 0; i < 100; i++) {
+    try { if ((await fetch(`${base}/health`)).ok) return; } catch {}
+    await new Promise(r => setTimeout(r, 150));
+  }
+  throw new Error(`hub did not start on ${port}: ${err.slice(-600)}`);
+}
+async function stopHub() {
+  if (!proc) return;
+  const p = proc;
+  proc = null;
+  await new Promise<void>(res => { p.once("exit", () => res()); p.kill("SIGTERM"); setTimeout(() => { p.kill("SIGKILL"); res(); }, 5000); });
+}
+afterAll(async () => { await stopHub(); try { rmSync(home, { recursive: true, force: true }); } catch {} });
+
+async function api(token: string, path: string, init?: RequestInit) {
+  const res = await fetch(`${base}${path}`, { ...init, headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" } });
+  return { status: res.status, body: await res.json() as any };
+}
+
+test("an upgraded hub moves node owners to agent_owner and then enforces human owner / agent executor", async () => {
+  await startHub();
+  const reg = await (await fetch(`${base}/api/auth/register`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ username: "e2e_owner", password: "E2eOwner123!pass" }) })).json() as any;
+  expect(reg.ok).toBe(true);
+  const token = reg.token as string, net = reg.network_id as string, uid = reg.user.user_id as string;
+  const human = { kind: "user", id: uid }, agent = { kind: "node", id: "node_e2e_exec" };
+  {
+    const db = new Database(dbFile);
+    db.run("INSERT INTO nodes (node_id,node_name,alias,network_id) VALUES (?1,'e2e-exec','e2e-exec',?2)", [agent.id, net]);
+    db.close();
+  }
+  const card = await api(token, "/api/requirements", { method: "POST", body: JSON.stringify({ name: "旧式卡", network_id: net, participants: [human] }) });
+  expect(card.status).toBe(201);
+  const keep = await api(token, "/api/requirements", { method: "POST", body: JSON.stringify({ name: "人类负责人卡", network_id: net, owner: human }) });
+  expect(keep.status).toBe(201);
+  await stopHub();
+  {
+    // 退回旧库:节点当负责人,且没有 agent_owner_json 列
+    const db = new Database(dbFile);
+    db.run("UPDATE requirements SET owner_json = ?1 WHERE requirement_id = ?2", [JSON.stringify(agent), card.body.requirement.id]);
+    db.exec("ALTER TABLE requirements DROP COLUMN agent_owner_json");
+    const cols = (db.query("PRAGMA table_info(requirements)").all() as { name: string }[]).map(c => c.name);
+    expect(cols.includes("agent_owner_json")).toBe(false);
+    db.close();
+  }
+  await startHub();
+  const listed = await api(token, `/api/requirements?network_id=${net}`);
+  expect(listed.status).toBe(200);
+  expect(listed.body.requirements.length).toBe(2);
+  const upgraded = listed.body.requirements.find((r: any) => r.id === card.body.requirement.id);
+  expect(upgraded.owner).toBeNull();
+  expect(upgraded.agent_owner).toEqual(agent);
+  expect(upgraded.participants).toEqual([human]);
+  expect(upgraded.name).toBe("旧式卡");
+  const untouched = listed.body.requirements.find((r: any) => r.id === keep.body.requirement.id);
+  expect(untouched.owner).toEqual(human);
+  expect(untouched.agent_owner).toBeNull();
+
+  const path = `/api/requirements/${upgraded.id}?network_id=${net}`;
+  const both = await api(token, path, { method: "PATCH", body: JSON.stringify({ owner: human }) });
+  expect(both.status).toBe(200);
+  expect(both.body.requirement.owner).toEqual(human);
+  expect(both.body.requirement.agent_owner).toEqual(agent);
+  expect((await api(token, path, { method: "PATCH", body: JSON.stringify({ owner: agent, agent_owner: agent }) })).body.error).toBe("owner_must_be_human");
+  expect((await api(token, path, { method: "PATCH", body: JSON.stringify({ agent_owner: human }) })).body.error).toBe("agent_owner_must_be_agent");
+
+  // 预计完成:旧卡的全天值(升级前写的)原样读回;改成带时刻的,存 UTC
+  const dated = await api(token, path, { method: "PATCH", body: JSON.stringify({ due: "2026-10-01" }) });
+  expect(dated.body.requirement.due).toBe("2026-10-01");
+  // 描述 / 子任务:升级后的旧卡可写,单项勾选只动那一项
+  expect(upgraded.description).toBe("");
+  expect(upgraded.checklist).toEqual([]);
+  const withList = await api(token, path, { method: "PATCH", body: JSON.stringify({ description: "# 验收\n- 能用", checklist: [{ id: "one", text: "第一步" }, { id: "two", text: "第二步" }] }) });
+  expect(withList.status).toBe(200);
+  const ticked = await api(token, `/api/requirements/${upgraded.id}/checklist/two?network_id=${net}`, { method: "PATCH", body: JSON.stringify({ done: true }) });
+  expect(ticked.body.requirement.checklist).toEqual([{ id: "one", text: "第一步", done: false }, { id: "two", text: "第二步", done: true }]);
+
+  // 项目:升级后没有任何项目(不预置),建一个、给旧卡挂上
+  expect((await api(token, `/api/requirements/projects?network_id=${net}`)).body.projects).toEqual([]);
+  const proj = await api(token, `/api/requirements/projects?network_id=${net}`, { method: "POST", body: JSON.stringify({ name: "军团项目" }) });
+  expect(proj.status).toBe(201);
+  expect((await api(token, path, { method: "PATCH", body: JSON.stringify({ project_id: proj.body.project.id }) })).body.requirement.project_id).toBe(proj.body.project.id);
+
+  // 第三次启动(同一个库):迁移不再改任何东西
+  await stopHub();
+  await startHub();
+  const again = (await api(token, `/api/requirements?network_id=${net}`)).body.requirements;
+  expect(again.length).toBe(2);
+  const same = again.find((r: any) => r.id === upgraded.id);
+  expect(same.owner).toEqual(human);
+  expect(same.agent_owner).toEqual(agent);
+  expect(same.description).toBe("# 验收\n- 能用");
+  expect(same.checklist.map((i: any) => i.done)).toEqual([false, true]);
+  expect(same.project_id).toBe(proj.body.project.id);
+  expect(same.due).toBe("2026-10-01");
+  const timed = await api(token, `/api/requirements/${upgraded.id}?network_id=${net}`, { method: "PATCH", body: JSON.stringify({ due: "2026-10-01T18:30:45+08:00" }) });
+  expect(timed.body.requirement.due).toBe("2026-10-01T10:30:45Z");
+  expect((await api(token, `/api/requirements/projects?network_id=${net}`)).body.projects.map((p: any) => p.name)).toEqual(["军团项目"]);
+}, 60_000);

package/src/requirements-upgrade-migration.test.ts

@@ -0,0 +1,98 @@
+// 负责人 / 负责 Agent 拆分的启动迁移:旧库里 owner 是节点的卡,节点挪到 agent_owner、owner 置空。
+// 用 #2065 时代的表结构(没有 agent_owner_json 列)先建库、塞行,再 import db.ts + requirements.ts(真实启动路径)。
+import { afterAll, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const dir = mkdtempSync(join(tmpdir(), "anet-req-agent-owner-"));
+const file = join(dir, "hub.db");
+process.env.COMMHUB_DB = file;
+
+const legacy = new Database(file);
+legacy.exec(`CREATE TABLE requirements (
+  requirement_id TEXT PRIMARY KEY, network_id TEXT NOT NULL, title TEXT NOT NULL,
+  column_name TEXT NOT NULL DEFAULT 'pool', priority TEXT NOT NULL DEFAULT 'normal', 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')),
+  owner_json TEXT, participants_json TEXT NOT NULL DEFAULT '[]')`);
+const rows: [string, string | null, string][] = [
+  ["r_node_owner", JSON.stringify({ kind: "node", id: "node_x" }), JSON.stringify([{ kind: "user", id: "u1" }])],
+  ["r_user_owner", JSON.stringify({ kind: "user", id: "u1" }), "[]"],
+  ["r_no_owner", null, "[]"],
+  ["r_bad_json", "{not json", "[]"],
+  ["r_node_no_id", JSON.stringify({ kind: "node" }), "[]"],
+  ["r_node_owner_2", JSON.stringify({ kind: "node", id: "node_y" }), "[]"],
+];
+for (const [id, owner, participants] of rows) {
+  legacy.run("INSERT INTO requirements (requirement_id, network_id, title, due_on, assignee, owner_json, participants_json) VALUES (?1, 'net', ?2, '2026-10-01', 'legacy', ?3, ?4)", [id, `卡 ${id}`, owner, participants]);
+}
+// 升级前就在「完成」列的一张(旧库 updated_at 是 datetime('now') 的「YYYY-MM-DD HH:MM:SS」UTC 形状)。
+legacy.run("UPDATE requirements SET column_name = 'done', updated_at = '2026-09-01 10:00:00' WHERE requirement_id = 'r_user_owner'");
+legacy.close();
+
+afterAll(() => { try { rmSync(dir, { recursive: true, force: true }); } catch {} });
+
+const snapshot = (db: any) => db.all("SELECT requirement_id, network_id, title, due_on, assignee, participants_json, owner_json, agent_owner_json, project_id FROM requirements ORDER BY requirement_id") as any[];
+
+test("startup migration moves node owners to agent_owner, keeps every row, and is idempotent", async () => {
+  const { db } = await import("./db.js");
+  await import("./requirements.js"); // 真实启动路径:server.ts 载入 requirements.ts 时迁移
+  const { migrateRequirementAgentOwners } = await import("./requirements-migrate.js");
+  const after = snapshot(db);
+  expect(after.length).toBe(rows.length);
+  const by = Object.fromEntries(after.map(r => [r.requirement_id, r]));
+  expect(by.r_node_owner.owner_json).toBeNull();
+  expect(JSON.parse(by.r_node_owner.agent_owner_json)).toEqual({ kind: "node", id: "node_x" });
+  expect(by.r_node_owner.participants_json).toBe(JSON.stringify([{ kind: "user", id: "u1" }]));
+  expect(JSON.parse(by.r_node_owner_2.agent_owner_json)).toEqual({ kind: "node", id: "node_y" });
+  expect(JSON.parse(by.r_user_owner.owner_json)).toEqual({ kind: "user", id: "u1" });
+  expect(by.r_user_owner.agent_owner_json).toBeNull();
+  expect(by.r_no_owner.owner_json).toBeNull();
+  // 读不懂的旧值原样留着,不猜、不删
+  expect(by.r_bad_json.owner_json).toBe("{not json");
+  expect(by.r_node_no_id.owner_json).toBe(JSON.stringify({ kind: "node" }));
+  for (const r of after) {
+    expect(r.title).toBe(`卡 ${r.requirement_id}`);
+    expect(r.network_id).toBe("net");
+    expect(r.due_on).toBe("2026-10-01");
+    expect(r.assignee).toBe("legacy");
+  }
+  // 加列只加不改:旧行的描述 / 子任务是空
+  const cols = (db.all("PRAGMA table_info(requirements)") as { name: string }[]).map(c => c.name);
+  expect(cols.includes("description") && cols.includes("checklist_json") && cols.includes("agent_owner_json")).toBe(true);
+  const extra = db.all("SELECT description, checklist_json FROM requirements") as any[];
+  expect(extra.every(r => r.description === null && r.checklist_json === null)).toBe(true);
+  // 项目表:建了、是空的(不预置),重复执行不报错;卡片的 project_id 列只加不改
+  expect(cols.includes("project_id")).toBe(true);
+  // PR B:外部引用 / 归档 / 谁做的 —— 只加不改;旧行 archived = 0、其余 NULL;external_ref 的部分唯一索引建了
+  for (const c of ["external_ref", "external_url", "archived", "created_by_json", "updated_by_json", "parent_id"]) expect(cols.includes(c)).toBe(true);
+  expect((db.all("SELECT parent_id FROM requirements WHERE parent_id IS NOT NULL") as any[]).length).toBe(0);
+  expect((db.all("PRAGMA index_list(requirements)") as { name: string }[]).some(i => i.name === "idx_requirements_parent")).toBe(true);
+  expect((db.all("SELECT archived, external_ref FROM requirements") as any[]).every(r => r.archived === 0 && r.external_ref === null)).toBe(true);
+  const idx = (db.all("PRAGMA index_list(requirements)") as { name: string; unique: number }[]).find(i => i.name === "idx_requirements_external_ref");
+  expect(idx?.unique).toBe(1);
+  const { ensureRequirementIndexes } = await import("./requirements-migrate.js");
+  ensureRequirementIndexes(db);
+  expect((db.all("SELECT project_id FROM requirements WHERE project_id IS NOT NULL") as any[]).length).toBe(0);
+  expect((db.get("SELECT COUNT(*) AS n FROM requirement_projects") as any).n).toBe(0);
+  const { ensureRequirementProjects } = await import("./requirements-migrate.js");
+  ensureRequirementProjects(db);
+  ensureRequirementProjects(db);
+  expect((db.get("SELECT COUNT(*) AS n FROM requirement_projects") as any).n).toBe(0);
+  // 完成时间:三列加上;升级前已完成的卡按 updated_at 补成 ISO、标近似、完成者留空;别的卡不动;索引建了
+  for (const c of ["completed_at", "completed_by_json", "completed_at_approx"]) expect(cols.includes(c)).toBe(true);
+  const completed = db.all("SELECT requirement_id, completed_at, completed_by_json, completed_at_approx FROM requirements ORDER BY requirement_id") as any[];
+  for (const r of completed) {
+    if (r.requirement_id === "r_user_owner") expect(r).toEqual({ requirement_id: "r_user_owner", completed_at: "2026-09-01T10:00:00.000Z", completed_by_json: null, completed_at_approx: 1 });
+    else expect([r.completed_at, r.completed_by_json, r.completed_at_approx]).toEqual([null, null, 0]);
+  }
+  expect((db.all("PRAGMA index_list(requirements)") as { name: string }[]).some(i => i.name === "idx_requirements_network_completed")).toBe(true);
+  const { ensureRequirementCompletedAt } = await import("./requirements-migrate.js");
+  // 再跑一次(= 下次启动):什么都不动
+  expect(ensureRequirementCompletedAt(db)).toEqual({ backfilled: 0, cleared: 0 });
+  expect(db.all("SELECT requirement_id, completed_at, completed_by_json, completed_at_approx FROM requirements ORDER BY requirement_id")).toEqual(completed);
+  expect(migrateRequirementAgentOwners(db).moved).toBe(0);
+  expect(snapshot(db)).toEqual(after);
+});