@sleep2agi/commhub-server 0.9.0-preview.71 → 0.9.0-preview.73

package/src/requirements.ts

@@ -1,11 +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 每多一行,文档里钉着的行号就漂一次。
@@ -13,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;
 
@@ -58,6 +60,7 @@ type Row = {
   issues_json: string | null;
   tags_json: string | null;
   created_at: string;
+  seq: number | null;
 };
 
 function jsonError(error: string, status: number): Response {
@@ -283,6 +286,8 @@ 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 || "",
@@ -357,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, start_on, " +
+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";
 
@@ -452,7 +457,8 @@ function ifNoneMatchHits(header: string | null, etag: string): boolean {
   return header.split(",").some(tag => tag.trim() === "*" || bare(tag) === bare(etag));
 }
 
-export const REQUIREMENT_CAPABILITIES = ["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements", "tags", "priority_lowest", "start_date"] as const;
+// 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 置空。
@@ -602,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, start_on)
-       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)`,
-      [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],
-    );
+       (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) {
@@ -726,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");
@@ -759,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");
@@ -770,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 ?? [];
@@ -812,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 conditionalJson(ctx.req, { 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") {
@@ -859,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);
@@ -877,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]);
@@ -894,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

@@ -8,8 +8,8 @@ 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 = "";
@@ -128,8 +128,13 @@ describe("Hub scheduled task API and dispatcher", () => {
       (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 () => {
@@ -283,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();
@@ -294,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();
   });

package/src/server.ts

@@ -10,7 +10,7 @@ import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/
 import { z } from "zod/v4";
 import { registerTools } from "./tools.js";
 import { db, logTaskEvent, logAudit, syncScheduledRunForTask } from "./db.js";
-import { createSSEStream, createNetworkObserverStream, createUserEventStream, pushEvent, pushNetworkObserverEvent, getSSEStats, PRINTABLE_OBSERVER_KEY_PREFIX, closeUserStreamsInNetwork } from "./push.js";
+import { createSSEStream, createNetworkObserverStream, createUserEventStream, pushEvent, pushNetworkObserverEvent, getSSEStats, PRINTABLE_OBSERVER_KEY_PREFIX, closeUserStreamsInNetwork, getUserPresence, onUserPresenceChange, pushUserEventToNetwork } from "./push.js";
 import { assertNodeActive } from "./lifecycle-guard.js";
 import { pendingInboxCount } from "./inbox-count.js";
 import { addAgentNetworkScope, addHumanNetworkScope, addNetworkScope, addOwnTrafficScope, canRestWriteNetwork, canRestWriteNetworkAsHuman, getUserNetworkIds, resolveRestNetworkScope, resolveRestWriteNetworkId, singleNetworkId, type RestNetworkScope } from "./network-scope.js";
@@ -238,6 +238,16 @@ function isTmuxAllowedIP(ip: string): boolean {
 function isNodeCredential(resolved: { networkId: string | null } | null | undefined): boolean {
   return !!resolved?.networkId;
 }
+// 人员列表的在线点:某人的第一条用户流连上 / 最后一条断开时,推给他所在每个网络里其他连着用户流的成员。
+// 收件人本来就是该网络成员(用户流入口按成员资格鉴权),与 GET /api/networks/:id/humans 同一可见范围。
+// 字段叫 member_user_id:pushUserEvent 会把 user_id 写成**收件人**自己。
+onUserPresenceChange((userId, online, lastSeenAt) => {
+  const nets = db.all<{ network_id: string }>("SELECT network_id FROM network_members WHERE user_id = ?1", userId);
+  for (const { network_id } of nets) {
+    pushUserEventToNetwork(network_id, { type: "member_presence", member_user_id: userId, online, last_seen_at: lastSeenAt }, userId);
+  }
+});
+
 function isHubAdminCredential(resolved: { networkId: string | null; user: { role: string } } | null | undefined): boolean {
   return !!resolved && !resolved.networkId && resolved.user.role === "admin";
 }
@@ -1606,7 +1616,11 @@ return Bun.serve({
       if (resolved.user.role !== "admin" && !getUserNetworkRole(resolved.user.user_id, netId)) {
         return withCors(req, Response.json({ ok: false, error: "not a member of this network" }, { status: 403 }));
       }
-      return withCors(req, Response.json({ ok: true, network_id: netId, humans: getNetworkHumans(netId) }));
+      const humans = getNetworkHumans(netId);
+      // 在线状态(online / last_seen_at)只给用户令牌:节点令牌拿到的仍是原来的身份字段,不多得任何东西。
+      if (isNodeCredential(resolved)) return withCors(req, Response.json({ ok: true, network_id: netId, humans }));
+      const presence = getUserPresence(humans.map((h) => h.user_id));
+      return withCors(req, Response.json({ ok: true, network_id: netId, humans: humans.map((h) => ({ ...h, ...presence.get(h.user_id)! })) }));
     }
 
     // ── V3.13: Network members + invites ──
@@ -3459,7 +3473,7 @@ return Bun.serve({
         db.run("DELETE FROM nodes WHERE node_id = ?1", [node.node_id]);
         if (node.alias) {
           db.run(
-            "DELETE FROM sessions WHERE alias = ?1 AND (network_id = ?2 OR (?2 IS NULL AND network_id IS NULL))",
+            "DELETE FROM sessions WHERE alias = ?1 AND (network_id = ?2 OR (CAST(?2 AS TEXT) IS NULL AND network_id IS NULL))",
             [node.alias, node.network_id ?? null]
           );
         }

package/src/side-thread-command-transport.test.ts

@@ -1,12 +1,22 @@
 import { describe, expect, test } from "bun:test";
 import { Database } from "bun:sqlite";
-import { SQLiteAdapter } from "./db-adapter";
+import { PgAdapter, SQLiteAdapter, resolveDatabaseTarget, type DbAdapter } from "./db-adapter";
 import { DurableSideThreadCommandPort, SideThreadCommandStore, handleSideThreadCommandRequest } from "./side-thread-command-transport";
 import { SideThreadCoordinator, SideThreadStore } from "./side-thread";
 
 function actor(tokenId = "tok-node") { return { tokenId, networkId: "net-1", nodeId: "node-1" }; }
+// RFC-039 S4: with COMMHUB_TEST_PG_URL (validated by the adapter guard) the
+// same tests run on PostgreSQL, each fixture on an emptied schema.
+function freshDb(): DbAdapter {
+  if (!process.env.COMMHUB_TEST_PG_URL) return new SQLiteAdapter(new Database(":memory:"));
+  const target = resolveDatabaseTarget();
+  if (target.kind !== "postgres") throw new Error("COMMHUB_TEST_PG_URL did not select PostgreSQL");
+  const pg = new PgAdapter(target.url);
+  pg.exec("DROP SCHEMA public CASCADE; CREATE SCHEMA public");
+  return pg;
+}
 function fixture() {
-  const db = new SQLiteAdapter(new Database(":memory:"));
+  const db = freshDb();
   db.exec("CREATE TABLE inbox(id TEXT PRIMARY KEY, content TEXT)");
   const store = new SideThreadCommandStore(db, () => 123);
   const port = new DurableSideThreadCommandPort({ store, networkForNode: (id) => id === "node-1" ? "net-1" : null,

package/src/side-thread.ts

@@ -450,6 +450,10 @@ export function installSideThreadSchema(database: DbAdapter): void {
     if (!/duplicate column|already exists/i.test(error?.message ?? ""))
       throw error;
   }
+  // RFC-039 F3: operations are listed in insertion order via SQLite's
+  // implicit rowid; PostgreSQL needs a real column for that.
+  if (database.dialect === "postgres")
+    database.exec("ALTER TABLE side_chat_operations ADD COLUMN IF NOT EXISTS rowid BIGSERIAL");
 }
 
 type SideChatRow = {

package/src/skillhub-http.test.ts

@@ -84,6 +84,22 @@ describe("SkillHub real Hub + SQLite", () => {
     expect(detail.created_by_user).toBeUndefined(); expect(detail.reviewed_by_user).toBeUndefined(); expect(detail.content_hash).toBeUndefined();
   });
 
+  test("query matches regardless of letter case (SQLite LIKE semantics, kept on PostgreSQL)", async () => {
+    for (const query of ["incident", "INCIDENT", "Handoff"]) {
+      const found = await tool(nodeToken, "list_skills", { network_id: networkId, query });
+      expect(found.skills.map((x: any) => x.skill_id)).toContain(skillId);
+    }
+    expect((await tool(nodeToken, "list_skills", { network_id: networkId, query: "no-such-skill" })).skills).toHaveLength(0);
+  });
+
+  test("% and _ in the query are literal characters, not wildcards (#2141)", async () => {
+    const ids = async (query: string) => (await tool(nodeToken, "list_skills", { network_id: networkId, query })).skills.map((x: any) => x.skill_id);
+    expect(await ids("_")).not.toContain(skillId);       // was: matched everything
+    expect(await ids("%")).not.toContain(skillId);
+    expect(await ids("incident_handoff")).not.toContain(skillId); // `_` must not stand for the "-" in the slug
+    expect(await ids("incident-handoff")).toContain(skillId);
+  });
+
   test("foreign user cannot read or review another network", async () => {
     expect((await tool(foreignToken, "list_skills", { network_id: networkId })).ok).toBe(false);
     const review = await tool(foreignToken, "review_skill", { network_id: networkId, skill_id: skillId, decision: "rejected" });

package/src/sqlite-close-checkpoint.test.ts

@@ -0,0 +1,78 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { copyFileSync, existsSync, mkdtempSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { SQLiteAdapter } from "./db-adapter";
+
+// #2151 — a cleanly stopped Hub must leave a complete .db: the -wal is absent
+// or empty, and a copy of the .db file alone still has the data.
+const dir = mkdtempSync(join(tmpdir(), "anet-wal-close-"));
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+const walBytes = (db: string) => (existsSync(`${db}-wal`) ? statSync(`${db}-wal`).size : 0);
+
+function copyOnlyDb(db: string): Database {
+  const copy = join(dirname(db), `copy-of-${db.split("/").pop()}`);
+  copyFileSync(db, copy); // deliberately without -wal / -shm
+  return new Database(copy, { readonly: true });
+}
+
+describe("#2151 SQLite WAL is checkpointed on close", () => {
+  test("SQLiteAdapter.close() after >20 distinct statements leaves a complete .db", () => {
+    const path = join(dir, "adapter.db");
+    const raw = new Database(path);
+    raw.exec("PRAGMA journal_mode=WAL");
+    const db = new SQLiteAdapter(raw);
+    db.exec("CREATE TABLE t (x TEXT)");
+    db.run("INSERT INTO t VALUES (?1)", ["kept"]);
+    // bun:sqlite stops being able to close after more than 20 distinct query() strings.
+    for (let i = 0; i < 30; i++) db.get(`SELECT ${i} AS v`);
+    db.close();
+    expect(walBytes(path)).toBe(0);
+    const copy = copyOnlyDb(path);
+    expect(copy.query("SELECT x FROM t").all()).toEqual([{ x: "kept" }]);
+    copy.close();
+  });
+
+  test("a real Hub that served traffic and got SIGTERM leaves a complete .db", async () => {
+    const bin = join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "commhub.ts");
+    const home = join(dir, "home");
+    const path = join(dir, "hub.db");
+    const port = String(27000 + Math.floor(Math.random() * 2000));
+    const base = `http://127.0.0.1:${port}`;
+    const hub = Bun.spawn(["bun", bin, "--port", port, "--host", "127.0.0.1", "--db", path], {
+      env: { PATH: process.env.PATH ?? "", HOME: home }, stdout: "pipe", stderr: "pipe",
+    });
+    try {
+      let up = false;
+      for (let i = 0; i < 150 && !up; i++) {
+        up = await fetch(`${base}/health`).then((r) => r.ok, () => false);
+        if (!up) await Bun.sleep(100);
+      }
+      expect(up).toBe(true);
+      const post = (p: string, body: unknown, token?: string) => fetch(`${base}${p}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+        body: JSON.stringify(body),
+      }).then((r) => r.json() as Promise<any>);
+      const reg = await post("/api/auth/register", { username: "walcheck", password: "StrongPassw0rd" });
+      expect(reg.ok).toBe(true);
+      const login = await post("/api/auth/login", { username: "walcheck", password: "StrongPassw0rd" });
+      const net = await post("/api/networks", { name: "wal-net" }, login.token);
+      expect(net.ok).toBe(true);
+      const ntok = await post("/api/auth/node-token", { network_id: net.network_id, node_name: "wal-agent" }, login.token);
+      expect(ntok.ok).toBe(true);
+      expect(walBytes(path)).toBeGreaterThan(0); // the writes really are in the WAL before the stop
+    } finally {
+      hub.kill("SIGTERM");
+      await hub.exited;
+    }
+    expect(walBytes(path)).toBe(0);
+    const copy = copyOnlyDb(path);
+    expect(copy.query("SELECT COUNT(*) AS n FROM users WHERE username = 'walcheck'").get()).toEqual({ n: 1 });
+    expect(copy.query("SELECT COUNT(*) AS n FROM networks WHERE network_name = 'wal-net'").get()).toEqual({ n: 1 });
+    copy.close();
+  }, 40_000);
+});

package/src/tools.ts

@@ -357,8 +357,9 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
                    FROM skillhub_skills WHERE network_id = ?1`;
       if (!showPending) sql += ` AND status = 'published'`;
       if (query?.trim()) {
-        params.push(`%${query.trim()}%`);
-        sql += ` AND (slug LIKE ?${params.length} OR name LIKE ?${params.length} OR description LIKE ?${params.length})`;
+        params.push(`%${query.trim().replace(/[\\%_]/g, (c) => `\\${c}`)}%`); // #2141: the query is text, not a pattern
+        const like = db.dialect === "postgres" ? "ILIKE" : "LIKE"; // RFC-039 F6: SQLite LIKE ignores ASCII case; keep that on PG
+        sql += ` AND (slug ${like} ?${params.length} ESCAPE '\\' OR name ${like} ?${params.length} ESCAPE '\\' OR description ${like} ?${params.length} ESCAPE '\\')`;
       }
       sql += ` ORDER BY updated_at DESC LIMIT ${limit ?? 100}`;
       return skillHubReply({ ok: true, reviewer, skills: db.all(sql, ...params) });
@@ -5780,12 +5781,14 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   };
   const pick = (args: Record<string, unknown>, keys: string[]) => Object.fromEntries(keys.filter(k => args[k] !== undefined).map(k => [k, args[k]]));
   const REQ_WRITE_KEYS = [...Object.keys(reqFields), "external_ref", "archived"];
+  const REQ_ID_DESC = "requirement id (req_…) or its short number \"#N\" (e.g. \"#42\", per network; a user token that sees several networks must also pass network_id, else 409 ambiguous_seq)";
 
   server.tool(
     "requirements_list",
-    "List requirement tasks in your network. Filters: status (pool/doing/done), project_id ('none' = no project), owner / agent_owner ('user:<id>' / 'node:<id>' / 'none'), updated_since (ISO), external_ref, parent_id / top_level, include_archived. Newest first, max 500. Each task carries children {total, done}.",
+    "List requirement tasks in your network. Filters: seq (the per-network short number shown as #N), status (pool/doing/done), project_id ('none' = no project), owner / agent_owner ('user:<id>' / 'node:<id>' / 'none'), updated_since (ISO), external_ref, parent_id / top_level, include_archived; q = search title / description / owner, agent and participant names / project name / tags (space-separated terms are ANDed). Newest first, 500 per page by default (limit ≤ 1000); has_more + next_cursor → pass cursor for the next page. Each task carries children {total, done}.",
     {
       network_id: z.string().max(200).optional(),
+      seq: z.number().int().positive().optional().describe("short number (#N) of one task in this network"),
       status: z.enum(["pool", "doing", "done"]).optional(),
       project_id: z.string().max(200).optional(),
       owner: z.string().max(210).optional(),
@@ -5794,11 +5797,11 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       external_ref: z.string().max(200).optional(),
       include_archived: z.boolean().optional(),
       parent_id: z.string().max(200).optional().describe("children of this requirement ('none' = top level)"),
-      top_level: z.boolean().optional(),
+      top_level: z.boolean().optional(), q: z.string().max(200).optional(), limit: z.number().int().min(1).max(1000).optional(), cursor: z.string().max(600).optional(),
     },
     async (args) => {
       const q = new URLSearchParams();
-      for (const k of ["status", "project_id", "owner", "agent_owner", "updated_since", "external_ref", "parent_id"] as const) if (args[k] !== undefined) q.set(k, String(args[k]));
+      for (const k of ["seq", "status", "project_id", "owner", "agent_owner", "updated_since", "external_ref", "parent_id", "q", "limit", "cursor"] as const) if (args[k] !== undefined) q.set(k, String(args[k]));
       if (args.include_archived) q.set("include_archived", "1");
       if (args.top_level) q.set("top_level", "1");
       return requirementsCall("GET", `/api/requirements${q.size ? `?${q}` : ""}`, args.network_id);
@@ -5807,8 +5810,8 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "requirements_get",
-    "Get one requirement task by id (with description, checklist, owners, project, external_ref).",
-    { id: z.string().min(1).max(200), network_id: z.string().max(200).optional() },
+    "Get one requirement task by id or by its short number \"#N\" (with description, checklist, owners, project, external_ref, seq).",
+    { id: z.string().min(1).max(200).describe(REQ_ID_DESC), network_id: z.string().max(200).optional() },
     async ({ id, network_id }) => requirementsCall("GET", `/api/requirements/${encodeURIComponent(id)}`, network_id),
   );
 
@@ -5821,15 +5824,15 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "requirements_update",
-    "Patch a requirement task; omitted fields keep their value. archived=true hides it from the default list (agents cannot delete).",
-    { id: z.string().min(1).max(200), network_id: z.string().max(200).optional(), ...reqFields, external_ref: z.string().max(200).nullable().optional(), archived: z.boolean().optional() },
+    "Patch a requirement task (id or \"#N\"); omitted fields keep their value. archived=true hides it from the default list (agents cannot delete).",
+    { id: z.string().min(1).max(200).describe(REQ_ID_DESC), network_id: z.string().max(200).optional(), ...reqFields, external_ref: z.string().max(200).nullable().optional(), archived: z.boolean().optional() },
     async (args) => requirementsCall("PATCH", `/api/requirements/${encodeURIComponent(args.id)}`, args.network_id, pick(args, REQ_WRITE_KEYS)),
   );
 
   server.tool(
     "requirements_checklist_toggle",
     "Set one checklist item done / not done (only that item is written, so concurrent edits of other items are kept).",
-    { id: z.string().min(1).max(200), item_id: z.string().regex(/^[A-Za-z0-9_-]{1,40}$/), done: z.boolean(), network_id: z.string().max(200).optional() },
+    { id: z.string().min(1).max(200).describe(REQ_ID_DESC), item_id: z.string().regex(/^[A-Za-z0-9_-]{1,40}$/), done: z.boolean(), network_id: z.string().max(200).optional() },
     async ({ id, item_id, done, network_id }) => requirementsCall("PATCH", `/api/requirements/${encodeURIComponent(id)}/checklist/${encodeURIComponent(item_id)}`, network_id, { done }),
   );