@sleep2agi/commhub-server 0.9.0-preview.70 → 0.9.0-preview.72

package/src/requirements.ts

@@ -1,10 +1,12 @@
 // 需求池。长期卡片，存在 Hub 上，手机和电脑读同一份。
 // 不是 tasks：tasks 是正在派给节点的活，状态由节点收尾。
+import { createHash } from "node:crypto";
+import { encodeCursor, matchesTaskId, matchesTerms, parseListQuery, type ListQuery, type NameMaps } from "./requirements-search.js";
 import { db } from "./db.js";
 import { normalizeTags, storedTags } from "./requirement-tags.js";
 import { addHumanNetworkScope, canRestWriteNetwork, canRestWriteNetworkAsHuman, resolveRestWriteNetworkId, type RestNetworkScope } from "./network-scope.js";
 import { isAgentRestricted, visibleAgents } from "./agent-access.js";
-import { ensureRequirementIndexes, ensureRequirementProjects, migrateRequirementAgentOwners, migrateRequirementPriorityCheck } from "./requirements-migrate.js";
+import { ensureRequirementIndexes, ensureRequirementProjects, ensureRequirementSeq, migrateRequirementAgentOwners, migrateRequirementPriorityCheck, nextRequirementSeq } from "./requirements-migrate.js";
 
 // 启动迁移:旧库里节点当负责人的卡,节点挪到 agent_owner(列由 db.ts 的加列循环加上)。
 // 放在这里而不是 db.ts:db.ts 每多一行,文档里钉着的行号就漂一次。
@@ -12,6 +14,7 @@ migrateRequirementPriorityCheck(db);
 migrateRequirementAgentOwners(db);
 ensureRequirementProjects(db);
 ensureRequirementIndexes(db);
+ensureRequirementSeq(db);
 
 type RequestAuth = { userId: string; networkId: string | null; username: string; tokenId?: string | null; tokenName?: string | null } | null;
 
@@ -52,10 +55,12 @@ type Row = {
   column_name: string;
   priority: string;
   due_on: string | null;
+  start_on: string | null;
   assignee: string | null;
   issues_json: string | null;
   tags_json: string | null;
   created_at: string;
+  seq: number | null;
 };
 
 function jsonError(error: string, status: number): Response {
@@ -281,10 +286,14 @@ function toPublic(row: Row) {
     project_id: row.project_id || null,
     participants: JSON.parse(row.participants_json || '[]'),
     id: row.requirement_id,
+    // 短号:每个网络自己的 #1、#2…(不回收)。界面显示 #N;GET / PATCH / MCP 的 id 也收「#N」。旧 App 忽略它。
+    seq: row.seq == null ? null : Number(row.seq),
     name: row.title,
     priority: row.priority,
     assignee: row.assignee || "",
     due: row.due_on || "",
+    // 开始(可空,甘特图用)。形状同 due;没设 = ""。旧 App 不认识这个字段,忽略即可。
+    start: row.start_on || "",
     column: row.column_name,
     createdAt: row.created_at,
     updatedAt: row.updated_at || row.created_at,
@@ -353,7 +362,7 @@ function toPublicFor(ctx: RequirementsRequestContext, row: Row) {
   };
 }
 
-const SELECT = "requirement_id, network_id, title, column_name, priority, due_on, assignee, issues_json, tags_json, created_at, owner_json, participants_json, agent_owner_json, description, checklist_json, project_id, external_ref, external_url, archived, created_by, created_by_json, updated_by_json, updated_at, parent_id, " +
+const SELECT = "requirement_id, network_id, title, column_name, priority, due_on, assignee, issues_json, tags_json, created_at, owner_json, participants_json, agent_owner_json, description, checklist_json, project_id, external_ref, external_url, archived, created_by, created_by_json, updated_by_json, updated_at, parent_id, start_on, seq, " +
   "(SELECT COUNT(*) FROM requirements c WHERE c.parent_id = requirements.requirement_id AND COALESCE(c.archived, 0) = 0) AS children_total, " +
   "(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";
 
@@ -427,7 +436,29 @@ function operationOf(req: Request, url: URL): string {
   return "create";
 }
 
-export const REQUIREMENT_CAPABILITIES = ["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements", "tags", "priority_lowest"] as const;
+/**
+ * GET /api/requirements 的条件请求:ETag = 响应体的哈希,`If-None-Match` 对上就回 304 空体。
+ * app 每 15 s 轮询整张表(生产 500 行 708 KB / gzip 163 KB,中国 → 美国约 0.65 s 纯传输),
+ * 绝大多数轮询里表根本没变。按**响应体**算,所以对这个调用方可见的任何字段变了都会变
+ * (同一张表不同成员看到的不同,ETag 也不同)。不带 If-None-Match 的旧客户端照旧拿 200 全量。
+ */
+export function conditionalJson(req: Request, payload: unknown): Response {
+  const body = JSON.stringify(payload);
+  const etag = `W/"${createHash("sha256").update(body).digest("base64url").slice(0, 27)}"`;
+  // private:按用户可见范围生成,不能被共享缓存复用;no-cache:每次都要回来验证,不会拿旧表当新的。
+  const headers = { ETag: etag, "Cache-Control": "private, no-cache" };
+  if (ifNoneMatchHits(req.headers.get("if-none-match"), etag)) return new Response(null, { status: 304, headers });
+  return new Response(body, { headers: { ...headers, "Content-Type": "application/json;charset=utf-8" } });
+}
+
+function ifNoneMatchHits(header: string | null, etag: string): boolean {
+  if (!header) return false;
+  const bare = (tag: string) => tag.trim().replace(/^W\//, "");
+  return header.split(",").some(tag => tag.trim() === "*" || bare(tag) === bare(etag));
+}
+
+// search:GET 认 q=(服务端搜索,语义同 App 的任务搜索);paging:认 limit / cursor,响应带 has_more / next_cursor。
+export const REQUIREMENT_CAPABILITIES = ["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements", "tags", "priority_lowest", "start_date", "requirement_seq", "search", "paging"] as const;
 
 // ── 子需求 ──
 // parent_id:同一网络里的另一张卡;不能成环;最多 5 层(顶层是第 1 层)。删父卡 = 子卡保留、parent_id 置空。
@@ -534,6 +565,8 @@ async function createRequirement(ctx: RequirementsRequestContext, body: Record<s
   if (!PRIORITIES.has(priority)) return jsonError("invalid_priority", 400);
   const due = typeof body.due === "string" ? normalizeDue(body.due) : "";
   if (due === null) return jsonError("invalid_due", 400);
+  const start = typeof body.start === "string" ? normalizeDue(body.start) : "";
+  if (start === null) return jsonError("invalid_start", 400);
   const assignee = typeof body.assignee === "string" ? body.assignee.trim().slice(0, 80) : "";
   const clientId = typeof body.client_id === "string" ? body.client_id.trim() : "";
   if (clientId && !/^[A-Za-z0-9._-]{1,80}$/.test(clientId)) return jsonError("invalid_client_id", 400);
@@ -575,12 +608,13 @@ async function createRequirement(ctx: RequirementsRequestContext, body: Record<s
   try { people = assignments(body, networkId, undefined, hiddenNodeFilter(ctx, networkId)); } catch (e) { return jsonError((e as Error).message, 400); }
   const actor = JSON.stringify(actorOf(ctx));
   try {
-    db.run(
+    // 领号和插入在同一个事务里:插入被唯一索引挡下时,号一起回滚,不留空洞。
+    db.transaction(() => db.run(
       `INSERT INTO requirements
-       (requirement_id, network_id, title, column_name, priority, due_on, assignee, client_id, issues_json, created_by, created_at, updated_at, owner_json, participants_json, agent_owner_json, description, checklist_json, project_id, external_ref, external_url, created_by_json, updated_by_json, archived, parent_id, tags_json)
-       VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?11, ?12, ?13, ?14, ?15, ?16, ?17, ?18, ?19, ?20, ?20, 0, ?21, ?22)`,
-      [id, networkId, name, column, priority, due || null, assignee, clientId || null, JSON.stringify(issues), ctx.auth?.userId ?? null, createdAt, people.ownerJson, people.participantsJson, people.agentOwnerJson, description || null, JSON.stringify(checklist), projectId, ref, extUrl, actor, parentId, JSON.stringify(tags)],
-    );
+       (requirement_id, network_id, title, column_name, priority, due_on, assignee, client_id, issues_json, created_by, created_at, updated_at, owner_json, participants_json, agent_owner_json, description, checklist_json, project_id, external_ref, external_url, created_by_json, updated_by_json, archived, parent_id, tags_json, start_on, seq)
+       VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?11, ?12, ?13, ?14, ?15, ?16, ?17, ?18, ?19, ?20, ?20, 0, ?21, ?22, ?23, ?24)`,
+      [id, networkId, name, column, priority, due || null, assignee, clientId || null, JSON.stringify(issues), ctx.auth?.userId ?? null, createdAt, people.ownerJson, people.participantsJson, people.agentOwnerJson, description || null, JSON.stringify(checklist), projectId, ref, extUrl, actor, parentId, JSON.stringify(tags), start || null, nextRequirementSeq(db, networkId)],
+    ));
   } catch {
     // 并发的同一个 external_ref / client_id:唯一索引挡住了第二个,回已有的那条。
     if (ref) {
@@ -597,7 +631,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"];
+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);
   const has = (k: string) => Object.prototype.hasOwnProperty.call(body, k);
@@ -628,6 +662,13 @@ function patchRequirement(ctx: RequirementsRequestContext, row: Row, body: Recor
     if (next === null) return jsonError("invalid_due", 400);
     due = next;
   }
+  let start = row.start_on || "";
+  if (has("start")) {
+    if (typeof body.start !== "string") return jsonError("invalid_start", 400);
+    const next = normalizeDue(body.start);
+    if (next === null) return jsonError("invalid_start", 400);
+    start = next;
+  }
   let assignee = row.assignee || "";
   if (has("assignee")) {
     if (typeof body.assignee !== "string") return jsonError("invalid_assignee", 400);
@@ -673,10 +714,10 @@ function patchRequirement(ctx: RequirementsRequestContext, row: Row, body: Recor
   const updatedAt = new Date().toISOString();
   db.run(
     `UPDATE requirements SET column_name = ?1, updated_at = ?2, title = ?7, priority = ?8, due_on = ?9, assignee = ?10, owner_json = ?4, participants_json = ?5, issues_json = ?6,
-       agent_owner_json = ?11, description = ?12, checklist_json = ?13, project_id = ?14, external_ref = ?15, external_url = ?16, archived = ?17, updated_by_json = ?18, parent_id = ?19, tags_json = ?20
+       agent_owner_json = ?11, description = ?12, checklist_json = ?13, project_id = ?14, external_ref = ?15, external_url = ?16, archived = ?17, updated_by_json = ?18, parent_id = ?19, tags_json = ?20, start_on = ?21
      WHERE requirement_id = ?3`,
     [has("column") ? body.column : row.column_name, updatedAt, row.requirement_id, people.ownerJson, people.participantsJson, has("issues") ? JSON.stringify(issues) : row.issues_json, name, priority, due || null, assignee, people.agentOwnerJson,
-      has("description") ? (description || null) : row.description, has("checklist") ? JSON.stringify(checklist) : row.checklist_json, projectId, ref, extUrl, archived, JSON.stringify(actorOf(ctx)), parentId, has("tags") ? JSON.stringify(tags) : row.tags_json],
+      has("description") ? (description || null) : row.description, has("checklist") ? JSON.stringify(checklist) : row.checklist_json, projectId, ref, extUrl, archived, JSON.stringify(actorOf(ctx)), parentId, has("tags") ? JSON.stringify(tags) : row.tags_json, start || null],
   );
   const updated = db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE requirement_id = ?1`, row.requirement_id)!;
   return Response.json(withLegacyOwner(toPublicFor(ctx, updated), people.coerced));
@@ -692,14 +733,30 @@ function withLegacyOwner(requirement: ReturnType<typeof toPublic>, coerced: Pers
   return { ok: true, requirement: { ...requirement, owner: coerced }, owner_coerced_to_agent_owner: true };
 }
 
-function scopedRow(ctx: RequirementsRequestContext, id: string): Row | undefined {
-  const params: unknown[] = [id];
-  let sql = `SELECT ${SELECT} FROM requirements WHERE requirement_id = ?1`;
+/** 「#123」→ 123;别的形状(包括裸数字)→ null,仍按 requirement_id 查。 */
+export function seqFromId(id: string): number | null {
+  const m = /^#([1-9]\d{0,14})$/.exec(id.trim());
+  return m ? Number(m[1]) : null;
+}
+
+/**
+ * 按 id 或「#N」找调用者作用域里的那张卡。短号只在一个网络里唯一:作用域跨多个网络、又各有一张 #N 时
+ * 不猜,回 409 ambiguous_seq(带 ?network_id= 再查)。
+ */
+function scopedRow(ctx: RequirementsRequestContext, id: string): Row | Response {
+  const seq = seqFromId(id);
+  const params: unknown[] = [seq ?? id];
+  let sql = `SELECT ${SELECT} FROM requirements WHERE ${seq === null ? "requirement_id" : "seq"} = ?1`;
   sql = addHumanNetworkScope(sql, params, ctx.scope);
-  return db.get<Row>(sql, ...params) ?? undefined;
+  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 rows[0] ?? jsonError("requirement_not_found", 404);
 }
 
-/** GET 的筛选(同步方 / MCP 用):status、project_id、owner / agent_owner(kind:id)、updated_since、external_ref、parent_id / top_level、include_archived。 */
+/** GET 的筛选(同步方 / MCP 用):seq(短号)、status、project_id、owner / agent_owner(kind:id)、updated_since、external_ref、parent_id / top_level、include_archived。 */
 function listFilters(url: URL, sql: string, params: unknown[], ctx?: RequirementsRequestContext): string | Response {
   const q = url.searchParams;
   const status = q.get("status");
@@ -725,6 +782,11 @@ function listFilters(url: URL, sql: string, params: unknown[], ctx?: Requirement
     if (!Number.isFinite(ms)) return jsonError("invalid_updated_since", 400);
     sql += ` AND updated_at >= ?${params.push(new Date(ms).toISOString())}`;
   }
+  const seq = q.get("seq");
+  if (seq !== null) {
+    if (!/^[1-9]\d{0,14}$/.test(seq)) return jsonError("invalid_seq", 400);
+    sql += ` AND seq = ?${params.push(Number(seq))}`;
+  }
   const ref = q.get("external_ref");
   if (ref !== null) sql += ` AND external_ref = ?${params.push(ref)}`;
   const parent = q.get("parent_id");
@@ -736,6 +798,55 @@ function listFilters(url: URL, sql: string, params: unknown[], ctx?: Requirement
   return sql;
 }
 
+const LIST_ORDER = " ORDER BY created_at DESC, requirement_id DESC";
+type LightRow = { requirement_id: string; seq?: number | null; network_id: string; created_at: string; title: string; description: string | null; assignee: string | null; tags_json: string | null; project_id: string | null; owner_json: string | null; agent_owner_json: string | null; participants_json: string | null };
+const parseRef = (json: string | null) => { try { return json ? JSON.parse(json) : null; } catch { return null; } };
+
+/**
+ * 列表的一页(from = listFilters 拼好的「FROM requirements WHERE …」)。没有搜索词:SQL 直接 LIMIT。有搜索词:先按同样的筛选 + 顺序读轻量列(不算子需求计数),
+ * 在这里逐行匹配,凑够 limit + 1 张就停,再按 id 读这一页的完整行。
+ */
+function listPage(ctx: RequirementsRequestContext, from: string, baseParams: unknown[], lq: ListQuery): { rows: Row[]; hasMore: boolean; nextCursor: string | null } {
+  const params = [...baseParams];
+  let where = from;
+  if (lq.cursor) {
+    const a = params.push(lq.cursor.createdAt), b = params.push(lq.cursor.id);
+    where += ` AND (created_at < ?${a} OR (created_at = ?${a} AND requirement_id < ?${b}))`;
+  }
+  let rows: Row[];
+  if (!lq.terms.length) {
+    rows = db.all<Row>(`SELECT ${SELECT} ${where}${LIST_ORDER} LIMIT ${lq.limit + 1}`, ...params);
+  } else {
+    // seq(任务短号,#2139):启动迁移 ensureRequirementSeq 在 SQLite / PostgreSQL 上都加这一列,SELECT 本来就带它。
+    const light = db.all<LightRow>(`SELECT requirement_id, seq, network_id, created_at, title, description, assignee, tags_json, project_id, owner_json, agent_owner_json, participants_json ${where}${LIST_ORDER}`, ...params);
+    const maps = new Map<string, NameMaps>();
+    const hits: string[] = [];
+    for (const r of light) {
+      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);
+      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]) : []);
+    rows = hits.map(id => byId.get(id)).filter((r): r is Row => !!r);
+  }
+  const hasMore = rows.length > lq.limit;
+  if (hasMore) rows = rows.slice(0, lq.limit);
+  const last = rows[rows.length - 1];
+  return { rows, hasMore, nextCursor: hasMore && last ? encodeCursor({ createdAt: last.created_at, id: last.requirement_id }) : null };
+}
+
+/** 搜索用的名字表(与 GET /api/requirements/people 同一个显示名规则);调用者看不见的节点不放进来。 */
+function searchNameMaps(ctx: RequirementsRequestContext, networkId: string): NameMaps {
+  const hidden = hiddenNodeFilter(ctx, networkId);
+  const people = new Map<string, string>();
+  for (const u of db.all<{ id: string; name: string }>("SELECT u.user_id AS id, COALESCE(NULLIF(u.display_name,''), u.username) AS name FROM network_members m JOIN users u ON u.user_id=m.user_id WHERE m.network_id=?1", networkId)) people.set(`user:${u.id}`, u.name);
+  for (const n of db.all<{ id: string; name: string }>("SELECT node_id AS id, COALESCE(NULLIF(display_name,''), NULLIF(alias,''), node_name) AS name FROM nodes WHERE network_id=?1", networkId)) if (!hidden?.(n.id)) people.set(`node:${n.id}`, n.name);
+  const projects = new Map(db.all<{ project_id: string; name: string }>("SELECT project_id, name FROM requirement_projects WHERE network_id=?1", networkId).map(p => [p.project_id, p.name] as const));
+  return { people, projects };
+}
+
 /** 这个节点对调用者在他作用域内的某个受限网络里是否隐藏。 */
 function hiddenFilterForScope(ctx: RequirementsRequestContext, nodeId: string): boolean {
   const restricted = ctx.scope.agentRestriction?.networkIds ?? [];
@@ -778,13 +889,18 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
 
   if (url.pathname === "/api/requirements" && req.method === "GET") {
     const params: unknown[] = [];
-    let sql = `SELECT ${SELECT} FROM requirements WHERE 1=1`;
+    // 只拼 FROM … WHERE:同一组条件既用来读整行,也用来(搜索时)先读轻量列。
+    let sql = "FROM requirements WHERE 1=1";
     sql = addHumanNetworkScope(sql, params, ctx.scope);
     const filtered = listFilters(url, sql, params, ctx);
     if (typeof filtered !== "string") return filtered;
-    const rows = db.all<Row>(`${filtered} ORDER BY created_at DESC LIMIT 500`, ...params).map(row => toPublicFor(ctx, row));
+    // q= / limit / cursor(requirements-search.ts)。都不带 = 旧行为:最新 500 张、同样的顺序。
+    const lq = parseListQuery(url.searchParams);
+    if ("error" in lq) return jsonError(lq.error, 400);
+    const page = listPage(ctx, filtered, params, lq);
     // capabilities:客户端按这个决定显示哪些功能(预计完成能不能带时刻、有没有项目…),不用靠猜字段。
-    return Response.json({ ok: true, requirements: rows, capabilities: REQUIREMENT_CAPABILITIES });
+    // has_more / next_cursor:后面还有没有(带 cursor=next_cursor 再读一页)。旧客户端不认识,忽略即可。
+    return conditionalJson(ctx.req, { ok: true, requirements: page.rows.map(row => toPublicFor(ctx, row)), capabilities: REQUIREMENT_CAPABILITIES, has_more: page.hasMore, next_cursor: page.nextCursor });
   }
 
   if (url.pathname === "/api/requirements" && req.method === "POST") {
@@ -825,7 +941,7 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
     try { body = await bodyObject(req); } catch { return jsonError("invalid_json", 400); }
     if (typeof body.done !== "boolean") return jsonError("invalid_done", 400);
     const row = scopedRow(ctx, decodeURIComponent(itemMatch[1]));
-    if (!row) return jsonError("requirement_not_found", 404);
+    if (row instanceof Response) return row;
     if (!canWrite(ctx, row.network_id)) return jsonError("permission_denied", 403);
     // 读-改-写在同一个同步段里完成(中间没有 await),同一进程里的两次勾选不会交错。
     const items = storedChecklist(row.checklist_json);
@@ -843,12 +959,12 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
   const id = decodeURIComponent(match[1]);
   if (req.method === "GET") {
     const row = scopedRow(ctx, id);
-    return row ? Response.json({ ok: true, requirement: toPublicFor(ctx, row) }) : jsonError("requirement_not_found", 404);
+    return row instanceof Response ? row : Response.json({ ok: true, requirement: toPublicFor(ctx, row) });
   }
   if (req.method === "DELETE") {
     // 删除只给人(节点令牌在入口已被拒):Agent 用 archived 归档。
     const row = scopedRow(ctx, id);
-    if (!row) return jsonError("requirement_not_found", 404);
+    if (row instanceof Response) return row;
     if (!canWrite(ctx, row.network_id)) return jsonError("permission_denied", 403);
     // 子需求不跟着删:先解挂(变成顶层),再删父卡。
     db.run("UPDATE requirements SET parent_id = NULL WHERE parent_id = ?1", [row.requirement_id]);
@@ -860,6 +976,6 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
   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);
   const row = scopedRow(ctx, id);
-  if (!row) return jsonError("requirement_not_found", 404);
+  if (row instanceof Response) return row;
   return patchRequirement(ctx, row, body);
 }

package/src/retention.ts

@@ -197,10 +197,13 @@ export function sweepRetention(cfg: RetentionConfig = readRetentionConfig()): Sw
   //     DBs must run a one-time blocking `VACUUM` themselves (out of
   //     scope for the sweeper, which deliberately stays non-
   //     blocking).
+  //   Both are SQLite PRAGMAs; on PostgreSQL autovacuum does this job and
+  //   the two counters stay null (RFC-039 S3).
   let walCheckpointPagesMoved: number | null = null;
   let incrementalFreedPages: number | null = null;
   let errored = false;
-  try {
+  const sqliteVacuum = db.dialect === "sqlite";
+  if (sqliteVacuum) try {
     // wal_checkpoint(TRUNCATE) returns a row { busy, log, checkpointed }.
     // We expose `log` (page count moved into the main DB) for ops visibility.
     const checkpoint = db.get<{ busy: number; log: number; checkpointed: number }>(
@@ -211,7 +214,7 @@ export function sweepRetention(cfg: RetentionConfig = readRetentionConfig()): Sw
     console.log(`[commhub retention] wal_checkpoint failed: ${e?.message ?? e}`);
     errored = true;
   }
-  try {
+  if (sqliteVacuum) try {
     // incremental_vacuum is a no-op on databases not created with
     // PRAGMA auto_vacuum = INCREMENTAL. For existing prod DBs that
     // weren't, the operator would have to run a full one-time VACUUM

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

@@ -1,14 +1,15 @@
-import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { tmpdir } from "node:os";
 import { addNetworkMember, createNetworkTokenForNode, register } from "./auth.js";
 import { db } from "./db.js";
 import { assertScheduledTaskBackendSupported, nextOccurrence, runDueScheduledTasks } from "./scheduled-tasks.js";
 
 const dir = mkdtempSync(join(tmpdir(), "anet-scheduler-"));
-const activeDbPath = process.env.COMMHUB_DB;
-if (!activeDbPath) throw new Error("test601 requires COMMHUB_DB before module import");
+const activeDbPath = process.env.COMMHUB_DB ?? (process.env.COMMHUB_TEST_PG_URL ? "postgres" : undefined);
+if (!activeDbPath) throw new Error("test601 requires COMMHUB_DB (or COMMHUB_TEST_PG_URL) before module import");
 let server: any;
 let base = "";
 let ownerToken = "";
@@ -26,6 +27,31 @@ async function api(token: string, path: string, init?: RequestInit) {
   return { status: res.status, body: await res.json() as any };
 }
 
+// #2135 —— 每条测试自己建它要断言的数据:不读前面测试留下的 schedule / run 行,也不靠执行顺序。
+// 单跑任何一条(-t)、从 server/ 或仓根跑,结果都一样。
+async function createSchedule(name: string, extra: Record<string, unknown> = {}) {
+  const res = await api(ownerToken, "/api/scheduled-tasks", {
+    method: "POST",
+    body: JSON.stringify({
+      network_id: networkId,
+      name,
+      target_node_id: nodeId,
+      task: `${name} task`,
+      timezone: "UTC",
+      schedule: { type: "interval", every_seconds: 60 },
+      ...extra,
+    }),
+  });
+  expect(res.status).toBe(201);
+  return res.body.schedule as { schedule_id: string; revision: number; [key: string]: any };
+}
+
+/** Make exactly this schedule due at `at` (default: a minute ago). */
+function makeDue(scheduleId: string, at = new Date(Date.now() - 60_000).toISOString()): string {
+  db.run("UPDATE scheduled_tasks SET next_run_at = ?1 WHERE schedule_id = ?2", [at, scheduleId]);
+  return at;
+}
+
 // 30s 而不是 bun 默认的 5s:这个 hook 跑 register()(KDF)+bootServer(),
 // 本机空载基线 ~620ms,而 2026-08-17 与 2026-08-31 两次 CI 上它被 5s 上限打死
 // (0 pass / 1 fail / Ran 1 test —— 见 #928、#1627)。5247ms 是**被截断的下界**,
@@ -66,8 +92,12 @@ afterAll(() => {
 });
 
 describe("Hub scheduled task API and dispatcher", () => {
-  let scheduleId = "";
-  let revision = 0;
+  // runDueScheduledTasks() sweeps every due schedule in the DB. Park whatever an earlier test
+  // left due (e.g. the race schedule when its workers could not start), so each test's
+  // processed counts only ever see the schedules it made due itself.
+  beforeEach(() => {
+    db.run("UPDATE scheduled_tasks SET next_run_at = ?1 WHERE next_run_at IS NOT NULL", [new Date(Date.now() + 24 * 3600_000).toISOString()]);
+  });
 
   test("schedule math supports timezone-aware daily and weekly forms", () => {
     const daily = nextOccurrence({ type: "daily", time: "09:30" }, "Asia/Shanghai", new Date("2026-08-09T02:00:00Z"));
@@ -90,16 +120,21 @@ describe("Hub scheduled task API and dispatcher", () => {
   });
 
   test("scheduler startup rejects a backend without real transactions", () => {
-    const original = db.dialect;
+    const original = db.atomicTransactions;
     try {
-      (db as any).dialect = "postgres";
+      (db as any).atomicTransactions = false;
       expect(() => assertScheduledTaskBackendSupported()).toThrow("scheduled_tasks_require_transactional_sqlite_backend");
     } finally {
-      (db as any).dialect = original;
+      (db as any).atomicTransactions = original;
     }
     expect(() => assertScheduledTaskBackendSupported()).not.toThrow();
-    const misfireColumn = db.all<any>("PRAGMA table_info(scheduled_tasks)").find((column: any) => column.name === "misfire_policy");
-    expect(misfireColumn?.dflt_value).toBe("'catch_up_once'");
+    if (db.dialect === "sqlite") {
+      const misfireColumn = db.all<any>("PRAGMA table_info(scheduled_tasks)").find((column: any) => column.name === "misfire_policy");
+      expect(misfireColumn?.dflt_value).toBe("'catch_up_once'");
+    } else {
+      const misfireColumn = db.get<any>("SELECT column_default FROM information_schema.columns WHERE table_name = 'scheduled_tasks' AND column_name = 'misfire_policy'");
+      expect(misfireColumn?.column_default).toBe("'catch_up_once'::text");
+    }
   });
 
   test("owner creates; viewer and node token cannot mutate", async () => {
@@ -130,11 +165,10 @@ describe("Hub scheduled task API and dispatcher", () => {
     expect(created.body.schedule.misfire_policy).toBe("catch_up_once");
     expect(created.body.schedule.created_by).toBeUndefined();
     expect(created.body.schedule.schedule_json).toBeUndefined();
-    scheduleId = created.body.schedule.schedule_id;
-    revision = created.body.schedule.revision;
   });
 
   test("network scope hides schedules from foreign users and viewers may read", async () => {
+    const scheduleId = (await createSchedule("Scope probe")).schedule_id;
     const visible = await api(viewerToken, `/api/scheduled-tasks?network_id=${encodeURIComponent(networkId)}`);
     expect(visible.status).toBe(200);
     expect(visible.body.schedules.map((x: any) => x.schedule_id)).toContain(scheduleId);
@@ -145,9 +179,9 @@ describe("Hub scheduled task API and dispatcher", () => {
     expect(hidden.status).toBe(403);
   });
 
-  test("due occurrence creates ordinary inbox/task/run atomically and is idempotent", () => {
-    const due = new Date(Date.now() - 120_000).toISOString();
-    db.run("UPDATE scheduled_tasks SET next_run_at = ?1 WHERE schedule_id = ?2", [due, scheduleId]);
+  test("due occurrence creates ordinary inbox/task/run atomically and is idempotent", async () => {
+    const scheduleId = (await createSchedule("Due occurrence probe")).schedule_id;
+    makeDue(scheduleId, new Date(Date.now() - 120_000).toISOString());
     expect(runDueScheduledTasks().processed).toBe(1);
     const run = db.get<any>("SELECT * FROM scheduled_task_runs WHERE schedule_id = ?1 ORDER BY created_at DESC LIMIT 1", scheduleId)!;
     expect(["delivered", "queued"]).toContain(run.status);
@@ -254,10 +288,17 @@ describe("Hub scheduled task API and dispatcher", () => {
     // Test-only fault injection at the second durable write. The inbox row has
     // already been attempted when this aborts, so any missing transaction
     // boundary leaves an observable half-state.
-    db.run(`CREATE TRIGGER test601_abort_scheduled_task_insert
-      BEFORE INSERT ON tasks
-      WHEN NEW.meta_json LIKE '%${atomicScheduleId}%'
-      BEGIN SELECT RAISE(ABORT, 'test601_injected_task_failure'); END`);
+    if (db.dialect === "sqlite") {
+      db.run(`CREATE TRIGGER test601_abort_scheduled_task_insert
+        BEFORE INSERT ON tasks
+        WHEN NEW.meta_json LIKE '%${atomicScheduleId}%'
+        BEGIN SELECT RAISE(ABORT, 'test601_injected_task_failure'); END`);
+    } else {
+      db.exec(`CREATE FUNCTION test601_abort_scheduled_task_insert() RETURNS trigger AS $$
+        BEGIN RAISE EXCEPTION 'test601_injected_task_failure'; END; $$ LANGUAGE plpgsql;
+        CREATE TRIGGER test601_abort_scheduled_task_insert BEFORE INSERT ON tasks FOR EACH ROW
+        WHEN (NEW.meta_json LIKE '%${atomicScheduleId}%') EXECUTE FUNCTION test601_abort_scheduled_task_insert()`);
+    }
     const failed = runDueScheduledTasks();
     expect(failed.failed).toBe(1);
     expect(db.get("SELECT run_id FROM scheduled_task_runs WHERE schedule_id = ?1", atomicScheduleId)).toBeNull();
@@ -265,7 +306,8 @@ describe("Hub scheduled task API and dispatcher", () => {
     expect(db.get("SELECT task_id FROM tasks WHERE meta_json LIKE '%' || ?1 || '%'", atomicScheduleId)).toBeNull();
     expect(db.get<{ next_run_at: string }>("SELECT next_run_at FROM scheduled_tasks WHERE schedule_id = ?1", atomicScheduleId)!.next_run_at).toBe(due);
 
-    db.run("DROP TRIGGER test601_abort_scheduled_task_insert");
+    if (db.dialect === "sqlite") db.run("DROP TRIGGER test601_abort_scheduled_task_insert");
+    else db.exec("DROP TRIGGER test601_abort_scheduled_task_insert ON tasks; DROP FUNCTION test601_abort_scheduled_task_insert()");
     expect(runDueScheduledTasks().processed).toBe(1);
     expect(db.get("SELECT task_id FROM scheduled_task_runs WHERE schedule_id = ?1", atomicScheduleId)).toBeTruthy();
   });
@@ -289,11 +331,14 @@ describe("Hub scheduled task API and dispatcher", () => {
 
     const raceDir = mkdtempSync(join(dir, "race-"));
     const gate = join(raceDir, "go");
-    const workerPath = "tests/test601-hub-scheduled-tasks/race-worker.ts";
+    // Resolved from this file, not from the current directory (#2135): `bun test` from server/
+    // used to look for tests/… under server/ and never start the workers.
+    const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+    const workerPath = join(repoRoot, "tests", "test601-hub-scheduled-tasks", "race-worker.ts");
     const dbPath = activeDbPath;
     const spawnWorker = (id: string) => Bun.spawn(
       ["bun", workerPath, dbPath, raceScheduleId, due, join(raceDir, `ready-${id}`), gate],
-      { cwd: process.cwd(), stdout: "pipe", stderr: "pipe", env: { ...process.env, COMMHUB_DB: dbPath } },
+      { cwd: repoRoot, stdout: "pipe", stderr: "pipe", env: { ...process.env, COMMHUB_DB: dbPath } },
     );
     const waitReady = async (id: string) => {
       const readyPath = join(raceDir, `ready-${id}`);
@@ -326,16 +371,23 @@ describe("Hub scheduled task API and dispatcher", () => {
     expect(db.get<{ count: number }>("SELECT COUNT(*) AS count FROM inbox WHERE meta_json LIKE '%' || ?1 || '%'", raceScheduleId)!.count).toBe(1);
   }, 20_000);
 
-  test("non-overlap skips while prior task is open; rename follows stable node_id", () => {
+  test("non-overlap skips while prior task is open; rename follows stable node_id", async () => {
+    // Its own node: the rename below must not change the node every other test targets.
+    const renameNodeId = `n_sched_rename_${Date.now()}`;
+    db.run("INSERT INTO nodes (node_id, node_name, alias, runtime, network_id) VALUES (?1, 'Rename Probe', 'scheduler-rename-probe', 'codex-sdk', ?2)", [renameNodeId, networkId]);
+    db.run("INSERT INTO sessions (resume_id, alias, status, node_id, network_id) VALUES (?1, 'scheduler-rename-probe', 'idle', ?2, ?3)", [`r_rename_${Date.now()}`, renameNodeId, networkId]);
+    const scheduleId = (await createSchedule("Non-overlap probe", { target_node_id: renameNodeId })).schedule_id;
+    makeDue(scheduleId, new Date(Date.now() - 90_000).toISOString());
+    expect(runDueScheduledTasks().processed).toBe(1);
     const firstTask = db.get<{ task_id: string }>("SELECT task_id FROM scheduled_task_runs WHERE schedule_id = ?1 AND task_id IS NOT NULL LIMIT 1", scheduleId)!.task_id;
-    const due2 = new Date(Date.now() - 60_000).toISOString();
-    db.run("UPDATE scheduled_tasks SET next_run_at = ?1 WHERE schedule_id = ?2", [due2, scheduleId]);
+
+    const due2 = makeDue(scheduleId);
     expect(runDueScheduledTasks().processed).toBe(1);
     expect(db.get<any>("SELECT status FROM scheduled_task_runs WHERE schedule_id = ?1 AND scheduled_for = ?2", scheduleId, due2)!.status).toBe("skipped");
 
     db.run("UPDATE tasks SET status = 'replied', completed_at = datetime('now') WHERE task_id = ?1", [firstTask]);
-    db.run("UPDATE nodes SET alias = 'scheduler-renamed' WHERE node_id = ?1 AND network_id = ?2", [nodeId, networkId]);
-    db.run("UPDATE sessions SET alias = 'scheduler-renamed' WHERE node_id = ?1 AND network_id = ?2", [nodeId, networkId]);
+    db.run("UPDATE nodes SET alias = 'scheduler-renamed' WHERE node_id = ?1 AND network_id = ?2", [renameNodeId, networkId]);
+    db.run("UPDATE sessions SET alias = 'scheduler-renamed' WHERE node_id = ?1 AND network_id = ?2", [renameNodeId, networkId]);
     const due3 = new Date(Date.now() - 30_000).toISOString();
     db.run("UPDATE scheduled_tasks SET next_run_at = ?1 WHERE schedule_id = ?2", [due3, scheduleId]);
     expect(runDueScheduledTasks().processed).toBe(1);
@@ -344,6 +396,7 @@ describe("Hub scheduled task API and dispatcher", () => {
   });
 
   test("full edit validates target and policy, preserves cadence, and recomputes through DST-safe schedule math", async () => {
+    const scheduleId = (await createSchedule("Daily briefing to edit", { priority: "high", timezone: "Asia/Shanghai" })).schedule_id;
     // Pin a recognizable future occurrence so a metadata-only edit can prove
     // that it does not silently reset the interval cadence.
     const pinnedNext = new Date(Date.now() + 45 * 60_000).toISOString();
@@ -413,6 +466,7 @@ describe("Hub scheduled task API and dispatcher", () => {
   });
 
   test("two editors with one revision produce one winner and one refreshable conflict", async () => {
+    const scheduleId = (await createSchedule("Two editors probe")).schedule_id;
     const current = (await api(ownerToken, `/api/scheduled-tasks/${scheduleId}?network_id=${encodeURIComponent(networkId)}`)).body.schedule;
     const [a, b] = await Promise.all([
       api(ownerToken, `/api/scheduled-tasks/${scheduleId}?network_id=${encodeURIComponent(networkId)}`, {
@@ -523,8 +577,18 @@ describe("Hub scheduled task API and dispatcher", () => {
   });
 
   test("optimistic revision, pause/resume, run-now and cancel preserve history", async () => {
+    const scheduleId = (await createSchedule("History probe")).schedule_id;
+    // Its own history before the lifecycle calls: a run, a skipped overlap, and a second run.
+    makeDue(scheduleId, new Date(Date.now() - 180_000).toISOString());
+    expect(runDueScheduledTasks().processed).toBe(1);
+    makeDue(scheduleId, new Date(Date.now() - 120_000).toISOString());
+    expect(runDueScheduledTasks().processed).toBe(1);
+    db.run("UPDATE tasks SET status='replied' WHERE task_id IN (SELECT task_id FROM scheduled_task_runs WHERE schedule_id=?1)", [scheduleId]);
+    makeDue(scheduleId);
+    expect(runDueScheduledTasks().processed).toBe(1);
+    expect(db.get<{ n: number }>("SELECT COUNT(*) AS n FROM scheduled_task_runs WHERE schedule_id = ?1", scheduleId)!.n).toBe(3);
     const latest = await api(ownerToken, `/api/scheduled-tasks/${scheduleId}?network_id=${encodeURIComponent(networkId)}`);
-    revision = latest.body.schedule.revision;
+    const revision = latest.body.schedule.revision;
     const stale = await api(ownerToken, `/api/scheduled-tasks/${scheduleId}?network_id=${encodeURIComponent(networkId)}`, { method: "PATCH", body: JSON.stringify({ revision: revision - 1, status: "paused" }) });
     expect(stale.status).toBe(409);
     const paused = await api(ownerToken, `/api/scheduled-tasks/${scheduleId}?network_id=${encodeURIComponent(networkId)}`, { method: "PATCH", body: JSON.stringify({ revision, status: "paused" }) });

package/src/scheduled-tasks.ts

@@ -57,8 +57,9 @@ const MISFIRE_POLICIES = new Set<MisfirePolicy>(["catch_up_once", "skip"]);
 export const MISFIRE_GRACE_MS = 60_000;
 
 export function assertScheduledTaskBackendSupported(): void {
-  if (db.dialect !== "sqlite") {
-    throw new Error("scheduled_tasks_require_transactional_sqlite_backend");
+  const refusal = db.transactionalFeaturesRefusal;
+  if (refusal !== null) {
+    throw new Error(`scheduled_tasks_require_transactional_sqlite_backend${refusal ? `: ${refusal}` : ""}`);
   }
 }