@sleep2agi/commhub-server 0.9.0-preview.4 → 0.9.0-preview.41

package/src/observer-avatar-http.test.ts

@@ -0,0 +1,424 @@
+// #461 + #462 — HTTP integration tests against the real Bun.serve hub.
+//
+// Boots a PRIVATE server instance via the #434 seam (`bootServer({ port: 0 })`,
+// same signature as PR #438) and derives BASE from the actual bound port.
+// This keeps the suite alive in aggregate runs: `await import("./server.js")`
+// is a module-cache no-op when another file booted first, so relying on the
+// import side effect + own PORT env leaves every fetch ConnectionRefused
+// while the tests still "run" (通信龙 #461 review, finding 2). Gate:
+//   bun test src/uploads-http.test.ts src/observer-avatar-http.test.ts → 0 fail
+//
+// #461: GET /events/network/:id observer stream — membership auth incl.
+//       member-removal revocation, summary events for third-party traffic
+//       (REST dispatch + MCP send_reply), no content leakage.
+// #462: PUT /api/nodes/:ref/avatar + GET /api/nodes round trip — persistence,
+//       href normalization, XSS-shaped rejects, clear semantics, write gate.
+
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { register, login, addNetworkMember, removeNetworkMember, createNetworkTokenForNode } from "./auth.js";
+import { registerTools } from "./tools.js";
+import { db } from "./db.js";
+
+const SERVER_DB = mkdtempSync(join(tmpdir(), "anet-obs-avatar-db-")) + "/commhub.db";
+
+let BASE = "";
+let privateServer: any = null;
+
+let memberToken = "";
+let memberNetworkId = "";
+let memberUserId = "";
+let outsiderToken = "";
+let outsiderUserId = "";
+const TARGET_ALIAS = "obs-target-agent";
+const AVATAR_NODE_ID = "node_avatar_test_1";
+
+beforeAll(async () => {
+  // Kept for per-file runs launched without an external COMMHUB_DB (the
+  // documented contract still is to set it externally; see db-adapter.ts).
+  process.env.COMMHUB_DB = process.env.COMMHUB_DB || SERVER_DB;
+  process.env.HOST = "127.0.0.1";
+  // (#438 corrective: importing server.js is side-effect-free — no
+  // default instance, no PORT juggling; only the private bootServer
+  // instance below listens.)
+
+  const suffix = `${Date.now()}_${Math.floor(Math.random() * 1000)}`;
+  const pw = "BootstrapPw123Aa!";
+
+  const memberName = `obs_member_${suffix}`;
+  let r = register(memberName, pw, undefined, "seed");
+  if (!r.ok || !r.token) {
+    const lr = login(memberName, pw);
+    if (lr.token) { memberToken = lr.token; memberNetworkId = lr.network_id ?? ""; }
+  } else {
+    memberToken = r.token;
+    memberNetworkId = r.network_id ?? "";
+  }
+  expect(memberToken).toBeTruthy();
+  expect(memberNetworkId).toBeTruthy();
+  memberUserId = db.get<any>("SELECT user_id FROM users WHERE username = ?1", memberName)?.user_id ?? "";
+  expect(memberUserId).toBeTruthy();
+
+  const outsiderName = `obs_outsider_${suffix}`;
+  const r2 = register(outsiderName, pw, undefined, "seed");
+  if (r2.ok && r2.token) outsiderToken = r2.token;
+  expect(outsiderToken).toBeTruthy();
+  outsiderUserId = db.get<any>("SELECT user_id FROM users WHERE username = ?1", outsiderName)?.user_id ?? "";
+  expect(outsiderUserId).toBeTruthy();
+
+  // Target agent session in the member's network, freshly seen → online.
+  db.run(
+    `INSERT INTO sessions (resume_id, alias, status, network_id, updated_at, last_seen_at)
+     VALUES (?1, ?2, 'idle', ?3, datetime('now'), datetime('now'))`,
+    [`resume_${suffix}`, TARGET_ALIAS, memberNetworkId]
+  );
+
+  // Node row for the avatar round trip.
+  db.run(
+    `INSERT OR REPLACE INTO nodes (node_id, node_name, alias, network_id, created_at, updated_at)
+     VALUES (?1, 'avatar-test-node', ?2, ?3, datetime('now'), datetime('now'))`,
+    [AVATAR_NODE_ID, TARGET_ALIAS, memberNetworkId]
+  );
+
+  // Private instance on an OS-assigned port — collision-free by
+  // construction (kernel-assigned).
+  const mod: any = await import("./server.js");
+  privateServer = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${privateServer.port}`;
+});
+
+afterAll(() => {
+  try { privateServer?.stop?.(true); } catch {}
+  try { rmSync(SERVER_DB, { recursive: true, force: true }); } catch {}
+});
+
+function auth(token: string): Record<string, string> {
+  return { "Authorization": `Bearer ${token}` };
+}
+
+/** Read the next SSE data frame from a fetch Response, with timeout. */
+async function readFrame(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  timeoutMs = 3_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`);
+}
+
+describe("#461 GET /events/network/:id — auth", () => {
+  test("anonymous → 401", async () => {
+    const res = await fetch(`${BASE}/events/network/${memberNetworkId}`);
+    expect(res.status).toBe(401);
+  });
+
+  test("non-member user token → 403", async () => {
+    const res = await fetch(`${BASE}/events/network/${memberNetworkId}`, { headers: auth(outsiderToken) });
+    expect(res.status).toBe(403);
+    const body = await res.json() as any;
+    expect(body.ok).toBe(false);
+  });
+
+  test("member user token → SSE stream with observer connected frame", async () => {
+    const res = await fetch(`${BASE}/events/network/${memberNetworkId}`, { headers: auth(memberToken) });
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type") || "").toContain("text/event-stream");
+    const reader = res.body!.getReader();
+    const connected = await readFrame(reader);
+    expect(connected.type).toBe("connected");
+    expect(connected.observer).toBe(true);
+    expect(connected.network_id).toBe(memberNetworkId);
+    await reader.cancel();
+  });
+
+  test("membership removal revokes observer access — ntok exploit repro (通信龙 review finding 1)", async () => {
+    // Exact repro of the review's exploit: add user C to network A, mint
+    // an ntok BOUND to A, remove C from A — the same live ntok must lose
+    // the stream. network_members IS the revocation mechanism because
+    // removeNetworkMember does not revoke the user's tokens; the old
+    // `!role && authCtx.networkId !== observedNetId` OR-form let the
+    // token's network binding bypass the membership check (utok would
+    // not catch this: its authCtx.networkId is null, so only ntok
+    // exercises the vulnerable branch — verified by stubbing the OR
+    // back in: THIS test goes red, the utok variants stay green).
+    const added = addNetworkMember(memberNetworkId, outsiderUserId, "member");
+    expect(added.ok).toBe(true);
+    const minted = createNetworkTokenForNode(outsiderUserId, memberNetworkId, "revocation-probe");
+    expect(minted.ok).toBe(true);
+    const ntok = minted.token!;
+    expect(ntok.startsWith("ntok_")).toBe(true);
+
+    const whileMember = await fetch(`${BASE}/events/network/${memberNetworkId}`, { headers: auth(ntok) });
+    expect(whileMember.status).toBe(200);
+    const reader = whileMember.body!.getReader();
+    expect((await readFrame(reader)).type).toBe("connected");
+    await reader.cancel();
+
+    const removed = removeNetworkMember(memberNetworkId, outsiderUserId);
+    expect(removed.ok).toBe(true);
+    // The review's failing probe: /events/network/A with the still-live
+    // network-bound token → must now be 403, not 200.
+    const afterRemoval = await fetch(`${BASE}/events/network/${memberNetworkId}`, { headers: auth(ntok) });
+    expect(afterRemoval.status).toBe(403);
+    // utok of the removed user is denied too.
+    const utokAfter = await fetch(`${BASE}/events/network/${memberNetworkId}`, { headers: auth(outsiderToken) });
+    expect(utokAfter.status).toBe(403);
+  });
+});
+
+describe("GET /events/users/me — Desktop user stream auth", () => {
+  test("anonymous → 401", async () => {
+    const res = await fetch(`${BASE}/events/users/me?network_id=${encodeURIComponent(memberNetworkId)}`);
+    expect(res.status).toBe(401);
+  });
+
+  test("ntok is refused for user stream", async () => {
+    const minted = createNetworkTokenForNode(memberUserId, memberNetworkId, "desktop-ntok-probe");
+    expect(minted.ok).toBe(true);
+    const res = await fetch(`${BASE}/events/users/me?network_id=${encodeURIComponent(memberNetworkId)}`, { headers: auth(minted.token!) });
+    expect(res.status).toBe(403);
+    const body = await res.json() as any;
+    expect(body.error).toBe("user_token_required");
+  });
+
+  test("utok without network_id → 400", async () => {
+    const res = await fetch(`${BASE}/events/users/me`, { headers: auth(memberToken) });
+    expect(res.status).toBe(400);
+    const body = await res.json() as any;
+    expect(body.error).toBe("network_id required");
+  });
+
+  test("non-member utok → 403", async () => {
+    const res = await fetch(`${BASE}/events/users/me?network_id=${encodeURIComponent(memberNetworkId)}`, { headers: auth(outsiderToken) });
+    expect(res.status).toBe(403);
+    const body = await res.json() as any;
+    expect(body.error).toBe("not a member of this network");
+  });
+
+  test("member utok → user stream connected frame keyed to authenticated user", async () => {
+    const res = await fetch(`${BASE}/events/users/me?network_id=${encodeURIComponent(memberNetworkId)}`, { headers: auth(memberToken) });
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type") || "").toContain("text/event-stream");
+    const reader = res.body!.getReader();
+    const connected = await readFrame(reader);
+    expect(connected.type).toBe("connected");
+    expect(connected.user).toBe(true);
+    expect(connected.network_id).toBe(memberNetworkId);
+    expect(connected.user_id).toBe(memberUserId);
+    await reader.cancel();
+  });
+});
+
+describe("GET /api/messages — client inbox count", () => {
+  test("alias filter returns only that inbox and pending_count for unacked rows", async () => {
+    const selfAlias = `user-${memberUserId}`;
+    db.run(
+      `INSERT INTO inbox (id, session_name, type, priority, content, from_session, acked, network_id, created_at)
+       VALUES (?1, ?2, 'task', 'normal', 'unread self', 'agent-a', 0, ?3, datetime('now'))`,
+      [`msg_self_unread_${Date.now()}`, selfAlias, memberNetworkId],
+    );
+    db.run(
+      `INSERT INTO inbox (id, session_name, type, priority, content, from_session, acked, network_id, created_at)
+       VALUES (?1, ?2, 'task', 'normal', 'read self', 'agent-a', 1, ?3, datetime('now'))`,
+      [`msg_self_read_${Date.now()}`, selfAlias, memberNetworkId],
+    );
+    db.run(
+      `INSERT INTO inbox (id, session_name, type, priority, content, from_session, acked, network_id, created_at)
+       VALUES (?1, 'other-alias', 'task', 'normal', 'other inbox', 'agent-b', 0, ?2, datetime('now'))`,
+      [`msg_other_${Date.now()}`, memberNetworkId],
+    );
+
+    const res = await fetch(`${BASE}/api/messages?alias=${encodeURIComponent(selfAlias)}&network_id=${encodeURIComponent(memberNetworkId)}&limit=20`, {
+      headers: auth(memberToken),
+    });
+    expect(res.status).toBe(200);
+    const body = await res.json() as any;
+    expect(body.ok).toBe(true);
+    expect(body.pending_count).toBe(1);
+    expect(body.messages.length).toBeGreaterThanOrEqual(2);
+    expect(body.messages.every((m: any) => m.to_alias === selfAlias)).toBe(true);
+    expect(body.messages.some((m: any) => m.content === "other inbox")).toBe(false);
+  });
+});
+
+describe("#461 observer receives third-party traffic summaries", () => {
+  test("REST /api/task dispatch → observer gets new_task summary, no content", async () => {
+    const res = await fetch(`${BASE}/events/network/${memberNetworkId}`, { headers: auth(memberToken) });
+    const reader = res.body!.getReader();
+    await readFrame(reader); // connected
+
+    const secret = `SECRET-TASK-CONTENT-${Date.now()}`;
+    const dispatch = await fetch(`${BASE}/api/task`, {
+      method: "POST",
+      headers: { ...auth(memberToken), "Content-Type": "application/json" },
+      body: JSON.stringify({ alias: TARGET_ALIAS, task: secret, priority: "high", from: "third-party-sender", network_id: memberNetworkId }),
+    });
+    expect([200, 202]).toContain(dispatch.status);
+    const dispatched = await dispatch.json() as any;
+    expect(dispatched.task_id).toBeTruthy();
+
+    const evt = await readFrame(reader);
+    expect(evt.type).toBe("new_task");
+    expect(evt.task_id).toBe(dispatched.task_id);
+    expect(evt.from).toBe("third-party-sender");
+    expect(evt.to).toBe(TARGET_ALIAS);
+    // Online session was seeded → delivered; offline would report queued.
+    expect(evt.status).toBe("delivered");
+    expect(evt.priority).toBe("high");
+    expect(evt.network_id).toBe(memberNetworkId);
+    expect(evt.scope).toBe("network");
+    // The acceptance line: summary must NOT leak the task body.
+    expect(JSON.stringify(evt)).not.toContain(secret);
+    await reader.cancel();
+  });
+
+  test("MCP send_reply → observer gets new_reply summary, reply text NOT in frame", async () => {
+    // Drive the REAL registered MCP handler (same interception pattern as
+    // ack-create-request.test.ts) with the member's network enforced, and
+    // read the observer stream over real HTTP.
+    const res = await fetch(`${BASE}/events/network/${memberNetworkId}`, { headers: auth(memberToken) });
+    const reader = res.body!.getReader();
+    await readFrame(reader); // connected
+
+    const tools: Record<string, (args: any) => Promise<any>> = {};
+    const mcp = new McpServer({ name: "test", version: "0" }) as any;
+    mcp.tool = (name: string, _desc: string, _schema: any, handler: any) => { tools[name] = handler; };
+    registerTools(mcp, undefined, memberNetworkId, memberUserId);
+    expect(typeof tools["send_reply"]).toBe("function");
+
+    const secret = `SECRET-REPLY-TEXT-${Date.now()}`;
+    const result = await tools["send_reply"]({
+      alias: TARGET_ALIAS,
+      text: secret,
+      status: "replied",
+      from_session: "reply-worker",
+    });
+    const parsed = JSON.parse(result.content[0].text);
+    expect(parsed.ok).toBe(true);
+
+    const evt = await readFrame(reader);
+    expect(evt.type).toBe("new_reply");
+    expect(evt.from).toBe("reply-worker");
+    expect(evt.to).toBe(TARGET_ALIAS);
+    expect(evt.status).toBe("replied");
+    expect(evt.message_id).toBe(parsed.message_id);
+    expect(evt.network_id).toBe(memberNetworkId);
+    expect(JSON.stringify(evt)).not.toContain(secret);
+    await reader.cancel();
+  });
+});
+
+describe("#462 PUT /api/nodes/:ref/avatar + GET /api/nodes", () => {
+  test("set avatar → 200, GET /api/nodes returns it (cross-device persistence)", async () => {
+    const avatarUrl = "https://cdn.example.com/avatars/custom-1.png";
+    const put = await fetch(`${BASE}/api/nodes/${AVATAR_NODE_ID}/avatar`, {
+      method: "PUT",
+      headers: { ...auth(memberToken), "Content-Type": "application/json" },
+      body: JSON.stringify({ avatar_url: avatarUrl }),
+    });
+    expect(put.status).toBe(200);
+    const putBody = await put.json() as any;
+    expect(putBody.ok).toBe(true);
+    expect(putBody.avatar_url).toBe(avatarUrl);
+
+    const list = await fetch(`${BASE}/api/nodes?node_id=${AVATAR_NODE_ID}`, { headers: auth(memberToken) });
+    expect(list.status).toBe(200);
+    const listBody = await list.json() as any;
+    expect(listBody.ok).toBe(true);
+    const row = listBody.nodes.find((n: any) => n.node_id === AVATAR_NODE_ID);
+    expect(row).toBeTruthy();
+    expect(row.avatar_url).toBe(avatarUrl);
+    // #312 discipline still holds — internals must not leak.
+    expect("config_snapshot" in row).toBe(false);
+  });
+
+  test("markup-hostile chars are stored NORMALIZED (href), not raw (通信龙 review finding 3)", async () => {
+    const put = await fetch(`${BASE}/api/nodes/${AVATAR_NODE_ID}/avatar`, {
+      method: "PUT",
+      headers: { ...auth(memberToken), "Content-Type": "application/json" },
+      body: JSON.stringify({ avatar_url: 'https://cdn.example.com/a"b.png' }),
+    });
+    expect(put.status).toBe(200);
+    const putBody = await put.json() as any;
+    expect(putBody.avatar_url).toBe("https://cdn.example.com/a%22b.png");
+    const row = db.get<any>("SELECT avatar_url FROM nodes WHERE node_id = ?1", AVATAR_NODE_ID);
+    expect(row.avatar_url).toBe("https://cdn.example.com/a%22b.png");
+    expect(row.avatar_url).not.toContain('"');
+  });
+
+  test("clear avatar with null → avatar_url null in list", async () => {
+    const put = await fetch(`${BASE}/api/nodes/${AVATAR_NODE_ID}/avatar`, {
+      method: "PUT",
+      headers: { ...auth(memberToken), "Content-Type": "application/json" },
+      body: JSON.stringify({ avatar_url: null }),
+    });
+    expect(put.status).toBe(200);
+    const list = await fetch(`${BASE}/api/nodes?node_id=${AVATAR_NODE_ID}`, { headers: auth(memberToken) });
+    const listBody = await list.json() as any;
+    const row = listBody.nodes.find((n: any) => n.node_id === AVATAR_NODE_ID);
+    expect(row.avatar_url).toBeNull();
+  });
+
+  test("javascript: URL → 400 invalid_avatar_url, value NOT persisted", async () => {
+    const put = await fetch(`${BASE}/api/nodes/${AVATAR_NODE_ID}/avatar`, {
+      method: "PUT",
+      headers: { ...auth(memberToken), "Content-Type": "application/json" },
+      body: JSON.stringify({ avatar_url: "javascript:alert(1)" }),
+    });
+    expect(put.status).toBe(400);
+    const body = await put.json() as any;
+    expect(body.error).toBe("invalid_avatar_url");
+    const row = db.get<any>("SELECT avatar_url FROM nodes WHERE node_id = ?1", AVATAR_NODE_ID);
+    expect(row.avatar_url ?? null).toBeNull();
+  });
+
+  test("data: URL → 400", async () => {
+    const put = await fetch(`${BASE}/api/nodes/${AVATAR_NODE_ID}/avatar`, {
+      method: "PUT",
+      headers: { ...auth(memberToken), "Content-Type": "application/json" },
+      body: JSON.stringify({ avatar_url: "data:text/html,<script>alert(1)</script>" }),
+    });
+    expect(put.status).toBe(400);
+  });
+
+  test("anonymous → 401; non-member → 404/403 (network-scoped lookup)", async () => {
+    const anon = await fetch(`${BASE}/api/nodes/${AVATAR_NODE_ID}/avatar`, {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ avatar_url: "https://example.com/x.png" }),
+    });
+    expect(anon.status).toBe(401);
+
+    // Outsider's network scope can't even see the node → 404 (or 403 if
+    // visibility rules change later; both deny the write).
+    const outsider = await fetch(`${BASE}/api/nodes/${AVATAR_NODE_ID}/avatar`, {
+      method: "PUT",
+      headers: { ...auth(outsiderToken), "Content-Type": "application/json" },
+      body: JSON.stringify({ avatar_url: "https://example.com/x.png" }),
+    });
+    expect([403, 404]).toContain(outsider.status);
+    const row = db.get<any>("SELECT avatar_url FROM nodes WHERE node_id = ?1", AVATAR_NODE_ID);
+    expect(row.avatar_url ?? null).toBeNull();
+  });
+});

package/src/observer-push.test.ts

@@ -0,0 +1,252 @@
+// #461 — unit tests for the network observer SSE channel (push.ts).
+//
+// These tests read REAL bytes off the observer stream, so they are a
+// live gate: stub pushNetworkObserverEvent out to a no-op and every
+// "receives …" test below times out red. (Per 通信龙 2026-07-28 rule:
+// a test that stays green when the core function is emptied is a fake
+// gate.)
+
+import { afterEach, describe, expect, test } from "bun:test";
+import {
+  __resetSSEClientsForTest,
+  createNetworkObserverStream,
+  createSSEStream,
+  createUserEventStream,
+  pushEvent,
+  pushNetworkObserverEvent,
+  pushUserEvent,
+} from "./push";
+
+afterEach(() => {
+  __resetSSEClientsForTest();
+});
+
+type Frame = Record<string, any>;
+
+/** Read the next SSE data frame (skipping keepalive comments), with a
+ *  hard timeout so a silent stream fails the test instead of hanging. */
+async function readFrame(
+  reader: ReadableStreamDefaultReader<Uint8Array>,
+  timeoutMs = 2_000,
+): Promise<Frame> {
+  const decoder = new TextDecoder();
+  let buf = "";
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const remaining = deadline - Date.now();
+    const result = await Promise.race([
+      reader.read(),
+      new Promise<never>((_, rej) =>
+        setTimeout(() => rej(new Error(`no SSE frame within ${timeoutMs}ms`)), remaining),
+      ),
+    ]);
+    if (result.done) throw new Error("stream ended before a data frame arrived");
+    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; // keepalive comment frame — keep reading
+    return JSON.parse(dataLine.slice(6));
+  }
+  throw new Error(`no SSE frame within ${timeoutMs}ms`);
+}
+
+describe("#461 network observer stream", () => {
+  test("observer receives connected frame, then new_task summary with metadata only", async () => {
+    const res = createNetworkObserverStream("net_obs_a");
+    const reader = res.body!.getReader();
+
+    const connected = await readFrame(reader);
+    expect(connected.type).toBe("connected");
+    expect(connected.observer).toBe(true);
+    expect(connected.network_id).toBe("net_obs_a");
+
+    pushNetworkObserverEvent("net_obs_a", {
+      type: "new_task",
+      task_id: "task-123",
+      from: "sender-agent",
+      to: "receiver-agent",
+      status: "delivered",
+      priority: "high",
+    });
+
+    const evt = await readFrame(reader);
+    expect(evt.type).toBe("new_task");
+    expect(evt.task_id).toBe("task-123");
+    expect(evt.from).toBe("sender-agent");
+    expect(evt.to).toBe("receiver-agent");
+    expect(evt.status).toBe("delivered");
+    expect(evt.priority).toBe("high");
+    expect(evt.network_id).toBe("net_obs_a");
+    expect(evt.scope).toBe("network");
+    // Summary contract: NO content field, ever.
+    expect("content" in evt).toBe(false);
+    expect("task" in evt).toBe(false);
+    await reader.cancel();
+  });
+
+  test("observer receives new_reply summary", async () => {
+    const res = createNetworkObserverStream("net_obs_reply");
+    const reader = res.body!.getReader();
+    await readFrame(reader); // connected
+
+    pushNetworkObserverEvent("net_obs_reply", {
+      type: "new_reply",
+      task_id: "parent-task",
+      message_id: "msg-9",
+      from: "worker",
+      to: "boss",
+      status: "completed",
+    });
+
+    const evt = await readFrame(reader);
+    expect(evt.type).toBe("new_reply");
+    expect(evt.task_id).toBe("parent-task");
+    expect(evt.message_id).toBe("msg-9");
+    expect(evt.status).toBe("completed");
+    expect("content" in evt).toBe(false);
+    expect("text" in evt).toBe(false);
+    await reader.cancel();
+  });
+
+  test("events are network-isolated: observer on net B never sees net A traffic", async () => {
+    const resB = createNetworkObserverStream("net_obs_b");
+    const readerB = resB.body!.getReader();
+    await readFrame(readerB); // connected
+
+    // Push to A first, then a marker to B. Delivery per key is
+    // synchronous and ordered, so if B's next frame is the marker,
+    // the A event provably never reached B.
+    pushNetworkObserverEvent("net_obs_a2", { type: "new_task", task_id: "leaked" });
+    pushNetworkObserverEvent("net_obs_b", { type: "new_task", task_id: "marker-b" });
+
+    const evt = await readFrame(readerB);
+    expect(evt.task_id).toBe("marker-b");
+    await readerB.cancel();
+  });
+
+  test("observer stream is isolated from session channels (both directions)", async () => {
+    const sessionRes = createSSEStream("agent-x", "net_obs_c");
+    const sessionReader = sessionRes.body!.getReader();
+    await readFrame(sessionReader); // connected
+
+    const obsRes = createNetworkObserverStream("net_obs_c");
+    const obsReader = obsRes.body!.getReader();
+    await readFrame(obsReader); // connected
+
+    // Session push must NOT hit the observer; observer push must NOT
+    // hit the session. Marker technique as above.
+    pushEvent("agent-x", { type: "new_task", inbox_count: 1, marker: "to-session" }, "net_obs_c");
+    pushNetworkObserverEvent("net_obs_c", { type: "new_task", task_id: "to-observer" });
+
+    const sessionEvt = await readFrame(sessionReader);
+    expect(sessionEvt.marker).toBe("to-session");
+    expect("task_id" in sessionEvt).toBe(false);
+
+    const obsEvt = await readFrame(obsReader);
+    expect(obsEvt.task_id).toBe("to-observer");
+    expect("marker" in obsEvt).toBe(false);
+
+    await sessionReader.cancel();
+    await obsReader.cancel();
+  });
+
+  test("null / undefined networkId is a silent no-op", () => {
+    // Must not throw — legacy null-network traffic has no observer
+    // stream by design (documented in #461 / the PR).
+    expect(() => pushNetworkObserverEvent(null, { type: "new_task" })).not.toThrow();
+    expect(() => pushNetworkObserverEvent(undefined, { type: "new_task" })).not.toThrow();
+  });
+
+  test("multiple observers on the same network all receive the event", async () => {
+    const r1 = createNetworkObserverStream("net_obs_multi");
+    const r2 = createNetworkObserverStream("net_obs_multi");
+    const reader1 = r1.body!.getReader();
+    const reader2 = r2.body!.getReader();
+    await readFrame(reader1);
+    await readFrame(reader2);
+
+    pushNetworkObserverEvent("net_obs_multi", { type: "new_task", task_id: "fanout" });
+
+    expect((await readFrame(reader1)).task_id).toBe("fanout");
+    expect((await readFrame(reader2)).task_id).toBe("fanout");
+    await reader1.cancel();
+    await reader2.cancel();
+  });
+});
+
+describe("Desktop user SSE stream", () => {
+  test("user stream receives connected frame, then desktop_message", async () => {
+    const res = createUserEventStream("net_user_a", "u_user_a");
+    const reader = res.body!.getReader();
+
+    const connected = await readFrame(reader);
+    expect(connected.type).toBe("connected");
+    expect(connected.user).toBe(true);
+    expect(connected.network_id).toBe("net_user_a");
+    expect(connected.user_id).toBe("u_user_a");
+
+    pushUserEvent("net_user_a", "u_user_a", {
+      type: "desktop_message",
+      message_id: "dm_one",
+      from: "agent-a",
+      message: "hello",
+    });
+
+    const evt = await readFrame(reader);
+    expect(evt.type).toBe("desktop_message");
+    expect(evt.message_id).toBe("dm_one");
+    expect(evt.from).toBe("agent-a");
+    expect(evt.message).toBe("hello");
+    expect(evt.network_id).toBe("net_user_a");
+    expect(evt.user_id).toBe("u_user_a");
+    expect(evt.scope).toBe("user");
+    await reader.cancel();
+  });
+
+  test("user stream is isolated from alias and observer key spaces", async () => {
+    const userRes = createUserEventStream("net_user_iso", "u_iso");
+    const userReader = userRes.body!.getReader();
+    await readFrame(userReader);
+
+    const sessionRes = createSSEStream("u_iso", "net_user_iso");
+    const sessionReader = sessionRes.body!.getReader();
+    await readFrame(sessionReader);
+
+    const observerRes = createNetworkObserverStream("net_user_iso");
+    const observerReader = observerRes.body!.getReader();
+    await readFrame(observerReader);
+
+    pushEvent("u_iso", { type: "alias_marker", marker: "alias" }, "net_user_iso");
+    pushNetworkObserverEvent("net_user_iso", { type: "observer_marker", marker: "observer" });
+    pushUserEvent("net_user_iso", "u_iso", { type: "desktop_message", marker: "user" });
+
+    expect((await readFrame(sessionReader)).marker).toBe("alias");
+    expect((await readFrame(observerReader)).marker).toBe("observer");
+    expect((await readFrame(userReader)).marker).toBe("user");
+
+    await userReader.cancel();
+    await sessionReader.cancel();
+    await observerReader.cancel();
+  });
+
+  test("same user and network fan out to multiple live clients; cancelling one leaves the other live", async () => {
+    const r1 = createUserEventStream("net_user_multi", "u_multi");
+    const r2 = createUserEventStream("net_user_multi", "u_multi");
+    const reader1 = r1.body!.getReader();
+    const reader2 = r2.body!.getReader();
+    await readFrame(reader1);
+    await readFrame(reader2);
+
+    pushUserEvent("net_user_multi", "u_multi", { type: "desktop_message", message_id: "dm_fanout_1" });
+    expect((await readFrame(reader1)).message_id).toBe("dm_fanout_1");
+    expect((await readFrame(reader2)).message_id).toBe("dm_fanout_1");
+
+    await reader1.cancel();
+    pushUserEvent("net_user_multi", "u_multi", { type: "desktop_message", message_id: "dm_fanout_2" });
+    expect((await readFrame(reader2)).message_id).toBe("dm_fanout_2");
+    await reader2.cancel();
+  });
+});