@sleep2agi/commhub-server 0.9.0-preview.100 → 0.9.0-preview.102

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.100",
+  "version": "0.9.0-preview.102",
   "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and MCP tools (17 collaboration-core + node/provider ops tools; authoritative list: docs-site/docs/api/mcp-tools.md).",
   "type": "module",
   "main": "src/index.ts",

package/src/agent-groups-perf.test.ts

@@ -4,8 +4,10 @@
 // 场景:NET 里 300 个节点;50 个组,每组 6 个节点(合起来覆盖全部 300 个)。
 //   baseline —— bob 直接授权这 300 个节点(没有组);
 //   groups   —— alice 授权这 50 个组(没有直接授权),可见集合与 bob 完全相同。
-// 两人看到的 Agent 一样多,差值就是「按组展开」本身的代价(交替量 15 轮,取每轮差值的中位数)。团队要求 ≈2 ms 以内(本机实测 −0.5~+1.9 ms);
+// 两人看到的 Agent 一样多,差值就是「按组展开」本身的代价。团队要求 ≈2 ms 以内(本机实测 −0.5~+1.9 ms);
 // 断言放宽到 max(5 ms, 基线的 15%)—— CI 容器比本机慢时两边一起变慢,绝对差也跟着放大。数字打印出来。
+// #517:差值怎么量见 lowDelta*() —— 交替且每轮翻转先后、样本 40 对、比两边的 p20(不是每轮差值的中位数)、
+// 一轮超标再重量最多 2 轮。界限本身(max(5 ms, 15%))没动。
 
 import { describe, expect, test, beforeAll, afterAll } from "bun:test";
 import { mkdtempSync, rmSync } from "fs";
@@ -30,10 +32,11 @@ const PER_GROUP = NODES / GROUPS;
 const BOUND_MS = 5;
 const bound = (base: number) => Math.max(BOUND_MS, base * 0.15);
 // CI 容器里一次 visibleAgents() 约 65 ms(本机约 28 ms):原来 40 次 × 两边再加预热,顶破了 bun 默认的 5 s 单测超时(#2131 CI 实测)。
-// 15 次取中位数足够稳;性能用例另给显式超时。
+// 性能用例另给显式超时(差值守卫最坏 3 轮 × 40 对,见 lowDelta)。
 const WARMUP = 3;
-const ITER = 15;
 const PERF_TIMEOUT_MS = 60_000;
+// #517 差值守卫:每轮 DELTA_PAIRS 对、比两边的 LOW_P 分位、超标再量最多 RETRIES 轮。
+const DELTA_PAIRS = 40, LOW_P = 0.2, RETRIES = 2;
 
 const json = (token: string) => ({ Authorization: `Bearer ${token}`, "Content-Type": "application/json" });
 async function send(token: string, method: string, path: string, payload?: unknown) {
@@ -56,15 +59,46 @@ function pairedDelta(a: () => void, b: () => void, n: number): { a: number; b: n
   }
   return { a: median(as), b: median(bs), delta: median(ds) };
 }
-async function pairedDeltaAsync(a: () => Promise<void>, b: () => Promise<void>, n: number): Promise<{ a: number; b: number; delta: number }> {
-  for (let i = 0; i < WARMUP; i++) { await a(); await b(); }
-  const as: number[] = [], bs: number[] = [], ds: number[] = [];
-  for (let i = 0; i < n; i++) {
-    let t = performance.now(); await a(); const ta = performance.now() - t;
-    t = performance.now(); await b(); const tb = performance.now() - t;
-    as.push(ta); bs.push(tb); ds.push(tb - ta);
+const pct = (xs: number[], p: number) => { const s = [...xs].sort((a, b) => a - b); return s[Math.min(s.length - 1, Math.floor(p * s.length))]; };
+type LowDelta = { a: number; b: number; delta: number; aP50: number; bP50: number; ok: boolean };
+/**
+ * #517 —— 「组授权比直接授权多出多少」的稳健量法。旧做法(15 对、每轮固定先 A 后 B、取每轮差值中位数)在 test638
+ * 两份 aggregate 并发时红过(本地 2 核 + 忙循环邻居实测 paired-delta 7.34 ms > 5 ms,同一轮两边中位数差出 10 ms)——
+ * 量的是负载,不是组展开。现在:
+ *   - 每轮翻转先后(偶数轮 A→B,奇数轮 B→A),「第二个总吃前一个的 GC / 调度」这类顺序偏差两边对半分;
+ *   - 每边 DELTA_PAIRS 个样本,比两边各自的 LOW_P 分位:调度噪声只会加时间,低尾最接近真实成本;
+ *   - 一轮超标就整轮重量,最多 RETRIES 次;真回归(组路径每节点多查一次,#2133 那种 N+1)每一轮都超。
+ */
+function lowDelta(a: () => void, b: () => void, bound: (base: number) => number): LowDelta {
+  let r: LowDelta | null = null;
+  for (let attempt = 0; attempt <= RETRIES; attempt++) {
+    for (let i = 0; i < WARMUP; i++) { a(); b(); }
+    const as: number[] = [], bs: number[] = [];
+    for (let i = 0; i < DELTA_PAIRS; i++) {
+      const time = (f: () => void) => { const t = performance.now(); f(); return performance.now() - t; };
+      if (i % 2 === 0) { as.push(time(a)); bs.push(time(b)); } else { bs.push(time(b)); as.push(time(a)); }
+    }
+    const lowA = pct(as, LOW_P), lowB = pct(bs, LOW_P);
+    r = { a: lowA, b: lowB, delta: lowB - lowA, aP50: pct(as, 0.5), bP50: pct(bs, 0.5), ok: lowB - lowA <= bound(lowA) };
+    if (r.ok) return r;
   }
-  return { a: median(as), b: median(bs), delta: median(ds) };
+  return r!;
+}
+async function lowDeltaAsync(a: () => Promise<void>, b: () => Promise<void>, bound: (base: number) => number, label: string): Promise<LowDelta> {
+  let r: LowDelta | null = null;
+  for (let attempt = 0; attempt <= RETRIES; attempt++) {
+    for (let i = 0; i < WARMUP; i++) { await a(); await b(); }
+    const as: number[] = [], bs: number[] = [];
+    const time = async (f: () => Promise<void>) => { const t = performance.now(); await f(); return performance.now() - t; };
+    for (let i = 0; i < DELTA_PAIRS; i++) {
+      if (i % 2 === 0) { as.push(await time(a)); bs.push(await time(b)); } else { bs.push(await time(b)); as.push(await time(a)); }
+    }
+    const lowA = pct(as, LOW_P), lowB = pct(bs, LOW_P);
+    r = { a: lowA, b: lowB, delta: lowB - lowA, aP50: pct(as, 0.5), bP50: pct(bs, 0.5), ok: lowB - lowA <= bound(lowA) };
+    console.log(`[perf] ${label} pass ${attempt + 1}: p${LOW_P * 100} direct-300=${lowA.toFixed(2)}ms groups-50x6=${lowB.toFixed(2)}ms delta=${r.delta.toFixed(2)}ms bound=${bound(lowA).toFixed(2)}ms (p50 ${r.aP50.toFixed(2)} / ${r.bP50.toFixed(2)}) ${r.ok ? "ok" : "OVER"}`);
+    if (r.ok) return r;
+  }
+  return r!;
 }
 
 beforeAll(async () => {
@@ -123,8 +157,8 @@ describe("Agent 分组:性能守卫(50 组 × 300 节点)", () => {
   });
 
   test(`visibleAgents():组展开的额外开销 ≤ max(${BOUND_MS} ms, 基线 15%)(目标 ≈2 ms)`, () => {
-    const r = pairedDelta(() => { visibleAgents(bob.id, NET); }, () => { visibleAgents(alice.id, NET); }, ITER);
-    console.log(`[perf] visibleAgents median: direct-300=${r.a.toFixed(2)}ms groups-50x6=${r.b.toFixed(2)}ms paired-delta=${r.delta.toFixed(2)}ms bound=${bound(r.a).toFixed(2)}ms`);
+    const r = lowDelta(() => { visibleAgents(bob.id, NET); }, () => { visibleAgents(alice.id, NET); }, bound);
+    console.log(`[perf] visibleAgents p${LOW_P * 100}: direct-300=${r.a.toFixed(2)}ms groups-50x6=${r.b.toFixed(2)}ms delta=${r.delta.toFixed(2)}ms bound=${bound(r.a).toFixed(2)}ms (p50 ${r.aP50.toFixed(2)} / ${r.bP50.toFixed(2)})`);
     expect(r.delta).toBeLessThanOrEqual(bound(r.a));
   }, PERF_TIMEOUT_MS);
 
@@ -157,8 +191,7 @@ describe("Agent 分组:性能守卫(50 组 × 300 节点)", () => {
       const body = await r.json() as any;
       if ((body.sessions ?? []).length !== NODES) throw new Error(`expected ${NODES} sessions, got ${(body.sessions ?? []).length}`);
     };
-    const r = await pairedDeltaAsync(() => hit(bob.token), () => hit(alice.token), ITER);
-    console.log(`[perf] GET /api/status median: direct-300=${r.a.toFixed(2)}ms groups-50x6=${r.b.toFixed(2)}ms paired-delta=${r.delta.toFixed(2)}ms bound=${bound(r.a).toFixed(2)}ms`);
+    const r = await lowDeltaAsync(() => hit(bob.token), () => hit(alice.token), bound, "GET /api/status");
     expect(r.delta).toBeLessThanOrEqual(bound(r.a));
   }, PERF_TIMEOUT_MS);
 

package/src/db.ts

@@ -1596,6 +1596,12 @@ try { db.exec("ALTER TABLE scheduled_tasks ADD COLUMN misfire_policy TEXT NOT NU
 // whether the node had ever picked it up: not_received | in_progress.
 try { db.exec("ALTER TABLE scheduled_task_runs ADD COLUMN blocked_by_task_id TEXT"); } catch {}
 try { db.exec("ALTER TABLE scheduled_task_runs ADD COLUMN blocked_by_state TEXT"); } catch {}
+// #523 — consecutive-failure alert bookkeeping (scheduled-failures.ts). Additive and nullable:
+// an older Hub never reads them, so rolling back is safe. failure_alert_at = ISO time of the last
+// alert; failure_alert_key = the last successful run_id at that moment ('' = none yet), so a
+// success in between re-arms the alert.
+try { db.exec("ALTER TABLE scheduled_tasks ADD COLUMN failure_alert_at TEXT"); } catch {}
+try { db.exec("ALTER TABLE scheduled_tasks ADD COLUMN failure_alert_key TEXT"); } catch {}
 
 // RFC-036 / B4 — owner-authorized edits of node-host managed schedules.
 // This is intentionally separate from Hub scheduled_tasks: these rows are
@@ -1986,6 +1992,18 @@ export function chainReplyToParent(
 
 const SCHEDULED_RUN_TERMINAL_STATUSES = new Set(["replied", "failed", "cancelled", "expired"]);
 
+// #523 — called after a run row is closed by its task's terminal state. Registered by
+// scheduled-failures.ts (a hook, not an import: that module depends on db.ts). Never throws.
+type ScheduledRunTerminalHook = (scheduleId: string, status: string) => void;
+let scheduledRunTerminalHook: ScheduledRunTerminalHook | null = null;
+export function setScheduledRunTerminalHook(fn: ScheduledRunTerminalHook | null): void { scheduledRunTerminalHook = fn; }
+function fireScheduledRunTerminalHook(scheduleId: string, status: string): void {
+  if (!scheduledRunTerminalHook) return;
+  try { scheduledRunTerminalHook(scheduleId, status); } catch (e: any) {
+    console.error(`[scheduled-tasks] run terminal hook failed schedule=${scheduleId}: ${e?.message || e}`);
+  }
+}
+
 type ScheduledTaskLifecycleRow = {
   task_id: string;
   network_id: string | null;
@@ -2041,6 +2059,7 @@ export function syncScheduledRunForTask(taskId: string, expectedNetworkId?: stri
         WHERE run_id = ?4 AND task_id = ?5 AND network_id = ?6 AND schedule_id = ?7`,
       [task.status, errorCode, task.completed_at, binding.run_id, task.task_id, task.network_id, binding.schedule_id],
     );
+    if (updated.changes === 1) fireScheduledRunTerminalHook(binding.schedule_id, task.status);
     return { matched: updated.changes === 1, status: task.status };
   }
 

package/src/report-status-handover-capabilities-http.test.ts

@@ -0,0 +1,124 @@
+// #550 — the sticky session capability flags (rules_file_capable / skills_capable /
+// files_capable / logs_capable) survive a session handover.
+//
+// report_status for an alias that already has a row under ANOTHER resume_id takes
+// the DELETE + INSERT handover path. That path carried registered_at and the
+// descriptive columns, but not the capability flags, so the new row started at
+// the column default 0 — although the flags are meant to be sticky (only ever set
+// to 1). Board #548: a production node's MCP channel reconnected under a new
+// resume_id and the rules-file / skills / files / logs doorbells went dark.
+//
+// Pinned through the real HTTP entrance (POST /mcp with the node's own token):
+//   1. flags set on resume A are still 1 after the same alias reports resume B
+//      without them — and after it switches back to A.
+//   2. only flags that were 1 are carried; a 0 is never promoted.
+//   3. a later report omitting the flags on the same resume_id still keeps them.
+//   4. a user token cannot report for the alias, so it cannot hand the flags to a
+//      session of its own.
+//
+// 跑法:cd server && COMMHUB_DB=/tmp/x.db bun test src/report-status-handover-capabilities-http.test.ts
+//       PG:COMMHUB_TEST_PG_URL=… COMMHUB_PG_EXPERIMENTAL=1(tests/test2123-hub-postgres-ladder 里注册)
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { createNetworkTokenForNode, register } from "./auth.js";
+import { db } from "./db.js";
+
+const dir = mkdtempSync(join(tmpdir(), "anet-handover-caps-"));
+const activeDbPath = process.env.COMMHUB_DB ?? (process.env.COMMHUB_TEST_PG_URL ? "postgres" : undefined);
+if (!activeDbPath) throw new Error("report-status-handover-capabilities requires COMMHUB_DB (or COMMHUB_TEST_PG_URL) before module import");
+
+const stamp = Date.now();
+let server: any;
+let base = "";
+let ownerToken = "", ownerId = "", NET = "";
+type Node = { alias: string; nodeId: string; token: string };
+const nodes: Record<string, Node> = {};
+
+async function tool(token: string, name: string, args: Record<string, unknown>) {
+  const res = await fetch(`${base}/mcp`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-03-26" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }),
+  });
+  const raw = await res.text();
+  const data = raw.split("\n").filter((x) => x.startsWith("data:"));
+  const payload = data.length ? JSON.parse(data.at(-1)!.slice(5).trim()) : JSON.parse(raw);
+  const text = payload.result.content[0].text;
+  if (!text.startsWith("{")) throw new Error(`${name}: ${text}`);
+  return JSON.parse(text);
+}
+
+// resume_id is the sessions primary key — every alias below uses its own (cc-*-<nodeId>).
+const ALL_FLAGS = { rules_file_capable: true, skills_capable: true, files_capable: true, logs_capable: true };
+const report = (token: string, n: Node, resume: string, extra: Record<string, unknown> = {}) =>
+  tool(token, "report_status", { resume_id: resume, alias: n.alias, status: "idle", agent: "claude-code", network_id: NET, ...extra });
+
+type CapRow = { resume_id: string; rules_file_capable: number; skills_capable: number; files_capable: number; logs_capable: number };
+const capRows = (alias: string) =>
+  db.all<CapRow>(
+    "SELECT resume_id, rules_file_capable, skills_capable, files_capable, logs_capable FROM sessions WHERE alias = ?1 AND network_id = ?2",
+    alias, NET,
+  ).map((r) => ({
+    resume_id: r.resume_id,
+    rules_file_capable: Number(r.rules_file_capable), skills_capable: Number(r.skills_capable),
+    files_capable: Number(r.files_capable), logs_capable: Number(r.logs_capable),
+  }));
+
+beforeAll(async () => {
+  process.env.COMMHUB_UPLOADS_DIR = join(dir, "uploads");
+  process.env.HOST = "127.0.0.1";
+  const owner = register(`hcap_owner_${stamp}`, "HandoverCaps123!", undefined, "seed");
+  ownerToken = owner.token!; ownerId = owner.user!.user_id; NET = owner.network_id!;
+  for (const key of ["all", "some", "user"]) {
+    const alias = `hcap-${key}-${stamp}`;
+    const nodeId = `n_hcap_${key}_${stamp}`;
+    const minted = createNetworkTokenForNode(ownerId, NET, alias, nodeId);
+    expect(minted.ok).toBe(true);
+    nodes[key] = { alias, nodeId, token: minted.token! };
+  }
+  const mod: any = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { server?.stop?.(true); } catch {}
+  try { rmSync(dir, { recursive: true, force: true }); } catch {}
+});
+
+describe("#550 sticky capability flags survive a resume_id handover", () => {
+  test("all four flags carry to the new resume_id, and back again", async () => {
+    const n = nodes.all!;
+    expect((await report(n.token, n, `cc-a-${n.nodeId}`, ALL_FLAGS)).ok).toBe(true);
+    expect(capRows(n.alias)).toEqual([{ resume_id: `cc-a-${n.nodeId}`, rules_file_capable: 1, skills_capable: 1, files_capable: 1, logs_capable: 1 }]);
+
+    // The channel reconnects under a new resume_id and reports WITHOUT the flags.
+    expect((await report(n.token, n, `cc-b-${n.nodeId}`)).ok).toBe(true);
+    expect(capRows(n.alias)).toEqual([{ resume_id: `cc-b-${n.nodeId}`, rules_file_capable: 1, skills_capable: 1, files_capable: 1, logs_capable: 1 }]);
+
+    // Same resume_id, flags omitted again (status-only report) — still sticky.
+    expect((await report(n.token, n, `cc-b-${n.nodeId}`)).ok).toBe(true);
+    expect(capRows(n.alias)[0]).toMatchObject({ rules_file_capable: 1, skills_capable: 1, files_capable: 1, logs_capable: 1 });
+
+    // Two reporters taking turns (agent-node + TUI MCP): switching back keeps them too.
+    expect((await report(n.token, n, `cc-a-${n.nodeId}`)).ok).toBe(true);
+    expect(capRows(n.alias)).toEqual([{ resume_id: `cc-a-${n.nodeId}`, rules_file_capable: 1, skills_capable: 1, files_capable: 1, logs_capable: 1 }]);
+  }, 20_000);
+
+  test("only flags that were 1 are carried — a 0 is never promoted", async () => {
+    const n = nodes.some!;
+    expect((await report(n.token, n, `cc-a-${n.nodeId}`, { rules_file_capable: true, logs_capable: true })).ok).toBe(true);
+    expect((await report(n.token, n, `cc-b-${n.nodeId}`)).ok).toBe(true);
+    expect(capRows(n.alias)).toEqual([{ resume_id: `cc-b-${n.nodeId}`, rules_file_capable: 1, skills_capable: 0, files_capable: 0, logs_capable: 1 }]);
+  }, 20_000);
+
+  test("a user token cannot report for the alias, so it cannot take over the flags", async () => {
+    const n = nodes.user!;
+    expect((await report(n.token, n, `cc-a-${n.nodeId}`, ALL_FLAGS)).ok).toBe(true);
+    const r = await report(ownerToken, n, `cc-hijack-${n.nodeId}`);
+    expect(r.ok).toBe(false);
+    expect(capRows(n.alias)).toEqual([{ resume_id: `cc-a-${n.nodeId}`, rules_file_capable: 1, skills_capable: 1, files_capable: 1, logs_capable: 1 }]);
+  }, 20_000);
+});

package/src/requirement-due-reminders-http.test.ts

@@ -19,6 +19,9 @@ process.env.HOST = "127.0.0.1";
 delete process.env.COMMHUB_DUE_REMINDER_TZ;
 delete process.env.COMMHUB_DUE_OVERDUE_MAX_DAYS;
 delete process.env.COMMHUB_DUE_REMINDER_NETWORKS;
+delete process.env.COMMHUB_DUE_REMINDERS;
+delete process.env.COMMHUB_DUE_REMINDERS_NETWORKS;
+delete process.env.COMMHUB_DUE_REMINDERS_EXCLUDE_NETWORKS;
 // 节点提醒默认关;这个文件的大部分用例要看节点那一路,先打开(「默认关」单独一个用例)。
 process.env.COMMHUB_DUE_REMINDER_NODES = "1";
 const PW = "DueRemindPassw0rd!x";
@@ -335,6 +338,131 @@ describe("上线护栏", () => {
       expect(sentFor(due.runDueReminders({ now: T0 + 3600_000 }), old)).toEqual([]);
     } finally { delete process.env.COMMHUB_DUE_REMINDER_NETWORKS; }
   });
+
+  // ── #524 按网络开关 ────────────────────────────────────
+  const SCOPE_VARS = ["COMMHUB_DUE_REMINDERS", "COMMHUB_DUE_REMINDERS_NETWORKS", "COMMHUB_DUE_REMINDERS_EXCLUDE_NETWORKS", "COMMHUB_DUE_REMINDER_NETWORKS"];
+  async function withEnv<T>(vars: Record<string, string>, fn: () => T | Promise<T>): Promise<T> {
+    const saved = Object.fromEntries(SCOPE_VARS.map((k) => [k, process.env[k]]));
+    for (const k of SCOPE_VARS) delete process.env[k];
+    Object.assign(process.env, vars);
+    try { return await fn(); } finally {
+      for (const k of SCOPE_VARS) { if (saved[k] === undefined) delete process.env[k]; else process.env[k] = saved[k]!; }
+    }
+  }
+  const baselineCount = (net: string) => db.get("SELECT COUNT(*) AS n FROM requirement_due_reminders WHERE kind = 'baseline' AND network_id = ?1", net).n;
+  const rowCount = (id: string) => db.get("SELECT COUNT(*) AS n FROM requirement_due_reminders WHERE requirement_id = ?1", id).n;
+
+  test("#524 范围解析:各种组合 / 空白值 / 只绑本分支用到的参数", async () => {
+    const S = (vars: Record<string, string>) => withEnv(vars, () => due.dueReminderScope());
+    // 都不设 = 原样:所有网络
+    expect(await S({})).toEqual({ mode: "all", exclude: [] });
+    expect(await S({ COMMHUB_DUE_REMINDERS: "1" })).toEqual({ mode: "all", exclude: [] });
+    expect(await S({ COMMHUB_DUE_REMINDERS: "0" })).toEqual({ mode: "off" });
+    // 旧名白名单不能在 =0 时打开(行为不变)
+    expect(await S({ COMMHUB_DUE_REMINDERS: "0", COMMHUB_DUE_REMINDER_NETWORKS: "net_a" })).toEqual({ mode: "off" });
+    expect(await S({ COMMHUB_DUE_REMINDER_NETWORKS: "net_a" })).toEqual({ mode: "only", include: ["net_a"], exclude: [] });
+    // 新名白名单:=0 时也打开,只给名单里的
+    expect(await S({ COMMHUB_DUE_REMINDERS: "0", COMMHUB_DUE_REMINDERS_NETWORKS: " net_a , net_b,net_a, " })).toEqual({ mode: "only", include: ["net_a", "net_b"], exclude: [] });
+    expect(await S({ COMMHUB_DUE_REMINDERS: "1", COMMHUB_DUE_REMINDERS_NETWORKS: "net_a" })).toEqual({ mode: "only", include: ["net_a"], exclude: [] });
+    // 黑名单
+    expect(await S({ COMMHUB_DUE_REMINDERS: "1", COMMHUB_DUE_REMINDERS_EXCLUDE_NETWORKS: "net_x" })).toEqual({ mode: "all", exclude: ["net_x"] });
+    expect(await S({ COMMHUB_DUE_REMINDERS: "0", COMMHUB_DUE_REMINDERS_EXCLUDE_NETWORKS: "net_x" })).toEqual({ mode: "off" });
+    expect(await S({ COMMHUB_DUE_REMINDERS_NETWORKS: "net_a,net_x", COMMHUB_DUE_REMINDERS_EXCLUDE_NETWORKS: "net_x" })).toEqual({ mode: "only", include: ["net_a"], exclude: ["net_x"] });
+    // 空 / 空白 / 只有逗号 = 没设
+    expect(await S({ COMMHUB_DUE_REMINDERS: "0", COMMHUB_DUE_REMINDERS_NETWORKS: "" })).toEqual({ mode: "off" });
+    expect(await S({ COMMHUB_DUE_REMINDERS: "0", COMMHUB_DUE_REMINDERS_NETWORKS: "  , ,  " })).toEqual({ mode: "off" });
+    expect(await S({ COMMHUB_DUE_REMINDERS_NETWORKS: "   ", COMMHUB_DUE_REMINDERS_EXCLUDE_NETWORKS: " , " })).toEqual({ mode: "all", exclude: [] });
+    // SQL:每个分支只 push 自己用到的参数
+    const p1: unknown[] = ["lo", "hi"];
+    expect(due.dueScopeSql({ mode: "all", exclude: [] }, p1)).toBe("");
+    expect(p1).toEqual(["lo", "hi"]);
+    const p2: unknown[] = ["lo", "hi"];
+    expect(due.dueScopeSql({ mode: "all", exclude: ["net_x"] }, p2)).toBe(" AND network_id NOT IN (?3)");
+    expect(p2).toEqual(["lo", "hi", "net_x"]);
+    const p3: unknown[] = ["lo", "hi"];
+    expect(due.dueScopeSql({ mode: "only", include: ["net_a", "net_b"], exclude: [] }, p3)).toBe(" AND network_id IN (?3, ?4)");
+    expect(p3).toEqual(["lo", "hi", "net_a", "net_b"]);
+    const p4: unknown[] = [];
+    expect(due.dueScopeSql({ mode: "only", include: [], exclude: ["net_x"] }, p4)).toBeNull();
+    expect(due.dueScopeSql({ mode: "off" }, p4)).toBeNull();
+    expect(p4).toEqual([]);
+  });
+
+  test("#524 COMMHUB_DUE_REMINDERS=0 + 白名单:只有白名单网络收到;别的网络的行连基线都不写", async () => {
+    const other = mkNet("allow_other");
+    const mine = await card("dr-524-白名单内", "2026-10-11");
+    const theirs = await cardIn(other, "dr-524-白名单外", "2026-10-11");
+    const out = await withEnv({ COMMHUB_DUE_REMINDERS: "0", COMMHUB_DUE_REMINDERS_NETWORKS: ` ${NET} ,` }, () => due.runDueReminders({ now: T0 }));
+    expect(sentFor(out, mine)).toEqual(["due_soon"]);
+    expect(userNotices(mine)[owen.id]).toHaveLength(1);
+    expect(sentFor(out, theirs)).toEqual([]);
+    expect(rowCount(theirs)).toBe(0);
+    expect(baselineCount(other.net)).toBe(0);
+    // 对照:=0 不带白名单 → 整个关掉,谁都不发
+    const fresh = await card("dr-524-全关", "2026-10-11");
+    const off = await withEnv({ COMMHUB_DUE_REMINDERS: "0" }, () => due.runDueReminders({ now: T0 }));
+    expect(off).toEqual([]);
+    expect(rowCount(fresh)).toBe(0);
+    // 白名单空白 = 没设 → 仍然关
+    expect(await withEnv({ COMMHUB_DUE_REMINDERS: "0", COMMHUB_DUE_REMINDERS_NETWORKS: " , " }, () => due.runDueReminders({ now: T0 }))).toEqual([]);
+  });
+
+  test("#524 黑名单:功能开着时被排除的网络不发、不写基线;其余照发", async () => {
+    const other = mkNet("excl_other");
+    const mine = await card("dr-524-未排除", "2026-10-11");
+    const theirs = await cardIn(other, "dr-524-被排除", "2026-10-11");
+    const out = await withEnv({ COMMHUB_DUE_REMINDERS: "1", COMMHUB_DUE_REMINDERS_EXCLUDE_NETWORKS: other.net }, () => due.runDueReminders({ now: T0 }));
+    expect(sentFor(out, mine)).toEqual(["due_soon"]);
+    expect(sentFor(out, theirs)).toEqual([]);
+    expect(rowCount(theirs)).toBe(0);
+    expect(baselineCount(other.net)).toBe(0);
+    // 白名单里也点了名 → 排除优先;白名单只剩它 → 什么都不扫
+    const both = mkNet("excl_both");
+    const c = await cardIn(both, "dr-524-白名单又被排除", "2026-10-11");
+    const out2 = await withEnv({ COMMHUB_DUE_REMINDERS: "0", COMMHUB_DUE_REMINDERS_NETWORKS: both.net, COMMHUB_DUE_REMINDERS_EXCLUDE_NETWORKS: both.net }, () => due.runDueReminders({ now: T0 }));
+    expect(out2).toEqual([]);
+    expect(rowCount(c)).toBe(0);
+    expect(baselineCount(both.net)).toBe(0);
+  });
+
+  test("#524 默认不变:两个新变量都不设 → 所有网络照发;黑名单空白 = 没设", async () => {
+    const other = mkNet("dflt_other");
+    const mine = await card("dr-524-默认", "2026-10-11");
+    const theirs = await cardIn(other, "dr-524-默认别的网络", "2026-10-11");
+    const out = await withEnv({}, () => due.runDueReminders({ now: T0 }));
+    expect(sentFor(out, mine)).toEqual(["due_soon"]);
+    expect(sentFor(out, theirs)).toEqual(["due_soon"]);
+    const other2 = mkNet("dflt_blank");
+    const theirs2 = await cardIn(other2, "dr-524-黑名单空白", "2026-10-11");
+    const out2 = await withEnv({ COMMHUB_DUE_REMINDERS_EXCLUDE_NETWORKS: "  " }, () => due.runDueReminders({ now: T0 }));
+    expect(sentFor(out2, theirs2)).toEqual(["due_soon"]);
+  });
+
+  test("#524 启动:=0 不起定时器;=0 + 白名单起;各打一行范围日志(只有网络 id)", async () => {
+    const logs: string[] = [];
+    const g = globalThis as any;
+    const orig = { log: console.log, setTimeout: g.setTimeout, setInterval: g.setInterval };
+    // 不起真定时器(否则 30 秒后会用真时钟扫一遍,干扰后面的用例):只记下调了几次。
+    let timers = 0;
+    console.log = (...a: unknown[]) => { logs.push(a.map(String).join(" ")); };
+    g.setTimeout = () => { timers++; return { unref() {} }; };
+    g.setInterval = () => { timers++; return { fake: true }; };
+    try {
+      const off = await withEnv({ COMMHUB_DUE_REMINDERS: "0" }, () => due.startDueReminderTimer());
+      expect(off).toBeNull();
+      expect(timers).toBe(0);
+      const on = await withEnv({ COMMHUB_DUE_REMINDERS: "0", COMMHUB_DUE_REMINDERS_NETWORKS: "net_placeholder_a" }, () => due.startDueReminderTimer());
+      expect(on).toEqual({ fake: true } as any);
+      expect(timers).toBe(2);
+      await withEnv({ COMMHUB_DUE_REMINDERS_EXCLUDE_NETWORKS: "net_placeholder_x" }, () => due.startDueReminderTimer());
+    } finally { console.log = orig.log; g.setTimeout = orig.setTimeout; g.setInterval = orig.setInterval; }
+    const scopeLogs = logs.filter((l) => l.startsWith("[due-reminders] scope:"));
+    expect(scopeLogs).toEqual([
+      "[due-reminders] scope: off",
+      "[due-reminders] scope: only networks net_placeholder_a",
+      "[due-reminders] scope: all networks except net_placeholder_x",
+    ]);
+  });
 });
 
 describe("#494 列表筛选", () => {

package/src/requirement-due-reminders.ts

@@ -21,6 +21,11 @@
 //
 // 上线护栏(生产上有别的团队的网络和节点):
 //   COMMHUB_DUE_REMINDER_NETWORKS=<id,id,…>  只给这些网络发;不设 = 所有网络(自建 Hub 默认就有这个功能)。
+//   #524 按网络开关(一个 Hub 上多个团队的网络,只想给自己的网络开):
+//   COMMHUB_DUE_REMINDERS_NETWORKS=<id,id,…>          白名单。COMMHUB_DUE_REMINDERS=0 时也生效:只给这些网络发。
+//   COMMHUB_DUE_REMINDERS_EXCLUDE_NETWORKS=<id,id,…>  黑名单。功能开着时这些网络不发(白名单里也排除)。
+//   两个新变量都不设 → 行为与之前完全相同。生效范围在 startHub 时打一行日志(只有网络 id)。
+//   过滤写在扫描 SQL 的 WHERE 里(基线 INSERT 与候选 SELECT 同一个条件),范围外网络的行根本不会被读出来。
 //   COMMHUB_DUE_REMINDER_NODES=1              给负责 Agent 节点发消息;默认关(人照常提醒)。
 //   开通时不补发:每个网络第一次被扫描到时记一行基线(kind='baseline',sent_at = 那一刻)。只有在基线**之后**才变成逾期的卡
 //     会收到「已逾期」提醒;基线之前就已经逾期的卡永远不发逾期提醒(打开功能 / 把网络加进白名单都不会刷一批旧卡)。
@@ -72,13 +77,60 @@ export function dueReminderTimezone(): string {
   const tz = process.env.COMMHUB_DUE_REMINDER_TZ?.trim() || "Asia/Shanghai";
   try { new Intl.DateTimeFormat("en-US", { timeZone: tz }); return tz; } catch { return "Asia/Shanghai"; }
 }
-/** COMMHUB_DUE_REMINDER_NETWORKS:逗号分隔的网络 id;没设(或只有空白)→ null = 所有网络。 */
-export function reminderNetworks(): string[] | null {
-  const raw = process.env.COMMHUB_DUE_REMINDER_NETWORKS;
+/** 逗号分隔的网络 id;没设(或只有空白 / 逗号)→ null。去重,保持顺序。 */
+function envIdList(name: string): string[] | null {
+  const raw = process.env[name];
   if (raw === undefined) return null;
-  const ids = raw.split(",").map((x) => x.trim()).filter(Boolean);
+  const ids = [...new Set(raw.split(",").map((x) => x.trim()).filter(Boolean))];
   return ids.length ? ids : null;
 }
+/** COMMHUB_DUE_REMINDER_NETWORKS:逗号分隔的网络 id;没设(或只有空白)→ null = 所有网络。 */
+export function reminderNetworks(): string[] | null {
+  return envIdList("COMMHUB_DUE_REMINDER_NETWORKS");
+}
+
+/**
+ * #524 生效范围。
+ *   off  —— 不扫描(COMMHUB_DUE_REMINDERS=0 且没设 COMMHUB_DUE_REMINDERS_NETWORKS)。
+ *   all  —— 所有网络,减去 exclude。
+ *   only —— 只扫 include(已减去 exclude;可能为空 = 什么都不扫)。
+ * 白名单 = COMMHUB_DUE_REMINDERS_NETWORKS ∪ COMMHUB_DUE_REMINDER_NETWORKS(旧名);但只有新名能在 COMMHUB_DUE_REMINDERS=0 时打开。
+ * 白名单一旦设了就收窄(包括 COMMHUB_DUE_REMINDERS=1):宁可少发,不给没点名的网络发。
+ */
+export type DueReminderScope =
+  | { mode: "off" }
+  | { mode: "all"; exclude: string[] }
+  | { mode: "only"; include: string[]; exclude: string[] };
+
+export function dueReminderScope(): DueReminderScope {
+  const allow = envIdList("COMMHUB_DUE_REMINDERS_NETWORKS");
+  const legacy = envIdList("COMMHUB_DUE_REMINDER_NETWORKS");
+  const exclude = envIdList("COMMHUB_DUE_REMINDERS_EXCLUDE_NETWORKS") ?? [];
+  if (process.env.COMMHUB_DUE_REMINDERS === "0" && !allow) return { mode: "off" };
+  if (!allow && !legacy) return { mode: "all", exclude };
+  const include = [...new Set([...(allow ?? []), ...(legacy ?? [])])].filter((id) => !exclude.includes(id));
+  return { mode: "only", include, exclude };
+}
+
+export function describeDueReminderScope(scope: DueReminderScope = dueReminderScope()): string {
+  if (scope.mode === "off") return "off";
+  if (scope.mode === "all") return scope.exclude.length ? `all networks except ${scope.exclude.join(",")}` : "all networks";
+  return scope.include.length ? `only networks ${scope.include.join(",")}` : "no networks (allowlist empty after exclude)";
+}
+
+/**
+ * 范围条件(拼在 WHERE 后面)。只 push 这个分支真正用到的参数(PG 预编译拒绝绑了没用的参数)。
+ * null = 范围为空,调用方不该查询。
+ */
+export function dueScopeSql(scope: DueReminderScope, params: unknown[]): string | null {
+  if (scope.mode === "off") return null;
+  if (scope.mode === "only") {
+    if (!scope.include.length) return null;
+    return ` AND network_id IN (${scope.include.map((id) => `?${params.push(id)}`).join(", ")})`;
+  }
+  if (!scope.exclude.length) return "";
+  return ` AND network_id NOT IN (${scope.exclude.map((id) => `?${params.push(id)}`).join(", ")})`;
+}
 export function nodeRemindersEnabled(): boolean { return process.env.COMMHUB_DUE_REMINDER_NODES === "1"; }
 export const BASELINE_KIND = "baseline";
 
@@ -213,13 +265,15 @@ export function runDueReminders(opts: { now?: number } = {}): DueReminderSent[]
   // 范围:最老 = 今天 - maxOverdue - 1(UTC 日期 ≤ 本地日期,多留一天);最新 < 今天 + 2(24 小时内的时刻型 UTC 日期 ≤ 明天)。
   const lo = addDays(today, -maxOverdue - 1);
   const hi = addDays(today, 2);
-  const allow = reminderNetworks();
+  const scope = dueReminderScope();
+  // 范围为空(关闭 / 白名单全被排除)→ 什么都不读、不写基线。
+  if (dueScopeSql(scope, []) === null) return [];
   const sentAt = new Date(nowMs).toISOString();
   // 基线:范围内每个网络第一次被扫到的那一刻(已有就不动)。一条 INSERT … SELECT。
   {
     const bp: unknown[] = [BASELINE_KIND, sentAt];
     // WHERE 必须有:SQLite 里「INSERT … SELECT … FROM t ON CONFLICT」会把 ON 读成 JOIN 约束(语法错),要一个 WHERE 隔开。
-    const where = ` WHERE 1=1${allow ? ` AND network_id IN (${allow.map((id) => `?${bp.push(id)}`).join(", ")})` : ""}`;
+    const where = ` WHERE 1=1${dueScopeSql(scope, bp) ?? ""}`;
     db.run(
       `INSERT INTO requirement_due_reminders (requirement_id, kind, due_on, day, network_id, sent_at)
        SELECT '__baseline__:' || network_id, ?1, '', '', network_id, ?2 FROM networks${where}
@@ -233,7 +287,7 @@ export function runDueReminders(opts: { now?: number } = {}): DueReminderSent[]
       .filter((e): e is readonly [string, number] => e[1] !== null),
   );
   const params: unknown[] = [lo, hi];
-  const netFilter = allow ? ` AND network_id IN (${allow.map((id) => `?${params.push(id)}`).join(", ")})` : "";
+  const netFilter = dueScopeSql(scope, params) ?? "";
   const rows = db.all<DueRow>(
     `SELECT requirement_id, network_id, seq, title, due_on, owner_json, participants_json, agent_owner_json
        FROM requirements
@@ -299,9 +353,14 @@ function deliver(row: DueRow, r: { kind: DueKind; overdueDays: number; dueDay: s
   return { requirement_id: row.requirement_id, kind: r.kind as DueKind, users, node: notifiedNode };
 }
 
-/** startHub 里调用。COMMHUB_DUE_REMINDERS=0 关掉;bootServer(测试)不调用它。第一次扫描延后一个间隔外的 30 秒,不和启动抢。 */
+/**
+ * startHub 里调用。COMMHUB_DUE_REMINDERS=0 关掉(除非设了 COMMHUB_DUE_REMINDERS_NETWORKS,见 dueReminderScope);
+ * bootServer(测试)不调用它。第一次扫描延后一个间隔外的 30 秒,不和启动抢。启动时打一行生效范围(只有网络 id)。
+ */
 export function startDueReminderTimer(): ReturnType<typeof setInterval> | null {
-  if (process.env.COMMHUB_DUE_REMINDERS === "0") return null;
+  const scope = dueReminderScope();
+  console.log(`[due-reminders] scope: ${describeDueReminderScope(scope)}`);
+  if (scope.mode === "off") return null;
   const ms = envNumber("COMMHUB_DUE_REMINDER_TICK_MS", 10 * 60_000, 1_000);
   const tick = () => { try { runDueReminders(); } catch (e: any) { console.error(`[due-reminders] tick failed: ${e?.message || e}`); } };
   const first = setTimeout(tick, Math.min(ms, 30_000));