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

package/src/http-gzip.test.ts

@@ -0,0 +1,73 @@
+import { expect, test } from "bun:test";
+import { maybeGzipResponse, wantsGzip, isCompressibleResponse, trimLightTask, GZIP_MIN_BYTES, LIGHT_TASK_MAX_CHARS } from "./http-gzip";
+
+const big = JSON.stringify({ sessions: Array.from({ length: 200 }, (_, i) => ({ alias: `节点${i}`, task: "x".repeat(50) })) });
+const json = (body: string, extra: Record<string, string> = {}) =>
+  new Response(body, { status: 200, headers: { "Content-Type": "application/json; charset=utf-8", ...extra } });
+const reqWith = (ae?: string, method = "GET") =>
+  new Request("http://hub/api/status?light=1", { method, headers: ae === undefined ? {} : { "Accept-Encoding": ae } });
+
+test("wantsGzip reads Accept-Encoding, including q-values", () => {
+  expect(wantsGzip(reqWith("gzip, deflate, br"))).toBe(true);
+  expect(wantsGzip(reqWith("br;q=1.0, gzip;q=0.8"))).toBe(true);
+  expect(wantsGzip(reqWith("identity"))).toBe(false);
+  expect(wantsGzip(reqWith("gzip;q=0"))).toBe(false);
+  expect(wantsGzip(reqWith())).toBe(false);
+});
+
+test("a large JSON body is gzipped only when the client asked, and round-trips", async () => {
+  const out = await maybeGzipResponse(reqWith("gzip"), json(big));
+  expect(out!.headers.get("Content-Encoding")).toBe("gzip");
+  expect(out!.headers.get("Vary")).toContain("Accept-Encoding");
+  const bytes = new Uint8Array(await out!.arrayBuffer());
+  expect(bytes.byteLength).toBeLessThan(big.length / 3);
+  expect(Number(out!.headers.get("Content-Length"))).toBe(bytes.byteLength);
+  expect(new TextDecoder().decode(Bun.gunzipSync(bytes))).toBe(big);
+  expect(out!.headers.get("Content-Type")).toContain("application/json");
+
+  const plain = json(big);
+  expect(await maybeGzipResponse(reqWith(), plain)).toBe(plain); // untouched object
+});
+
+test("small, streamed, already-encoded, SSE, 204 and HEAD responses are left alone", async () => {
+  const small = json("{\"ok\":true}");
+  const outSmall = await maybeGzipResponse(reqWith("gzip"), small);
+  expect(outSmall!.headers.get("Content-Encoding")).toBeNull();
+  expect(await outSmall!.text()).toBe("{\"ok\":true}");
+  expect(GZIP_MIN_BYTES).toBe(1024);
+
+  const sse = new Response(new ReadableStream(), { headers: { "Content-Type": "text/event-stream" } });
+  expect(isCompressibleResponse(sse)).toBe(false);
+  expect(await maybeGzipResponse(reqWith("gzip"), sse)).toBe(sse);
+
+  const encoded = json(big, { "Content-Encoding": "br" });
+  expect(await maybeGzipResponse(reqWith("gzip"), encoded)).toBe(encoded);
+
+  const noContent = new Response(null, { status: 204 });
+  expect(await maybeGzipResponse(reqWith("gzip"), noContent)).toBe(noContent);
+
+  const head = json(big);
+  expect(await maybeGzipResponse(reqWith("gzip", "HEAD"), head)).toBe(head);
+
+  // /api/files downloads: Range replies and attachments keep their exact byte lengths (CI #509/#514 caught this)
+  const partial = new Response("x".repeat(4096), { status: 206, headers: { "Content-Type": "text/plain", "Content-Range": "bytes 0-4095/8192" } });
+  expect(await maybeGzipResponse(reqWith("gzip"), partial)).toBe(partial);
+  const attachment = new Response("y".repeat(4096), { status: 200, headers: { "Content-Type": "text/plain", "Content-Disposition": "attachment; filename=\"a.txt\"" } });
+  expect(await maybeGzipResponse(reqWith("gzip"), attachment)).toBe(attachment);
+
+  const binary = new Response(new Uint8Array(4096), { headers: { "Content-Type": "image/png" } });
+  expect(await maybeGzipResponse(reqWith("gzip"), binary)).toBe(binary);
+
+  expect(await maybeGzipResponse(reqWith("gzip"), undefined)).toBeUndefined();
+});
+
+test("trimLightTask keeps a one-line preview under the cap", () => {
+  expect(trimLightTask(null)).toBeNull();
+  expect(trimLightTask("   ")).toBeNull();
+  expect(trimLightTask("a\n  b")).toBe("a b");
+  const long = "字".repeat(LIGHT_TASK_MAX_CHARS + 40);
+  const t = trimLightTask(long)!;
+  expect(t.endsWith("…")).toBe(true);
+  expect([...t].length).toBe(LIGHT_TASK_MAX_CHARS + 1);
+  expect(trimLightTask("short")).toBe("short");
+});

package/src/http-gzip.ts

@@ -0,0 +1,60 @@
+// 2026-09-16(Vincent:「发一个消息都要被吞一段时间」「打开窗口历史很久才出来」):
+// 桌面端经 RELAY 连 hub,链路实测只有 ~13 KB/s;/api/status?light=1 128 KB 要 17 s,
+// 一页 20 条任务 41 KB 要 5.6 s,而 hub 从不压缩。gzip 后 128 KB → 31 KB、137 KB → 49 KB。
+// 只在客户端明确 `Accept-Encoding: gzip` 时压;text/event-stream(SSE)与流式 body 一律不碰。
+export const GZIP_MIN_BYTES = 1024;
+
+const COMPRESSIBLE = /^(application\/json|text\/(plain|html|css|javascript)|application\/javascript)\b/i;
+
+export function wantsGzip(req: Request): boolean {
+  const ae = req.headers.get("accept-encoding") || "";
+  for (const part of ae.split(",")) {
+    const [coding, ...params] = part.trim().split(";").map((x) => x.trim());
+    if (coding.toLowerCase() !== "gzip") continue;
+    const q = params.find((x) => /^q=/i.test(x));
+    if (!q) return true;
+    const n = Number(q.slice(2));
+    return Number.isFinite(n) && n > 0;
+  }
+  return false;
+}
+
+export function isCompressibleResponse(res: Response): boolean {
+  // 只压完整的 200:206 Partial Content / Content-Range / 附件下载(Content-Disposition)都有自己的
+  // 字节语义(Range 客户端按 Content-Length 数字节),压了就错 —— CI 的 /api/files Range 测试抓到的。
+  if (res.status !== 200 || !res.body) return false;
+  if (res.headers.get("content-encoding") || res.headers.get("content-range") || res.headers.get("content-disposition")) return false;
+  const ct = res.headers.get("content-type") || "";
+  if (/text\/event-stream/i.test(ct)) return false;
+  return COMPRESSIBLE.test(ct);
+}
+
+/**
+ * Gzip a finished response when the client asked for it and the body is worth it.
+ * Reads the body once; callers must not have consumed it. Anything streamed or
+ * not compressible is returned untouched (same object).
+ */
+export async function maybeGzipResponse(req: Request, res: Response | undefined | void): Promise<Response | undefined> {
+  if (!res) return res as undefined;
+  if (req.method === "HEAD" || !wantsGzip(req) || !isCompressibleResponse(res)) return res;
+  const raw = new Uint8Array(await res.arrayBuffer());
+  if (raw.byteLength < GZIP_MIN_BYTES) {
+    return new Response(raw, { status: res.status, statusText: res.statusText, headers: res.headers });
+  }
+  const gz = Bun.gzipSync(raw);
+  const headers = new Headers(res.headers);
+  headers.set("Content-Encoding", "gzip");
+  headers.set("Content-Length", String(gz.byteLength));
+  const vary = headers.get("Vary");
+  headers.set("Vary", vary && !/accept-encoding/i.test(vary) ? `${vary}, Accept-Encoding` : (vary || "Accept-Encoding"));
+  return new Response(gz, { status: res.status, statusText: res.statusText, headers });
+}
+
+/** 轻量列表里的 task 只给列表预览用;全文占了 light 载荷的一半以上。 */
+export const LIGHT_TASK_MAX_CHARS = 160;
+export function trimLightTask(task: unknown): string | null {
+  if (typeof task !== "string") return null;
+  const t = task.replace(/\s+/g, " ").trim();
+  if (!t) return null;
+  return t.length > LIGHT_TASK_MAX_CHARS ? `${t.slice(0, LIGHT_TASK_MAX_CHARS)}…` : t;
+}

package/src/hub-timestamp.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+import { parseHubTimestamp } from "./hub-timestamp";
+
+const RAW = "2026-08-30 21:11:24";                    // sessions.last_seen_at 的真实取值
+const TRUE_UTC = Date.UTC(2026, 7, 30, 21, 11, 24);
+
+describe("parseHubTimestamp (#1650)", () => {
+  test("🔴 非 UTC 时区下也必须解出同一个 UTC 时刻", () => {
+    // `bun test` 把测试进程时区固定成 UTC(getTimezoneOffset() === 0)。
+    // 在 UTC 下,「补 Z」和「不补 Z」解析出**同一个数** —— 这个函数存在的那个
+    // 缺陷在测试进程里**结构上不可见**。所以这一条必须开 TZ≠UTC 的子进程。
+    // 实测:去掉补 Z,本文件其余各条**全绿**。
+    const child = `import { parseHubTimestamp } from ${JSON.stringify(import.meta.dir + "/hub-timestamp.ts")};
+process.stdout.write(new Date().getTimezoneOffset() + "," + parseHubTimestamp(${JSON.stringify(RAW)}));`;
+    const r = Bun.spawnSync(["bun", "-e", child], { env: { ...process.env, TZ: "Asia/Shanghai" } });
+    const [offset, parsed] = r.stdout.toString().trim().split(",");
+    // 🔴 先断言控制生效:子进程真的不在 UTC。否则 TZ 被忽略时这条又变成空测试。
+    expect(Number(offset)).not.toBe(0);
+    expect(parsed).toBe(String(TRUE_UTC));
+  });
+
+  test("已带 Z / ±HH:MM 的串不再追加时区", () => {
+    expect(parseHubTimestamp("2026-08-30T21:11:24Z")).toBe(TRUE_UTC);
+    expect(parseHubTimestamp("2026-08-30T22:11:24+01:00")).toBe(TRUE_UTC);
+  });
+
+  test("拿不到就返回 null,不返回一个看起来合理的数", () => {
+    for (const bad of [undefined, null, "", "  ", 0, 1788124284000, {}, [], "2026-08-30", "垃圾"]) {
+      expect(parseHubTimestamp(bad as unknown)).toBeNull();
+    }
+  });
+
+  test("🔴 INTEGER 列(epoch 毫秒)不归它管 —— 传数字必须返回 null,而不是悄悄接受", () => {
+    // external_schedule_edits.* 是 INTEGER。如果有人把本函数用在那儿,
+    // 应当立刻拿到 null 而不是一个错的时刻。
+    expect(parseHubTimestamp(TRUE_UTC)).toBeNull();
+  });
+});

package/src/hub-timestamp.ts

@@ -0,0 +1,27 @@
+/**
+ * #1650 — hub 的 TEXT 时间戳列是 SQLite `datetime('now')` 写的，
+ * 形如 `2026-08-30 21:11:24`：**UTC，但不带任何时区标记**。
+ *
+ * 🔴 `new Date(raw)` / `Date.parse(raw)` 对这种串按**本地时间**解析（ES 规范：
+ *    带时间的形式无偏移时视为本地时间），误差恰好等于主机时区偏移，**而且不报错**：
+ *
+ *      TZ=UTC                   误差  0h
+ *      TZ=Asia/Shanghai         误差 -8h   （看起来更陈旧）
+ *      TZ=America/Los_Angeles   误差 +7h   （看起来更新鲜 ← 朝好的一侧错）
+ *
+ * 🔴 **只对 TEXT 列用它。** 同一个字段名在不同表里可能是不同类型：
+ *      sessions.last_seen_at / licenses.expires_at   → TEXT（要用本函数）
+ *      external_schedule_edits.expires_at 等 4 列     → INTEGER（epoch 毫秒，直接 new Date 就对）
+ *    按字段名判会判错 —— 见 #1650 里的更正。
+ *
+ * 与 agent-network 侧的同名函数是**有意的重复**：server 包不依赖 agent-network，
+ * 仓里也没有共享 lib。两边各自带测试。
+ */
+export function parseHubTimestamp(raw: unknown): number | null {
+  if (typeof raw !== "string") return null;
+  const t = raw.trim();
+  if (!/^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}:\d{2}/.test(t)) return null;
+  const hasZone = /([Zz]|[+-]\d{2}:?\d{2})$/.test(t);
+  const ms = Date.parse(t.replace(" ", "T") + (hasZone ? "" : "Z"));
+  return Number.isFinite(ms) ? ms : null;
+}

package/src/human-dm.ts

@@ -0,0 +1,149 @@
+// 多用户账号:人与人私信(同一网络里的两个用户之间)。
+//
+// 投递复用 user_inbox(与 send_desktop_message 同一张表、同一条 /events/users/me 推送、同一套
+// /api/messages?scope=user 未读与 ack),另外记下 sender_user_id —— 由 Hub 按发信人的用户令牌写入,
+// 不是客户端声称的 from_session。会话记录按 (收件人, sender_user_id) 双向取,所以发信人看得到自己发的。
+//
+// 与 Agent 权限无关:受限成员(看不到任何 Agent 的成员)照样能和网络里的其他人私信。
+
+import { db, uuidv4 } from "./db.js";
+import { getUserNetworkRole } from "./auth.js";
+import { isAgentRestricted } from "./agent-access.js";
+import { pushUserEvent, hasUserSubscribers } from "./push.js";
+import { existsSync, readFileSync } from "fs";
+import { FILE_ID_REGEX, indexEntryPath, validateAttachments, validateIndexEntry } from "./uploads.js";
+import { restrictedMemberCanUseFile } from "./restricted-files.js";
+import { redactMessageRow } from "./redact-tokens.js";
+
+export const HUMAN_DM_KIND = "human_dm";
+const MAX_DM_CHARS = 10_000;
+
+export type HumanDmSendInput = {
+  networkId: string;
+  sender: { userId: string; username: string };
+  toUserId?: unknown;
+  toUsername?: unknown;
+  message?: unknown;
+  attachments?: unknown;
+  clientRequestId?: unknown;
+};
+
+export type HumanDmSendResult =
+  | { ok: true; message: Record<string, unknown>; delivered: boolean }
+  | { ok: false; error: string; status: number };
+
+export function sendHumanDm(input: HumanDmSendInput): HumanDmSendResult {
+  const { networkId, sender } = input;
+  if (!getUserNetworkRole(sender.userId, networkId)) return { ok: false, error: "not a member of this network", status: 403 };
+  const text = typeof input.message === "string" ? input.message : "";
+  if (text.length > MAX_DM_CHARS) return { ok: false, error: "message_too_long", status: 400 };
+
+  const byId = typeof input.toUserId === "string" && input.toUserId
+    ? db.get<{ user_id: string; username: string }>("SELECT user_id, username FROM users WHERE user_id = ?1", input.toUserId)
+    : null;
+  const byName = typeof input.toUsername === "string" && input.toUsername
+    ? db.get<{ user_id: string; username: string }>("SELECT user_id, username FROM users WHERE username = ?1", input.toUsername)
+    : null;
+  if (byId && byName && byId.user_id !== byName.user_id) return { ok: false, error: "dm_target_mismatch", status: 400 };
+  const target = byId ?? byName;
+  // 不存在与不在本网络同一个错误,不给用户名探测留差异。
+  if (!target || !getUserNetworkRole(target.user_id, networkId)) return { ok: false, error: "dm_target_not_in_network", status: 404 };
+  if (target.user_id === sender.userId) return { ok: false, error: "dm_to_self", status: 400 };
+
+  const attachments = validateAttachments(input.attachments);
+  if (!attachments.ok) return { ok: false, error: "bad_attachments", status: 400 };
+  if (!text.trim() && attachments.attachments.length === 0) return { ok: false, error: "message_required", status: 400 };
+  const restricted = isAgentRestricted(sender.userId, networkId);
+  for (const a of attachments.attachments) {
+    const fileId = (a as { file_id?: string }).file_id;
+    if (!fileId) continue;
+    const usable = restricted
+      ? restrictedMemberCanUseFile(sender.userId, sender.username, networkId, fileId)
+      : fileInNetwork(networkId, fileId);
+    if (!usable) return { ok: false, error: "attachment_not_accessible", status: 403 };
+  }
+
+  const clientRequestId = typeof input.clientRequestId === "string" && /^[A-Za-z0-9._-]{1,80}$/.test(input.clientRequestId)
+    ? input.clientRequestId : null;
+  // 同一个气泡重试:按 (发信人, client_request_id) 定出同一个 message_id,重投不产生第二条。
+  const messageId = clientRequestId
+    ? `dm_${sender.userId}_${clientRequestId}`.slice(0, 120)
+    : `dm_${uuidv4()}`;
+  const metaJson = attachments.attachments.length ? JSON.stringify({ attachments: attachments.attachments }) : null;
+
+  db.transaction(() => {
+    db.run(
+      // created_at 带毫秒:同一秒里一来一回的两条私信要能排出先后(秒级的 datetime('now') 排不出)。
+      `INSERT INTO user_inbox (message_id, network_id, user_id, from_session, kind, title, content, severity, meta_json, sender_user_id, created_at)
+       VALUES (?1, ?2, ?3, ?4, ?5, NULL, ?6, 'info', ?7, ?8, strftime('%Y-%m-%d %H:%M:%f', 'now'))
+       ON CONFLICT(message_id) DO NOTHING`,
+      [messageId, networkId, target.user_id, sender.username, HUMAN_DM_KIND, text, metaJson, sender.userId],
+    );
+    db.run(
+      `INSERT INTO audit_log (user_id, username, action, target_type, target_id, detail, network_id)
+       VALUES (?1, ?2, 'human_dm_sent', 'user', ?3, ?4, ?5)`,
+      [sender.userId, sender.username, target.user_id, JSON.stringify({ message_id: messageId, attachments: attachments.attachments.length }), networkId],
+    );
+  });
+  const row = db.get<Record<string, unknown>>(
+    `SELECT message_id, network_id, user_id, sender_user_id, from_session, kind, content, meta_json, acked, created_at
+       FROM user_inbox WHERE message_id = ?1`,
+    messageId,
+  )!;
+  // 推送在提交之后(与 send_desktop_message 同一条规矩:回滚的消息不能先被看见)。
+  const delivered = hasUserSubscribers(networkId, target.user_id);
+  pushUserEvent(networkId, target.user_id, {
+    type: "desktop_message",
+    message_id: messageId,
+    kind: HUMAN_DM_KIND,
+    from: sender.username,
+    from_user_id: sender.userId,
+    title: null,
+    message: text,
+    severity: "info",
+    created_at: new Date().toISOString(),
+    ...(metaJson ? { meta: JSON.parse(metaJson) } : {}),
+  });
+  return { ok: true, message: redactMessageRow(row), delivered };
+}
+
+/** 不受限的成员带附件:文件必须属于这个网络(防把别的网络的 file_id 塞进来)。 */
+function fileInNetwork(networkId: string, fileId: string): boolean {
+  if (!FILE_ID_REGEX.test(fileId)) return false;
+  const path = indexEntryPath(fileId);
+  if (!path || !existsSync(path)) return false;
+  try {
+    const entry = JSON.parse(readFileSync(path, "utf8"));
+    return validateIndexEntry(entry) && entry.file_id === fileId && entry.network_id === networkId;
+  } catch { return false; }
+}
+
+/** 我和某人的私信记录(双向),新的在前。before = 上一页最后一条的 created_at。 */
+export function listDmThread(networkId: string, meUserId: string, otherUserId: string, limit = 50, before?: string | null) {
+  const params: unknown[] = [networkId, meUserId, otherUserId];
+  let sql = `SELECT message_id, network_id, user_id, sender_user_id, from_session, kind, content, meta_json, acked, created_at
+               FROM user_inbox
+              WHERE network_id = ?1 AND kind = '${HUMAN_DM_KIND}'
+                AND ((user_id = ?2 AND sender_user_id = ?3) OR (user_id = ?3 AND sender_user_id = ?2))`;
+  if (before) { params.push(before); sql += ` AND created_at < ?${params.length}`; }
+  params.push(Math.max(1, Math.min(limit, 200)));
+  sql += ` ORDER BY created_at DESC, rowid DESC LIMIT ?${params.length}`;
+  return db.all<Record<string, unknown>>(sql, ...params).map((row) => ({
+    ...redactMessageRow(row),
+    direction: row.sender_user_id === meUserId ? "out" : "in",
+  }));
+}
+
+/** 我在这个网络里的私信会话:每个对方一行,最后一条时间 + 我这边的未读数。 */
+export function listDmThreads(networkId: string, meUserId: string) {
+  return db.all<{ other_user_id: string; last_at: string; unread: number }>(
+    `SELECT other_user_id, MAX(created_at) AS last_at, SUM(unread) AS unread FROM (
+       SELECT sender_user_id AS other_user_id, created_at, CASE WHEN acked = 0 THEN 1 ELSE 0 END AS unread
+         FROM user_inbox WHERE network_id = ?1 AND user_id = ?2 AND kind = '${HUMAN_DM_KIND}' AND sender_user_id IS NOT NULL
+       UNION ALL
+       SELECT user_id AS other_user_id, created_at, 0 AS unread
+         FROM user_inbox WHERE network_id = ?1 AND sender_user_id = ?2 AND kind = '${HUMAN_DM_KIND}'
+     ) GROUP BY other_user_id ORDER BY last_at DESC`,
+    networkId, meUserId,
+  ).map((r) => ({ other_user_id: r.other_user_id, last_at: r.last_at, unread: Number(r.unread ?? 0) }));
+}

package/src/inbox-count-sse.test.ts

@@ -0,0 +1,310 @@
+// SSE `inbox_count` contract for the message-shaped events.
+//
+// Background: `new_task` has shipped a real unacked count since #1304,
+// but `new_message` / `new_reply` carried NO count at all and
+// `broadcast` carried a hardcoded `inbox_count: 1`. A client that
+// renders "N new" from the SSE payload therefore never moved for plain
+// messages and replies, and showed a constant 1 for broadcasts.
+//
+// Gate discipline: every assertion below expects a count that is NOT 1
+// (pre-seeded unacked rows push the expected value to 2 or 3). A
+// hardcoded `1` — the exact defect being fixed — fails these tests
+// rather than passing them. Asserting `=== 1` would have been a fake
+// gate that the old code satisfied.
+//
+// Run: COMMHUB_DB=/tmp/inbox-count-sse.db bun test src/inbox-count-sse.test.ts
+
+import { afterAll, beforeEach, afterEach, describe, expect, test } from "bun:test";
+import { db, uuidv4 } from "./db.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools } from "./tools.js";
+import { __resetSSEClientsForTest, createSSEStream } from "./push.js";
+import { pendingInboxCount } from "./inbox-count.js";
+
+const NET = "net_inboxcount";
+const OWNER = "u_inboxcount_owner";
+const RECV = "peer-inboxcount-recv";   // receives messages/replies
+const OTHER = "peer-inboxcount-other"; // second broadcast recipient
+const SENDER = "peer-inboxcount-send";
+// #1440 ① — a broadcast target the lifecycle guard skips.
+const STOPPED = "peer-inboxcount-stopped";
+const ALIASES = [RECV, OTHER, SENDER];
+
+type ToolHandler = (args: any, extra?: any) => Promise<{ content: Array<{ type: "text"; text: string }> }>;
+
+function cleanup() {
+  for (const t of ["tasks", "inbox", "task_events"]) {
+    try { db.run(`DELETE FROM ${t} WHERE network_id = ?1`, [NET]); } catch {}
+  }
+  try { db.run("DELETE FROM sessions WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM nodes WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM network_members WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM networks WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM users WHERE user_id = ?1", [OWNER]); } catch {}
+}
+
+function seed() {
+  db.run(
+    `INSERT INTO users (user_id, username, password_hash, role, created_at)
+     VALUES (?1, ?1, 'x', 'user', datetime('now'))`,
+    [OWNER],
+  );
+  db.run(`INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?1, ?2, datetime('now'))`, [NET, OWNER]);
+  db.run(`INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, 'owner', datetime('now'))`, [OWNER, NET]);
+  for (const alias of ALIASES) {
+    db.run(
+      `INSERT INTO nodes (node_id, node_name, alias, network_id, hostname, created_at, updated_at, lifecycle_state)
+       VALUES (?1, ?2, ?2, ?3, ?4, datetime('now'), datetime('now'), 'active')`,
+      [`node_${alias}`, alias, NET, `host-${alias}`],
+    );
+    db.run(
+      `INSERT INTO sessions (resume_id, alias, status, node_id, network_id, updated_at, last_seen_at)
+       VALUES (?1, ?2, 'idle', ?3, ?4, datetime('now'), datetime('now'))`,
+      [`res_${alias}`, alias, `node_${alias}`, NET],
+    );
+  }
+  // A session that broadcast will select as a target, but whose node is
+  // NOT active — assertNodeActive skips it, so it gets no inbox row.
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, hostname, created_at, updated_at, lifecycle_state)
+     VALUES (?1, ?2, ?2, ?3, ?4, datetime('now'), datetime('now'), 'stopped')`,
+    [`node_${STOPPED}`, STOPPED, NET, `host-${STOPPED}`],
+  );
+  db.run(
+    `INSERT INTO sessions (resume_id, alias, status, node_id, network_id, updated_at, last_seen_at)
+     VALUES (?1, ?2, 'idle', ?3, ?4, datetime('now'), datetime('now'))`,
+    [`res_${STOPPED}`, STOPPED, `node_${STOPPED}`, NET],
+  );
+}
+
+beforeEach(() => { cleanup(); seed(); });
+afterEach(() => { __resetSSEClientsForTest(); });
+afterAll(cleanup);
+
+function buildHandlers(alias: string): Record<string, ToolHandler> {
+  const server = new McpServer({ name: "test", version: "0" }) as any;
+  const tools: Record<string, ToolHandler> = {};
+  const origTool = server.tool.bind(server);
+  server.tool = (name: string, _desc: string, schema: any, handler: ToolHandler) => {
+    tools[name] = handler;
+    return origTool(name, _desc, schema, handler);
+  };
+  registerTools(server, undefined, NET, OWNER, alias, true, null);
+  return tools;
+}
+
+async function call(handler: ToolHandler, args: any): Promise<Record<string, any>> {
+  const r = await handler(args);
+  return JSON.parse(r.content[0].text);
+}
+
+/** Read the next SSE data frame, with a hard timeout so a silent stream
+ *  fails instead of hanging. Skips keepalive comment frames. */
+async function readFrame(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  timeoutMs = 2_000,
+): Promise<Record<string, any>> {
+  const decoder = new TextDecoder();
+  let buf = "";
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const result = await Promise.race([
+      reader.read(),
+      new Promise<never>((_, rej) =>
+        setTimeout(() => rej(new Error(`no SSE frame within ${timeoutMs}ms`)), deadline - Date.now()),
+      ),
+    ]);
+    if (result.done) throw new Error("SSE stream ended unexpectedly");
+    buf += decoder.decode(result.value, { stream: true });
+    const sep = buf.indexOf("\n\n");
+    if (sep === -1) continue;
+    const rawFrame = buf.slice(0, sep);
+    buf = buf.slice(sep + 2);
+    const dataLine = rawFrame.split("\n").find((l) => l.startsWith("data: "));
+    if (!dataLine) continue;
+    return JSON.parse(dataLine.slice(6));
+  }
+  throw new Error(`no SSE frame within ${timeoutMs}ms`);
+}
+
+/** Subscribe and swallow the initial `connected` frame. */
+async function subscribe(alias: string) {
+  const reader = createSSEStream(alias, NET).body!.getReader();
+  await readFrame(reader);
+  return reader;
+}
+
+/** Pre-existing unacked inbox rows, so the expected count is never 1. */
+function seedUnacked(alias: string, n: number, type = "message") {
+  for (let i = 0; i < n; i++) {
+    db.run(
+      `INSERT INTO inbox (id, session_name, node_id, type, priority, content, from_session, network_id)
+       VALUES (?1, ?2, ?3, ?4, 'normal', ?5, ?6, ?7)`,
+      [uuidv4(), alias, `node_${alias}`, type, `backlog ${i}`, SENDER, NET],
+    );
+  }
+}
+
+function makeTask(from: string, to: string, content: string, status = "delivered"): string {
+  const id = uuidv4();
+  db.run(
+    `INSERT INTO tasks (task_id, from_name, to_name, priority, status, content, requires_response, created_at, network_id)
+     VALUES (?1, ?2, ?3, 'normal', ?4, ?5, 'reply', datetime('now'), ?6)`,
+    [id, from, to, status, content, NET],
+  );
+  return id;
+}
+
+describe("SSE inbox_count", () => {
+  test("new_message carries the recipient's real unacked count, not a hardcoded 1", async () => {
+    seedUnacked(RECV, 2);
+    const reader = await subscribe(RECV);
+
+    const tools = buildHandlers(SENDER);
+    const res = await call(tools.send_message, { alias: RECV, message: "hello", network_id: NET });
+    expect(res.ok ?? true).not.toBe(false);
+
+    const evt = await readFrame(reader);
+    expect(evt.type).toBe("new_message");
+    // 2 seeded + this one. A hardcoded 1 — or a missing field — fails here.
+    expect(evt.inbox_count).toBe(3);
+    expect(evt.inbox_count).toBe(pendingInboxCount(RECV, NET));
+  });
+
+  test("new_reply carries the reply target's real unacked count", async () => {
+    seedUnacked(RECV, 1);
+    const taskId = makeTask(RECV, SENDER, "please do the thing");
+    const reader = await subscribe(RECV);
+
+    const tools = buildHandlers(SENDER);
+    const res = await call(tools.send_reply, {
+      alias: RECV,
+      text: "done",
+      in_reply_to: taskId,
+      status: "completed",
+      network_id: NET,
+    });
+    expect(res.ok).toBe(true);
+
+    const evt = await readFrame(reader);
+    expect(evt.type).toBe("new_reply");
+    // 1 seeded + the reply row. Not 1, and not absent.
+    expect(evt.inbox_count).toBe(2);
+    expect(evt.inbox_count).toBe(pendingInboxCount(RECV, NET));
+  });
+
+  test("broadcast counts per recipient instead of shipping a constant 1", async () => {
+    // Asymmetric backlogs: if the payload were hardcoded, both
+    // recipients would report the same number. They must not.
+    seedUnacked(RECV, 2);
+    const recvReader = await subscribe(RECV);
+    const otherReader = await subscribe(OTHER);
+
+    const tools = buildHandlers(SENDER);
+    await call(tools.broadcast, { message: "all hands", network_id: NET });
+
+    const recvEvt = await readFrame(recvReader);
+    const otherEvt = await readFrame(otherReader);
+    expect(recvEvt.type).toBe("broadcast");
+    expect(otherEvt.type).toBe("broadcast");
+
+    // RECV: 2 seeded + the broadcast row. OTHER: only the broadcast row.
+    expect(recvEvt.inbox_count).toBe(3);
+    expect(otherEvt.inbox_count).toBe(1);
+    expect(recvEvt.inbox_count).not.toBe(otherEvt.inbox_count);
+  });
+
+  test("acked rows are excluded — the count tracks what is still unread", async () => {
+    seedUnacked(RECV, 3);
+    db.run("UPDATE inbox SET acked = 1 WHERE session_name = ?1 AND network_id = ?2", [RECV, NET]);
+    const reader = await subscribe(RECV);
+
+    const tools = buildHandlers(SENDER);
+    await call(tools.send_message, { alias: RECV, message: "after the catch-up", network_id: NET });
+
+    const evt = await readFrame(reader);
+    // 3 acked rows contribute nothing; only the new one is outstanding.
+    expect(evt.inbox_count).toBe(1);
+  });
+});
+
+// #1440 ② — `retry_task` and `reassign_task` re-queue a task and push
+// `new_task`, but both shipped a hardcoded `inbox_count: 1` while the
+// hub already knew the real number. Same defect family as the
+// `broadcast` case above; same gate discipline — the expected counts
+// here are 3, so a hardcoded 1 cannot satisfy them.
+describe("#1440 new_task inbox_count on requeue paths", () => {
+  test("retry_task carries the real unacked count, not a hardcoded 1", async () => {
+    seedUnacked(RECV, 2);
+    const taskId = makeTask(SENDER, RECV, "flaky job", "failed");
+    const reader = await subscribe(RECV);
+
+    const tools = buildHandlers(SENDER);
+    const res = await call(tools.retry_task, { task_id: taskId, network_id: NET });
+    expect(res.ok).toBe(true);
+
+    const evt = await readFrame(reader);
+    expect(evt.type).toBe("new_task");
+    // 2 seeded + the re-queued task row.
+    expect(evt.inbox_count).toBe(3);
+    expect(evt.inbox_count).toBe(pendingInboxCount(RECV, NET));
+  });
+
+  test("reassign_task carries the NEW assignee's real unacked count", async () => {
+    seedUnacked(RECV, 2);
+    const taskId = makeTask(SENDER, OTHER, "moved job");
+    const reader = await subscribe(RECV);
+
+    const tools = buildHandlers(SENDER);
+    const res = await call(tools.reassign_task, { task_id: taskId, new_alias: RECV, network_id: NET });
+    expect(res.ok).toBe(true);
+    expect(res.reassigned_to).toBe(RECV);
+
+    const evt = await readFrame(reader);
+    expect(evt.type).toBe("new_task");
+    // 2 seeded on the new assignee + the row reassign just wrote.
+    expect(evt.inbox_count).toBe(3);
+    expect(evt.inbox_count).toBe(pendingInboxCount(RECV, NET));
+  });
+});
+
+// #1440 ① — the broadcast push loop walked every candidate target,
+// including the ones assertNodeActive had just skipped. Those nodes
+// were told "you have a broadcast" while their inbox got no row for it.
+// Before #1439 the hardcoded `inbox_count: 1` hid this: everyone got
+// the same digit, so a spurious event was indistinguishable from a real
+// one.
+describe("#1440 broadcast delivery set", () => {
+  test("a lifecycle-skipped node gets no inbox row AND no broadcast event", async () => {
+    const activeReader = await subscribe(OTHER);
+    const stoppedReader = await subscribe(STOPPED);
+
+    const tools = buildHandlers(SENDER);
+    const res = await call(tools.broadcast, { message: "all hands", network_id: NET });
+
+    // The active recipient is served — this proves the broadcast ran, so
+    // the absence checked below is "not sent", not "not yet sent"
+    // (pushEvent is synchronous inside the handler).
+    const activeEvt = await readFrame(activeReader);
+    expect(activeEvt.type).toBe("broadcast");
+
+    // The skipped node has no row...
+    const rows = db.get<{ cnt: number }>(
+      "SELECT COUNT(*) AS cnt FROM inbox WHERE session_name = ?1 AND type = 'broadcast'",
+      STOPPED,
+    );
+    expect(rows?.cnt).toBe(0);
+    // ...and must therefore receive no event announcing one.
+    await expect(readFrame(stoppedReader, 300)).rejects.toThrow(/no SSE frame/);
+
+    // message_ids covers only the recipients that actually got a row:
+    // RECV + OTHER + SENDER, never STOPPED.
+    expect(res.message_ids).toHaveLength(3);
+    // #1440 ③ — `recipients` counted candidates, not deliveries, so it
+    // disagreed with the documented invariant
+    // ("message_ids.length === recipients", docs-site/docs/api/rest-data.md)
+    // exactly when a node was skipped. 4 sessions, 3 delivered.
+    expect(res.recipients).toBe(res.message_ids.length);
+    expect(res.recipients).toBe(3);
+  });
+});