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

package/src/model-auth-notify-http.test.ts

@@ -0,0 +1,181 @@
+// #462 —— 节点模型登录失效 → 通知节点主人一次。
+//
+// 钉住:
+//   1. 翻转判定(纯函数):进入 revoked/expired 发一次;坏→坏不再发(含 revoked⇄expired);回到 ok 才重新上膛;
+//      unknown / 没报既不发也不上膛。
+//   2. 真 report_status(节点令牌):ok→expired→expired→ok→expired = 恰好 2 条,只给节点主人;
+//      网络 owner 和别的成员 0 条。正文带别名、原因、`codex login` 修法,不教人拷别人的 auth.json。
+//   3. 别的节点 / 用户令牌替它报坏状态 → 不发(与 #448 同一条「只有本节点令牌能替自己说健康」)。
+//   4. Hub 重启(内存标记清空)后第一眼看到坏状态:主人还有没读的同类消息 → 不再发;读过了 → 发。
+//
+// 跑法:cd server && COMMHUB_DB=/tmp/x.db bun test src/model-auth-notify-http.test.ts
+//       PG:COMMHUB_TEST_PG_URL=… COMMHUB_PG_EXPERIMENTAL=1(tests/test2123-hub-postgres-ladder 里注册)
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { addNetworkMember, createNetworkTokenForNode, register } from "./auth.js";
+import { db } from "./db.js";
+import { registerTools } from "./tools.js";
+import { clearNodeHealthStore } from "./node-health-store.js";
+import { __resetModelAuthNoticesForTest, decideModelAuthNotice, MODEL_AUTH_NOTICE_KIND, modelAuthNoticeText } from "./model-auth-notify.js";
+
+const dir = mkdtempSync(join(tmpdir(), "anet-model-auth-notify-"));
+const activeDbPath = process.env.COMMHUB_DB ?? (process.env.COMMHUB_TEST_PG_URL ? "postgres" : undefined);
+if (!activeDbPath) throw new Error("model-auth-notify requires COMMHUB_DB (or COMMHUB_TEST_PG_URL) before module import");
+
+const PW = "ModelAuthNotify123!";
+const stamp = Date.now();
+const NODE = `ma-node-${stamp}`;
+const NODE_ID = `n_ma_node_${stamp}`;
+const PEER = `ma-peer-${stamp}`;
+const PEER_ID = `n_ma_peer_${stamp}`;
+let netId = "";
+let bossId = "", noraId = "", ottoId = "";
+let nodeTokenId = "", peerTokenId = "";
+
+async function connectAs(alias: string, userId: string, tokenId: string, isNetworkToken = true) {
+  const s = new McpServer({ name: "model-auth-notify", version: "1" });
+  registerTools(s, undefined, netId, userId, alias, isNetworkToken, tokenId);
+  const client = new Client({ name: "model-auth-notify-client", version: "1" });
+  const [ct, st] = InMemoryTransport.createLinkedPair();
+  await s.connect(st);
+  await client.connect(ct);
+  const report = async (model_auth: string | undefined, asAlias = NODE, nodeId = NODE_ID) => {
+    const r: any = await client.callTool({
+      name: "report_status",
+      arguments: { resume_id: `sdk-${nodeId}`, alias: asAlias, status: "idle", node_id: nodeId, network_id: netId, health: { bridge: "ok", ...(model_auth ? { model_auth } : {}) } },
+    });
+    expect(r.isError === true).toBe(false);
+  };
+  return { report, close: async () => { await client.close(); await s.close(); } };
+}
+
+const notices = (userId: string) => db.all<{ message_id: string; from_session: string; title: string; content: string; severity: string; meta_json: string; acked: number }>(
+  "SELECT message_id, from_session, title, content, severity, meta_json, acked FROM user_inbox WHERE user_id = ?1 AND network_id = ?2 AND kind = ?3 ORDER BY created_at, message_id",
+  userId, netId, MODEL_AUTH_NOTICE_KIND,
+);
+const clearNotices = () => db.run("DELETE FROM user_inbox WHERE network_id = ?1 AND kind = ?2", [netId, MODEL_AUTH_NOTICE_KIND]);
+
+beforeAll(() => {
+  process.env.COMMHUB_UPLOADS_DIR = join(dir, "uploads");
+  const boss = register(`ma_boss_${stamp}`, PW);
+  expect(boss.ok).toBe(true);
+  bossId = boss.user!.user_id; netId = boss.network_id!;
+  const nora = register(`ma_nora_${stamp}`, PW);
+  const otto = register(`ma_otto_${stamp}`, PW);
+  noraId = nora.user!.user_id; ottoId = otto.user!.user_id;
+  addNetworkMember(netId, noraId, "member", bossId, { agentAccess: "all" });
+  addNetworkMember(netId, ottoId, "member", bossId, { agentAccess: "all" });
+  // 节点主人是 nora(她铸的节点令牌 → nodes.owner_user_id),不是网络 owner boss。
+  const minted = createNetworkTokenForNode(noraId, netId, NODE, NODE_ID);
+  expect(minted.ok).toBe(true);
+  nodeTokenId = minted.token_id!;
+  const peer = createNetworkTokenForNode(ottoId, netId, PEER, PEER_ID);
+  expect(peer.ok).toBe(true);
+  peerTokenId = peer.token_id!;
+});
+beforeEach(() => { __resetModelAuthNoticesForTest(); clearNodeHealthStore(); clearNotices(); });
+afterAll(() => { clearNotices(); __resetModelAuthNoticesForTest(); clearNodeHealthStore(); });
+
+describe("#462 transition logic", () => {
+  test("bad once per entry, re-armed only by ok", () => {
+    const seq: Array<Parameters<typeof decideModelAuthNotice>[1]> = ["ok", "expired", "expired", "revoked", "unknown", undefined, "expired", "ok", "unknown", "revoked", "revoked"];
+    let mark: ReturnType<typeof decideModelAuthNotice>["mark"];
+    const fired: boolean[] = [];
+    for (const s of seq) { const d = decideModelAuthNotice(mark, s); fired.push(d.notify); mark = d.mark; }
+    expect(fired).toEqual([false, true, false, false, false, false, false, false, false, true, false]);
+  });
+
+  test("first sight is bad → notify; unknown/missing never arms", () => {
+    expect(decideModelAuthNotice(undefined, "revoked")).toEqual({ notify: true, mark: "notified" });
+    expect(decideModelAuthNotice(undefined, "unknown")).toEqual({ notify: false, mark: undefined });
+    expect(decideModelAuthNotice("notified", "unknown")).toEqual({ notify: false, mark: "notified" });
+    expect(decideModelAuthNotice("notified", undefined)).toEqual({ notify: false, mark: "notified" });
+    expect(decideModelAuthNotice("notified", "ok")).toEqual({ notify: false, mark: "armed" });
+  });
+
+  test("text names the node, the cause and the per-node re-login; never says to copy credentials", () => {
+    for (const s of ["revoked", "expired"] as const) {
+      const { title, text } = modelAuthNoticeText("node-a", s);
+      expect(title).toBe("节点登录失效");
+      expect(text).toContain("节点 node-a");
+      expect(text).toContain("codex login");
+      expect(text).toContain("CODEX_HOME=");
+      expect(text).toContain("不要拷别的节点的 auth.json");
+    }
+    expect(modelAuthNoticeText("node-a", "revoked").text).toContain("作废");
+    expect(modelAuthNoticeText("node-a", "expired").text).toContain("过期");
+  });
+});
+
+describe("#462 report_status → owner notice", () => {
+  test("ok → expired → expired → ok → expired = exactly 2 notices, owner only", async () => {
+    const n = await connectAs(NODE, noraId, nodeTokenId);
+    try {
+      for (const s of ["ok", "expired", "expired", "ok", "expired"]) await n.report(s);
+    } finally { await n.close(); }
+    const mine = notices(noraId);
+    expect(mine.length).toBe(2);
+    for (const m of mine) {
+      expect(m.from_session).toBe(NODE);
+      expect(m.title).toBe("节点登录失效");
+      expect(m.severity).toBe("warning");
+      expect(m.content).toContain(`节点 ${NODE}`);
+      expect(m.content).toContain("codex login");
+      expect(JSON.parse(m.meta_json)).toEqual({ model_auth_notice: { alias: NODE, state: "expired" } });
+    }
+    expect(notices(bossId).length).toBe(0);
+    expect(notices(ottoId).length).toBe(0);
+  });
+
+  test("a node that only ever reports ok / unknown / nothing gets no notice", async () => {
+    const n = await connectAs(NODE, noraId, nodeTokenId);
+    try {
+      for (const s of ["unknown", "ok", undefined, "unknown", "ok"]) await n.report(s);
+    } finally { await n.close(); }
+    expect(notices(noraId).length).toBe(0);
+  });
+
+  test("another node or a user login cannot trigger a notice for this node", async () => {
+    const p = await connectAs(PEER, ottoId, peerTokenId);
+    try { await p.report("revoked", NODE, NODE_ID); } finally { await p.close(); }
+    const u = await connectAs("", bossId, "", false);
+    try { await u.report("revoked", NODE, NODE_ID); } finally { await u.close(); }
+    expect(notices(noraId).length).toBe(0);
+    expect(notices(bossId).length).toBe(0);
+    expect(notices(ottoId).length).toBe(0);
+  });
+
+  test("hub restart: an unread notice suppresses the repeat; once read, the next sight notifies", async () => {
+    const n = await connectAs(NODE, noraId, nodeTokenId);
+    try {
+      await n.report("revoked");
+      expect(notices(noraId).length).toBe(1);
+      __resetModelAuthNoticesForTest(); // = Hub 重启,内存标记没了
+      await n.report("revoked");
+      expect(notices(noraId).length).toBe(1);
+      db.run("UPDATE user_inbox SET acked = 1 WHERE user_id = ?1 AND network_id = ?2 AND kind = ?3", [noraId, netId, MODEL_AUTH_NOTICE_KIND]);
+      __resetModelAuthNoticesForTest();
+      await n.report("revoked");
+      expect(notices(noraId).length).toBe(2);
+      await n.report("revoked");
+      expect(notices(noraId).length).toBe(2);
+    } finally { await n.close(); }
+  });
+
+  test("owner no longer in the network → nobody is notified", async () => {
+    db.run("DELETE FROM network_members WHERE network_id = ?1 AND user_id = ?2", [netId, noraId]);
+    try {
+      const n = await connectAs(NODE, noraId, nodeTokenId);
+      try { await n.report("expired"); } finally { await n.close(); }
+      expect(notices(noraId).length).toBe(0);
+      expect(notices(bossId).length).toBe(0);
+    } finally {
+      addNetworkMember(netId, noraId, "member", bossId, { agentAccess: "all" });
+    }
+  });
+});

package/src/model-auth-notify.ts

@@ -0,0 +1,116 @@
+// #462(#448 的子项)—— 节点模型登录失效时通知节点主人。
+//
+// 现场:codex 节点的 refresh token 被作废 / 过期后,节点自己知道(report_status.health.model_auth),
+// Hub 也会拒绝给它派活(#460 node-health-guard.ts),但**没有人被告诉** —— 主人要等到某次派活被 409
+// 才发现。这里在 report_status 收下健康报告的那一刻看 model_auth 的翻转:进入 revoked / expired 时
+// 给节点主人发**一条**消息,说是哪个节点、出了什么事、怎么重新登录。
+//
+// 🔴 只检测 + 通知。不自动换号、不拷别的节点的 auth.json、不重新 stage 凭据(owner 定的边界)。
+//
+// 去重:每次「进入坏状态」只发一条;回到 ok 才重新上膛。unknown / 没报 model_auth 既不发也不上膛
+//   (一次模型调用都还没跑的节点报 unknown,不能把它当「恢复了」,否则 expired→unknown→expired 会刷屏)。
+//   revoked ⇄ expired 互相切换不算新的翻转 —— 修法是同一条命令。
+// 状态在内存里(同 node-health-store.ts);Hub 重启后第一次看到坏状态时,先查收件人有没有**还没读**的同类
+//   消息,有就不再发 —— 否则每次升级 Hub 都会给还没修好的节点主人再发一遍。
+//
+// 收件人 = 节点主人:上报令牌绑定的 nodes.owner_user_id(RFC-036,建节点时定死),没有绑定(老令牌)就取
+//   铸这个节点令牌的用户(api_tokens.user_id —— 新令牌里两者相同)。只发给这一个人;不在本网络了就不发。
+// 怎么送:agent-notice.ts(user_inbox + /events/users/me,from_session = 节点别名)。
+
+import { db } from "./db.js";
+import { getUserNetworkRole } from "./auth.js";
+import { sendAgentNotice } from "./agent-notice.js";
+import { degradedLayers } from "./node-health-guard.js";
+import type { NodeHealth } from "./node-health-store.js";
+
+export const MODEL_AUTH_NOTICE_KIND = "node_model_auth";
+const MAX_TRACKED = 5_000;
+
+type ModelAuth = NodeHealth["model_auth"];
+/** armed = 下一次进入坏状态要发;notified = 这一段坏状态已经发过。 */
+export type NoticeMark = "armed" | "notified";
+
+export const isBadModelAuth = (s: ModelAuth): s is "revoked" | "expired" => s === "revoked" || s === "expired";
+
+/**
+ * 纯函数:上一份标记 + 这一份 model_auth → 发不发、新标记。
+ * prev = undefined 表示这个 Hub 进程还没见过这个节点(调用方另查库里有没有未读的旧通知)。
+ */
+export function decideModelAuthNotice(prev: NoticeMark | undefined, state: ModelAuth): { notify: boolean; mark: NoticeMark | undefined } {
+  if (state === "ok") return { notify: false, mark: "armed" };
+  if (isBadModelAuth(state)) {
+    if (prev === "notified") return { notify: false, mark: "notified" };
+    return { notify: true, mark: "notified" };
+  }
+  return { notify: false, mark: prev }; // unknown / 没报:保持原样
+}
+
+export function modelAuthNoticeText(alias: string, state: "revoked" | "expired"): { title: string; text: string } {
+  const what = state === "revoked"
+    ? "模型登录凭据已被作废(refresh token revoked),需要重新登录"
+    : "模型登录已过期,且没能自动刷新";
+  // 修法与派发被拒时(#460)给的同一句,别出现两套说法。
+  const hint = degradedLayers({ model_auth: state })[0]?.hint ?? "";
+  return {
+    title: "节点登录失效",
+    text: `节点 ${alias} 的${what}。在它恢复之前,派给它的任务会被拒绝。\n\n怎么修:${hint}。\n登录好之后节点会自动报告恢复,不用再做别的。`,
+  };
+}
+
+const marks = new Map<string, NoticeMark>();
+const keyOf = (networkId: string, alias: string) => `${networkId}\0${alias}`;
+
+export function __resetModelAuthNoticesForTest(): void { marks.clear(); }
+
+/** 上报令牌对应的节点主人。 */
+function ownerOfNodeToken(tokenId: string, networkId: string): string | null {
+  const row = db.get<{ user_id: string | null; owner_user_id: string | null }>(
+    `SELECT t.user_id, n.owner_user_id FROM api_tokens t LEFT JOIN nodes n ON n.node_id = t.bound_node_id
+      WHERE t.token_id = ?1 AND t.network_id = ?2`,
+    tokenId, networkId,
+  );
+  return row?.owner_user_id || row?.user_id || null;
+}
+
+function hasUnreadNotice(userId: string, networkId: string, alias: string): boolean {
+  return !!db.get(
+    "SELECT 1 AS hit FROM user_inbox WHERE user_id = ?1 AND network_id = ?2 AND from_session = ?3 AND kind = ?4 AND acked = 0 LIMIT 1",
+    userId, networkId, alias, MODEL_AUTH_NOTICE_KIND,
+  );
+}
+
+/**
+ * report_status 收下一份(已验过是本节点令牌报的)健康报告之后调用。返回这次通知到的 user_id(测试用;没发 = [])。
+ * 任何异常都吞掉:这是附带的通知,不能让一份正常的 report_status 失败。
+ */
+export function noteModelAuthHealth(input: { networkId: string; alias: string; tokenId: string; health: NodeHealth }): string[] {
+  try {
+    const { networkId, alias, tokenId, health } = input;
+    const state = health.model_auth;
+    const key = keyOf(networkId, alias);
+    const prev = marks.get(key);
+    const { notify, mark } = decideModelAuthNotice(prev, state);
+    if (mark) {
+      marks.delete(key);
+      marks.set(key, mark);
+      if (marks.size > MAX_TRACKED) marks.delete(marks.keys().next().value!);
+    }
+    if (!notify || !isBadModelAuth(state)) return [];
+
+    const owner = ownerOfNodeToken(tokenId, networkId);
+    if (!owner || !getUserNetworkRole(owner, networkId)) return [];
+    // Hub 重启后的第一眼:主人还有一条没读的同类消息 → 这是同一段坏状态,不再发。
+    if (prev === undefined && hasUnreadNotice(owner, networkId, alias)) return [];
+
+    const { title, text } = modelAuthNoticeText(alias, state);
+    const sent = sendAgentNotice({
+      networkId, userId: owner, fromAlias: alias, kind: MODEL_AUTH_NOTICE_KIND, title, text,
+      meta: { model_auth_notice: { alias, state } }, idPrefix: "dm_auth_",
+    });
+    if (!sent) return [];
+    return [owner];
+  } catch (e: any) {
+    console.error(`[model-auth-notify] ${input.alias}: ${e?.message ?? e}`);
+    return [];
+  }
+}

package/src/network-name-http.test.ts

@@ -0,0 +1,75 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { createNetworkTokenForNode, register } from "./auth.js";
+import { db } from "./db.js";
+
+const PRIVATE_DB_DIR = mkdtempSync(join(tmpdir(), "anet-network-name-http-"));
+let server: any;
+let base = "";
+let userToken = "";
+let nodeToken = "";
+let networkId = "";
+let username = "";
+
+// 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 () => {
+  process.env.COMMHUB_DB = process.env.COMMHUB_DB || join(PRIVATE_DB_DIR, "hub.db");
+  username = `network_name_${Date.now()}_${process.pid}`;
+  const registered = register(username, "NetworkName123!", undefined, "seed");
+  expect(registered.ok).toBe(true);
+  userToken = registered.token!;
+  networkId = registered.network_id!;
+  const userId = db.get<{ user_id: string }>(
+    "SELECT user_id FROM users WHERE username = ?1",
+    [username],
+  )!.user_id;
+  const minted = createNetworkTokenForNode(userId, networkId, "network-name-node");
+  expect(minted.ok).toBe(true);
+  nodeToken = minted.token!;
+  const mod: any = 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 {}
+});
+
+async function networks(token: string): Promise<any[]> {
+  const response = await fetch(`${base}/api/networks`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  expect(response.status).toBe(200);
+  const body = await response.json() as any;
+  expect(body.ok).toBe(true);
+  return body.networks;
+}
+
+describe("GET /api/networks name compatibility (#449)", () => {
+  test("utok rows expose equal non-null name and network_name", async () => {
+    const rows = await networks(userToken);
+    expect(rows).toHaveLength(1);
+    expect(rows[0].network_id).toBe(networkId);
+    // #449 is about `name` and `network_name` agreeing and being non-null.
+    // Pin them to the registered username rather than the literal "default":
+    // the auto-created network is named after its owner, so hardcoding the
+    // old literal would test the naming scheme instead of the compat shim.
+    expect(rows[0].network_name).toBe(username);
+    expect(rows[0].name).toBe(username);
+  });
+
+  test("network-bound ntok rows expose the same alias", async () => {
+    const rows = await networks(nodeToken);
+    expect(rows).toHaveLength(1);
+    expect(rows[0].network_id).toBe(networkId);
+    expect(rows[0].network_name).toBe(username);
+    expect(rows[0].name).toBe(rows[0].network_name);
+    expect(rows[0].name).not.toBeNull();
+  });
+});

package/src/network-scope.ts

@@ -0,0 +1,276 @@
+// Network-scope resolution shared by BOTH transports.
+//
+// #517: REST (server.ts) and MCP (tools.ts) each carried their own copy of
+// the "which network does this caller write to" rule. REST grew a
+// single-network fallback (POST /api/task); MCP never did — so a utok_
+// caller could read everything but write nothing, with a misleading
+// permission_denied. Extracted here (same pattern as lifecycle-guard.ts)
+// so the rule has exactly ONE implementation. If you change write-scope
+// semantics, this module is the only place — do NOT re-inline a copy in
+// server.ts or tools.ts.
+
+import { db } from "./db.js";
+import { getUserNetworkRole } from "./auth.js";
+import { isAgentRestricted, restrictedNetworkIds, usernameIsAgentAlias, visibleAgents } from "./agent-access.js";
+
+export type RestNetworkScope = {
+  networkId: string | null;
+  networkIds: string[] | null;
+  denied?: string;
+  // 多用户 Agent 权限:scope 里哪些网络对这个调用者是「只看授权 Agent」的。
+  // addNetworkScope 对这些网络 fail-closed(整网不返回);要按授权放行的路径
+  // 显式改用 addAgentNetworkScope / addOwnTrafficScope,人类数据用 addHumanNetworkScope。
+  agentRestriction?: { userId: string; username: string; networkIds: string[] };
+};
+
+type ScopeAuthCtx = { userId: string; networkId: string | null; username?: string | null };
+
+function usernameOf(userId: string, known?: string | null): string {
+  if (known) return known;
+  return db.get<{ username: string }>("SELECT username FROM users WHERE user_id = ?1", userId)?.username ?? "";
+}
+
+function withAgentRestriction(scope: RestNetworkScope, authCtx: ScopeAuthCtx): RestNetworkScope {
+  const inScope = scope.networkId ? [scope.networkId] : (scope.networkIds ?? []);
+  if (inScope.length === 0) return scope;
+  const restricted = restrictedNetworkIds(authCtx.userId).filter((id) => inScope.includes(id));
+  if (restricted.length === 0) return scope;
+  return { ...scope, agentRestriction: { userId: authCtx.userId, username: usernameOf(authCtx.userId, authCtx.username), networkIds: restricted } };
+}
+
+export function getUserNetworkIds(userId: string): string[] {
+  // JOIN networks: deleteNetwork historically left network_members rows
+  // behind (fixed alongside PR #519, but legacy DBs still carry strays).
+  // A ghost membership must neither make a single-network user look
+  // ambiguous nor let the write fallback resolve INTO a deleted network.
+  return db.all<{ network_id: string }>(
+    `SELECT m.network_id FROM network_members m
+     JOIN networks n ON n.network_id = m.network_id
+     WHERE m.user_id = ?1`,
+    userId
+  ).map((row) => row.network_id);
+}
+
+export function resolveRestNetworkScope(requested: string | null, authCtx: ScopeAuthCtx | null, isAdmin: boolean): RestNetworkScope {
+  // Legacy global token or open dev mode keeps the old global behavior.
+  if (!authCtx) return { networkId: requested || null, networkIds: null };
+
+  // Network tokens are forcibly scoped to their bound network.
+  if (authCtx.networkId) return { networkId: authCtx.networkId, networkIds: null };
+
+  // System admins may intentionally inspect all networks.
+  if (isAdmin) return { networkId: requested || null, networkIds: null };
+
+  if (requested) {
+    const role = getUserNetworkRole(authCtx.userId, requested);
+    if (!role) return { networkId: null, networkIds: [], denied: "access denied to requested network" };
+    return withAgentRestriction({ networkId: requested, networkIds: null }, authCtx);
+  }
+
+  return withAgentRestriction({ networkId: null, networkIds: getUserNetworkIds(authCtx.userId) }, authCtx);
+}
+
+function unrestrictedNetworks(scope: RestNetworkScope): string[] | null {
+  const excluded = scope.agentRestriction?.networkIds ?? [];
+  if (scope.networkId) return excluded.includes(scope.networkId) ? [] : [scope.networkId];
+  if (scope.networkIds) return scope.networkIds.filter((id) => !excluded.includes(id));
+  return null;
+}
+
+function placeholders(params: any[], values: string[]): string {
+  const start = params.length;
+  params.push(...values);
+  return values.map((_, i) => `?${start + i + 1}`).join(", ");
+}
+
+/**
+ * 默认的网络作用域 —— 对受限成员的受限网络 **fail-closed**:整网不返回。
+ * 没被逐条审过、不知道按授权怎么放行的查询,默认走这里,受限成员什么都看不到。
+ */
+export function addNetworkScope(sql: string, params: any[], scope: RestNetworkScope, column = "network_id"): string {
+  if (!scope.agentRestriction) return addHumanNetworkScope(sql, params, scope, column);
+  const allowed = unrestrictedNetworks(scope) ?? [];
+  if (allowed.length === 0) return `${sql} AND 1=0`;
+  return `${sql} AND ${column} IN (${placeholders(params, allowed)})`;
+}
+
+/**
+ * 人类数据(自己的私信收件箱、需求看板、项目、网络成员)的作用域:受限成员照常看得到
+ * 自己所在网络。只给已确认不含 Agent 内容的查询用。
+ */
+export function addHumanNetworkScope(sql: string, params: any[], scope: RestNetworkScope, column = "network_id"): string {
+  if (scope.networkId) {
+    sql += ` AND ${column} = ?${params.length + 1}`;
+    params.push(scope.networkId);
+  } else if (scope.networkIds) {
+    if (scope.networkIds.length === 0) {
+      sql += " AND 1=0";
+    } else {
+      const placeholders = scope.networkIds.map((_, i) => `?${params.length + i + 1}`).join(", ");
+      sql += ` AND ${column} IN (${placeholders})`;
+      params.push(...scope.networkIds);
+    }
+  }
+  return sql;
+}
+
+type AgentColumns = { network?: string; alias: string; nodeId?: string };
+
+/**
+ * Agent 行(sessions / nodes)的作用域:不受限的网络整网放行;受限网络只放行授权的 Agent。
+ * mode="message" 时只放行 can_message 的授权。
+ */
+export function addAgentNetworkScope(sql: string, params: any[], scope: RestNetworkScope, cols: AgentColumns, mode: "see" | "message" = "see"): string {
+  const restriction = scope.agentRestriction;
+  if (!restriction) return addHumanNetworkScope(sql, params, scope, cols.network ?? "network_id");
+  const net = cols.network ?? "network_id";
+  const parts: string[] = [];
+  const allowed = unrestrictedNetworks(scope) ?? [];
+  if (allowed.length) parts.push(`${net} IN (${placeholders(params, allowed)})`);
+  for (const networkId of restriction.networkIds) {
+    const visible = visibleAgents(restriction.userId, networkId);
+    const aliases = mode === "message" ? visible.messageAliases : visible.aliases;
+    const nodeIds = mode === "message" ? visible.messageNodeIds : visible.nodeIds;
+    const conds: string[] = [];
+    if (aliases.length) conds.push(`${cols.alias} IN (${placeholders(params, aliases)})`);
+    if (cols.nodeId && nodeIds.length) conds.push(`${cols.nodeId} IN (${placeholders(params, nodeIds)})`);
+    if (conds.length === 0) continue;
+    parts.push(`(${net} = ${placeholders(params, [networkId])} AND (${conds.join(" OR ")}))`);
+  }
+  return parts.length ? `${sql} AND (${parts.join(" OR ")})` : `${sql} AND 1=0`;
+}
+
+type TrafficColumns = { network?: string; from: string; to: string; fromNodeId?: string; toNodeId?: string };
+
+/**
+ * 任务 / inbox 这类「谁发给谁」的行:受限网络里只放行**自己**与**授权 Agent**之间的往来
+ * (from=自己 且 to=授权 Agent,或反过来)。别人(包括 owner)和同一个 Agent 的对话看不到。
+ */
+export function addOwnTrafficScope(sql: string, params: any[], scope: RestNetworkScope, cols: TrafficColumns): string {
+  const restriction = scope.agentRestriction;
+  if (!restriction) return addHumanNetworkScope(sql, params, scope, cols.network ?? "network_id");
+  const net = cols.network ?? "network_id";
+  const parts: string[] = [];
+  const allowed = unrestrictedNetworks(scope) ?? [];
+  if (allowed.length) parts.push(`${net} IN (${placeholders(params, allowed)})`);
+  if (restriction.username) {
+    for (const networkId of restriction.networkIds) {
+      // 用户名与本网络某个 Agent 的 alias 撞名时(入网时拦过,但 Agent 之后注册的 alias 拦不住),
+      // 「发给我的」无法和「发给那个 Agent 的」区分开 —— 这个网络的往来一律不放行。
+      if (usernameIsAgentAlias(networkId, restriction.username)) continue;
+      const visible = visibleAgents(restriction.userId, networkId);
+      // 先判空再生成占位符:side() 会往 params 里推值,推了又丢弃会让参数个数对不上。
+      const useNodeIds = !!(cols.fromNodeId && cols.toNodeId) && visible.nodeIds.length > 0;
+      if (visible.aliases.length === 0 && !useNodeIds) continue;
+      const side = (aliasCol: string, nodeCol?: string): string | null => {
+        const conds: string[] = [];
+        if (visible.aliases.length) conds.push(`${aliasCol} IN (${placeholders(params, visible.aliases)})`);
+        if (nodeCol && useNodeIds) conds.push(`${nodeCol} IN (${placeholders(params, visible.nodeIds)})`);
+        return conds.length ? `(${conds.join(" OR ")})` : null;
+      };
+      const toAgent = side(cols.to, cols.toNodeId)!;
+      const fromAgent = side(cols.from, cols.fromNodeId)!;
+      const me = placeholders(params, [restriction.username]);
+      parts.push(`(${net} = ${placeholders(params, [networkId])} AND ((${cols.from} = ${me} AND ${toAgent}) OR (${cols.to} = ${me} AND ${fromAgent})))`);
+    }
+  }
+  return parts.length ? `${sql} AND (${parts.join(" OR ")})` : `${sql} AND 1=0`;
+}
+
+/**
+ * #563 —— 「不同用户看到同一个节点,消息应该是一样的」。
+ *
+ * tasks 行(聊天窗口的历史 + 回复都在这张表)的作用域:受限网络里,只要成员**看得见** Agent N
+ * (直接授权或经组授权,见 visibleAgents),N 的整条时间线他都看得见 —— 不论是谁发的(包括 owner、
+ * 其他成员),也包括授权之前的历史。时间线 = 一端是看得见的 Agent,另一端是:
+ *   - 另一个看得见的 Agent;或
+ *   - 不是本网络任何 Agent 的名字(人类用户 / scheduler / hub 这类系统发送方)。
+ * 另一端是**看不见**的 Agent 的行一律不放行(不借时间线暴露看不见的节点)。
+ * 没有任何授权的成员什么都看不到(与之前一样);能不能**发**仍由 canMessageAgent 管。
+ * Agent 主动发给某个人的 user_inbox 私信不在这张表里,不受影响。
+ *
+ * 与 addOwnTrafficScope 的区别只在受限网络:那里只放行「自己 ↔ 授权 Agent」。inbox(投递队列)
+ * 仍走 addOwnTrafficScope。用户名与 Agent alias 撞名的网络照旧整网不放行(fail-closed)。
+ */
+export function addAgentTimelineScope(sql: string, params: any[], scope: RestNetworkScope, cols: Required<Pick<TrafficColumns, "from" | "to" | "fromNodeId" | "toNodeId">> & { network?: string }): string {
+  const restriction = scope.agentRestriction;
+  if (!restriction) return addHumanNetworkScope(sql, params, scope, cols.network ?? "network_id");
+  const net = cols.network ?? "network_id";
+  const parts: string[] = [];
+  const allowed = unrestrictedNetworks(scope) ?? [];
+  if (allowed.length) parts.push(`${net} IN (${placeholders(params, allowed)})`);
+  if (restriction.username) {
+    for (const networkId of restriction.networkIds) {
+      if (usernameIsAgentAlias(networkId, restriction.username)) continue;
+      const visible = visibleAgents(restriction.userId, networkId);
+      // 先判空再推参数:推了又不用的绑定参数会让 PG 报错(SQLite 会忽略)。
+      if (visible.aliases.length === 0 && visible.nodeIds.length === 0) continue;
+      const aliasIn = visible.aliases.length ? placeholders(params, visible.aliases) : null;
+      const nodeIn = visible.nodeIds.length ? placeholders(params, visible.nodeIds) : null;
+      const netP = placeholders(params, [networkId]);
+      const isVisible = (aliasCol: string, nodeCol: string): string => {
+        const conds: string[] = [];
+        if (aliasIn) conds.push(`${aliasCol} IN (${aliasIn})`);
+        if (nodeIn) conds.push(`${nodeCol} IN (${nodeIn})`);
+        return `(${conds.join(" OR ")})`;
+      };
+      // 「不是本网络任何 Agent」:没有 node_id,且 alias 不在本网络的 sessions / nodes 里。
+      const notAnAgent = (aliasCol: string, nodeCol: string): string =>
+        `(${nodeCol} IS NULL`
+        + ` AND ${aliasCol} NOT IN (SELECT alias FROM sessions WHERE network_id = ${netP} AND alias IS NOT NULL)`
+        + ` AND ${aliasCol} NOT IN (SELECT alias FROM nodes WHERE network_id = ${netP} AND alias IS NOT NULL))`;
+      const toV = isVisible(cols.to, cols.toNodeId);
+      const fromV = isVisible(cols.from, cols.fromNodeId);
+      const otherFrom = `(${fromV} OR ${notAnAgent(cols.from, cols.fromNodeId)})`;
+      const otherTo = `(${toV} OR ${notAnAgent(cols.to, cols.toNodeId)})`;
+      parts.push(`(${net} = ${netP} AND ((${toV} AND ${otherFrom}) OR (${fromV} AND ${otherTo})))`);
+    }
+  }
+  return parts.length ? `${sql} AND (${parts.join(" OR ")})` : `${sql} AND 1=0`;
+}
+
+export function singleNetworkId(scope: RestNetworkScope): string | null {
+  if (scope.networkId) return scope.networkId;
+  if (scope.networkIds?.length === 1) return scope.networkIds[0];
+  return null;
+}
+
+/**
+ * Resolve one unambiguous network for a REST write.
+ *
+ * Admin read scope is intentionally global (`networkIds=null`), so it cannot
+ * by itself express that an admin happens to have exactly one membership.
+ * Writes must not inherit that ambiguity: use the sole real membership when
+ * one exists, and keep requiring an explicit network for zero or 2+.
+ */
+export function resolveRestWriteNetworkId(
+  scope: RestNetworkScope,
+  authCtx: { userId: string; networkId: string | null } | null,
+  isAdmin: boolean,
+): string | null {
+  const scoped = singleNetworkId(scope);
+  if (scoped) return scoped;
+  if (!authCtx || !isAdmin) return null;
+  const memberships = getUserNetworkIds(authCtx.userId);
+  return memberships.length === 1 ? memberships[0] : null;
+}
+
+/**
+ * 能不能往这个网络写**面向 Agent 的东西**(派任务、改节点、排程……)。
+ * 受限成员在受限网络里恒为 false(fail-closed);给授权 Agent 发任务的路径另用
+ * canMessageAgent 单独放行,人类侧的写入(私信、需求、上传)用 canRestWriteNetworkAsHuman。
+ */
+export function canRestWriteNetwork(authCtx: { userId: string; networkId: string | null } | null, networkId: string | null, isAdmin: boolean): boolean {
+  if (!canRestWriteNetworkAsHuman(authCtx, networkId, isAdmin)) return false;
+  if (!authCtx || isAdmin || !networkId) return true;
+  return !isAgentRestricted(authCtx.userId, networkId);
+}
+
+/** 旧的「成员且不是 viewer」判据,不看 Agent 授权。只给人类侧写入用。 */
+export function canRestWriteNetworkAsHuman(authCtx: { userId: string; networkId: string | null } | null, networkId: string | null, isAdmin: boolean): boolean {
+  if (!authCtx) return true; // legacy global token or open dev mode
+  if (isAdmin) return true;
+  if (!networkId) return false;
+  const role = getUserNetworkRole(authCtx.userId, networkId);
+  return !!role && role !== "viewer";
+}