@sleep2agi/commhub-server 0.9.0-preview.72 → 0.9.0-preview.73

package/bin/commhub.ts

@@ -12,19 +12,56 @@
 
 const args = process.argv.slice(2);
 
-for (let i = 0; i < args.length; i++) {
-  if (args[i] === "--port" || args[i] === "-p") process.env.PORT = args[++i];
-  if (args[i] === "--host") process.env.HOST = args[++i];
-  if (args[i] === "--token" || args[i] === "-t") process.env.COMMHUB_AUTH_TOKEN = args[++i];
-  if (args[i] === "--db") process.env.COMMHUB_DB = args[++i];
-  if (args[i] === "--cors") process.env.COMMHUB_CORS_ORIGINS = args[++i];
-  if (args[i] === "--dev-open") process.env.COMMHUB_DEV_OPEN = "1";
-  if (args[i] === "--help" || args[i] === "-h") {
+// RFC-039 S5 — offline SQLite → PostgreSQL copy. Handled before any server
+// option parsing: it never starts a Hub and never opens the default database.
+if (args[0] === "migrate-to-pg") {
+  const flag = (name: string) => args.includes(name);
+  const value = (name: string) => { const i = args.indexOf(name); return i > 0 ? args[i + 1] : undefined; };
+  const MIGRATE_VALUE_FLAGS = new Set(["--from", "--to"]);
+  const MIGRATE_FLAGS = new Set(["--dry-run", "--i-know-this-is-a-copy", "--help", "-h"]);
+  for (let i = 1; i < args.length; i++) {
+    if (MIGRATE_VALUE_FLAGS.has(args[i])) { i++; continue; }
+    if (!MIGRATE_FLAGS.has(args[i])) {
+      console.error(`commhub-server migrate-to-pg: unknown argument ${args[i]}\nRun "commhub-server migrate-to-pg --help" for usage.`);
+      process.exit(2);
+    }
+  }
+  if (flag("--help") || flag("-h") || !value("--from") || !value("--to")) {
     console.log(`
+Usage:
+  commhub-server migrate-to-pg --from <sqlite file> --to <postgres url> [--dry-run] [--i-know-this-is-a-copy]
+
+Copies a stopped Hub's SQLite database into an EMPTY PostgreSQL database, in one
+transaction, verifying per-table row counts and content hashes before COMMIT.
+Experimental (RFC-039); available from commhub-server 0.9.0-preview.73.
+Files under the uploads directory are not copied.
+
+  --dry-run                 do everything, then roll back and leave the target empty
+  --i-know-this-is-a-copy   allow a source under ~/.commhub (refused by default)
+`);
+    process.exit(flag("--help") || flag("-h") ? 0 : 2);
+  }
+  const { migrateSqliteToPg, MigrateRefused } = await import("../src/migrate-sqlite-to-pg.ts");
+  try {
+    await migrateSqliteToPg({
+      from: value("--from")!,
+      to: value("--to")!,
+      dryRun: flag("--dry-run"),
+      allowCommhubCopy: flag("--i-know-this-is-a-copy"),
+    });
+    process.exit(0);
+  } catch (error) {
+    console.error(error instanceof MigrateRefused ? error.message : `[migrate-to-pg] FAILED, rolled back: ${(error as Error)?.message ?? error}`);
+    process.exit(error instanceof MigrateRefused ? 2 : 1);
+  }
+}
+
+const HELP = `
 CommHub MCP Server — AI Agent 通信中枢
 
 Usage:
   commhub-server [options]
+  commhub-server migrate-to-pg --help    Copy a stopped Hub's SQLite database into PostgreSQL (experimental)
 
 Options:
   --port, -p <port>       Port to listen on (default: 9200, env: PORT)
@@ -34,6 +71,7 @@ Options:
   --cors <origins>        CORS origins, comma-separated (env: COMMHUB_CORS_ORIGINS)
   --dev-open              Explicit unauthenticated local development mode
   --help, -h              Show this help
+  --version, -v           Print the version and exit
 
 Environment Variables:
   PORT                    Server port (default: 9200)
@@ -49,8 +87,43 @@ Examples:
   commhub-server --port 9200 --token my-secret-token
   commhub-server --port 9200 --dev-open
   PORT=9200 COMMHUB_AUTH_TOKEN=secret commhub-server
-`);
+`;
+
+// Anything this bin does not recognise is a usage error: exit 2 and never
+// start a Hub. Before this, unknown words and flags were ignored and a Hub
+// started on the defaults — `commhub-server <some-subcommand>` on a version
+// without that subcommand opened ~/.commhub/commhub.db on :9200.
+function usageError(message: string): never {
+  console.error(`commhub-server: ${message}\nRun "commhub-server --help" for usage.`);
+  process.exit(2);
+}
+
+const VALUE_FLAGS: Record<string, string> = {
+  "--port": "PORT", "-p": "PORT",
+  "--host": "HOST",
+  "--token": "COMMHUB_AUTH_TOKEN", "-t": "COMMHUB_AUTH_TOKEN",
+  "--db": "COMMHUB_DB",
+  "--cors": "COMMHUB_CORS_ORIGINS",
+};
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (Object.hasOwn(VALUE_FLAGS, arg)) {
+    const value = args[i + 1];
+    if (value === undefined || value.startsWith("--")) usageError(`${arg} needs a value`);
+    process.env[VALUE_FLAGS[arg]] = value;
+    i++;
+  } else if (arg === "--dev-open") {
+    process.env.COMMHUB_DEV_OPEN = "1";
+  } else if (arg === "--help" || arg === "-h") {
+    console.log(HELP);
+    process.exit(0);
+  } else if (arg === "--version" || arg === "-v") {
+    const pkg = (await import("../package.json", { with: { type: "json" } })).default as { version: string };
+    console.log(pkg.version);
     process.exit(0);
+  } else {
+    usageError(arg.startsWith("-") ? `unknown option ${arg}` : `unknown command ${arg}`);
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.72",
+  "version": "0.9.0-preview.73",
   "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",

package/src/agent-acl-http.test.ts

@@ -255,7 +255,7 @@ describe("humans: restricted members can still see and DM other humans", () => {
     const r = await get(aliceToken, `/api/networks/${NET}/humans`);
     expect(r.status).toBe(200);
     expect(r.body.humans.map((h: any) => h.user_id).sort()).toEqual([adminId, aliceId, bobId].sort());
-    expect(Object.keys(r.body.humans[0]).sort()).toEqual(["display_name", "user_id", "username"]);
+    expect(Object.keys(r.body.humans[0]).sort()).toEqual(["display_name", "last_seen_at", "online", "user_id", "username"]);
     // 非成员拿不到。
     const outsider = register(`acl_out_${Date.now()}`, PW);
     expect((await get(outsider.token!, `/api/networks/${NET}/humans`)).status).toBe(403);

package/src/commhub-bin-args.test.ts

@@ -0,0 +1,85 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// commhub-server must refuse what it does not understand instead of starting a
+// Hub on the defaults (the live ~/.commhub/commhub.db). Every child gets a
+// throwaway HOME and a throwaway PORT, so even a regression binds nothing real.
+const BIN = join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "commhub.ts");
+const PKG_VERSION = JSON.parse(readFileSync(join(dirname(BIN), "..", "package.json"), "utf8")).version as string;
+const home = mkdtempSync(join(tmpdir(), "anet-bin-args-"));
+const PORT = String(26000 + Math.floor(Math.random() * 3000));
+
+afterAll(() => rmSync(home, { recursive: true, force: true }));
+
+function run(args: string[], extraEnv: Record<string, string> = {}, timeoutMs = 15_000) {
+  const proc = Bun.spawnSync(["bun", BIN, ...args], {
+    env: { PATH: process.env.PATH ?? "", HOME: home, PORT, HOST: "127.0.0.1", ...extraEnv },
+    stdout: "pipe", stderr: "pipe", timeout: timeoutMs,
+  });
+  return { code: proc.exitCode, stdout: proc.stdout.toString(), stderr: proc.stderr.toString() };
+}
+
+async function listening(port: string): Promise<boolean> {
+  try { await fetch(`http://127.0.0.1:${port}/health`, { signal: AbortSignal.timeout(500) }); return true; } catch { return false; }
+}
+
+describe("commhub-server argument handling", () => {
+  for (const [args, message] of [
+    [["bogus"], "unknown command bogus"],
+    [["--port=29999"], "unknown option --port=29999"],
+    [["--bogus-flag"], "unknown option --bogus-flag"],
+    [["--port"], "--port needs a value"],
+    [["--db", "--dev-open"], "--db needs a value"],
+  ] as const) {
+    test(`${args.join(" ")} → exit 2, no database, nothing listening`, async () => {
+      const r = run([...args]);
+      expect(r.code).toBe(2);
+      expect(r.stderr).toContain(message);
+      expect(r.stderr).toContain("commhub-server --help");
+      expect(existsSync(join(home, ".commhub"))).toBe(false);
+      expect(await listening(PORT)).toBe(false);
+    });
+  }
+
+  test("migrate-to-pg with missing or unknown arguments exits 2 and starts nothing", async () => {
+    const missing = run(["migrate-to-pg", "--from", "/x.db"]);
+    expect(missing.code).toBe(2);
+    expect(missing.stdout).toContain("commhub-server migrate-to-pg --from <sqlite file> --to <postgres url>");
+    const unknown = run(["migrate-to-pg", "--from", "/x.db", "--to", "postgres://u@127.0.0.1/anet_x_test", "--bogus"]);
+    expect(unknown.code).toBe(2);
+    expect(unknown.stderr).toContain("unknown argument --bogus");
+    expect(existsSync(join(home, ".commhub"))).toBe(false);
+    expect(await listening(PORT)).toBe(false);
+  });
+
+  test("--help and --version exit 0 without starting", async () => {
+    const help = run(["--help"]);
+    expect(help.code).toBe(0);
+    expect(help.stdout).toContain("--port, -p <port>");
+    const version = run(["--version"]);
+    expect(version.code).toBe(0);
+    expect(version.stdout.trim()).toBe(PKG_VERSION);
+    expect(existsSync(join(home, ".commhub"))).toBe(false);
+  });
+
+  test("the known forms still start a Hub", async () => {
+    const db = join(home, "known.db");
+    const port = String(Number(PORT) + 1);
+    const child = Bun.spawn(["bun", BIN, "--port", port, "--host", "127.0.0.1", "--db", db, "--dev-open"], {
+      env: { PATH: process.env.PATH ?? "", HOME: home }, stdout: "pipe", stderr: "pipe",
+    });
+    try {
+      let up = false;
+      for (let i = 0; i < 100 && !up; i++) { up = await listening(port); if (!up) await Bun.sleep(100); }
+      expect(up).toBe(true);
+      expect(existsSync(db)).toBe(true);
+      expect(existsSync(join(home, ".commhub", "commhub.db"))).toBe(false);
+    } finally {
+      child.kill();
+      await child.exited;
+    }
+  }, 30_000);
+});

package/src/db-adapter-translate.test.ts

@@ -38,6 +38,11 @@ describe("RFC-039 S2a sqliteToPostgres", () => {
     expect(sqliteToPostgres("CAST(x AS INTEGER)")).toBe("CAST(x AS BIGINT)");
   });
 
+  test("REAL → DOUBLE PRECISION (SQLite REAL is 8-byte), identifiers containing real untouched", () => {
+    expect(sqliteToPostgres("mem_used_gb REAL, realm TEXT")).toBe("mem_used_gb DOUBLE PRECISION, realm TEXT");
+    expect(sqliteToPostgres("CAST(x AS REAL)")).toBe("CAST(x AS DOUBLE PRECISION)");
+  });
+
   test("BLOB → BYTEA, identifiers containing blob untouched", () => {
     expect(sqliteToPostgres("iv BLOB NOT NULL, blob_ref TEXT")).toBe("iv BYTEA NOT NULL, blob_ref TEXT");
   });

package/src/db-adapter.ts

@@ -90,6 +90,17 @@ export class SQLiteAdapter implements DbAdapter {
   }
 
   close(): void {
+    // #2151: once more than 20 distinct SQL strings have gone through query(),
+    // bun:sqlite's close() can no longer really close the connection (measured:
+    // close(true) reports "database is locked"), so SQLite never checkpoints and
+    // a cleanly stopped Hub left its latest writes in -wal. Checkpoint first,
+    // so the .db file alone is complete after a clean stop.
+    try {
+      const r = this.rawDb.query<{ busy: number; log: number; checkpointed: number }, []>("PRAGMA wal_checkpoint(TRUNCATE)").get();
+      if (r && r.busy !== 0) console.warn(`[commhub] WAL checkpoint on close was busy: ${JSON.stringify(r)}`);
+    } catch (e) {
+      console.warn(`[commhub] WAL checkpoint on close failed: ${(e as Error)?.message ?? e}`);
+    }
     this.rawDb.close();
   }
 }
@@ -140,6 +151,9 @@ export function sqliteToPostgres(sql: string): string {
   // INTEGER → BIGINT: SQLite integers are 64-bit, and the Hub stores epoch
   // milliseconds in INTEGER columns (a 32-bit PG integer overflows).
   s = s.replace(/\bINTEGER\b/gi, "BIGINT");
+  // REAL → DOUBLE PRECISION: SQLite REAL is 8-byte; PostgreSQL REAL is 4-byte
+  // and would silently round telemetry and scores.
+  s = s.replace(/\bREAL\b/gi, "DOUBLE PRECISION");
   // BLOB → BYTEA
   s = s.replace(/\bBLOB\b/gi, "BYTEA");
   return s;

package/src/member-presence-http.test.ts

@@ -0,0 +1,206 @@
+// 人员列表的在线状态 —— HTTP 集成测试(真实 Bun.serve,私有端口,临时库)。
+//
+// GET /api/networks/:id/humans 给每个人加 online / last_seen_at(判据 = 此刻有没有活着的用户流
+// /events/users/me);用户流上推 member_presence。两个方向都测:
+//   看得到:普通成员、受限成员、viewer;连上 → online=true,断开 → online=false + last_seen_at。
+//   看不到:非成员 403;节点令牌拿到的仍是原来三个身份字段;别的网络的人收不到推送;自己收不到自己的。
+
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { register } from "./auth.js";
+import { db, hashToken, generateNetworkToken, generateId } from "./db.js";
+
+const DIR = mkdtempSync(join(tmpdir(), "anet-member-presence-"));
+let BASE = "";
+let hub: any = null;
+
+const PW = "PresenceTestPassw0rd!x";
+let ownerToken = "";
+let NET = "";
+const users: Record<string, { token: string; userId: string }> = {};
+let nodeToken = "";
+
+const auth = (token: string) => ({ Authorization: `Bearer ${token}` });
+
+async function get(token: string, path: string): Promise<{ status: number; body: any }> {
+  const res = await fetch(`${BASE}${path}`, { headers: auth(token) });
+  const text = await res.text();
+  let body: any = text;
+  try { body = JSON.parse(text); } catch {}
+  return { status: res.status, body };
+}
+async function post(token: string, path: string, payload: unknown): Promise<{ status: number; body: any }> {
+  const res = await fetch(`${BASE}${path}`, { method: "POST", headers: { ...auth(token), "Content-Type": "application/json" }, body: JSON.stringify(payload) });
+  const text = await res.text();
+  let body: any = text;
+  try { body = JSON.parse(text); } catch {}
+  return { status: res.status, body };
+}
+async function login(username: string): Promise<{ token: string; userId: string }> {
+  const r = await post("", "/api/auth/login", { username, password: PW });
+  expect(r.status).toBe(200);
+  return { token: r.body.token, userId: r.body.user.user_id };
+}
+
+/** 一条用户流:收集 data: 帧,close() 模拟 app 退出。 */
+async function openUserStream(token: string, networkId: string) {
+  const ctrl = new AbortController();
+  const res = await fetch(`${BASE}/events/users/me?network_id=${encodeURIComponent(networkId)}`, { headers: auth(token), signal: ctrl.signal });
+  expect(res.status).toBe(200);
+  const events: any[] = [];
+  const reader = res.body!.getReader();
+  const decoder = new TextDecoder();
+  let buf = "";
+  void (async () => {
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buf += decoder.decode(value);
+        let i: number;
+        while ((i = buf.indexOf("\n\n")) >= 0) {
+          const frame = buf.slice(0, i);
+          buf = buf.slice(i + 2);
+          for (const line of frame.split("\n")) if (line.startsWith("data: ")) events.push(JSON.parse(line.slice(6)));
+        }
+      }
+    } catch { /* aborted */ }
+  })();
+  await waitFor(() => events.some((e) => e.type === "connected"));
+  return { events, close: () => ctrl.abort(), presence: () => events.filter((e) => e.type === "member_presence") };
+}
+
+async function waitFor(cond: () => boolean | Promise<boolean>, ms = 3000): Promise<void> {
+  const until = Date.now() + ms;
+  while (Date.now() < until) {
+    if (await cond()) return;
+    await new Promise((r) => setTimeout(r, 20));
+  }
+  throw new Error("waitFor timed out");
+}
+
+const humanOf = async (token: string, userId: string) =>
+  (await get(token, `/api/networks/${NET}/humans`)).body.humans.find((h: any) => h.user_id === userId);
+
+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 owner = register(`pres_owner_${Date.now()}`, PW, undefined, "Owner");
+  expect(owner.ok).toBe(true);
+  ownerToken = owner.token!;
+  NET = owner.network_id!;
+  db.run("UPDATE users SET role = 'admin' WHERE user_id = ?1", [owner.user!.user_id]);
+  users.owner = { token: ownerToken, userId: owner.user!.user_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}`;
+
+  // 受限成员(默认 agent_access=granted)、viewer、普通成员;外人自己一个网络。
+  for (const [name, role] of [["pres_alpha", "member"], ["pres_beta", "member"], ["pres_gamma", "viewer"]] as const) {
+    const r = await post(ownerToken, "/api/admin/users", { username: name, password: PW, network_id: NET, role });
+    expect(r.status).toBe(200);
+    users[name] = await login(name);
+  }
+  const outsider = register(`pres_out_${Date.now()}`, PW);
+  expect(outsider.ok).toBe(true);
+  users.outsider = { token: outsider.token!, userId: outsider.user!.user_id };
+  users.outsider_net = { token: outsider.token!, userId: outsider.network_id! };
+
+  nodeToken = generateNetworkToken();
+  db.run("INSERT INTO api_tokens (token_id, token_hash, user_id, network_id, name, scope) VALUES (?1, ?2, ?3, ?4, 'pres-node', 'network')",
+    [generateId("tok"), hashToken(nodeToken), users.owner.userId, NET]);
+}, 30_000);
+
+afterAll(() => {
+  try { hub?.stop?.(true); } catch {}
+  try { rmSync(DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("GET /api/networks/:id/humans — online / last_seen_at", () => {
+  test("never connected since hub start → online=false, last_seen_at=null (unknown, not 'long ago')", async () => {
+    const r = await get(users.pres_alpha.token, `/api/networks/${NET}/humans`);
+    expect(r.status).toBe(200);
+    expect(Object.keys(r.body.humans[0]).sort()).toEqual(["display_name", "last_seen_at", "online", "user_id", "username"]);
+    const beta = r.body.humans.find((h: any) => h.user_id === users.pres_beta.userId);
+    expect(beta.online).toBe(false);
+    expect(beta.last_seen_at).toBeNull();
+  });
+
+  test("user stream open → online for member, restricted member and viewer; closed → offline with last_seen_at", async () => {
+    const watcher = await openUserStream(users.pres_alpha.token, NET);
+    const before = Date.now();
+    const beta = await openUserStream(users.pres_beta.token, NET);
+
+    for (const viewer of ["pres_alpha", "pres_gamma", "owner"]) {
+      const h = await humanOf(users[viewer].token, users.pres_beta.userId);
+      expect(h.online).toBe(true);
+      expect(Date.parse(h.last_seen_at)).toBeGreaterThanOrEqual(before - 1000);
+    }
+    // 推送:alpha 收到 beta 上线;beta 收不到自己的。
+    await waitFor(() => watcher.presence().some((e) => e.member_user_id === users.pres_beta.userId && e.online === true));
+    const up = watcher.presence().find((e) => e.member_user_id === users.pres_beta.userId)!;
+    expect(up.network_id).toBe(NET);
+    expect(up.user_id).toBe(users.pres_alpha.userId); // 收件人
+    expect(beta.presence().filter((e) => e.member_user_id === users.pres_beta.userId)).toEqual([]);
+
+    beta.close();
+    await waitFor(async () => (await humanOf(users.pres_alpha.token, users.pres_beta.userId)).online === false);
+    const off = await humanOf(users.pres_gamma.token, users.pres_beta.userId);
+    expect(off.online).toBe(false);
+    expect(Date.parse(off.last_seen_at)).toBeGreaterThanOrEqual(before - 1000);
+    await waitFor(() => watcher.presence().some((e) => e.member_user_id === users.pres_beta.userId && e.online === false));
+    const down = watcher.presence().find((e) => e.member_user_id === users.pres_beta.userId && e.online === false)!;
+    expect(typeof down.last_seen_at).toBe("string");
+    watcher.close();
+  });
+
+  test("two streams for one user: closing one keeps them online, no offline event", async () => {
+    const watcher = await openUserStream(users.pres_alpha.token, NET);
+    const a = await openUserStream(users.pres_beta.token, NET);
+    const b = await openUserStream(users.pres_beta.token, NET);
+    await waitFor(() => watcher.presence().some((e) => e.member_user_id === users.pres_beta.userId && e.online));
+    a.close();
+    await new Promise((r) => setTimeout(r, 200));
+    expect((await humanOf(users.pres_alpha.token, users.pres_beta.userId)).online).toBe(true);
+    expect(watcher.presence().filter((e) => e.member_user_id === users.pres_beta.userId && !e.online)).toEqual([]);
+    b.close();
+    await waitFor(async () => (await humanOf(users.pres_alpha.token, users.pres_beta.userId)).online === false);
+    watcher.close();
+  });
+});
+
+describe("who must NOT see presence", () => {
+  test("non-member → 403, no humans at all", async () => {
+    const r = await get(users.outsider.token, `/api/networks/${NET}/humans`);
+    expect(r.status).toBe(403);
+    expect(r.body.humans).toBeUndefined();
+  });
+
+  test("node token → same three identity fields as before, no online / last_seen_at", async () => {
+    const beta = await openUserStream(users.pres_beta.token, NET);
+    const r = await get(nodeToken, `/api/networks/${NET}/humans`);
+    expect(r.status).toBe(200);
+    for (const h of r.body.humans) expect(Object.keys(h).sort()).toEqual(["display_name", "user_id", "username"]);
+    // 节点令牌也不能订阅用户流(既有行为,这里钉住:不能借它收 member_presence)。
+    expect((await fetch(`${BASE}/events/users/me?network_id=${NET}`, { headers: auth(nodeToken) })).status).toBe(403);
+    beta.close();
+    await waitFor(async () => (await humanOf(users.pres_alpha.token, users.pres_beta.userId)).online === false);
+  });
+
+  test("a user connected in another network gets no member_presence about this network's people", async () => {
+    const outsiderStream = await openUserStream(users.outsider.token, users.outsider_net.userId);
+    const watcher = await openUserStream(users.pres_alpha.token, NET);
+    const beta = await openUserStream(users.pres_beta.token, NET);
+    await waitFor(() => watcher.presence().some((e) => e.member_user_id === users.pres_beta.userId && e.online));
+    beta.close();
+    await waitFor(() => watcher.presence().some((e) => e.member_user_id === users.pres_beta.userId && !e.online));
+    expect(outsiderStream.presence()).toEqual([]);
+    watcher.close();
+    outsiderStream.close();
+  });
+});

package/src/migrate-sqlite-to-pg.test.ts

@@ -0,0 +1,47 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { MigrateRefused, migrateSqliteToPg } from "./migrate-sqlite-to-pg";
+
+// Only the refusals that happen before any connection is attempted; the full
+// copy runs against a real PostgreSQL in test2123 (migrate-stage.sh).
+const home = mkdtempSync(join(tmpdir(), "anet-migrate-home-"));
+const commhub = join(home, ".commhub");
+mkdirSync(commhub);
+writeFileSync(join(commhub, "commhub.db"), "");
+const elsewhere = join(home, "copies");
+mkdirSync(elsewhere);
+symlinkSync(join(commhub, "commhub.db"), join(elsewhere, "link.db"));
+const PG = "postgres://user:s3cret@127.0.0.1:1/anet_never_test";
+
+afterAll(() => rmSync(home, { recursive: true, force: true }));
+
+async function refusal(opts: Parameters<typeof migrateSqliteToPg>[0]): Promise<string> {
+  try {
+    await migrateSqliteToPg({ ...opts, home, log: () => {} });
+  } catch (e) {
+    expect(e).toBeInstanceOf(MigrateRefused);
+    return String((e as Error).message);
+  }
+  throw new Error("expected a refusal");
+}
+
+describe("RFC-039 S5 migrate-to-pg refusals", () => {
+  test("target must be a postgres URL", async () => {
+    expect(await refusal({ from: join(elsewhere, "x.db"), to: "mysql://h/db" })).toContain("--to must be a postgres");
+  });
+
+  test("missing source", async () => {
+    expect(await refusal({ from: join(elsewhere, "missing.db"), to: PG })).toContain("does not exist");
+  });
+
+  test("the live Hub directory ~/.commhub is refused, also through a symlink", async () => {
+    for (const from of [join(commhub, "commhub.db"), join(elsewhere, "link.db")]) {
+      const message = await refusal({ from, to: PG });
+      expect(message).toContain("live Hub's directory");
+      expect(message).toContain("--i-know-this-is-a-copy");
+      expect(message).not.toContain("s3cret");
+    }
+  });
+});

package/src/migrate-sqlite-to-pg.ts

@@ -0,0 +1,263 @@
+/**
+ * RFC-039 S5 — offline copy of a Hub's SQLite database into an EMPTY
+ * PostgreSQL database.
+ *
+ *   commhub-server migrate-to-pg --from <sqlite file> --to <postgres url>
+ *                                [--dry-run] [--i-know-this-is-a-copy]
+ *
+ * Contract:
+ *   - offline: no running process may have the source (or its -wal/-shm)
+ *     open (checked through /proc on Linux). A stopped Hub normally leaves a
+ *     -wal behind — that is expected, and its contents are included: the
+ *     source is opened read-only and read through a `VACUUM INTO` snapshot in
+ *     a private temp dir.
+ *   - never the live Hub's database: a source whose real path is under
+ *     ~/.commhub is refused unless --i-know-this-is-a-copy is given.
+ *   - empty target only: the target's `public` schema must hold no tables,
+ *     views, sequences or functions. The schema is then built by the Hub's
+ *     own module graph (no second copy of the DDL).
+ *   - one transaction: every table is copied and verified — row counts plus
+ *     a SHA-256 over canonicalised rows — before COMMIT; any mismatch or
+ *     error rolls everything back.
+ *   - --dry-run does all of the above, rolls back, and drops what it created,
+ *     leaving the target as it found it.
+ *   - the target URL is printed with credentials removed.
+ */
+import { Database } from "bun:sqlite";
+import { createHash } from "node:crypto";
+import { existsSync, mkdtempSync, readdirSync, readlinkSync, realpathSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve, sep } from "node:path";
+import { PgAdapter, redactPgUrl, type DbAdapter } from "./db-adapter.js";
+
+export type MigrateOptions = {
+  from: string;
+  to: string;
+  dryRun?: boolean;
+  allowCommhubCopy?: boolean;
+  home?: string;
+  log?: (line: string) => void;
+};
+
+export type TableReport = { table: string; rows: number; sha256: string };
+export type MigrateReport = { ok: true; dryRun: boolean; tables: TableReport[] };
+
+class DryRunRollback extends Error {}
+
+/** Refusals are thrown as MigrateRefused so the CLI can print them without a stack. */
+export class MigrateRefused extends Error {}
+
+function refuse(message: string): never {
+  throw new MigrateRefused(`[migrate-to-pg] REFUSING: ${message}`);
+}
+
+const quoteIdent = (name: string) => `"${name.replace(/"/g, '""')}"`;
+
+/** One canonical text per value, identical for bun:sqlite and PgAdapter output. */
+function canonical(value: unknown): unknown {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "bigint") return `i:${value.toString()}`;
+  if (typeof value === "number") return Number.isInteger(value) ? `i:${value}` : `f:${value}`;
+  if (value instanceof Uint8Array) return `b:${Buffer.from(value).toString("hex")}`;
+  if (typeof value === "string" && /^-?\d+$/.test(value) && value.length > 15) return `i:${value}`; // unsafe int8 comes back as text
+  return `s:${String(value)}`;
+}
+
+/** Order-independent digest: hash each row, sort the row hashes, hash the list. */
+function tableDigest(rows: Iterable<Record<string, unknown>>, cols: string[]): { rows: number; sha256: string } {
+  const rowHashes: string[] = [];
+  for (const row of rows) {
+    rowHashes.push(createHash("sha256").update(JSON.stringify(cols.map((c) => canonical(row[c])))).digest("hex"));
+  }
+  rowHashes.sort();
+  return { rows: rowHashes.length, sha256: createHash("sha256").update(rowHashes.join("\n")).digest("hex") };
+}
+
+function bindValue(value: unknown): unknown {
+  if (typeof value === "bigint") {
+    const n = Number(value);
+    return Number.isSafeInteger(n) ? n : value.toString();
+  }
+  return value;
+}
+
+function checkSource(from: string, home: string, allowCommhubCopy: boolean): string {
+  const abs = resolve(from);
+  if (!existsSync(abs)) refuse(`source ${abs} does not exist`);
+  const real = realpathSync(abs);
+  if (!statSync(real).isFile()) refuse(`source ${real} is not a file`);
+  const commhubDir = join(home, ".commhub");
+  const guarded = existsSync(commhubDir) ? realpathSync(commhubDir) : resolve(commhubDir);
+  if ((real === guarded || real.startsWith(guarded + sep)) && !allowCommhubCopy) {
+    refuse(`source ${real} is under ${guarded}, the live Hub's directory. Stop the Hub, copy the database elsewhere, ` +
+      "and migrate the copy — or pass --i-know-this-is-a-copy if this file already is one");
+  }
+  const holders = processesHolding([real, `${real}-wal`, `${real}-shm`]);
+  if (holders === null) {
+    console.warn("[migrate-to-pg] cannot inspect open files on this platform — make sure the Hub using this database is stopped");
+  } else if (holders.length) {
+    refuse(`${real} is open in running process(es) ${holders.join(", ")} — stop the Hub first`);
+  }
+  return real;
+}
+
+/** PIDs (other than ours) with any of `paths` open; null where /proc is unavailable. */
+function processesHolding(paths: string[]): number[] | null {
+  if (!existsSync("/proc/self/fd")) return null;
+  const wanted = new Set(paths);
+  const holders: number[] = [];
+  for (const entry of readdirSync("/proc")) {
+    const pid = Number(entry);
+    if (!Number.isInteger(pid) || pid === process.pid) continue;
+    let fds: string[];
+    try { fds = readdirSync(`/proc/${pid}/fd`); } catch { continue; } // gone, or another user's
+    for (const fd of fds) {
+      let target = "";
+      try { target = readlinkSync(`/proc/${pid}/fd/${fd}`); } catch { continue; }
+      if (wanted.has(target.replace(/ \(deleted\)$/, ""))) { holders.push(pid); break; }
+    }
+  }
+  return holders;
+}
+
+function publicObjectCount(pg: PgAdapter): number {
+  const row = pg.get<{ n: number }>(
+    `SELECT (SELECT COUNT(*) FROM information_schema.tables WHERE table_schema = 'public')
+          + (SELECT COUNT(*) FROM information_schema.sequences WHERE sequence_schema = 'public')
+          + (SELECT COUNT(*) FROM information_schema.routines WHERE routine_schema = 'public') AS n`,
+  );
+  return Number(row?.n ?? 0);
+}
+
+function dropEverythingInPublic(pg: DbAdapter) {
+  // Only ever called on a target that was verified empty before we started,
+  // so everything here was created by this run.
+  pg.exec(`DO $$ DECLARE r record; BEGIN
+    FOR r IN SELECT tablename FROM pg_tables WHERE schemaname = 'public' LOOP
+      EXECUTE 'DROP TABLE IF EXISTS public.' || quote_ident(r.tablename) || ' CASCADE';
+    END LOOP;
+    FOR r IN SELECT p.oid::regprocedure AS sig FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace WHERE n.nspname = 'public' LOOP
+      EXECUTE 'DROP FUNCTION IF EXISTS ' || r.sig || ' CASCADE';
+    END LOOP;
+    FOR r IN SELECT sequencename FROM pg_sequences WHERE schemaname = 'public' LOOP
+      EXECUTE 'DROP SEQUENCE IF EXISTS public.' || quote_ident(r.sequencename) || ' CASCADE';
+    END LOOP;
+  END $$`);
+}
+
+export async function migrateSqliteToPg(opts: MigrateOptions): Promise<MigrateReport> {
+  const log = opts.log ?? ((line: string) => console.log(line));
+  const home = opts.home ?? process.env.HOME ?? "";
+  if (!/^postgres(ql)?:\/\//.test(opts.to)) refuse("--to must be a postgres:// or postgresql:// URL");
+  const source = checkSource(opts.from, home, !!opts.allowCommhubCopy);
+  log(`[migrate-to-pg] source ${source}`);
+  log(`[migrate-to-pg] target ${redactPgUrl(opts.to)}${opts.dryRun ? " (dry run)" : ""}`);
+
+  // Empty-target check on a connection of our own, before the schema exists.
+  const probe = new PgAdapter(opts.to);
+  const existing = publicObjectCount(probe);
+  probe.close();
+  if (existing > 0) refuse(`target schema "public" is not empty (${existing} tables/sequences/functions). Migrate only into a new, empty database`);
+
+  // Snapshot the source: a consistent read that cannot touch the original.
+  const snapDir = mkdtempSync(join(tmpdir(), "anet-migrate-"));
+  const snapshot = join(snapDir, "snapshot.db");
+  try {
+    const original = new Database(source, { readonly: true });
+    original.exec(`VACUUM INTO '${snapshot.replace(/'/g, "''")}'`);
+    original.close();
+    const src = new Database(snapshot, { readonly: true, safeIntegers: true });
+
+    // Build the target schema exactly as the Hub does: import its module graph
+    // with DATABASE_URL pointing at the target.
+    delete process.env.COMMHUB_DB;
+    process.env.DATABASE_URL = opts.to;
+    await import("./server.js");
+    const { db } = await import("./db.js");
+    if (db.dialect !== "postgres") throw new Error("schema build did not select PostgreSQL");
+
+    const tables = (src.query("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' ORDER BY name").all() as { name: string }[])
+      .map((r) => r.name);
+    const report: TableReport[] = [];
+
+    try {
+      db.transaction(() => {
+        for (const table of tables) {
+          const srcCols = (src.query(`PRAGMA table_info(${quoteIdent(table)})`).all() as { name: string }[]).map((c) => c.name);
+          const tgtCols = new Set(db.all<{ column_name: string }>(
+            "SELECT column_name FROM information_schema.columns WHERE table_schema = 'public' AND table_name = ?1", table,
+          ).map((c) => c.column_name));
+          const srcCount = Number((src.query(`SELECT COUNT(*) AS n FROM ${quoteIdent(table)}`).get() as { n: bigint | number }).n);
+          if (tgtCols.size === 0) {
+            if (srcCount > 0) throw new Error(`table ${table} (${srcCount} rows) does not exist in the Hub's PostgreSQL schema`);
+            log(`[migrate-to-pg] skip ${table}: not in the PostgreSQL schema, and empty in the source`);
+            continue;
+          }
+          const missing = srcCols.filter((c) => !tgtCols.has(c));
+          if (missing.length && srcCount > 0) throw new Error(`table ${table}: column(s) ${missing.join(", ")} do not exist in PostgreSQL`);
+          const cols = srcCols.filter((c) => tgtCols.has(c));
+          // SQLite's implicit rowid carries insertion order; PostgreSQL keeps it
+          // in a real `rowid` column on the tables that sort by it (RFC-039 F3).
+          const copyRowid = tgtCols.has("rowid") && !srcCols.includes("rowid");
+          const selectCols = [...(copyRowid ? ["rowid AS rowid"] : []), ...cols.map(quoteIdent)].join(", ");
+          const insertCols = [...(copyRowid ? ["rowid"] : []), ...cols];
+
+          // Triggers are off only while this table is being filled. Re-enabled
+          // in `finally` so no path — including a failed batch — leaves them
+          // off; a rollback also restores them (DDL is transactional in PG).
+          db.exec(`ALTER TABLE ${quoteIdent(table)} DISABLE TRIGGER USER`);
+          try {
+            db.run(`DELETE FROM ${quoteIdent(table)}`); // rows the schema bootstrap seeded; the source is authoritative
+            const perBatch = Math.max(1, Math.floor(30000 / insertCols.length));
+            const stmt = src.query(`SELECT ${selectCols} FROM ${quoteIdent(table)} ORDER BY rowid LIMIT ?1 OFFSET ?2`);
+            for (let offset = 0; offset < srcCount; offset += perBatch) {
+              const rows = stmt.all(perBatch, offset) as Record<string, unknown>[];
+              if (!rows.length) break;
+              const params: unknown[] = [];
+              const tuples = rows.map((row) => `(${insertCols.map((c) => { params.push(bindValue(row[c])); return `?${params.length}`; }).join(", ")})`);
+              db.run(`INSERT INTO ${quoteIdent(table)} (${insertCols.map(quoteIdent).join(", ")}) VALUES ${tuples.join(", ")}`, params);
+            }
+          } finally {
+            db.exec(`ALTER TABLE ${quoteIdent(table)} ENABLE TRIGGER USER`);
+          }
+
+          // Sequences behind BIGSERIAL columns continue after the copied ids.
+          for (const seq of db.all<{ column_name: string }>(
+            "SELECT column_name FROM information_schema.columns WHERE table_schema = 'public' AND table_name = ?1 AND column_default LIKE 'nextval(%'", table,
+          )) {
+            db.get(`SELECT setval(pg_get_serial_sequence(?1, ?2), COALESCE((SELECT MAX(${quoteIdent(seq.column_name)}) FROM ${quoteIdent(table)}), 0) + 1, false)`,
+              table, seq.column_name);
+          }
+
+          // Verify before COMMIT.
+          const hashCols = copyRowid ? ["rowid", ...cols] : cols;
+          const srcDigest = tableDigest(src.query(`SELECT ${selectCols} FROM ${quoteIdent(table)}`).all() as Record<string, unknown>[], hashCols);
+          const tgtDigest = tableDigest(db.all(`SELECT ${hashCols.map(quoteIdent).join(", ")} FROM ${quoteIdent(table)}`), hashCols);
+          if (srcDigest.rows !== tgtDigest.rows || srcDigest.sha256 !== tgtDigest.sha256) {
+            throw new Error(`verification failed for ${table}: source ${srcDigest.rows} rows ${srcDigest.sha256.slice(0, 12)}, ` +
+              `target ${tgtDigest.rows} rows ${tgtDigest.sha256.slice(0, 12)}`);
+          }
+          report.push({ table, rows: srcDigest.rows, sha256: srcDigest.sha256 });
+          log(`[migrate-to-pg] ${table}: ${srcDigest.rows} rows, sha256 ${srcDigest.sha256.slice(0, 16)} ✓`);
+        }
+        if (opts.dryRun) throw new DryRunRollback("dry run");
+      });
+    } catch (e) {
+      const rows = report.reduce((n, t) => n + t.rows, 0);
+      dropEverythingInPublic(db);
+      src.close();
+      if (!(e instanceof DryRunRollback)) {
+        const verify = e instanceof Error && e.message.startsWith("verification failed") ? "MISMATCH" : "NOT-REACHED";
+        log(`[migrate-to-pg] SUMMARY result=FAILED tables_verified=${report.length}/${tables.length} rows=${rows} verify=${verify} — rolled back, target left empty`);
+        throw e;
+      }
+      log(`[migrate-to-pg] SUMMARY result=DRY-RUN tables=${report.length} rows=${rows} verify=OK — rolled back, target left empty`);
+      return { ok: true, dryRun: true, tables: report };
+    }
+    src.close();
+    log(`[migrate-to-pg] SUMMARY result=COMMITTED tables=${report.length} rows=${report.reduce((n, t) => n + t.rows, 0)} verify=OK`);
+    return { ok: true, dryRun: false, tables: report };
+  } finally {
+    rmSync(snapDir, { recursive: true, force: true });
+  }
+}

package/src/push.ts

@@ -158,6 +158,10 @@ function closeClient(client: SSEClient, reason: string): void {
     // we're done with it.
   }
   console.log(`[${ts()}] SSE ✕ ${printableKey(client.key)} closed (reason=${reason})`);
+  if (isUserStreamClient(client)) {
+    touchUserSeen(client.subscriberUserId!);
+    if (!isUserOnline(client.subscriberUserId!)) notifyPresence(client.subscriberUserId!, false);
+  }
 }
 
 /** Best-effort enqueue with backpressure guard. Returns:
@@ -308,8 +312,11 @@ function createStreamForKey(
         ...(opts.eventFilter ? { eventFilter: opts.eventFilter } : {}),
       };
 
+      const presenceUser = isUserStreamClient(client) ? client.subscriberUserId! : null;
+      const wasOnline = presenceUser ? isUserOnline(presenceUser) : true;
       if (!clients.has(key)) clients.set(key, []);
       clients.get(key)!.push(client);
+      if (presenceUser) touchUserSeen(presenceUser);
       console.log(`[${ts()}] SSE ← ${printableKey(key)} connected (${clients.get(key)!.length} clients)`);
 
       // Send initial connected frame through the backpressure guard so
@@ -328,6 +335,7 @@ function createStreamForKey(
           return;
         }
         const result = tryEnqueueBytes(client, encoder.encode(`: keepalive\n\n`));
+        if (result === "ok" && isUserStreamClient(client)) touchUserSeen(client.subscriberUserId!);
         if (result === "dead") {
           // closeClient already cleared the timer; just make sure we
           // also prune from the map.
@@ -337,6 +345,8 @@ function createStreamForKey(
       (client.keepaliveTimer as any)?.unref?.();
 
       ensureLivenessSweep();
+      // 在线状态的广播放在 connected 帧之后:订阅方先拿到自己的 connected,再看到别人的变化。
+      if (presenceUser && !wasOnline) notifyPresence(presenceUser, true);
     },
     cancel() {
       // Consumer side hangup — straightforward path, mark closed and
@@ -523,6 +533,75 @@ export function pushUserEvent(
   if (needPrune) pruneClosed(key);
 }
 
+// ── 人类成员在线状态(人员列表的在线点)──────────────────────────────────
+// 判据就是上面这张用户流(/events/users/me)注册表:此刻有活着的用户流 = 在线。按**用户**算,
+// 不按网络 —— 桌面端同一时刻只连当前网络的用户流,按网络算会把正在别的网络里的人画成离线。
+// last_seen 只在内存:连上、每次 keepalive 成功、断开时刷新。Hub 重启后清空(未知 = null,
+// 调用方不要把 null 画成「很久以前」)。
+
+const userLastSeen = new Map<string, number>();
+let presenceListener: ((userId: string, online: boolean, lastSeenAt: string | null) => void) | null = null;
+
+function isUserStreamClient(client: SSEClient): boolean {
+  return !!client.subscriberUserId && client.key.startsWith(USER_KEY_PREFIX);
+}
+
+function touchUserSeen(userId: string): void {
+  userLastSeen.set(userId, Date.now());
+}
+
+function isUserOnline(userId: string): boolean {
+  for (const [key, arr] of clients) {
+    if (!key.startsWith(USER_KEY_PREFIX)) continue;
+    if (arr.some((c) => !c.closed && c.subscriberUserId === userId)) return true;
+  }
+  return false;
+}
+
+function lastSeenIso(userId: string): string | null {
+  const ms = userLastSeen.get(userId);
+  return ms === undefined ? null : new Date(ms).toISOString();
+}
+
+function notifyPresence(userId: string, online: boolean): void {
+  if (!presenceListener) return;
+  try {
+    presenceListener(userId, online, lastSeenIso(userId));
+  } catch (e: any) {
+    console.log(`[${ts()}] presence listener failed: ${e?.message || e}`);
+  }
+}
+
+/** 用户的第一条用户流连上 / 最后一条断开时回调(server.ts 用它向同网络成员推 member_presence)。 */
+export function onUserPresenceChange(cb: ((userId: string, online: boolean, lastSeenAt: string | null) => void) | null): void {
+  presenceListener = cb;
+}
+
+/** 一批用户此刻的在线状态。鉴权由调用方负责。 */
+export function getUserPresence(userIds: readonly string[]): Map<string, { online: boolean; last_seen_at: string | null }> {
+  const online = new Set<string>();
+  for (const [key, arr] of clients) {
+    if (!key.startsWith(USER_KEY_PREFIX)) continue;
+    for (const c of arr) if (!c.closed && c.subscriberUserId) online.add(c.subscriberUserId);
+  }
+  const out = new Map<string, { online: boolean; last_seen_at: string | null }>();
+  for (const uid of userIds) out.set(uid, { online: online.has(uid), last_seen_at: lastSeenIso(uid) });
+  return out;
+}
+
+/** 推给某网络里所有连着用户流的人(可排除一个)。鉴权由调用方负责。 */
+export function pushUserEventToNetwork(networkId: string, event: Record<string, unknown>, exceptUserId?: string): number {
+  const prefix = `${USER_KEY_PREFIX}${networkId}:`;
+  const recipients: string[] = [];
+  for (const key of clients.keys()) {
+    if (!key.startsWith(prefix)) continue;
+    const uid = key.slice(prefix.length);
+    if (uid && uid !== exceptUserId) recipients.push(uid);
+  }
+  for (const uid of recipients) pushUserEvent(networkId, uid, event);
+  return recipients.length;
+}
+
 /**
  * 多用户 Agent 权限:某用户在某网络的授权 / 成员资格变了,断开他在这个网络里**订阅时带了身份**
  * 的流(网络观察流、用户流),客户端重连时按新权限重新鉴权。返回断开的条数。
@@ -549,6 +628,7 @@ export function __resetSSEClientsForTest(): void {
     for (const c of arr) closeClient(c, "reset-for-test");
   }
   clients.clear();
+  userLastSeen.clear();
   if (livenessSweepTimer) {
     clearInterval(livenessSweepTimer);
     livenessSweepTimer = null;

package/src/server.ts

@@ -10,7 +10,7 @@ import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/
 import { z } from "zod/v4";
 import { registerTools } from "./tools.js";
 import { db, logTaskEvent, logAudit, syncScheduledRunForTask } from "./db.js";
-import { createSSEStream, createNetworkObserverStream, createUserEventStream, pushEvent, pushNetworkObserverEvent, getSSEStats, PRINTABLE_OBSERVER_KEY_PREFIX, closeUserStreamsInNetwork } from "./push.js";
+import { createSSEStream, createNetworkObserverStream, createUserEventStream, pushEvent, pushNetworkObserverEvent, getSSEStats, PRINTABLE_OBSERVER_KEY_PREFIX, closeUserStreamsInNetwork, getUserPresence, onUserPresenceChange, pushUserEventToNetwork } from "./push.js";
 import { assertNodeActive } from "./lifecycle-guard.js";
 import { pendingInboxCount } from "./inbox-count.js";
 import { addAgentNetworkScope, addHumanNetworkScope, addNetworkScope, addOwnTrafficScope, canRestWriteNetwork, canRestWriteNetworkAsHuman, getUserNetworkIds, resolveRestNetworkScope, resolveRestWriteNetworkId, singleNetworkId, type RestNetworkScope } from "./network-scope.js";
@@ -238,6 +238,16 @@ function isTmuxAllowedIP(ip: string): boolean {
 function isNodeCredential(resolved: { networkId: string | null } | null | undefined): boolean {
   return !!resolved?.networkId;
 }
+// 人员列表的在线点:某人的第一条用户流连上 / 最后一条断开时,推给他所在每个网络里其他连着用户流的成员。
+// 收件人本来就是该网络成员(用户流入口按成员资格鉴权),与 GET /api/networks/:id/humans 同一可见范围。
+// 字段叫 member_user_id:pushUserEvent 会把 user_id 写成**收件人**自己。
+onUserPresenceChange((userId, online, lastSeenAt) => {
+  const nets = db.all<{ network_id: string }>("SELECT network_id FROM network_members WHERE user_id = ?1", userId);
+  for (const { network_id } of nets) {
+    pushUserEventToNetwork(network_id, { type: "member_presence", member_user_id: userId, online, last_seen_at: lastSeenAt }, userId);
+  }
+});
+
 function isHubAdminCredential(resolved: { networkId: string | null; user: { role: string } } | null | undefined): boolean {
   return !!resolved && !resolved.networkId && resolved.user.role === "admin";
 }
@@ -1606,7 +1616,11 @@ return Bun.serve({
       if (resolved.user.role !== "admin" && !getUserNetworkRole(resolved.user.user_id, netId)) {
         return withCors(req, Response.json({ ok: false, error: "not a member of this network" }, { status: 403 }));
       }
-      return withCors(req, Response.json({ ok: true, network_id: netId, humans: getNetworkHumans(netId) }));
+      const humans = getNetworkHumans(netId);
+      // 在线状态(online / last_seen_at)只给用户令牌:节点令牌拿到的仍是原来的身份字段,不多得任何东西。
+      if (isNodeCredential(resolved)) return withCors(req, Response.json({ ok: true, network_id: netId, humans }));
+      const presence = getUserPresence(humans.map((h) => h.user_id));
+      return withCors(req, Response.json({ ok: true, network_id: netId, humans: humans.map((h) => ({ ...h, ...presence.get(h.user_id)! })) }));
     }
 
     // ── V3.13: Network members + invites ──

package/src/skillhub-http.test.ts

@@ -84,6 +84,22 @@ describe("SkillHub real Hub + SQLite", () => {
     expect(detail.created_by_user).toBeUndefined(); expect(detail.reviewed_by_user).toBeUndefined(); expect(detail.content_hash).toBeUndefined();
   });
 
+  test("query matches regardless of letter case (SQLite LIKE semantics, kept on PostgreSQL)", async () => {
+    for (const query of ["incident", "INCIDENT", "Handoff"]) {
+      const found = await tool(nodeToken, "list_skills", { network_id: networkId, query });
+      expect(found.skills.map((x: any) => x.skill_id)).toContain(skillId);
+    }
+    expect((await tool(nodeToken, "list_skills", { network_id: networkId, query: "no-such-skill" })).skills).toHaveLength(0);
+  });
+
+  test("% and _ in the query are literal characters, not wildcards (#2141)", async () => {
+    const ids = async (query: string) => (await tool(nodeToken, "list_skills", { network_id: networkId, query })).skills.map((x: any) => x.skill_id);
+    expect(await ids("_")).not.toContain(skillId);       // was: matched everything
+    expect(await ids("%")).not.toContain(skillId);
+    expect(await ids("incident_handoff")).not.toContain(skillId); // `_` must not stand for the "-" in the slug
+    expect(await ids("incident-handoff")).toContain(skillId);
+  });
+
   test("foreign user cannot read or review another network", async () => {
     expect((await tool(foreignToken, "list_skills", { network_id: networkId })).ok).toBe(false);
     const review = await tool(foreignToken, "review_skill", { network_id: networkId, skill_id: skillId, decision: "rejected" });

package/src/sqlite-close-checkpoint.test.ts

@@ -0,0 +1,78 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { copyFileSync, existsSync, mkdtempSync, rmSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { SQLiteAdapter } from "./db-adapter";
+
+// #2151 — a cleanly stopped Hub must leave a complete .db: the -wal is absent
+// or empty, and a copy of the .db file alone still has the data.
+const dir = mkdtempSync(join(tmpdir(), "anet-wal-close-"));
+afterAll(() => rmSync(dir, { recursive: true, force: true }));
+
+const walBytes = (db: string) => (existsSync(`${db}-wal`) ? statSync(`${db}-wal`).size : 0);
+
+function copyOnlyDb(db: string): Database {
+  const copy = join(dirname(db), `copy-of-${db.split("/").pop()}`);
+  copyFileSync(db, copy); // deliberately without -wal / -shm
+  return new Database(copy, { readonly: true });
+}
+
+describe("#2151 SQLite WAL is checkpointed on close", () => {
+  test("SQLiteAdapter.close() after >20 distinct statements leaves a complete .db", () => {
+    const path = join(dir, "adapter.db");
+    const raw = new Database(path);
+    raw.exec("PRAGMA journal_mode=WAL");
+    const db = new SQLiteAdapter(raw);
+    db.exec("CREATE TABLE t (x TEXT)");
+    db.run("INSERT INTO t VALUES (?1)", ["kept"]);
+    // bun:sqlite stops being able to close after more than 20 distinct query() strings.
+    for (let i = 0; i < 30; i++) db.get(`SELECT ${i} AS v`);
+    db.close();
+    expect(walBytes(path)).toBe(0);
+    const copy = copyOnlyDb(path);
+    expect(copy.query("SELECT x FROM t").all()).toEqual([{ x: "kept" }]);
+    copy.close();
+  });
+
+  test("a real Hub that served traffic and got SIGTERM leaves a complete .db", async () => {
+    const bin = join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "commhub.ts");
+    const home = join(dir, "home");
+    const path = join(dir, "hub.db");
+    const port = String(27000 + Math.floor(Math.random() * 2000));
+    const base = `http://127.0.0.1:${port}`;
+    const hub = Bun.spawn(["bun", bin, "--port", port, "--host", "127.0.0.1", "--db", path], {
+      env: { PATH: process.env.PATH ?? "", HOME: home }, stdout: "pipe", stderr: "pipe",
+    });
+    try {
+      let up = false;
+      for (let i = 0; i < 150 && !up; i++) {
+        up = await fetch(`${base}/health`).then((r) => r.ok, () => false);
+        if (!up) await Bun.sleep(100);
+      }
+      expect(up).toBe(true);
+      const post = (p: string, body: unknown, token?: string) => fetch(`${base}${p}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+        body: JSON.stringify(body),
+      }).then((r) => r.json() as Promise<any>);
+      const reg = await post("/api/auth/register", { username: "walcheck", password: "StrongPassw0rd" });
+      expect(reg.ok).toBe(true);
+      const login = await post("/api/auth/login", { username: "walcheck", password: "StrongPassw0rd" });
+      const net = await post("/api/networks", { name: "wal-net" }, login.token);
+      expect(net.ok).toBe(true);
+      const ntok = await post("/api/auth/node-token", { network_id: net.network_id, node_name: "wal-agent" }, login.token);
+      expect(ntok.ok).toBe(true);
+      expect(walBytes(path)).toBeGreaterThan(0); // the writes really are in the WAL before the stop
+    } finally {
+      hub.kill("SIGTERM");
+      await hub.exited;
+    }
+    expect(walBytes(path)).toBe(0);
+    const copy = copyOnlyDb(path);
+    expect(copy.query("SELECT COUNT(*) AS n FROM users WHERE username = 'walcheck'").get()).toEqual({ n: 1 });
+    expect(copy.query("SELECT COUNT(*) AS n FROM networks WHERE network_name = 'wal-net'").get()).toEqual({ n: 1 });
+    copy.close();
+  }, 40_000);
+});

package/src/tools.ts

@@ -357,8 +357,9 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
                    FROM skillhub_skills WHERE network_id = ?1`;
       if (!showPending) sql += ` AND status = 'published'`;
       if (query?.trim()) {
-        params.push(`%${query.trim()}%`);
-        sql += ` AND (slug LIKE ?${params.length} OR name LIKE ?${params.length} OR description LIKE ?${params.length})`;
+        params.push(`%${query.trim().replace(/[\\%_]/g, (c) => `\\${c}`)}%`); // #2141: the query is text, not a pattern
+        const like = db.dialect === "postgres" ? "ILIKE" : "LIKE"; // RFC-039 F6: SQLite LIKE ignores ASCII case; keep that on PG
+        sql += ` AND (slug ${like} ?${params.length} ESCAPE '\\' OR name ${like} ?${params.length} ESCAPE '\\' OR description ${like} ?${params.length} ESCAPE '\\')`;
       }
       sql += ` ORDER BY updated_at DESC LIMIT ${limit ?? 100}`;
       return skillHubReply({ ok: true, reviewer, skills: db.all(sql, ...params) });