@sleep2agi/commhub-server 0.9.0-preview.6 → 0.9.0-preview.61

package/src/report-status-resume-id-handover.test.ts

@@ -0,0 +1,150 @@
+// 同一 alias 换 resume_id 上报时,hub 的 report_status 走的是「DELETE 旧行 + INSERT 新行」,
+// ON CONFLICT 里的 COALESCE 一次都不会触发 —— 上报里没带的描述性列(version / agent /
+// hostname / 遥测 / registered_at)全部变 NULL。
+//
+// 2026-09-04 DEV 真机(hub 日志):
+//   12:46:47 grok-v1 (sdk-n_6c)  → report_status: working       version=2.5.0-preview.64
+//   12:46:53 grok-v1 (grok-cli)  → report_status: working       ← TUI 的 MCP 上报,不带 version
+//   12:46:54 grok-v1 (sdk-n_6c)  → report_status: idle          ← 又换回来,也不带 version
+// 结果:version=NULL、registered_at 被改成 12:46:54。舰队里 grok 3/10、claude 5/15 有 version,
+// codex 34/34 有 —— 差别就是有没有第二个上报者。
+//
+// 判据:换 resume_id 之后,只有一行;上报了的列以上报为准,没上报的列从被替换的那行接手。
+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";
+
+const NET_ID = "net_handover";
+const USER_ID = "u_handover";
+const NODE_ID = "n_handover";
+const ALIAS = "grok-handover";
+const TOK_ID = "tok_handover";
+const RESUME_SDK = `sdk-${NODE_ID}`;
+const RESUME_CLI = `grok-cli-${NODE_ID}`;
+const OLD_REGISTERED_AT = "2026-01-02 03:04:05";
+
+type ToolHandler = (args: any, extra?: any) => Promise<{ content: Array<{ type: "text"; text: string }> }>;
+
+function cleanup() {
+  for (const [sql, params] of [
+    ["DELETE FROM agent_telemetry 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() {
+  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]);
+  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')`,
+    [NODE_ID, ALIAS, ALIAS, NET_ID, "dev-box"],
+  );
+  // agent-node 自己注册的那行:带 version / agent / hostname / 遥测 / 早就存在的 registered_at
+  db.run(
+    `INSERT INTO sessions (resume_id, alias, status, node_id, network_id, version, agent, hostname, server, project_dir,
+                           cpu_cores, mem_total_gb, disk_total_gb, registered_at, updated_at, last_seen_at)
+     VALUES (?1, ?2, 'working', ?3, ?4, '2.5.0-preview.64', 'agent-node:grok-build-cli', 'dev-box', 'dev-box', '/home/x/proj',
+             8, 61.4, 500, ?5, datetime('now'), datetime('now'))`,
+    [RESUME_SDK, ALIAS, NODE_ID, NET_ID, OLD_REGISTERED_AT],
+  );
+  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)`,
+    [TOK_ID, USER_ID, NET_ID, `node:${ALIAS}`, `hash_${TOK_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, ALIAS, true, 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);
+}
+
+type Row = { resume_id: string; status: string; version: string | null; agent: string | null; hostname: string | null;
+  cpu_cores: number | null; mem_total_gb: number | null; registered_at: string; task: string | null };
+function rows(): Row[] {
+  return db.all("SELECT resume_id, status, version, agent, hostname, cpu_cores, mem_total_gb, registered_at, task FROM sessions WHERE alias = ?1 AND network_id = ?2", [ALIAS, NET_ID]) as Row[];
+}
+
+describe("report_status: 同 alias 换 resume_id 时,描述性列从被替换的那行接手", () => {
+  test("第二个上报者(grok-cli)不带 version/agent/遥测 → 这些列保留,status/task 以本次为准,仍只有一行", async () => {
+    seed();
+    const tools = buildHandlers();
+    const r = await call(tools.report_status!, { resume_id: RESUME_CLI, alias: ALIAS, status: "working", task: "PING 已收到", network_id: NET_ID });
+    expect(r.ok, JSON.stringify(r)).toBe(true);
+    const all = rows();
+    expect(all.length).toBe(1);
+    const row = all[0]!;
+    expect(row.resume_id).toBe(RESUME_CLI);
+    expect(row.status).toBe("working");
+    expect(row.task).toBe("PING 已收到");
+    expect(row.version).toBe("2.5.0-preview.64");
+    expect(row.agent).toBe("agent-node:grok-build-cli");
+    expect(row.hostname).toBe("dev-box");
+    expect(row.cpu_cores).toBe(8);
+    expect(row.mem_total_gb).toBe(61.4);
+    expect(row.registered_at).toBe(OLD_REGISTERED_AT);
+  });
+
+  test("上报里带了的列以上报为准(version 变了就用新的)", async () => {
+    seed();
+    const tools = buildHandlers();
+    const r = await call(tools.report_status!, { resume_id: RESUME_CLI, alias: ALIAS, status: "idle", version: "9.9.9", hostname: "other-box", network_id: NET_ID });
+    expect(r.ok, JSON.stringify(r)).toBe(true);
+    const row = rows()[0]!;
+    expect(rows().length).toBe(1);
+    expect(row.version).toBe("9.9.9");
+    expect(row.hostname).toBe("other-box");
+    expect(row.agent).toBe("agent-node:grok-build-cli");
+  });
+
+  test("再换回原 resume_id(sdk)也不丢:两个上报者轮流说话,version 始终在", async () => {
+    seed();
+    const tools = buildHandlers();
+    await call(tools.report_status!, { resume_id: RESUME_CLI, alias: ALIAS, status: "working", network_id: NET_ID });
+    const r = await call(tools.report_status!, { resume_id: RESUME_SDK, alias: ALIAS, status: "idle", network_id: NET_ID });
+    expect(r.ok, JSON.stringify(r)).toBe(true);
+    const all = rows();
+    expect(all.length).toBe(1);
+    expect(all[0]!.resume_id).toBe(RESUME_SDK);
+    expect(all[0]!.status).toBe("idle");
+    expect(all[0]!.version).toBe("2.5.0-preview.64");
+    expect(all[0]!.registered_at).toBe(OLD_REGISTERED_AT);
+  });
+
+  test("没有别的行可接手时(全新 alias)行为不变:INSERT 一行,registered_at 取 now", async () => {
+    seed();
+    db.run("DELETE FROM sessions WHERE network_id = ?1", [NET_ID]);
+    const tools = buildHandlers();
+    const r = await call(tools.report_status!, { resume_id: RESUME_SDK, alias: ALIAS, status: "idle", network_id: NET_ID });
+    expect(r.ok, JSON.stringify(r)).toBe(true);
+    const all = rows();
+    expect(all.length).toBe(1);
+    expect(all[0]!.version).toBeNull();
+    expect(all[0]!.registered_at).not.toBe(OLD_REGISTERED_AT);
+  });
+});

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;
+}

package/src/response-charset.test.ts

@@ -0,0 +1,130 @@
+// #426 unit tests for the withUtf8CharsetContentType helper — the
+// piece that rewrites text-y Content-Type headers to include
+// charset=utf-8 so legacy Windows clients don't fall back to
+// ISO-8859-1 decoding. The helper lives in server/src/index.ts;
+// to keep the test standalone we re-implement its pure semantics here
+// and assert those. Any drift between this pure copy and the
+// production helper is caught by the "identical semantics" test at
+// the bottom via a source grep.
+
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// Pure re-implementation — MUST match server/src/index.ts:withUtf8CharsetContentType.
+function withUtf8CharsetContentType(res: Response): Response {
+  const ct = res.headers.get("content-type");
+  if (!ct) return res;
+  if (/;\s*charset=/i.test(ct)) return res;
+  const trimmed = ct.trim();
+  if (
+    trimmed === "application/json" ||
+    trimmed.startsWith("text/") ||
+    trimmed.startsWith("application/json;") ||
+    trimmed === "application/ld+json" ||
+    trimmed === "application/xml"
+  ) {
+    res.headers.set("content-type", `${trimmed}; charset=utf-8`);
+  }
+  return res;
+}
+
+function makeRes(contentType: string | null, body = ""): Response {
+  return new Response(body, { headers: contentType ? { "content-type": contentType } : {} });
+}
+
+describe("withUtf8CharsetContentType — #426", () => {
+  test("appends charset to text/event-stream", () => {
+    const res = withUtf8CharsetContentType(makeRes("text/event-stream"));
+    expect(res.headers.get("content-type")).toBe("text/event-stream; charset=utf-8");
+  });
+
+  test("appends charset to application/json (bare)", () => {
+    const res = withUtf8CharsetContentType(makeRes("application/json"));
+    expect(res.headers.get("content-type")).toBe("application/json; charset=utf-8");
+  });
+
+  test("appends charset to text/plain", () => {
+    const res = withUtf8CharsetContentType(makeRes("text/plain"));
+    expect(res.headers.get("content-type")).toBe("text/plain; charset=utf-8");
+  });
+
+  test("appends charset to text/html", () => {
+    const res = withUtf8CharsetContentType(makeRes("text/html"));
+    expect(res.headers.get("content-type")).toBe("text/html; charset=utf-8");
+  });
+
+  test("no-op when charset already present (case-insensitive)", () => {
+    for (const ct of [
+      "application/json; charset=utf-8",
+      "application/json;charset=UTF-8",
+      "text/event-stream;Charset=us-ascii",
+      "text/plain; CHARSET=iso-8859-1",
+    ]) {
+      const res = withUtf8CharsetContentType(makeRes(ct));
+      expect(res.headers.get("content-type")).toBe(ct);
+    }
+  });
+
+  test("no-op on binary types (opaque)", () => {
+    for (const ct of [
+      "application/octet-stream",
+      "image/png",
+      "image/jpeg",
+      "video/mp4",
+      "application/pdf",
+      "font/woff2",
+    ]) {
+      const res = withUtf8CharsetContentType(makeRes(ct));
+      expect(res.headers.get("content-type")).toBe(ct);
+    }
+  });
+
+  test("no-op when Content-Type header is absent entirely (returns as-is)", () => {
+    const res = withUtf8CharsetContentType(makeRes(null));
+    expect(res.headers.get("content-type")).toBeNull();
+  });
+
+  test("handles application/ld+json / application/xml", () => {
+    expect(withUtf8CharsetContentType(makeRes("application/ld+json")).headers.get("content-type"))
+      .toBe("application/ld+json; charset=utf-8");
+    expect(withUtf8CharsetContentType(makeRes("application/xml")).headers.get("content-type"))
+      .toBe("application/xml; charset=utf-8");
+  });
+
+  test("preserves non-charset parameters and appends charset (application/json; boundary=…)", () => {
+    // Bun's Response.json emits `application/json;charset=utf-8`; the test
+    // above covers that no-op path. When a caller sends a parametrised
+    // header like `application/json; profile=…`, the helper still recognises
+    // it via the `application/json;` prefix and appends the charset.
+    const res = withUtf8CharsetContentType(makeRes("application/json; profile=example"));
+    expect(res.headers.get("content-type")).toBe("application/json; profile=example; charset=utf-8");
+  });
+
+  test("returns the same Response instance (mutates in place)", () => {
+    const input = makeRes("text/event-stream");
+    const output = withUtf8CharsetContentType(input);
+    expect(output).toBe(input);
+  });
+
+  // Drift guard: the pure copy in this file MUST match the production
+  // helper's branching set. If someone edits one without touching the
+  // other, this test fails visibly instead of the helper going silently
+  // out of sync. Kept as fragment-level greps (not whole-body match) so
+  // added comments don't break the assertion.
+  test("production helper covers the same content-type branches", () => {
+    const src = readFileSync(join(import.meta.dir, "server.ts"), "utf-8");
+    expect(src).toContain("function withUtf8CharsetContentType(res: Response): Response {");
+    expect(src).toContain("if (/;\\s*charset=/i.test(ct)) return res;");
+    for (const branch of [
+      'trimmed === "application/json"',
+      'trimmed.startsWith("text/")',
+      'trimmed.startsWith("application/json;")',
+      'trimmed === "application/ld+json"',
+      'trimmed === "application/xml"',
+    ]) {
+      expect(src).toContain(branch);
+    }
+    expect(src).toContain('res.headers.set("content-type", `${trimmed}; charset=utf-8`);');
+  });
+});

package/src/rest-explicit-columns-http.test.ts

@@ -0,0 +1,216 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const PRIVATE_DB_DIR = mkdtempSync(join(tmpdir(), "anet-rest-columns-"));
+process.env.COMMHUB_DB ||= join(PRIVATE_DB_DIR, "hub.db");
+
+let db: typeof import("./db.js").db;
+let server: ReturnType<typeof Bun.serve>;
+let base = "";
+let token = "";
+let networkId = "";
+
+const INTERNAL_SENTINEL = "future_internal_only";
+const sortedKeys = (value: Record<string, unknown>): string[] => Object.keys(value).sort();
+const sorted = (values: readonly string[]): string[] => [...values].sort();
+
+// Independent wire-contract golden. Do not derive these expectations from
+// rest-projections.ts: doing so makes a deleted projection column disappear
+// from both the response and the expected value, producing a false green.
+const GOLDEN_RESPONSE_KEYS = {
+  networkList: [
+    "network_id", "network_name", "owner_id", "description", "settings",
+    "created_at", "updated_at", "visibility", "max_members", "member_role", "name",
+  ],
+  // 🔴 #1097：GET /api/auth/me 走的是 auth.ts 的 getUserAllNetworks()，
+  //    与 GET /api/networks 的 admin 分支**不是同一条查询**。
+  //    server.ts:985 直接返回原始行，没有 :1166 那个 withNetworkNameAlias，
+  //    所以比 networkList 少一个 "name"。这里逐字写死，不从 rest-projections.ts 推导
+  //    —— 理由见本文件顶部：从投影推导会让被删掉的列同时从响应和期望里消失，产生假绿。
+  authMeNetwork: [
+    "network_id", "network_name", "owner_id", "description", "settings",
+    "created_at", "updated_at", "visibility", "max_members", "member_role",
+  ],
+  networkDetail: [
+    "network_id", "network_name", "owner_id", "description", "settings",
+    "created_at", "updated_at", "visibility", "max_members",
+  ],
+  statusSession: [
+    "resume_id", "alias", "tmux_name", "server", "ip", "hostname", "agent",
+    "project_dir", "version", "status", "task", "output", "progress", "score",
+    "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", "network_id", "registered_at", "updated_at",
+    "node_id", "session_id", "config_path", "channels", "last_seen_at", "model",
+    "external_schedules", "rules_file_capable", "skills_capable", "files_capable", "runtime", "host", "process_telemetry",
+  ],
+  task: [
+    "task_id", "from_node_id", "from_name", "to_node_id", "to_name", "priority",
+    "status", "content", "result", "in_reply_to", "requires_response", "scope",
+    "created_at", "delivered_at", "started_at", "runtime_submitted_at", "consumed_at",
+    "completed_at", "expires_at", "network_id", "parent_task_id", "meta_json",
+    "thread_id", "turn_id",
+  ],
+  audit: [
+    "id", "user_id", "username", "action", "target_type", "target_id", "detail",
+    "ip", "network_id", "created_at",
+  ],
+  taskEvent: [
+    "id", "task_id", "from_status", "to_status", "event_type", "actor", "detail",
+    "created_at", "network_id",
+  ],
+  completion: [
+    "id", "session_name", "task", "result", "artifacts", "score",
+    "duration_minutes", "network_id", "completed_at",
+  ],
+  scheduledTask: [
+    "schedule_id", "network_id", "name", "target_node_id", "target_alias",
+    "task_content", "priority", "schedule_type", "timezone", "overlap_policy",
+    "misfire_policy", "status", "next_run_at", "last_run_at", "revision",
+    "created_at", "updated_at", "schedule",
+  ],
+} as const;
+
+async function api(path: string): Promise<any> {
+  const response = await fetch(`${base}${path}`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  expect(response.status).toBe(200);
+  return response.json();
+}
+
+// 30s 而不是 bun 默认的 5s:这个 hook 跑 register()(KDF)+bootServer(),
+// 本机空载基线 ~620ms,而 2026-08-17 与 2026-08-31 两次 CI 上它被 5s 上限打死
+// (0 pass / 1 fail / Ran 1 test —— 见 #928、#1627)。5247ms 是**被截断的下界**,
+// 不是测量值,所以余量按基线的 ~48x 取,而不是按那个数取。
+beforeAll(async () => {
+  ({ db } = await import("./db.js"));
+  const { register } = await import("./auth.js");
+  const auth = register(`rest_shape_${Date.now()}`, "RestShape-Strong-1!", undefined, "rest-shape");
+  expect(auth.ok).toBe(true);
+  token = auth.token!;
+  networkId = auth.network_id!;
+
+  // Simulate future migrations. Any REST SELECT * silently broadcasts these
+  // columns; every endpoint below must keep them private without needing a
+  // code change when the table grows.
+  for (const table of ["networks", "sessions", "audit_log", "task_events", "tasks", "completions", "scheduled_tasks"]) {
+    db.exec(`ALTER TABLE ${table} ADD COLUMN ${INTERNAL_SENTINEL} TEXT`);
+  }
+
+  db.run(
+    `INSERT INTO sessions (resume_id, alias, status, agent, model, network_id, external_schedules)
+     VALUES ('resume-rest-shape', 'rest-shape-node', 'idle', 'agent-node:codex', 'gpt-shape', ?1, ?2)`,
+    [networkId, JSON.stringify({ observed_at: "2026-08-10T02:00:00.000Z", schedules: [] })],
+  );
+  db.run(
+    `INSERT INTO tasks (task_id, from_name, to_name, status, content, priority, network_id, parent_task_id, meta_json)
+     VALUES ('task-rest-shape', 'sender', 'rest-shape-node', 'delivered', 'shape', 'normal', ?1, 'parent-shape', '{"attachment":true}')`,
+    [networkId],
+  );
+  db.run(
+    `INSERT INTO task_events (task_id, from_status, to_status, actor, detail, network_id)
+     VALUES ('task-rest-shape', 'created', 'delivered', 'shape-test', 'shape', ?1)`,
+    [networkId],
+  );
+  db.run(
+    `INSERT INTO completions (id, session_name, task, result, network_id)
+     VALUES ('completion-rest-shape', 'rest-shape-node', 'shape', 'done', ?1)`,
+    [networkId],
+  );
+  db.run(
+    `INSERT INTO audit_log (user_id, username, action, target_type, target_id, detail, ip, network_id)
+     VALUES ((SELECT owner_id FROM networks WHERE network_id = ?1), 'shape-user', 'shape_action', 'shape', 'shape-id', 'shape', '127.0.0.1', ?1)`,
+    [networkId],
+  );
+  db.run(
+    `INSERT INTO scheduled_tasks
+       (schedule_id, network_id, created_by, name, target_node_id, target_alias,
+        task_content, schedule_type, schedule_json, timezone, next_run_at)
+     VALUES ('schedule-rest-shape', ?1, 'private-user-id', 'shape schedule',
+             'node-rest-shape', 'rest-shape-node', 'shape task', 'interval',
+             '{"type":"interval","every_seconds":3600}', 'UTC', '2099-01-01T00:00:00.000Z')`,
+    [networkId],
+  );
+
+  const mod = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { server?.stop(true); } catch {}
+  try { rmSync(PRIVATE_DB_DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("#311 REST response projections are stable across future ALTER TABLE", () => {
+  test("network list and detail preserve their existing public keys", async () => {
+    const list = await api("/api/networks");
+    const row = list.networks.find((item: any) => item.network_id === networkId);
+    expect(sortedKeys(row)).toEqual(sorted(GOLDEN_RESPONSE_KEYS.networkList));
+    expect(row[INTERNAL_SENTINEL]).toBeUndefined();
+
+    const detail = await api(`/api/networks/${networkId}`);
+    expect(sortedKeys(detail.network)).toEqual(sorted(GOLDEN_RESPONSE_KEYS.networkDetail));
+    expect(detail.network[INTERNAL_SENTINEL]).toBeUndefined();
+  });
+
+  // 🔴 #1097：这条补的是 test647 抓到的一个**真覆盖洞**。
+  //    tests/test647-rest-explicit-columns 的 L3b 变异把 auth.ts 的
+  //    `SELECT ${sqlColumns(NETWORK_REST_COLUMNS, "n")}, nm.role as member_role`
+  //    改成 `SELECT n.*, …`，而**整套测试仍然全绿** —— 因为 getUserAllNetworks()
+  //    只在两处可达：server.ts:985(GET /api/auth/me) 与 server.ts:1165
+  //    (GET /api/networks 的三元 **else** 分支)，而上面那条测试打的是 /api/networks
+  //    且它的用户走 **if** 分支（:1156-1162 的内联查询）⇒ 两条可达路径一条都没覆盖。
+  test("auth/me networks come from an explicit column list, not SELECT *", async () => {
+    const me = await api("/api/auth/me");
+    const row = me.networks.find((item: any) => item.network_id === networkId);
+    expect(row).toBeDefined();
+    expect(sortedKeys(row)).toEqual(sorted(GOLDEN_RESPONSE_KEYS.authMeNetwork));
+    expect(row[INTERNAL_SENTINEL]).toBeUndefined();
+  });
+
+  test("full status preserves telemetry compatibility without storage drift", async () => {
+    const body = await api(`/api/status?network_id=${networkId}`);
+    const row = body.sessions.find((item: any) => item.alias === "rest-shape-node");
+    expect(sortedKeys(row)).toEqual(sorted(GOLDEN_RESPONSE_KEYS.statusSession));
+    expect(row[INTERNAL_SENTINEL]).toBeUndefined();
+    expect(row.external_schedules).toEqual({ observed_at: "2026-08-10T02:00:00.000Z", schedules: [] });
+  });
+
+  test("task list and task detail expose the same explicit contract", async () => {
+    const list = await api(`/api/tasks?network_id=${networkId}&task_id=task-rest-shape&skip_stats=1`);
+    expect(sortedKeys(list.tasks[0])).toEqual(sorted(GOLDEN_RESPONSE_KEYS.task));
+    expect(list.tasks[0][INTERNAL_SENTINEL]).toBeUndefined();
+
+    const detail = await api(`/api/tasks/task-rest-shape?network_id=${networkId}`);
+    expect(sortedKeys(detail.task)).toEqual(sorted(GOLDEN_RESPONSE_KEYS.task));
+    expect(detail.task[INTERNAL_SENTINEL]).toBeUndefined();
+  });
+
+  test("audit, task-event, and completion rows are explicit", async () => {
+    const audit = await api("/api/audit-log?action=shape_action");
+    expect(sortedKeys(audit.logs[0])).toEqual(sorted(GOLDEN_RESPONSE_KEYS.audit));
+    expect(audit.logs[0][INTERNAL_SENTINEL]).toBeUndefined();
+
+    const events = await api(`/api/task_events?network_id=${networkId}&task_id=task-rest-shape`);
+    expect(sortedKeys(events.events[0])).toEqual(sorted(GOLDEN_RESPONSE_KEYS.taskEvent));
+    expect(events.events[0][INTERNAL_SENTINEL]).toBeUndefined();
+
+    const completions = await api(`/api/completions?network_id=${networkId}&since=2000-01-01T00:00:00.000Z`);
+    expect(sortedKeys(completions.completions[0])).toEqual(sorted(GOLDEN_RESPONSE_KEYS.completion));
+    expect(completions.completions[0][INTERNAL_SENTINEL]).toBeUndefined();
+  });
+
+  test("scheduled-task decoding keeps storage-only identity and JSON private", async () => {
+    const body = await api(`/api/scheduled-tasks?network_id=${networkId}`);
+    const row = body.schedules.find((item: any) => item.schedule_id === "schedule-rest-shape");
+    expect(sortedKeys(row)).toEqual(sorted(GOLDEN_RESPONSE_KEYS.scheduledTask));
+    expect(row.created_by).toBeUndefined();
+    expect(row.schedule_json).toBeUndefined();
+    expect(row[INTERNAL_SENTINEL]).toBeUndefined();
+  });
+});