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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.87",
+  "version": "0.9.0-preview.88",
   "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-notice.ts

@@ -0,0 +1,48 @@
+// Hub 以某个节点的名义发给一个用户的一条通知(#462 登录失效、#464 定时任务卡住)。
+//
+// 走 user_inbox + /events/users/me 的 desktop_message —— 与 send_desktop_message 同一张表、同一条推送,
+// from_session = 节点别名,所以 App 把它显示在**与该节点的会话**里(主动消息)+ 未读角标 + 通知。不新增渠道。
+// 只发给一个人;他不在本网络了就不发。推送在写库之后:收到推送的 App 立刻回读得到这一行。
+
+import { db, uuidv4 } from "./db.js";
+import { getUserNetworkRole } from "./auth.js";
+import { pushUserEvent } from "./push.js";
+
+export type AgentNotice = {
+  networkId: string;
+  userId: string;
+  /** 节点别名:通知出现在与它的会话里。 */
+  fromAlias: string;
+  kind: string;
+  title: string;
+  text: string;
+  severity?: "info" | "warning" | "error";
+  meta: Record<string, unknown>;
+  /** 消息 id 前缀(`dm_` 开头,与 App 的去重键同一套)。 */
+  idPrefix: string;
+};
+
+/** 返回 message_id;没发(收件人不在本网络)→ null。 */
+export function sendAgentNotice(n: AgentNotice): string | null {
+  if (!getUserNetworkRole(n.userId, n.networkId)) return null;
+  const messageId = `${n.idPrefix}${uuidv4()}`;
+  const severity = n.severity ?? "warning";
+  db.run(
+    `INSERT INTO user_inbox (message_id, network_id, user_id, from_session, kind, title, content, severity, meta_json)
+     VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)
+     ON CONFLICT(message_id) DO NOTHING`,
+    [messageId, n.networkId, n.userId, n.fromAlias, n.kind, n.title, n.text, severity, JSON.stringify(n.meta)],
+  );
+  pushUserEvent(n.networkId, n.userId, {
+    type: "desktop_message",
+    message_id: messageId,
+    kind: n.kind,
+    from: n.fromAlias,
+    title: n.title,
+    message: n.text,
+    severity,
+    created_at: new Date().toISOString(),
+    meta: n.meta,
+  });
+  return messageId;
+}

package/src/db.ts

@@ -1,6 +1,6 @@
-import { createAdapter, type DbAdapter } from "./db-adapter";
+import { createAdapter, type DbAdapter } from "./db-adapter"; import { withStatementHook } from "./status-read-cache"; // #431 写 sessions 的语句让 /api/status 缓存失效
 
-export const db: DbAdapter = createAdapter();
+export const db: DbAdapter = withStatementHook(createAdapter());
 
 // Schema
 db.exec(`

package/src/http-gzip.ts

@@ -56,7 +56,9 @@ function gzipCached(key: string | undefined, raw: () => Promise<Uint8Array>): Pr
   }
   return raw().then(bytes => {
     if (bytes.byteLength < GZIP_MIN_BYTES) return { raw: bytes, gz: null };
-    const gz = Bun.gzipSync(bytes);
+    // 可复用的正文(带键)压一次、存起来、反复发:压缩级别拉到 9 —— 多花的那点 CPU 只花一次,
+    // 而线上每次都少发 ~3%(#431 实测:旧节点别名解析读 29.6 KB → 28.6 KB)。不带键的照旧默认级别。
+    const gz = key ? Bun.gzipSync(bytes, { level: 9 }) : Bun.gzipSync(bytes);
     if (key) gzipCacheStats.misses++;
     if (key && gz.byteLength <= GZIP_CACHE_MAX_BYTES / 4) {
       gzipCache.set(key, gz);

package/src/model-auth-notify.ts

@@ -15,12 +15,11 @@
 //
 // 收件人 = 节点主人:上报令牌绑定的 nodes.owner_user_id(RFC-036,建节点时定死),没有绑定(老令牌)就取
 //   铸这个节点令牌的用户(api_tokens.user_id —— 新令牌里两者相同)。只发给这一个人;不在本网络了就不发。
-// 怎么送:user_inbox(与 send_desktop_message 同一张表、同一条 /events/users/me 推送),from_session = 节点别名,
-//   所以 App 把它显示在**与该节点的会话**里(主动消息)+ 未读角标 + 通知。不新增渠道。
+// 怎么送:agent-notice.ts(user_inbox + /events/users/me,from_session = 节点别名)。
 
-import { db, uuidv4 } from "./db.js";
+import { db } from "./db.js";
 import { getUserNetworkRole } from "./auth.js";
-import { pushUserEvent } from "./push.js";
+import { sendAgentNotice } from "./agent-notice.js";
 import { degradedLayers } from "./node-health-guard.js";
 import type { NodeHealth } from "./node-health-store.js";
 
@@ -104,26 +103,11 @@ export function noteModelAuthHealth(input: { networkId: string; alias: string; t
     if (prev === undefined && hasUnreadNotice(owner, networkId, alias)) return [];
 
     const { title, text } = modelAuthNoticeText(alias, state);
-    const messageId = `dm_auth_${uuidv4()}`;
-    const meta = { model_auth_notice: { alias, state } };
-    db.run(
-      `INSERT INTO user_inbox (message_id, network_id, user_id, from_session, kind, title, content, severity, meta_json)
-       VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, 'warning', ?8)
-       ON CONFLICT(message_id) DO NOTHING`,
-      [messageId, networkId, owner, alias, MODEL_AUTH_NOTICE_KIND, title, text, JSON.stringify(meta)],
-    );
-    // 推送在写库之后:收到推送的 App 立刻回读得到这一行。
-    pushUserEvent(networkId, owner, {
-      type: "desktop_message",
-      message_id: messageId,
-      kind: MODEL_AUTH_NOTICE_KIND,
-      from: alias,
-      title,
-      message: text,
-      severity: "warning",
-      created_at: new Date().toISOString(),
-      meta,
+    const sent = sendAgentNotice({
+      networkId, userId: owner, fromAlias: alias, kind: MODEL_AUTH_NOTICE_KIND, title, text,
+      meta: { model_auth_notice: { alias, state } }, idPrefix: "dm_auth_",
     });
+    if (!sent) return [];
     return [owner];
   } catch (e: any) {
     console.error(`[model-auth-notify] ${input.alias}: ${e?.message ?? e}`);

package/src/node-health-store.ts

@@ -34,7 +34,22 @@ export type NodeHealth = NonNullable<z.infer<typeof nodeHealthSchema>>;
 const store = new Map<string, { health: NodeHealth; at: number }>();
 const keyOf = (networkId: string | null | undefined, alias: string) => `${networkId ?? "default"}\0${alias}`;
 
+// #431 —— /api/status 的记忆化(status-read-cache.ts)按这两样判断正文还对不对:任何一次上报 → 版本 +1;
+// 任何一份报告过 TTL 的那一刻(degraded / health 字段会消失)→ 由 nodeHealthNextExpiryAt 给出的时刻失效。
+let version = 0;
+export function nodeHealthVersion(): number { return version; }
+/** 最早一份还没过期的报告的过期时刻(ms);一份都没有 → Infinity。 */
+export function nodeHealthNextExpiryAt(now = Date.now()): number {
+  let next = Infinity;
+  for (const v of store.values()) {
+    const at = v.at + NODE_HEALTH_TTL_MS;
+    if (at >= now && at < next) next = at;
+  }
+  return next;
+}
+
 export function recordNodeHealth(networkId: string | null | undefined, alias: string, health: NodeHealth, now = Date.now()): void {
+  version++;
   store.set(keyOf(networkId, alias), { health, at: now });
   // 有界:按 TTL 顺手清掉过期的,别让改过名/删掉的节点在内存里攒着。
   if (store.size > 256) {
@@ -54,4 +69,4 @@ export function readNodeHealth(
 }
 
 /** 测试用。 */
-export function clearNodeHealthStore(): void { store.clear(); }
+export function clearNodeHealthStore(): void { store.clear(); version++; }

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

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

package/src/scheduled-stuck.ts

@@ -0,0 +1,153 @@
+// #464 —— 定时任务被一次没结束的执行卡住:告警 + 超时放行。
+//
+// 现场:overlap=skip 的排程,上一次派出的任务节点一直没有终态回复 → 之后每一次都记成
+//   skipped / previous_run_active,没有超时、也没人被告诉(当天 ~25 分钟,10-01 ~7 小时)。
+//
+// 1. 告警:同一个「卡住的任务」(blocked_by_task_id)连续挡掉 N 次 → 给排程的创建者发**一条**通知
+//    (agent-notice.ts,与 #462 同一条路,出现在与目标节点的会话里)。按挡路的任务计数,所以
+//    一段卡住只发一次;任务一换(下一次真派出去了)自然重新上膛。不依赖内存,Hub 重启不会重发。
+// 2. 超时:挡路的任务开着超过 stuckTimeoutMs(间隔)就按**已有的** expired 状态结束它(同 TTL 巡检:
+//    tasks.status='expired' + 收件箱行置 acked + db.ts 的镜像把这次 run 记成 expired / task_expired),
+//    然后这一次照常派发。任务行不删,照样能查;晚到的回复被 send_reply 以 reply_task_terminal 拒掉,
+//    什么都不改(不重开 run、不碰新派出去的那条)。
+//    如果超时发生在 N 次之前(长间隔的排程,比如每天一次),那一刻补发一条「已超时结束」—— 每段卡住
+//    恰好一条通知。
+//
+// 默认值(PR 里有推导):N=3;超时 = clamp(6 × 间隔, 下限 1 小时, 上限 24 小时)。
+//   下限 1 小时:一轮 agent 任务正常要跑几十分钟,不能因为排程间隔短就把还在干活的任务掐掉。
+//   上限 24 小时:Hub 本来就给定时任务 24 小时的 expires_at(没被取走时由巡检过期),开着超过一天的
+//   定时任务不是「还在做」。6 × 间隔:间隔长的排程(每小时一次)给它 6 小时,而不是 1 小时。
+// 环境变量可改(运维 / 测试):COMMHUB_SCHEDULE_STUCK_NOTICE_SKIPS、COMMHUB_SCHEDULE_STUCK_TIMEOUT_FACTOR、
+//   COMMHUB_SCHEDULE_STUCK_TIMEOUT_FLOOR_SEC、COMMHUB_SCHEDULE_STUCK_TIMEOUT_CAP_SEC。
+
+import { db, syncScheduledRunForTask } from "./db.js";
+import { parseDbTimestampMs } from "./db-timestamp.js";
+import { sendAgentNotice } from "./agent-notice.js";
+
+export const SCHEDULE_STUCK_NOTICE_KIND = "schedule_stuck";
+
+function envNumber(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 ? n : fallback;
+}
+
+export function stuckNoticeSkips(): number {
+  return Math.floor(envNumber("COMMHUB_SCHEDULE_STUCK_NOTICE_SKIPS", 3, 1));
+}
+
+/** 排程的名义间隔(秒):interval 取 every_seconds;daily / weekly 取一天(两次之间最短一天);once 取 0。 */
+export function nominalIntervalSeconds(scheduleJson: string): number {
+  try {
+    const spec = JSON.parse(scheduleJson) as { type?: string; every_seconds?: number };
+    if (spec.type === "interval" && Number.isFinite(spec.every_seconds)) return Number(spec.every_seconds);
+    if (spec.type === "daily" || spec.type === "weekly") return 86_400;
+  } catch {}
+  return 0;
+}
+
+export function stuckTimeoutMs(scheduleJson: string): number {
+  const factor = envNumber("COMMHUB_SCHEDULE_STUCK_TIMEOUT_FACTOR", 6, 0);
+  const floor = envNumber("COMMHUB_SCHEDULE_STUCK_TIMEOUT_FLOOR_SEC", 3_600, 1);
+  const cap = Math.max(floor, envNumber("COMMHUB_SCHEDULE_STUCK_TIMEOUT_CAP_SEC", 86_400, 1));
+  return Math.min(cap, Math.max(floor, factor * nominalIntervalSeconds(scheduleJson))) * 1000;
+}
+
+type Blocker = { task_id: string; created_at: string; status: string };
+
+/** 挡路的任务开了多久已经到超时 → true。读不出时间 = 不超时(宁可多挡一次,不错杀)。 */
+export function blockerTimedOut(blocker: Pick<Blocker, "created_at">, scheduleJson: string, now: Date): boolean {
+  const started = parseDbTimestampMs(blocker.created_at);
+  if (!Number.isFinite(started)) return false;
+  return now.getTime() - started >= stuckTimeoutMs(scheduleJson);
+}
+
+/**
+ * 在调用方的事务里按超时结束挡路的任务。只动还开着的任务(条件写),返回是否真的结束了它。
+ * 与 TTL 巡检(server.ts patrolExpiredTasks)同一套写法:status=expired、收件箱行置 acked、镜像到 run。
+ */
+export function expireStuckBlocker(taskId: string, networkId: string, ageMs: number, limitMs: number): boolean {
+  const changed = db.run(
+    `UPDATE tasks SET status = 'expired', completed_at = datetime('now')
+      WHERE task_id = ?1 AND network_id = ?2 AND status IN ('created', 'delivered', 'acked', 'running')`,
+    [taskId, networkId],
+  );
+  if (changed.changes < 1) return false;
+  db.run("UPDATE inbox SET acked = 1 WHERE COALESCE(task_id, id) = ?1 AND acked = 0", [taskId]);
+  syncScheduledRunForTask(taskId, networkId);
+  db.run(
+    "UPDATE scheduled_task_runs SET error_message = ?1 WHERE task_id = ?2 AND network_id = ?3",
+    [`timed out by the scheduler: open for ${Math.round(ageMs / 60_000)} min (limit ${Math.round(limitMs / 60_000)} min); the next occurrence was dispatched`, taskId, networkId],
+  );
+  return true;
+}
+
+/** 这个任务已经挡掉了几次(只算 previous_run_active 的跳过)。 */
+export function skipsBlockedBy(scheduleId: string, taskId: string): number {
+  return db.get<{ n: number }>(
+    "SELECT COUNT(*) AS n FROM scheduled_task_runs WHERE schedule_id = ?1 AND blocked_by_task_id = ?2 AND error_code = 'previous_run_active'",
+    scheduleId, taskId,
+  )?.n ?? 0;
+}
+
+export type StuckNotice = {
+  reason: "stuck" | "timed_out";
+  scheduleId: string;
+  scheduleName: string;
+  networkId: string;
+  createdBy: string | null;
+  alias: string;
+  timezone: string;
+  taskId: string;
+  taskCreatedAt: string;
+  skips: number;
+  timeoutMs: number;
+};
+
+function fmtTime(dbTs: string, timezone: string): string {
+  const ms = parseDbTimestampMs(dbTs);
+  if (!Number.isFinite(ms)) return dbTs;
+  try {
+    const s = new Intl.DateTimeFormat("sv-SE", { timeZone: timezone, year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit", hourCycle: "h23" }).format(new Date(ms));
+    return `${s} (${timezone})`;
+  } catch { return dbTs; }
+}
+
+function fmtDuration(ms: number): string {
+  const min = Math.round(ms / 60_000);
+  if (min < 60) return `${min} 分钟`;
+  const h = Math.floor(min / 60), m = min % 60;
+  return m ? `${h} 小时 ${m} 分钟` : `${h} 小时`;
+}
+
+export function stuckNoticeText(n: StuckNotice): { title: string; text: string } {
+  const started = fmtTime(n.taskCreatedAt, n.timezone);
+  if (n.reason === "stuck") {
+    return {
+      title: "定时任务被卡住",
+      text: `定时任务「${n.scheduleName}」被上一次的执行卡住了:任务 ${n.taskId} 于 ${started} 派给节点 ${n.alias},到现在还没有完成,之后的 ${n.skips} 次执行都被跳过。\n\n`
+        + `它开着超过 ${fmtDuration(n.timeoutMs)} 后会被自动按超时结束,下一次照常派发。等不及可以在任务列表里取消这条任务。`,
+    };
+  }
+  return {
+    title: "定时任务已超时放行",
+    text: `定时任务「${n.scheduleName}」上一次的任务 ${n.taskId}(${started} 派给节点 ${n.alias})开着超过 ${fmtDuration(n.timeoutMs)} 还没有完成,已按超时结束,不再挡后面的执行。`,
+  };
+}
+
+/** 提交之后调用。没有创建者 / 创建者不在网络里 → 不发。 */
+export function sendStuckNotice(n: StuckNotice): string | null {
+  if (!n.createdBy) return null;
+  try {
+    const { title, text } = stuckNoticeText(n);
+    return sendAgentNotice({
+      networkId: n.networkId, userId: n.createdBy, fromAlias: n.alias, kind: SCHEDULE_STUCK_NOTICE_KIND, title, text,
+      meta: { schedule_stuck: { reason: n.reason, schedule_id: n.scheduleId, blocked_by_task_id: n.taskId, skips: n.skips } },
+      idPrefix: "dm_sched_",
+    });
+  } catch (e: any) {
+    console.error(`[scheduled-tasks] stuck notice failed schedule=${n.scheduleId}: ${e?.message || e}`);
+    return null;
+  }
+}

package/src/scheduled-tasks.ts

@@ -5,6 +5,8 @@ import { addNetworkScope, canRestWriteNetwork, singleNetworkId, type RestNetwork
 import { canMessageAgent } from "./agent-access.js";
 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";
 
 export type ScheduleSpec =
   | { type: "once"; run_at: string }
@@ -203,6 +205,13 @@ function validateTarget(networkId: string, nodeId: unknown): { node_id: string;
   return { node_id: node.node_id, alias: node.alias };
 }
 
+function stuckNoticeFor(row: ScheduledRow, reason: StuckNotice["reason"], blocker: { task_id: string; created_at: string }, skips: number, timeoutMs: number): StuckNotice {
+  return {
+    reason, scheduleId: row.schedule_id, scheduleName: row.name, networkId: row.network_id, createdBy: row.created_by,
+    alias: row.target_alias, timezone: row.timezone, taskId: blocker.task_id, taskCreatedAt: blocker.created_at, skips, timeoutMs,
+  };
+}
+
 type DispatchEvent = { alias: string; networkId: string; taskId: string; priority: string; state: "delivered" | "queued" };
 
 export function dispatchScheduledOccurrence(row: ScheduledRow, scheduledFor: string, advanceSchedule: boolean, advanceAfter = new Date()): { runId: string; taskId?: string; status: string; event?: DispatchEvent } {
@@ -210,6 +219,8 @@ export function dispatchScheduledOccurrence(row: ScheduledRow, scheduledFor: str
   let event: DispatchEvent | undefined;
   let finalStatus = "failed";
   let createdTaskId: string | undefined;
+  const notices: StuckNotice[] = [];
+  const timedOut: Array<{ taskId: string; fromStatus: string }> = [];
 
   db.transaction(() => {
     // UNIQUE(schedule_id, scheduled_for) is the cross-process claim. If two
@@ -225,8 +236,8 @@ export function dispatchScheduledOccurrence(row: ScheduledRow, scheduledFor: str
       // received:节点那边有没有把这条任务取走过(inbox 行被 ack,或任务已进 acked/running)。
       // 跳过记录带上它,客户端才分得清「节点还没收到」和「节点在处理」—— 前者是投递故障,
       // 后者才是真的上一次还没做完。
-      const open = db.get<{ task_id: string; received: number }>(
-        `SELECT r.task_id,
+      const findOpen = () => db.get<{ task_id: string; received: number; created_at: string; status: string }>(
+        `SELECT r.task_id, t.created_at, t.status,
                 CASE WHEN t.status IN ('acked', 'running')
                        OR EXISTS (SELECT 1 FROM inbox i WHERE (i.task_id = r.task_id OR i.id = r.task_id) AND i.acked = 1)
                      THEN 1 ELSE 0 END AS received
@@ -236,6 +247,20 @@ export function dispatchScheduledOccurrence(row: ScheduledRow, scheduledFor: str
          ORDER BY r.created_at DESC LIMIT 1`,
         row.schedule_id, ...OPEN_TASK_STATUSES,
       );
+      let open = findOpen();
+      // #464 — a blocker open past the stuck timeout is ended as `expired` (the existing terminal state) and
+      // this occurrence dispatches normally. Bounded: each pass ends one exact open task or stops.
+      for (let guard = 0; open && guard < 20 && blockerTimedOut(open, row.schedule_json, advanceAfter); guard++) {
+        const limitMs = stuckTimeoutMs(row.schedule_json);
+        const ageMs = advanceAfter.getTime() - parseDbTimestampMs(open.created_at);
+        if (!expireStuckBlocker(open.task_id, row.network_id, ageMs, limitMs)) break;
+        timedOut.push({ taskId: open.task_id, fromStatus: open.status });
+        // Each stuck episode gets exactly one notice: if the stuck notice already went out (N skips), stay quiet.
+        if (skipsBlockedBy(row.schedule_id, open.task_id) < stuckNoticeSkips()) {
+          notices.push(stuckNoticeFor(row, "timed_out", open, skipsBlockedBy(row.schedule_id, open.task_id), limitMs));
+        }
+        open = findOpen();
+      }
       if (open) {
         finalStatus = "skipped";
         const blockedState = open.received ? "in_progress" : "not_received";
@@ -251,6 +276,9 @@ export function dispatchScheduledOccurrence(row: ScheduledRow, scheduledFor: str
             blockedState,
           ],
         );
+        // #464 — the Nth consecutive skip behind the same task tells the schedule's creator, once.
+        const skips = skipsBlockedBy(row.schedule_id, open.task_id);
+        if (skips === stuckNoticeSkips()) notices.push(stuckNoticeFor(row, "stuck", open, skips, stuckTimeoutMs(row.schedule_json)));
         if (advanceSchedule) advance(row, scheduledFor, advanceAfter);
         return;
       }
@@ -349,6 +377,8 @@ export function dispatchScheduledOccurrence(row: ScheduledRow, scheduledFor: str
   // never turn a durably-created task into an API-level failure: callers may
   // retry an apparent failure and create a second manual occurrence.
   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);
     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);

package/src/server.ts

@@ -1,5 +1,6 @@
 import { buildServeErrorResponse } from "./serve-error.js";
-import { maybeGzipResponse, trimLightTask } from "./http-gzip";
+import { markGzipReusable, maybeGzipResponse, trimLightTask } from "./http-gzip";
+import { ifNoneMatchHits, memoStatusBody } from "./status-read-cache";
 import { statusAliasResolverRead } from "./status-alias-resolver.js";
 import { readNodeHealth } from "./node-health-store.js";
 import { assertNodeHealthy, degradedLayers } from "./node-health-guard.js";
@@ -2310,6 +2311,11 @@ return Bun.serve({
         sql += ` AND node_id = ?${params.length}`;
       }
       sql += " ORDER BY updated_at DESC";
+      // #431 —— 同一份正文不重复算(status-read-cache.ts):键 = 最终 SQL + 参数(含调用者能看到谁)+ 投影;
+      // 写 sessions / 健康上报 / 健康过期就失效。正文逐字节等于当场重算(status-read-cache-http.test.ts)。
+      const memoKey = JSON.stringify([sql, params, isLight, withNodeId]);
+      const { body: statusBody, etag: statusEtag } = memoStatusBody(memoKey, () => {
+      let timeDependent = false;
       // `model` comes straight from the explicit sessions projection; `runtime` is
       // derived from the raw `agent` field. Both default to null for old nodes
       // that never reported a model — the dashboard falls back to a placeholder.
@@ -2372,6 +2378,8 @@ return Bun.serve({
           // null = not reported / stale / older agent-node — never "healthy".
           ...(() => {
             const h = readNodeHealth(s.network_id, s.alias);
+            // health_observed_ms_ago 随时间走:带上它的正文不能缓存。
+            if (h) timeDependent = true;
             return { health: h?.health ?? null, health_observed_ms_ago: h?.observed_ms_ago ?? null };
           })(),
           ...degradedField(s.network_id, s.alias),
@@ -2384,8 +2392,16 @@ return Bun.serve({
         else acc.idle++;
         return acc;
       }, { idle: 0, working: 0, offline: 0, total: sessions.length });
-      const res = Response.json({ ok: true, sessions, summary });
-      if (aliasResolverRead) res.headers.set("X-Status-Projection", "alias-resolver");
+      return { body: JSON.stringify({ ok: true, sessions, summary }), cacheable: !timeDependent };
+      });
+      // 强 ETag = 正文哈希;If-None-Match 命中回 304 空体(旧 agent-node 不发,app / dashboard 接上后受益)。
+      const statusHeaders: Record<string, string> = { ETag: statusEtag, "Cache-Control": "private, no-cache" };
+      if (aliasResolverRead) statusHeaders["X-Status-Projection"] = "alias-resolver";
+      if (ifNoneMatchHits(req.headers.get("if-none-match"), statusEtag)) {
+        return withCors(req, new Response(null, { status: 304, headers: statusHeaders }));
+      }
+      // Content-Type 与 Response.json 的一致;同一份正文的 gzip 结果按 ETag 复用(http-gzip.ts)。
+      const res = markGzipReusable(new Response(statusBody, { headers: { ...statusHeaders, "Content-Type": "application/json;charset=utf-8" } }), statusEtag);
       return withCors(req, res);
     }
 

package/src/status-read-cache-http.test.ts

@@ -0,0 +1,229 @@
+// #431 —— GET /api/status 记忆化 + 强 ETag(status-read-cache.ts)。钉住:
+//   - 正文逐字节不变:随机写序列(改 sessions、健康上报、健康过期、改名清理)之后,每种读法「可能命中缓存的那一份」
+//     都等于「清空缓存当场重算的那一份」;而且确实命中过(不是全靠重算凑出来的绿);
+//   - JSON.stringify 与原来的 Response.json 对这些正文逐字节一致;Content-Type 不变;
+//   - 不同调用者(另一个网络的用户、节点令牌的别名解析读法)键不串;
+//   - 全量投影里有健康报告(health_observed_ms_ago 随时间走)就不缓存;
+//   - ETag / If-None-Match → 304;gzip 解开等于原文。
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { gunzipSync } from "zlib";
+import { register, createNetworkTokenForNode } from "./auth.js";
+import { db } from "./db.js";
+import { clearNodeHealthStore, recordNodeHealth, NODE_HEALTH_TTL_MS } from "./node-health-store.js";
+import { __resetStatusCacheForTest, __setStatusCacheBypassForTest, noteStatement, statusCacheStats, statusWriteGeneration } from "./status-read-cache.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-status-read-cache-"));
+let BASE = "";
+let hub: any = null;
+const PW = "StatusReadCachePassw0rd!";
+let userToken = "", userId = "", NET = "", nodeToken = "", otherToken = "", OTHER_NET = "";
+const ROWS = 60;
+
+// 时间戳在 JS 里算好再绑定(SQLite 的 datetime('now', …) 拼接在 PostgreSQL 上没有,这份测试两种库都跑)。
+const ts = (offsetSec: number) => new Date(Date.now() + offsetSec * 1000).toISOString().replace("T", " ").slice(0, 19);
+function seed(i: number) {
+  const node = `node_src_${i}`, alias = i % 2 ? `示例-${i}` : `src-${i}`;
+  db.run(`INSERT INTO nodes (node_id, node_name, alias, network_id, owner_user_id) VALUES (?1, ?2, ?2, ?3, ?4)`, [node, alias, NET, userId]);
+  db.run(
+    `INSERT INTO sessions (resume_id, alias, node_id, status, network_id, task, output, project_dir, hostname, server, agent, version,
+       cpu_load_1min, mem_total_gb, process_rss_bytes, external_schedules, updated_at, last_seen_at, registered_at)
+     VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?9, ?10, '2.5.0-preview.88', '1.5', '61.4', 121868288, ?11,
+       ?12, ?13, '2026-09-01 00:00:00')`,
+    [`r_${node}`, alias, node, i % 3 ? "idle" : "offline", NET, `示例任务 ${i}:\n  "引号" \\ 反斜杠 
 `.repeat(1 + (i % 5)),
+      i % 4 ? null : `示例输出 ${i}`, `/home/user/project-${i}`, `sample-host-${i % 4}`,
+      i % 2 ? "agent-node:codex-app-server" : "claude-code", i % 3 ? null : JSON.stringify([{ id: `s${i}`, every: 60 }]), ts(-i), ts(0)],
+  );
+}
+
+async function get(path: string, headers: Record<string, string>) {
+  const res = await fetch(`${BASE}${path}`, { headers });
+  const buf = new Uint8Array(await res.arrayBuffer());
+  return { status: res.status, buf, headers: res.headers };
+}
+const text = (b: Uint8Array) => new TextDecoder().decode(b);
+
+type Variant = { name: string; path: () => string; headers: () => Record<string, string> };
+const VARIANTS: Variant[] = [
+  { name: "user full", path: () => `/api/status?network_id=${NET}`, headers: () => ({ Authorization: `Bearer ${userToken}` }) },
+  { name: "user light", path: () => `/api/status?network_id=${NET}&light=1`, headers: () => ({ Authorization: `Bearer ${userToken}` }) },
+  { name: "user alias", path: () => `/api/status?network_id=${NET}&alias=${encodeURIComponent("示例-7")}`, headers: () => ({ Authorization: `Bearer ${userToken}` }) },
+  { name: "node light node_id", path: () => `/api/status?network_id=${NET}&light=1&node_id=node_src_9`, headers: () => ({ Authorization: `Bearer ${nodeToken}` }) },
+  { name: "old alias resolver", path: () => `/api/status?network_id=${NET}`, headers: () => ({ Authorization: `Bearer ${nodeToken}`, Accept: "application/json" }) },
+  { name: "node full=1", path: () => `/api/status?network_id=${NET}&full=1`, headers: () => ({ Authorization: `Bearer ${nodeToken}`, Accept: "application/json" }) },
+  { name: "other network user", path: () => `/api/status?network_id=${OTHER_NET}`, headers: () => ({ Authorization: `Bearer ${otherToken}` }) },
+];
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+  process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+  process.env.HOST = "127.0.0.1";
+  const a = register(`src_owner_${Date.now()}`, PW);
+  userToken = a.token!; userId = a.user!.user_id; NET = a.network_id!;
+  for (let i = 0; i < ROWS; i++) seed(i);
+  nodeToken = createNetworkTokenForNode(userId, NET, "src-8", "node_src_8").token!;
+  const b = register(`src_other_${Date.now()}`, PW);
+  otherToken = b.token!; OTHER_NET = b.network_id!;
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("write detection", () => {
+  test("writes that name sessions bump the generation; reads and other tables do not", () => {
+    const g = statusWriteGeneration();
+    noteStatement("SELECT * FROM sessions");
+    noteStatement("UPDATE tasks SET status = 'x'");
+    noteStatement("INSERT INTO inbox (id) VALUES (1)");
+    expect(statusWriteGeneration()).toBe(g);
+    noteStatement("  update sessions set status='idle'");
+    noteStatement("INSERT INTO sessions (resume_id) VALUES ('x') RETURNING resume_id");
+    noteStatement("DELETE FROM sessions WHERE alias = 'x'");
+    noteStatement("WITH t AS (SELECT 1) UPDATE sessions SET task = NULL");
+    expect(statusWriteGeneration()).toBe(g + 4);
+  });
+
+  test("the hook sits on the shared db adapter (every module's writes go through it)", () => {
+    const g = statusWriteGeneration();
+    db.run("UPDATE sessions SET progress = progress WHERE 1=0");
+    expect(statusWriteGeneration()).toBe(g + 1);
+  });
+
+  test("no foreign key / trigger can change sessions without naming it", () => {
+    if (db.dialect === "postgres") {
+      const fks = db.all<{ c: number }>(`SELECT COUNT(*) AS c FROM information_schema.referential_constraints rc
+        JOIN information_schema.table_constraints tc ON tc.constraint_name = rc.unique_constraint_name WHERE tc.table_name = 'sessions'`);
+      expect(Number(fks[0]?.c ?? 0)).toBe(0);
+      const trg = db.all<{ c: number }>(`SELECT COUNT(*) AS c FROM information_schema.triggers WHERE action_statement ILIKE '%sessions%' OR event_object_table = 'sessions'`);
+      expect(Number(trg[0]?.c ?? 0)).toBe(0);
+      return;
+    }
+    const fks = db.all<{ sql: string }>("SELECT sql FROM sqlite_master WHERE sql IS NOT NULL").map(r => r.sql);
+    expect(fks.filter(s => /references\s+sessions\b/i.test(s))).toEqual([]);
+    expect(fks.filter(s => /create\s+trigger/i.test(s) && /\bsessions\b/i.test(s))).toEqual([]);
+  });
+});
+
+describe("GET /api/status bodies are byte-identical with the cache", () => {
+  test("random writes / health reports / expiry: cached == recomputed, and the cache is really used", async () => {
+    __resetStatusCacheForTest();
+    let rnd = 461;
+    const r = () => (rnd = (rnd * 1103515245 + 12345) % 2147483648) / 2147483648;
+    let compared = 0, hits = 0;
+    for (let step = 0; step < 60; step++) {
+      const op = Math.floor(r() * 6);
+      const i = Math.floor(r() * ROWS);
+      const alias = i % 2 ? `示例-${i}` : `src-${i}`;
+      if (op === 0) db.run(`UPDATE sessions SET status = ?1, updated_at = ?2 WHERE node_id = ?3`, [r() < 0.5 ? "idle" : "working", ts(step), `node_src_${i}`]);
+      if (op === 1) db.run(`UPDATE sessions SET task = ?1 WHERE node_id = ?2`, [`新任务 ${step}`, `node_src_${i}`]);
+      if (op === 2) recordNodeHealth(NET, alias, { bridge: "ok", app_server: { ok: r() < 0.5, rtt_ms: 3, last_error: null }, model_auth: "ok" });
+      if (op === 3) {
+        // A report that expires a few ms from now: the degraded field must disappear on time.
+        recordNodeHealth(NET, alias, { bridge: "ok", app_server: { ok: false, rtt_ms: null, last_error: "closed (code=1006)" }, model_auth: "ok" }, Date.now() - NODE_HEALTH_TTL_MS + 30);
+        await Bun.sleep(40);
+      }
+      if (op === 4) db.run(`UPDATE sessions SET alias = ?1 WHERE node_id = ?2`, [`${alias}-改`, `node_src_${i}`]);
+      // op 5: no write at all — the next reads must be cache hits for the cacheable variants.
+      for (const v of VARIANTS) {
+        const first = await get(v.path(), v.headers());
+        const before = statusCacheStats.hits;
+        const again = await get(v.path(), v.headers());
+        hits += statusCacheStats.hits - before;
+        // Fresh = recomputed right now, without dropping what the cache holds (stale entries must stay in play
+        // across steps — clearing here would hide a missed invalidation).
+        __setStatusCacheBypassForTest(true);
+        const fresh = await get(v.path(), v.headers()).finally(() => __setStatusCacheBypassForTest(false));
+        expect(first.status).toBe(200);
+        const norm = (b: Uint8Array) => text(b).replace(/"health_observed_ms_ago":\d+/g, '"health_observed_ms_ago":0');
+        expect(norm(first.buf)).toBe(norm(fresh.buf));
+        expect(norm(again.buf)).toBe(norm(fresh.buf));
+        if (!text(fresh.buf).includes('"health_observed_ms_ago":')) expect(text(again.buf)).toBe(text(fresh.buf));
+        compared++;
+      }
+    }
+    expect(compared).toBe(60 * VARIANTS.length);
+    // Cacheable variants (everything except a full body carrying a health report) read twice in a row must hit.
+    expect(hits).toBeGreaterThan(60 * 4);
+  }, 120_000);
+
+  test("JSON.stringify == Response.json for these bodies; headers keep Content-Type, add ETag", async () => {
+    for (const v of VARIANTS) {
+      const res = await get(v.path(), v.headers());
+      const body = text(res.buf);
+      expect(await Response.json(JSON.parse(body)).text()).toBe(body);
+      expect(res.headers.get("content-type")).toBe("application/json;charset=utf-8");
+      expect(res.headers.get("etag")).toMatch(/^"s-[0-9a-z]+-[0-9a-z]+"$/);
+    }
+  });
+
+  test("keys do not leak across callers", async () => {
+    const owner = JSON.parse(text((await get(`/api/status?network_id=${NET}`, { Authorization: `Bearer ${userToken}` })).buf));
+    const other = JSON.parse(text((await get(`/api/status?network_id=${OTHER_NET}`, { Authorization: `Bearer ${otherToken}` })).buf));
+    expect(owner.sessions.length).toBe(ROWS);
+    expect(other.sessions.length).toBe(0);
+    const resolver = await get(`/api/status?network_id=${NET}`, { Authorization: `Bearer ${nodeToken}`, Accept: "application/json" });
+    expect(resolver.headers.get("x-status-projection")).toBe("alias-resolver");
+    expect(Object.keys(JSON.parse(text(resolver.buf)).sessions[0])).not.toContain("host");
+  });
+
+  test("a health report expiring (no write at all) invalidates the cached body on time", async () => {
+    __resetStatusCacheForTest();
+    clearNodeHealthStore();
+    const v = VARIANTS[1]; // user light: carries `degraded` for a fresh down app_server
+    const [{ alias: target }] = db.all<{ alias: string }>("SELECT alias FROM sessions WHERE node_id = 'node_src_2'");
+    recordNodeHealth(NET, target, { bridge: "ok", app_server: { ok: false, rtt_ms: null, last_error: "closed (code=1006)" }, model_auth: "ok" }, Date.now() - NODE_HEALTH_TTL_MS + 1_500);
+    const during = text((await get(v.path(), v.headers())).buf);
+    expect(during).toContain('"degraded":[{"layer":"app_server"');
+    const hitsBefore = statusCacheStats.hits;
+    expect(text((await get(v.path(), v.headers())).buf)).toBe(during);
+    expect(statusCacheStats.hits).toBe(hitsBefore + 1); // it was cached
+    await Bun.sleep(1_600);
+    const after = text((await get(v.path(), v.headers())).buf);
+    expect(after).not.toContain('"degraded"');
+    __resetStatusCacheForTest();
+    expect(text((await get(v.path(), v.headers())).buf)).toBe(after);
+  });
+
+  test("full projection with a health report is not cached (its body moves with time)", async () => {
+    __resetStatusCacheForTest();
+    recordNodeHealth(NET, "src-0", { bridge: "ok", model_auth: "ok" });
+    const v = VARIANTS[0];
+    const a = text((await get(v.path(), v.headers())).buf);
+    await Bun.sleep(15);
+    const b = text((await get(v.path(), v.headers())).buf);
+    expect(statusCacheStats.uncacheable).toBeGreaterThanOrEqual(2);
+    expect(a).not.toBe(b); // health_observed_ms_ago moved — a cached copy would have frozen it
+  });
+});
+
+describe("ETag / 304 / gzip", () => {
+  test("If-None-Match with the current ETag → 304 empty; after a write → 200 with a new ETag", async () => {
+    const h = { Authorization: `Bearer ${nodeToken}`, Accept: "application/json" };
+    const first = await get(`/api/status?network_id=${NET}`, h);
+    const etag = first.headers.get("etag")!;
+    const not = await get(`/api/status?network_id=${NET}`, { ...h, "If-None-Match": etag });
+    expect(not.status).toBe(304);
+    expect(not.buf.byteLength).toBe(0);
+    expect(not.headers.get("x-status-projection")).toBe("alias-resolver");
+    db.run(`UPDATE sessions SET status = 'working', updated_at = ?1 WHERE node_id = 'node_src_3'`, [ts(120)]);
+    const changed = await get(`/api/status?network_id=${NET}`, { ...h, "If-None-Match": etag });
+    expect(changed.status).toBe(200);
+    expect(changed.headers.get("etag")).not.toBe(etag);
+  });
+
+  test("gzip (the old node's Accept-Encoding: gzip, deflate) decodes to the same bytes", async () => {
+    const h = { Authorization: `Bearer ${nodeToken}`, Accept: "application/json" };
+    const plain = await get(`/api/status?network_id=${NET}`, h);
+    const res = await fetch(`${BASE}/api/status?network_id=${NET}`, { headers: { ...h, "Accept-Encoding": "gzip, deflate" }, decompress: false } as any);
+    expect(res.headers.get("content-encoding")).toBe("gzip");
+    const raw = new Uint8Array(await res.arrayBuffer());
+    expect(text(gunzipSync(raw))).toBe(text(plain.buf));
+  });
+});

package/src/status-read-cache.ts

@@ -0,0 +1,108 @@
+// #431(app「连接较慢」)—— GET /api/status 的序列化结果记忆化 + 强 ETag。
+//
+// 现场(2026-10-02 生产 /api/stats/routes,15 分钟窗口):GET /api/status 2000 次 ≈ 2.2 次/秒,全部来自 UA「node」
+// (旧版 agent-node 的别名解析器,.82 起给它 light+node_id 投影),线上平均 30 KB/次(已经是 gzip 后的字节:
+// node 的 fetch 发 `Accept-Encoding: gzip, deflate`)。两次读之间表多半没变(report_status 约 0.75 次/秒),
+// 但每次都重新 SELECT 300 行、拼对象、JSON.stringify、再 gzip 一遍。
+//
+// 这里只做「同一份正文不重复算」,**不改任何正文**:
+//   键 = 最终 SQL + 参数(里面已经编码了调用者能看到哪些节点)+ 投影开关;
+//   失效 = 任何写 sessions 表的语句(db.ts 里统一挂钩,SQLite / PG 同一处)、任何健康上报、
+//          任何一份健康报告过 TTL(那一刻 degraded / health 字段会变)。
+//   全量投影里 `health_observed_ms_ago` 随时间走:只要有一行带健康报告,这份正文就是时间的函数,不缓存。
+// 命中时正文和当场重算逐字节相同(status-read-cache-http.test.ts 用随机写序列钉住)。
+//
+// ETag:正文的哈希,`If-None-Match` 命中回 304 空体。🔴 旧 agent-node 不发 If-None-Match(fetch 没有 HTTP 缓存),
+// 所以 ETag 只帮得上会带它的客户端(app / dashboard 以后接上);隧道上省字节靠的是同一份 gzip 只压一次
+// 且用更高的压缩级别(http-gzip.ts:可复用的正文压一次、存起来,级别 9)。
+
+import type { DbAdapter } from "./db-adapter";
+import { nodeHealthNextExpiryAt, nodeHealthVersion } from "./node-health-store.js";
+
+let sessionsWriteGen = 0;
+
+const WRITE_START = /^\s*(?:insert|update|delete|replace|upsert|merge|alter|drop|create|truncate|with)\b/i;
+const SESSIONS_WORD = /\bsessions\b/i;
+
+/**
+ * 每条经过 db 的语句都过一遍。写语句(含带 RETURNING 的、DDL)里点名了 sessions → 代数 +1。读语句不动。
+ * 不会有「没点名 sessions 却改了它」的写:两种方言的 schema 里都没有指向 sessions 的外键 / 级联删除
+ * (status-read-cache.test.ts 钉住这一点)。
+ */
+export function noteStatement(sql: string): void {
+  if (WRITE_START.test(sql) && SESSIONS_WORD.test(sql)) sessionsWriteGen++;
+}
+
+/** 原生 exec(迁移 / DDL / 多语句):不逐句判断,一律失效。 */
+export function noteExec(): void { sessionsWriteGen++; }
+
+export function statusWriteGeneration(): number { return sessionsWriteGen; }
+
+/**
+ * db.ts 用它包住唯一的那个适配器:每条语句先报给上面两个函数。挂在这一个出口上,SQLite / PG 一样,
+ * 不靠每个写 sessions 的地方各自记得。直接换掉实例上的四个方法(不用 Proxy):有测试按 `db.all = …`
+ * 临时打桩数查询次数,方法得是普通可写属性。
+ */
+export function withStatementHook(inner: DbAdapter): DbAdapter {
+  const run = inner.run.bind(inner), get = inner.get.bind(inner), all = inner.all.bind(inner), exec = inner.exec.bind(inner);
+  inner.run = (sql: string, params?: any[]) => { noteStatement(sql); return run(sql, params); };
+  inner.get = ((sql: string, ...params: any[]) => { noteStatement(sql); return get(sql, ...params); }) as DbAdapter["get"];
+  inner.all = ((sql: string, ...params: any[]) => { noteStatement(sql); return all(sql, ...params); }) as DbAdapter["all"];
+  inner.exec = (sql: string) => { noteExec(); return exec(sql); };
+  return inner;
+}
+
+type Entry = { gen: number; healthVer: number; validUntil: number; body: string; etag: string };
+const MAX_ENTRIES = 64;
+const memo = new Map<string, Entry>();
+export const statusCacheStats = { hits: 0, misses: 0, uncacheable: 0 };
+
+function etagOf(body: string): string {
+  return `"s-${Bun.hash(body).toString(36)}-${body.length.toString(36)}"`;
+}
+
+/**
+ * 取或算。compute 返回正文和它能不能缓存(全量投影里有健康报告 = 正文随时间变 = 不能)。
+ * 返回的 etag 总是这份正文的哈希(不缓存的也给,便于 304)。
+ */
+let bypass = false;
+/** 测试用:临时绕过缓存(既不读也不写),拿「当场重算」的那一份来对比,而不清掉缓存里已有的条目。 */
+export function __setStatusCacheBypassForTest(on: boolean): void { bypass = on; }
+
+export function memoStatusBody(key: string, compute: () => { body: string; cacheable: boolean }, now = Date.now()): { body: string; etag: string; hit: boolean } {
+  if (bypass) { const { body } = compute(); return { body, etag: etagOf(body), hit: false }; }
+  const gen = sessionsWriteGen;
+  const healthVer = nodeHealthVersion();
+  const hit = memo.get(key);
+  if (hit && hit.gen === gen && hit.healthVer === healthVer && now < hit.validUntil) {
+    statusCacheStats.hits++;
+    memo.delete(key);
+    memo.set(key, hit); // LRU
+    return { body: hit.body, etag: hit.etag, hit: true };
+  }
+  const { body, cacheable } = compute();
+  const etag = etagOf(body);
+  // 以算之前的代数入账:算的过程中若有写(改名清理之类),下一次比较就对不上、重算 —— 宁可多算一次也不发旧正文。
+  if (!cacheable) {
+    statusCacheStats.uncacheable++;
+    memo.delete(key);
+    return { body, etag, hit: false };
+  }
+  statusCacheStats.misses++;
+  memo.set(key, { gen, healthVer, validUntil: nodeHealthNextExpiryAt(now), body, etag });
+  while (memo.size > MAX_ENTRIES) memo.delete(memo.keys().next().value as string);
+  return { body, etag, hit: false };
+}
+
+/** If-None-Match 里有这个 ETag(或 `*`)。弱比较:去掉 W/ 前缀。 */
+export function ifNoneMatchHits(header: string | null, etag: string): boolean {
+  if (!header) return false;
+  const bare = (t: string) => t.trim().replace(/^W\//, "");
+  return header.split(",").some((t) => t.trim() === "*" || bare(t) === bare(etag));
+}
+
+/** 测试用。 */
+export function __resetStatusCacheForTest(): void {
+  memo.clear();
+  statusCacheStats.hits = statusCacheStats.misses = statusCacheStats.uncacheable = 0;
+}