@sleep2agi/commhub-server 0.9.0-preview.97 → 0.9.0-preview.99

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.97",
+  "version": "0.9.0-preview.99",
   "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/requirements-last-event-http.test.ts

@@ -235,3 +235,110 @@ describe("#506 GET /api/requirements last_event", () => {
     }
   });
 });
+
+// #506 跟进 —— 评论不动 updated_at,所以增量读(changes=1 + updated_since)过去看不见它:「评论了」要等下次整读。
+// 现在 changes=1(且带 last_event)时,游标之后有新流水的卡也回。updated_at 语义不变(评论不改卡)。
+describe("#506 changes=1 returns cards whose newest event is after the cursor", () => {
+  const tick = () => new Promise(r => setTimeout(r, 5));
+  const changes = (t: string, since: string, extra = "", headers: Record<string, string> = {}) =>
+    list(t, `&changes=1&updated_since=${encodeURIComponent(since)}${extra}`, headers);
+  const cursorNow = async (t: string) => {
+    const base = await changes(t, new Date().toISOString());
+    expect(base.status).toBe(200);
+    await tick();
+    return base.body.server_time as string;
+  };
+
+  test("a comment after the cursor → that row comes back with the new last_event; untouched rows do not", async () => {
+    const a = await create(admin.token, { name: "增量评论 A" });
+    const b = await create(admin.token, { name: "增量评论 B" });
+    const before = rowOf(await list(admin.token), a.id);
+    await tick();
+    const since = await cursorNow(admin.token);
+    expect((await comment(member.token, a.id, "增量里看得到这条")).status).toBe(201);
+    const r = await changes(admin.token, since);
+    expect(r.status).toBe(200);
+    const ids = (r.body.requirements as any[]).map(x => x.id);
+    expect(ids).toEqual([a.id]);
+    expect(ids).not.toContain(b.id);
+    const row = rowOf(r, a.id);
+    expect(row.updatedAt).toBe(before.updatedAt); // updated_at 语义不变:评论不改卡
+    expect(row.last_event).toMatchObject({ type: "comment", actor: { id: member.id, kind: "user" }, summary: "增量里看得到这条" });
+    expect(r.body.deleted).toEqual([]);
+    // summary 视图同样回
+    const s = await changes(admin.token, since, "&view=summary");
+    expect((s.body.requirements as any[]).map(x => x.id)).toEqual([a.id]);
+    expect(rowOf(s, a.id).last_event.summary).toBe("增量里看得到这条");
+  });
+
+  test("no event and no update after the cursor → nothing returned; a comment then changes the result and its ETag", async () => {
+    const a = await create(admin.token, { name: "增量空" });
+    await tick();
+    const since = await cursorNow(admin.token);
+    const empty = await changes(admin.token, since);
+    expect(empty.status).toBe(200);
+    expect(empty.body.requirements).toEqual([]);
+    expect(empty.body.deleted).toEqual([]);
+    expect(empty.etag).toBeTruthy();
+    expect((await comment(admin.token, a.id, "空之后的评论")).status).toBe(201);
+    const after = await changes(admin.token, since, "", { "If-None-Match": empty.etag! });
+    expect(after.status).toBe(200);
+    expect(after.etag).not.toBe(empty.etag);
+    expect((after.body.requirements as any[]).map(x => x.id)).toEqual([a.id]);
+  });
+
+  test("full-list ETag changes on a comment (list cache invalidated by the write)", async () => {
+    const a = await create(admin.token, { name: "整表 ETag" });
+    const first = await list(admin.token);
+    expect((await list(admin.token, "", { "If-None-Match": first.etag! })).status).toBe(304);
+    expect((await comment(admin.token, a.id, "整表也变")).status).toBe(201);
+    const after = await list(admin.token, "", { "If-None-Match": first.etag! });
+    expect(after.status).toBe(200);
+    expect(after.etag).not.toBe(first.etag);
+  });
+
+  test("unchanged contracts: last_event=0 (MCP default) and plain updated_since (no changes=1) still filter by updated_at only", async () => {
+    const a = await create(admin.token, { name: "旧语义" });
+    await tick();
+    const since = await cursorNow(admin.token);
+    expect((await comment(admin.token, a.id, "只是一条评论")).status).toBe(201);
+    expect((await changes(admin.token, since, "&last_event=0")).body.requirements).toEqual([]);
+    const plain = await list(admin.token, `&updated_since=${encodeURIComponent(since)}`);
+    expect(plain.status).toBe(200);
+    expect(rowOf(plain, a.id)).toBeUndefined();
+    // MCP changes=true 默认不带 last_event → 同样不回;include_last_event=true → 回
+    const mDef = await mcp(nodeToken, "requirements_list", { changes: true, updated_since: since });
+    expect(mDef.isError).toBe(false);
+    expect(mDef.data.requirements.map((r: any) => r.id)).not.toContain(a.id);
+    const mOn = await mcp(nodeToken, "requirements_list", { changes: true, updated_since: since, include_last_event: true });
+    expect(mOn.isError).toBe(false);
+    expect(mOn.data.requirements.find((r: any) => r.id === a.id)?.last_event).toMatchObject({ type: "comment", summary: "只是一条评论" });
+  });
+
+  test("a real update after the cursor still comes back (updated_at path); a delete is reported in `deleted`, not as a row", async () => {
+    const a = await create(admin.token, { name: "增量改动" });
+    const d = await create(admin.token, { name: "增量删除" });
+    await comment(admin.token, d.id, "删之前的评论");
+    await tick();
+    const since = await cursorNow(admin.token);
+    expect((await send(admin.token, "PATCH", `/api/requirements/${a.id}?network_id=${NET}`, { priority: "high" })).status).toBe(200);
+    expect((await send(admin.token, "DELETE", `/api/requirements/${d.id}?network_id=${NET}`)).status).toBe(200);
+    const r = await changes(admin.token, since);
+    expect((r.body.requirements as any[]).map(x => x.id)).toEqual([a.id]);
+    expect(rowOf(r, a.id).last_event).toMatchObject({ type: "changed", field: "priority" });
+    expect(r.body.deleted).toEqual([d.id]);
+  });
+
+  test("visibility: a scoped member does not get a card it cannot see, even when it was commented on", async () => {
+    const hidden = await create(admin.token, { name: "scoped 看不见" });
+    const mine = await create(admin.token, { name: "scoped 看得见", owner: { kind: "user", id: scoped.id } });
+    await tick();
+    const since = await cursorNow(scoped.token);
+    expect((await comment(admin.token, hidden.id, "别人的卡上的评论")).status).toBe(201);
+    expect((await comment(admin.token, mine.id, "他的卡上的评论")).status).toBe(201);
+    const r = await changes(scoped.token, since);
+    expect(r.status).toBe(200);
+    expect((r.body.requirements as any[]).map(x => x.id)).toEqual([mine.id]);
+    expect(JSON.stringify(r.body)).not.toContain(hidden.id);
+  });
+});

package/src/requirements.ts

@@ -1105,7 +1105,16 @@ function listFilters(url: URL, sql: string, params: unknown[], ctx?: Requirement
   if (since !== null) {
     const ms = Date.parse(since);
     if (!Number.isFinite(ms)) return jsonError("invalid_updated_since", 400);
-    sql += ` AND updated_at >= ?${params.push(new Date(ms).toISOString())}`;
+    const n = params.push(new Date(ms).toISOString());
+    // #506 —— 增量(changes=1)且带 last_event 时,「之后有新流水」的卡也算改过:评论只追加 requirement_events、
+    // 不动 updated_at(updatedAt 是「卡本身最后一次被改」,评论不算 —— 见 last_event 测试),不这样评论要等下次整读才出现。
+    // 同一个占位符用两次(SQLite / PostgreSQL 都认,没有绑了不用的参数);子查询走 idx_requirement_events_created,
+    // 只扫游标之后的流水。不带 changes 的 updated_since 照旧只按 updated_at 过滤(同步方 / MCP 筛选语义不变);
+    // last_event=0(MCP 默认)行上没有动态可看,也照旧。
+    const eventsToo = q.get("changes") === "1" && q.get("last_event") !== "0";
+    sql += eventsToo
+      ? ` AND (updated_at >= ?${n} OR requirement_id IN (SELECT requirement_id FROM requirement_events WHERE created_at >= ?${n}))`
+      : ` AND updated_at >= ?${n}`;
   }
   const seq = q.get("seq");
   if (seq !== null) {

package/src/server.ts

@@ -22,6 +22,7 @@ import { recentNodeIdentityConflicts } from "./node-identity-conflict.js";
 import { createSSEStream, createNetworkObserverStream, createUserEventStream, pushEvent, pushNetworkObserverEvent, getSSEStats, PRINTABLE_OBSERVER_KEY_PREFIX, closeUserStreamsInNetwork, getUserPresence, onUserPresenceChange, pushUserEventToNetwork } from "./push.js";
 import { assertNodeActive } from "./lifecycle-guard.js";
 import { pendingInboxCount } from "./inbox-count.js";
+import { notifyExpiredTasks, type ExpiredTaskRow } from "./task-expiry-notice.js";
 import { addAgentNetworkScope, addHumanNetworkScope, addNetworkScope, addOwnTrafficScope, canRestWriteNetwork, canRestWriteNetworkAsHuman, getUserNetworkIds, resolveRestNetworkScope, resolveRestWriteNetworkId, singleNetworkId, type RestNetworkScope } from "./network-scope.js";
 import { restrictedMemberSeesFile, restrictedMemberAttachmentsDenied } from "./restricted-files.js";
 import { dmParticipantSeesFile, listDmThread, listDmThreads, sendHumanDm } from "./human-dm.js";
@@ -891,16 +892,24 @@ const wsTmuxIntervals = new Map<object, ReturnType<typeof setInterval>>();
 export function patrolExpiredTasks(): void {
   try {
     const expired = db.transaction(() => {
-      const due = db.all<{ task_id: string; network_id: string | null }>(
-        `SELECT task_id, network_id FROM tasks
+      // #500 — a task the node already took into a turn before its deadline
+      // (consumed_at < expires_at) is not "never picked up": the status only
+      // stays `delivered` because delivered → running needs a verbatim
+      // report_status match. Leave it for the node to finish. A consumed_at
+      // stamped AFTER the deadline (late receipt replay) does not save it.
+      const due = db.all<ExpiredTaskRow>(
+        `SELECT task_id, network_id, from_name, from_node_id, to_name, content, created_at, expires_at, parent_task_id, meta_json
+           FROM tasks
           WHERE expires_at IS NOT NULL AND expires_at < datetime('now')
-            AND status IN ('created', 'delivered')`,
+            AND status IN ('created', 'delivered')
+            AND (consumed_at IS NULL OR consumed_at >= expires_at)`,
       );
-      const changed: Array<{ task_id: string; network_id: string | null }> = [];
+      const changed: ExpiredTaskRow[] = [];
       for (const task of due) {
         const result = db.run(
           `UPDATE tasks SET status = 'expired', completed_at = datetime('now')
-            WHERE task_id = ?1 AND status IN ('created', 'delivered')`,
+            WHERE task_id = ?1 AND status IN ('created', 'delivered')
+              AND (consumed_at IS NULL OR consumed_at >= expires_at)`,
           [task.task_id],
         );
         // SQLite may include the AFTER UPDATE terminal-journal trigger write
@@ -925,6 +934,9 @@ export function patrolExpiredTasks(): void {
     if (expired.length > 0) {
       console.log(`[patrol] expired ${expired.length} stale task(s)`);
       for (const task of expired) logTaskEvent(task.task_id, null, "expired", "patrol");
+      // #500 — tell the sender, after commit (task-expiry-notice.ts).
+      const notices = notifyExpiredTasks(expired);
+      if (notices.length > 0) console.log(`[patrol] sent ${notices.length} expiry notice(s)`);
     }
   } catch {}
 }

package/src/task-expiry-notice-http.test.ts

@@ -0,0 +1,287 @@
+// #500 —— 任务过期时告诉派活的人;节点已经取走的任务不再被过期。HTTP 集成测试(真实 Bun.serve,私有端口,临时库)。
+// test2123 在真实 PostgreSQL 上原样再跑一遍(COMMHUB_TEST_PG_URL)。
+//
+// 任务一律经真入口 POST /api/task 派出(节点令牌 / 用户令牌),只把 created_at / expires_at 往前拨,
+// 然后调 TTL 巡检(server.ts patrolExpiredTasks,定时器调的就是它)。收件一侧也走真入口:
+// agent 用自己的节点令牌订阅 /events/<alias> 并经 /mcp get_inbox 取;人订阅 /events/users/me。
+//
+// 钉住:
+//   1. consumed_at 早于期限 → 不过期、不通知;consumed_at 晚于期限(迟到的回执)→ 照样过期。
+//   2. agent 派的任务过期 → 它收到恰好一条 type=reply / from=hub / requires_response=none 的通知 + SSE new_reply;
+//      正文带目标别名、等了几分钟、前面还有几个、retry_task、「不要原样重发」。
+//   3. 人派的 → user_inbox kind=task_expired 一条,from_session = 目标节点(出现在与它的会话里)+ SSE desktop_message。
+//   4. scheduler 派的 → 谁都不通知。
+//   5. 子任务过期 → 父任务的发送方收到一条「子任务已过期」,父任务状态 / result 不变。
+//   6. 同一次巡检里同一 (发送方, 目标) 5 条过期 → 只发一条,列出 5 个 id。
+//
+// 跑法:cd server && COMMHUB_DB=/tmp/x.db bun test src/task-expiry-notice-http.test.ts
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-expiry-notice-"));
+process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+process.env.HOST = "127.0.0.1";
+const PW = "ExpiryNotice123!x";
+const stamp = Date.now();
+
+let db: any;
+let patrol: () => void;
+let KIND = "";
+let hub: any = null;
+let BASE = "";
+let NET = "";
+let bossToken = "", umaToken = "", umaId = "", umaName = "";
+type Node = { alias: string; nodeId: string; token: string };
+const nodes: Record<"sender" | "target" | "other", Node> = {} as any;
+
+async function send(token: string, method: string, path: string, payload?: unknown) {
+  const res = await fetch(`${BASE}${path}`, {
+    method,
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    body: payload === undefined ? undefined : JSON.stringify(payload),
+  });
+  return { status: res.status, body: await res.json().catch(() => null) as any };
+}
+async function tool(token: string, name: string, args: Record<string, unknown>) {
+  const res = await fetch(`${BASE}/mcp`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-03-26" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }),
+  });
+  const raw = await res.text();
+  const data = raw.split("\n").filter((x) => x.startsWith("data:"));
+  const payload = data.length ? JSON.parse(data.at(-1)!.slice(5).trim()) : JSON.parse(raw);
+  return JSON.parse(payload.result.content[0].text);
+}
+
+type Sub = { events: any[]; close: () => void };
+async function subscribe(path: string, token: string): Promise<Sub> {
+  const ctrl = new AbortController();
+  const res = await fetch(`${BASE}${path}`, { headers: { Authorization: `Bearer ${token}` }, signal: ctrl.signal });
+  expect(res.status).toBe(200);
+  const events: any[] = [];
+  const reader = res.body!.getReader();
+  const dec = new TextDecoder();
+  let buf = "";
+  void (async () => {
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buf += dec.decode(value);
+        let i: number;
+        while ((i = buf.indexOf("\n\n")) >= 0) {
+          const frame = buf.slice(0, i); buf = buf.slice(i + 2);
+          for (const line of frame.split("\n")) if (line.startsWith("data: ")) { try { events.push(JSON.parse(line.slice(6))); } catch {} }
+        }
+      }
+    } catch {}
+  })();
+  await until(() => events.some((e) => e.type === "connected"));
+  return { events, close: () => ctrl.abort() };
+}
+const until = async (cond: () => boolean, tries = 150) => { for (let k = 0; k < tries && !cond(); k++) await new Promise((r) => setTimeout(r, 20)); };
+
+let seq = 0;
+/** 经 POST /api/task 派一条;返回 task_id。 */
+async function dispatch(token: string, to: string, extra: Record<string, unknown> = {}): Promise<string> {
+  const r = await send(token, "POST", "/api/task", { alias: to, task: `expiry case ${stamp} #${++seq}`, network_id: NET, ...extra });
+  expect(r.status).toBe(200);
+  expect(r.body.ok).toBe(true);
+  return r.body.task_id;
+}
+/** 把这条任务拨成「61 分钟前派出、1 分钟前到期」。 */
+const backdate = (taskId: string) => db.run(
+  "UPDATE tasks SET created_at = datetime('now', '-61 minutes'), delivered_at = datetime('now', '-61 minutes'), expires_at = datetime('now', '-1 minutes') WHERE task_id = ?1",
+  [taskId],
+);
+const taskRow = (taskId: string) => db.get("SELECT status, result FROM tasks WHERE task_id = ?1", taskId) as { status: string; result: string | null };
+const agentNotices = (alias: string) => db.all(
+  "SELECT id, type, content, from_session, in_reply_to, requires_response, meta_json, acked FROM inbox WHERE session_name = ?1 AND network_id = ?2 AND from_session = 'hub' AND id LIKE 'exp_%' ORDER BY created_at, id",
+  alias, NET,
+) as Array<{ id: string; type: string; content: string; from_session: string; in_reply_to: string; requires_response: string; meta_json: string; acked: number }>;
+const userNotices = (userId: string) => db.all(
+  "SELECT message_id, from_session, title, content, meta_json FROM user_inbox WHERE user_id = ?1 AND network_id = ?2 AND kind = ?3 ORDER BY created_at, message_id",
+  userId, NET, KIND,
+) as Array<{ message_id: string; from_session: string; title: string; content: string; meta_json: string }>;
+
+beforeAll(async () => {
+  ({ db } = await import("./db.js"));
+  const { addNetworkMember, createNetworkTokenForNode, register } = await import("./auth.js");
+  ({ TASK_EXPIRED_NOTICE_KIND: KIND } = await import("./task-expiry-notice.js"));
+  const boss = register(`exp_boss_${stamp}`, PW);
+  expect(boss.ok).toBe(true);
+  bossToken = boss.token!; NET = boss.network_id!;
+  const bossId = boss.user!.user_id;
+  const uma = register(`exp_uma_${stamp}`, PW);
+  umaToken = uma.token!; umaId = uma.user!.user_id; umaName = uma.user!.username;
+  expect(addNetworkMember(NET, umaId, "member", bossId, { agentAccess: "all" }).ok).toBe(true);
+  for (const key of ["sender", "target", "other"] as const) {
+    const alias = `exp-${key}-${stamp}`;
+    const nodeId = `n_exp_${key}_${stamp}`;
+    const minted = createNetworkTokenForNode(bossId, NET, alias, nodeId);
+    expect(minted.ok).toBe(true);
+    nodes[key] = { alias, nodeId, token: minted.token! };
+  }
+  const mod: any = await import("./server.js");
+  patrol = mod.patrolExpiredTasks;
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+  for (const n of Object.values(nodes)) {
+    const r = await tool(n.token, "report_status", { resume_id: `sdk-${n.nodeId}`, alias: n.alias, status: "idle", node_id: n.nodeId, network_id: NET });
+    expect(r.ok).toBe(true);
+  }
+}, 30_000);
+
+beforeEach(() => {
+  // 每条用例自己的数据:上一条留下的开着的任务不许算进「前面还有几个」,也不许被这一次巡检过期。
+  db.run("UPDATE tasks SET status = 'replied', completed_at = datetime('now') WHERE network_id = ?1 AND status IN ('created', 'delivered', 'acked', 'running')", [NET]);
+  db.run("DELETE FROM inbox WHERE network_id = ?1 AND id LIKE 'exp_%'", [NET]);
+  db.run("DELETE FROM user_inbox WHERE network_id = ?1 AND kind = ?2", [NET, KIND]);
+});
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("#500 consumed before the deadline → not expired", () => {
+  test("consumed_at < expires_at keeps the task; a late consumed_at (after the deadline) does not", async () => {
+    const taken = await dispatch(nodes.sender.token, nodes.target.alias);
+    const late = await dispatch(nodes.sender.token, nodes.target.alias);
+    backdate(taken); backdate(late);
+    db.run("UPDATE tasks SET consumed_at = datetime('now', '-30 minutes') WHERE task_id = ?1", [taken]);
+    db.run("UPDATE tasks SET consumed_at = datetime('now') WHERE task_id = ?1", [late]);
+    patrol();
+    expect(taskRow(taken).status).toBe("delivered");
+    expect(taskRow(late).status).toBe("expired");
+    // 通知只说过期的那一条。
+    const n = agentNotices(nodes.sender.alias);
+    expect(n.length).toBe(1);
+    expect(n[0].content).toContain(late);
+    expect(n[0].content).not.toContain(taken);
+  });
+});
+
+describe("#500 sender is an agent node", () => {
+  test("exactly one terminal reply-row notice + new_reply push; get_inbox returns it", async () => {
+    const sub = await subscribe(`/events/${encodeURIComponent(nodes.sender.alias)}?network_id=${NET}`, nodes.sender.token);
+    try {
+      // 目标上有一条比它早、还开着的任务(别人派的,没到期)→ 「前面还有 1 个」。
+      const ahead = await dispatch(bossToken, nodes.target.alias);
+      db.run("UPDATE tasks SET created_at = datetime('now', '-90 minutes') WHERE task_id = ?1", [ahead]);
+      const id = await dispatch(nodes.sender.token, nodes.target.alias);
+      backdate(id);
+      patrol();
+      expect(taskRow(id).status).toBe("expired");
+      expect(taskRow(ahead).status).toBe("delivered");
+
+      const n = agentNotices(nodes.sender.alias);
+      expect(n.length).toBe(1);
+      expect(n[0].type).toBe("reply");
+      expect(n[0].from_session).toBe("hub");
+      expect(n[0].requires_response).toBe("none");
+      expect(n[0].in_reply_to).toBe(id);
+      for (const frag of ["[Hub] 任务已过期", nodes.target.alias, id, "等了 61 分钟", "期限 60 分钟", "还有 1 个", "retry_task", "不要原样重发", "do not blindly resend"]) {
+        expect(n[0].content).toContain(frag);
+      }
+      expect(JSON.parse(n[0].meta_json).task_expired).toEqual({ target: nodes.target.alias, task_ids: [id], queued_ahead: 1 });
+
+      await until(() => sub.events.some((e) => e.type === "new_reply" && e.message_id === n[0].id));
+      const push = sub.events.find((e) => e.type === "new_reply" && e.message_id === n[0].id);
+      expect(push).toMatchObject({ from: "hub", in_reply_to: id, status: "expired" });
+
+      const inbox = await tool(nodes.sender.token, "get_inbox", { alias: nodes.sender.alias, limit: 50 });
+      const got = JSON.stringify(inbox);
+      expect(got).toContain(n[0].id);
+      // 目标节点自己什么都没多收(过期的任务行已 acked,通知只给发送方)。
+      expect(agentNotices(nodes.target.alias).length).toBe(0);
+
+      // 再巡检一次:不重复发。
+      patrol();
+      expect(agentNotices(nodes.sender.alias).length).toBe(1);
+    } finally { sub.close(); }
+  });
+});
+
+describe("#500 sender is a person (Dashboard / App)", () => {
+  test("user_inbox task_expired from the target node + desktop_message push; no agent inbox row", async () => {
+    const sub = await subscribe(`/events/users/me?network_id=${NET}`, umaToken);
+    try {
+      const id = await dispatch(umaToken, nodes.target.alias);
+      backdate(id);
+      patrol();
+      expect(taskRow(id).status).toBe("expired");
+      const n = userNotices(umaId);
+      expect(n.length).toBe(1);
+      expect(n[0].from_session).toBe(nodes.target.alias);
+      expect(n[0].title).toBe("任务已过期");
+      for (const frag of [nodes.target.alias, id, "等了 61 分钟", "retry_task", "不要原样重发"]) expect(n[0].content).toContain(frag);
+      await until(() => sub.events.some((e) => e.type === "desktop_message" && e.message_id === n[0].message_id));
+      expect(sub.events.find((e) => e.type === "desktop_message" && e.message_id === n[0].message_id)).toMatchObject({ kind: KIND, from: nodes.target.alias });
+      // 没有往「用户名」那个 alias 的 agent inbox 里塞东西。
+      expect(agentNotices(umaName).length).toBe(0);
+    } finally { sub.close(); }
+  });
+});
+
+describe("#500 sender is the scheduler", () => {
+  test("no notice to anyone; the task still expires", async () => {
+    const id = `sched_task_${stamp}`;
+    db.run(
+      `INSERT INTO tasks (task_id, from_name, to_name, to_node_id, priority, status, content, requires_response, created_at, delivered_at, expires_at, network_id, meta_json)
+       VALUES (?1, 'scheduler', ?2, ?3, 'normal', 'delivered', 'scheduled', 'reply', datetime('now', '-61 minutes'), datetime('now', '-61 minutes'), datetime('now', '-1 minutes'), ?4, ?5)`,
+      [id, nodes.target.alias, nodes.target.nodeId, NET, JSON.stringify({ auth_origin: "hub_scheduler" })],
+    );
+    patrol();
+    expect(taskRow(id).status).toBe("expired");
+    const anyAgent = db.get("SELECT COUNT(*) AS n FROM inbox WHERE network_id = ?1 AND id LIKE 'exp_%'", NET) as { n: number };
+    expect(Number(anyAgent.n)).toBe(0);
+    const anyUser = db.get("SELECT COUNT(*) AS n FROM user_inbox WHERE network_id = ?1 AND kind = ?2", NET, KIND) as { n: number };
+    expect(Number(anyUser.n)).toBe(0);
+  });
+});
+
+describe("#500 child task expires", () => {
+  test("parent sender is told; parent stays open with its result untouched", async () => {
+    const parent = await dispatch(umaToken, nodes.sender.alias);
+    const child = await dispatch(nodes.sender.token, nodes.target.alias, { parent_task_id: parent });
+    backdate(child);
+    patrol();
+    expect(taskRow(child).status).toBe("expired");
+    expect(taskRow(parent)).toEqual({ status: "delivered", result: null });
+    // 子任务的发送方(父任务的执行者)照常收到过期通知。
+    expect(agentNotices(nodes.sender.alias).length).toBe(1);
+    // 父任务的发送方(人)收到一条「子任务已过期」,出现在与父任务执行者的会话里。
+    const n = userNotices(umaId);
+    expect(n.length).toBe(1);
+    expect(n[0].title).toBe("子任务已过期");
+    expect(n[0].from_session).toBe(nodes.sender.alias);
+    for (const frag of [parent, child, nodes.target.alias, "父任务没有被结束"]) expect(n[0].content).toContain(frag);
+  });
+});
+
+describe("#500 one notice per (sender, target) per patrol pass", () => {
+  test("5 expiring to the same target → one summarized notice listing all 5", async () => {
+    const ids: string[] = [];
+    for (let i = 0; i < 5; i++) ids.push(await dispatch(nodes.sender.token, nodes.target.alias));
+    // 再来一条派给另一个目标:那是另一组,单独一条。
+    const elsewhere = await dispatch(nodes.sender.token, nodes.other.alias);
+    for (const id of [...ids, elsewhere]) backdate(id);
+    patrol();
+    for (const id of ids) expect(taskRow(id).status).toBe("expired");
+    const n = agentNotices(nodes.sender.alias);
+    expect(n.length).toBe(2);
+    const batch = n.find((x) => x.content.includes(nodes.target.alias))!;
+    expect(batch.content).toContain("[Hub] 5 个任务已过期");
+    for (const id of ids) expect(batch.content).toContain(id);
+    expect(batch.content).not.toContain(elsewhere);
+    expect(JSON.parse(batch.meta_json).task_expired.task_ids.sort()).toEqual([...ids].sort());
+    const single = n.find((x) => x.content.includes(nodes.other.alias))!;
+    expect(single.content).toContain(elsewhere);
+  });
+});

package/src/task-expiry-notice.ts

@@ -0,0 +1,307 @@
+// #500 —— 任务过期时告诉派活的人。
+//
+// 以前 TTL 巡检(server.ts patrolExpiredTasks)只把任务改成 expired、写一条 task_events,
+// 派活的一方什么都收不到:14 天 109 条过期,0 条被告知;agent 收不到回音就原样重发,队列越排越长。
+//
+// 这里在巡检提交之后,按「派活的一方是谁」走它平时收回复的那条路:
+//   - agent 节点:inbox 写一行 type='reply'(requires_response='none')+ SSE new_reply。
+//     与 send_reply 同形:agent-node(peer-reply-inbox.ts)和 claude-code channel(channel-inbox-wake.ts)
+//     都把 new_reply 当门铃拉 inbox。agent-node 按 inbox-message-policy.ts 把 type=reply 当「终态结果」
+//     交给模型、不回复(不会被当成新任务);claude-code channel 像别的回复一样注入会话。from_session = 'hub':自派(A→A)的任务不会被节点当成自己发的而跳过。
+//   - 人(Dashboard / App 的用户):agent-notice.ts(user_inbox + /events/users/me 的 desktop_message),
+//     from_session = 目标节点别名 —— 与 #462/#464 同一条路,出现在**与该节点的会话**里 + 未读 + 通知。
+//   - scheduler:不发。scheduled_task_runs 那一行已经记了 expired(syncScheduledRunForTask)。
+//   - hub / api / 认不出来的发送方:不发(没有可达的收件人)。
+// 限流:同一次巡检里,同一个 (网络, 发送方, 目标) 只发**一条**,多条过期合并成一条摘要。
+// 父任务:子任务过期时通知父任务的发送方一条(同样按父任务合并),**不**改父任务的状态 / result ——
+//   chainReplyToParent 会把父任务改成 replied/failed,这里刻意不走它:父任务的执行者可能还在干活。
+// 全部在巡检事务提交之后做,每一步各自吞异常:通知失败不能让巡检失败,也不能回滚已经过期的任务。
+
+import { db, uuidv4 } from "./db.js";
+import { parseDbTimestampMs } from "./db-timestamp.js";
+import { sendAgentNotice } from "./agent-notice.js";
+import { pushEvent, pushNetworkObserverEvent } from "./push.js";
+import { pendingInboxCount } from "./inbox-count.js";
+
+export const TASK_EXPIRED_NOTICE_KIND = "task_expired";
+
+/** 巡检刚刚结束为 expired 的一行(巡检 SELECT 出来的列)。 */
+export type ExpiredTaskRow = {
+  task_id: string;
+  network_id: string | null;
+  from_name: string | null;
+  from_node_id: string | null;
+  to_name: string;
+  content: string | null;
+  created_at: string | null;
+  expires_at: string | null;
+  parent_task_id: string | null;
+  meta_json: string | null;
+};
+
+export type ExpirySenderRoute =
+  | { kind: "agent"; alias: string }
+  | { kind: "user"; userId: string; username: string }
+  | { kind: "none"; reason: "scheduler" | "system" | "unknown" };
+
+/** 一条发出去的通知(测试 / 日志用)。 */
+export type ExpiryNoticeSent = {
+  route: "agent" | "user";
+  recipient: string;
+  target: string;
+  task_ids: string[];
+  message_id: string;
+  about: "task" | "child";
+};
+
+const SYSTEM_SENDERS = new Set(["", "hub", "api"]);
+const MAX_LISTED = 10;
+
+function authOrigin(metaJson: string | null): string | null {
+  if (!metaJson) return null;
+  try {
+    const m = JSON.parse(metaJson);
+    return m && typeof m === "object" && typeof m.auth_origin === "string" ? m.auth_origin : null;
+  } catch { return null; }
+}
+
+function isScheduledTask(taskId: string): boolean {
+  return !!db.get("SELECT 1 AS hit FROM scheduled_task_runs WHERE task_id = ?1", taskId);
+}
+
+function memberUser(username: string, networkId: string | null): { userId: string } | null {
+  if (!networkId) return null; // user_inbox 按网络存:没有网络就没有可达的人
+  const u = db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", username);
+  if (!u) return null;
+  const m = db.get("SELECT 1 AS hit FROM network_members WHERE network_id = ?1 AND user_id = ?2", networkId, u.user_id);
+  return m ? { userId: u.user_id } : null;
+}
+
+function agentSession(alias: string, networkId: string | null): { node_id: string | null } | null {
+  return networkId
+    ? db.get<{ node_id: string | null }>("SELECT node_id FROM sessions WHERE alias = ?1 AND network_id = ?2 ORDER BY updated_at DESC LIMIT 1", alias, networkId)
+    : db.get<{ node_id: string | null }>("SELECT node_id FROM sessions WHERE alias = ?1 AND network_id IS NULL ORDER BY updated_at DESC LIMIT 1", alias);
+}
+
+/**
+ * 派活的一方是谁 → 走哪条路。
+ * 节点派的(auth_origin=node 或带 from_node_id)先按节点认;否则先按人认(Dashboard 用用户令牌派活,
+ * from_name 是用户名、from_node_id 为空)。两种都认不出 → 不发。
+ */
+export function classifyExpirySender(row: Pick<ExpiredTaskRow, "task_id" | "network_id" | "from_name" | "from_node_id" | "meta_json">): ExpirySenderRoute {
+  const from = (row.from_name ?? "").trim();
+  const origin = authOrigin(row.meta_json);
+  if (from === "scheduler" || origin === "hub_scheduler" || isScheduledTask(row.task_id)) return { kind: "none", reason: "scheduler" };
+  if (SYSTEM_SENDERS.has(from)) return { kind: "none", reason: "system" };
+  const nodeFirst = origin === "node" || (!!row.from_node_id && origin !== "user");
+  const asAgent = (): ExpirySenderRoute | null => (agentSession(from, row.network_id) ? { kind: "agent", alias: from } : null);
+  const asUser = (): ExpirySenderRoute | null => {
+    const u = memberUser(from, row.network_id);
+    return u ? { kind: "user", userId: u.userId, username: from } : null;
+  };
+  return (nodeFirst ? (asAgent() ?? asUser()) : (asUser() ?? asAgent())) ?? { kind: "none", reason: "unknown" };
+}
+
+/** 过期那一刻,目标节点上比它早、还没结束的任务数(正在跑的也算)。 */
+export function openTasksAhead(target: string, networkId: string | null, createdAt: string | null): number | null {
+  if (!createdAt) return null;
+  try {
+    const row = networkId
+      ? db.get<{ n: number }>(
+        `SELECT COUNT(*) AS n FROM tasks WHERE to_name = ?1 AND network_id = ?2
+            AND status IN ('created', 'delivered', 'acked', 'running') AND created_at < ?3`,
+        target, networkId, createdAt)
+      : db.get<{ n: number }>(
+        `SELECT COUNT(*) AS n FROM tasks WHERE to_name = ?1 AND network_id IS NULL
+            AND status IN ('created', 'delivered', 'acked', 'running') AND created_at < ?2`,
+        target, createdAt);
+    return Number(row?.n ?? 0);
+  } catch { return null; }
+}
+
+function minutesBetween(fromTs: string | null, toMs: number): number | null {
+  if (!fromTs) return null;
+  const ms = parseDbTimestampMs(fromTs);
+  return Number.isFinite(ms) ? Math.max(0, Math.round((toMs - ms) / 60_000)) : null;
+}
+
+function preview(content: string | null, max = 60): string {
+  const s = (content ?? "").replace(/\s+/g, " ").trim();
+  return s.length > max ? `${s.slice(0, max)}…` : s;
+}
+
+export const EXPIRY_GUIDANCE_ZH = "建议:换一个空闲的节点重新派(已过期的任务不能 reassign_task),或稍后用 retry_task 让它在原节点重新排队;不要原样重发一条新任务 —— 重发只会让它的队列更长。";
+export const EXPIRY_GUIDANCE_EN = "Consider sending it to another node or retry_task later; do not blindly resend.";
+
+export type ExpiryNoticeInput = {
+  target: string;
+  tasks: Array<{ task_id: string; content: string | null; waited_min: number | null; ttl_min: number | null }>;
+  queued_ahead: number | null;
+};
+
+const fmtMin = (m: number | null) => (m === null ? "?" : String(m));
+
+/** 给派活一方的正文。单条与多条两种形状;人和 agent 读同一份。 */
+export function expiryNoticeText(n: ExpiryNoticeInput): { title: string; text: string } {
+  const count = n.tasks.length;
+  const ahead = n.queued_ahead === null ? "" : `过期时 ${n.target} 上还有 ${n.queued_ahead} 个比它早、没结束的任务。\n`;
+  const aheadEn = n.queued_ahead === null ? "" : `, ${n.queued_ahead} open task(s) ahead`;
+  if (count === 1) {
+    const t = n.tasks[0];
+    const ttl = t.ttl_min === null ? "" : `(期限 ${t.ttl_min} 分钟)`;
+    return {
+      title: "任务已过期",
+      text: `[Hub] 任务已过期:你派给 ${n.target} 的任务 ${t.task_id} 等了 ${fmtMin(t.waited_min)} 分钟仍没被取走${ttl},Hub 已把它结束为 expired,${n.target} 不会再执行它。\n`
+        + ahead
+        + `内容:${preview(t.content)}\n`
+        + `${EXPIRY_GUIDANCE_ZH}\n`
+        + `Task ${t.task_id} to ${n.target} expired unconsumed after ${fmtMin(t.waited_min)} min${aheadEn}. ${EXPIRY_GUIDANCE_EN}`,
+    };
+  }
+  const waited = n.tasks.map((t) => t.waited_min).filter((m): m is number => m !== null);
+  const longest = waited.length ? Math.max(...waited) : null;
+  const lines = n.tasks.slice(0, MAX_LISTED).map((t) => `- ${t.task_id} 等了 ${fmtMin(t.waited_min)} 分钟:${preview(t.content, 40)}`);
+  if (count > MAX_LISTED) lines.push(`- …另外 ${count - MAX_LISTED} 个`);
+  return {
+    title: `${count} 个任务已过期`,
+    text: `[Hub] ${count} 个任务已过期:你派给 ${n.target} 的 ${count} 个任务都没被取走(最长等了 ${fmtMin(longest)} 分钟),Hub 已把它们结束为 expired,${n.target} 不会再执行。\n`
+      + ahead
+      + `${lines.join("\n")}\n`
+      + `${EXPIRY_GUIDANCE_ZH}\n`
+      + `${count} tasks to ${n.target} expired unconsumed (longest wait ${fmtMin(longest)} min${aheadEn}). ${EXPIRY_GUIDANCE_EN}`,
+  };
+}
+
+/** 父任务发送方收到的正文:子任务过期了,父任务**没有**被结束。 */
+export function childExpiryNoticeText(p: { parent_task_id: string; parent_target: string; child_target: string; child_task_ids: string[] }): { title: string; text: string } {
+  const n = p.child_task_ids.length;
+  return {
+    title: "子任务已过期",
+    text: `[Hub] 子任务已过期:你派给 ${p.parent_target} 的任务 ${p.parent_task_id} 拆出的 ${n} 个子任务(派给 ${p.child_target}:${p.child_task_ids.join(", ")})没被取走,已结束为 expired。`
+      + `父任务没有被结束,仍由 ${p.parent_target} 处理;它也收到了过期通知。\n`
+      + `Sub-task(s) of ${p.parent_task_id} sent by ${p.parent_target} to ${p.child_target} expired unconsumed; the parent task is still open.`,
+  };
+}
+
+/** 审计:task_events 记一笔「通知过谁」。不用 logTaskEvent:它按 to_status 派生 event_type,
+ *  写 expired 会多出一条 task.expired,让按事件数过期的统计翻倍。 */
+function noteEvent(taskId: string, status: string, detail: string): void {
+  try {
+    db.run(
+      `INSERT INTO task_events (task_id, from_status, to_status, event_type, actor, detail, network_id)
+       VALUES (?1, ?2, ?2, 'task.expiry_notice', 'patrol', ?3, (SELECT network_id FROM tasks WHERE task_id = ?1))`,
+      [taskId, status, detail],
+    );
+  } catch {}
+}
+
+function deliverToAgent(alias: string, networkId: string | null, inReplyTo: string, text: string, meta: Record<string, unknown>): string {
+  const id = `exp_${uuidv4().replace(/-/g, "").slice(0, 20)}`;
+  const nodeId = agentSession(alias, networkId)?.node_id ?? null;
+  db.run(
+    `INSERT INTO inbox (id, session_name, node_id, type, priority, content, from_session, in_reply_to, requires_response, network_id, meta_json)
+     VALUES (?1, ?2, ?3, 'reply', 'normal', ?4, 'hub', ?5, 'none', ?6, ?7)`,
+    [id, alias, nodeId, text, inReplyTo, networkId, JSON.stringify(meta)],
+  );
+  pushEvent(alias, { type: "new_reply", inbox_count: pendingInboxCount(alias, networkId), from: "hub", message_id: id, in_reply_to: inReplyTo, status: "expired" }, networkId);
+  return id;
+}
+
+function deliver(
+  route: Extract<ExpirySenderRoute, { kind: "agent" | "user" }>,
+  networkId: string | null,
+  fromAlias: string,
+  inReplyTo: string,
+  notice: { title: string; text: string },
+  meta: Record<string, unknown>,
+): string | null {
+  if (route.kind === "agent") return deliverToAgent(route.alias, networkId, inReplyTo, notice.text, meta);
+  if (!networkId) return null;
+  return sendAgentNotice({
+    networkId, userId: route.userId, fromAlias, kind: TASK_EXPIRED_NOTICE_KIND,
+    title: notice.title, text: notice.text, severity: "warning", meta, idPrefix: "dm_expired_",
+  });
+}
+
+/**
+ * 巡检提交之后调用。返回发出去的通知(测试用)。任何一组失败只记日志,不影响别的组。
+ */
+export function notifyExpiredTasks(rows: ExpiredTaskRow[], nowMs = Date.now()): ExpiryNoticeSent[] {
+  const sent: ExpiryNoticeSent[] = [];
+  if (rows.length === 0) return sent;
+
+  // 网络观察者(Dashboard 任务页):与 send_reply 同一个摘要事件,只带路由元数据,让任务行刷新成 expired。
+  for (const r of rows) {
+    try { pushNetworkObserverEvent(r.network_id, { type: "new_reply", task_id: r.task_id, message_id: null, from: "hub", to: r.from_name ?? null, status: "expired" }); } catch {}
+  }
+
+  // 1. 给派活的一方:按 (网络, 发送方, 目标) 合并。
+  const groups = new Map<string, ExpiredTaskRow[]>();
+  for (const r of rows) {
+    const key = JSON.stringify([r.network_id ?? null, r.from_name ?? "", r.to_name]);
+    const g = groups.get(key);
+    if (g) g.push(r); else groups.set(key, [r]);
+  }
+  for (const group of groups.values()) {
+    try {
+      group.sort((a, b) => String(a.created_at).localeCompare(String(b.created_at)));
+      const head = group[0];
+      const route = classifyExpirySender(head);
+      if (route.kind === "none") continue;
+      const newest = group[group.length - 1];
+      const input: ExpiryNoticeInput = {
+        target: head.to_name,
+        tasks: group.map((t) => ({
+          task_id: t.task_id,
+          content: t.content,
+          waited_min: minutesBetween(t.created_at, nowMs),
+          ttl_min: t.created_at && t.expires_at
+            ? Math.round((parseDbTimestampMs(t.expires_at) - parseDbTimestampMs(t.created_at)) / 60_000)
+            : null,
+        })),
+        queued_ahead: openTasksAhead(head.to_name, head.network_id, newest.created_at),
+      };
+      const notice = expiryNoticeText(input);
+      const taskIds = group.map((t) => t.task_id);
+      const meta = { task_expired: { target: head.to_name, task_ids: taskIds, queued_ahead: input.queued_ahead } };
+      const id = deliver(route, head.network_id, head.to_name, newest.task_id, notice, meta);
+      if (id) {
+        sent.push({ route: route.kind, recipient: route.kind === "agent" ? route.alias : route.userId, target: head.to_name, task_ids: taskIds, message_id: id, about: "task" });
+        for (const t of group) noteEvent(t.task_id, "expired", `notified ${route.kind} ${route.kind === "agent" ? route.alias : route.username}`);
+      }
+    } catch (e: any) {
+      console.error(`[patrol] expiry notice failed: ${e?.message || e}`);
+    }
+  }
+
+  // 2. 父任务:按父任务合并,只通知,不改父任务的状态 / result。跨网络的父任务不碰。
+  const byParent = new Map<string, ExpiredTaskRow[]>();
+  for (const r of rows) {
+    if (!r.parent_task_id) continue;
+    const g = byParent.get(r.parent_task_id);
+    if (g) g.push(r); else byParent.set(r.parent_task_id, [r]);
+  }
+  for (const [parentId, children] of byParent) {
+    try {
+      const parent = db.get<{ task_id: string; from_name: string | null; from_node_id: string | null; to_name: string; status: string; network_id: string | null; meta_json: string | null }>(
+        "SELECT task_id, from_name, from_node_id, to_name, status, network_id, meta_json FROM tasks WHERE task_id = ?1",
+        parentId,
+      );
+      if (!parent) continue;
+      const childNet = children[0].network_id ?? null;
+      if ((parent.network_id ?? null) !== childNet) continue;
+      const childIds = children.map((c) => c.task_id);
+      const childTargets = [...new Set(children.map((c) => c.to_name))].join(", ");
+      noteEvent(parent.task_id, parent.status, `child expired: ${childIds.join(",")} → ${childTargets}`);
+      const route = classifyExpirySender(parent);
+      if (route.kind === "none") continue;
+      const notice = childExpiryNoticeText({ parent_task_id: parent.task_id, parent_target: parent.to_name, child_target: childTargets, child_task_ids: childIds });
+      const meta = { task_expired: { parent_task_id: parent.task_id, target: childTargets, task_ids: childIds } };
+      const id = deliver(route, parent.network_id, parent.to_name, parent.task_id, notice, meta);
+      if (id) sent.push({ route: route.kind, recipient: route.kind === "agent" ? route.alias : route.userId, target: childTargets, task_ids: childIds, message_id: id, about: "child" });
+    } catch (e: any) {
+      console.error(`[patrol] child-expiry notice failed parent=${parentId}: ${e?.message || e}`);
+    }
+  }
+  return sent;
+}

package/src/tools.ts

@@ -5977,7 +5977,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     limit: z.number().int().min(1).max(1000).optional().describe(`page size, default ${REQ_LIST_MCP_DEFAULT_LIMIT}`),
     cursor: z.string().max(600).optional().describe("next_cursor from the previous page"),
     view: z.enum(["full", "summary"]).optional().describe("default summary (no description / checklist bodies; has_description, checklist_count instead); full = everything"),
-    changes: z.boolean().optional().describe("with updated_since: only tasks changed since then (archived included) + deleted ids + server_time"),
+    changes: z.boolean().optional().describe("with updated_since: only tasks changed since then (archived included; with include_last_event also ones with a newer event, e.g. a comment) + deleted ids + server_time"),
     include_last_event: z.boolean().optional().describe("default false; true adds last_event per row (newest event incl. comments: type, field, actor, at, summary; null if none), ~150 B/row"),
   };
   const reqListKeys = Object.keys(reqListShape);