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

package/src/status-alias-resolver-http.test.ts

@@ -0,0 +1,163 @@
+// 旧版 agent-node(< 2.5.0-preview.93)找自己别名的全量 /api/status 读法 → light 投影 + node_id。
+//
+// 背景(2026-10-01,app「连接较慢」#431):生产上约 2.3 次/秒的全量状态读(~93 KB gzip)几乎都来自旧节点的
+// CurrentAliasResolver,它只读 sessions[].node_id / .alias,且 2.5 s 硬超时。经 RELAY frp 隧道到国内机器时常常
+// 读不完就中止,Hub 已经推进隧道的字节被丢掉(约占隧道 60%)。这里钉住:
+//   - 签名只认「节点令牌 + Accept 恰好 application/json + 只有 network_id」(statusAliasResolverRead);
+//   - 命中时回 light + node_id,旧解析器照旧解析出别名(含改名之后);
+//   - 不命中的(用户令牌 / CLI 不带 Accept / 浏览器 */* / light / node_id / alias / full=1 / 多值 Accept)字节不变;
+//   - 量体积:同一批行,完整投影 vs 这条读法的 gzip 字节。
+
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { gzipSync } from "zlib";
+import { register, createNetworkTokenForNode } from "./auth.js";
+import { db } from "./db.js";
+import { statusAliasResolverRead } from "./status-alias-resolver.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-status-alias-resolver-"));
+let BASE = "";
+let hub: any = null;
+const PW = "StatusAliasResolverPassw0rd!";
+let userToken = "", userId = "", NET = "";
+let nodeToken = "";
+const ROWS = 120;
+
+function seed(i: number) {
+  const node = `node_sar_${i}`, alias = `sar-${i}`;
+  db.run(`INSERT INTO nodes (node_id, node_name, alias, network_id, owner_user_id) VALUES (?1, ?2, ?2, ?3, ?4)`, [node, alias, NET, userId]);
+  db.run(
+    `INSERT INTO sessions (resume_id, alias, node_id, status, network_id, task, output, project_dir, config_path, hostname, ip, server, agent, version,
+       cpu_load_1min, cpu_cores, mem_total_gb, mem_used_gb, mem_avail_gb, disk_total_gb, disk_used_gb, disk_avail_gb,
+       process_rss_bytes, process_rss_mb, process_cpu_pct, process_uptime_seconds, process_in_flight_count, updated_at, last_seen_at, registered_at)
+     VALUES (?1, ?2, ?3, 'idle', ?4, ?5, ?6, ?7, ?8, ?9, '10.0.0.' || ?10, ?9, 'agent-node:codex-app-server', '2.5.0-preview.88',
+       '1.5', '8', '61.4', '26.9', '34.5', '491.8', '442.2', '29.4', 121868288, 116.2, 0.2, 292866, 0,
+       datetime('now', '-' || ?10 || ' seconds'), datetime('now'), datetime('now', '-30 days'))`,
+    [`r_${node}`, alias, node, NET, `示例任务 ${i}:`.repeat(12), `示例输出 ${i} `.repeat(20), `/home/user/project-${i}`,
+      `/home/user/project-${i}/.anet/nodes/${alias}/config.json`, `sample-host-${i % 4}`, i],
+  );
+}
+
+async function req(path: string, headers: Record<string, string>) {
+  const res = await fetch(`${BASE}${path}`, { headers: { "Accept-Encoding": "gzip", ...headers } });
+  const text = await res.text();
+  return { status: res.status, text, body: JSON.parse(text) as any, projection: res.headers.get("x-status-projection") };
+}
+const asNode = (accept?: string) => ({ Authorization: `Bearer ${nodeToken}`, ...(accept !== undefined ? { Accept: accept } : {}) });
+const gz = (s: string) => gzipSync(Buffer.from(s)).length;
+
+// The exact call agent-node 2.5.0-preview.32 … .90 makes (dist/cli.js CurrentAliasResolver.fetchCanonicalAlias).
+async function oldResolver(nodeId: string, token: string, networkId: string): Promise<string | null> {
+  try {
+    const headers: Record<string, string> = { Accept: "application/json" };
+    if (token) headers.Authorization = `Bearer ${token}`;
+    const url = `${BASE}/api/status${networkId ? `?network_id=${encodeURIComponent(networkId)}` : ""}`;
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), 2500);
+    try {
+      const res = await fetch(url, { headers, signal: ctl.signal });
+      if (!res.ok) return null;
+      const body = (await res.json()) as { sessions?: Array<{ node_id?: string; alias?: string }> };
+      return body.sessions?.find((s) => s.node_id === nodeId)?.alias ?? null;
+    } finally { clearTimeout(timer); }
+  } catch { return null; }
+}
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+  process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+  process.env.HOST = "127.0.0.1";
+  const a = register(`sar_owner_${Date.now()}`, PW);
+  userToken = a.token!; userId = a.user!.user_id; NET = a.network_id!;
+  for (let i = 0; i < ROWS; i++) seed(i);
+  nodeToken = createNetworkTokenForNode(userId, NET, "sar-7", "node_sar_7").token!;
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("statusAliasResolverRead (signature)", () => {
+  const p = (q: string) => new URLSearchParams(q);
+  test("matches only node token + Accept exactly application/json + at most network_id", () => {
+    expect(statusAliasResolverRead(p(""), "ntok_x", "application/json")).toBe(true);
+    expect(statusAliasResolverRead(p("network_id=net_1"), "ntok_x", "application/json")).toBe(true);
+    expect(statusAliasResolverRead(p("network_id=net_1"), "ntok_x", " Application/JSON ")).toBe(true);
+    expect(statusAliasResolverRead(p("network_id=net_1"), "utok_x", "application/json")).toBe(false);
+    expect(statusAliasResolverRead(p("network_id=net_1"), "legacy-global-token", "application/json")).toBe(false);
+    expect(statusAliasResolverRead(p("network_id=net_1"), "ntok_x", null)).toBe(false);
+    expect(statusAliasResolverRead(p("network_id=net_1"), "ntok_x", "*/*")).toBe(false);
+    expect(statusAliasResolverRead(p("network_id=net_1"), "ntok_x", "application/json, text/plain, */*")).toBe(false);
+    for (const q of ["light=1", "node_id=n", "alias=a", "full=1", "network_id=n&full=1", "network_id=n&light=0"]) {
+      expect(statusAliasResolverRead(p(q), "ntok_x", "application/json")).toBe(false);
+    }
+  });
+});
+
+describe("GET /api/status for the old alias resolver", () => {
+  test("old resolver still resolves its alias from the light body", async () => {
+    expect(await oldResolver("node_sar_7", nodeToken, NET)).toBe("sar-7");
+    expect(await oldResolver("node_sar_7", nodeToken, "")).toBe("sar-7");
+    // other rows are resolvable too (the resolver can be asked about a renamed peer id) and an unknown id is null
+    expect(await oldResolver("node_sar_42", nodeToken, NET)).toBe("sar-42");
+    expect(await oldResolver("node_nobody", nodeToken, NET)).toBeNull();
+  });
+
+  test("…and follows a rename (the reason the resolver exists)", async () => {
+    db.run("UPDATE sessions SET alias = 'sar-7-renamed' WHERE node_id = 'node_sar_7'");
+    try {
+      expect(await oldResolver("node_sar_7", nodeToken, NET)).toBe("sar-7-renamed");
+    } finally {
+      db.run("UPDATE sessions SET alias = 'sar-7' WHERE node_id = 'node_sar_7'");
+    }
+  });
+
+  test("the body is the light projection plus node_id, marked by a header", async () => {
+    const r = await req(`/api/status?network_id=${NET}`, asNode("application/json"));
+    expect(r.status).toBe(200);
+    expect(r.projection).toBe("alias-resolver");
+    expect(r.body.sessions).toHaveLength(ROWS);
+    expect(Object.keys(r.body.sessions[0]).sort()).toEqual(["agent", "alias", "network_id", "node_id", "runtime", "server", "status", "task", "updated_at"]);
+    expect(r.body.summary.total).toBe(ROWS);
+  });
+
+  test("everything else is byte-identical to the full projection", async () => {
+    const full = await req(`/api/status?network_id=${NET}&full=1`, asNode("application/json"));
+    expect(full.projection).toBeNull();
+    expect(full.body.sessions[0].host).toBeDefined();
+    const same = [
+      await req(`/api/status?network_id=${NET}`, { Authorization: `Bearer ${userToken}`, Accept: "application/json" }), // user token (app / dashboard)
+      await req(`/api/status?network_id=${NET}`, asNode()),                                                          // anet CLI: authHeaders() only
+      await req(`/api/status?network_id=${NET}`, asNode("*/*")),                                                     // browser / undici / bun default
+      await req(`/api/status?network_id=${NET}`, asNode("application/json, text/plain, */*")),
+    ];
+    for (const r of same) {
+      expect(r.projection).toBeNull();
+      expect(r.body.sessions[0].host).toBeDefined();
+      expect(r.text).toBe(full.text);
+    }
+  });
+
+  test("light / node_id reads keep their own exact shape", async () => {
+    const light = await req(`/api/status?network_id=${NET}&light=1`, asNode("application/json"));
+    expect(light.projection).toBeNull();
+    expect(light.body.sessions[0].node_id).toBeUndefined();
+    const one = await req(`/api/status?network_id=${NET}&node_id=node_sar_7&light=1`, asNode("application/json"));
+    expect(one.body.sessions).toHaveLength(1);
+    expect(one.body.sessions[0].node_id).toBe("node_sar_7");
+  });
+
+  test("size: full projection vs the alias-resolver body (gzip)", async () => {
+    const full = await req(`/api/status?network_id=${NET}&full=1`, asNode("application/json"));
+    const slim = await req(`/api/status?network_id=${NET}`, asNode("application/json"));
+    const f = gz(full.text), s = gz(slim.text);
+    console.log(`[size] ${ROWS} rows: full ${full.text.length} B raw / ${f} B gzip → alias-resolver ${slim.text.length} B raw / ${s} B gzip (${Math.round(100 - (100 * s) / f)}% smaller)`);
+    expect(s).toBeLessThan(f / 2);
+  });
+});

package/src/status-alias-resolver.ts

@@ -0,0 +1,19 @@
+// GET /api/status 的「旧版 agent-node 找自己别名」读法识别(纯函数,可单测)。
+//
+// agent-node < 2.5.0-preview.93 的 CurrentAliasResolver 每 30 s 读一次全网完整 /api/status,只用
+// sessions[].node_id / .alias,并且 2.5 s 硬超时。它的请求有一个别的客户端都不发的签名(2026-10-01 逐个核过
+// 线上在用的 agent-node .32–.93 包、agent-network CLI 2.2.21 / 2.3.0-preview.76–.120 源码、dashboard、
+// claude-code 节点的 .anet/node-server.js):
+//   - 节点令牌(ntok_);
+//   - Accept 恰好是 `application/json`(CLI 的 authHeaders 只带 Authorization;浏览器 / undici / bun 默认 `*/*`);
+//   - 查询串里除了 network_id 什么都没有(不带 light / node_id / alias / full)。
+// 命中 ⇒ 回 light 投影 + node_id(它读的就这两列)。`?full=1` 永远拿完整投影。
+
+const ALLOWED_PARAMS = new Set(["network_id"]);
+
+export function statusAliasResolverRead(params: URLSearchParams, token: string, accept: string | null): boolean {
+  if (!token.startsWith("ntok_")) return false;
+  if ((accept ?? "").trim().toLowerCase() !== "application/json") return false;
+  for (const key of params.keys()) if (!ALLOWED_PARAMS.has(key)) return false;
+  return true;
+}

package/src/status-node-id-filter-http.test.ts

@@ -0,0 +1,161 @@
+// GET /api/status?node_id=<id> — one node's rows instead of the whole network.
+// Every agent-node resolves its own current alias every 30 s (CurrentAliasResolver). Unfiltered that
+// is the whole network's full projection (~91 KB gzip per call on production, ~90 nodes ⇒ ~3 req/s)
+// to read one row. This suite pins that the filter narrows, never widens (it is exactly the caller's
+// unfiltered rows with that node_id, for every kind of caller), that it combines with light=1 (which
+// then carries node_id so the caller can check the row is its own), that an unknown id is an empty
+// list rather than an error, that no/blank node_id is byte-identical to the old response, and that
+// /health advertises it.
+
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { register, createNetworkTokenForNode } from "./auth.js";
+import { db } from "./db.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-status-node-id-"));
+let BASE = "";
+let hub: any = null;
+const PW = "StatusNodeIdPassw0rd!";
+let aToken = "", aId = "", NET_A = "";
+let bToken = "", bId = "", NET_B = "";
+let nodeToken = "";
+
+async function raw(token: string | null, path: string) {
+  const res = await fetch(`${BASE}${path}`, { headers: token ? { Authorization: `Bearer ${token}` } : {} });
+  return { status: res.status, text: await res.text() };
+}
+async function get(token: string, path: string) {
+  const r = await raw(token, path);
+  return { status: r.status, body: JSON.parse(r.text) as any };
+}
+function seed(alias: string, node: string, net: string, owner: string, minutesAgo: number) {
+  db.run(`INSERT INTO nodes (node_id, node_name, alias, network_id, owner_user_id) VALUES (?1, ?2, ?2, ?3, ?4)`, [node, alias, net, owner]);
+  db.run(
+    `INSERT INTO sessions (resume_id, alias, node_id, status, network_id, task, updated_at, last_seen_at) VALUES (?1, ?2, ?3, 'idle', ?4, ?5, datetime('now', ?6), datetime('now'))`,
+    [`r_${node}`, alias, node, net, `task of ${alias}`, `-${minutesAgo} minutes`],
+  );
+}
+const nodeIds = (rows: any[]) => rows.map(r => r.node_id);
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+  process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+  process.env.HOST = "127.0.0.1";
+  const a = register(`sn_owner_a_${Date.now()}`, PW);
+  aToken = a.token!; aId = a.user!.user_id; NET_A = a.network_id!;
+  const b = register(`sn_owner_b_${Date.now()}`, PW);
+  bToken = b.token!; bId = b.user!.user_id; NET_B = b.network_id!;
+  seed("sn-one", "node_sn_one", NET_A, aId, 1);
+  seed("sn-two", "node_sn_two", NET_A, aId, 2);
+  seed("sn-three", "node_sn_three", NET_A, aId, 3);
+  seed("sn-b-only", "node_sn_b_only", NET_B, bId, 0);
+  const minted = createNetworkTokenForNode(aId, NET_A, "sn-two", "node_sn_two");
+  nodeToken = minted.token!;
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("/api/status?node_id=", () => {
+  test("node_id narrows the full projection to that node", async () => {
+    const r = await get(aToken, `/api/status?network_id=${NET_A}&node_id=node_sn_two`);
+    expect(r.status).toBe(200);
+    expect(nodeIds(r.body.sessions)).toEqual(["node_sn_two"]);
+    expect(r.body.sessions[0].alias).toBe("sn-two");
+    expect(typeof r.body.sessions[0].rules_file_capable).toBe("boolean");
+    expect(r.body.sessions[0].host).toBeDefined();
+    expect(r.body.summary.total).toBe(1);
+  });
+
+  test("combines with light=1: light projection, one row, and it carries node_id", async () => {
+    const r = await get(aToken, `/api/status?light=1&network_id=${NET_A}&node_id=node_sn_three`);
+    expect(r.status).toBe(200);
+    expect(r.body.sessions).toHaveLength(1);
+    expect(r.body.sessions[0].alias).toBe("sn-three");
+    expect(r.body.sessions[0].node_id).toBe("node_sn_three");
+    expect(r.body.sessions[0].host).toBeUndefined();
+    expect(Object.keys(r.body.sessions[0]).sort()).toEqual(
+      ["agent", "alias", "network_id", "node_id", "runtime", "server", "status", "task", "updated_at"],
+    );
+  });
+
+  test("unknown id is an empty list with 200, not a 404", async () => {
+    for (const path of [`/api/status?network_id=${NET_A}&node_id=node_nobody`, `/api/status?light=1&node_id=node_nobody`]) {
+      const r = await get(aToken, path);
+      expect(r.status).toBe(200);
+      expect(r.body.ok).toBe(true);
+      expect(r.body.sessions).toEqual([]);
+      expect(r.body.summary.total).toBe(0);
+    }
+  });
+
+  test("absent or blank node_id: response bytes identical to the old read (full and light)", async () => {
+    for (const base of [`/api/status?network_id=${NET_A}`, `/api/status?light=1&network_id=${NET_A}`, `/api/status`]) {
+      const plain = await raw(aToken, base);
+      const blank = await raw(aToken, `${base}${base.includes("?") ? "&" : "?"}node_id=%20`);
+      expect(plain.status).toBe(200);
+      expect(blank.text).toBe(plain.text);
+    }
+    // the light rows without the param never gained a node_id field
+    const light = await get(aToken, `/api/status?light=1&network_id=${NET_A}`);
+    expect(light.body.sessions.length).toBe(3);
+    for (const s of light.body.sessions) expect("node_id" in s).toBe(false);
+  });
+
+  test("never widens: for every caller, filtered == that caller's unfiltered rows with that node_id", async () => {
+    const callers = [aToken, bToken, nodeToken];
+    const ids = ["node_sn_one", "node_sn_two", "node_sn_three", "node_sn_b_only", "node_nobody"];
+    for (const tok of callers) {
+      const full = await get(tok, `/api/status`);
+      expect(full.status).toBe(200);
+      for (const id of ids) {
+        const one = await get(tok, `/api/status?node_id=${id}`);
+        expect(one.status).toBe(full.status);
+        expect(one.body.sessions).toEqual(full.body.sessions.filter((s: any) => s.node_id === id));
+      }
+    }
+  });
+
+  test("a member of another network gets nothing for a node outside their network", async () => {
+    const r = await get(bToken, `/api/status?node_id=node_sn_one`);
+    expect(r.status).toBe(200);
+    expect(r.body.sessions).toEqual([]);
+    const own = await get(bToken, `/api/status?node_id=node_sn_b_only`);
+    expect(nodeIds(own.body.sessions)).toEqual(["node_sn_b_only"]);
+  });
+
+  test("a node token reads its own row (light) and nothing from another network", async () => {
+    const own = await get(nodeToken, `/api/status?light=1&node_id=node_sn_two`);
+    expect(own.status).toBe(200);
+    expect(own.body.sessions.map((s: any) => [s.node_id, s.alias])).toEqual([["node_sn_two", "sn-two"]]);
+    const foreign = await get(nodeToken, `/api/status?light=1&node_id=node_sn_b_only`);
+    expect(foreign.status).toBe(200);
+    expect(foreign.body.sessions).toEqual([]);
+    // explicit other network_id is refused exactly as without the filter
+    const cross = await raw(nodeToken, `/api/status?network_id=${NET_B}&node_id=node_sn_b_only`);
+    const crossNoFilter = await raw(nodeToken, `/api/status?network_id=${NET_B}`);
+    expect(cross.status).toBe(crossNoFilter.status);
+    if (cross.status !== 200) expect(cross.text).toBe(crossNoFilter.text);
+    else expect(JSON.parse(cross.text).sessions).toEqual([]);
+  });
+
+  test("unauthenticated read is refused exactly as without the filter", async () => {
+    const withFilter = await raw(null, `/api/status?node_id=node_sn_one`);
+    const without = await raw(null, `/api/status`);
+    expect(withFilter.status).toBe(without.status);
+    expect(withFilter.text).toBe(without.text);
+  });
+
+  test("/health advertises status_node_id", async () => {
+    const r = await raw(null, `/health`);
+    expect(r.status).toBe(200);
+    expect(JSON.parse(r.text).capabilities).toContain("status_node_id");
+  });
+});

package/src/status-read-cache-http.test.ts

@@ -0,0 +1,229 @@
+// #431 —— GET /api/status 记忆化 + 强 ETag(status-read-cache.ts)。钉住:
+//   - 正文逐字节不变:随机写序列(改 sessions、健康上报、健康过期、改名清理)之后,每种读法「可能命中缓存的那一份」
+//     都等于「清空缓存当场重算的那一份」;而且确实命中过(不是全靠重算凑出来的绿);
+//   - JSON.stringify 与原来的 Response.json 对这些正文逐字节一致;Content-Type 不变;
+//   - 不同调用者(另一个网络的用户、节点令牌的别名解析读法)键不串;
+//   - 全量投影里有健康报告(health_observed_ms_ago 随时间走)就不缓存;
+//   - ETag / If-None-Match → 304;gzip 解开等于原文。
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { gunzipSync } from "zlib";
+import { register, createNetworkTokenForNode } from "./auth.js";
+import { db } from "./db.js";
+import { clearNodeHealthStore, recordNodeHealth, NODE_HEALTH_TTL_MS } from "./node-health-store.js";
+import { __resetStatusCacheForTest, __setStatusCacheBypassForTest, noteStatement, statusCacheStats, statusWriteGeneration } from "./status-read-cache.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-status-read-cache-"));
+let BASE = "";
+let hub: any = null;
+const PW = "StatusReadCachePassw0rd!";
+let userToken = "", userId = "", NET = "", nodeToken = "", otherToken = "", OTHER_NET = "";
+const ROWS = 60;
+
+// 时间戳在 JS 里算好再绑定(SQLite 的 datetime('now', …) 拼接在 PostgreSQL 上没有,这份测试两种库都跑)。
+const ts = (offsetSec: number) => new Date(Date.now() + offsetSec * 1000).toISOString().replace("T", " ").slice(0, 19);
+function seed(i: number) {
+  const node = `node_src_${i}`, alias = i % 2 ? `示例-${i}` : `src-${i}`;
+  db.run(`INSERT INTO nodes (node_id, node_name, alias, network_id, owner_user_id) VALUES (?1, ?2, ?2, ?3, ?4)`, [node, alias, NET, userId]);
+  db.run(
+    `INSERT INTO sessions (resume_id, alias, node_id, status, network_id, task, output, project_dir, hostname, server, agent, version,
+       cpu_load_1min, mem_total_gb, process_rss_bytes, external_schedules, updated_at, last_seen_at, registered_at)
+     VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?9, ?10, '2.5.0-preview.88', '1.5', '61.4', 121868288, ?11,
+       ?12, ?13, '2026-09-01 00:00:00')`,
+    [`r_${node}`, alias, node, i % 3 ? "idle" : "offline", NET, `示例任务 ${i}:\n  "引号" \\ 反斜杠 
 `.repeat(1 + (i % 5)),
+      i % 4 ? null : `示例输出 ${i}`, `/home/user/project-${i}`, `sample-host-${i % 4}`,
+      i % 2 ? "agent-node:codex-app-server" : "claude-code", i % 3 ? null : JSON.stringify([{ id: `s${i}`, every: 60 }]), ts(-i), ts(0)],
+  );
+}
+
+async function get(path: string, headers: Record<string, string>) {
+  const res = await fetch(`${BASE}${path}`, { headers });
+  const buf = new Uint8Array(await res.arrayBuffer());
+  return { status: res.status, buf, headers: res.headers };
+}
+const text = (b: Uint8Array) => new TextDecoder().decode(b);
+
+type Variant = { name: string; path: () => string; headers: () => Record<string, string> };
+const VARIANTS: Variant[] = [
+  { name: "user full", path: () => `/api/status?network_id=${NET}`, headers: () => ({ Authorization: `Bearer ${userToken}` }) },
+  { name: "user light", path: () => `/api/status?network_id=${NET}&light=1`, headers: () => ({ Authorization: `Bearer ${userToken}` }) },
+  { name: "user alias", path: () => `/api/status?network_id=${NET}&alias=${encodeURIComponent("示例-7")}`, headers: () => ({ Authorization: `Bearer ${userToken}` }) },
+  { name: "node light node_id", path: () => `/api/status?network_id=${NET}&light=1&node_id=node_src_9`, headers: () => ({ Authorization: `Bearer ${nodeToken}` }) },
+  { name: "old alias resolver", path: () => `/api/status?network_id=${NET}`, headers: () => ({ Authorization: `Bearer ${nodeToken}`, Accept: "application/json" }) },
+  { name: "node full=1", path: () => `/api/status?network_id=${NET}&full=1`, headers: () => ({ Authorization: `Bearer ${nodeToken}`, Accept: "application/json" }) },
+  { name: "other network user", path: () => `/api/status?network_id=${OTHER_NET}`, headers: () => ({ Authorization: `Bearer ${otherToken}` }) },
+];
+
+beforeAll(async () => {
+  process.env.COMMHUB_DB ||= join(DIR, "hub.db");
+  process.env.COMMHUB_UPLOADS_DIR = join(DIR, "uploads");
+  process.env.HOST = "127.0.0.1";
+  const a = register(`src_owner_${Date.now()}`, PW);
+  userToken = a.token!; userId = a.user!.user_id; NET = a.network_id!;
+  for (let i = 0; i < ROWS; i++) seed(i);
+  nodeToken = createNetworkTokenForNode(userId, NET, "src-8", "node_src_8").token!;
+  const b = register(`src_other_${Date.now()}`, PW);
+  otherToken = b.token!; OTHER_NET = b.network_id!;
+  const mod: any = await import("./server.js");
+  hub = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${hub.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("write detection", () => {
+  test("writes that name sessions bump the generation; reads and other tables do not", () => {
+    const g = statusWriteGeneration();
+    noteStatement("SELECT * FROM sessions");
+    noteStatement("UPDATE tasks SET status = 'x'");
+    noteStatement("INSERT INTO inbox (id) VALUES (1)");
+    expect(statusWriteGeneration()).toBe(g);
+    noteStatement("  update sessions set status='idle'");
+    noteStatement("INSERT INTO sessions (resume_id) VALUES ('x') RETURNING resume_id");
+    noteStatement("DELETE FROM sessions WHERE alias = 'x'");
+    noteStatement("WITH t AS (SELECT 1) UPDATE sessions SET task = NULL");
+    expect(statusWriteGeneration()).toBe(g + 4);
+  });
+
+  test("the hook sits on the shared db adapter (every module's writes go through it)", () => {
+    const g = statusWriteGeneration();
+    db.run("UPDATE sessions SET progress = progress WHERE 1=0");
+    expect(statusWriteGeneration()).toBe(g + 1);
+  });
+
+  test("no foreign key / trigger can change sessions without naming it", () => {
+    if (db.dialect === "postgres") {
+      const fks = db.all<{ c: number }>(`SELECT COUNT(*) AS c FROM information_schema.referential_constraints rc
+        JOIN information_schema.table_constraints tc ON tc.constraint_name = rc.unique_constraint_name WHERE tc.table_name = 'sessions'`);
+      expect(Number(fks[0]?.c ?? 0)).toBe(0);
+      const trg = db.all<{ c: number }>(`SELECT COUNT(*) AS c FROM information_schema.triggers WHERE action_statement ILIKE '%sessions%' OR event_object_table = 'sessions'`);
+      expect(Number(trg[0]?.c ?? 0)).toBe(0);
+      return;
+    }
+    const fks = db.all<{ sql: string }>("SELECT sql FROM sqlite_master WHERE sql IS NOT NULL").map(r => r.sql);
+    expect(fks.filter(s => /references\s+sessions\b/i.test(s))).toEqual([]);
+    expect(fks.filter(s => /create\s+trigger/i.test(s) && /\bsessions\b/i.test(s))).toEqual([]);
+  });
+});
+
+describe("GET /api/status bodies are byte-identical with the cache", () => {
+  test("random writes / health reports / expiry: cached == recomputed, and the cache is really used", async () => {
+    __resetStatusCacheForTest();
+    let rnd = 461;
+    const r = () => (rnd = (rnd * 1103515245 + 12345) % 2147483648) / 2147483648;
+    let compared = 0, hits = 0;
+    for (let step = 0; step < 60; step++) {
+      const op = Math.floor(r() * 6);
+      const i = Math.floor(r() * ROWS);
+      const alias = i % 2 ? `示例-${i}` : `src-${i}`;
+      if (op === 0) db.run(`UPDATE sessions SET status = ?1, updated_at = ?2 WHERE node_id = ?3`, [r() < 0.5 ? "idle" : "working", ts(step), `node_src_${i}`]);
+      if (op === 1) db.run(`UPDATE sessions SET task = ?1 WHERE node_id = ?2`, [`新任务 ${step}`, `node_src_${i}`]);
+      if (op === 2) recordNodeHealth(NET, alias, { bridge: "ok", app_server: { ok: r() < 0.5, rtt_ms: 3, last_error: null }, model_auth: "ok" });
+      if (op === 3) {
+        // A report that expires a few ms from now: the degraded field must disappear on time.
+        recordNodeHealth(NET, alias, { bridge: "ok", app_server: { ok: false, rtt_ms: null, last_error: "closed (code=1006)" }, model_auth: "ok" }, Date.now() - NODE_HEALTH_TTL_MS + 30);
+        await Bun.sleep(40);
+      }
+      if (op === 4) db.run(`UPDATE sessions SET alias = ?1 WHERE node_id = ?2`, [`${alias}-改`, `node_src_${i}`]);
+      // op 5: no write at all — the next reads must be cache hits for the cacheable variants.
+      for (const v of VARIANTS) {
+        const first = await get(v.path(), v.headers());
+        const before = statusCacheStats.hits;
+        const again = await get(v.path(), v.headers());
+        hits += statusCacheStats.hits - before;
+        // Fresh = recomputed right now, without dropping what the cache holds (stale entries must stay in play
+        // across steps — clearing here would hide a missed invalidation).
+        __setStatusCacheBypassForTest(true);
+        const fresh = await get(v.path(), v.headers()).finally(() => __setStatusCacheBypassForTest(false));
+        expect(first.status).toBe(200);
+        const norm = (b: Uint8Array) => text(b).replace(/"health_observed_ms_ago":\d+/g, '"health_observed_ms_ago":0');
+        expect(norm(first.buf)).toBe(norm(fresh.buf));
+        expect(norm(again.buf)).toBe(norm(fresh.buf));
+        if (!text(fresh.buf).includes('"health_observed_ms_ago":')) expect(text(again.buf)).toBe(text(fresh.buf));
+        compared++;
+      }
+    }
+    expect(compared).toBe(60 * VARIANTS.length);
+    // Cacheable variants (everything except a full body carrying a health report) read twice in a row must hit.
+    expect(hits).toBeGreaterThan(60 * 4);
+  }, 120_000);
+
+  test("JSON.stringify == Response.json for these bodies; headers keep Content-Type, add ETag", async () => {
+    for (const v of VARIANTS) {
+      const res = await get(v.path(), v.headers());
+      const body = text(res.buf);
+      expect(await Response.json(JSON.parse(body)).text()).toBe(body);
+      expect(res.headers.get("content-type")).toBe("application/json;charset=utf-8");
+      expect(res.headers.get("etag")).toMatch(/^"s-[0-9a-z]+-[0-9a-z]+"$/);
+    }
+  });
+
+  test("keys do not leak across callers", async () => {
+    const owner = JSON.parse(text((await get(`/api/status?network_id=${NET}`, { Authorization: `Bearer ${userToken}` })).buf));
+    const other = JSON.parse(text((await get(`/api/status?network_id=${OTHER_NET}`, { Authorization: `Bearer ${otherToken}` })).buf));
+    expect(owner.sessions.length).toBe(ROWS);
+    expect(other.sessions.length).toBe(0);
+    const resolver = await get(`/api/status?network_id=${NET}`, { Authorization: `Bearer ${nodeToken}`, Accept: "application/json" });
+    expect(resolver.headers.get("x-status-projection")).toBe("alias-resolver");
+    expect(Object.keys(JSON.parse(text(resolver.buf)).sessions[0])).not.toContain("host");
+  });
+
+  test("a health report expiring (no write at all) invalidates the cached body on time", async () => {
+    __resetStatusCacheForTest();
+    clearNodeHealthStore();
+    const v = VARIANTS[1]; // user light: carries `degraded` for a fresh down app_server
+    const [{ alias: target }] = db.all<{ alias: string }>("SELECT alias FROM sessions WHERE node_id = 'node_src_2'");
+    recordNodeHealth(NET, target, { bridge: "ok", app_server: { ok: false, rtt_ms: null, last_error: "closed (code=1006)" }, model_auth: "ok" }, Date.now() - NODE_HEALTH_TTL_MS + 1_500);
+    const during = text((await get(v.path(), v.headers())).buf);
+    expect(during).toContain('"degraded":[{"layer":"app_server"');
+    const hitsBefore = statusCacheStats.hits;
+    expect(text((await get(v.path(), v.headers())).buf)).toBe(during);
+    expect(statusCacheStats.hits).toBe(hitsBefore + 1); // it was cached
+    await Bun.sleep(1_600);
+    const after = text((await get(v.path(), v.headers())).buf);
+    expect(after).not.toContain('"degraded"');
+    __resetStatusCacheForTest();
+    expect(text((await get(v.path(), v.headers())).buf)).toBe(after);
+  });
+
+  test("full projection with a health report is not cached (its body moves with time)", async () => {
+    __resetStatusCacheForTest();
+    recordNodeHealth(NET, "src-0", { bridge: "ok", model_auth: "ok" });
+    const v = VARIANTS[0];
+    const a = text((await get(v.path(), v.headers())).buf);
+    await Bun.sleep(15);
+    const b = text((await get(v.path(), v.headers())).buf);
+    expect(statusCacheStats.uncacheable).toBeGreaterThanOrEqual(2);
+    expect(a).not.toBe(b); // health_observed_ms_ago moved — a cached copy would have frozen it
+  });
+});
+
+describe("ETag / 304 / gzip", () => {
+  test("If-None-Match with the current ETag → 304 empty; after a write → 200 with a new ETag", async () => {
+    const h = { Authorization: `Bearer ${nodeToken}`, Accept: "application/json" };
+    const first = await get(`/api/status?network_id=${NET}`, h);
+    const etag = first.headers.get("etag")!;
+    const not = await get(`/api/status?network_id=${NET}`, { ...h, "If-None-Match": etag });
+    expect(not.status).toBe(304);
+    expect(not.buf.byteLength).toBe(0);
+    expect(not.headers.get("x-status-projection")).toBe("alias-resolver");
+    db.run(`UPDATE sessions SET status = 'working', updated_at = ?1 WHERE node_id = 'node_src_3'`, [ts(120)]);
+    const changed = await get(`/api/status?network_id=${NET}`, { ...h, "If-None-Match": etag });
+    expect(changed.status).toBe(200);
+    expect(changed.headers.get("etag")).not.toBe(etag);
+  });
+
+  test("gzip (the old node's Accept-Encoding: gzip, deflate) decodes to the same bytes", async () => {
+    const h = { Authorization: `Bearer ${nodeToken}`, Accept: "application/json" };
+    const plain = await get(`/api/status?network_id=${NET}`, h);
+    const res = await fetch(`${BASE}/api/status?network_id=${NET}`, { headers: { ...h, "Accept-Encoding": "gzip, deflate" }, decompress: false } as any);
+    expect(res.headers.get("content-encoding")).toBe("gzip");
+    const raw = new Uint8Array(await res.arrayBuffer());
+    expect(text(gunzipSync(raw))).toBe(text(plain.buf));
+  });
+});