@sleep2agi/commhub-server 0.9.0-preview.87 → 0.9.0-preview.89

package/src/requirements-owner-strict-mcp-http.test.ts

@@ -0,0 +1,145 @@
+// #470(MCP 任务生命周期测试报告问题 1)—— Agent 经 MCP 把负责人设成节点:以前走旧 App 的兼容改写,
+// 人类负责人被静默清空、负责 Agent 被换掉,响应还显示 owner=节点。现在:
+//   - MCP 上 owner 传节点(建 / 改 / upsert,节点令牌和用户令牌都一样)→ 400 owner_must_be_human + hint,什么都不写;
+//   - MCP 写入的响应就是落库的那一行(和紧接着的 requirements_get 一字不差);
+//   - REST 上旧 App ≤ 0.2.142 的兼容路径不变(requirements-http.test.ts「old-app compat」那条钉着)。
+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-owner-strict-mcp-"));
+let BASE = "";
+let hub: any = null;
+const PW = "OwnerStrictMcpPassw0rd!x";
+let NET = "", ownerToken = "", ownerId = "", nodeToken = "";
+const human = () => ({ kind: "user", id: ownerId });
+const nodeA = { kind: "node", id: "node_strict_a" };
+const nodeB = { kind: "node", id: "node_strict_b" };
+
+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 mcp(token: string, name: string, args: Record<string, unknown>): Promise<any> {
+  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: "tools/call", params: { name, arguments: args } }),
+  });
+  const raw = await res.text();
+  const lines = raw.split("\n").filter(x => x.startsWith("data:"));
+  const out = lines.length ? JSON.parse(lines.at(-1)!.slice(5).trim()) : JSON.parse(raw);
+  return JSON.parse(out.result.content[0].text);
+}
+const stored = (id: string) => db.get<{ owner_json: string | null; agent_owner_json: string | null }>("SELECT owner_json, agent_owner_json FROM requirements WHERE requirement_id = ?1", id)!;
+
+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(`strict_owner_${Date.now()}`, PW, undefined, "Owner");
+  ownerToken = a.token!; ownerId = a.user!.user_id; NET = a.network_id!;
+  nodeToken = createNetworkTokenForNode(ownerId, NET, "strict-a", "node_strict_a").token!;
+  createNetworkTokenForNode(ownerId, NET, "strict-b", "node_strict_b");
+  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}`;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("MCP: owner must be a person", () => {
+  test("update owner=node → 400 owner_must_be_human + hint; the human owner and the agent owner are untouched", async () => {
+    const card = (await mcp(nodeToken, "requirements_create", { name: "负责人保护", owner: human(), agent_owner: nodeB })).requirement;
+    expect(card.owner).toEqual(human());
+    const r = await mcp(nodeToken, "requirements_update", { id: card.id, owner: nodeA });
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe("owner_must_be_human");
+    expect(r.status).toBe(400);
+    expect(r.hint).toContain("agent_owner");
+    expect(r.owner_coerced_to_agent_owner).toBeUndefined();
+    const row = stored(card.id);
+    expect(JSON.parse(row.owner_json!)).toEqual(human());
+    expect(JSON.parse(row.agent_owner_json!)).toEqual(nodeB);
+    const got = (await mcp(nodeToken, "requirements_get", { id: card.id })).requirement;
+    expect(got.owner).toEqual(human());
+    expect(got.agent_owner).toEqual(nodeB);
+  });
+
+  test("…the same for a user token over MCP, for create (nothing is written) and for upsert", async () => {
+    const r = await mcp(ownerToken, "requirements_update", { network_id: NET, id: (await mcp(ownerToken, "requirements_create", { network_id: NET, name: "用户令牌", owner: human() })).requirement.id, owner: nodeA });
+    expect(r.error).toBe("owner_must_be_human");
+    const before = db.get<{ n: number }>("SELECT COUNT(*) AS n FROM requirements WHERE network_id = ?1", NET)!.n;
+    const c = await mcp(nodeToken, "requirements_create", { name: "建时就传节点", owner: nodeA });
+    expect(c.error).toBe("owner_must_be_human");
+    expect(c.hint).toContain("agent_owner");
+    expect(db.get<{ n: number }>("SELECT COUNT(*) AS n FROM requirements WHERE network_id = ?1", NET)!.n).toBe(before);
+    const u = await mcp(nodeToken, "requirements_upsert_by_external_ref", { external_ref: "github:example/repo#470", name: "upsert", owner: nodeA });
+    expect(u.error).toBe("owner_must_be_human");
+    expect(db.get("SELECT 1 FROM requirements WHERE external_ref = 'github:example/repo#470'")).toBeNull();
+  });
+
+  test("the right way still works: agent_owner = node, owner = person, owner = null", async () => {
+    const card = (await mcp(nodeToken, "requirements_create", { name: "正确的写法", owner: human() })).requirement;
+    const r = await mcp(nodeToken, "requirements_update", { id: card.id, agent_owner: nodeA });
+    expect(r.ok).toBe(true);
+    expect(r.requirement.owner).toEqual(human());
+    expect(r.requirement.agent_owner).toEqual(nodeA);
+    const cleared = await mcp(nodeToken, "requirements_update", { id: card.id, owner: null });
+    expect(cleared.requirement.owner).toBeNull();
+    // agent_owner given a person is refused the other way round, with its own hint.
+    const wrong = await mcp(nodeToken, "requirements_update", { id: card.id, agent_owner: human() });
+    expect(wrong.error).toBe("agent_owner_must_be_agent");
+    expect(wrong.hint).toContain("owner");
+  });
+
+  test("every MCP write's response equals a fresh requirements_get", async () => {
+    const card = (await mcp(nodeToken, "requirements_create", { name: "响应即落库", owner: human(), checklist: [{ text: "一" }] })).requirement;
+    expect((await mcp(nodeToken, "requirements_get", { id: card.id })).requirement).toEqual(card);
+    const patches: Record<string, unknown>[] = [
+      { column: "doing" }, { agent_owner: nodeA }, { participants: [nodeB, human()] }, { owner: null }, { owner: human(), priority: "high" },
+      { agent_owner: null }, { due: "2026-10-10" }, { archived: true }, { archived: false },
+    ];
+    for (const p of patches) {
+      const r = await mcp(nodeToken, "requirements_update", { id: card.id, ...p });
+      expect(r.ok).toBe(true);
+      expect(r.owner_coerced_to_agent_owner).toBeUndefined();
+      expect(r.requirement).toEqual((await mcp(nodeToken, "requirements_get", { id: card.id })).requirement);
+    }
+  });
+});
+
+describe("REST", () => {
+  test("new clients' responses equal a fresh GET (the old-app compat echo is the only exception, pinned in requirements-http.test.ts)", async () => {
+    const card = (await rest(ownerToken, "POST", "/api/requirements", { network_id: NET, name: "REST 响应", owner: human() })).body.requirement;
+    for (const p of [{ agent_owner: nodeA }, { owner: human(), agent_owner: nodeB }, { participants: [nodeA] }]) {
+      const r = await rest(ownerToken, "PATCH", `/api/requirements/${card.id}`, p);
+      expect(r.status).toBe(200);
+      expect(r.body.requirement).toEqual((await rest(ownerToken, "GET", `/api/requirements/${card.id}`)).body.requirement);
+    }
+    // A new client (sends agent_owner) passing a node as owner: still strict, now with the hint.
+    const strict = await rest(ownerToken, "PATCH", `/api/requirements/${card.id}`, { owner: nodeA, agent_owner: nodeB });
+    expect(strict.status).toBe(400);
+    expect(strict.body.error).toBe("owner_must_be_human");
+    expect(strict.body.hint).toContain("agent_owner");
+  });
+
+  test("old-app compat on REST is unchanged: owner=node without agent_owner is still coerced (200 + flag)", async () => {
+    const card = (await rest(ownerToken, "POST", "/api/requirements", { network_id: NET, name: "旧 App", owner: human() })).body.requirement;
+    const old = await rest(ownerToken, "PATCH", `/api/requirements/${card.id}`, { owner: nodeA });
+    expect(old.status).toBe(200);
+    expect(old.body.owner_coerced_to_agent_owner).toBe(true);
+    const row = stored(card.id);
+    expect(row.owner_json).toBeNull();
+    expect(JSON.parse(row.agent_owner_json!)).toEqual(nodeA);
+  });
+});

package/src/requirements-search.ts

@@ -94,7 +94,7 @@ export function decodeCursor(raw: string): Cursor | null {
   }
 }
 
-export type ListQuery = { limit: number; cursor: Cursor | null; terms: string[]; /** 整句当任务 ID 去对(taskIdQuery);空 = 没有搜索。 */ idQuery: string };
+export type ListQuery = { limit: number; cursor: Cursor | null; terms: string[]; /** 整句当任务 ID 去对(taskIdQuery);空 = 没有搜索。 */ idQuery: string; /** #471 —— 只要带这个标签的卡(精确、区分大小写);null = 不按标签筛。 */ tag: string | null };
 
 /**
  * 任务 ID(同 App 的 task-short-id.ts matchesTaskId):「#42」「42」精确对短号 seq;完整 id,或 8 位以上的
@@ -134,5 +134,12 @@ export function parseListQuery(params: URLSearchParams): ListQuery | { error: st
   const q = params.get("q") ?? "";
   if (q.length > MAX_QUERY_LENGTH) return { error: "invalid_q" };
   const terms = searchTerms(q);
-  return { limit, cursor, terms, idQuery: terms.length ? taskIdQuery(q) : "" };
+  // #471 —— tag=:和卡片标签同一套规范(去首尾空白、1–20 个字符、不含控制字符);不带 = 旧行为。
+  const rawTag = params.get("tag");
+  let tag: string | null = null;
+  if (rawTag !== null) {
+    tag = rawTag.trim();
+    if (!tag || [...tag].length > 20 || /[\u0000-\u001f\u007f]/u.test(tag)) return { error: "invalid_tag" };
+  }
+  return { limit, cursor, terms, idQuery: terms.length ? taskIdQuery(q) : "", tag };
 }

package/src/requirements.ts

@@ -1,5 +1,6 @@
 // 需求池。长期卡片，存在 Hub 上，手机和电脑读同一份。
 // 不是 tasks：tasks 是正在派给节点的活，状态由节点收尾。
+import { errorBody, errorFrom, RequirementFieldError, type ErrorContext } from "./requirements-errors.js";
 import { createHash } from "node:crypto";
 import { encodeCursor, matchesTaskId, matchesTerms, parseListQuery, type ListQuery, type NameMaps } from "./requirements-search.js";
 import { db, logAudit } from "./db.js";
@@ -37,6 +38,12 @@ export type RequirementsRequestContext = {
   isAdmin: boolean;
   isNodeToken: boolean;
   scope: RestNetworkScope;
+  /**
+   * #470 —— 负责人(owner)只收人,传节点一律 400 owner_must_be_human,不走旧 App 的「节点负责人 → 负责 Agent」兼容。
+   * MCP 工具(Agent 与人经 MCP 的调用)总是严格:那条兼容只为 App ≤ 0.2.142 的 REST 保存存在,Agent 走它会
+   * 静默清空人类负责人(task-lifecycle 测试报告问题 1)。REST 上带 agent_owner 的新客户端也严格(见 assignments)。
+   */
+  strictOwner?: boolean;
 };
 
 const COLUMNS = new Set(["pool", "doing", "done"]);
@@ -78,8 +85,9 @@ type Row = {
   completed_at_approx: number | null;
 };
 
-function jsonError(error: string, status: number): Response {
-  return Response.json({ ok: false, error }, { status });
+// #472:错误码原样,统一补 field / message / hint(requirements-errors.ts,唯一出口)。
+function jsonError(error: string, status: number, ctx?: ErrorContext): Response {
+  return Response.json(errorBody(error, ctx), { status });
 }
 
 // ── 任务的人员权限(RFC-038 §9,判定在 task-access.ts) ──
@@ -261,10 +269,10 @@ function projectNameTaken(networkId: string, name: string, except?: string): boo
 /** 卡片上的 project_id:null 清空;字符串必须是同一网络、未归档的项目。 */
 function projectRef(value: unknown, networkId: string): string | null {
   if (value === null) return null;
-  if (typeof value !== "string" || !value) throw new Error("invalid_project");
+  if (typeof value !== "string" || !value) throw new RequirementFieldError("invalid_project", "project_id", value);
   const row = db.get<ProjectRow>(`SELECT ${PROJECT_SELECT} FROM requirement_projects WHERE project_id = ?1`, value);
-  if (!row || row.network_id !== networkId) throw new Error("project_not_in_network");
-  if (row.archived) throw new Error("project_archived");
+  if (!row || row.network_id !== networkId) throw new RequirementFieldError("project_not_in_network", "project_id", value);
+  if (row.archived) throw new RequirementFieldError("project_archived", "project_id", value);
   return row.project_id;
 }
 
@@ -512,15 +520,15 @@ const SELECT = "requirement_id, network_id, title, column_name, priority, due_on
   "(SELECT COUNT(*) FROM requirements c WHERE c.parent_id = requirements.requirement_id AND COALESCE(c.archived, 0) = 0 AND c.column_name = 'done') AS children_done";
 
 type PersonRef = { kind: 'user' | 'node'; id: string };
-function personRef(value: unknown, networkId: string, hidden: HiddenNode = null): PersonRef {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('invalid_person');
+function personRef(value: unknown, networkId: string, hidden: HiddenNode = null, field = 'owner'): PersonRef {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new RequirementFieldError('invalid_person', field);
   const row = value as Record<string, unknown>;
-  if ((row.kind !== 'user' && row.kind !== 'node') || typeof row.id !== 'string' || !row.id.trim()) throw new Error('invalid_person');
+  if ((row.kind !== 'user' && row.kind !== 'node') || typeof row.id !== 'string' || !row.id.trim()) throw new RequirementFieldError('invalid_person', field);
   const exists = row.kind === 'user'
     ? db.get("SELECT 1 FROM network_members m JOIN users u ON u.user_id=m.user_id WHERE m.network_id=?1 AND m.user_id=?2", networkId, row.id)
     : db.get("SELECT 1 FROM nodes WHERE network_id=?1 AND node_id=?2", networkId, row.id);
   // 没授权的节点与不存在的节点同一个错误,不给受限成员留 node_id 探测差异。
-  if (!exists || (row.kind === 'node' && hidden?.(row.id as string))) throw new Error('person_not_in_network');
+  if (!exists || (row.kind === 'node' && hidden?.(row.id as string))) throw new RequirementFieldError('person_not_in_network', field);
   return { kind: row.kind, id: row.id };
 }
 
@@ -529,7 +537,7 @@ function personRef(value: unknown, networkId: string, hidden: HiddenNode = null)
 // 旧客户端兼容(App ≤ 0.2.142 只有一个「负责人」,可以选节点):请求里 owner 是节点、又**没带** agent_owner
 // → 当成设置负责 Agent,负责人清空,照常 200,并回 owner_coerced_to_agent_owner: true。
 // 带了 agent_owner 的就是新客户端,保持严格:owner 是节点 → 400 owner_must_be_human。
-function assignments(body: Record<string, unknown>, networkId: string, current?: Row, hidden: HiddenNode = null) {
+function assignments(body: Record<string, unknown>, networkId: string, current?: Row, hidden: HiddenNode = null, strictOwner = false) {
   let owner = current?.owner_json ? JSON.parse(current.owner_json) : null;
   let agentOwner = current?.agent_owner_json ? JSON.parse(current.agent_owner_json) : null;
   let coerced: PersonRef | null = null;
@@ -538,7 +546,7 @@ function assignments(body: Record<string, unknown>, networkId: string, current?:
   if ('owner' in body) {
     owner = body.owner === null ? null : personRef(body.owner, networkId, hidden);
     if (owner && owner.kind !== 'user') {
-      if ('agent_owner' in body) throw new Error('owner_must_be_human');
+      if (strictOwner || 'agent_owner' in body) throw new Error('owner_must_be_human');
       coerced = owner;
       agentOwner = owner;
       owner = null;
@@ -547,13 +555,13 @@ function assignments(body: Record<string, unknown>, networkId: string, current?:
   if (coerced && agentOwnerLocked) throw new Error('agent_owner_not_granted');
   if ('agent_owner' in body) {
     if (agentOwnerLocked) throw new Error('agent_owner_not_granted');
-    agentOwner = body.agent_owner === null ? null : personRef(body.agent_owner, networkId, hidden);
+    agentOwner = body.agent_owner === null ? null : personRef(body.agent_owner, networkId, hidden, 'agent_owner');
     if (agentOwner && agentOwner.kind !== 'node') throw new Error('agent_owner_must_be_agent');
   }
   let participants = current ? JSON.parse(current.participants_json || '[]') : [];
   if ('participants' in body) {
     if (!Array.isArray(body.participants) || body.participants.length > 100) throw new Error('invalid_participants');
-    const refs = body.participants.map(value => personRef(value, networkId, hidden));
+    const refs = body.participants.map(value => personRef(value, networkId, hidden, 'participants'));
     // 参与人是整体替换:把受限成员看不见的那些节点原样留下,别让他「保存」时静默删掉。
     const keptHidden = hidden ? participants.filter((ref: unknown) => isHiddenRef(ref, hidden)) : [];
     participants = [...new Map([...keptHidden, ...refs].map((ref: PersonRef) => [`${ref.kind}:${ref.id}`, ref])).values()];
@@ -741,7 +749,7 @@ async function createRequirement(ctx: RequirementsRequestContext, body: Record<s
   const scoped = !!caller && isTaskScoped(caller.userId, networkId);
   let projectId: string | null = null;
   if (body.project_id !== undefined) {
-    try { projectId = projectRef(body.project_id, networkId); } catch (e) { return jsonError((e as Error).message, 400); }
+    try { projectId = projectRef(body.project_id, networkId); } catch (e) { return errorFrom(e); }
     // scoped 成员只能建进自己 can_edit 的项目;没授权的项目与不存在的项目同一个错误。
     if (!canUseProject(caller, networkId, projectId)) return jsonError("project_not_in_network", 400);
   }
@@ -760,7 +768,7 @@ async function createRequirement(ctx: RequirementsRequestContext, body: Record<s
   if (ref) {
     const existing = rowByExternalRef(networkId, ref);
     // 同一个外部条目再建一次 = 冲突,回已有的 id(同步方改用 upsert,或按这个 id PATCH)。
-    if (existing) return Response.json({ ok: false, error: "external_ref_exists", existing_id: existing.requirement_id }, { status: 409 });
+    if (existing) return Response.json({ ...errorBody("external_ref_exists"), existing_id: existing.requirement_id }, { status: 409 });
   }
   if (clientId) {
     const existing = db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE network_id = ?1 AND client_id = ?2`, networkId, clientId);
@@ -770,7 +778,7 @@ async function createRequirement(ctx: RequirementsRequestContext, body: Record<s
   const id = `req_${crypto.randomUUID()}`;
   const createdAt = new Date().toISOString();
   let people;
-  try { people = assignments(body, networkId, undefined, hiddenNodeFilter(ctx, networkId)); } catch (e) { return jsonError((e as Error).message, 400); }
+  try { people = assignments(body, networkId, undefined, hiddenNodeFilter(ctx, networkId), ctx.strictOwner === true); } catch (e) { return errorFrom(e); }
   const actor = JSON.stringify(actorOf(ctx));
   try {
     // 领号、插入、记「新建」这条动态在同一个事务里:插入被唯一索引挡下时,号和动态一起回滚,不留空洞。
@@ -790,7 +798,7 @@ async function createRequirement(ctx: RequirementsRequestContext, body: Record<s
     // 并发的同一个 external_ref / client_id:唯一索引挡住了第二个,回已有的那条。
     if (ref) {
       const existing = rowByExternalRef(networkId, ref);
-      if (existing) return Response.json({ ok: false, error: "external_ref_exists", existing_id: existing.requirement_id }, { status: 409 });
+      if (existing) return Response.json({ ...errorBody("external_ref_exists"), existing_id: existing.requirement_id }, { status: 409 });
     }
     if (!clientId) return jsonError("insert_failed", 500);
     const existing = db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE network_id = ?1 AND client_id = ?2`, networkId, clientId);
@@ -805,7 +813,7 @@ async function createRequirement(ctx: RequirementsRequestContext, body: Record<s
 // ── 修改(省略的字段保留原值) ──
 const PATCH_FIELDS = ["column", "issues", "tags", "name", "priority", "due", "assignee", "owner", "agent_owner", "participants", "description", "checklist", "project_id", "external_ref", "external_url", "archived", "parent_id", "start"];
 function patchRequirement(ctx: RequirementsRequestContext, row: Row, body: Record<string, unknown>): Response {
-  if (!PATCH_FIELDS.some(k => Object.prototype.hasOwnProperty.call(body, k))) return jsonError("empty_patch", 400);
+  if (!PATCH_FIELDS.some(k => Object.prototype.hasOwnProperty.call(body, k))) return jsonError("empty_patch", 400, { sent: Object.keys(body), writable: PATCH_FIELDS });
   const has = (k: string) => Object.prototype.hasOwnProperty.call(body, k);
   if (!canWrite(ctx, row.network_id)) return jsonError("permission_denied", 403);
   const caller = taskCaller(ctx);
@@ -856,10 +864,10 @@ function patchRequirement(ctx: RequirementsRequestContext, row: Row, body: Recor
     assignee = body.assignee.trim().slice(0, 80);
   }
   let people;
-  try { people = assignments(body, row.network_id, row, hiddenNodeFilter(ctx, row.network_id)); } catch (e) { return jsonError((e as Error).message, 400); }
+  try { people = assignments(body, row.network_id, row, hiddenNodeFilter(ctx, row.network_id), ctx.strictOwner === true); } catch (e) { return errorFrom(e); }
   let projectId = row.project_id;
   if (has("project_id")) {
-    try { projectId = projectRef(body.project_id, row.network_id); } catch (e) { return jsonError((e as Error).message, 400); }
+    try { projectId = projectRef(body.project_id, row.network_id); } catch (e) { return errorFrom(e); }
     // scoped 成员只能挪进自己 can_edit 的项目;没授权的项目与不存在的项目同一个错误。
     if (projectId !== row.project_id && !canUseProject(caller, row.network_id, projectId)) return jsonError("project_not_in_network", 400);
   }
@@ -869,7 +877,7 @@ function patchRequirement(ctx: RequirementsRequestContext, row: Row, body: Recor
     if (next === undefined) return jsonError("invalid_external_ref", 400);
     if (next && next !== row.external_ref) {
       const taken = rowByExternalRef(row.network_id, next);
-      if (taken) return Response.json({ ok: false, error: "external_ref_exists", existing_id: taken.requirement_id }, { status: 409 });
+      if (taken) return Response.json({ ...errorBody("external_ref_exists"), existing_id: taken.requirement_id }, { status: 409 });
     }
     ref = next;
   }
@@ -950,7 +958,7 @@ function scopedRow(ctx: RequirementsRequestContext, id: string): Row | Response
   const rows = db.all<Row>(`${sql} LIMIT 2`, ...params);
   if (rows.length > 1) {
     const networks = rows.map(r => r.network_id);
-    return Response.json({ ok: false, error: "ambiguous_seq", networks, message: `#${seq} exists in more than one network you can see (${networks.join(", ")}); pass network_id to pick one` }, { status: 409 });
+    return Response.json({ ...errorBody("ambiguous_seq"), networks, message: `#${seq} exists in more than one network you can see (${networks.join(", ")}); pass network_id to pick one` }, { status: 409 });
   }
   return rows[0] ?? jsonError("requirement_not_found", 404);
 }
@@ -1014,7 +1022,7 @@ function listPage(ctx: RequirementsRequestContext, from: string, baseParams: unk
     where += ` AND (created_at < ?${a} OR (created_at = ?${a} AND requirement_id < ?${b}))`;
   }
   let rows: Row[];
-  if (!lq.terms.length) {
+  if (!lq.terms.length && lq.tag === null) {
     rows = db.all<Row>(`SELECT ${SELECT} ${where}${LIST_ORDER} LIMIT ${lq.limit + 1}`, ...params);
   } else {
     // seq(任务短号,#2139):启动迁移 ensureRequirementSeq 在 SQLite / PostgreSQL 上都加这一列,SELECT 本来就带它。
@@ -1025,7 +1033,9 @@ function listPage(ctx: RequirementsRequestContext, from: string, baseParams: unk
       let m = maps.get(r.network_id);
       if (!m) maps.set(r.network_id, m = searchNameMaps(ctx, r.network_id));
       const row = { name: r.title, description: r.description || "", assignee: r.assignee || "", tags: storedTags(r.tags_json), project_id: r.project_id, owner: parseRef(r.owner_json), agent_owner: parseRef(r.agent_owner_json), participants: parseRef(r.participants_json) ?? [] };
-      if (matchesTaskId(r, lq.idQuery) || matchesTerms(row, lq.terms, m)) hits.push(r.requirement_id);
+      // #471 —— tag= 在这里按存好的标签数组精确比(JSON 列,SQLite / PostgreSQL 写法不同,所以不进 SQL)。
+      if (lq.tag !== null && !row.tags.includes(lq.tag)) continue;
+      if (!lq.terms.length || matchesTaskId(r, lq.idQuery) || matchesTerms(row, lq.terms, m)) hits.push(r.requirement_id);
       if (hits.length > lq.limit) break;
     }
     const byId = new Map(hits.length ? db.all<Row>(`SELECT ${SELECT} FROM requirements WHERE requirement_id IN (${hits.map((_, i) => `?${i + 1}`).join(",")})`, ...hits).map(r => [r.requirement_id, r]) : []);
@@ -1436,7 +1446,7 @@ async function handleRequirementsRequestInner(ctx: RequirementsRequestContext):
   if (req.method !== "PATCH") return jsonError("not_found", 404);
   let body: Record<string, unknown>;
   try { body = await bodyObject(req); } catch { return jsonError("invalid_json", 400); }
-  if (!PATCH_FIELDS.some(k => Object.prototype.hasOwnProperty.call(body, k))) return jsonError("empty_patch", 400);
+  if (!PATCH_FIELDS.some(k => Object.prototype.hasOwnProperty.call(body, k))) return jsonError("empty_patch", 400, { sent: Object.keys(body), writable: PATCH_FIELDS });
   const row = scopedRow(ctx, id);
   if (row instanceof Response) return row;
   return patchRequirement(ctx, row, body);

package/src/scheduled-stuck-http.test.ts

@@ -0,0 +1,238 @@
+// #464 —— 定时任务被一次没结束的执行卡住:告警 + 超时放行。
+//
+// 钉住:
+//   1. 默认值:超时 = clamp(6 × 间隔, 1h, 24h);环境变量能改。
+//   2. 同一个挡路任务连续挡掉 3 次 → 给排程创建者发恰好 1 条通知(别的成员 0 条);第 4、5 次不再发;
+//      挡路任务一换(下一次真派出去了)重新上膛。
+//   3. 挡路任务开着超过超时 → 它变成 expired(行还在、收件箱行 acked、run 记 expired/task_expired、
+//      error_message 说明是调度器超时),这一次照常派发。超时前已发过「卡住」→ 不再发;没发过 → 发一条「已超时」。
+//   4. 晚到的回复:send_reply 以 reply_task_terminal 拒掉,旧 run / 旧任务 / 新任务 / 新 run 都不变,创建者不多收东西。
+//   5. GET /runs 带 blocked_by_task_id / blocked_by_state。
+//
+// 跑法:cd server && COMMHUB_DB=/tmp/x.db bun test src/scheduled-stuck-http.test.ts
+//       PG:COMMHUB_TEST_PG_URL=… COMMHUB_PG_EXPERIMENTAL=1(tests/test2123-hub-postgres-ladder 里注册)
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { addNetworkMember, createNetworkTokenForNode, register } from "./auth.js";
+import { db } from "./db.js";
+import { dispatchScheduledOccurrence, handleScheduledTaskRequest } from "./scheduled-tasks.js";
+import { SCHEDULE_STUCK_NOTICE_KIND, stuckTimeoutMs } from "./scheduled-stuck.js";
+import { registerTools } from "./tools.js";
+
+const activeDbPath = process.env.COMMHUB_DB ?? (process.env.COMMHUB_TEST_PG_URL ? "postgres" : undefined);
+if (!activeDbPath) throw new Error("scheduled-stuck requires COMMHUB_DB (or COMMHUB_TEST_PG_URL) before module import");
+
+const stamp = Date.now();
+const ALIAS = `stuck-node-${stamp}`;
+const NODE_ID = `n_stuck_${stamp}`;
+let NET = "", creatorId = "", otherId = "";
+const ENV_KEYS = ["COMMHUB_SCHEDULE_STUCK_NOTICE_SKIPS", "COMMHUB_SCHEDULE_STUCK_TIMEOUT_FACTOR", "COMMHUB_SCHEDULE_STUCK_TIMEOUT_FLOOR_SEC", "COMMHUB_SCHEDULE_STUCK_TIMEOUT_CAP_SEC"];
+
+function seedSchedule(name = "日报汇总"): any {
+  const scheduleId = `sched_${crypto.randomUUID()}`;
+  db.run(
+    `INSERT INTO scheduled_tasks
+       (schedule_id, network_id, created_by, name, target_node_id, target_alias, task_content, priority,
+        schedule_type, schedule_json, timezone, status, next_run_at)
+     VALUES (?1, ?2, ?3, ?4, ?5, ?6, 'scheduled task', 'normal', 'interval',
+             '{"type":"interval","every_seconds":60}', 'Asia/Shanghai', 'active', datetime('now', '+1 minute'))`,
+    [scheduleId, NET, creatorId, name, NODE_ID, ALIAS],
+  );
+  return db.get("SELECT * FROM scheduled_tasks WHERE schedule_id = ?1", scheduleId);
+}
+
+let slot = 0;
+const nextSlot = () => new Date(Date.UTC(2026, 9, 2, 0, 0, 0) + (++slot) * 60_000).toISOString();
+const fire = (schedule: any, now = new Date()) => dispatchScheduledOccurrence(schedule, nextSlot(), false, now);
+
+const notices = (userId: string) => db.all<{ title: string; content: string; meta_json: string; from_session: string }>(
+  "SELECT title, content, meta_json, from_session FROM user_inbox WHERE user_id = ?1 AND network_id = ?2 AND kind = ?3 ORDER BY created_at, message_id",
+  userId, NET, SCHEDULE_STUCK_NOTICE_KIND,
+);
+const runRow = (runId: string) => db.get<any>("SELECT * FROM scheduled_task_runs WHERE run_id = ?1", runId);
+const taskRow = (taskId: string) => db.get<any>("SELECT * FROM tasks WHERE task_id = ?1", taskId);
+/** 把任务的开始时间往前拨(数据库里的 UTC 无时区串)。 */
+const backdate = (taskId: string, ms: number) => db.run("UPDATE tasks SET created_at = ?1 WHERE task_id = ?2", [new Date(Date.now() - ms).toISOString().slice(0, 19).replace("T", " "), taskId]);
+
+async function nodeReply(args: Record<string, unknown>): Promise<any> {
+  const mcp = new McpServer({ name: "sched-stuck", version: "0" }) as any;
+  const handlers: Record<string, (a: any) => Promise<any>> = {};
+  const original = mcp.tool.bind(mcp);
+  mcp.tool = (name: string, ...rest: any[]) => {
+    const handler = rest.at(-1);
+    if (typeof handler === "function") handlers[name] = handler;
+    return original(name, ...rest);
+  };
+  registerTools(mcp, undefined, NET, creatorId, ALIAS, true, null);
+  const out = await handlers.send_reply(args);
+  return JSON.parse(out.content[0].text);
+}
+
+beforeAll(() => {
+  const creator = register(`stuck_creator_${stamp}`, "StuckCreator123!", undefined, "seed");
+  expect(creator.ok).toBe(true);
+  NET = creator.network_id!; creatorId = creator.user!.user_id;
+  const other = register(`stuck_other_${stamp}`, "StuckOther123!", undefined, "seed");
+  otherId = other.user!.user_id;
+  expect(addNetworkMember(NET, otherId, "member", creatorId, { agentAccess: "all" }).ok).toBe(true);
+  expect(createNetworkTokenForNode(creatorId, NET, ALIAS).ok).toBe(true);
+  db.run("INSERT INTO nodes (node_id, node_name, alias, runtime, network_id) VALUES (?1, ?2, ?2, 'claude-code', ?3)", [NODE_ID, ALIAS, NET]);
+  db.run("INSERT INTO sessions (resume_id, alias, status, node_id, network_id) VALUES (?1, ?2, 'idle', ?3, ?4)", [`r_stuck_${stamp}`, ALIAS, NODE_ID, NET]);
+});
+beforeEach(() => {
+  for (const k of ENV_KEYS) delete process.env[k];
+  db.run("DELETE FROM user_inbox WHERE network_id = ?1 AND kind = ?2", [NET, SCHEDULE_STUCK_NOTICE_KIND]);
+  // 上一个用例留下的开着的任务不许挡这一个(每个用例自己的排程,只按 schedule 查,保险起见也关掉)
+  db.run("UPDATE tasks SET status = 'replied' WHERE network_id = ?1 AND status IN ('created', 'delivered', 'acked', 'running')", [NET]);
+});
+afterEach(() => { for (const k of ENV_KEYS) delete process.env[k]; });
+afterAll(() => { db.run("DELETE FROM user_inbox WHERE network_id = ?1 AND kind = ?2", [NET, SCHEDULE_STUCK_NOTICE_KIND]); });
+
+describe("#464 defaults", () => {
+  test("timeout = clamp(6 × interval, 1h, 24h)", () => {
+    const iv = (s: number) => JSON.stringify({ type: "interval", every_seconds: s });
+    expect(stuckTimeoutMs(iv(60))).toBe(3_600_000);
+    expect(stuckTimeoutMs(iv(600))).toBe(3_600_000);
+    expect(stuckTimeoutMs(iv(1800))).toBe(3 * 3_600_000);
+    expect(stuckTimeoutMs(iv(3600))).toBe(6 * 3_600_000);
+    expect(stuckTimeoutMs(iv(86_400))).toBe(24 * 3_600_000);
+    expect(stuckTimeoutMs(JSON.stringify({ type: "daily", time: "09:00" }))).toBe(24 * 3_600_000);
+    expect(stuckTimeoutMs(JSON.stringify({ type: "once", run_at: "2026-10-02T00:00:00Z" }))).toBe(3_600_000);
+    process.env.COMMHUB_SCHEDULE_STUCK_TIMEOUT_FACTOR = "0";
+    process.env.COMMHUB_SCHEDULE_STUCK_TIMEOUT_FLOOR_SEC = "20";
+    expect(stuckTimeoutMs(iv(60))).toBe(20_000);
+    process.env.COMMHUB_SCHEDULE_STUCK_TIMEOUT_FLOOR_SEC = "junk";
+    expect(stuckTimeoutMs(iv(60))).toBe(3_600_000);
+  });
+});
+
+describe("#464 stuck notice", () => {
+  test("3rd consecutive skip behind the same task → exactly one notice to the creator, none to others", () => {
+    const s = seedSchedule();
+    const first = fire(s);
+    expect(first.status).toBe("delivered");
+    const skips = [fire(s), fire(s)];
+    expect(notices(creatorId).length).toBe(0);
+    skips.push(fire(s), fire(s), fire(s));
+    expect(skips.map((r) => r.status)).toEqual(["skipped", "skipped", "skipped", "skipped", "skipped"]);
+    const mine = notices(creatorId);
+    expect(mine.length).toBe(1);
+    expect(notices(otherId).length).toBe(0);
+    const n = mine[0];
+    expect(n.from_session).toBe(ALIAS);
+    expect(n.title).toBe("定时任务被卡住");
+    for (const frag of ["日报汇总", first.taskId!, ALIAS, "(Asia/Shanghai)", "3 次", "1 小时"]) expect(n.content).toContain(frag);
+    expect(JSON.parse(n.meta_json).schedule_stuck).toEqual({ reason: "stuck", schedule_id: s.schedule_id, blocked_by_task_id: first.taskId, skips: 3 });
+  });
+
+  test("re-armed once a run is dispatched again: a second episode notifies again", () => {
+    const s = seedSchedule();
+    const first = fire(s);
+    for (let i = 0; i < 4; i++) fire(s);
+    db.run("UPDATE tasks SET status = 'replied', completed_at = datetime('now') WHERE task_id = ?1", [first.taskId]);
+    const second = fire(s);
+    expect(second.status).toBe("delivered");
+    for (let i = 0; i < 3; i++) fire(s);
+    const mine = notices(creatorId);
+    expect(mine.length).toBe(2);
+    // 两条通知同一秒写入,created_at 排不出先后:按挡路任务比集合。
+    expect(mine.map((m) => JSON.parse(m.meta_json).schedule_stuck.blocked_by_task_id).sort()).toEqual([first.taskId, second.taskId].sort());
+  });
+
+  test("COMMHUB_SCHEDULE_STUCK_NOTICE_SKIPS changes N", () => {
+    process.env.COMMHUB_SCHEDULE_STUCK_NOTICE_SKIPS = "1";
+    const s = seedSchedule();
+    fire(s); fire(s);
+    expect(notices(creatorId).length).toBe(1);
+  });
+
+  test("schedule without a creator → no notice, skips still recorded", () => {
+    const s = seedSchedule();
+    db.run("UPDATE scheduled_tasks SET created_by = NULL WHERE schedule_id = ?1", [s.schedule_id]);
+    const row = db.get("SELECT * FROM scheduled_tasks WHERE schedule_id = ?1", s.schedule_id);
+    fire(row); for (let i = 0; i < 4; i++) expect(fire(row).status).toBe("skipped");
+    expect(notices(creatorId).length).toBe(0);
+  });
+});
+
+describe("#464 stuck timeout", () => {
+  test("blocker past the timeout is expired (row kept) and this occurrence dispatches; no second notice", () => {
+    const s = seedSchedule();
+    const first = fire(s);
+    db.run("UPDATE tasks SET status = 'running' WHERE task_id = ?1", [first.taskId]);
+    for (let i = 0; i < 3; i++) fire(s);
+    expect(notices(creatorId).length).toBe(1);
+
+    backdate(first.taskId!, 59 * 60_000);
+    expect(fire(s).status).toBe("skipped"); // 59 分钟 < 1 小时
+    backdate(first.taskId!, 61 * 60_000);
+    const next = fire(s);
+    expect(next.status).toBe("delivered");
+    expect(next.taskId).not.toBe(first.taskId);
+
+    const old = taskRow(first.taskId!);
+    expect(old.status).toBe("expired");
+    expect(old.content).toBe("scheduled task");
+    expect(db.get<any>("SELECT acked FROM inbox WHERE task_id = ?1", first.taskId).acked).toBeTruthy();
+    const oldRun = runRow(first.runId);
+    expect(oldRun.status).toBe("expired");
+    expect(oldRun.error_code).toBe("task_expired");
+    expect(oldRun.error_message).toContain("timed out by the scheduler");
+    expect(db.get<any>("SELECT COUNT(*) AS n FROM task_events WHERE task_id = ?1 AND to_status = 'expired' AND actor = 'hub-scheduler'", first.taskId).n).toBe(1);
+    expect(notices(creatorId).length).toBe(1); // 每段卡住恰好一条
+  });
+
+  test("timed out before N skips (long interval) → one 'timed out' notice instead", () => {
+    const s = seedSchedule("每日巡检");
+    const first = fire(s);
+    expect(fire(s).status).toBe("skipped");
+    backdate(first.taskId!, 2 * 3_600_000);
+    expect(fire(s).status).toBe("delivered");
+    const mine = notices(creatorId);
+    expect(mine.length).toBe(1);
+    expect(mine[0].title).toBe("定时任务已超时放行");
+    expect(mine[0].content).toContain(first.taskId!);
+    expect(JSON.parse(mine[0].meta_json).schedule_stuck.reason).toBe("timed_out");
+  });
+
+  test("a late reply to the expired task is refused and changes nothing", async () => {
+    const s = seedSchedule();
+    const first = fire(s);
+    backdate(first.taskId!, 2 * 3_600_000);
+    const next = fire(s);
+    expect(next.status).toBe("delivered");
+    const inboxBefore = db.get<any>("SELECT COUNT(*) AS n FROM inbox WHERE network_id = ?1", NET).n;
+    const out = await nodeReply({ alias: "scheduler", text: "late answer", in_reply_to: first.taskId, status: "replied", from_session: ALIAS });
+    expect(out.ok).toBe(false);
+    expect(out.error).toBe("reply_task_terminal");
+    expect(out.reply_queued).toBe(false);
+    expect(taskRow(first.taskId!).status).toBe("expired");
+    expect(runRow(first.runId).status).toBe("expired");
+    expect(taskRow(next.taskId!).status).toBe("delivered");
+    expect(runRow(next.runId).status).toBe("delivered");
+    expect(db.get<any>("SELECT COUNT(*) AS n FROM inbox WHERE network_id = ?1", NET).n).toBe(inboxBefore);
+    // 新那条照常能被回复,run 照常收尾
+    const ok = await nodeReply({ alias: "scheduler", text: "on time", in_reply_to: next.taskId, status: "replied", from_session: ALIAS });
+    expect(ok.ok).toBe(true);
+    expect(runRow(next.runId).status).toBe("replied");
+  });
+});
+
+describe("#464 history clarity", () => {
+  test("GET /runs exposes blocked_by_task_id and blocked_by_state on skipped rows", async () => {
+    const s = seedSchedule();
+    const first = fire(s);
+    const second = fire(s);
+    const url = new URL(`http://hub.test/api/scheduled-tasks/${s.schedule_id}/runs`);
+    const res = await handleScheduledTaskRequest({
+      req: new Request(url, { method: "GET" }), url,
+      auth: { userId: creatorId, networkId: NET, username: "creator" },
+      isAdmin: false, isNodeToken: false, scope: { networkId: NET, networkIds: [NET] } as any,
+    });
+    const body = await res!.json() as any;
+    const skipped = body.runs.find((r: any) => r.run_id === second.runId);
+    expect(skipped.status).toBe("skipped");
+    expect(skipped.blocked_by_task_id).toBe(first.taskId);
+    expect(skipped.blocked_by_state).toBe("not_received");
+  });
+});