@sleep2agi/commhub-server 0.9.0-preview.29 → 0.9.0-preview.30

package/README.md

@@ -11,6 +11,23 @@ The supported path is to install the `anet` CLI (`@sleep2agi/agent-network`) and
 
 ## Quick start (verified)
 
+> ⚠️ **Do not run `bunx @sleep2agi/commhub-server` without a version**
+> Without a version this resolves to the npm `latest` dist-tag, and **`latest` is currently `0.8.8` (published 2026-06-24)**.
+> 
+> On `0.8.8` an anonymous `GET /health` **returns the `{networkId}:{alias}` of every live SSE connection** — no token required.
+> The redaction fix is [`7bacb729`](https://github.com/sleep2agi/agent-network/commit/7bacb729) (`security(#473)`, **2026-07-29**),
+> **35 days after** `0.8.8` shipped, so `0.8.8` does not contain it.
+> 
+> **Pin a version, or use the preview channel:**
+> 
+> ```bash
+> bunx --bun @sleep2agi/commhub-server@preview      # contains the redaction fix
+> ```
+> 
+> Or use the supported path, `anet hub start`, which pulls the version in `PINNED_SERVER_VERSION` rather than `latest`.
+> 
+> Self-check: `curl -sS http://<host>:9200/health | jq 'has("sse_sessions")'` — `true` means you are on an affected build.
+
 ```bash
 # Recommended — through the anet CLI
 npm install -g @sleep2agi/agent-network
@@ -74,6 +91,8 @@ authoritative. Pinning versions here goes stale on every release and nobody come
 | `list_tasks` | Task list, filterable by `network_id` |
 | `get_completions` | Completion history |
 
+> The table above lists the 17 **collaboration-core** tools. Node lifecycle / provider ops tools ship on the same MCP surface — the authoritative full list is [docs-site/docs/api/mcp-tools.md](../docs-site/docs/api/mcp-tools.md). Don't read the count above as "17 tools total".
+
 ## REST API
 
 The server exposes ~33 endpoints across health, auth, networks, and observability surfaces. The endpoints in use today by the verified flow are:
@@ -149,6 +168,102 @@ DATABASE_URL=postgres://user:pass@host:5432/commhub bunx @sleep2agi/commhub-serv
 | `COMMHUB_DB` | `~/.commhub/commhub.db` | SQLite path |
 | `DATABASE_URL` | (none) | switches to PostgreSQL when set (unverified) |
 
+## Running the unit tests
+
+### 先说该走哪条路:Docker
+
+仓库规约是测试在 Docker 里跑(`CLAUDE.md`「所有测试在 Docker 里跑:不碰本地
+环境,不改生产」)。`server/src` 的测试在 `tests/` 下已经有 **24 个**按主题分片的
+套件覆盖(实测:遍历 main 上 204 个套件目录,run.sh 里跑 `server/src/*.test.ts`
+的有 24 个),每个都在容器内自带 `COMMHUB_DB`。跑其中任意一个都是这个形状:
+
+```bash
+# 从仓根跑
+docker build --build-arg SOURCE_COMMIT="$(git rev-parse HEAD)" \
+  -t anet-test624 -f tests/test624-task-cursor-pagination/Dockerfile .
+docker run --rm anet-test624
+```
+
+（实跑过:退出码 0,`6 pass / 0 fail`,`RESULT: PASS`。换成 `tests/` 下别的
+`test*-*/Dockerfile` 同理,但 **build-arg 的名字要照抄那个 Dockerfile** ——
+main 上 66 处写的是 `SOURCE_COMMIT`,另有若干写成 `TEST<编号>_SOURCE_COMMIT`
+(如 `TEST686_SOURCE_COMMIT`、`TEST765_SOURCE_COMMIT`)。传错名字不会报错,
+只会让套件收到 `unknown` 然后按它自己的规则红或绿 —— 这不是你想要的那种绿。）
+
+> ⚠️ **目前没有一个套件跑「`server/src` 下的全部」单测。** 上面那些是按主题
+> 分片的;聚合门在 #798 里,尚未合入 main。所以「所有分片套件都绿」**不等于**
+> 69 个单测文件都跑过 —— 在 #798 合入之前,不要把前者当成后者。
+
+### 直接在宿主上跑时的两条契约
+
+下面这两条是上面那些套件在容器内**已经替你满足**的东西。你只有在本地迭代
+单个文件时才需要自己处理它们 —— 而那种跑法不构成任何门禁证据。
+
+
+1. **`COMMHUB_DB` must be set.** It is not optional — `~/.commhub/commhub.db` is a
+   *live* database on any machine that has ever run a hub. This one is enforced:
+   with `NODE_ENV=test` (which `bun test` sets) and no `COMMHUB_DB`, the adapter
+   refuses with `REFUSING to open the default SQLite database`.
+
+2. **Each test *file* needs its own database.** This is *not* enforced — a single
+   shared `COMMHUB_DB` passes the guard above and then fails a handful of tests
+   for reasons that look like product bugs but are not. `scripts/qa.sh` encodes
+   the real contract:
+
+   ```bash
+   # 从仓根跑(见下),每个文件一个全新的库
+   f=server/src/auth-validate.test.ts
+   db=/tmp/anet-$(basename "$f" .test.ts).db
+   rm -f "$db"                       # 复用上一次的库同样会破坏隔离
+   COMMHUB_DB="$db" bun test "$f"
+   ```
+
+   整套跑法:
+
+   ```bash
+   rc=0
+   # 用 find 而不是 `server/src/*.test.ts` —— glob 不进子目录,会漏掉
+   # server/src/shared/ 下的 3 个(实测:深度 1 是 66 个,递归是 69 个)。
+   # scripts/qa.sh 与 test798 用的就是 find,这里保持一致。
+   while IFS= read -r f; do
+     # 用完整路径派生库名,不用 basename:加入子目录之后,
+     # 两个不同目录下的同名文件会派生出同一个库(原来只扫单层时不可能)。
+     db=/tmp/anet-$(printf '%s' "${f%.test.ts}" | tr '/.' '--').db
+     rm -f "$db" "$db-wal" "$db-shm"
+     COMMHUB_DB="$db" bun test "$f" || { echo "FAILED: $f"; rc=1; }
+   done < <(find server/src -type f -name '*.test.ts' | sort)
+   [ "$rc" -eq 0 ]
+   ```
+
+   ⚠️ 最后那行 `[ "$rc" -eq 0 ]` 不是装饰,是这段的**门**。写成
+   `bun test "$f" || echo "FAILED: $f"` 会让循环打印一行然后继续,
+   整段的退出码恒为 0 —— **测试全红,脚本报绿**。用 `[ ... ]` 而不是
+   `exit "$rc"`,是为了这段直接粘进终端时不会把你的 shell 关掉;
+   存成脚本跑时,它是最后一条命令,脚本退出码就等于它。
+
+   ⚠️ 别把 `$name` 之类的占位符原样抄进命令行 —— 未定义的变量会展开成空串,
+   于是每个文件都写进**同一个** `/tmp/…-.db`,正好是这一节要避免的事。
+
+   Symptom if you ignore it: `bun test src/` under one database turns
+   `admin-networks-http` and `scheduled-tasks-http` red. Both are **global-count
+   assertions that are correct under the contract**:
+
+   ```ts
+   // admin-networks-http.test.ts — the admin sees EXACTLY this file's two networks
+   expect(new Set(rows.map((row) => row.network_id)))
+     .toEqual(new Set([adminNetworkId, memberNetworkId]));
+
+   // scheduled-tasks-http.test.ts — EXACTLY one due occurrence was processed
+   expect(runDueScheduledTasks().processed).toBe(1);
+   ```
+
+   Share a database and other files' networks and due schedules join the count.
+   Nothing is broken; the run violated the contract.
+
+   `scripts/qa.sh` 的 L0 目前只点名跑 5 个 server 测试(白名单),不是全量;
+   把 `server/src` 全域逐文件跑起来的那道 CI 门还在评审中(`#798`),
+   未进 `main` —— 所以本节描述的是**契约**,不是「已经有东西在替你执行它」。
+
 ## Auth modes
 
 1. **V3 user system (default)** — `POST /api/auth/register` and `/api/auth/login` issue `utok_…` tokens; nodes get `ntok_…`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.29",
-  "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and 17 MCP tools.",
+  "version": "0.9.0-preview.30",
+  "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and MCP tools (17 collaboration-core + node/provider ops tools; authoritative list: docs-site/docs/api/mcp-tools.md).",
   "type": "module",
   "main": "src/index.ts",
   "bin": {

package/src/alias-filter.test.ts

@@ -0,0 +1,72 @@
+import { expect, test } from "bun:test";
+import { parseAliasFilter } from "./alias-filter";
+
+test("no filter given means no filtering, not an empty match", () => {
+  for (const raw of [undefined, null, "", "   ", ",", " , , "]) {
+    const f = parseAliasFilter(raw as any);
+    expect(f.aliases).toEqual([]);
+    expect(f.sql).toBe("");
+  }
+});
+
+test("a single alias produces one placeholder", () => {
+  const f = parseAliasFilter("TM门户马");
+  expect(f.aliases).toEqual(["TM门户马"]);
+  expect(f.sql).toBe(" AND alias IN (?)");
+});
+
+test("several aliases keep their order and count", () => {
+  const f = parseAliasFilter("A站内容,A站内容牛,hub");
+  expect(f.aliases).toEqual(["A站内容", "A站内容牛", "hub"]);
+  expect(f.sql).toBe(" AND alias IN (?,?,?)");
+});
+
+test("surrounding whitespace is trimmed", () => {
+  expect(parseAliasFilter(" a , b ").aliases).toEqual(["a", "b"]);
+});
+
+// The point of the module. A trailing comma must not become `alias = ''`,
+// which matches nothing and reads exactly like "those nodes do not exist".
+test("blank entries are dropped, never turned into a match-nothing term", () => {
+  const f = parseAliasFilter("a,,b,");
+  expect(f.aliases).toEqual(["a", "b"]);
+  expect(f.sql).toBe(" AND alias IN (?,?)");
+  expect(f.aliases).not.toContain("");
+});
+
+test("a filter of only commas is the same as no filter — it must not silently match zero rows", () => {
+  const f = parseAliasFilter(",,,");
+  expect(f.sql).toBe("");
+});
+
+test("placeholder count always equals alias count, so params can never misalign", () => {
+  for (const raw of ["a", "a,b", "a,,b", " a , b , c ", ",x,"]) {
+    const f = parseAliasFilter(raw);
+    expect((f.sql.match(/\?/g) ?? []).length).toBe(f.aliases.length);
+  }
+});
+
+test("aliases are passed through verbatim — no globbing, no case folding", () => {
+  const f = parseAliasFilter("A站内容,a站内容");
+  expect(f.aliases).toEqual(["A站内容", "a站内容"]);
+  expect(f.sql).not.toContain("LIKE");
+});
+
+// Wiring: the tool must actually use this module, and must say what its
+// `summary` counted — a caller who asked about three aliases and gets back
+// "idle: 96" can easily read the 96 as being about their three.
+import { readFileSync } from "fs";
+import { join } from "path";
+
+test("get_all_status uses parseAliasFilter and declares what summary counted", () => {
+  const source = readFileSync(join(import.meta.dir, "tools.ts"), "utf8");
+  const a = source.indexOf('"get_all_status"');
+  expect(a).toBeGreaterThan(-1);
+  const body = source.slice(a, source.indexOf('server.tool(', a + 10));
+  expect(body).toContain("filter_alias");
+  expect(body).toContain("parseAliasFilter(filter_alias)");
+  expect(body).toContain("summary_scope");
+  expect(body).toContain("sessions_returned");
+  // The alias list must go through parameters, never be interpolated.
+  expect(body).not.toMatch(/alias IN \(\$\{/);
+});

package/src/alias-filter.ts

@@ -0,0 +1,32 @@
+// Parse the `filter_alias` argument of `get_all_status` into an exact-match
+// IN list.
+//
+// Why this exists at all: on a 222-session hub the unfiltered response is about
+// 259 KB — past what an MCP client accepts in one result. A caller who wanted
+// the status of three specific nodes could not get it from the tool, and had to
+// go around it to the REST API. The filter is the fix; this module is the part
+// of it worth pinning, because the interesting behaviour is what happens to the
+// inputs that are not a clean alias.
+//
+// Blank entries are DROPPED rather than matched. A trailing comma would
+// otherwise produce `alias = ''`, which matches no row — and "no rows" reads
+// exactly like "those nodes do not exist". The failure and the true answer
+// would be indistinguishable to the caller, which is the thing to avoid.
+
+export interface AliasFilter {
+  /** Exact aliases to match. Empty means "no alias filtering". */
+  aliases: string[];
+  /** SQL fragment to append, or "" when there is nothing to filter on. */
+  sql: string;
+}
+
+export function parseAliasFilter(raw: string | undefined | null): AliasFilter {
+  const aliases = (raw ?? "")
+    .split(",")
+    .map(a => a.trim())
+    .filter(Boolean);
+  return {
+    aliases,
+    sql: aliases.length > 0 ? ` AND alias IN (${aliases.map(() => "?").join(",")})` : "",
+  };
+}

package/src/db.ts

@@ -1101,6 +1101,71 @@ try { db.exec("ALTER TABLE tasks ADD COLUMN meta_json TEXT"); } catch {}
 try { db.exec("ALTER TABLE tasks ADD COLUMN runtime_submitted_at TEXT"); } catch {}
 try { db.exec("ALTER TABLE tasks ADD COLUMN consumed_at TEXT"); } catch {}
 
+// #1181 durable outbound terminal cursor.  A task's created_at cannot be used
+// as a recovery watermark because an old task may become terminal after newer
+// tasks.  Record terminal transitions in their own monotonically increasing
+// journal instead.  The journal is append-only for a logical task; retry keeps
+// the existing task identity and therefore the same idempotency domain.
+db.exec(`
+  CREATE TABLE IF NOT EXISTS task_terminal_events (
+    terminal_seq INTEGER PRIMARY KEY AUTOINCREMENT,
+    task_id TEXT NOT NULL UNIQUE,
+    network_id TEXT,
+    from_node_id TEXT,
+    completed_at TEXT NOT NULL DEFAULT (datetime('now'))
+  );
+  CREATE INDEX IF NOT EXISTS idx_task_terminal_events_sender_seq
+    ON task_terminal_events(network_id, from_node_id, terminal_seq);
+`);
+if (db.dialect === "sqlite") {
+  db.exec(`
+    CREATE TRIGGER IF NOT EXISTS tasks_terminal_event_insert
+    AFTER INSERT ON tasks
+    WHEN NEW.status IN ('replied', 'failed', 'cancelled', 'expired')
+    BEGIN
+      INSERT OR IGNORE INTO task_terminal_events (task_id, network_id, from_node_id, completed_at)
+      VALUES (NEW.task_id, NEW.network_id, NEW.from_node_id, COALESCE(NEW.completed_at, datetime('now')));
+    END;
+    CREATE TRIGGER IF NOT EXISTS tasks_terminal_event_update
+    AFTER UPDATE OF status ON tasks
+    WHEN NEW.status IN ('replied', 'failed', 'cancelled', 'expired')
+      AND OLD.status NOT IN ('replied', 'failed', 'cancelled', 'expired')
+    BEGIN
+      INSERT OR IGNORE INTO task_terminal_events (task_id, network_id, from_node_id, completed_at)
+      VALUES (NEW.task_id, NEW.network_id, NEW.from_node_id, COALESCE(NEW.completed_at, datetime('now')));
+    END;
+  `);
+  db.run(`INSERT OR IGNORE INTO task_terminal_events (task_id, network_id, from_node_id, completed_at)
+          SELECT task_id, network_id, from_node_id, COALESCE(completed_at, created_at)
+            FROM tasks
+           WHERE status IN ('replied', 'failed', 'cancelled', 'expired')
+           ORDER BY COALESCE(completed_at, created_at), task_id`);
+} else {
+  db.exec(`
+    CREATE OR REPLACE FUNCTION record_task_terminal_event() RETURNS trigger AS $$
+    BEGIN
+      IF NEW.status IN ('replied', 'failed', 'cancelled', 'expired')
+         AND (TG_OP = 'INSERT' OR OLD.status NOT IN ('replied', 'failed', 'cancelled', 'expired')) THEN
+        INSERT INTO task_terminal_events (task_id, network_id, from_node_id, completed_at)
+        VALUES (NEW.task_id, NEW.network_id, NEW.from_node_id, COALESCE(NEW.completed_at, NOW()))
+        ON CONFLICT (task_id) DO NOTHING;
+      END IF;
+      RETURN NEW;
+    END;
+    $$ LANGUAGE plpgsql;
+    DROP TRIGGER IF EXISTS tasks_terminal_event_insert ON tasks;
+    DROP TRIGGER IF EXISTS tasks_terminal_event_update ON tasks;
+    CREATE TRIGGER tasks_terminal_event_insert AFTER INSERT ON tasks
+      FOR EACH ROW EXECUTE FUNCTION record_task_terminal_event();
+    CREATE TRIGGER tasks_terminal_event_update AFTER UPDATE OF status ON tasks
+      FOR EACH ROW EXECUTE FUNCTION record_task_terminal_event();
+    INSERT INTO task_terminal_events (task_id, network_id, from_node_id, completed_at)
+    SELECT task_id, network_id, from_node_id, COALESCE(completed_at, created_at)
+      FROM tasks WHERE status IN ('replied', 'failed', 'cancelled', 'expired')
+    ON CONFLICT (task_id) DO NOTHING;
+  `);
+}
+
 // ── Hub scheduled tasks ──────────────────────────────────────────────
 // Scheduling is a Hub concern: clients manage these rows, while agents only
 // receive the ordinary inbox/tasks rows produced for each occurrence.  Keep

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/rest-explicit-columns-http.test.ts

@@ -2,15 +2,6 @@ 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";
-import {
-  AUDIT_LOG_REST_COLUMNS,
-  COMPLETION_REST_COLUMNS,
-  NETWORK_REST_COLUMNS,
-  SESSION_REST_COLUMNS,
-  TASK_EVENT_REST_COLUMNS,
-  TASK_REST_COLUMNS,
-  SCHEDULED_TASK_STORAGE_COLUMNS,
-} from "./rest-projections.js";
 
 const PRIVATE_DB_DIR = mkdtempSync(join(tmpdir(), "anet-rest-columns-"));
 process.env.COMMHUB_DB ||= join(PRIVATE_DB_DIR, "hub.db");
@@ -25,6 +16,63 @@ 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", "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",
+  ],
+  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}` },
@@ -97,51 +145,65 @@ 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([...NETWORK_REST_COLUMNS, "member_role", "name"]));
+    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(NETWORK_REST_COLUMNS));
+    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([...SESSION_REST_COLUMNS, "runtime", "host", "process_telemetry"]));
+    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(TASK_REST_COLUMNS));
+    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(TASK_REST_COLUMNS));
+    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(AUDIT_LOG_REST_COLUMNS));
+    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(TASK_EVENT_REST_COLUMNS));
+    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(COMPLETION_REST_COLUMNS));
+    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");
-    const publicColumns = SCHEDULED_TASK_STORAGE_COLUMNS.filter((key) => key !== "created_by" && key !== "schedule_json");
-    expect(sortedKeys(row)).toEqual(sorted([...publicColumns, "schedule"]));
+    expect(sortedKeys(row)).toEqual(sorted(GOLDEN_RESPONSE_KEYS.scheduledTask));
     expect(row.created_by).toBeUndefined();
     expect(row.schedule_json).toBeUndefined();
     expect(row[INTERNAL_SENTINEL]).toBeUndefined();

package/src/rest-identity.test.ts

@@ -60,7 +60,16 @@ describe("REST from_session identity binding", () => {
     })).toEqual({ ok: true, fromSession: "admin" });
   });
 
-  test("user token with no from still defaults to 'api'", () => {
+  test("user token with no from defaults to the authenticated username", () => {
+    expect(resolveRestFromSession({
+      token: UTOK,
+      tokenName: null,
+      authenticatedUsername: "admin",
+      requestedFrom: undefined,
+    })).toEqual({ ok: true, fromSession: "admin" });
+  });
+
+  test("legacy user auth without a username still falls back to 'api'", () => {
     expect(resolveRestFromSession({
       token: UTOK,
       tokenName: null,

package/src/rest-identity.ts

@@ -21,6 +21,8 @@ export interface RestIdentityInput {
   token: string;
   /** `api_tokens.name`; for node tokens it is `node:<alias>`. */
   tokenName: string | null | undefined;
+  /** Username resolved from the authenticated token. */
+  authenticatedUsername?: string | null;
   /** Caller-supplied `body.from`. */
   requestedFrom: unknown;
 }
@@ -69,11 +71,16 @@ export function resolveRestFromSession(input: RestIdentityInput): RestIdentityRe
     return { ok: true, fromSession: "api" };
   }
 
-  // Not a node token: unchanged behaviour. The Dashboard legitimately posts as
-  // its logged-in user; tightening that is a separate change with its own
-  // compatibility surface.
+  // A user-token client normally does not need to repeat its identity in every
+  // request. Prefer an explicit, backwards-compatible claim when present;
+  // otherwise attribute the task to the authenticated username. Falling back
+  // to the transport label `api` is reserved for legacy auth contexts where
+  // the server genuinely has no user identity.
   if (!alias) {
-    return { ok: true, fromSession: requested || "api" };
+    const authenticatedUsername = typeof input.authenticatedUsername === "string"
+      ? input.authenticatedUsername.trim()
+      : "";
+    return { ok: true, fromSession: requested || authenticatedUsername || "api" };
   }
 
   // Node token claiming somebody else — refuse rather than silently rewrite,