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

package/src/node-request-retention.test.ts

@@ -0,0 +1,281 @@
+// node_rules_requests content retention — privacy purge of node file bytes.
+//
+// Real MCP in-process transport, same harness as rules-file-transport.test.ts.
+// Covers:
+//   1. read result is handed out on the first terminal read, still handed out to
+//      a second reader inside the grace window (the desktop app's
+//      request_in_flight → follow path), then purged: status + metadata stay,
+//      `content_purged: true` replaces content.
+//   2. a caller outside the row's network can neither read nor stamp/purge it.
+//   3. TTL sweep: >24h content cleared (stale pending flipped to timeout first),
+//      >30d rows deleted, fresh unread rows untouched.
+//   4. write payload (`content` column) is cleared; skill_read name is kept.
+//
+// 跑法：cd server && COMMHUB_DB=/tmp/nrr.db bun test src/node-request-retention.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";
+import { CONTENT_GRACE_MS, CONTENT_TTL_MS, ROW_TTL_MS, sweepNodeRequestContent } from "./node-request-retention.js";
+import { sweepRetention } from "./retention.js";
+
+const NET = "net_nrr";
+const OTHER_NET = "net_nrr_other";
+const USER = "u_nrr_owner";
+const NODE_ID = "node_nrr_claude";
+const NODE_ALIAS = "nrr-claude";
+const NODE_TOKEN = "tok_nrr_node";
+
+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 audit_log 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]);
+  }
+  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'))`,
+    [NODE_ID, NODE_ALIAS, NODE_ALIAS, NET],
+  );
+  db.run(
+    `INSERT INTO api_tokens (token_id, user_id, network_id, scope, name, token_hash, expires_at, revoked_at) VALUES (?1, ?2, ?3, 'network', ?4, ?5, NULL, NULL)`,
+    [NODE_TOKEN, USER, NET, `node:${NODE_ALIAS}`, "hash_nrr_node"],
+  );
+}
+
+type Identity = { net: string; alias: string; isNetworkToken: boolean; tokenId: string };
+const asUser: Identity = { net: NET, alias: USER, isNetworkToken: false, tokenId: "tok_nrr_user" };
+// Same human, scoped to the OTHER network: passes canWrite there, but the row
+// lives in NET — SEC-1 must answer request_not_found and touch nothing.
+const asUserOtherScope: Identity = { net: OTHER_NET, alias: USER, isNetworkToken: false, tokenId: "tok_nrr_user_other" };
+const asNode: Identity = { net: NET, alias: NODE_ALIAS, isNetworkToken: true, tokenId: NODE_TOKEN };
+// Same user, same network, a different login token: #1999 makes project-file
+// results readable only by the token that asked.
+const asUserOtherLogin: Identity = { net: NET, alias: USER, isNetworkToken: false, tokenId: "tok_nrr_user_other_login" };
+
+async function connect(id: Identity) {
+  const server = new McpServer({ name: "nrr-test", version: "1" });
+  registerTools(server, undefined, id.net, USER, id.alias, id.isNetworkToken, id.tokenId);
+  const client = new Client({ name: "nrr-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}`);
+    return JSON.parse(first.text);
+  };
+  const close = async () => { await client.close(); await server.close(); };
+  return { call, close };
+}
+
+type Row = { status: string; content: string | null; result_content: string | null; file_name: string | null; first_read_at: number | null; content_purged_at: number | null; op: string };
+const rowOf = (id: string) => db.get<Row>(
+  "SELECT status, content, result_content, file_name, first_read_at, content_purged_at, op FROM node_rules_requests WHERE request_id = ?1", id,
+);
+const ageFirstRead = (id: string, ms: number) => db.run("UPDATE node_rules_requests SET first_read_at = first_read_at - ?1 WHERE request_id = ?2", [ms, id]);
+const ageCreated = (id: string, ms: number) => db.run("UPDATE node_rules_requests SET created_at = created_at - ?1 WHERE request_id = ?2", [ms, id]);
+
+async function readRoundTrip(u: Awaited<ReturnType<typeof connect>>, n: Awaited<ReturnType<typeof connect>>, body: string) {
+  const enq = await u.call("read_node_rules_file", { node_id: NODE_ID });
+  expect(enq.ok).toBe(true);
+  await n.call("get_rules_file_request", {});
+  await n.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", file_name: "CLAUDE.md", exists: true, content: body });
+  return enq.request_id as string;
+}
+
+beforeEach(() => { cleanup(); seedWorld(); });
+afterAll(cleanup);
+
+describe("node_rules_requests — read once, purge after grace", () => {
+  test("content returned on first terminal read and to a follower inside the grace window, then purged", async () => {
+    const u = await connect(asUser);
+    const n = await connect(asNode);
+    try {
+      const body = "# secret rules\n";
+      const rid = await readRoundTrip(u, n, body);
+      expect(rowOf(rid)!.first_read_at).toBeNull();
+
+      const first = await u.call("get_rules_file_result", { request_id: rid });
+      expect(first).toMatchObject({ ok: true, status: "done", content: body, file_name: "CLAUDE.md", exists: true });
+      expect(first.content_purged).toBeUndefined();
+      const stamped = rowOf(rid)!.first_read_at;
+      expect(stamped).not.toBeNull();
+
+      // Second reader (app follow path) inside the grace window still gets it,
+      // and the stamp is NOT pushed forward (a poller can't keep it alive).
+      sweepNodeRequestContent();
+      const follower = await u.call("get_rules_file_result", { request_id: rid });
+      expect(follower.content).toBe(body);
+      expect(rowOf(rid)!.first_read_at).toBe(stamped);
+
+      ageFirstRead(rid, CONTENT_GRACE_MS + 1);
+      // Any enqueue runs the opportunistic sweep.
+      await u.call("list_node_skills", { node_id: NODE_ID });
+      const row = rowOf(rid)!;
+      expect(row.result_content).toBeNull();
+      expect(row.content_purged_at).not.toBeNull();
+      expect(row.status).toBe("done");
+      expect(row.file_name).toBe("CLAUDE.md");
+
+      const after = await u.call("get_rules_file_result", { request_id: rid });
+      expect(after).toMatchObject({ ok: true, status: "done", file_name: "CLAUDE.md", exists: true, content_purged: true });
+      expect("content" in after).toBe(false);
+    } finally { await u.close(); await n.close(); }
+  }, 20_000);
+
+  test("non-terminal polls do not stamp; a never-read result keeps its content until TTL", async () => {
+    const u = await connect(asUser);
+    const n = await connect(asNode);
+    try {
+      const enq = await u.call("read_node_rules_file", { node_id: NODE_ID });
+      expect((await u.call("get_rules_file_result", { request_id: enq.request_id })).status).toBe("pending");
+      expect(rowOf(enq.request_id)!.first_read_at).toBeNull();
+      await n.call("get_rules_file_request", {});
+      await n.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", file_name: "CLAUDE.md", exists: true, content: "x" });
+      sweepNodeRequestContent(Date.now() + CONTENT_GRACE_MS * 10);
+      expect(rowOf(enq.request_id)!.result_content).toBe("x");
+    } finally { await u.close(); await n.close(); }
+  }, 20_000);
+});
+
+describe("node_rules_requests — authorization", () => {
+  test("a caller outside the row's network gets request_not_found and cannot stamp or purge it", async () => {
+    const u = await connect(asUser);
+    const n = await connect(asNode);
+    const o = await connect(asUserOtherScope);
+    try {
+      const rid = await readRoundTrip(u, n, "# mine\n");
+      for (let i = 0; i < 3; i++) {
+        expect(await o.call("get_rules_file_result", { request_id: rid })).toMatchObject({ ok: false, error: "request_not_found" });
+      }
+      // Also pass the owner's network_id explicitly — scope is the token's, not the arg's.
+      expect((await o.call("get_rules_file_result", { request_id: rid, network_id: NET })).content).toBeUndefined();
+      expect(rowOf(rid)!.first_read_at).toBeNull();
+      sweepNodeRequestContent(Date.now() + CONTENT_GRACE_MS * 10);
+      expect(rowOf(rid)!.result_content).toBe("# mine\n");
+      // The rightful requester still gets it.
+      expect((await u.call("get_rules_file_result", { request_id: rid })).content).toBe("# mine\n");
+    } finally { await u.close(); await n.close(); await o.close(); }
+  }, 20_000);
+});
+
+describe("node_rules_requests — project files (#1999)", () => {
+  test("another login token can't read or stamp a file_read row; the requester's read starts the grace clock; path is kept", async () => {
+    const u = await connect(asUser);
+    const n = await connect(asNode);
+    const other = await connect(asUserOtherLogin);
+    try {
+      const enq = await u.call("read_node_file", { node_id: NODE_ID, path: "docs/plan.md" });
+      expect(enq.ok).toBe(true);
+      await n.call("get_rules_file_request", {});
+      const body = JSON.stringify({ path: "docs/plan.md", kind: "text", content: "TOP SECRET PLAN" });
+      await n.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", content: body });
+
+      expect(await other.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ ok: false, error: "request_not_found" });
+      expect(rowOf(enq.request_id)!.first_read_at).toBeNull();
+
+      expect((await u.call("get_rules_file_result", { request_id: enq.request_id })).content).toBe(body);
+      ageFirstRead(enq.request_id, CONTENT_GRACE_MS + 1);
+      sweepNodeRequestContent();
+      const row = rowOf(enq.request_id)!;
+      expect(row.result_content).toBeNull();
+      expect(row.content).toBe("docs/plan.md");
+      expect(await u.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ status: "done", content_purged: true });
+    } finally { await u.close(); await n.close(); await other.close(); }
+  }, 20_000);
+});
+
+describe("node_rules_requests — write payload", () => {
+  test("write body in `content` is cleared after the grace window; skill_read name is kept", async () => {
+    const u = await connect(asUser);
+    const n = await connect(asNode);
+    try {
+      const body = "# new rules with a secret\n";
+      const w = await u.call("write_node_rules_file", { node_id: NODE_ID, content: body });
+      await n.call("get_rules_file_request", {});
+      await n.call("ack_rules_file_request", { request_id: w.request_id, status: "done", file_name: "CLAUDE.md", exists: true });
+      expect(rowOf(w.request_id)!.content).toBe(body);
+
+      const s = await u.call("read_node_skill", { node_id: NODE_ID, name: "my-skill" });
+      await n.call("get_rules_file_request", {});
+      await n.call("ack_rules_file_request", { request_id: s.request_id, status: "done", content: JSON.stringify({ name: "my-skill", content: "SKILL BODY" }) });
+
+      const wr = await u.call("get_rules_file_result", { request_id: w.request_id });
+      expect(wr).toMatchObject({ status: "done", op: "write" });
+      expect(wr.content).toBeUndefined();
+      expect((await u.call("get_rules_file_result", { request_id: s.request_id })).content).toContain("SKILL BODY");
+
+      ageFirstRead(w.request_id, CONTENT_GRACE_MS + 1);
+      ageFirstRead(s.request_id, CONTENT_GRACE_MS + 1);
+      sweepNodeRequestContent();
+
+      const wRow = rowOf(w.request_id)!;
+      expect(wRow.content).toBeNull();
+      expect(wRow.content_purged_at).not.toBeNull();
+      expect(wRow.status).toBe("done");
+      const sRow = rowOf(s.request_id)!;
+      expect(sRow.result_content).toBeNull();
+      expect(sRow.content).toBe("my-skill");
+      expect(await u.call("get_rules_file_result", { request_id: w.request_id })).toMatchObject({ status: "done", op: "write", content_purged: true });
+    } finally { await u.close(); await n.close(); }
+  }, 20_000);
+});
+
+describe("node_rules_requests — TTL sweep", () => {
+  test(">24h content cleared (stale pending write expired first, so no node can pull an emptied write); >30d rows deleted; fresh rows kept", async () => {
+    const u = await connect(asUser);
+    const n = await connect(asNode);
+    try {
+      // Create everything first, age afterwards: every enqueue runs the sweep.
+      const oldRead = await readRoundTrip(u, n, "# old, never fetched\n");
+      const ancient = await readRoundTrip(u, n, "# ancient\n");
+      const fresh = await readRoundTrip(u, n, "# fresh, never fetched\n");
+      // A write the node never pulled (offline for a day). Enqueued last so
+      // single-flight doesn't refuse it.
+      const w = await u.call("write_node_rules_file", { node_id: NODE_ID, content: "# stale write body\n" });
+      expect(w.ok).toBe(true);
+      ageCreated(oldRead, CONTENT_TTL_MS + 60_000);
+      ageCreated(ancient, ROW_TTL_MS + 60_000);
+      ageCreated(w.request_id, CONTENT_TTL_MS + 60_000);
+
+      const r = sweepRetention();
+      expect(r.nodeRequests.deleted).toBe(1);
+      expect(r.nodeRequests.timedOut).toBe(1);
+      expect(r.nodeRequests.purged).toBe(2);
+
+      expect(rowOf(ancient)).toBeNull();
+      const o = rowOf(oldRead)!;
+      expect(o.result_content).toBeNull();
+      expect(o.status).toBe("done");
+      expect(o.file_name).toBe("CLAUDE.md");
+      expect(rowOf(fresh)!.result_content).toBe("# fresh, never fetched\n");
+
+      const wr = rowOf(w.request_id)!;
+      expect(wr.status).toBe("timeout");
+      expect(wr.content).toBeNull();
+      // The node coming back must not receive the emptied write.
+      expect(await n.call("get_rules_file_request", {})).toEqual({ ok: true, request: null });
+
+      expect(await u.call("get_rules_file_result", { request_id: oldRead })).toMatchObject({ status: "done", content_purged: true });
+
+      // Idempotent.
+      const again = sweepNodeRequestContent();
+      expect(again).toEqual({ timedOut: 0, purged: 0, deleted: 0 });
+    } finally { await u.close(); await n.close(); }
+  }, 20_000);
+});

package/src/node-request-retention.ts

@@ -0,0 +1,120 @@
+// node_rules_requests content retention (privacy).
+//
+// The rules-file / skills (and project-folder) queue carries **node file
+// contents** through the hub: `result_content` holds what the node sent back
+// (CLAUDE.md / AGENTS.md, SKILL.md, directory listings, file bodies) and
+// `content` holds write payloads (the full new rules file). Before this module
+// nothing ever cleared or deleted those rows — every file anyone ever opened in
+// the desktop app stayed in the hub DB forever.
+//
+// Policy (metadata — status, op, file_name, file_exists, error, timestamps,
+// requester — is kept for audit; only file bytes are dropped):
+//
+//   1. Read-once + grace: the first time an authorized requester reads a
+//      TERMINAL result (done/failed/timeout) the row is stamped `first_read_at`.
+//      CONTENT_GRACE_MS later the content is purged. Not immediate, because the
+//      desktop app has a real second-reader path: when enqueue is rejected with
+//      `request_in_flight` the app FOLLOWS the existing request id
+//      (requestIdToFollow → waitForRulesFileResult, NodeRulesSection /
+//      NodeSkillsSection / NodeFilesSection). Two windows (or a remount) polling
+//      the same request reach terminal within one poll interval (≤ 3 s) of each
+//      other; an immediate purge would hand the second one `done` with no
+//      content and NodeRulesSection would load an EMPTY editor (`content ?? ''`)
+//      that a Save would then write back to the node. 60 s is 20× the slowest
+//      poll interval.
+//   2. TTL: anything older than CONTENT_TTL_MS gets its content purged whether
+//      or not anyone ever read it (e.g. the app was closed mid-request). A
+//      still-pending/in_progress row that old is first flipped to `timeout`, so
+//      a node that comes back after a day can never pull a write whose payload
+//      was just nulled (it would otherwise receive `content: ""` and write an
+//      empty rules file).
+//   3. Rows older than ROW_TTL_MS are deleted outright.
+//   4. Run logs (op = logs_tail) are stricter: read-once with NO grace — the
+//      first authorized terminal read purges them in the same call
+//      (purgeLogsResultNow), because the app never follows another request's
+//      logs result (it simply asks again) and a process log is the most
+//      sensitive thing on this queue. Unread terminal results are purged after
+//      LOGS_CONTENT_TTL_MS (the requester closed the page). The filter JSON in
+//      `content` (it can hold a user-typed grep) goes with it.
+//
+// Every statement is bounded (LIMIT via `request_id IN (SELECT … LIMIT n)` —
+// SQLite's UPDATE/DELETE … LIMIT needs a compile flag we don't control) and
+// uses an index (idx_nrr_created / idx_nrr_first_read). It runs
+// opportunistically on enqueue and on terminal reads, from a one-shot timer
+// armed at the first terminal read, and from the hourly retention sweeper
+// (retention.ts) — so the first sweep after deploy also clears every old row
+// that predates this module.
+
+import { db } from "./db.js";
+
+export const CONTENT_GRACE_MS = 60_000;
+export const CONTENT_TTL_MS = 24 * 60 * 60 * 1000;
+export const ROW_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+export const SWEEP_BATCH = 500;
+export const LOGS_CONTENT_TTL_MS = 5 * 60 * 1000;
+
+export type NodeRequestSweepResult = { timedOut: number; purged: number; deleted: number };
+
+// `content` is only a file body for op=write. For skill_read / file_read it is
+// the skill name / relative path the requester asked for — audit metadata, kept.
+// For logs_tail it is the filter JSON, which may carry a user-typed grep — purged.
+const PURGE_SET =
+  "result_content = NULL, content = CASE WHEN op IN ('write', 'logs_tail') THEN NULL ELSE content END, content_purged_at = ?1";
+
+function purgeWhere(where: string, params: (string | number)[], now: number): number {
+  const r = db.run(
+    `UPDATE node_rules_requests SET ${PURGE_SET} WHERE request_id IN (SELECT request_id FROM node_rules_requests WHERE content_purged_at IS NULL AND ${where} LIMIT ${SWEEP_BATCH})`,
+    [now, ...params],
+  );
+  return r.changes ?? 0;
+}
+
+export function sweepNodeRequestContent(now: number = Date.now()): NodeRequestSweepResult {
+  const out: NodeRequestSweepResult = { timedOut: 0, purged: 0, deleted: 0 };
+  try {
+    // Delete first so rows past the row TTL aren't pointlessly purged, then
+    // expire stale non-terminal rows, then purge.
+    out.deleted = db.run(
+      `DELETE FROM node_rules_requests WHERE request_id IN (SELECT request_id FROM node_rules_requests WHERE created_at < ?1 LIMIT ${SWEEP_BATCH})`,
+      [now - ROW_TTL_MS],
+    ).changes ?? 0;
+    const ttlCutoff = now - CONTENT_TTL_MS;
+    out.timedOut = db.run(
+      `UPDATE node_rules_requests SET status = 'timeout', acked_at = ?1, error = ?2 WHERE request_id IN (SELECT request_id FROM node_rules_requests WHERE created_at < ?3 AND status IN ('pending', 'in_progress') LIMIT ${SWEEP_BATCH})`,
+      [now, "expired by retention sweep (node never answered)", ttlCutoff],
+    ).changes ?? 0;
+    // ?1 = now (PURGE_SET), ?2… = where params.
+    out.purged += purgeWhere("first_read_at IS NOT NULL AND first_read_at <= ?2 AND status IN ('done', 'failed', 'timeout')", [now - CONTENT_GRACE_MS], now);
+    out.purged += purgeWhere("created_at < ?2 AND status IN ('done', 'failed', 'timeout')", [ttlCutoff], now);
+    out.purged += purgeWhere("op = 'logs_tail' AND created_at < ?2 AND status IN ('done', 'failed', 'timeout')", [now - LOGS_CONTENT_TTL_MS], now);
+  } catch (e: any) {
+    console.log(`[commhub retention] node_rules_requests sweep failed: ${e?.message ?? e}`);
+  }
+  return out;
+}
+
+/** Called by get_rules_file_result AFTER the requester passed every auth check
+ *  and only for a terminal status. Stamps the first terminal read, arms a
+ *  one-shot purge for after the grace window, and reports whether this row's
+ *  content is already gone. */
+export function noteTerminalResultRead(requestId: string, now: number = Date.now()): { purged: boolean } {
+  const r = db.run(
+    "UPDATE node_rules_requests SET first_read_at = ?1 WHERE request_id = ?2 AND first_read_at IS NULL",
+    [now, requestId],
+  );
+  if ((r.changes ?? 0) > 0) {
+    const t = setTimeout(() => { sweepNodeRequestContent(); }, CONTENT_GRACE_MS + 1_000);
+    (t as any).unref?.();
+  }
+  const row = db.get<{ content_purged_at: number | null }>(
+    "SELECT content_purged_at FROM node_rules_requests WHERE request_id = ?1",
+    requestId,
+  );
+  return { purged: row?.content_purged_at != null };
+}
+
+/** Run-log results are read-once: called by get_rules_file_result right after it
+ *  handed a terminal logs_tail result to its (authorized) requester. */
+export function purgeLogsResultNow(requestId: string, now: number = Date.now()): void {
+  db.run(`UPDATE node_rules_requests SET ${PURGE_SET} WHERE request_id = ?2 AND op = 'logs_tail' AND content_purged_at IS NULL`, [now, requestId]);
+}

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

@@ -0,0 +1,209 @@
+// Node skills view — list_node_skills / read_node_skill ride the rules-file
+// queue + doorbell (ops skills_list / skill_read).
+//
+// Hub-side contract verified here:
+//   1. report_status { skills_capable: true } is sticky and set only by the
+//      session's own bound node token.
+//   2. list_node_skills / read_node_skill reach a session with no nodes row by
+//      alias; the node pulls with its own token; read carries the skill NAME
+//      (never a path) in the pulled request; results come back through
+//      get_rules_file_result for both ops.
+//   3. Bad skill names are refused before any request row exists.
+//   4. A session that can serve rules files but did not report skills_capable is
+//      refused up front for skills ops (skills_target_not_found).
+//   5. Separate single-flight lanes: a pending rules read does not block a skills
+//      list and vice versa; a second skills request while one is pending is refused.
+//   6. Network isolation and foreign acks are ignored.
+//
+// 跑法：cd server && COMMHUB_DB=/tmp/skills-session.db bun test src/node-skills-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_skills_session";
+const OTHER_NET = "net_skills_session_other";
+const USER = "u_skills_session_owner";
+const SESSION_ALIAS = "skills-session-cc";
+const SESSION_RESUME = "cc-skills-session-1";
+const OTHER_ALIAS = "skills-session-peer";
+const NODE_ROW_ALIAS = "skills-session-noderow";
+const NODE_ROW_ID = "node_skills_session_noderow";
+const T_SESSION = "tok_skills_session_cc";
+const T_PEER = "tok_skills_session_peer";
+const T_OTHER_NET_SAME_ALIAS = "tok_skills_session_other_net";
+const T_NODE_ROW = "tok_skills_session_noderow";
+
+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 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) => db.run(
+    `INSERT INTO api_tokens (token_id, user_id, network_id, scope, name, token_hash, expires_at, revoked_at) VALUES (?1, ?2, ?3, 'network', ?4, ?5, NULL, NULL)`,
+    [id, USER, net, `node:${alias}`, `hash_${id}`],
+  );
+  tok(T_SESSION, NET, SESSION_ALIAS);
+  tok(T_PEER, NET, OTHER_ALIAS);
+  tok(T_OTHER_NET_SAME_ALIAS, OTHER_NET, SESSION_ALIAS);
+  tok(T_NODE_ROW, NET, NODE_ROW_ALIAS);
+  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'))`,
+    [NODE_ROW_ID, NODE_ROW_ALIAS, NODE_ROW_ALIAS, NET],
+  );
+}
+
+type Identity = { net: string; alias: string; isNetworkToken: boolean; tokenId: string };
+const asUser: Identity = { net: NET, alias: USER, isNetworkToken: false, tokenId: "tok_skills_session_user" };
+const asOtherNetUser: Identity = { net: OTHER_NET, alias: USER, isNetworkToken: false, tokenId: "tok_skills_session_user2" };
+const asSession: Identity = { net: NET, alias: SESSION_ALIAS, isNetworkToken: true, tokenId: T_SESSION };
+const asPeer: Identity = { net: NET, alias: OTHER_ALIAS, isNetworkToken: true, tokenId: T_PEER };
+const asOtherNetSameAlias: Identity = { net: OTHER_NET, alias: SESSION_ALIAS, isNetworkToken: true, tokenId: T_OTHER_NET_SAME_ALIAS };
+const asNodeRow: Identity = { net: NET, alias: NODE_ROW_ALIAS, isNetworkToken: true, tokenId: T_NODE_ROW };
+
+async function connect(id: Identity) {
+  const server = new McpServer({ name: "skills-session-test", version: "1" });
+  registerTools(server, undefined, id.net, USER, id.alias, id.isNetworkToken, id.tokenId);
+  const client = new Client({ name: "skills-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)}`);
+    return JSON.parse(first.text);
+  };
+  const close = async () => { await client.close(); await server.close(); };
+  return { call, close };
+}
+
+const capable = (alias: string, net = NET) =>
+  db.get<{ c: number }>("SELECT skills_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 registerSession(id: Identity, alias: string, resume: string, flag: boolean) {
+  const c = await connect(id);
+  try {
+    return await c.call("report_status", { resume_id: resume, alias, status: "idle", agent: "claude-code", ...(flag ? { rules_file_capable: true, skills_capable: true } : {}) });
+  } finally { await c.close(); }
+}
+
+beforeEach(() => { cleanup(); seedWorld(); });
+afterAll(cleanup);
+
+async function reportRulesOnly(id: Identity, alias: string, resume: string) {
+  const c = await connect(id);
+  try { return await c.call("report_status", { resume_id: resume, alias, status: "idle", agent: "claude-code", rules_file_capable: true }); }
+  finally { await c.close(); }
+}
+
+describe("skills_capable is set only by the session's own node token", () => {
+  test("bound token sets it; a report without it does not clear it; a peer cannot set it", async () => {
+    await registerSession(asSession, SESSION_ALIAS, SESSION_RESUME, true);
+    expect(capable(SESSION_ALIAS)).toBe(1);
+    await registerSession(asSession, SESSION_ALIAS, SESSION_RESUME, false);
+    expect(capable(SESSION_ALIAS)).toBe(1);
+    const r = await registerSession(asPeer, SESSION_ALIAS, SESSION_RESUME, true);
+    expect(r).toMatchObject({ ok: false });
+  }, 20_000);
+});
+
+describe("list / read by alias reach a session with no nodes row", () => {
+  test("list round trip: enqueue → pull (no content) → ack JSON → result carries it", async () => {
+    await registerSession(asSession, SESSION_ALIAS, SESSION_RESUME, true);
+    const u = await connect(asUser);
+    const s = await connect(asSession);
+    try {
+      const enq = await u.call("list_node_skills", { alias: SESSION_ALIAS });
+      expect(enq).toMatchObject({ ok: true, op: "skills_list" });
+      const pulled = await s.call("get_rules_file_request", {});
+      expect(pulled.request).toEqual({ request_id: enq.request_id, op: "skills_list" });
+      const payload = JSON.stringify({ skills: [{ name: "ship", scope: "project", path_rel: ".claude/skills/ship/SKILL.md", description: "d" }] });
+      expect(await s.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", file_name: "skills", exists: true, content: payload })).toMatchObject({ ok: true, status: "done" });
+      const res = await u.call("get_rules_file_result", { request_id: enq.request_id });
+      expect(res).toMatchObject({ ok: true, op: "skills_list", status: "done", content: payload });
+    } finally { await u.close(); await s.close(); }
+  }, 20_000);
+
+  test("read round trip: the pulled request carries the skill name only", async () => {
+    await registerSession(asSession, SESSION_ALIAS, SESSION_RESUME, true);
+    const u = await connect(asUser);
+    const s = await connect(asSession);
+    try {
+      const enq = await u.call("read_node_skill", { alias: SESSION_ALIAS, name: "ship" });
+      expect(enq).toMatchObject({ ok: true, op: "skill_read" });
+      const pulled = await s.call("get_rules_file_request", {});
+      expect(pulled.request).toEqual({ request_id: enq.request_id, op: "skill_read", content: "ship" });
+      const payload = JSON.stringify({ name: "ship", scope: "project", path_rel: ".claude/skills/ship/SKILL.md", description: "d", content: "# ship" });
+      await s.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", file_name: "ship", 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);
+
+  test("bad names are refused before any row is written", async () => {
+    await registerSession(asSession, SESSION_ALIAS, SESSION_RESUME, true);
+    const u = await connect(asUser);
+    try {
+      for (const name of ["..", ".", "../CLAUDE.md", "a/b", "a b"]) {
+        expect(await u.call("read_node_skill", { alias: SESSION_ALIAS, name })).toMatchObject({ ok: false, error: "invalid_skill_name" });
+      }
+      expect(rowCount()).toBe(0);
+    } finally { await u.close(); }
+  }, 20_000);
+
+  test("rules-capable but not skills-capable → skills_target_not_found, no row", async () => {
+    await reportRulesOnly(asSession, SESSION_ALIAS, SESSION_RESUME);
+    const u = await connect(asUser);
+    try {
+      expect(await u.call("list_node_skills", { alias: SESSION_ALIAS })).toMatchObject({ ok: false, error: "skills_target_not_found" });
+      expect(rowCount()).toBe(0);
+      expect(await u.call("read_node_rules_file", { alias: SESSION_ALIAS })).toMatchObject({ ok: true });
+    } finally { await u.close(); }
+  }, 20_000);
+});
+
+describe("single-flight lanes", () => {
+  test("a pending rules read does not block a skills list; a second skills request is refused", async () => {
+    await registerSession(asSession, SESSION_ALIAS, SESSION_RESUME, true);
+    const u = await connect(asUser);
+    try {
+      expect(await u.call("read_node_rules_file", { alias: SESSION_ALIAS })).toMatchObject({ ok: true });
+      const list = await u.call("list_node_skills", { alias: SESSION_ALIAS });
+      expect(list).toMatchObject({ ok: true });
+      expect(await u.call("read_node_skill", { alias: SESSION_ALIAS, name: "ship" })).toMatchObject({ ok: false, error: "request_in_flight", existing_request_id: list.request_id });
+      expect(await u.call("read_node_rules_file", { alias: SESSION_ALIAS })).toMatchObject({ ok: false, error: "request_in_flight" });
+    } finally { await u.close(); }
+  }, 20_000);
+});
+
+describe("isolation", () => {
+  test("same alias in another network neither pulls nor acks; a peer's ack is ignored", async () => {
+    await registerSession(asSession, SESSION_ALIAS, SESSION_RESUME, true);
+    const u = await connect(asUser);
+    const other = await connect(asOtherNetSameAlias);
+    const peer = await connect(asPeer);
+    try {
+      const enq = await u.call("list_node_skills", { 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({ ok: true, ignored: "unknown_or_foreign_request" });
+      expect(await peer.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", content: "{}" })).toMatchObject({ ok: true, 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);
+});