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

package/src/delivered-without-push.test.ts

@@ -0,0 +1,140 @@
+// f015d9d6 症状①：tasks.status 被置为 'delivered'，而 SSE 推送根本没发出。
+//
+// send_task 无条件以字面量 'delivered' 插入 tasks 行，推送却另外被
+// `if (target.state === "online")` 挡着（tools.ts:1432）。同一段代码里给
+// network observer 的事件把同一件事标成 "queued" —— 也就是说代码**知道**
+// 它没投出去，却仍然把 delivered 写进了 tasks.status。
+//
+// 而 "online" 的判据是 resolveDeliveryTarget 里的
+//   stale = now - (last_seen_at || updated_at) > 5 分钟
+// 且 last_seen_at 只在 report_status 时刷新（tools.ts:674/702）。
+// 全网「停发心跳/状态类消息」的省额度规则之下，一个安静的 MCP 会话必然变 stale。
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { db } from "./db.js";
+import { registerTools } from "./tools.js";
+import { __resetSSEClientsForTest, createSSEStream } from "./push.js";
+
+const NET = "net_delivered_push_f015";
+const USER = "user_delivered_push_f015";
+const SENDER = "sender-f015b";
+const TARGET = "quiet-mcp-f015b";
+
+type ToolHandler = (args: any) => Promise<{ content: Array<{ type: "text"; text: string }> }>;
+
+function cleanup() {
+  __resetSSEClientsForTest();
+  for (const t of ["tasks", "inbox", "task_events", "sessions", "api_tokens", "nodes", "rename_txn"]) {
+    try { db.run(`DELETE FROM ${t} 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", [USER]); } catch {}
+}
+
+/** minutesAgo 控制目标会话的 last_seen_at —— 这是本文件唯一要动的变量。 */
+function seed(minutesAgo: number) {
+  db.run("INSERT INTO users (user_id, username, password_hash, role, created_at) VALUES (?1, ?1, 'x', 'admin', datetime('now'))", [USER]);
+  db.run("INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?1, ?2, datetime('now'))", [NET, USER]);
+  db.run("INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, 'owner', datetime('now'))", [USER, NET]);
+  for (const alias of [SENDER, TARGET]) {
+    db.run(
+      "INSERT INTO api_tokens (token_id, token_hash, user_id, network_id, name, scope) VALUES (?1, ?2, ?3, ?4, ?5, 'network')",
+      [`token-${alias}`, `hash-${alias}`, USER, NET, `node:${alias}`],
+    );
+  }
+  db.run(
+    "INSERT INTO sessions (resume_id, alias, status, node_id, network_id, updated_at, last_seen_at) VALUES (?1, ?1, 'idle', NULL, ?2, datetime('now'), datetime('now', ?3))",
+    [SENDER, NET, "-1 minutes"],
+  );
+  // 🔴 目标：MCP 挂载的 claude-code 会话形状（node_id NULL），
+  //    status 是 'idle'（不是 offline），只是安静了 minutesAgo 分钟。
+  db.run(
+    "INSERT INTO sessions (resume_id, alias, status, node_id, network_id, updated_at, last_seen_at) VALUES (?1, ?2, 'idle', NULL, ?3, datetime('now', ?4), datetime('now', ?4))",
+    [`cc-n_${TARGET}`, TARGET, NET, `-${minutesAgo} minutes`],
+  );
+}
+
+function toolsFor(alias: string): Record<string, ToolHandler> {
+  const server = new McpServer({ name: "delivered-push-f015", version: "0" }) as any;
+  const tools: Record<string, ToolHandler> = {};
+  const original = server.tool.bind(server);
+  server.tool = (name: string, description: string, schema: any, handler: ToolHandler) => {
+    tools[name] = handler; return original(name, description, schema, handler);
+  };
+  registerTools(server, undefined, NET, USER, alias, true, `token-${alias}`);
+  return tools;
+}
+
+/** 从订阅者那一侧真正读出字节 —— 地面真相，不是连接计数。 */
+async function readUntil(reader: ReadableStreamDefaultReader<Uint8Array>, needle: string, ms = 1500): Promise<string | null> {
+  const dec = new TextDecoder();
+  let buf = "";
+  const deadline = Date.now() + ms;
+  while (Date.now() < deadline) {
+    const chunk = await Promise.race([
+      reader.read(),
+      new Promise<{ done: true; value: undefined }>((r) => setTimeout(() => r({ done: true, value: undefined }), 200)),
+    ]);
+    if (chunk.value) buf += dec.decode(chunk.value, { stream: true });
+    if (buf.includes(needle)) return buf;
+  }
+  return null;
+}
+
+let sendSeq = 0;
+/** minutesAgo = 目标安静了多久；withSubscriber = 是否真的有人连着。 */
+async function send(minutesAgo: number, withSubscriber = true) {
+  cleanup(); seed(minutesAgo);
+  let reader: ReadableStreamDefaultReader<Uint8Array> | null = null;
+  if (withSubscriber) {
+    const res = createSSEStream(TARGET, NET);
+    reader = res.body!.getReader();
+  }
+  const r = await toolsFor(SENDER).send_task({ alias: TARGET, task: `ping-${++sendSeq}`, priority: "normal" });
+  const out = JSON.parse(r.content[0].text);
+  const row = db.get<{ status: string }>("SELECT status FROM tasks WHERE to_name = ?1 AND network_id = ?2", TARGET, NET);
+  const received = reader ? await readUntil(reader, "new_task") : null;
+  return { out, taskStatus: row?.status ?? null, received };
+}
+
+describe("f015d9d6 症状① — delivered 置位与实际推送不同步", () => {
+  beforeEach(() => cleanup());
+  afterAll(() => cleanup());
+
+  test("对照：目标 1 分钟前还活跃 ⇒ 订阅者收到 new_task", async () => {
+    const { taskStatus, received } = await send(1);
+    expect(taskStatus).toBe("delivered");
+    expect(received).toContain("new_task");
+  });
+
+  test("🔴 核心：目标安静 10 分钟但订阅者连着 ⇒ 仍然收得到（修复前这里收到 null）", async () => {
+    const { taskStatus, received } = await send(10);
+    expect(received).toContain("new_task");
+    expect(taskStatus).toBe("delivered");   // 现在这个 delivered 是真话了
+  });
+
+  test("🔴 可达性判据必须来自订阅者注册表，不是 last_seen_at 的时间戳猜测", async () => {
+    // 安静 10 分钟 = 时间戳判据会说 offline；而实际上有人在听。
+    const quiet = await send(10);
+    expect(quiet.received).toContain("new_task");
+    // 真没人听的时候，pushEvent 本来就是 no-op，不需要额外的闸来保护。
+    const nobody = await send(10, false);
+    expect(nobody.received).toBeNull();
+  });
+
+  test("真的没有订阅者时，tasks 行仍写 delivered —— 本 PR 刻意不改，记录在案", async () => {
+    const { taskStatus, received } = await send(10, false);
+    expect(received).toBeNull();
+    // 这一条钉的是**当前行为**，不是我认为对的行为：没人收到，行仍自称 delivered。
+    expect(taskStatus).toBe("delivered");
+  });
+
+  test("活性判据的输入 last_seen_at 只由 report_status 刷新 —— 发送方不刷新它", async () => {
+    cleanup(); seed(4);
+    const before = db.get<{ last_seen_at: string }>("SELECT last_seen_at FROM sessions WHERE alias = ?1 AND network_id = ?2", TARGET, NET);
+    await toolsFor(SENDER).send_task({ alias: TARGET, task: `ping-${++sendSeq}`, priority: "normal" });
+    const after = db.get<{ last_seen_at: string }>("SELECT last_seen_at FROM sessions WHERE alias = ?1 AND network_id = ?2", TARGET, NET);
+    expect(after?.last_seen_at).toBe(before!.last_seen_at);
+  });
+});

package/src/desktop-message-seam.test.ts

@@ -0,0 +1,150 @@
+// #1459 —— P2 写路径与 P3 读路径的**接缝**。
+//
+// 通信龙 在 origin/main 上核出的覆盖缝：desktop-message.test.ts 测真实 send 但
+// 不碰 scope=user 读；user-inbox-read-http.test.ts 测 scope=user 读但用 SQL 直接
+// 播种行。两半各自对着自己的夹具绿，而"真实 send 写进的行、真实 scope=user
+// 读得回来"从没验过。本文件就走这一条：真 send → 真 HTTP 读。
+//
+// 附带钉住 network_id 不为 NULL 的**真实机制**：不是 INSERT 时兜底，而是
+// tools.ts 里 `if (!effectiveNetId) return writeDeniedReply(...)` 在写之前就拒。
+// 见下面 "解析不出 network 时拒发" 那条 —— 把那个 if 拿掉，本文件会红。
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+const PRIVATE_DB_DIR = mkdtempSync(join(tmpdir(), "anet-dm-seam-"));
+process.env.COMMHUB_DB ||= join(PRIVATE_DB_DIR, "hub.db");
+
+let server: ReturnType<typeof Bun.serve>;
+let base = "";
+let targetToken = "";
+let senderId = "", targetId = "", senderNet = "", secondNet = "";
+let send: (args: any) => Promise<Record<string, any>>;
+
+function buildSend(opts: { netId: string | null; userId: string | null; alias: string | null }) {
+  const mcp = new McpServer({ name: "test", version: "0" }) as any;
+  const tools: Record<string, any> = {};
+  const origTool = mcp.tool.bind(mcp);
+  mcp.tool = (name: string, _d: string, _s: any, handler: any) => { tools[name] = handler; return origTool(name, _d, _s, handler); };
+  const { registerTools } = require("./tools.js");
+  registerTools(mcp, undefined, opts.netId, opts.userId, opts.alias, false, "tok_seam_test");
+  return async (args: any) => JSON.parse((await tools["send_desktop_message"](args)).content[0].text);
+}
+
+beforeAll(async () => {
+  const { db } = await import("./db.js");
+  const { register, addNetworkMember } = await import("./auth.js");
+  const stamp = Date.now();
+
+  // 首个注册用户自动成为全局 admin，而 admin 读侧不走 scope 过滤分支。
+  // 收件人必须是普通 user，否则"读得回来"可能只是因为它绕过了过滤。
+  expect(register(`seam_admin_${stamp}`, "SeamAdmin-Strong-1!").ok).toBe(true);
+  const s = register(`seam_sender_${stamp}`, "SeamSender-Strong-1!");
+  const t = register(`seam_target_${stamp}`, "SeamTarget-Strong-1!");
+  expect(s.ok && t.ok).toBe(true);
+  targetToken = t.token!;
+  senderNet = s.network_id!;
+  secondNet = t.network_id!;
+  senderId = db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", `seam_sender_${stamp}`)!.user_id;
+  targetId = db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", `seam_target_${stamp}`)!.user_id;
+  expect(db.get<{ role: string }>("SELECT role FROM users WHERE user_id = ?1", targetId)?.role).toBe("user");
+
+  // 收件人进发件人的网（真实形态：同网两成员）。
+  expect(addNetworkMember(senderNet, targetId, "member").ok).toBe(true);
+
+  send = buildSend({ netId: senderNet, userId: senderId, alias: "seam-sender" });
+
+  const mod = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+});
+
+afterAll(() => {
+  try { server?.stop(true); } catch {}
+  try { rmSync(PRIVATE_DB_DIR, { recursive: true, force: true }); } catch {}
+});
+
+const readOwn = async (token: string, qs = "") => {
+  const r = await fetch(`${base}/api/messages?scope=user${qs}`, { headers: { Authorization: `Bearer ${token}` } });
+  return { status: r.status, body: await r.json() as any };
+};
+
+describe("#1459 P2 写 → P3 读 接缝", () => {
+  test("🔴 真实 send_desktop_message 写进的行，真实 GET ?scope=user 读得回来", async () => {
+    const sent = await send({ to_user_id: targetId, message: "接缝测试正文", title: "接缝", severity: "warning", kind: "agent_message" });
+    expect([sent.ok, sent.persisted]).toEqual([true, true]);
+
+    const { status, body } = await readOwn(targetToken);
+    expect(status).toBe(200);
+    const row = body.messages.find((m: any) => m.message_id === sent.message_id);
+    expect(row).toBeTruthy();                      // 承重：两半接得上
+    expect(row.content).toBe("接缝测试正文");
+    expect(row.title).toBe("接缝");
+    expect(row.severity).toBe("warning");
+    expect(row.user_id).toBe(targetId);
+  });
+
+  test("🔴 落库的 network_id 就是授权用的那个网，不是 NULL —— 否则 scoped 读回不来", async () => {
+    const { db } = require("./db.js");
+    const sent = await send({ to_user_id: targetId, message: "网络归属" });
+    const row = db.get<any>("SELECT network_id FROM user_inbox WHERE message_id = ?1", sent.message_id);
+    expect(row.network_id).toBe(senderNet);
+
+    const { body } = await readOwn(targetToken);
+    expect(body.messages.map((m: any) => m.message_id)).toContain(sent.message_id);
+  });
+
+  test("unread 随真实 send 增长", async () => {
+    const before = (await readOwn(targetToken)).body.unread;
+    await send({ to_user_id: targetId, message: "计数 +1" });
+    expect((await readOwn(targetToken)).body.unread).toBe(before + 1);
+  });
+
+  test("redact-at-read 作用在真实写进去的正文上", async () => {
+    const sent = await send({ to_user_id: targetId, message: "凭据 ntok_seamtoken123456 在正文里" });
+    const { db } = require("./db.js");
+    // 存储侧保留原文，遮蔽发生在**回读**时 —— 这两句一起才说明是 read-time 脱敏。
+    expect(db.get<any>("SELECT content FROM user_inbox WHERE message_id = ?1", sent.message_id).content)
+      .toContain("ntok_seamtoken123456");
+    const row = (await readOwn(targetToken)).body.messages.find((m: any) => m.message_id === sent.message_id);
+    expect(row.content).toContain("ntok_***redacted***");
+    expect(row.content).not.toContain("ntok_seamtoken123456");
+  });
+
+  // 🔴 这一条是 `if (!effectiveNetId) return` 这道守卫**唯一**能被触发的场景。
+  //    有 auth ctx 时前一道 `canWrite` 就拦了；而 canRestWriteNetwork 对
+  //    legacy 全局 token / --dev-open（authCtx 为 null）是 `return true`
+  //    （network-scope.ts:96）—— 那条路上只剩这道守卫挡着 NULL 孤儿行。
+  //    把 tools.ts:2320 那行删掉，本条会红（写出一行 network_id=NULL）。
+  test("🔴 legacy 无 auth ctx 的调用者同样拒发，不写 NULL 孤儿行", async () => {
+    const { db } = require("./db.js");
+    const legacy = buildSend({ netId: null, userId: null as any, alias: null as any });
+    const before = db.get<{ n: number }>("SELECT COUNT(*) AS n FROM user_inbox")!.n;
+    const r = await legacy({ to_user_id: targetId, message: "legacy 无网络上下文" });
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe("network_id_required");
+    expect(db.get<{ n: number }>("SELECT COUNT(*) AS n FROM user_inbox")!.n).toBe(before);
+    expect(db.get<{ n: number }>("SELECT COUNT(*) AS n FROM user_inbox WHERE network_id IS NULL")!.n).toBe(0);
+  });
+
+  test("🔴 解析不出 network 时**拒发**，而不是写一行 network_id=NULL 的孤儿", async () => {
+    const { db } = require("./db.js");
+    const { addNetworkMember } = require("./auth.js");
+    // 发件人进第二个网 ⇒ 不带 network_id 时 singleNetworkId 解析不出唯一网。
+    addNetworkMember(secondNet, senderId, "member");
+    const ambiguous = buildSend({ netId: null, userId: senderId, alias: "seam-sender" });
+
+    const before = db.get<{ n: number }>("SELECT COUNT(*) AS n FROM user_inbox")!.n;
+    const r = await ambiguous({ to_user_id: targetId, message: "无法解析网络" });
+
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe("network_id_required");
+    // 承重：拒发意味着**一行都不写**。若把 tools.ts 的
+    // `if (!effectiveNetId) return writeDeniedReply(...)` 拿掉，这里会多出一行
+    // network_id=NULL 的孤儿 —— 写得进去、scoped 读不回来。
+    expect(db.get<{ n: number }>("SELECT COUNT(*) AS n FROM user_inbox")!.n).toBe(before);
+    expect(db.get<{ n: number }>("SELECT COUNT(*) AS n FROM user_inbox WHERE network_id IS NULL")!.n).toBe(0);
+  });
+});

package/src/desktop-message.test.ts

@@ -0,0 +1,368 @@
+// Desktop user push contract.
+//
+// Pins the new user-keyed SSE path and send_desktop_message MCP tool:
+// - user streams are keyed by networkId:userId, never alias
+// - ntok callers cannot cross network by supplying a foreign to_user_id/network_id
+// - target ambiguity/miss is fail-closed before audit/push
+
+import { afterAll, afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { db } from "./db.js";
+import { registerTools } from "./tools.js";
+import {
+  __resetSSEClientsForTest,
+  createUserEventStream,
+  pushUserEvent,
+} from "./push.js";
+
+const NET_A = "net_desktop_a";
+const NET_B = "net_desktop_b";
+const NODE_USER = "u_desktop_node_owner";
+const SENDER_USER = "u_desktop_sender";
+const TARGET_A = "u_desktop_target_a";
+const TARGET_B = "u_desktop_target_b";
+const TARGET_BOTH = "u_desktop_target_both";
+const ALL_USERS = [NODE_USER, SENDER_USER, TARGET_A, TARGET_B, TARGET_BOTH];
+
+type ToolHandler = (args: any) => Promise<{ content: Array<{ type: "text"; text: string }> }>;
+
+function cleanup() {
+  try { db.run("DELETE FROM audit_log WHERE action = 'send_desktop_message' OR network_id IN (?1, ?2)", [NET_A, NET_B]); } catch {}
+  try { db.run("DELETE FROM network_members WHERE network_id IN (?1, ?2)", [NET_A, NET_B]); } catch {}
+  try { db.run("DELETE FROM networks WHERE network_id IN (?1, ?2)", [NET_A, NET_B]); } catch {}
+  for (const u of ALL_USERS) {
+    try { db.run("DELETE FROM users WHERE user_id = ?1", [u]); } catch {}
+  }
+}
+
+function seed() {
+  for (const u of ALL_USERS) {
+    db.run(
+      `INSERT INTO users (user_id, username, password_hash, role, created_at)
+       VALUES (?1, ?2, 'x', 'user', datetime('now'))`,
+      [u, `${u}_name`],
+    );
+  }
+  db.run(`INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?1, ?2, datetime('now'))`, [NET_A, SENDER_USER]);
+  db.run(`INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?1, ?2, datetime('now'))`, [NET_B, TARGET_B]);
+  const member = (userId: string, networkId: string, role: string) =>
+    db.run(`INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, ?3, datetime('now'))`, [userId, networkId, role]);
+  member(NODE_USER, NET_A, "member");
+  member(SENDER_USER, NET_A, "owner");
+  member(TARGET_A, NET_A, "member");
+  member(TARGET_B, NET_B, "member");
+  member(TARGET_BOTH, NET_A, "member");
+  member(TARGET_BOTH, NET_B, "member");
+}
+
+beforeEach(() => { cleanup(); seed(); });
+afterEach(() => { __resetSSEClientsForTest(); });
+afterAll(cleanup);
+
+function buildHandlers(opts: { netId?: string | null; userId?: string | null; alias?: string | null; isNetwork?: boolean }) {
+  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,
+    opts.netId ?? null,
+    opts.userId ?? null,
+    opts.alias ?? opts.userId ?? null,
+    opts.isNetwork ?? false,
+    "tok_desktop_test",
+  );
+  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);
+}
+
+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`);
+}
+
+function auditCount() {
+  return db.get<{ n: number }>("SELECT COUNT(*) AS n FROM audit_log WHERE action = 'send_desktop_message'")?.n ?? 0;
+}
+
+describe("send_desktop_message", () => {
+  test("ntok caller can push to a user in the same bound network", async () => {
+    const stream = createUserEventStream(NET_A, TARGET_A);
+    const reader = stream.body!.getReader();
+    await readFrame(reader);
+
+    const tools = buildHandlers({ netId: NET_A, userId: NODE_USER, alias: "node-a", isNetwork: true });
+    const result = await call(tools.send_desktop_message, {
+      to_user_id: TARGET_A,
+      message: "desktop hello",
+      severity: "success",
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.message_id).toStartWith("dm_");
+    expect(auditCount()).toBe(1);
+    const evt = await readFrame(reader);
+    expect(evt.type).toBe("desktop_message");
+    expect(evt.message_id).toBe(result.message_id);
+    expect(evt.message).toBe("desktop hello");
+    expect(evt.from).toBe("node-a");
+    expect(evt.network_id).toBe(NET_A);
+    expect(evt.user_id).toBe(TARGET_A);
+    expect(evt.scope).toBe("user");
+    await reader.cancel();
+  });
+
+  test("utok caller can push with explicit network_id to a member user", async () => {
+    const stream = createUserEventStream(NET_A, TARGET_A);
+    const reader = stream.body!.getReader();
+    await readFrame(reader);
+
+    const tools = buildHandlers({ userId: SENDER_USER, alias: "sender-user" });
+    const result = await call(tools.send_desktop_message, {
+      to_username: `${TARGET_A}_name`,
+      network_id: NET_A,
+      title: "Heads up",
+      message: "from user token",
+    });
+
+    expect(result.ok).toBe(true);
+    const evt = await readFrame(reader);
+    expect(evt.title).toBe("Heads up");
+    expect(evt.message).toBe("from user token");
+    expect(evt.network_id).toBe(NET_A);
+    await reader.cancel();
+  });
+
+  test("ntok caller cannot cross network with foreign network_id and to_user_id; no audit or push happens first", async () => {
+    const stream = createUserEventStream(NET_B, TARGET_B);
+    const reader = stream.body!.getReader();
+    await readFrame(reader);
+
+    const tools = buildHandlers({ netId: NET_A, userId: NODE_USER, alias: "node-a", isNetwork: true });
+    const result = await call(tools.send_desktop_message, {
+      to_user_id: TARGET_B,
+      network_id: NET_B,
+      message: "must not cross",
+    });
+
+    expect(result).toEqual({ ok: false, error: "desktop_target_not_in_network", network_id: NET_A });
+    expect(auditCount()).toBe(0);
+
+    pushUserEvent(NET_B, TARGET_B, { type: "desktop_message", message_id: "marker_after_denied" });
+    expect((await readFrame(reader)).message_id).toBe("marker_after_denied");
+    await reader.cancel();
+  });
+
+  test("missing target is fail-closed before audit", async () => {
+    const tools = buildHandlers({ netId: NET_A, userId: NODE_USER, alias: "node-a", isNetwork: true });
+    const result = await call(tools.send_desktop_message, { message: "nobody" });
+    expect(result).toEqual({
+      ok: false,
+      error: "desktop_target_required",
+      message: "to_user_id or to_username is required",
+    });
+    expect(auditCount()).toBe(0);
+  });
+
+  test("conflicting to_user_id and to_username is fail-closed before audit", async () => {
+    const tools = buildHandlers({ netId: NET_A, userId: NODE_USER, alias: "node-a", isNetwork: true });
+    const result = await call(tools.send_desktop_message, {
+      to_user_id: TARGET_A,
+      to_username: `${TARGET_BOTH}_name`,
+      message: "conflict",
+    });
+    expect(result).toEqual({
+      ok: false,
+      error: "desktop_target_mismatch",
+      to_user_id: TARGET_A,
+      to_username: `${TARGET_BOTH}_name`,
+    });
+    expect(auditCount()).toBe(0);
+  });
+
+  test("unknown target is fail-closed before audit", async () => {
+    const tools = buildHandlers({ netId: NET_A, userId: NODE_USER, alias: "node-a", isNetwork: true });
+    const result = await call(tools.send_desktop_message, {
+      to_username: "not_a_real_user",
+      message: "lost",
+    });
+    expect(result).toEqual({ ok: false, error: "desktop_target_not_found", field: "to_username" });
+    expect(auditCount()).toBe(0);
+  });
+});
+
+// #1459 —— 返回值必须反映真实投递态。
+//
+// send_desktop_message 是 fire-and-forget：只 INSERT audit_log（不写 inbox），
+// 再 pushUserEvent 扇出；而 pushUserEvent 在没有订阅者时静默 return。
+// 用户 dashboard 离线/重连时消息永久丢（无 DB 行 ⇒ 无从 reconcile，
+// /api/messages 只 SELECT ... FROM inbox），而调用方拿到的是 ok:true。
+//
+// 本 PR 只做「让丢失可见」这一半：不碰 schema，返回值说实话。
+// 持久化 + 重连补投（让丢失不发生）是另一条，方向已定为按 user_id 寻址的新表。
+describe("#1459 send_desktop_message 返回值反映真实投递态", () => {
+  test("🔴 无活跃订阅者 ⇒ delivered:false + 可判读的 reason，而不是笼统 ok:true", async () => {
+    // 故意不建 SSE 流：这正是用户 dashboard 关着的情形
+    const tools = buildHandlers({ netId: NET_A, userId: NODE_USER, alias: "node-a", isNetwork: true });
+    const before = auditCount();
+    const result = await call(tools.send_desktop_message, {
+      to_user_id: TARGET_A,
+      message: "nobody is listening",
+      severity: "info",
+    });
+
+    // ok 仍为 true：调用被接受、审计已落库 —— 这一格没变
+    expect(result.ok).toBe(true);
+    expect(result.message_id).toStartWith("dm_");
+    expect(auditCount()).toBe(before + 1);
+
+    // 新增的那一格：投递态
+    expect(result.delivered).toBe(false);
+    expect(result.reason).toBe("no_live_subscriber");
+  });
+
+  test("有活跃订阅者 ⇒ delivered:true 且不带 reason", async () => {
+    const stream = createUserEventStream(NET_A, TARGET_A);
+    const reader = stream.body!.getReader();
+    await readFrame(reader);
+
+    const tools = buildHandlers({ netId: NET_A, userId: NODE_USER, alias: "node-a", isNetwork: true });
+    const result = await call(tools.send_desktop_message, {
+      to_user_id: TARGET_A,
+      message: "someone is listening",
+      severity: "info",
+    });
+
+    expect(result.delivered).toBe(true);
+    expect(result.reason).toBeUndefined();
+    // 前提断言：这一条真的送到了订阅者手上，否则 delivered:true 就是空话
+    const evt = await readFrame(reader);
+    expect(evt.message).toBe("someone is listening");
+    await reader.cancel();
+  });
+
+  test("🔴 两种情形必须给出不同读数 —— 防止判据退化成恒真", async () => {
+    const tools = buildHandlers({ netId: NET_A, userId: NODE_USER, alias: "node-a", isNetwork: true });
+    const offline = await call(tools.send_desktop_message, { to_user_id: TARGET_A, message: "off", severity: "info" });
+
+    const stream = createUserEventStream(NET_A, TARGET_A);
+    const reader = stream.body!.getReader();
+    await readFrame(reader);
+    const online = await call(tools.send_desktop_message, { to_user_id: TARGET_A, message: "on", severity: "info" });
+    await reader.cancel();
+
+    expect(offline.delivered).not.toBe(online.delivered);
+  });
+});
+
+// #1459 ① P2 —— 写入持久化。
+describe("#1459 ① P2 send_desktop_message 持久化", () => {
+  const rowsFor = (mid: string) =>
+    db.get<{ n: number }>("SELECT COUNT(*) AS n FROM user_inbox WHERE message_id = ?1", mid)?.n ?? 0;
+
+  test("🔴 发一条消息 ⇒ user_inbox 落一行，字段与事件一致", async () => {
+    const tools = buildHandlers({ netId: NET_A, userId: NODE_USER, alias: "node-a", isNetwork: true });
+    const r = await call(tools.send_desktop_message, {
+      to_user_id: TARGET_A, message: "persist me", severity: "warning", title: "T", kind: "agent_message",
+    });
+    expect(r.ok).toBe(true);
+    expect(r.persisted).toBe(true);
+    const row = db.get<any>("SELECT * FROM user_inbox WHERE message_id = ?1", r.message_id);
+    expect(row).toBeTruthy();
+    expect(row.user_id).toBe(TARGET_A);
+    expect(row.content).toBe("persist me");
+    expect(row.severity).toBe("warning");
+    expect(row.title).toBe("T");
+    expect(row.from_session).toBe("node-a");
+    expect(row.network_id).toBe(NET_A);
+    expect(row.acked).toBe(0);
+  });
+
+  test("🔴 没有活订阅者时也要落库 —— 「丢了」变成「待补投」的那一格", async () => {
+    const tools = buildHandlers({ netId: NET_A, userId: NODE_USER, alias: "node-a", isNetwork: true });
+    const r = await call(tools.send_desktop_message, { to_user_id: TARGET_A, message: "offline body" });
+    expect(r.delivered).toBe(false);
+    expect(r.reason).toBe("no_live_subscriber");
+    expect(r.persisted).toBe(true);
+    expect(rowsFor(r.message_id)).toBe(1);
+  });
+
+  test("🔴 zod 默认值不可依赖：直接调 handler 不传 kind/severity 也必须落库", async () => {
+    // 测试与未来的内部调用方绕过 MCP 的 zod .default()，拿到的是 undefined。
+    // 列上虽有 DEFAULT，但显式传 NULL 会覆盖它 —— 所以写入侧要自己兜。
+    const tools = buildHandlers({ netId: NET_A, userId: NODE_USER, alias: "node-a", isNetwork: true });
+    const r = await call(tools.send_desktop_message, { to_user_id: TARGET_A, message: "no kind given" });
+    expect(rowsFor(r.message_id)).toBe(1);
+    const row = db.get<any>("SELECT kind, severity FROM user_inbox WHERE message_id = ?1", r.message_id);
+    expect(row.kind).toBe("agent_message");
+    expect(row.severity).toBe("info");
+  });
+
+  test("audit_log 与 user_inbox 同生共死（同一事务，条数一致）", async () => {
+    const before = auditCount();
+    const tools = buildHandlers({ netId: NET_A, userId: NODE_USER, alias: "node-a", isNetwork: true });
+    const r = await call(tools.send_desktop_message, { to_user_id: TARGET_A, message: "paired" });
+    expect(auditCount()).toBe(before + 1);
+    expect(rowsFor(r.message_id)).toBe(1);
+  });
+});
+
+// #1459 ① P2 —— 幂等写法的选择本身要被钉住。
+//
+// 🔴 实现时踩到的：最初用 `INSERT OR IGNORE`，它对「重投同一 message_id」是对的，
+//    但**连 NOT NULL 违规也一起吞掉** —— kind 为 undefined 时整行被静默丢弃，
+//    而工具照样返回 persisted:true。**一条消息凭空消失且报告成功**，正是本
+//    issue 要消灭的那个形状。改成 ON CONFLICT(message_id) DO NOTHING：
+//    只赦免主键冲突，别的约束照常抛。
+describe("#1459 ① P2 幂等写法：赦免重复，但不吞约束错误", () => {
+  const stmt = `INSERT INTO user_inbox
+      (message_id, network_id, user_id, from_session, kind, title, content, severity, meta_json)
+    VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)
+    ON CONFLICT(message_id) DO NOTHING`;
+
+  test("重复的 message_id ⇒ 不抛错、也不产生第二行", () => {
+    const mid = `dm_dup_${Date.now()}`;
+    const ins = () => db.run(stmt, [mid, NET_A, TARGET_A, "node-a", "info", null, "body", "info", null]);
+    ins();
+    expect(() => ins()).not.toThrow();
+    expect(db.get<{ n: number }>("SELECT COUNT(*) AS n FROM user_inbox WHERE message_id = ?1", mid)?.n).toBe(1);
+  });
+
+  test("🔴 NOT NULL 违规必须抛出来 —— 不能像 OR IGNORE 那样静默丢行", () => {
+    const mid = `dm_bad_${Date.now()}`;
+    expect(() =>
+      db.run(stmt, [mid, NET_A, TARGET_A, "node-a", null, null, "body", "info", null]),
+    ).toThrow();
+    expect(db.get<{ n: number }>("SELECT COUNT(*) AS n FROM user_inbox WHERE message_id = ?1", mid)?.n).toBe(0);
+  });
+});