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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.100",
+  "version": "0.9.0-preview.101",
   "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/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/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));

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

@@ -0,0 +1,233 @@
+// #523 —— 定时任务连续失败:告诉创建者(可选自动暂停)。
+//
+// 钉住:
+//   1. 连续 5 次失败(派出去的任务以 failed 结束)→ 给创建者恰好 1 条通知(别的成员 0 条),第 6–10 次不再发;
+//      通知里有排程名、目标节点、失败次数、最近一次的错误(截断)和怎么暂停。
+//   2. 派发时就失败(目标节点不存在)同样计数。
+//   3. 中间成功一次 → 重新上膛:再连续 5 次失败才发第二条。
+//   4. 一直失败:24 小时内不重发;上次告警早于 24 小时 → 再发一条。
+//   5. 默认不自动暂停;COMMHUB_SCHEDULE_FAILURE_AUTO_PAUSE_RUNS=3 → 第 3 次失败后排程 paused、next_run_at 清空、
+//      revision+1,并通知一次。
+//   6. GET /runs 返回 consecutive_failures / failure_alert_threshold / last_failure_alert_at,
+//      任务以 failed 结束的 run 的 error_message 取自任务的回复正文。
+//
+// 跑法:cd server && COMMHUB_DB=/tmp/x.db bun test src/scheduled-failures-http.test.ts
+//       PG:COMMHUB_TEST_PG_URL=… COMMHUB_PG_EXPERIMENTAL=1(tests/test2123-hub-postgres-ladder 里注册)
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { addNetworkMember, createNetworkTokenForNode, register } from "./auth.js";
+import { db } from "./db.js";
+import { dispatchScheduledOccurrence, handleScheduledTaskRequest } from "./scheduled-tasks.js";
+import { SCHEDULE_FAILING_NOTICE_KIND, failureStreak } from "./scheduled-failures.js";
+import { registerTools } from "./tools.js";
+
+const activeDbPath = process.env.COMMHUB_DB ?? (process.env.COMMHUB_TEST_PG_URL ? "postgres" : undefined);
+if (!activeDbPath) throw new Error("scheduled-failures requires COMMHUB_DB (or COMMHUB_TEST_PG_URL) before module import");
+
+const stamp = Date.now();
+const ALIAS = `fail-node-${stamp}`;
+const NODE_ID = `n_fail_${stamp}`;
+let NET = "", creatorId = "", otherId = "";
+const ENV_KEYS = ["COMMHUB_SCHEDULE_FAILURE_NOTICE_RUNS", "COMMHUB_SCHEDULE_FAILURE_RENOTICE_SEC", "COMMHUB_SCHEDULE_FAILURE_AUTO_PAUSE_RUNS"];
+const SAFETY_ERROR = "执行出错: upstream model refused the request (safety system). " + "x".repeat(600);
+
+function seedSchedule(name = "前后端分离巡检", targetNodeId = NODE_ID): any {
+  const scheduleId = `sched_${crypto.randomUUID()}`;
+  db.run(
+    `INSERT INTO scheduled_tasks
+       (schedule_id, network_id, created_by, name, target_node_id, target_alias, task_content, priority,
+        schedule_type, schedule_json, timezone, status, next_run_at)
+     VALUES (?1, ?2, ?3, ?4, ?5, ?6, 'scheduled task', 'normal', 'interval',
+             '{"type":"interval","every_seconds":120}', 'Asia/Shanghai', 'active', datetime('now', '+2 minutes'))`,
+    [scheduleId, NET, creatorId, name, targetNodeId, ALIAS],
+  );
+  return reload(scheduleId);
+}
+const reload = (scheduleId: string) => db.get<any>("SELECT * FROM scheduled_tasks WHERE schedule_id = ?1", scheduleId);
+
+let slot = 0;
+const nextSlot = () => new Date(Date.UTC(2026, 9, 4, 0, 0, 0) + (++slot) * 120_000).toISOString();
+const fire = (schedule: any, now = new Date()) => dispatchScheduledOccurrence(schedule, nextSlot(), false, now);
+
+const notices = (userId: string) => db.all<{ title: string; content: string; meta_json: string; from_session: string; severity: string }>(
+  "SELECT title, content, meta_json, from_session, severity FROM user_inbox WHERE user_id = ?1 AND network_id = ?2 AND kind = ?3 ORDER BY created_at, message_id",
+  userId, NET, SCHEDULE_FAILING_NOTICE_KIND,
+);
+const noticesFor = (userId: string, scheduleId: string) => notices(userId).filter((n) => JSON.parse(n.meta_json).schedule_failing.schedule_id === scheduleId);
+
+async function nodeReply(args: Record<string, unknown>): Promise<any> {
+  const mcp = new McpServer({ name: "sched-fail", version: "0" }) as any;
+  const handlers: Record<string, (a: any) => Promise<any>> = {};
+  const original = mcp.tool.bind(mcp);
+  mcp.tool = (name: string, ...rest: any[]) => {
+    const handler = rest.at(-1);
+    if (typeof handler === "function") handlers[name] = handler;
+    return original(name, ...rest);
+  };
+  registerTools(mcp, undefined, NET, creatorId, ALIAS, true, null);
+  const out = await handlers.send_reply(args);
+  return JSON.parse(out.content[0].text);
+}
+
+/** 派一次,节点以 failed(或 replied)回复。 */
+async function runOnce(schedule: any, outcome: "failed" | "replied" = "failed"): Promise<{ runId: string; taskId: string }> {
+  const r = fire(schedule);
+  expect(r.status).toBe("delivered");
+  const out = await nodeReply({ alias: "scheduler", text: outcome === "failed" ? SAFETY_ERROR : "done", in_reply_to: r.taskId, status: outcome, from_session: ALIAS });
+  expect(out.ok).toBe(true);
+  return { runId: r.runId, taskId: r.taskId! };
+}
+
+async function getRuns(scheduleId: string): Promise<any> {
+  const url = new URL(`http://hub.test/api/scheduled-tasks/${scheduleId}/runs`);
+  const res = await handleScheduledTaskRequest({
+    req: new Request(url, { method: "GET" }), url,
+    auth: { userId: creatorId, networkId: NET, username: "creator" },
+    isAdmin: false, isNodeToken: false, scope: { networkId: NET, networkIds: [NET] } as any,
+  });
+  expect(res!.status).toBe(200);
+  return res!.json();
+}
+
+beforeAll(() => {
+  const creator = register(`fail_creator_${stamp}`, "FailCreator123!", undefined, "seed");
+  expect(creator.ok).toBe(true);
+  NET = creator.network_id!; creatorId = creator.user!.user_id;
+  const other = register(`fail_other_${stamp}`, "FailOther123!", undefined, "seed");
+  otherId = other.user!.user_id;
+  expect(addNetworkMember(NET, otherId, "member", creatorId, { agentAccess: "all" }).ok).toBe(true);
+  expect(createNetworkTokenForNode(creatorId, NET, ALIAS).ok).toBe(true);
+  db.run("INSERT INTO nodes (node_id, node_name, alias, runtime, network_id) VALUES (?1, ?2, ?2, 'claude-code', ?3)", [NODE_ID, ALIAS, NET]);
+  db.run("INSERT INTO sessions (resume_id, alias, status, node_id, network_id) VALUES (?1, ?2, 'idle', ?3, ?4)", [`r_fail_${stamp}`, ALIAS, NODE_ID, NET]);
+});
+beforeEach(() => { for (const k of ENV_KEYS) delete process.env[k]; });
+afterEach(() => { for (const k of ENV_KEYS) delete process.env[k]; });
+afterAll(() => { db.run("DELETE FROM user_inbox WHERE network_id = ?1 AND kind = ?2", [NET, SCHEDULE_FAILING_NOTICE_KIND]); });
+
+describe("#523 consecutive-failure alert", () => {
+  test("5 failed runs → exactly one notice to the creator with name/target/count/error/how to pause; runs 6–10 stay quiet", async () => {
+    const s = seedSchedule();
+    for (let i = 0; i < 4; i++) await runOnce(s);
+    expect(noticesFor(creatorId, s.schedule_id).length).toBe(0);
+    await runOnce(s);
+    const mine = noticesFor(creatorId, s.schedule_id);
+    expect(mine.length).toBe(1);
+    expect(noticesFor(otherId, s.schedule_id).length).toBe(0);
+    const n = mine[0];
+    expect(n.from_session).toBe(ALIAS);
+    expect(n.title).toBe("定时任务连续失败");
+    expect(n.severity).toBe("error");
+    for (const frag of ["前后端分离巡检", ALIAS, "连续 5 次", "safety system", "task_failed", "暂停", s.schedule_id]) expect(n.content).toContain(frag);
+    expect(n.content).not.toContain("x".repeat(400)); // 错误被截断
+    expect(JSON.parse(n.meta_json).schedule_failing).toEqual({ reason: "failing", schedule_id: s.schedule_id, consecutive_failures: 5, error_code: "task_failed" });
+    for (let i = 0; i < 5; i++) await runOnce(s);
+    expect(noticesFor(creatorId, s.schedule_id).length).toBe(1);
+    expect(reload(s.schedule_id).status).toBe("active"); // 默认不自动暂停
+  });
+
+  test("dispatch-time failures (target node gone) count too", () => {
+    const s = seedSchedule("孤儿排程", `n_missing_${stamp}`);
+    for (let i = 0; i < 5; i++) expect(fire(s).status).toBe("failed");
+    const mine = noticesFor(creatorId, s.schedule_id);
+    expect(mine.length).toBe(1);
+    expect(mine[0].content).toContain("target_node_not_found");
+    expect(mine[0].content).toContain("The bound node no longer exists");
+  });
+
+  test("a success in between re-arms: the next 5 failures notify again", async () => {
+    const s = seedSchedule();
+    for (let i = 0; i < 5; i++) await runOnce(s);
+    expect(noticesFor(creatorId, s.schedule_id).length).toBe(1);
+    await runOnce(s, "replied");
+    expect(failureStreak(s.schedule_id).consecutiveFailures).toBe(0);
+    for (let i = 0; i < 4; i++) await runOnce(s);
+    expect(noticesFor(creatorId, s.schedule_id).length).toBe(1);
+    await runOnce(s);
+    expect(noticesFor(creatorId, s.schedule_id).length).toBe(2);
+  });
+
+  test("still failing: no repeat within 24h; one more once the last alert is older than 24h", async () => {
+    const s = seedSchedule();
+    for (let i = 0; i < 5; i++) await runOnce(s);
+    expect(noticesFor(creatorId, s.schedule_id).length).toBe(1);
+    db.run("UPDATE scheduled_tasks SET failure_alert_at = ?1 WHERE schedule_id = ?2", [new Date(Date.now() - 23 * 3_600_000).toISOString(), s.schedule_id]);
+    await runOnce(s);
+    expect(noticesFor(creatorId, s.schedule_id).length).toBe(1);
+    db.run("UPDATE scheduled_tasks SET failure_alert_at = ?1 WHERE schedule_id = ?2", [new Date(Date.now() - 25 * 3_600_000).toISOString(), s.schedule_id]);
+    await runOnce(s);
+    expect(noticesFor(creatorId, s.schedule_id).length).toBe(2);
+    await runOnce(s);
+    expect(noticesFor(creatorId, s.schedule_id).length).toBe(2);
+  });
+
+  test("COMMHUB_SCHEDULE_FAILURE_NOTICE_RUNS changes N; no creator → no notice", async () => {
+    process.env.COMMHUB_SCHEDULE_FAILURE_NOTICE_RUNS = "2";
+    const s = seedSchedule();
+    await runOnce(s);
+    expect(noticesFor(creatorId, s.schedule_id).length).toBe(0);
+    await runOnce(s);
+    expect(noticesFor(creatorId, s.schedule_id).length).toBe(1);
+
+    const orphan = seedSchedule();
+    db.run("UPDATE scheduled_tasks SET created_by = NULL WHERE schedule_id = ?1", [orphan.schedule_id]);
+    const row = reload(orphan.schedule_id);
+    for (let i = 0; i < 3; i++) await runOnce(row);
+    expect(noticesFor(creatorId, orphan.schedule_id).length).toBe(0);
+  });
+});
+
+describe("#523 auto-pause (opt-in)", () => {
+  test("off by default: 10 failures leave the schedule active", async () => {
+    const s = seedSchedule();
+    for (let i = 0; i < 10; i++) await runOnce(s);
+    const after = reload(s.schedule_id);
+    expect(after.status).toBe("active");
+    expect(after.next_run_at).not.toBeNull();
+  });
+
+  test("COMMHUB_SCHEDULE_FAILURE_AUTO_PAUSE_RUNS=3 pauses after the 3rd failure and tells the creator once", async () => {
+    process.env.COMMHUB_SCHEDULE_FAILURE_AUTO_PAUSE_RUNS = "3";
+    const s = seedSchedule();
+    await runOnce(s); await runOnce(s);
+    expect(reload(s.schedule_id).status).toBe("active");
+    await runOnce(s);
+    const after = reload(s.schedule_id);
+    expect(after.status).toBe("paused");
+    expect(after.next_run_at).toBeNull();
+    expect(after.revision).toBe(s.revision + 1);
+    const mine = noticesFor(creatorId, s.schedule_id);
+    expect(mine.length).toBe(1);
+    expect(mine[0].title).toBe("定时任务连续失败,已自动暂停");
+    expect(JSON.parse(mine[0].meta_json).schedule_failing.reason).toBe("paused");
+    // 手动 run-now 再失败两次到 N=5:同一段失败,已经通知过 → 不再发
+    await runOnce(after); await runOnce(after);
+    expect(noticesFor(creatorId, s.schedule_id).length).toBe(1);
+  });
+});
+
+describe("#523 GET /runs", () => {
+  test("exposes consecutive_failures and the failed task's reason as error_message", async () => {
+    const s = seedSchedule();
+    await runOnce(s, "replied");
+    const fails = [await runOnce(s), await runOnce(s)];
+    const body = await getRuns(s.schedule_id);
+    expect(body.ok).toBe(true);
+    expect(body.consecutive_failures).toBe(2);
+    expect(body.failure_alert_threshold).toBe(5);
+    expect(body.last_failure_alert_at).toBeNull();
+    expect(body.runs.length).toBe(3);
+    const failed = body.runs.find((r: any) => r.run_id === fails[1].runId);
+    expect(failed.status).toBe("failed");
+    expect(failed.error_code).toBe("task_failed");
+    expect(failed.error_message).toContain("safety system");
+    expect(failed.error_message.length).toBeLessThanOrEqual(500);
+    for (const k of ["scheduled_for", "created_at", "completed_at", "task_id"]) expect(k in failed).toBe(true);
+    const ok = body.runs.find((r: any) => r.status === "replied");
+    expect(ok.error_message).toBeNull();
+
+    for (let i = 0; i < 3; i++) await runOnce(s);
+    const again = await getRuns(s.schedule_id);
+    expect(again.consecutive_failures).toBe(5);
+    expect(typeof again.last_failure_alert_at).toBe("string");
+  });
+});

package/src/scheduled-failures.ts

@@ -0,0 +1,179 @@
+// #523 —— 定时任务连续失败:告诉创建者(可选自动暂停)。
+//
+// 现场:一个每 2 分钟一次的排程,每一次派出去的任务都被节点以 failed 结束(上游模型拒绝),一天 720 次,
+//   排程照样 active,创建者什么都不知道。#464 只管「被上一次卡住」(skipped),不管「每次都失败」。
+//
+// 1. 计数:consecutive_failures = 最近一次成功(run.status='replied')之后,status='failed' 的 run 数。
+//    skipped / cancelled / expired / 还没结束的 run 不算失败,也不打断连续(expired 由 #464 的超时告警负责)。
+//    失败有两种来源,都会走到这里:派发时就失败(节点不在 / 被停用 / 降级 / 创建者无权限,
+//    scheduled-tasks.ts 提交后调用),以及派出去的任务以 failed 结束(db.ts 的 run 镜像触发钩子)。
+// 2. 告警:连续失败 ≥ N(默认 5)→ 给排程创建者发**一条**通知(agent-notice.ts,与 #462/#464 同一条路,
+//    出现在与目标节点的会话里)。去重落在 scheduled_tasks 两列上(条件写,一次只有一个调用方抢得到):
+//    failure_alert_key = 告警那一刻「最近一次成功」的 run_id —— 之后又成功过,key 就变了,下一段失败重新上膛;
+//    failure_alert_at  = 告警时间 —— 一直没成功过,24 小时后再提醒一次。Hub 重启不会重发。
+// 3. 自动暂停:默认关。COMMHUB_SCHEDULE_FAILURE_AUTO_PAUSE_RUNS=M(≥1)时,连续失败 ≥ M 的 active 排程
+//    被置为 paused(next_run_at 清空,revision+1,与用户手动暂停同形),并通知创建者。
+//
+// 环境变量:COMMHUB_SCHEDULE_FAILURE_NOTICE_RUNS(N,默认 5)、COMMHUB_SCHEDULE_FAILURE_RENOTICE_SEC
+//   (默认 86400)、COMMHUB_SCHEDULE_FAILURE_AUTO_PAUSE_RUNS(M,默认 0 = 关)。
+
+import { db, setScheduledRunTerminalHook } from "./db.js";
+import { sendAgentNotice } from "./agent-notice.js";
+
+export const SCHEDULE_FAILING_NOTICE_KIND = "schedule_failing";
+const ERROR_PREVIEW_CHARS = 300;
+
+function envInt(name: string, fallback: number, min: number): number {
+  const raw = process.env[name];
+  if (raw === undefined || raw.trim() === "") return fallback;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= min ? Math.floor(n) : fallback;
+}
+
+export function failureNoticeRuns(): number { return envInt("COMMHUB_SCHEDULE_FAILURE_NOTICE_RUNS", 5, 1); }
+export function failureRenoticeMs(): number { return envInt("COMMHUB_SCHEDULE_FAILURE_RENOTICE_SEC", 86_400, 1) * 1000; }
+/** 0 = 不自动暂停(默认)。 */
+export function failureAutoPauseRuns(): number { return envInt("COMMHUB_SCHEDULE_FAILURE_AUTO_PAUSE_RUNS", 0, 0); }
+
+export type FailureStreak = { consecutiveFailures: number; lastSuccessRunId: string | null };
+
+/** 最近一次成功之后的失败 run 数。scheduled_for 每个排程唯一(UNIQUE),按它排序是确定的。 */
+export function failureStreak(scheduleId: string): FailureStreak {
+  const lastSuccess = db.get<{ run_id: string; scheduled_for: string }>(
+    "SELECT run_id, scheduled_for FROM scheduled_task_runs WHERE schedule_id = ?1 AND status = 'replied' ORDER BY scheduled_for DESC LIMIT 1",
+    scheduleId,
+  );
+  const n = db.get<{ n: number }>(
+    "SELECT COUNT(*) AS n FROM scheduled_task_runs WHERE schedule_id = ?1 AND status = 'failed' AND scheduled_for > ?2",
+    scheduleId, lastSuccess?.scheduled_for ?? "",
+  )?.n ?? 0;
+  return { consecutiveFailures: Number(n), lastSuccessRunId: lastSuccess?.run_id ?? null };
+}
+
+type ScheduleForAlert = {
+  schedule_id: string;
+  network_id: string;
+  created_by: string | null;
+  name: string;
+  target_alias: string;
+  status: string;
+};
+
+export type FailureNotice = {
+  reason: "failing" | "paused";
+  scheduleId: string;
+  scheduleName: string;
+  networkId: string;
+  createdBy: string;
+  alias: string;
+  failures: number;
+  errorCode: string | null;
+  errorMessage: string | null;
+};
+
+function latestFailure(scheduleId: string): { error_code: string | null; error_message: string | null } {
+  const row = db.get<{ error_code: string | null; error_message: string | null; result: string | null }>(
+    `SELECT r.error_code, r.error_message, t.result
+       FROM scheduled_task_runs r
+       LEFT JOIN tasks t ON t.task_id = r.task_id AND t.network_id = r.network_id
+      WHERE r.schedule_id = ?1 AND r.status = 'failed'
+      ORDER BY r.scheduled_for DESC LIMIT 1`,
+    scheduleId,
+  );
+  // 任务以 failed 结束时 run.error_message 为空,原因在任务的回复正文里。
+  return { error_code: row?.error_code ?? null, error_message: row?.error_message || row?.result || null };
+}
+
+function truncate(s: string, max: number): string {
+  const flat = s.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max)}…` : flat;
+}
+
+export function failureNoticeText(n: FailureNotice): { title: string; text: string } {
+  const err = n.errorMessage ? truncate(n.errorMessage, ERROR_PREVIEW_CHARS) : "(没有错误详情)";
+  const code = n.errorCode ? ` [${n.errorCode}]` : "";
+  const head = `定时任务「${n.scheduleName}」(派给节点 ${n.alias})已经连续 ${n.failures} 次执行失败。\n\n最近一次的错误${code}:${err}\n\n`;
+  if (n.reason === "paused") {
+    return {
+      title: "定时任务连续失败,已自动暂停",
+      text: `${head}按 Hub 的设置,它已被自动暂停,不会再派发。处理好原因后,在定时任务里把它恢复为「启用」即可。`,
+    };
+  }
+  return {
+    title: "定时任务连续失败",
+    text: `${head}它仍在按计划运行。如需停止,在定时任务里暂停它(或 PATCH /api/scheduled-tasks/${n.scheduleId},body 带 {"status":"paused","revision":<当前 revision>})。`
+      + `在它重新成功之前,24 小时内不会再提醒。`,
+  };
+}
+
+export function sendFailureNotice(n: FailureNotice): string | null {
+  try {
+    const { title, text } = failureNoticeText(n);
+    return sendAgentNotice({
+      networkId: n.networkId, userId: n.createdBy, fromAlias: n.alias, kind: SCHEDULE_FAILING_NOTICE_KIND, title, text, severity: "error",
+      meta: { schedule_failing: { reason: n.reason, schedule_id: n.scheduleId, consecutive_failures: n.failures, error_code: n.errorCode } },
+      idPrefix: "dm_sched_",
+    });
+  } catch (e: any) {
+    console.error(`[scheduled-tasks] failure notice failed schedule=${n.scheduleId}: ${e?.message || e}`);
+    return null;
+  }
+}
+
+/**
+ * 一个 run 以 failed 结束之后调用(派发时失败 / 任务 failed 都算)。返回发出的通知(测试用),没有则 null。
+ * 告警与暂停都是条件写:并发的两个调用方只有一个写得进去,所以每段失败恰好一条通知。
+ */
+export function evaluateScheduleFailures(scheduleId: string, now = new Date()): FailureNotice | null {
+  const row = db.get<ScheduleForAlert>(
+    "SELECT schedule_id, network_id, created_by, name, target_alias, status FROM scheduled_tasks WHERE schedule_id = ?1",
+    scheduleId,
+  );
+  if (!row) return null;
+  const streak = failureStreak(scheduleId);
+  const noticeAt = failureNoticeRuns();
+  const pauseAt = failureAutoPauseRuns();
+  const wantsPause = pauseAt > 0 && streak.consecutiveFailures >= pauseAt && row.status === "active";
+  if (streak.consecutiveFailures < noticeAt && !wantsPause) return null;
+
+  let paused = false;
+  if (wantsPause) {
+    paused = db.run(
+      "UPDATE scheduled_tasks SET status = 'paused', next_run_at = NULL, revision = revision + 1, updated_at = datetime('now') WHERE schedule_id = ?1 AND status = 'active'",
+      [scheduleId],
+    ).changes === 1;
+  }
+  const key = streak.lastSuccessRunId ?? "";
+  const cutoff = new Date(now.getTime() - failureRenoticeMs()).toISOString();
+  // 去重:同一段失败(key 没变)且上次告警不到 24 小时 → 不写、不发。暂停是另一件事,照发。
+  const claimed = db.run(
+    `UPDATE scheduled_tasks SET failure_alert_at = ?1, failure_alert_key = ?2
+      WHERE schedule_id = ?3
+        AND (failure_alert_at IS NULL OR COALESCE(failure_alert_key, '') <> ?2 OR failure_alert_at <= ?4)`,
+    [now.toISOString(), key, scheduleId, cutoff],
+  ).changes === 1;
+  if (paused && !claimed) {
+    db.run("UPDATE scheduled_tasks SET failure_alert_at = ?1, failure_alert_key = ?2 WHERE schedule_id = ?3", [now.toISOString(), key, scheduleId]);
+  }
+  if (!paused && !claimed) return null;
+  if (!row.created_by) return null;
+  const latest = latestFailure(scheduleId);
+  const notice: FailureNotice = {
+    reason: paused ? "paused" : "failing",
+    scheduleId, scheduleName: row.name, networkId: row.network_id, createdBy: row.created_by, alias: row.target_alias,
+    failures: streak.consecutiveFailures, errorCode: latest.error_code, errorMessage: latest.error_message,
+  };
+  sendFailureNotice(notice);
+  return notice;
+}
+
+/** GET /runs 的附加字段。 */
+export function failureSummary(scheduleId: string): { consecutive_failures: number; failure_alert_threshold: number; last_failure_alert_at: string | null } {
+  const streak = failureStreak(scheduleId);
+  const alertAt = db.get<{ failure_alert_at: string | null }>("SELECT failure_alert_at FROM scheduled_tasks WHERE schedule_id = ?1", scheduleId)?.failure_alert_at ?? null;
+  return { consecutive_failures: streak.consecutiveFailures, failure_alert_threshold: failureNoticeRuns(), last_failure_alert_at: alertAt };
+}
+
+setScheduledRunTerminalHook((scheduleId, status) => {
+  if (status === "failed") evaluateScheduleFailures(scheduleId);
+});

package/src/scheduled-tasks.ts

@@ -7,6 +7,7 @@ import { hasSubscribers, pushEvent, pushNetworkObserverEvent } from "./push.js";
 import { SCHEDULED_TASK_STORAGE_SELECT } from "./rest-projections.js";
 import { parseDbTimestampMs } from "./db-timestamp.js";
 import { blockerTimedOut, expireStuckBlocker, sendStuckNotice, skipsBlockedBy, stuckNoticeSkips, stuckTimeoutMs, type StuckNotice } from "./scheduled-stuck.js";
+import { evaluateScheduleFailures, failureSummary } from "./scheduled-failures.js";
 
 export type ScheduleSpec =
   | { type: "once"; run_at: string }
@@ -379,6 +380,8 @@ export function dispatchScheduledOccurrence(row: ScheduledRow, scheduledFor: str
   try {
     for (const t of timedOut) logTaskEvent(t.taskId, t.fromStatus, "expired", "hub-scheduler", `stuck timeout; schedule=${row.schedule_id} run=${runId}`);
     for (const n of notices) sendStuckNotice(n);
+    // #523 — a run that failed at dispatch counts toward the consecutive-failure alert (task failures arrive via db.ts).
+    if (finalStatus === "failed") evaluateScheduleFailures(row.schedule_id, advanceAfter);
     if (createdTaskId) logTaskEvent(createdTaskId, null, "delivered", "hub-scheduler", `schedule=${row.schedule_id} run=${runId}`);
     if (event) {
       const pending = db.get<{ cnt: number }>("SELECT COUNT(*) AS cnt FROM inbox WHERE session_name = ?1 AND network_id = ?2 AND acked = 0", event.alias, event.networkId);
@@ -548,10 +551,16 @@ export async function handleScheduledTaskRequest(ctx: ScheduledRequestContext):
   if (sub === "runs" && req.method === "GET") {
     const limit = Math.max(1, Math.min(200, Number(url.searchParams.get("limit")) || 50));
     const runs = db.all(
-      "SELECT run_id, schedule_id, scheduled_for, task_id, status, error_code, error_message, blocked_by_task_id, blocked_by_state, created_at, completed_at FROM scheduled_task_runs WHERE schedule_id = ?1 AND network_id = ?2 ORDER BY created_at DESC LIMIT ?3",
+      // #523 — a task that ended `failed` leaves run.error_message empty; its reason is the task's reply text.
+      `SELECT r.run_id, r.schedule_id, r.scheduled_for, r.task_id, r.status, r.error_code,
+              CASE WHEN r.error_message IS NULL AND r.status = 'failed' THEN SUBSTR(t.result, 1, 500) ELSE r.error_message END AS error_message,
+              r.blocked_by_task_id, r.blocked_by_state, r.created_at, r.completed_at
+         FROM scheduled_task_runs r
+         LEFT JOIN tasks t ON t.task_id = r.task_id AND t.network_id = r.network_id
+        WHERE r.schedule_id = ?1 AND r.network_id = ?2 ORDER BY r.created_at DESC, r.scheduled_for DESC LIMIT ?3`,
       row.schedule_id, row.network_id, limit,
     );
-    return Response.json({ ok: true, runs });
+    return Response.json({ ok: true, runs, ...failureSummary(row.schedule_id) });
   }
   if (!sub && req.method === "GET") return Response.json({ ok: true, schedule: decodeRow(row) });
   if (!writeAllowed(ctx, row.network_id)) return jsonError("permission_denied", 403);