@sleep2agi/commhub-server 0.9.0-preview.8 → 0.9.0-preview.80

package/src/node-attrs.test.ts

@@ -0,0 +1,217 @@
+// Node display attributes — team / tags / display_name (Vincent 目标第 3 条).
+//
+// These are HUB-SIDE DISPLAY attributes. Following the `avatar_url` (#462)
+// precedent they are deliberately NOT part of the RFC-024 config-apply
+// pipeline: agent-node has nothing to consume, so pushing them through
+// config revision/ack would ring a doorbell for a field the node does not
+// understand and could wedge the config revision.
+//
+// They DO need concurrency protection (two dashboards editing the same
+// node), which `avatar_url` lacks. Hence a dedicated `attrs_revision` CAS
+// that is independent of `config_revision` — editing a tag must never bump
+// the node's *config* revision.
+//
+// Every test drives the REAL HTTP endpoint against a booted server, not a
+// helper: the contract under test is the wire shape + status codes.
+//
+// NOTE (test isolation): this file boots its own Bun.serve, same pattern as
+// uploads-http.test.ts / api-host-supervisors-fallback.test.ts. Those files
+// are per-file runs by design (single-process module-singleton conflict,
+// tracked in #434) — run this file on its own.
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+
+const tmpDb = join(mkdtempSync(join(tmpdir(), "anet-attrs-")), "commhub.db");
+process.env.COMMHUB_DB ||= tmpDb;
+const PORT = 23000 + Math.floor(Math.random() * 1500);
+process.env.PORT = String(PORT);
+process.env.HOST = "127.0.0.1";
+
+const { db } = await import("./db.js");
+const { issueUserToken } = await import("./auth.js");
+const { bootServer } = await import("./server.js");
+
+const BASE = `http://127.0.0.1:${PORT}`;
+const NET = "net_attrs";
+const USER = "u_attrs";
+/** A node row seeded the way a PRE-MIGRATION row looks: none of the new
+ *  columns are written, so they are NULL / default at read time. */
+const LEGACY_NODE = "node_attrs_legacy";
+const LEGACY_ALIAS = "attrs-legacy-node";
+
+let token = "";
+let server: { stop: (force?: boolean) => void } | null = null;
+
+// 30s 而不是 bun 默认的 5s:这个 hook 跑 register()(KDF)+bootServer(),
+// 本机空载基线 ~620ms,而 2026-08-17 与 2026-08-31 两次 CI 上它被 5s 上限打死
+// (0 pass / 1 fail / Ran 1 test —— 见 #928、#1627)。5247ms 是**被截断的下界**,
+// 不是测量值,所以余量按基线的 ~48x 取,而不是按那个数取。
+beforeAll(async () => {
+  db.run(`INSERT INTO users (user_id, username, password_hash, role) VALUES (?1, 'attrs-user', 'x', 'user')`, [USER]);
+  db.run(`INSERT INTO networks (network_id, network_name, owner_id) VALUES (?1, 'attrs-net', ?2)`, [NET, USER]);
+  db.run(`INSERT INTO network_members (network_id, user_id, role) VALUES (?1, ?2, 'owner')`, [NET, USER]);
+  // Legacy row: only the columns that existed before this change.
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, runtime, model, network_id)
+     VALUES (?1, 'attrs-legacy', ?2, 'claude-agent-sdk', 'claude-sonnet-4-6', ?3)`,
+    [LEGACY_NODE, LEGACY_ALIAS, NET],
+  );
+  token = issueUserToken(USER, "attrs-test").token;
+  server = bootServer({ port: PORT, hostname: "127.0.0.1" }) as never;
+  await new Promise((r) => setTimeout(r, 120));
+}, 30_000);
+
+afterAll(() => {
+  try { server?.stop(true); } catch { /* already down */ }
+});
+
+async function putAttrs(ref: string, body: unknown) {
+  const res = await fetch(`${BASE}/api/nodes/${encodeURIComponent(ref)}/attrs?network_id=${NET}`, {
+    method: "PUT",
+    headers: { "Content-Type": "application/json", Authorization: `Bearer ${token}` },
+    body: JSON.stringify(body),
+  });
+  return { status: res.status, json: (await res.json()) as Record<string, unknown> };
+}
+
+async function listNodes() {
+  const res = await fetch(`${BASE}/api/nodes?network_id=${NET}`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  const j = (await res.json()) as { nodes?: Array<Record<string, unknown>> };
+  return j.nodes ?? [];
+}
+
+describe("node display attrs — backward compatibility with existing rows", () => {
+  test("a pre-migration node row still lists fine; new fields read as empty, not missing/throwing", async () => {
+    const rows = await listNodes();
+    const row = rows.find((r) => r.node_id === LEGACY_NODE);
+    expect(row).toBeDefined();
+    // Must not blow up and must not omit the keys — the dashboard reads
+    // them unconditionally.
+    expect(row!).toHaveProperty("display_name");
+    expect(row!).toHaveProperty("team");
+    expect(row!).toHaveProperty("tags");
+    expect(row!.display_name ?? null).toBeNull();
+    expect(row!.team ?? null).toBeNull();
+    // tags normalises to an empty array rather than null/undefined so the
+    // dashboard can `.map()` without a guard.
+    expect(row!.tags).toEqual([]);
+    expect(row!.attrs_revision).toBe(0);
+  });
+});
+
+describe("node display attrs — write then read back", () => {
+  test("PUT sets display_name/team/tags, bumps attrs_revision, and GET /api/nodes reflects it", async () => {
+    const w = await putAttrs(LEGACY_ALIAS, {
+      base_attrs_revision: 0,
+      display_name: "研发一号机",
+      team: "platform",
+      tags: ["prod", "gpu"],
+    });
+    expect(w.status).toBe(200);
+    expect(w.json.ok).toBe(true);
+    expect(w.json.attrs_revision).toBe(1);
+
+    const row = (await listNodes()).find((r) => r.node_id === LEGACY_NODE)!;
+    expect(row.display_name).toBe("研发一号机");
+    expect(row.team).toBe("platform");
+    expect(row.tags).toEqual(["prod", "gpu"]);
+    expect(row.attrs_revision).toBe(1);
+  });
+
+  test("editing attrs does NOT touch config_revision (display vs config are separate revisions)", async () => {
+    const before = db.get<{ config_revision: number }>(
+      "SELECT config_revision FROM nodes WHERE node_id = ?1", LEGACY_NODE)!.config_revision ?? 0;
+    const w = await putAttrs(LEGACY_ALIAS, { base_attrs_revision: 1, team: "infra" });
+    expect(w.status).toBe(200);
+    const after = db.get<{ config_revision: number }>(
+      "SELECT config_revision FROM nodes WHERE node_id = ?1", LEGACY_NODE)!.config_revision ?? 0;
+    expect(after).toBe(before);
+  });
+
+  test("partial patch leaves untouched fields alone", async () => {
+    const row = (await listNodes()).find((r) => r.node_id === LEGACY_NODE)!;
+    // team was just changed to 'infra'; display_name/tags must survive.
+    expect(row.team).toBe("infra");
+    expect(row.display_name).toBe("研发一号机");
+    expect(row.tags).toEqual(["prod", "gpu"]);
+  });
+});
+
+describe("node display attrs — CAS concurrency guard", () => {
+  test("stale base_attrs_revision → 409 with the current revision, and NO write happens", async () => {
+    const before = (await listNodes()).find((r) => r.node_id === LEGACY_NODE)!;
+    const stale = await putAttrs(LEGACY_ALIAS, {
+      base_attrs_revision: 0, // deliberately stale
+      team: "should-not-land",
+    });
+    expect(stale.status).toBe(409);
+    expect(stale.json.ok).toBe(false);
+    expect(stale.json.error).toBe("attrs_revision_conflict");
+    expect(stale.json.current_attrs_revision).toBe(before.attrs_revision);
+
+    const after = (await listNodes()).find((r) => r.node_id === LEGACY_NODE)!;
+    expect(after.team).toBe(before.team); // unchanged
+    expect(after.attrs_revision).toBe(before.attrs_revision);
+  });
+});
+
+describe("node display attrs — untrusted input is narrowed at the boundary", () => {
+  test("tags: non-strings dropped, blanks dropped, duplicates folded, count + length capped", async () => {
+    const cur = (await listNodes()).find((r) => r.node_id === LEGACY_NODE)!.attrs_revision as number;
+    const w = await putAttrs(LEGACY_ALIAS, {
+      base_attrs_revision: cur,
+      tags: [
+        "keep",
+        "keep", // duplicate
+        "  spaced  ", // trimmed
+        "",
+        "   ",
+        42,
+        null,
+        { evil: true },
+        ["nested"],
+        "x".repeat(200), // over-long → dropped or truncated, never stored raw
+      ],
+    });
+    expect(w.status).toBe(200);
+    const tags = (await listNodes()).find((r) => r.node_id === LEGACY_NODE)!.tags as string[];
+    expect(Array.isArray(tags)).toBe(true);
+    expect(tags).toContain("keep");
+    expect(tags).toContain("spaced");
+    // one "keep", no junk, nothing absurdly long
+    expect(tags.filter((t) => t === "keep")).toHaveLength(1);
+    expect(tags.every((t) => typeof t === "string" && t.length > 0 && t.length <= 64)).toBe(true);
+    expect(tags.some((t) => t.includes("evil") || t.includes("nested"))).toBe(false);
+  });
+
+  test("display_name/team: non-string values are rejected, not coerced", async () => {
+    const cur = (await listNodes()).find((r) => r.node_id === LEGACY_NODE)!.attrs_revision as number;
+    const bad = await putAttrs(LEGACY_ALIAS, { base_attrs_revision: cur, team: { not: "a string" } });
+    expect(bad.status).toBe(400);
+    expect(bad.json.ok).toBe(false);
+  });
+});
+
+describe("node display attrs — auth + scope", () => {
+  test("no token → 401, and the row is untouched", async () => {
+    const before = (await listNodes()).find((r) => r.node_id === LEGACY_NODE)!;
+    const res = await fetch(`${BASE}/api/nodes/${LEGACY_ALIAS}/attrs?network_id=${NET}`, {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ base_attrs_revision: before.attrs_revision, team: "hijack" }),
+    });
+    expect(res.status).toBe(401);
+    const after = (await listNodes()).find((r) => r.node_id === LEGACY_NODE)!;
+    expect(after.team).toBe(before.team);
+  });
+
+  test("unknown node ref → 404", async () => {
+    const r = await putAttrs("no-such-node-ref", { base_attrs_revision: 0, team: "x" });
+    expect(r.status).toBe(404);
+  });
+});

package/src/node-create-request-status-http.test.ts

@@ -0,0 +1,92 @@
+// 桌面向导要看得到 daemon 回的失败原因:GET /api/node-create-requests?request_id=…
+// 承重:① 只在调用者的网络作用域里能读到(别的网络 → 404,与不存在同形);② 无用户上下文 401;③ 缺参 400;
+// ④ 回的是 daemon ack 写进去的 status/error 原文。
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const PRIVATE_DB_DIR = mkdtempSync(join(tmpdir(), "anet-create-request-status-"));
+process.env.COMMHUB_DB ||= join(PRIVATE_DB_DIR, "hub.db");
+
+let server: ReturnType<typeof Bun.serve>;
+let base = "";
+let aToken = "", bToken = "", aNet = "", bNet = "";
+const MASTER_TOKEN = "legacy-master-token-for-test";
+
+const get = async (path: string, token: string) => {
+  const r = await fetch(`${base}${path}`, { headers: { Authorization: `Bearer ${token}` } });
+  return { status: r.status, body: await r.json() as any };
+};
+
+beforeAll(async () => {
+  process.env.COMMHUB_AUTH_TOKEN ||= MASTER_TOKEN;
+  const { db } = await import("./db.js");
+  const { register } = await import("./auth.js");
+  const stamp = Date.now();
+  const admin = register(`cr_admin_${stamp}`, "CrAdmin-Strong-1!");
+  expect(admin.ok).toBe(true);
+  const a = register(`cr_a_${stamp}`, "CrA-Strong-1!");
+  const b = register(`cr_b_${stamp}`, "CrB-Strong-1!");
+  expect(a.ok && b.ok).toBe(true);
+  aToken = a.token!; bToken = b.token!; aNet = a.network_id!; bNet = b.network_id!;
+  const uid = (name: string) => db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", name)!.user_id;
+  for (const id of [uid(`cr_a_${stamp}`), uid(`cr_b_${stamp}`)]) {
+    expect(db.get<{ role: string }>("SELECT role FROM users WHERE user_id = ?1", id)?.role).toBe("user");
+  }
+  db.run(
+    `INSERT INTO node_create_requests
+       (request_id, daemon_node_id, child_name, network_id, runtime, model, flags_json, env_keys, status, child_token_id, created_at, created_by_token, acked_at, error)
+     VALUES ('cr_a_failed', 'node_daemon_a', 'vansin-go', ?1, 'opencode-cli', NULL, '{}', '[]', 'failed', NULL, ?2, 'tok', ?2,
+             'opencode-cli package entrypoint verification currently requires Linux')`,
+    [aNet, Date.now()],
+  );
+  db.run(
+    `INSERT INTO node_create_requests
+       (request_id, daemon_node_id, child_name, network_id, runtime, model, flags_json, env_keys, status, child_token_id, created_at, created_by_token)
+     VALUES ('cr_b_pending', 'node_daemon_b', 'other', ?1, 'codex-app-server', NULL, '{}', '[]', 'pending', NULL, ?2, 'tok')`,
+    [bNet, Date.now()],
+  );
+  const mod = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+});
+
+afterAll(() => {
+  try { server?.stop(true); } catch {}
+  try { rmSync(PRIVATE_DB_DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("GET /api/node-create-requests?request_id=", () => {
+  test("A reads her own failed request with the daemon's error verbatim", async () => {
+    const { status, body } = await get("/api/node-create-requests?request_id=cr_a_failed", aToken);
+    expect(status).toBe(200);
+    expect(body.ok).toBe(true);
+    expect(body.request).toMatchObject({
+      request_id: "cr_a_failed", child_name: "vansin-go", runtime: "opencode-cli", status: "failed",
+      error: "opencode-cli package entrypoint verification currently requires Linux",
+    });
+  });
+  test("🔴 B cannot read A's request — 404, same shape as nonexistent", async () => {
+    const other = await get("/api/node-create-requests?request_id=cr_a_failed", bToken);
+    const missing = await get("/api/node-create-requests?request_id=cr_nope", bToken);
+    expect(other.status).toBe(404);
+    expect(missing.status).toBe(404);
+    expect(other.body).toEqual(missing.body);
+  });
+  test("pending request reads as pending with no error", async () => {
+    const { body } = await get("/api/node-create-requests?request_id=cr_b_pending", bToken);
+    expect(body.request.status).toBe("pending");
+    expect(body.request.error).toBeNull();
+  });
+  test("missing request_id → 400", async () => {
+    const { status, body } = await get("/api/node-create-requests", aToken);
+    expect(status).toBe(400);
+    expect(body.error).toBe("request_id_required");
+  });
+  test("legacy master token (no user context) → 401", async () => {
+    const { status, body } = await get("/api/node-create-requests?request_id=cr_a_failed", MASTER_TOKEN);
+    expect(status).toBe(401);
+    expect(body.error).toBe("auth_required");
+  });
+});

package/src/node-files-transport.test.ts

@@ -0,0 +1,344 @@
+// Project folder view — list_node_files / read_node_file ride the rules-file
+// queue + doorbell (ops files_list / file_read).
+//
+// Hub-side contract verified here:
+//   1. report_status { files_capable: true } is sticky and set only by the
+//      session's own node token (bound or legacy-unbound, same rule as skills).
+//   2. Both tools reach a session with no nodes row by alias; the pulled
+//      request carries the normalized RELATIVE path; results come back through
+//      get_rules_file_result.
+//   3. Absolute paths, `..`, `~`, drive letters, backslashes and NUL are refused
+//      before any request row exists (the node re-checks; this is the first wall).
+//   4. A node token may not enqueue a files op (it would read another node's
+//      disk), and only the token that asked may read a files result.
+//   5. A token bound to node A never pulls or acks node B's files request; an
+//      unbound legacy token falls back to its alias exactly as it does for skills.
+//   6. Its own single-flight lane; rules-capable-only sessions are refused.
+//   7. Files acks may carry up to 1 MiB (escaped JSON of a 256 KiB file); rules
+//      acks keep their 256 KiB cap.
+//
+// 跑法：cd server && COMMHUB_DB=/tmp/files-transport.db bun test src/node-files-transport.test.ts
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { db } from "./db.js";
+import { registerTools } from "./tools.js";
+
+const NET = "net_files_session";
+const OTHER_NET = "net_files_session_other";
+const USER = "u_files_session_owner";
+const SESSION_ALIAS = "files-session-cc";
+const SESSION_RESUME = "cc-files-session-1";
+const PEER_ALIAS = "files-session-peer";
+const NODE_A = "files-node-a";
+const NODE_B = "files-node-b";
+const NODE_A_ID = "node_files_a";
+const NODE_B_ID = "node_files_b";
+const LEGACY_ALIAS = "files-node-legacy";
+const LEGACY_ID = "node_files_legacy";
+const T_SESSION = "tok_files_session_cc";
+const T_PEER = "tok_files_session_peer";
+const T_OTHER_NET_SAME_ALIAS = "tok_files_session_other_net";
+const T_A = "tok_files_node_a";
+const T_B = "tok_files_node_b";
+const T_LEGACY = "tok_files_node_legacy";
+
+function cleanup() {
+  for (const net of [NET, OTHER_NET]) {
+    try { db.run("DELETE FROM node_rules_requests WHERE network_id = ?1", [net]); } catch {}
+    try { db.run("DELETE FROM rename_txn WHERE network_id = ?1", [net]); } catch {}
+    try { db.run("DELETE FROM sessions WHERE network_id = ?1", [net]); } catch {}
+    try { db.run("DELETE FROM nodes WHERE network_id = ?1", [net]); } catch {}
+    try { db.run("DELETE FROM api_tokens WHERE network_id = ?1", [net]); } catch {}
+    try { db.run("DELETE FROM network_members WHERE network_id = ?1", [net]); } catch {}
+    try { db.run("DELETE FROM networks WHERE network_id = ?1", [net]); } catch {}
+  }
+  try { db.run("DELETE FROM users WHERE user_id = ?1", [USER]); } catch {}
+}
+
+function seedWorld() {
+  db.run(`INSERT INTO users (user_id, username, password_hash, role, created_at) VALUES (?1, ?2, 'x', 'user', datetime('now'))`, [USER, USER]);
+  for (const net of [NET, OTHER_NET]) {
+    db.run(`INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?2, ?3, datetime('now'))`, [net, net, USER]);
+    db.run(`INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, 'owner', datetime('now'))`, [USER, net]);
+  }
+  const tok = (id: string, net: string, alias: string, bound: string | null = null) => db.run(
+    `INSERT INTO api_tokens (token_id, user_id, network_id, scope, name, token_hash, expires_at, revoked_at, bound_node_id) VALUES (?1, ?2, ?3, 'network', ?4, ?5, NULL, NULL, ?6)`,
+    [id, USER, net, `node:${alias}`, `hash_${id}`, bound],
+  );
+  const node = (id: string, alias: string) => db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, created_at, updated_at) VALUES (?1, ?2, ?3, ?4, datetime('now'), datetime('now'))`,
+    [id, alias, alias, NET],
+  );
+  node(NODE_A_ID, NODE_A);
+  node(NODE_B_ID, NODE_B);
+  node(LEGACY_ID, LEGACY_ALIAS);
+  tok(T_SESSION, NET, SESSION_ALIAS);
+  tok(T_PEER, NET, PEER_ALIAS);
+  tok(T_OTHER_NET_SAME_ALIAS, OTHER_NET, SESSION_ALIAS);
+  tok(T_A, NET, NODE_A, NODE_A_ID);
+  tok(T_B, NET, NODE_B, NODE_B_ID);
+  tok(T_LEGACY, NET, LEGACY_ALIAS, null);
+}
+
+type Identity = { net: string; alias: string; isNetworkToken: boolean; tokenId: string };
+const asUser: Identity = { net: NET, alias: USER, isNetworkToken: false, tokenId: "tok_files_session_user" };
+const asUserOtherLogin: Identity = { net: NET, alias: USER, isNetworkToken: false, tokenId: "tok_files_session_user_other_login" };
+const asSession: Identity = { net: NET, alias: SESSION_ALIAS, isNetworkToken: true, tokenId: T_SESSION };
+const asPeer: Identity = { net: NET, alias: PEER_ALIAS, isNetworkToken: true, tokenId: T_PEER };
+const asOtherNetSameAlias: Identity = { net: OTHER_NET, alias: SESSION_ALIAS, isNetworkToken: true, tokenId: T_OTHER_NET_SAME_ALIAS };
+const asA: Identity = { net: NET, alias: NODE_A, isNetworkToken: true, tokenId: T_A };
+const asB: Identity = { net: NET, alias: NODE_B, isNetworkToken: true, tokenId: T_B };
+const asLegacy: Identity = { net: NET, alias: LEGACY_ALIAS, isNetworkToken: true, tokenId: T_LEGACY };
+
+async function connect(id: Identity) {
+  const server = new McpServer({ name: "files-session-test", version: "1" });
+  registerTools(server, undefined, id.net, USER, id.alias, id.isNetworkToken, id.tokenId);
+  const client = new Client({ name: "files-session-client", version: "1" });
+  const [ct, st] = InMemoryTransport.createLinkedPair();
+  await server.connect(st);
+  await client.connect(ct);
+  const call = async (name: string, args: Record<string, unknown>) => {
+    const r: any = await client.callTool({ name, arguments: args });
+    const first = r.content?.[0];
+    if (!first || first.type !== "text") throw new Error(`no text result from ${name}: ${JSON.stringify(r).slice(0, 300)}`);
+    try { return JSON.parse(first.text); } catch { return { raw: first.text, isError: r.isError === true }; }
+  };
+  const close = async () => { await client.close(); await server.close(); };
+  return { call, close };
+}
+
+const capable = (alias: string, net = NET) =>
+  db.get<{ c: number }>("SELECT files_capable AS c FROM sessions WHERE alias = ?1 AND network_id = ?2", alias, net)?.c;
+const rowCount = () => db.get<{ n: number }>("SELECT COUNT(*) AS n FROM node_rules_requests WHERE network_id = ?1", NET)!.n;
+
+async function report(id: Identity, alias: string, resume: string, flags: Record<string, true>) {
+  const c = await connect(id);
+  try { return await c.call("report_status", { resume_id: resume, alias, status: "idle", agent: "claude-code", ...flags }); }
+  finally { await c.close(); }
+}
+const ALL_FLAGS = { rules_file_capable: true, skills_capable: true, files_capable: true } as const;
+
+beforeEach(() => { cleanup(); seedWorld(); });
+afterAll(cleanup);
+
+describe("files_capable is set only by the session's own node token", () => {
+  test("own token sets it; a later report without it does not clear it; a peer cannot set it", async () => {
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, ALL_FLAGS);
+    expect(capable(SESSION_ALIAS)).toBe(1);
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, {});
+    expect(capable(SESSION_ALIAS)).toBe(1);
+    const r = await report(asPeer, SESSION_ALIAS, SESSION_RESUME, ALL_FLAGS);
+    expect(r).toMatchObject({ ok: false });
+    // A user login cannot set it either.
+    await report(asUser, PEER_ALIAS, "cc-files-user-report", ALL_FLAGS);
+    expect(capable(PEER_ALIAS) ?? 0).toBe(0);
+  }, 20_000);
+
+  test("a stale process whose report is rewritten to a renamed alias does not grant that alias the flag", async () => {
+    const NEW_ALIAS = "files-session-renamed";
+    db.run(
+      `INSERT INTO rename_txn (txn_id, network_id, old_alias, new_alias, status, committed_at) VALUES ('txn_files_rename', ?1, ?2, ?3, 'committed', datetime('now'))`,
+      [NET, PEER_ALIAS, NEW_ALIAS],
+    );
+    // Token still carries the old alias; the hub rewrites the report to NEW_ALIAS.
+    const r = await report(asPeer, PEER_ALIAS, "cc-files-renamed", ALL_FLAGS);
+    expect(r.ok).toBe(true);
+    expect(db.get<{ n: number }>("SELECT COUNT(*) AS n FROM sessions WHERE alias = ?1 AND network_id = ?2", NEW_ALIAS, NET)!.n).toBe(1);
+    expect(capable(NEW_ALIAS)).toBe(0);
+  }, 20_000);
+});
+
+describe("list / read by alias reach a session with no nodes row", () => {
+  test("list: pulled request carries the normalized relative path; result comes back", async () => {
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, ALL_FLAGS);
+    const u = await connect(asUser);
+    const s = await connect(asSession);
+    try {
+      const enq = await u.call("list_node_files", { alias: SESSION_ALIAS, path: "./src//lib/" });
+      expect(enq).toMatchObject({ ok: true, op: "files_list" });
+      const pulled = await s.call("get_rules_file_request", {});
+      expect(pulled.request).toEqual({ request_id: enq.request_id, op: "files_list", content: "src/lib" });
+      const payload = JSON.stringify({ path: "src/lib", entries: [{ name: "a.ts", type: "file", size: 3, mtime: 1 }], truncated: false, total: 1 });
+      expect(await s.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", file_name: "files", exists: true, content: payload })).toMatchObject({ ok: true, status: "done" });
+      expect(await u.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ ok: true, op: "files_list", status: "done", content: payload });
+    } finally { await u.close(); await s.close(); }
+  }, 20_000);
+
+  test("list with no path targets the root (empty content)", async () => {
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, ALL_FLAGS);
+    const u = await connect(asUser);
+    const s = await connect(asSession);
+    try {
+      const enq = await u.call("list_node_files", { alias: SESSION_ALIAS });
+      expect((await s.call("get_rules_file_request", {})).request).toEqual({ request_id: enq.request_id, op: "files_list", content: "" });
+    } finally { await u.close(); await s.close(); }
+  }, 20_000);
+
+  test("read round trip", async () => {
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, ALL_FLAGS);
+    const u = await connect(asUser);
+    const s = await connect(asSession);
+    try {
+      const enq = await u.call("read_node_file", { alias: SESSION_ALIAS, path: "docs/README.md" });
+      expect(enq).toMatchObject({ ok: true, op: "file_read" });
+      expect((await s.call("get_rules_file_request", {})).request).toEqual({ request_id: enq.request_id, op: "file_read", content: "docs/README.md" });
+      const payload = JSON.stringify({ path: "docs/README.md", name: "README.md", kind: "text", size: 6, content: "# hi\n" });
+      await s.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", file_name: "README.md", exists: true, content: payload });
+      expect(await u.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ status: "done", content: payload });
+    } finally { await u.close(); await s.close(); }
+  }, 20_000);
+});
+
+describe("path validation happens before any row is written", () => {
+  test("absolute, .., ~, drive letters, backslashes, NUL, and an empty read path are refused", async () => {
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, ALL_FLAGS);
+    const u = await connect(asUser);
+    try {
+      const bad = ["/etc/passwd", "../outside", "a/../../b", "src/..", "~/.ssh/id_rsa", "C:/Windows", "a\\b", "..\\x", "a\u0000b", "x".repeat(1025)];
+      for (const path of bad) {
+        // Over-long paths are stopped by the zod schema (an MCP input error); the rest by invalid_path.
+        const r = await u.call("read_node_file", { alias: SESSION_ALIAS, path });
+        expect(r.ok).not.toBe(true);
+        if (path.length <= 1024) expect(r).toMatchObject({ ok: false, error: "invalid_path" });
+        const l = await u.call("list_node_files", { alias: SESSION_ALIAS, path });
+        expect(l.ok).not.toBe(true);
+      }
+      expect(await u.call("read_node_file", { alias: SESSION_ALIAS, path: "/" })).toMatchObject({ ok: false, error: "invalid_path" });
+      expect(await u.call("read_node_file", { alias: SESSION_ALIAS, path: "./" })).toMatchObject({ ok: false, error: "invalid_path" });
+      expect(rowCount()).toBe(0);
+    } finally { await u.close(); }
+  }, 20_000);
+});
+
+describe("who may ask, and who may read the answer", () => {
+  test("a node token cannot enqueue a files op on another node (or itself)", async () => {
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, ALL_FLAGS);
+    const a = await connect(asA);
+    try {
+      expect(await a.call("list_node_files", { alias: SESSION_ALIAS })).toMatchObject({ ok: false, error: "node_token_cannot_browse_files" });
+      expect(await a.call("read_node_file", { node_id: NODE_B_ID, path: ".env" })).toMatchObject({ ok: false, error: "node_token_cannot_browse_files" });
+      expect(await a.call("list_node_files", { node_id: NODE_A_ID })).toMatchObject({ ok: false, error: "node_token_cannot_browse_files" });
+      expect(rowCount()).toBe(0);
+    } finally { await a.close(); }
+  }, 20_000);
+
+  test("only the token that asked can read a files result; node tokens never can", async () => {
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, ALL_FLAGS);
+    const u = await connect(asUser);
+    const other = await connect(asUserOtherLogin);
+    const s = await connect(asSession);
+    const a = await connect(asA);
+    try {
+      const enq = await u.call("read_node_file", { alias: SESSION_ALIAS, path: "notes.txt" });
+      await s.call("get_rules_file_request", {});
+      await s.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", content: JSON.stringify({ path: "notes.txt", kind: "text", content: "x" }) });
+      expect(await u.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ ok: true, status: "done" });
+      expect(await other.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ ok: false, error: "request_not_found" });
+      expect(await a.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ ok: false, error: "request_not_found" });
+      // The serving session itself cannot read the stored result back through the client tool either.
+      expect(await s.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ ok: false, error: "request_not_found" });
+    } finally { await u.close(); await other.close(); await s.close(); await a.close(); }
+  }, 20_000);
+
+  test("rules/skills results stay readable by any writer of the network (unchanged)", async () => {
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, ALL_FLAGS);
+    const u = await connect(asUser);
+    const other = await connect(asUserOtherLogin);
+    try {
+      const enq = await u.call("list_node_skills", { alias: SESSION_ALIAS });
+      expect(await other.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ ok: true, status: "pending" });
+    } finally { await u.close(); await other.close(); }
+  }, 20_000);
+});
+
+describe("a token bound to node A cannot touch node B's files request", () => {
+  test("B's request: A pulls nothing, A's ack is ignored, B pulls and acks it", async () => {
+    const u = await connect(asUser);
+    const a = await connect(asA);
+    const b = await connect(asB);
+    try {
+      const enq = await u.call("read_node_file", { node_id: NODE_B_ID, path: "secret-plan.md" });
+      expect(enq).toMatchObject({ ok: true });
+      expect((await a.call("get_rules_file_request", {})).request).toBeNull();
+      expect(await a.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", content: "{\"forged\":true}" })).toMatchObject({ ok: true, ignored: "unknown_or_foreign_request" });
+      expect(await u.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ status: "pending" });
+      expect((await b.call("get_rules_file_request", {})).request).toEqual({ request_id: enq.request_id, op: "file_read", content: "secret-plan.md" });
+      expect(await b.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", content: "{}" })).toMatchObject({ ok: true, status: "done" });
+    } finally { await u.close(); await a.close(); await b.close(); }
+  }, 20_000);
+
+  test("same alias in another network neither pulls nor acks; a peer's ack is ignored", async () => {
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, ALL_FLAGS);
+    const u = await connect(asUser);
+    const other = await connect(asOtherNetSameAlias);
+    const peer = await connect(asPeer);
+    try {
+      const enq = await u.call("list_node_files", { alias: SESSION_ALIAS });
+      expect((await other.call("get_rules_file_request", {})).request).toBeNull();
+      expect(await other.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", content: "{}" })).toMatchObject({ ignored: "unknown_or_foreign_request" });
+      expect(await peer.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", content: "{}" })).toMatchObject({ ignored: "unknown_or_foreign_request" });
+      expect(await u.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ status: "pending" });
+    } finally { await u.close(); await other.close(); await peer.close(); }
+  }, 20_000);
+
+  test("an unbound legacy token gets what skills gives it: alias fallback pull + ack, and it can set its own flag", async () => {
+    const u = await connect(asUser);
+    const legacy = await connect(asLegacy);
+    try {
+      await report(asLegacy, LEGACY_ALIAS, `sdk-${LEGACY_ID}`, ALL_FLAGS);
+      expect(capable(LEGACY_ALIAS)).toBe(1);
+      const skills = await u.call("list_node_skills", { node_id: LEGACY_ID });
+      const files = await u.call("list_node_files", { node_id: LEGACY_ID, path: "src" });
+      expect(skills).toMatchObject({ ok: true });
+      expect(files).toMatchObject({ ok: true });
+      const first = (await legacy.call("get_rules_file_request", {})).request;
+      const second = (await legacy.call("get_rules_file_request", {})).request;
+      expect([first.request_id, second.request_id].sort()).toEqual([skills.request_id, files.request_id].sort());
+      expect(await legacy.call("ack_rules_file_request", { request_id: files.request_id, status: "done", content: "{}" })).toMatchObject({ ok: true, status: "done" });
+      expect(await legacy.call("ack_rules_file_request", { request_id: skills.request_id, status: "done", content: "{}" })).toMatchObject({ ok: true, status: "done" });
+    } finally { await u.close(); await legacy.close(); }
+  }, 20_000);
+});
+
+describe("lanes, capability gate and ack size", () => {
+  test("files has its own single-flight lane", async () => {
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, ALL_FLAGS);
+    const u = await connect(asUser);
+    try {
+      expect(await u.call("read_node_rules_file", { alias: SESSION_ALIAS })).toMatchObject({ ok: true });
+      expect(await u.call("list_node_skills", { alias: SESSION_ALIAS })).toMatchObject({ ok: true });
+      const list = await u.call("list_node_files", { alias: SESSION_ALIAS });
+      expect(list).toMatchObject({ ok: true });
+      expect(await u.call("read_node_file", { alias: SESSION_ALIAS, path: "a.txt" })).toMatchObject({ ok: false, error: "request_in_flight", existing_request_id: list.request_id });
+    } finally { await u.close(); }
+  }, 20_000);
+
+  test("rules+skills capable but not files capable → files_target_not_found, no row", async () => {
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, { rules_file_capable: true, skills_capable: true });
+    const u = await connect(asUser);
+    try {
+      expect(await u.call("list_node_files", { alias: SESSION_ALIAS })).toMatchObject({ ok: false, error: "files_target_not_found" });
+      expect(rowCount()).toBe(0);
+    } finally { await u.close(); }
+  }, 20_000);
+
+  test("a files ack may carry up to 1 MiB; a rules ack keeps its 256 KiB cap", async () => {
+    await report(asSession, SESSION_ALIAS, SESSION_RESUME, ALL_FLAGS);
+    const u = await connect(asUser);
+    const s = await connect(asSession);
+    try {
+      const big = JSON.stringify({ path: "big.txt", kind: "text", content: "\n".repeat(256 * 1024) });
+      expect(big.length).toBeGreaterThan(256 * 1024);
+      const f = await u.call("read_node_file", { alias: SESSION_ALIAS, path: "big.txt" });
+      const r = await u.call("read_node_rules_file", { alias: SESSION_ALIAS });
+      await s.call("get_rules_file_request", {});
+      await s.call("get_rules_file_request", {});
+      expect(await s.call("ack_rules_file_request", { request_id: f.request_id, status: "done", content: big })).toMatchObject({ ok: true, status: "done" });
+      expect(await s.call("ack_rules_file_request", { request_id: r.request_id, status: "done", content: "x".repeat(256 * 1024 + 1) })).toMatchObject({ ok: false, error: "content_too_large" });
+      const tooBig = await s.call("ack_rules_file_request", { request_id: r.request_id, status: "done", content: "x".repeat(1024 * 1024 + 1) });
+      expect(tooBig.ok).not.toBe(true);
+    } finally { await u.close(); await s.close(); }
+  }, 20_000);
+});