@sleep2agi/commhub-server 0.9.0-preview.13 → 0.9.0-preview.130

package/src/human-dm.ts

@@ -0,0 +1,215 @@
+// 多用户账号:人与人私信(同一网络里的两个用户之间)。
+//
+// 投递复用 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 { DM_FILE_SCOPE, FILE_ID_REGEX, indexEntryPath, validateAttachments, validateIndexEntry, type UploadIndexEntry } from "./uploads.js";
+import { restrictedMemberCanUseFile } from "./restricted-files.js";
+import { redactMessageRow } from "./redact-tokens.js";
+
+export const HUMAN_DM_KIND = "human_dm";
+export 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 entry = networkFileEntry(networkId, fileId);
+    const usable = restricted
+      ? restrictedMemberCanUseFile(sender.userId, sender.username, networkId, fileId)
+      : !!entry;
+    if (!usable) return { ok: false, error: "attachment_not_accessible", status: 403 };
+    // 私信文件只能由看得见它的人转发:否则任何成员把别人私信里的 file_id 塞进一条自己发出的私信,
+    // 就成了「私信参与者」而解锁它。上传者本人、以及已经在某段私信里收到/发出过它的人可以转。
+    if (entry?.scope === DM_FILE_SCOPE && entry.owner_id !== sender.userId && !dmParticipantSeesFile(sender.userId, networkId, fileId)) {
+      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(() => {
+    insertDmRow({ messageId, networkId, targetUserId: target.user_id, sender, title: null, text, metaJson });
+    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 = pushDmEvent({ messageId, networkId, targetUserId: target.user_id, sender, title: null, text, metaJson });
+  return { ok: true, message: redactMessageRow(row), delivered };
+}
+
+type DmRow = { messageId: string; networkId: string; targetUserId: string; sender: { userId: string; username: string }; title: string | null; text: string; metaJson: string | null };
+
+function insertDmRow(m: DmRow): void {
+  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, ?6, ?7, 'info', ?8, ?9, strftime('%Y-%m-%d %H:%M:%f', 'now'))
+     ON CONFLICT(message_id) DO NOTHING`,
+    [m.messageId, m.networkId, m.targetUserId, m.sender.username, HUMAN_DM_KIND, m.title, m.text, m.metaJson, m.sender.userId],
+  );
+}
+
+/** 推 desktop_message 到收件人的 /events/users/me。返回推送时他有没有在线的订阅。 */
+function pushDmEvent(m: DmRow): boolean {
+  const delivered = hasUserSubscribers(m.networkId, m.targetUserId);
+  pushUserEvent(m.networkId, m.targetUserId, {
+    type: "desktop_message",
+    message_id: m.messageId,
+    kind: HUMAN_DM_KIND,
+    from: m.sender.username,
+    from_user_id: m.sender.userId,
+    title: m.title,
+    message: m.text,
+    severity: "info",
+    created_at: new Date().toISOString(),
+    ...(m.metaJson ? { meta: JSON.parse(m.metaJson) } : {}),
+  });
+  return delivered;
+}
+
+/**
+ * Hub 代某人发的一条私信(参与人改了任务的通知,见 requirement-notify.ts):与人发的私信同一张表、同一条推送,
+ * 所以 App 按私信展示(顶部提示 + 人员列表未读 + 与他的会话里能看到),不用新渠道。
+ * 不校验正文 / 附件(调用方生成),也不记 human_dm_sent 审计(这不是他亲手发的)。
+ * 收件人或发信人已不在网络里 → 不发。返回 false = 没发。
+ */
+export function sendNoticeDm(m: DmRow): boolean {
+  if (m.targetUserId === m.sender.userId) return false;
+  if (!getUserNetworkRole(m.sender.userId, m.networkId) || !getUserNetworkRole(m.targetUserId, m.networkId)) return false;
+  insertDmRow(m);
+  pushDmEvent(m);
+  return true;
+}
+
+/**
+ * 把一条还没读的通知私信改写成合并后的正文(同一段时间里的连续改动并成一条)。
+ * 收件人已经读过(acked)或那行没了 → false,调用方另发一条新的。
+ * 只改库、再推一次同一个 message_id:App 按 message_id 去重,不会第二次弹;会话列表下次拉到的是新正文。
+ */
+export function rewriteUnreadNoticeDm(m: DmRow): boolean {
+  const row = db.get<{ acked: number | boolean | null }>("SELECT acked FROM user_inbox WHERE message_id = ?1 AND user_id = ?2", m.messageId, m.targetUserId);
+  if (!row || row.acked) return false;
+  db.run("UPDATE user_inbox SET content = ?1, meta_json = ?2 WHERE message_id = ?3 AND user_id = ?4", [m.text, m.metaJson, m.messageId, m.targetUserId]);
+  pushDmEvent(m);
+  return true;
+}
+
+/** 带附件:文件必须属于这个网络(防把别的网络的 file_id 塞进来)。返回它的索引条目,不属于 → null。 */
+export function networkFileEntry(networkId: string, fileId: string): UploadIndexEntry | null {
+  if (!FILE_ID_REGEX.test(fileId)) return null;
+  const path = indexEntryPath(fileId);
+  if (!path || !existsSync(path)) return null;
+  try {
+    const entry = JSON.parse(readFileSync(path, "utf8"));
+    return validateIndexEntry(entry) && entry.file_id === fileId && entry.network_id === networkId ? entry : null;
+  } catch { return null; }
+}
+
+/**
+ * 这个用户是不是某段带着这个文件的私信里的一方(收到的或发出的)。私信文件(scope=dm)的下载只认它
+ * 和上传者本人(server.ts authorizeFileDownload)。LIKE 只做预筛,真正的判定按 attachments 键解析。
+ */
+export function dmParticipantSeesFile(userId: string, networkId: string, fileId: string): boolean {
+  if (!FILE_ID_REGEX.test(fileId)) return false;
+  const needle = `%"${fileId.replace(/_/g, "\\_")}"%`;
+  const rows = db.all<{ meta_json: string | null }>(
+    `SELECT meta_json FROM user_inbox
+      WHERE network_id = ?1 AND kind = '${HUMAN_DM_KIND}' AND (user_id = ?2 OR sender_user_id = ?2)
+        AND meta_json LIKE ?3 ESCAPE '\\' LIMIT 50`,
+    networkId, userId, needle,
+  );
+  return rows.some((row) => {
+    try {
+      const list = JSON.parse(row.meta_json ?? "null")?.attachments;
+      return Array.isArray(list) && list.some((a: any) => a && typeof a === "object" && a.file_id === fileId);
+    } 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-caller.ts

@@ -0,0 +1,49 @@
+import { db } from "./db.js";
+import { getUserNetworkRole } from "./auth.js";
+import { resolveNodeCaller } from "./create-node.js";
+import { resolveCanonicalAlias } from "./rename.js";
+
+type InboxCaller = {
+  tokenId?: string | null;
+  userId?: string | null;
+  networkId?: string | null;
+  nodeToken: boolean;
+  identityRejected: boolean;
+};
+
+/** Inbox reads and ACKs act as the recipient, not as a dispatch target. */
+export function resolveInboxCaller(alias: string, caller: InboxCaller):
+  { ok: true; alias: string } | { ok: false; error: string } {
+  const denied = { ok: false as const, error: "inbox_identity_mismatch" };
+  if (caller.identityRejected) return denied;
+  const requested = alias.trim();
+  if (caller.nodeToken) {
+    const node = resolveNodeCaller(caller.tokenId);
+    if (node.ok) {
+      if (node.networkId !== caller.networkId) return denied;
+      const canonical = resolveCanonicalAlias(node.networkId, requested).alias;
+      return canonical === node.alias ? { ok: true, alias: node.alias } : denied;
+    }
+    // Registration tokens are network-scoped human tokens, not node tokens.
+    // Missing/foreign/ambiguous node identities never fall back to the issuer.
+    if (node.reason !== "not_a_node_token" || !caller.tokenId) return denied;
+    const token = db.get<{ name: string | null }>(
+      "SELECT name FROM api_tokens WHERE token_id = ?1 AND revoked_at IS NULL", caller.tokenId,
+    );
+    if (!token || token.name?.startsWith("node:")) return denied;
+  }
+  // Preserve open-development and legacy global-token mode.
+  if (!caller.userId) return { ok: true, alias: requested };
+  const user = db.get<{ username: string }>("SELECT username FROM users WHERE user_id = ?1", caller.userId);
+  if (user?.username === requested) return { ok: true, alias: requested };
+  if (!caller.networkId) return { ok: false, error: "network_id_required" };
+  const role = getUserNetworkRole(caller.userId, caller.networkId);
+  if (!role) return denied;
+  const canonical = resolveCanonicalAlias(caller.networkId, requested).alias;
+  if (role === "owner" || role === "admin") return { ok: true, alias: canonical };
+  const owned = db.get<{ node_id: string }>(
+    "SELECT node_id FROM nodes WHERE alias = ?1 AND network_id = ?2 AND owner_user_id = ?3 LIMIT 1",
+    canonical, caller.networkId, caller.userId,
+  );
+  return owned ? { ok: true, alias: canonical } : denied;
+}

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);
+  });
+});

package/src/inbox-count.ts

@@ -0,0 +1,29 @@
+import { db } from "./db.js";
+
+/**
+ * Unacked inbox rows for `alias` — the number a client should show as
+ * "new". This is the count `new_task` has shipped since #1304; it is
+ * lifted here verbatim so every SSE event that carries `inbox_count`
+ * derives it the same way instead of hardcoding a digit.
+ *
+ * The SQL and its network scoping are unchanged from the `new_task`
+ * sites (tools.ts / server.ts): falsy `networkId` means "no network
+ * filter", matching both `addScope()` and the inline `if (taskNetId)`
+ * guard those sites already use.
+ *
+ * The `?? 1` fallback only fires if the COUNT itself returns no row,
+ * which SQLite does not do. It is not a default count: it is the
+ * fail-closed direction for this gate. Every caller pushes right after
+ * inserting an inbox row, so the floor is genuinely 1, and under-
+ * reporting an unread (badge says 0, a message is sitting there) is the
+ * failure this event exists to prevent.
+ */
+export function pendingInboxCount(alias: string, networkId?: string | null): number {
+  const params: any[] = [alias];
+  let sql = "SELECT COUNT(*) as cnt FROM inbox WHERE session_name = ?1 AND acked = 0";
+  if (networkId) {
+    sql += " AND network_id = ?2";
+    params.push(networkId);
+  }
+  return db.get<{ cnt: number }>(sql, ...params)?.cnt ?? 1;
+}