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

package/src/push.ts

@@ -97,6 +97,45 @@ function clientKey(sessionName: string, networkId?: string | null): string {
   return `${networkId || "global"}:${sessionName}`;
 }
 
+// ── #461 network observer channels ───────────────────────────────────
+// Dashboard (or any network member) subscribes GET /events/network/:id
+// and receives SUMMARY events for ALL new_task / new_reply traffic in
+// that network — not just tasks it sent/received. Summary events carry
+// ids + routing metadata only, never task/reply content.
+//
+// Key scheme: leading NUL byte makes an observer key impossible to
+// forge from the session scheme above (`${networkId}:${sessionName}`)
+// for any networkId the hub itself issues (net_* / "global"). Only a
+// master-token caller could even inject a NUL into network_id via the
+// legacy ?network_id= path, and master token is root already.
+const OBSERVER_KEY_PREFIX = "\u0000netobs:";
+const USER_KEY_PREFIX = "\u0000user:";
+
+/** Printable form of `OBSERVER_KEY_PREFIX` — the shape emitted by
+ *  `printableKey()` (below) and therefore the shape callers see via
+ *  `getSSEStats().sessions`. Exported so downstream consumers (e.g.
+ *  `/health` filter in server.ts) key off the same literal instead of
+ *  each side re-writing the escape sequence — CR3 audit 4703b0e7
+ *  found server.ts had `"netobs:"` (no `\\0`) which never matched and
+ *  silently over-filtered observer keys. */
+export const PRINTABLE_OBSERVER_KEY_PREFIX = "\\0netobs:";
+
+function observerKey(networkId: string): string {
+  return `${OBSERVER_KEY_PREFIX}${networkId}`;
+}
+
+function userKey(networkId: string, userId: string): string {
+  return `${USER_KEY_PREFIX}${networkId}:${userId}`;
+}
+
+/** Render a client key for logs / stats. Observer keys embed a raw NUL
+ *  byte (collision guard above); printing that verbatim makes grep treat
+ *  hub logs as binary and breaks log shippers, and getSSEStats feeds
+ *  /health. Display as a visible "\\0" escape instead. */
+function printableKey(key: string): string {
+  return key.split("\u0000").join("\\0");
+}
+
 // ─────────────────────────────────────────────────────────────────────
 // Close + dispatch helpers
 // ─────────────────────────────────────────────────────────────────────
@@ -114,7 +153,7 @@ function closeClient(client: SSEClient, reason: string): void {
     // Already closed by the runtime, or controller errored. Either way
     // we're done with it.
   }
-  console.log(`[${ts()}] SSE ✕ ${client.key} closed (reason=${reason})`);
+  console.log(`[${ts()}] SSE ✕ ${printableKey(client.key)} closed (reason=${reason})`);
 }
 
 /** Best-effort enqueue with backpressure guard. Returns:
@@ -215,8 +254,33 @@ function ensureLivenessSweep(): void {
 
 /** 创建 SSE Response 并注册到 clients map */
 export function createSSEStream(sessionName: string, networkId?: string | null): Response {
+  return createStreamForKey(
+    clientKey(sessionName, networkId),
+    { type: "connected", session: sessionName, network_id: networkId ?? null },
+  );
+}
+
+/** #461 — 创建网络级观察者 SSE Response（dashboard 观察第三方流量）。
+ *  Shares the exact same registration / backpressure / liveness
+ *  machinery as session streams; only the key scheme differs. */
+export function createNetworkObserverStream(networkId: string): Response {
+  return createStreamForKey(
+    observerKey(networkId),
+    { type: "connected", observer: true, network_id: networkId },
+  );
+}
+
+/** Desktop/user client SSE stream. Keyed by authenticated user_id, not
+ *  alias/session, so Desktop does not need to mint a pseudo node token. */
+export function createUserEventStream(networkId: string, userId: string): Response {
+  return createStreamForKey(
+    userKey(networkId, userId),
+    { type: "connected", user: true, network_id: networkId, user_id: userId },
+  );
+}
+
+function createStreamForKey(key: string, initialEvent: Record<string, unknown>): Response {
   const encoder = new TextEncoder();
-  const key = clientKey(sessionName, networkId);
   let client: SSEClient;
 
   const stream = new ReadableStream<Uint8Array>({
@@ -231,13 +295,13 @@ export function createSSEStream(sessionName: string, networkId?: string | null):
 
       if (!clients.has(key)) clients.set(key, []);
       clients.get(key)!.push(client);
-      console.log(`[${ts()}] SSE ← ${key} connected (${clients.get(key)!.length} clients)`);
+      console.log(`[${ts()}] SSE ← ${printableKey(key)} connected (${clients.get(key)!.length} clients)`);
 
       // Send initial connected frame through the backpressure guard so
       // even the first byte respects the contract.
       tryEnqueueBytes(
         client,
-        encoder.encode(`data: ${JSON.stringify({ type: "connected", session: sessionName, network_id: networkId ?? null })}\n\n`),
+        encoder.encode(`data: ${JSON.stringify(initialEvent)}\n\n`),
       );
 
       // Periodic keepalive doubles as a half-open probe — if the
@@ -280,7 +344,12 @@ export function createSSEStream(sessionName: string, networkId?: string | null):
 
   return new Response(stream, {
     headers: {
-      "Content-Type": "text/event-stream",
+      // #426: explicit charset so legacy Windows clients (PowerShell 5.1's
+      // Invoke-RestMethod / Invoke-WebRequest default to ISO-8859-1 when
+      // Content-Type omits the charset) decode UTF-8 payloads correctly.
+      // Hub itself was already writing clean UTF-8 bytes; the client-side
+      // 双重编码样式 mojibake was the header telling the client to guess.
+      "Content-Type": "text/event-stream; charset=utf-8",
       "Cache-Control": "no-cache, no-transform",
       "Connection": "keep-alive",
     },
@@ -294,7 +363,7 @@ function pruneClosed(key: string): void {
   const alive = arr.filter((c) => !c.closed);
   if (alive.length === 0) {
     clients.delete(key);
-    console.log(`[${ts()}] SSE ✕ ${key} disconnected (0 remaining)`);
+    console.log(`[${ts()}] SSE ✕ ${printableKey(key)} disconnected (0 remaining)`);
   } else if (alive.length !== arr.length) {
     clients.set(key, alive);
   }
@@ -327,6 +396,17 @@ eventBus.on("rename-committed", (event: RenameCommittedEvent) => {
 });
 
 /** 推送事件给指定 session 的所有 SSE 连接 */
+/** 这个 alias 上此刻是否真的有活着的 SSE 订阅者。
+ *
+ *  这是投递可达性的**实测**，区别于 resolveDeliveryTarget 里那个基于
+ *  last_seen_at 的**猜测**。一个安静但连着的会话（例如遵守「停发心跳」
+ *  规则的 MCP 会话）在时间戳判据下是 offline，在这里是 true。 */
+export function hasSubscribers(sessionName: string, networkId?: string | null): boolean {
+  const arr = clients.get(clientKey(sessionName, networkId));
+  if (!arr) return false;
+  return arr.some((c) => !c.closed);
+}
+
 export function pushEvent(sessionName: string, event: Record<string, unknown>, networkId?: string | null): void {
   const key = clientKey(sessionName, networkId ?? (event.network_id as string | null | undefined));
   const arr = clients.get(key);
@@ -347,6 +427,82 @@ export function pushEvent(sessionName: string, event: Record<string, unknown>, n
   if (needPrune) pruneClosed(key);
 }
 
+/** #461 — 推送网络级摘要事件给该网络的所有观察者连接。
+ *
+ *  Callers pass ROUTING METADATA ONLY (task_id / from / to / status /
+ *  priority / message_id) — never task or reply content. The event is
+ *  stamped with `network_id` + `scope: "network"` here so observers can
+ *  always tell which network the event belongs to and that it came from
+ *  the observer stream rather than their personal channel.
+ *
+ *  No-op when networkId is falsy: legacy null-network traffic has no
+ *  observer stream (the route requires an explicit network id). */
+export function pushNetworkObserverEvent(
+  networkId: string | null | undefined,
+  event: Record<string, unknown>,
+): void {
+  if (!networkId) return;
+  const key = observerKey(networkId);
+  const arr = clients.get(key);
+  if (!arr || arr.length === 0) return;
+
+  const data = `data: ${JSON.stringify({ ...event, network_id: networkId, scope: "network" })}\n\n`;
+  let needPrune = false;
+
+  for (const c of arr) {
+    if (c.closed) {
+      needPrune = true;
+      continue;
+    }
+    const result = tryEnqueueBytes(c, c.encoder.encode(data));
+    if (result === "dead") needPrune = true;
+  }
+
+  if (needPrune) pruneClosed(key);
+}
+
+/** Push an event to every active Desktop/web client for one user in one
+ *  network. No-op for falsy network/user ids; auth must be enforced by
+ *  the caller before invoking this helper. */
+/** 这个用户此刻是否真的有活着的 SSE 订阅者。
+ *
+ *  与 alias 版 `hasSubscribers` 同形状：投递可达性的**实测**，
+ *  调用方据此把「送到了」和「没人听」区分开，而不是一律报成功。 */
+export function hasUserSubscribers(
+  networkId: string | null | undefined,
+  userId: string | null | undefined,
+): boolean {
+  if (!networkId || !userId) return false;
+  const arr = clients.get(userKey(networkId, userId));
+  if (!arr) return false;
+  return arr.some((c) => !c.closed);
+}
+
+export function pushUserEvent(
+  networkId: string | null | undefined,
+  userId: string | null | undefined,
+  event: Record<string, unknown>,
+): void {
+  if (!networkId || !userId) return;
+  const key = userKey(networkId, userId);
+  const arr = clients.get(key);
+  if (!arr || arr.length === 0) return;
+
+  const data = `data: ${JSON.stringify({ ...event, network_id: networkId, user_id: userId, scope: "user" })}\n\n`;
+  let needPrune = false;
+
+  for (const c of arr) {
+    if (c.closed) {
+      needPrune = true;
+      continue;
+    }
+    const result = tryEnqueueBytes(c, c.encoder.encode(data));
+    if (result === "dead") needPrune = true;
+  }
+
+  if (needPrune) pruneClosed(key);
+}
+
 export function __resetSSEClientsForTest(): void {
   for (const arr of clients.values()) {
     for (const c of arr) closeClient(c, "reset-for-test");
@@ -365,7 +521,7 @@ export function getSSEStats(): { total: number; sessions: Record<string, number>
   for (const [name, arr] of clients) {
     const alive = arr.filter((c) => !c.closed);
     if (alive.length === 0) continue;
-    sessions[name] = alive.length;
+    sessions[printableKey(name)] = alive.length;
     total += alive.length;
   }
   return { total, sessions };

package/src/redact-tokens.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "bun:test";
+import { redactTokens, redactMessageRow } from "./redact-tokens.js";
+
+describe("#1459 ③ redact-at-read", () => {
+  test("🔴 各种前缀形状都被遮住，且前缀保留（读者仍知道泄漏的是哪一类）", () => {
+    const cases: Array<[string, string]> = [
+      ["ntok_abcdef123456", "ntok_"],
+      ["utok_abcdef123456", "utok_"],
+      ["ghp_" + "A".repeat(24), "ghp_"],
+      ["github_pat_" + "B".repeat(24), "github_pat_"],
+      ["xoxb-1234567890-abcdef", "xoxb-"],
+      ["sk-" + "C".repeat(20), "sk-"],
+    ];
+    for (const [raw, prefix] of cases) {
+      const out = redactTokens(`before ${raw} after`);
+      expect(out).toContain("***redacted***");
+      expect(out).toContain(prefix);
+      expect(out).not.toContain(raw);          // 原值一定不能整体幸存
+      expect(out).toContain("before");         // 周围文本不受影响
+      expect(out).toContain("after");
+    }
+  });
+
+  test("🔴 保守：不像凭据的内容一个字都不能改", () => {
+    for (const s of [
+      "任务完成，磁盘 96%",
+      "see https://example.com/a-b_c",
+      "sk-",                       // 太短，不是凭据
+      "ntok_",                     // 光前缀
+      "the stock ticker is SKU-12",
+    ]) {
+      expect(redactTokens(s)).toBe(s);
+    }
+  });
+
+  test("同一段里的多个 token 全部被遮", () => {
+    const out = redactTokens(`a ntok_aaaaaaaaaa b sk-${"z".repeat(20)} c`);
+    expect(out.match(/\*\*\*redacted\*\*\*/g)?.length).toBe(2);
+  });
+
+  test("redactMessageRow 只碰自由文本字段，不动结构字段", () => {
+    const row = {
+      message_id: "dm_ntok_looking_but_is_an_id",
+      user_id: "u_1",
+      content: "here is ntok_abcdef123456",
+      title: "sk-" + "d".repeat(20),
+      meta_json: JSON.stringify({ note: "ghp_" + "E".repeat(24) }),
+      created_at: "2026-08-30 00:00:00",
+    };
+    const out = redactMessageRow(row);
+    expect(out.content).toContain("***redacted***");
+    expect(out.title).toContain("***redacted***");
+    expect(out.meta_json).toContain("***redacted***");
+    // 结构字段原样 —— 即便 message_id 里恰好有个像前缀的子串
+    expect(out.message_id).toBe(row.message_id);
+    expect(out.user_id).toBe(row.user_id);
+    expect(out.created_at).toBe(row.created_at);
+  });
+
+  test("非字符串原样返回（null/数字不该被改成字符串）", () => {
+    expect(redactTokens(null as any)).toBeNull();
+    expect(redactTokens(42 as any)).toBe(42);
+    expect(redactMessageRow({ content: null, title: 7 } as any)).toEqual({ content: null, title: 7 } as any);
+  });
+});

package/src/redact-tokens.ts

@@ -0,0 +1,40 @@
+// #1459 ③ —— 读取时的 token 形状脱敏（redact-at-read）。
+//
+// 为什么在**读取**侧而不是写入侧：写入方是 agent，不受信任。存储侧已经走
+// normalizeMetaJson（跨主机路径脱敏，与 inbox 一致），那一层防的是"路径泄漏"；
+// 这一层防的是"有人把凭据塞进消息正文或 meta"。两层管的不是同一件事。
+//
+// 🔴 保守优先：宁可漏脱敏一个不像凭据的串，也不要把正常内容改花。所以只匹配
+//    几个**有明确前缀**的形状，不做熵检测、不猜。
+
+/** 有明确前缀的凭据形状。
+ *
+ *  🔴 前缀用**捕获组显式声明**，不靠"切到第一个下划线"之类的推断 ——
+ *     第一版就是那么写的，`github_pat_xxx` 被切成了 `github_`，把"这是哪一类
+ *     凭据"这个唯一有用的信息也遮掉了。声明比推断短，也不会错。 */
+const TOKEN_PATTERNS: ReadonlyArray<RegExp> = [
+  /\b(ntok_|utok_|atok_)[A-Za-z0-9_-]{6,}/g,          // 本仓自己的 token
+  /\b(github_pat_)[A-Za-z0-9_]{20,}/g,                // GitHub fine-grained PAT（必须排在 ghp_ 之前无关，但更长的前缀先声明更清楚）
+  /\b(ghp_)[A-Za-z0-9]{20,}/g,                        // GitHub classic PAT
+  /\b(xox[bpoars]-)[A-Za-z0-9-]{10,}/g,               // Slack
+  /\b(sk-)[A-Za-z0-9_-]{16,}/g,                       // OpenAI 风格
+];
+
+/** 对任意文本做 token 形状脱敏。非字符串原样返回。 */
+export function redactTokens<T>(value: T): T {
+  if (typeof value !== "string") return value;
+  let out: string = value;
+  // 保留捕获到的前缀（让读者知道泄漏的是哪一类），其余一律遮掉；不保留尾部 ——
+  // 尾部对识别没帮助，却能帮攻击者缩小搜索空间。
+  for (const re of TOKEN_PATTERNS) out = out.replace(re, (_m, prefix: string) => `${prefix}***redacted***`);
+  return out as unknown as T;
+}
+
+/** 对一行消息做脱敏：只碰会承载自由文本的字段，不动 id/时间戳等结构字段。 */
+export function redactMessageRow<T extends Record<string, unknown>>(row: T): T {
+  const out: Record<string, unknown> = { ...row };
+  for (const field of ["content", "title", "meta_json"]) {
+    if (typeof out[field] === "string") out[field] = redactTokens(out[field] as string);
+  }
+  return out as T;
+}

package/src/reply-target-derivation.test.ts

@@ -0,0 +1,96 @@
+// f015d9d6 根因隔离：admin(dashboard/人类) 发给「无 node_id 的 MCP 会话」的任务，
+// 其回执被 reply_target_mismatch 拒绝。
+//
+// 上报时给出的假设是「校验依赖投递绑定 ⇒ 任务还没真正 deliver 进会话时回执会被拒」。
+// 本文件把两个变量分开量，一次只动一个：
+//   变量 1 = 任务是否已投递（status created vs delivered，有无 SSE 订阅者）
+//   变量 2 = 调用方是否显式传 alias
+// 如果假设成立，变量 1 应当决定结果；如果 alias 推导才是决定因素，变量 2 才会。
+import { beforeEach, afterAll, 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_admin_reply_f015";
+const USER = "user_admin_reply_f015";
+const ADMIN = "admin-f015";           // 人类/dashboard 发起方，无 node
+const AGENT = "agent-mcp-f015";       // MCP 会话：sessions 行 node_id = NULL
+const AGENT_NODE = "node-agent-f015"; // token 绑定的 node（会话本身仍无 node_id）
+
+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 {}
+}
+
+function seed() {
+  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]);
+  db.run(
+    "INSERT INTO nodes (node_id, node_name, alias, network_id, hostname, config_snapshot, created_at, updated_at, lifecycle_state) VALUES (?1, ?2, ?2, ?3, 'host', '{}', datetime('now'), datetime('now'), 'active')",
+    [AGENT_NODE, AGENT, NET],
+  );
+  // 🔴 关键夹具属性：会话行 node_id 为 NULL —— 这正是 MCP 挂载的 claude-code 会话的形状
+  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'), datetime('now'))",
+    [`cc-n_${AGENT}`, AGENT, NET],
+  );
+  db.run(
+    "INSERT INTO api_tokens (token_id, token_hash, user_id, network_id, name, scope, bound_node_id) VALUES (?1, ?2, ?3, ?4, ?5, 'network', ?6)",
+    [`token-${AGENT}`, `hash-${AGENT}`, USER, NET, `node:${AGENT}`, AGENT_NODE],
+  );
+}
+
+function toolsFor(alias: string): Record<string, ToolHandler> {
+  const server = new McpServer({ name: "admin-reply-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;
+}
+
+function parse(res: { content: Array<{ text: string }> }) { return JSON.parse(res.content[0].text); }
+
+/** 造一条 admin(人类) → AGENT 的任务；delivered 控制「是否已投递」这一个变量。 */
+function seedAdminTask(taskId: string, delivered: boolean) {
+  db.run(
+    `INSERT INTO tasks (task_id, from_name, from_node_id, to_name, to_node_id, content, status, priority, network_id, created_at)
+     VALUES (?1, ?2, NULL, ?3, NULL, 'ping', ?4, 'normal', ?5, datetime('now'))`,
+    [taskId, ADMIN, AGENT, delivered ? "delivered" : "created", NET],
+  );
+}
+
+describe("f015d9d6 — admin→无 node_id 的 MCP 会话，回执绑定", () => {
+  beforeEach(() => { cleanup(); seed(); });
+  afterAll(() => cleanup());
+
+  test("变量1：任务【未投递】+ 省略 alias（走 #1085 推导）⇒ 回执应当成功", async () => {
+    seedAdminTask("t-undelivered", false);
+    const r = parse(await toolsFor(AGENT).send_reply({ in_reply_to: "t-undelivered", text: "done", status: "completed" }));
+    expect(r).toEqual(expect.objectContaining({ ok: true }));
+  });
+
+  test("变量1 对照：任务【已投递且有 SSE 订阅者】+ 省略 alias ⇒ 同样成功", async () => {
+    seedAdminTask("t-delivered", true);
+    createSSEStream(AGENT, NET);
+    const r = parse(await toolsFor(AGENT).send_reply({ in_reply_to: "t-delivered", text: "done", status: "completed" }));
+    expect(r).toEqual(expect.objectContaining({ ok: true }));
+  });
+
+  test("变量2：显式传一个不等于任务发起方的 alias ⇒ reply_target_mismatch", async () => {
+    seedAdminTask("t-wrong-alias", true);
+    const r = parse(await toolsFor(AGENT).send_reply({ alias: "someone-else", in_reply_to: "t-wrong-alias", text: "done", status: "completed" }));
+    expect(r).toEqual(expect.objectContaining({ ok: false, error: "reply_target_mismatch" }));
+  });
+});

package/src/require-explicit-test-db.ts

@@ -0,0 +1,9 @@
+// #434: real-server integration tests must know their DB before importing
+// auth/db/server modules. Setting COMMHUB_DB in beforeAll is too late because
+// ESM dependencies have already evaluated the db singleton.
+if (!process.env.COMMHUB_DB) {
+  throw new Error(
+    "explicit_test_database_required: run `cd server && bun run test`, " +
+    "or set COMMHUB_DB to an isolated temporary path before running this file",
+  );
+}

package/src/resolve-port.test.ts

@@ -0,0 +1,57 @@
+import { expect, test } from "bun:test";
+import { DEFAULT_PORT, resolvePort } from "./resolve-port";
+
+// The whole reason this module exists.
+test("PORT=0 means an ephemeral port, not the production default", () => {
+  expect(resolvePort("0")).toBe(0);
+  expect(resolvePort("0")).not.toBe(DEFAULT_PORT);
+});
+
+test("unset or empty falls back to the default", () => {
+  expect(resolvePort(undefined)).toBe(DEFAULT_PORT);
+  expect(resolvePort("")).toBe(DEFAULT_PORT);
+  expect(resolvePort("   ")).toBe(DEFAULT_PORT);
+});
+
+test("surrounding whitespace is tolerated — it is trimmed, not treated as malformed", () => {
+  expect(resolvePort(" 9201 ")).toBe(9201);
+  expect(resolvePort("\t0\n")).toBe(0);
+});
+
+test("an explicit port is used verbatim", () => {
+  expect(resolvePort("9201")).toBe(9201);
+  expect(resolvePort("1")).toBe(1);
+  expect(resolvePort("65535")).toBe(65535);
+});
+
+// Defaulting on a malformed value means a typo silently starts the server on
+// the production port — on this fleet, on top of the running Hub.
+test("a malformed value is rejected, never quietly defaulted", () => {
+  for (const bad of ["abc", "80a", "-1", "65536", "1.5", "0x10", "NaN", "Infinity", "9 200", "+80"]) {
+    expect(() => resolvePort(bad)).toThrow();
+  }
+});
+
+test("the rejection names the value and the accepted range", () => {
+  try {
+    resolvePort("abc");
+    throw new Error("should have thrown");
+  } catch (e: any) {
+    expect(e.message).toContain("abc");
+    expect(e.message).toContain("0 and 65535");
+    expect(e.message).toContain("ephemeral");
+  }
+});
+
+test("a caller can override the fallback without touching the default", () => {
+  expect(resolvePort(undefined, 3000)).toBe(3000);
+  expect(resolvePort("0", 3000)).toBe(0);
+});
+
+test("server.ts resolves PORT through this module, not through `|| DEFAULT`", () => {
+  const src = require("fs").readFileSync(require("path").join(import.meta.dir, "server.ts"), "utf8");
+  const code = src.split("\n").filter((l: string) => !l.trim().startsWith("//")).join("\n");
+  expect(code).toContain("resolvePort(process.env.PORT)");
+  // `Number(env) || default` is the exact shape that swallowed the 0.
+  expect(code).not.toMatch(/Number\(process\.env\.PORT\)\s*\|\|/);
+});

package/src/resolve-port.ts

@@ -0,0 +1,44 @@
+// Resolve the listen port from the environment.
+//
+// `Number(process.env.PORT) || 9200` swallows a legitimate `0`. `Number("0")`
+// is `0`, which is falsy, so `PORT=0` — the conventional way to ask the OS for
+// an ephemeral port — silently became 9200, the production Hub port.
+//
+// Three consequences, and the middle one is the worst:
+//
+//   1. On a host where 9200 is already taken (a running Hub), a test that sets
+//      PORT=0 dies with EADDRINUSE and reads as a product bug.
+//      task-lifecycle-watcher.test.ts fails on main today for exactly this.
+//   2. On a host where 9200 is FREE, the same test passes — by binding 9200.
+//      It is green because it grabbed the production port, not because PORT=0
+//      worked. Green for the wrong reason is worse than red.
+//   3. Anyone asking for an ephemeral port gets the production port instead.
+//
+// The file already knew: `bootServer` uses `opts.port ?? PORT` with a comment
+// saying `||` "would swallow a legitimate 0". The rule was one level up from
+// where it was needed.
+//
+// A malformed value is rejected rather than defaulted. Falling back to 9200 on
+// `PORT=abc` means a typo silently starts the server somewhere the operator did
+// not ask for — and on this fleet that somewhere is production.
+
+export const DEFAULT_PORT = 9200;
+
+export function resolvePort(raw: string | undefined, fallback = DEFAULT_PORT): number {
+  // Unset or empty means "not specified". An empty string is what a shell
+  // exports for an unset variable it still passes along, so treating it as 0
+  // would make `PORT= anet hub start` bind an ephemeral port by accident.
+  if (raw === undefined || raw.trim() === "") return fallback;
+
+  // Decimal digits only, after trimming. `Number()` alone accepts "0x10" (16)
+  // and " 9200 ", so a value that does not look like a port would still resolve
+  // to one — quietly, and to a different number than the operator typed.
+  const text = raw.trim();
+  const n = /^\d+$/.test(text) ? Number(text) : NaN;
+  if (!Number.isInteger(n) || n < 0 || n > 65535) {
+    throw new Error(
+      `PORT must be an integer between 0 and 65535 (0 asks the OS for an ephemeral port); got ${JSON.stringify(raw)}`,
+    );
+  }
+  return n;
+}