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

package/src/avatar-validate.test.ts

@@ -0,0 +1,163 @@
+// #462 — unit tests for the avatar_url XSS boundary (avatar-validate.ts).
+//
+// The validator's whole job is to keep hostile values out of a dashboard
+// <img src>; every rejection case here is a concrete injection shape.
+// Live-gate check: replace validateAvatarUrl with `return { ok: true,
+// value: String(raw) }` and the javascript:/data:/control-char tests go
+// red.
+
+import { describe, expect, test } from "bun:test";
+import { MAX_AVATAR_URL_LENGTH, validateAvatarUrl } from "./avatar-validate";
+
+describe("#462 validateAvatarUrl", () => {
+  test("accepts plain https URL", () => {
+    const r = validateAvatarUrl("https://cdn.example.com/a/b.png");
+    expect(r).toEqual({ ok: true, value: "https://cdn.example.com/a/b.png" });
+  });
+
+  test("accepts http URL and trims surrounding whitespace", () => {
+    const r = validateAvatarUrl("  http://example.com/x.jpg  ");
+    expect(r).toEqual({ ok: true, value: "http://example.com/x.jpg" });
+  });
+
+  test("accepts URL with query string", () => {
+    const r = validateAvatarUrl("https://example.com/img?size=64&v=2");
+    expect(r.ok).toBe(true);
+  });
+
+  test("null / undefined / empty / whitespace-only → clear (value null)", () => {
+    expect(validateAvatarUrl(null)).toEqual({ ok: true, value: null });
+    expect(validateAvatarUrl(undefined)).toEqual({ ok: true, value: null });
+    expect(validateAvatarUrl("")).toEqual({ ok: true, value: null });
+    expect(validateAvatarUrl("   ")).toEqual({ ok: true, value: null });
+  });
+
+  test("rejects non-string types", () => {
+    expect(validateAvatarUrl(42).ok).toBe(false);
+    expect(validateAvatarUrl({ url: "https://x" }).ok).toBe(false);
+    expect(validateAvatarUrl(["https://x"]).ok).toBe(false);
+    expect(validateAvatarUrl(true).ok).toBe(false);
+  });
+
+  test("rejects javascript: pseudo-protocol", () => {
+    expect(validateAvatarUrl("javascript:alert(1)").ok).toBe(false);
+    expect(validateAvatarUrl("JavaScript:alert(1)").ok).toBe(false);
+    expect(validateAvatarUrl("JAVASCRIPT:alert(document.cookie)").ok).toBe(false);
+  });
+
+  test("rejects javascript: smuggled via embedded tab/newline (URL() would strip them)", () => {
+    expect(validateAvatarUrl("java\tscript:alert(1)").ok).toBe(false);
+    expect(validateAvatarUrl("java\nscript:alert(1)").ok).toBe(false);
+    expect(validateAvatarUrl("java\rscript:alert(1)").ok).toBe(false);
+  });
+
+  test("rejects data: / vbscript: / file: / blob: and other non-http protocols", () => {
+    expect(validateAvatarUrl("data:text/html,<script>alert(1)</script>").ok).toBe(false);
+    expect(validateAvatarUrl("data:image/png;base64,iVBORw0KGgo=").ok).toBe(false);
+    expect(validateAvatarUrl("vbscript:msgbox(1)").ok).toBe(false);
+    expect(validateAvatarUrl("file:///etc/passwd").ok).toBe(false);
+    expect(validateAvatarUrl("blob:https://example.com/uuid").ok).toBe(false);
+    expect(validateAvatarUrl("ftp://example.com/a.png").ok).toBe(false);
+  });
+
+  test("rejects protocol-relative / non-URL / schemeless strings", () => {
+    // SPEC CHANGE (通信龙 裁定, avatar 接线单): same-origin pool paths
+    // (/avatars/<name>.<ext>) are now ACCEPTED — that case moved to the
+    // dedicated relative-branch suite below. Everything here stays rejected.
+    expect(validateAvatarUrl("//cdn.example.com/1.png").ok).toBe(false);
+    expect(validateAvatarUrl("not a url").ok).toBe(false);
+    expect(validateAvatarUrl("example.com/x.png").ok).toBe(false);
+  });
+
+  test("rejects embedded whitespace and control characters", () => {
+    expect(validateAvatarUrl("https://example.com/a b.png").ok).toBe(false);
+    expect(validateAvatarUrl("https://example.com/a\u0000.png").ok).toBe(false);
+    expect(validateAvatarUrl("https://example.com/a\u009f.png").ok).toBe(false);
+  });
+
+  test("normalizes to parsed.href: markup-hostile chars come out percent-encoded (finding 3)", () => {
+    const r1 = validateAvatarUrl('https://example.com/a"b.png');
+    expect(r1).toEqual({ ok: true, value: "https://example.com/a%22b.png" });
+    const r2 = validateAvatarUrl("https://example.com/</script><script>.png");
+    expect(r2.ok).toBe(true);
+    if (r2.ok) {
+      expect(r2.value).not.toContain("<");
+      expect(r2.value).not.toContain(">");
+    }
+    const r3 = validateAvatarUrl("https://example.com/a`b.png");
+    expect(r3.ok).toBe(true);
+    if (r3.ok) expect(r3.value).not.toContain("`");
+  });
+
+  test("rejects values whose href still carries attribute-breaking chars (single quote)", () => {
+    // WHATWG URL leaves ' un-encoded in the PATH component — href alone
+    // doesn't neutralize it there, so the validator must refuse.
+    expect(validateAvatarUrl("https://example.com/a'b.png").ok).toBe(false);
+    // In the QUERY component ' IS percent-encoded by href → accepted,
+    // but the stored value must carry no raw quote.
+    const q = validateAvatarUrl("https://example.com/x.png?a='1'");
+    expect(q.ok).toBe(true);
+    if (q.ok) expect(q.value).not.toContain("'");
+  });
+
+  test("rejects URLs with embedded credentials (userinfo)", () => {
+    expect(validateAvatarUrl("https://user:pass@example.com/a.png").ok).toBe(false);
+    expect(validateAvatarUrl("https://user@example.com/a.png").ok).toBe(false);
+    expect(validateAvatarUrl("http://:secret@example.com/a.png").ok).toBe(false);
+  });
+
+  test("enforces the length cap", () => {
+    const base = "https://example.com/";
+    const ok = base + "a".repeat(MAX_AVATAR_URL_LENGTH - base.length);
+    expect(validateAvatarUrl(ok).ok).toBe(true);
+    expect(validateAvatarUrl(ok + "a").ok).toBe(false);
+  });
+});
+
+// ── Same-origin relative branch (通信龙 裁定: relax to portable pool paths;
+//    absolute URLs would weld one hostname into the DB across multi-origin
+//    entry points). Each direction is its OWN test so any single guard
+//    being deleted turns its OWN assertion red (no merged catch-all).
+describe("validateAvatarUrl — same-origin relative pool paths", () => {
+  test("accepts a pool path: /avatars/avatar-09.webp", () => {
+    const r = validateAvatarUrl("/avatars/avatar-09.webp");
+    expect(r).toEqual({ ok: true, value: "/avatars/avatar-09.webp" });
+  });
+
+  test("accepts png and svg pool files", () => {
+    expect(validateAvatarUrl("/avatars/intern_avatar.png")).toEqual({ ok: true, value: "/avatars/intern_avatar.png" });
+    expect(validateAvatarUrl("/avatars/team-logo.svg")).toEqual({ ok: true, value: "/avatars/team-logo.svg" });
+  });
+
+  test("rejects protocol-relative //host (classic same-origin bypass)", () => {
+    const r = validateAvatarUrl("//evil.com/x.png");
+    expect(r.ok).toBe(false);
+    if (!r.ok) expect(r.reason).toContain("protocol-relative");
+  });
+
+  test("rejects javascript: scheme (still, after the relax)", () => {
+    expect(validateAvatarUrl("javascript:alert(1)").ok).toBe(false);
+  });
+
+  test("rejects non-/avatars/ absolute paths (/etc/passwd)", () => {
+    expect(validateAvatarUrl("/etc/passwd").ok).toBe(false);
+  });
+
+  test("rejects non-whitelisted extensions under /avatars/", () => {
+    expect(validateAvatarUrl("/avatars/payload.html").ok).toBe(false);
+  });
+
+  test("rejects nested/traversal paths (charset forbids further slashes)", () => {
+    expect(validateAvatarUrl("/avatars/../secrets.webp").ok).toBe(false);
+    expect(validateAvatarUrl("/avatars/sub/x.webp").ok).toBe(false);
+  });
+
+  test("rejects percent-encoding inside the filename (no encoded surprises)", () => {
+    expect(validateAvatarUrl("/avatars/a%2f..%2fx.webp").ok).toBe(false);
+  });
+
+  test("absolute http(s) branch is UNTOUCHED by the relax (positive control)", () => {
+    const r = validateAvatarUrl("https://example.com/pic.png");
+    expect(r.ok).toBe(true);
+  });
+});

package/src/avatar-validate.ts

@@ -0,0 +1,103 @@
+// #462 — validator for the user-set custom avatar URL (nodes.avatar_url).
+//
+// The value ends up in an <img src> on every dashboard client, so this is
+// an XSS trust boundary: protocol MUST be http/https (rejects javascript:,
+// data:, vbscript:, file:, blob:, …), no whitespace/control characters,
+// bounded length. Pure function, unit-tested in avatar-validate.test.ts.
+
+export const MAX_AVATAR_URL_LENGTH = 2048;
+
+export type AvatarValidation =
+  | { ok: true; value: string | null }
+  | { ok: false; reason: string };
+
+/**
+ * Normalize + validate an untrusted avatar_url patch value.
+ *
+ *   null / undefined / "" / whitespace-only  → { ok, value: null }  (clear)
+ *   same-origin pool path /avatars/<name>.<ext>  → { ok, value: trimmed }
+ *   valid absolute http(s) URL               → { ok, value: normalized }
+ *   anything else                            → { ok: false, reason }
+ *
+ * Relative branch rationale (通信龙 裁定, avatar 接线单): the hub is
+ * reached through several origins (localhost dev, public domains) — an
+ * absolute URL would weld ONE hostname into the DB and break the image
+ * for every other entry point; a same-origin relative path is portable.
+ * 🔴 Trap this branch must block: "starts with /" ≠ "same-origin" —
+ * "//evil.com/x.png" ALSO starts with "/" but is a protocol-relative URL
+ * the browser resolves to evil.com. Hence: single leading slash with the
+ * SECOND char not "/", then an exact value-set match (the /avatars/ pool
+ * prefix + extension whitelist), not a shape match.
+ */
+
+// Exact allowed set for same-origin values: the dashboard's designed pool
+// under /avatars/. Filename charset excludes "/" (no traversal, no nested
+// paths) and "%" (no encoded surprises); extensions mirror the actual
+// pool contents. Widen ONLY by extending this list deliberately.
+const SAME_ORIGIN_AVATAR_RE = /^\/avatars\/[A-Za-z0-9._-]+\.(webp|png|svg)$/;
+export function validateAvatarUrl(raw: unknown): AvatarValidation {
+  if (raw === null || raw === undefined) return { ok: true, value: null };
+  if (typeof raw !== "string") {
+    return { ok: false, reason: "avatar_url must be a string or null" };
+  }
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return { ok: true, value: null };
+  if (trimmed.length > MAX_AVATAR_URL_LENGTH) {
+    return { ok: false, reason: `avatar_url must be ≤ ${MAX_AVATAR_URL_LENGTH} chars` };
+  }
+  // Reject embedded whitespace + C0/C1 control chars outright. URL()
+  // silently strips some of these (e.g. tabs/newlines), which would let
+  // "java\tscript:" style payloads normalize into a hostile protocol —
+  // so this check must run BEFORE parsing, on the raw trimmed string.
+  if (/[\u0000-\u001f\u007f-\u009f\s]/.test(trimmed)) {
+    return { ok: false, reason: "avatar_url must not contain whitespace or control characters" };
+  }
+  // Same-origin relative branch (runs AFTER the whitespace/control gate
+  // above — that check protects this branch too). Order of the two tests
+  // matters for the reason string, not for safety: the exact-set regex
+  // alone already rejects "//…" (second char is "/", first segment must
+  // literally be "avatars"), the explicit double-slash check just names
+  // the classic bypass in its own words.
+  if (trimmed.startsWith("/")) {
+    if (trimmed.startsWith("//")) {
+      return { ok: false, reason: "avatar_url must not be protocol-relative (//host/…)" };
+    }
+    if (!SAME_ORIGIN_AVATAR_RE.test(trimmed)) {
+      return { ok: false, reason: "relative avatar_url must match /avatars/<name>.(webp|png|svg)" };
+    }
+    return { ok: true, value: trimmed };
+  }
+  // Absolute http(s) branch — unchanged from #462 (do not touch while
+  // relaxing: 通信龙 裁定 condition 3).
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return { ok: false, reason: "avatar_url must be an absolute URL" };
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    return { ok: false, reason: "avatar_url protocol must be http or https" };
+  }
+  // Embedded credentials (https://user:pass@host/…) would be persisted,
+  // leaked to the avatar host on every render, and can spoof the visible
+  // origin in UIs. Reject outright rather than silently stripping — the
+  // caller should know their input carried secrets (通信龙 review round-2
+  // follow-up).
+  if (parsed.username || parsed.password) {
+    return { ok: false, reason: "avatar_url must not contain credentials (userinfo)" };
+  }
+  // Persist the NORMALIZED href, not the raw input: href percent-encodes
+  // markup-hostile characters (" < > ` → %22 %3C %3E %60), so what lands
+  // in the DB is already safe to interpolate into an <img src> attribute.
+  // The dashboard renderer lives in a different package this repo cannot
+  // audit — the server must not bet on it escaping (审查修复 per 通信龙
+  // #461/#462 review, finding 3).
+  const normalized = parsed.href;
+  // Belt-and-braces: reject anything href does NOT encode that could
+  // still break out of an attribute context (WHATWG URL leaves ' and \
+  // untouched in some positions).
+  if (/["'<>\\`]/.test(normalized)) {
+    return { ok: false, reason: "avatar_url contains characters not allowed in a URL" };
+  }
+  return { ok: true, value: normalized };
+}

package/src/binding-generation-http.test.ts

@@ -0,0 +1,121 @@
+import { beforeAll, afterAll, expect, test } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { preflightCodexStart } from "../../agent-node/src/runtime/adopt-codex-start-preflight.js";
+
+process.env.COMMHUB_DB ||= `${mkdtempSync("/tmp/binding-http-")}/hub.db`;
+process.env.COMMHUB_AUTH_TOKEN ||= "binding-master-fixture";
+let db:any, hub:ReturnType<typeof Bun.serve>, base:string, owner:any, other:any;
+const daemon="n_binding_daemon", child="n_binding_child";
+let token:string, wrong:string, cross:string, ordinary:string, revoked:string;
+async function mcp(credential:string,name:string,args:Record<string,unknown>={}) {
+  const res=await fetch(`${base}/mcp`, {method:"POST",headers:{Authorization:`Bearer ${credential}`,
+    "Content-Type":"application/json",Accept:"application/json, text/event-stream","MCP-Protocol-Version":"2025-03-26"},
+    body:JSON.stringify({jsonrpc:"2.0",id:1,method:"tools/call",params:{name,arguments:args}})});
+  const raw=await res.text();
+  if(res.status!==200)return {ok:false,http_status:res.status};
+  const lines=raw.split("\n").filter(s=>s.startsWith("data:"));
+  const payload=JSON.parse(lines.length?lines.at(-1)!.slice(5):raw);
+  return payload.result?.content?.[0]?.text ? JSON.parse(payload.result.content[0].text) : {ok:false,error:payload.error};
+}
+const list=(t=token)=>mcp(t,"list_my_children");
+const request=()=>mcp(owner.token,"request_adopt_node",{node_id:child,daemon_node_id:daemon,workdir:"/fixture/project"});
+const ack=(id:string,status="adopted")=>mcp(token,"ack_adopt_request",{request_id:id,status});
+const unadopt=()=>mcp(owner.token,"unadopt_node",{node_id:child});
+async function activate(){const r=await request();expect(r.ok).toBe(true);expect((await ack(r.request_id)).status).toBe("active");return r.request_id;}
+beforeAll(async()=>{
+  ({db}=await import("./db.js"));
+  const {register}=await import("./auth.js");
+  owner=register("binding_owner","Fixture-Strong1!");other=register("binding_other","Fixture-Strong1!");
+  expect(owner.ok&&other.ok).toBe(true);
+  db.run("UPDATE users SET role='user' WHERE user_id=?1",[other.user.user_id]);
+  db.run("INSERT INTO network_members(network_id,user_id,role) VALUES(?1,?2,'member')",[owner.network_id,other.user.user_id]);
+  const {generateNetworkToken,hashToken}=await import("./db.js");
+  function node(id:string,network:string,user:string,supervisor=true){
+    db.run("INSERT INTO nodes(node_id,node_name,alias,network_id,owner_user_id,hostname,config_snapshot,lifecycle_state) VALUES(?1,?1,?1,?2,?3,'fixture-host',?4,'active')",
+      [id,network,user,JSON.stringify(supervisor?{role:"host_supervisor",daemon_capabilities:{adopt_capable:true}}:{})]);
+    db.run("INSERT INTO sessions(resume_id,alias,node_id,network_id,status,last_seen_at) VALUES(?1,?1,?1,?2,'idle',datetime('now'))",[id,network]);
+    const raw=generateNetworkToken();
+    db.run("INSERT INTO api_tokens(token_id,user_id,network_id,scope,name,token_hash) VALUES(?1,?2,?3,'network',?4,?5)",[id,user,network,`node:${id}`,hashToken(raw)]);
+    return raw;
+  }
+  token=node(daemon,owner.network_id,owner.user.user_id);
+  wrong=node("n_binding_other",owner.network_id,other.user.user_id);
+  cross=node("n_binding_cross",other.network_id,other.user.user_id);
+  node(child,owner.network_id,owner.user.user_id,false);
+  ordinary=generateNetworkToken();revoked=generateNetworkToken();
+  for(const [id,raw,name,dead] of [["ordinary",ordinary,"general",null],["revoked",revoked,`node:${daemon}`,"2020-01-01"]])
+    db.run("INSERT INTO api_tokens(token_id,user_id,network_id,scope,name,token_hash,revoked_at) VALUES(?1,?2,?3,'network',?4,?5,?6)",[id,owner.user.user_id,owner.network_id,name,hashToken(raw as string),dead]);
+  db.run("INSERT INTO nodes(node_id,node_name,alias,network_id,lifecycle_state) VALUES('node_binding_created','created','created',?1,'active')",[owner.network_id]);
+  db.run("INSERT INTO node_create_requests(request_id,daemon_node_id,child_name,network_id,runtime,flags_json,env_keys,status,created_at,created_by_token) VALUES('cr_binding_created',?1,'created',?2,'codex-sdk','{}','[]','succeeded',1,'fixture')",[daemon,owner.network_id]);
+  const {bootServer}=await import("./server.js");hub=bootServer({port:0,hostname:"127.0.0.1"});base=`http://127.0.0.1:${hub.port}`;
+},60000);
+afterAll(()=>hub?.stop(true));
+
+test("generation projection and unchanged created row",async()=>{
+  const id=await activate();
+  const r=await list();expect(r.ok).toBe(true);
+  expect((await mcp(token,"get_adopt_request",{request_id:id})).error).toBe("request_not_pending");
+  expect(r.children.find((n:any)=>n.child_node_id===child)).toEqual({child_node_id:child,alias:child,lifecycle_state:"active",managed:"adopted",binding_request_id:id});
+  expect(r.children.find((n:any)=>n.child_node_id==="node_binding_created")).toEqual({child_node_id:"node_binding_created",alias:"created",lifecycle_state:"active"});
+  // Old consumers continue reading exactly the same fields; additive only.
+  expect(r.children.map(({child_node_id,alias,lifecycle_state,managed}:any)=>({child_node_id,alias,lifecycle_state,managed}))).toContainEqual({child_node_id:child,alias:child,lifecycle_state:"active",managed:"adopted"});
+  expect((await unadopt()).ok).toBe(true);
+});
+test("token boundary denies humans general revoked and other owners",async()=>{
+  await activate();
+  for(const t of [owner.token,other.token,ordinary,revoked])expect((await list(t)).ok).toBe(false);
+  for(const t of [wrong,cross]){const r=await list(t);expect(r.ok).toBe(true);expect(r.children).toEqual([]);}
+  expect((await unadopt()).ok).toBe(true);
+});
+test("child node token sees an empty list, not its parent binding",async()=>{
+  const id=await activate();
+  try {
+    const issued=await fetch(`${base}/api/auth/node-token`,{method:"POST",
+      headers:{Authorization:`Bearer ${owner.token}`,"Content-Type":"application/json"},
+      body:JSON.stringify({network_id:owner.network_id,node_name:child,node_id:child})});
+    expect(issued.status).toBe(200);
+    const credential=await issued.json() as any;
+    expect(credential.ok).toBe(true);
+    expect(typeof credential.token).toBe("string");
+    // Same owner and network do not confer the parent's daemon identity.
+    expect((await list()).children.find((n:any)=>n.child_node_id===child).binding_request_id).toBe(id);
+    expect(await list(credential.token)).toEqual({ok:true,count:0,children:[]});
+  } finally {expect((await unadopt()).ok).toBe(true);}
+});
+test("network predicate rejects corrupted cross-network binding sentinel",async()=>{
+  const id=await activate();
+  // Deliberately inconsistent test DB: daemon stays in A, binding and child in B.
+  // This makes the network predicate independently load-bearing, HTTP still real.
+  try {
+    db.run("UPDATE node_daemon_bindings SET network_id=?1 WHERE request_id=?2",[other.network_id,id]);
+    db.run("UPDATE nodes SET network_id=?1 WHERE node_id=?2",[other.network_id,child]);
+    expect((await list()).children.some((n:any)=>n.child_node_id===child)).toBe(false);
+  } finally {
+    db.run("UPDATE node_daemon_bindings SET network_id=?1 WHERE request_id=?2",[owner.network_id,id]);
+    db.run("UPDATE nodes SET network_id=?1 WHERE node_id=?2",[owner.network_id,child]);await unadopt();
+  }
+});
+test("node join rejects mismatched node network sentinel",async()=>{
+  await activate();
+  try {db.run("UPDATE nodes SET network_id=?1 WHERE node_id=?2",[other.network_id,child]);expect((await list()).children.some((n:any)=>n.child_node_id===child)).toBe(false);}
+  finally {db.run("UPDATE nodes SET network_id=?1 WHERE node_id=?2",[owner.network_id,child]);await unadopt();}
+});
+test("non-active bindings never project generation",async()=>{
+  const r=await request();expect(r.ok).toBe(true);
+  expect((await list()).children.some((n:any)=>n.child_node_id===child)).toBe(false);
+  expect((await ack(r.request_id,"refused")).status).toBe("refused");
+  expect((await list()).children.some((n:any)=>n.child_node_id===child)).toBe(false);
+  await activate();await unadopt();expect((await list()).children.some((n:any)=>n.child_node_id===child)).toBe(false);
+});
+test("revocation rotates generation and old acknowledgements cannot revive",async()=>{
+  const r1=await activate();await unadopt();
+  expect((await ack(r1)).error).toBe("request_not_pending");
+  const r2=await request();expect(r2.ok).toBe(true);expect(r2.request_id).not.toBe(r1);
+  expect((await list()).children.some((n:any)=>n.child_node_id===child)).toBe(false);
+  expect((await ack(r2.request_id)).status).toBe("active");
+  const current=(await list()).children.find((n:any)=>n.child_node_id===child).binding_request_id;
+  expect(current).toBe(r2.request_id);expect(current).not.toBe(r1);
+  // Real HTTP authority feeds the existing daemon gate; later probes must not run.
+  for(const authority of [current,undefined])await expect(preflightCodexStart({request_id:r1} as any,{} as any,{} as any,authority,()=>true)).rejects.toThrow("adopt_codex_binding_generation_unproven");
+  await unadopt();
+});

package/src/blocked-exit-on-reply.test.ts

@@ -0,0 +1,122 @@
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { db } from "./db.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools } from "./tools.js";
+
+// #1548 —— 一个活着、能收发任务的节点可以在名册里永远显示 `blocked`:
+// 只有 report_completion 会把 sessions.status 拉回 idle,而现在大多数 agent 用
+// send_reply(终态)结束任务、用 send_task 派活 —— 这两条路径此前都不碰 sessions.status。
+// 「它刚回了我一条终态消息 / 刚派了一条任务」本身就是最强的活性证据。
+// 只出 `blocked`;`working` 可能真在忙别的任务,不碰(保守)。
+const NET_ID = "net_1548_blocked";
+const USER_ID = "u_1548";
+const NODE_ID = "node_1548_agent";
+const AGENT_ALIAS = "agent-1548";
+const DISPATCHER_NODE_ID = "node_1548_dispatcher";
+const DISPATCHER_ALIAS = "dispatcher-1548";
+const AGENT_TOK_ID = "tok_1548";
+
+type ToolHandler = (args: any, extra?: any) => Promise<{ content: Array<{ type: "text"; text: string }> }>;
+
+function cleanup() {
+  for (const [sql, params] of [
+    ["DELETE FROM tasks WHERE network_id = ?1", [NET_ID]],
+    ["DELETE FROM inbox WHERE network_id = ?1", [NET_ID]],
+    ["DELETE FROM task_events WHERE network_id = ?1", [NET_ID]],
+    ["DELETE FROM sessions WHERE network_id = ?1", [NET_ID]],
+    ["DELETE FROM nodes WHERE network_id = ?1", [NET_ID]],
+    ["DELETE FROM api_tokens WHERE network_id = ?1", [NET_ID]],
+    ["DELETE FROM network_members WHERE network_id = ?1", [NET_ID]],
+    ["DELETE FROM networks WHERE network_id = ?1", [NET_ID]],
+    ["DELETE FROM users WHERE user_id = ?1", [USER_ID]],
+  ] as const) {
+    try { db.run(sql, params as any); } catch {}
+  }
+}
+beforeEach(cleanup);
+afterAll(cleanup);
+
+function seed(agentStatus: string) {
+  db.run(`INSERT INTO users (user_id, username, password_hash, role, created_at) VALUES (?1, ?2, 'x', 'user', datetime('now'))`, [USER_ID, USER_ID]);
+  db.run(`INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?2, ?3, datetime('now'))`, [NET_ID, NET_ID, USER_ID]);
+  db.run(
+    `INSERT INTO network_members (user_id, network_id, role, joined_at)
+     VALUES (?1, ?2, 'owner', datetime('now'))`,
+    [USER_ID, NET_ID],
+  );
+  for (const [nodeId, alias] of [[DISPATCHER_NODE_ID, DISPATCHER_ALIAS], [NODE_ID, AGENT_ALIAS]] as const) {
+    db.run(
+      `INSERT INTO nodes (node_id, node_name, alias, network_id, hostname, created_at, updated_at, lifecycle_state)
+       VALUES (?1, ?2, ?3, ?4, ?5, datetime('now'), datetime('now'), 'active')`,
+      [nodeId, alias, alias, NET_ID, `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_${DISPATCHER_ALIAS}`, DISPATCHER_ALIAS, DISPATCHER_NODE_ID, NET_ID],
+  );
+  db.run(
+    `INSERT INTO sessions (resume_id, alias, status, node_id, network_id, updated_at, last_seen_at)
+     VALUES (?1, ?2, ?3, ?4, ?5, datetime('now'), datetime('now'))`,
+    [`res_${AGENT_ALIAS}`, AGENT_ALIAS, agentStatus, NODE_ID, NET_ID],
+  );
+  db.run(
+    `INSERT INTO api_tokens (token_id, user_id, network_id, scope, name, token_hash, expires_at, revoked_at)
+     VALUES (?1, ?2, ?3, 'network', ?4, ?5, NULL, NULL)`,
+    [AGENT_TOK_ID, USER_ID, NET_ID, `node:${AGENT_ALIAS}`, `hash_${AGENT_TOK_ID}`],
+  );
+}
+function makeTask(): string {
+  const id = "t_" + Math.random().toString(36).slice(2, 14);
+  db.run(
+    `INSERT INTO tasks (task_id, from_name, to_name, to_node_id, priority, status, content, requires_response, created_at, network_id)
+     VALUES (?1, ?2, ?3, ?4, 'normal', 'delivered', 'test', 'reply', datetime('now'), ?5)`,
+    [id, DISPATCHER_ALIAS, AGENT_ALIAS, NODE_ID, NET_ID],
+  );
+  return id;
+}
+function buildHandlers(): 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); };
+  const origRegisterTool = server.registerTool?.bind(server);
+  if (origRegisterTool) {
+    server.registerTool = (name: string, _cfg: any, handler: ToolHandler) => { tools[name] = handler; return origRegisterTool(name, _cfg, handler); };
+  }
+  registerTools(server, undefined, NET_ID, USER_ID, AGENT_ALIAS, true, AGENT_TOK_ID);
+  return tools;
+}
+async function call(handler: ToolHandler, args: any): Promise<any> {
+  const r = await handler(args);
+  return JSON.parse(r.content[0]!.text);
+}
+function agentStatus(): string {
+  return (db.get("SELECT status FROM sessions WHERE alias = ?1 AND network_id = ?2", [AGENT_ALIAS, NET_ID]) as { status: string }).status;
+}
+
+describe("#1548 blocked has an exit: a terminal reply or an outbound task proves the agent is alive", () => {
+  test("terminal send_reply from a blocked agent puts it back to idle", async () => {
+    seed("blocked");
+    const tools = buildHandlers();
+    const taskId = makeTask();
+    const r = await call(tools.send_reply!, { text: "done", in_reply_to: taskId, status: "replied", from_session: AGENT_ALIAS, network_id: NET_ID });
+    expect(r.ok, JSON.stringify(r)).toBe(true);
+    expect(agentStatus()).toBe("idle");
+  });
+  test("send_task from a blocked agent puts it back to idle", async () => {
+    seed("blocked");
+    const tools = buildHandlers();
+    const r = await call(tools.send_task!, { alias: DISPATCHER_ALIAS, task: "ping", priority: "normal", from_session: AGENT_ALIAS, network_id: NET_ID });
+    expect(r.ok, JSON.stringify(r)).toBe(true);
+    expect(agentStatus()).toBe("idle");
+  });
+  test("a working agent is left alone (it may be busy with another task)", async () => {
+    seed("working");
+    const tools = buildHandlers();
+    const taskId = makeTask();
+    await call(tools.send_reply!, { text: "done", in_reply_to: taskId, status: "replied", from_session: AGENT_ALIAS, network_id: NET_ID });
+    expect(agentStatus()).toBe("working");
+  });
+});

package/src/boot-side-effect.test.ts

@@ -0,0 +1,124 @@
+// #438 corrective — regression gate for the two boot-path failure modes:
+//
+//   1. import side effect: `import("./server.js")` must NOT bind any port.
+//      Pre-corrective (7fa3ad35, when this module was still index.ts with
+//      module-level `export const server = bootServer()`) this fails:
+//      witnessed-red showed the probe port EADDRINUSE right after import.
+//      The run-entry shim src/index.ts is the ONLY module whose import
+//      boots — by design, documented there — and is deliberately not
+//      imported anywhere in the test suite.
+//   2. silent no-op double start: `startHub()` is single-shot and must
+//      REJECT a second call observably — "I thought I started it but
+//      nothing happened" is the same failure family as the
+//      import.meta.main incident (#438 review).
+//
+// Test order inside this file matters: the no-side-effect probe must run
+// BEFORE anything calls startHub in this process. bun executes tests in
+// declaration order, and no other suite calls startHub.
+
+import { describe, expect, test } from "bun:test";
+
+const PROBE_PORT = 18500 + Math.floor(Math.random() * 500);
+
+describe("#438 corrective — importing server.ts is side-effect-free", () => {
+  test("importing server.js binds nothing (probe port stays free)", async () => {
+    // Pin the module's default PORT to the probe so that IF an import
+    // side effect ever regresses, it binds exactly the port we probe.
+    process.env.PORT = process.env.PORT || String(PROBE_PORT);
+    const probe = Number(process.env.PORT) || PROBE_PORT;
+    await import("./server.js");
+    // If import had booted a server, this bind would throw EADDRINUSE.
+    let listener: any = null;
+    expect(() => {
+      listener = Bun.listen({ hostname: "127.0.0.1", port: probe, socket: { data() {} } });
+    }).not.toThrow();
+    listener?.stop?.(true);
+  });
+});
+
+describe("#476 — import alone must let the process exit", () => {
+  test("a subprocess that only imports server.js exits by itself (no module-level timers hold the loop)", () => {
+    // Witnessed-red: pre-#476 (main 541a80aa) this child is killed by the
+    // timeout with a non-zero exit — two module-level setIntervals
+    // (rate-limit sweep + DB-writing task patrol) held the event loop
+    // after a bare import. Post-#476 both live inside startHub, so the
+    // child exits 0 on its own. Runs in a subprocess because the parent
+    // test process has its own handles and can't observe loop-emptiness.
+    const child = Bun.spawnSync({
+      cmd: ["bun", "-e", 'await import("./src/server.js");'],
+      cwd: `${import.meta.dir}/..`,
+      env: { ...process.env, COMMHUB_DB: process.env.COMMHUB_DB || "/tmp/anet-476-probe.db" },
+      timeout: 10_000,
+    });
+    expect(child.exitCode).toBe(0);
+  }, 15_000);
+
+  test("the moved task patrol actually FIRES under startHub (not just registered-looking)", () => {
+    // Fake-gate guard for the #476 move: stub patrolExpiredTasks to a
+    // no-op (or forget to register it in startHub) and this goes red.
+    // Runs in a subprocess because startHub is single-shot per process
+    // and the patrol period is shrunk via env for observability.
+    const script = `
+      process.env.COMMHUB_TASK_PATROL_MS = "100";
+      const { startHub } = await import("./src/server.js");
+      const { db } = await import("./src/db.js");
+      const hub = startHub({ port: 0, hostname: "127.0.0.1" });
+      db.run("DELETE FROM tasks WHERE task_id = 't476_patrol'");
+      db.run("INSERT INTO tasks (task_id, from_name, to_name, priority, status, content, created_at, expires_at) " +
+             "VALUES ('t476_patrol', 'a', 'b', 'normal', 'delivered', 'x', datetime('now'), datetime('now', '-1 minute'))");
+      await new Promise((r) => setTimeout(r, 600));
+      const row = db.get("SELECT status FROM tasks WHERE task_id = 't476_patrol'");
+      console.log("PATROL_RESULT:" + (row ? row.status : "missing"));
+      db.run("DELETE FROM tasks WHERE task_id = 't476_patrol'");
+      hub.stop(true);
+      process.exit(0);
+    `;
+    const child = Bun.spawnSync({
+      cmd: ["bun", "-e", script],
+      cwd: `${import.meta.dir}/..`,
+      env: { ...process.env, COMMHUB_DB: process.env.COMMHUB_DB || "/tmp/anet-476-patrol.db" },
+      timeout: 15_000,
+    });
+    const out = new TextDecoder().decode(child.stdout);
+    expect(out).toContain("PATROL_RESULT:expired");
+  }, 20_000);
+});
+
+describe("#438 corrective — startHub is explicit, single-shot, observable", () => {
+  test("startHub boots a live hub; second call throws with first boot's coordinates; bootServer stays available", async () => {
+    const { startHub, bootServer, getStartedHub } = await import("./server.js") as any;
+    expect(getStartedHub()).toBeNull();
+
+    const hub = startHub({ port: 0, hostname: "127.0.0.1" });
+    try {
+      expect(hub.port).toBeGreaterThan(0);
+      expect(getStartedHub()?.server).toBe(hub);
+
+      // Really listening — the production liveness probe, not just a
+      // non-null handle.
+      const health = await fetch(`http://127.0.0.1:${hub.port}/health`);
+      expect(health.status).toBe(200);
+      expect(((await health.json()) as any).ok).toBe(true);
+
+      // Second call must be an OBSERVABLE rejection, not a silent no-op,
+      // and must tell the caller where the first boot lives.
+      let thrown: Error | null = null;
+      try {
+        startHub({ port: 0 });
+      } catch (e: any) {
+        thrown = e;
+      }
+      expect(thrown).not.toBeNull();
+      expect(String(thrown!.message)).toContain("single-shot");
+      expect(String(thrown!.message)).toContain(String(hub.port));
+
+      // Throwaway instances stay available after startHub.
+      const extra = bootServer({ port: 0, hostname: "127.0.0.1" });
+      expect(extra.port).toBeGreaterThan(0);
+      expect(extra.port).not.toBe(hub.port);
+      extra.stop(true);
+    } finally {
+      hub.stop(true);
+    }
+  });
+});