@sleep2agi/commhub-server 0.9.0-preview.56 → 0.9.0-preview.58

package/package.json

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

package/src/db.ts

@@ -127,6 +127,9 @@ for (const col of [
   // that answers the rules-file doorbell. Sticky: set by a bound node token, never
   // cleared by reports that omit it (agent-node status-only reports do).
   { name: "rules_file_capable", def: "INTEGER NOT NULL DEFAULT 0" },
+  // Node skills view — the same session answers skills_list / skill_read on the
+  // rules-file doorbell (node-skills.ts). Sticky, bound-token only, like above.
+  { name: "skills_capable", def: "INTEGER NOT NULL DEFAULT 0" },
 ]) {
   try { db.exec(`ALTER TABLE sessions ADD COLUMN ${col.name} ${col.def}`); } catch {}
 }

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);
+});

package/src/rest-explicit-columns-http.test.ts

@@ -45,7 +45,7 @@ const GOLDEN_RESPONSE_KEYS = {
     "process_rss_mb", "process_cpu_pct", "process_uptime_seconds",
     "process_in_flight_count", "network_id", "registered_at", "updated_at",
     "node_id", "session_id", "config_path", "channels", "last_seen_at", "model",
-    "external_schedules", "rules_file_capable", "runtime", "host", "process_telemetry",
+    "external_schedules", "rules_file_capable", "skills_capable", "runtime", "host", "process_telemetry",
   ],
   task: [
     "task_id", "from_node_id", "from_name", "to_node_id", "to_name", "priority",

package/src/rest-projections.ts

@@ -19,7 +19,7 @@ export const SESSION_REST_COLUMNS = [
   "process_rss_mb", "process_cpu_pct", "process_uptime_seconds",
   "process_in_flight_count", "network_id", "registered_at", "updated_at",
   "node_id", "session_id", "config_path", "channels", "last_seen_at", "model",
-  "external_schedules", "rules_file_capable",
+  "external_schedules", "rules_file_capable", "skills_capable",
 ] as const;
 
 export const AUDIT_LOG_REST_COLUMNS = [

package/src/rules-file-duplicate-alias.test.ts

@@ -0,0 +1,234 @@
+// Duplicate-alias node rows vs the node pull/ack paths (field report).
+//
+// Re-creating a node under the same alias leaves the old `nodes` row behind, so
+// one alias can own several rows in a network. The pull/ack tools used to
+// resolve the caller by `WHERE alias = ? AND network_id = ?` + `db.get`, i.e.
+// the first row SQLite yields — the stale one. Field shape: the client queued a
+// rules-file read for the live node, the node pulled with its own (bound)
+// token, the hub looked under the stale node_id, answered `request: null`, and
+// the read timed out with only `[rules-file] doorbell received` in the node log.
+//
+// 跑法：cd server && COMMHUB_DB=/tmp/rules-dup.db bun test src/rules-file-duplicate-alias.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_rules_dup";
+const USER = "u_rules_dup_owner";
+const ALIAS = "rules-dup-node";
+// Inserted first → the row a plain `db.get` on the alias returns.
+const STALE_ID = "node_rules_dup_stale";
+const LIVE_ID = "node_rules_dup_live";
+const STALE_TOKEN = "tok_rules_dup_stale";
+const LIVE_TOKEN = "tok_rules_dup_live";
+const UNBOUND_TOKEN = "tok_rules_dup_unbound";
+
+function cleanup() {
+  try { db.run("DELETE FROM node_rules_requests WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM node_config_updates WHERE network_id = ?1", [NET]); } catch {}
+  try { db.run("DELETE FROM audit_log 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(opts: { liveSession?: boolean } = {}) {
+  db.run(
+    `INSERT INTO users (user_id, username, password_hash, role, created_at) VALUES (?1, ?2, 'x', 'user', datetime('now'))`,
+    [USER, USER],
+  );
+  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]);
+  // Stale row first (older created_at AND lower rowid), live row second.
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, created_at, updated_at) VALUES (?1, ?2, ?3, ?4, '2026-09-16 01:40:40', '2026-09-16 01:40:40')`,
+    [STALE_ID, ALIAS, ALIAS, NET],
+  );
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, created_at, updated_at) VALUES (?1, ?2, ?3, ?4, '2026-09-16 01:42:46', '2026-09-16 01:42:46')`,
+    [LIVE_ID, ALIAS, ALIAS, NET],
+  );
+  for (const [tok, bound, hash] of [
+    [STALE_TOKEN, STALE_ID, "hash_rules_dup_stale"],
+    [LIVE_TOKEN, LIVE_ID, "hash_rules_dup_live"],
+    [UNBOUND_TOKEN, null, "hash_rules_dup_unbound"],
+  ] as const) {
+    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)`,
+      [tok, USER, NET, `node:${ALIAS}`, hash, bound],
+    );
+  }
+  if (opts.liveSession !== false) {
+    db.run(
+      `INSERT INTO sessions (resume_id, alias, network_id, node_id, status, updated_at) VALUES (?1, ?2, ?3, ?4, 'idle', datetime('now'))`,
+      [`sdk-${LIVE_ID}`, ALIAS, NET, LIVE_ID],
+    );
+  }
+}
+
+type Identity = { alias: string; isNetworkToken: boolean; tokenId: string };
+const asUser: Identity = { alias: USER, isNetworkToken: false, tokenId: "tok_rules_dup_user" };
+const asLive: Identity = { alias: ALIAS, isNetworkToken: true, tokenId: LIVE_TOKEN };
+const asStale: Identity = { alias: ALIAS, isNetworkToken: true, tokenId: STALE_TOKEN };
+const asUnbound: Identity = { alias: ALIAS, isNetworkToken: true, tokenId: UNBOUND_TOKEN };
+
+async function connect(id: Identity) {
+  const server = new McpServer({ name: "rules-dup-test", version: "1" });
+  registerTools(server, undefined, NET, USER, id.alias, id.isNetworkToken, id.tokenId);
+  const client = new Client({ name: "rules-dup-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 };
+}
+
+function queuedNodeId(requestId: string): string | undefined {
+  return db.get<{ node_id: string }>("SELECT node_id FROM node_rules_requests WHERE request_id = ?1", requestId)?.node_id;
+}
+
+beforeEach(() => { cleanup(); });
+afterAll(cleanup);
+
+describe("duplicate alias — rules file pull/ack", () => {
+  test("field case: read queued for the live node_id is pulled and acked by the live node's bound token", async () => {
+    seedWorld();
+    const u = await connect(asUser);
+    const n = await connect(asLive);
+    try {
+      const enq = await u.call("read_node_rules_file", { node_id: LIVE_ID });
+      expect(enq).toMatchObject({ ok: true, op: "read" });
+      const pulled = await n.call("get_rules_file_request", {});
+      expect(pulled).toEqual({ ok: true, request: { request_id: enq.request_id, op: "read" } });
+      const ack = await n.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", file_name: "AGENTS.md", exists: true, content: "# live" });
+      expect(ack).toMatchObject({ ok: true, status: "done" });
+      expect(await u.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ status: "done", content: "# live" });
+    } finally { await u.close(); await n.close(); }
+  }, 20_000);
+
+  test("a token bound to the stale row can neither pull nor ack the live node's request", async () => {
+    seedWorld();
+    const u = await connect(asUser);
+    const stale = await connect(asStale);
+    try {
+      const enq = await u.call("read_node_rules_file", { node_id: LIVE_ID });
+      expect(await stale.call("get_rules_file_request", {})).toEqual({ ok: true, request: null });
+      expect(await stale.call("ack_rules_file_request", { request_id: enq.request_id, status: "done", content: "# forged" }))
+        .toEqual({ 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 stale.close(); }
+  }, 20_000);
+
+  test("the live token does not pull a request queued for the stale row", async () => {
+    seedWorld();
+    const u = await connect(asUser);
+    const n = await connect(asLive);
+    try {
+      await u.call("read_node_rules_file", { node_id: STALE_ID });
+      expect(await n.call("get_rules_file_request", {})).toEqual({ ok: true, request: null });
+    } finally { await u.close(); await n.close(); }
+  }, 20_000);
+
+  test("client targeting by alias queues under the row the alias's session points at", async () => {
+    seedWorld();
+    const u = await connect(asUser);
+    try {
+      const enq = await u.call("read_node_rules_file", { alias: ALIAS });
+      expect(enq).toMatchObject({ ok: true, op: "read" });
+      expect(queuedNodeId(enq.request_id)).toBe(LIVE_ID);
+      const sk = await u.call("list_node_skills", { alias: ALIAS });
+      expect(sk).toMatchObject({ ok: true });
+      expect(queuedNodeId(sk.request_id)).toBe(LIVE_ID);
+    } finally { await u.close(); }
+  }, 20_000);
+
+  test("without a session row, alias targeting falls back to the newest row", async () => {
+    seedWorld({ liveSession: false });
+    const u = await connect(asUser);
+    try {
+      const enq = await u.call("read_node_rules_file", { alias: ALIAS });
+      expect(queuedNodeId(enq.request_id)).toBe(LIVE_ID);
+    } finally { await u.close(); }
+  }, 20_000);
+
+  test("the session mapping wins over recency: alias targeting picks the older row when the session points at it", async () => {
+    seedWorld({ liveSession: false });
+    db.run(
+      `INSERT INTO sessions (resume_id, alias, network_id, node_id, status, updated_at) VALUES (?1, ?2, ?3, ?4, 'idle', datetime('now'))`,
+      [`sdk-${STALE_ID}`, ALIAS, NET, STALE_ID],
+    );
+    const u = await connect(asUser);
+    try {
+      const enq = await u.call("read_node_rules_file", { alias: ALIAS });
+      expect(queuedNodeId(enq.request_id)).toBe(STALE_ID);
+    } finally { await u.close(); }
+  }, 20_000);
+
+  test("a token bound to a node whose row is gone does not fall back to another row with its alias", async () => {
+    seedWorld();
+    db.run("UPDATE api_tokens SET bound_node_id = 'node_rules_dup_deleted' WHERE token_id = ?1", [STALE_TOKEN]);
+    const u = await connect(asUser);
+    const stale = await connect(asStale);
+    try {
+      const enq = await u.call("read_node_rules_file", { node_id: LIVE_ID });
+      expect(await stale.call("get_rules_file_request", {})).toEqual({ ok: true, request: null });
+      expect(await u.call("get_rules_file_result", { request_id: enq.request_id })).toMatchObject({ status: "pending" });
+    } finally { await u.close(); await stale.close(); }
+  }, 20_000);
+
+  test("an unbound legacy token resolves its alias to the session-mapped row", async () => {
+    seedWorld();
+    const u = await connect(asUser);
+    const n = await connect(asUnbound);
+    try {
+      const enq = await u.call("read_node_rules_file", { node_id: LIVE_ID });
+      expect(await n.call("get_rules_file_request", {})).toEqual({ ok: true, request: { request_id: enq.request_id, op: "read" } });
+    } finally { await u.close(); await n.close(); }
+  }, 20_000);
+});
+
+describe("duplicate alias — config update pull/ack", () => {
+  function queueUpdate(nodeId: string, updateId: string) {
+    db.run(
+      `INSERT INTO node_config_updates (update_id, node_id, network_id, patch_json, apply_mode, base_revision, status, created_at, created_by_token) VALUES (?1, ?2, ?3, '{"model":"m"}', 'hot', 0, 'pending', ?4, 'tok_rules_dup_user')`,
+      [updateId, nodeId, NET, Date.now()],
+    );
+  }
+
+  test("the live node's bound token pulls and acks its own pending update", async () => {
+    seedWorld();
+    queueUpdate(LIVE_ID, "cu_rules_dup_live");
+    const n = await connect(asLive);
+    try {
+      const pulled = await n.call("get_config_update", {});
+      expect(pulled.update?.update_id).toBe("cu_rules_dup_live");
+      const ack = await n.call("ack_config_update", { update_id: "cu_rules_dup_live", status: "applied", new_revision: 1 });
+      expect(ack.ok).toBe(true);
+      expect(ack.ignored).toBeUndefined();
+      expect(db.get<{ status: string }>("SELECT status FROM node_config_updates WHERE update_id = 'cu_rules_dup_live'")?.status).toBe("applied");
+    } finally { await n.close(); }
+  }, 20_000);
+
+  test("a token bound to the stale row cannot pull or ack the live node's update", async () => {
+    seedWorld();
+    queueUpdate(LIVE_ID, "cu_rules_dup_live2");
+    const stale = await connect(asStale);
+    try {
+      expect((await stale.call("get_config_update", {})).update).toBeNull();
+      await stale.call("ack_config_update", { update_id: "cu_rules_dup_live2", status: "applied", new_revision: 1 });
+      expect(db.get<{ status: string }>("SELECT status FROM node_config_updates WHERE update_id = 'cu_rules_dup_live2'")?.status).toBe("pending");
+    } finally { await stale.close(); }
+  }, 20_000);
+});

package/src/server.ts

@@ -1682,6 +1682,7 @@ return Bun.serve({
           external_schedules: externalSchedules,
           // app#225 follow-up — sqlite INTEGER 0/1 → boolean on the wire.
           rules_file_capable: s.rules_file_capable === 1,
+          skills_capable: s.skills_capable === 1,
           model: s.model ?? null,
           runtime: normalizeRuntime(s.agent),
           host: {

package/src/task-consumption.test.ts

@@ -126,6 +126,17 @@ describe("task consumed_at identity and lifecycle", () => {
     expect([...first.tasks, ...second.tasks].some((task: any) => task.task_id === "foreign-node-row")).toBe(false);
     expect((await call(handler, { from_node_id: `id_${NODE_B}`, durable_cursor: true, limit: 100 })).error).toBe("from_node_id_identity_mismatch");
   });
+  test("a legacy unbound node token is refused the durable cursor even for its own node", async () => {
+    // Pre-RFC-036 tokens carry no immutable node binding. The durable outbox
+    // cursor must stay closed to them (no bind-on-first-use); agent-node
+    // degrades to inbox-only compensation on this exact error code.
+    db.run("UPDATE api_tokens SET bound_node_id = NULL WHERE token_id = ?1", [`token_${NODE_A}`]);
+    const handler = toolsFor({ alias: NODE_A, nodeToken: true }).list_tasks;
+    expect((await call(handler, { from_node_id: `id_${NODE_A}`, durable_cursor: true, limit: 10 })).error).toBe("from_node_id_identity_mismatch");
+    expect((await call(handler, { from_node_id: `id_${NODE_B}`, durable_cursor: true, limit: 10 })).error).toBe("from_node_id_identity_mismatch");
+    const bound = db.get<{ bound_node_id: string | null }>("SELECT bound_node_id FROM api_tokens WHERE token_id = ?1", `token_${NODE_A}`);
+    expect(bound?.bound_node_id).toBeNull();
+  });
   test("terminal sequence paginates beyond 2000 and admits late completion of an old task", async () => {
     db.run(
       `INSERT INTO tasks (task_id, from_node_id, from_name, to_name, status, content, network_id, created_at)

package/src/tools.ts

@@ -719,8 +719,10 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       // no `nodes` row, and config_snapshot is persisted per node_id. Only a
       // node token bound to this same alias can set it; see the UPDATE below.
       rules_file_capable: z.literal(true).optional(),
+      // Node skills view — same doorbell, ops skills_list / skill_read.
+      skills_capable: z.literal(true).optional(),
     },
-    async ({ resume_id, alias, status, task, output, score, progress, server: srv, hostname: hn, agent: ag, project_dir: pd, version: ver, tmux_name: tmux, node_id, session_id, config_path, channels, model: mdl, node_name: nn, network_id: netId, host, process_telemetry: proc, external_schedules: externalSchedules, config_snapshot: cfgSnap, rules_file_capable: rulesFileCapable }) => {
+    async ({ resume_id, alias, status, task, output, score, progress, server: srv, hostname: hn, agent: ag, project_dir: pd, version: ver, tmux_name: tmux, node_id, session_id, config_path, channels, model: mdl, node_name: nn, network_id: netId, host, process_telemetry: proc, external_schedules: externalSchedules, config_snapshot: cfgSnap, rules_file_capable: rulesFileCapable, skills_capable: skillsCapable }) => {
       const effectiveNetId = getNetworkId(netId);
       const sessionNetId = effectiveNetId ?? "default";
       if (!callerTokenIsNetwork || !enforceNetworkId) {
@@ -926,6 +928,9 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         if (rulesFileCapable === true && callerTokenIsNetwork && callerAlias && callerAlias === effectiveAlias) {
           db.run("UPDATE sessions SET rules_file_capable = 1 WHERE resume_id = ?1", [resume_id]);
         }
+        if (skillsCapable === true && callerTokenIsNetwork && callerAlias && callerAlias === effectiveAlias) {
+          db.run("UPDATE sessions SET skills_capable = 1 WHERE resume_id = ?1", [resume_id]);
+        }
         if (host || proc) {
           db.run(
             `INSERT INTO agent_telemetry (id, network_id, resume_id, alias, hostname, ip, cpu_load_1min, cpu_cores, mem_total_gb, mem_used_gb, mem_avail_gb, disk_total_gb, disk_used_gb, disk_avail_gb, process_rss_bytes, process_rss_mb, process_cpu_pct, process_uptime_seconds, process_in_flight_count, created_at)
@@ -2977,6 +2982,51 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     },
   );
 
+  // One alias can own several `nodes` rows in a network: re-creating a node
+  // under the same alias leaves the old row behind, and `db.get` on
+  // `WHERE alias = ? AND network_id = ?` then returns whichever row SQLite
+  // happens to yield first. A field report showed the result: the client
+  // queued a rules-file read for the live node, the node pulled with its own
+  // token, the hub resolved its alias to the stale row, found nothing pending
+  // and returned `request: null` until the read timed out.
+  //
+  // resolveNodeByAlias: prefer the row the alias's session points at (sessions
+  // are UNIQUE per network+alias and carry the node_id that last reported),
+  // then the newest row. Used where only an alias is known (a client targeting
+  // by alias; unbound legacy node tokens).
+  const resolveNodeByAlias = (alias: string, networkId: string) =>
+    db.get<{ node_id: string; alias: string; network_id: string | null }>(
+      `SELECT n.node_id, n.alias, n.network_id FROM nodes n
+         LEFT JOIN sessions s ON s.alias = n.alias AND s.network_id = n.network_id AND s.node_id = n.node_id
+        WHERE n.alias = ?1 AND n.network_id = ?2
+        ORDER BY (s.node_id IS NOT NULL) DESC, n.created_at DESC, n.rowid DESC
+        LIMIT 1`,
+      alias,
+      networkId,
+    ) ?? null;
+  // resolveCallerNode: the node a network token pulls/acks for. A token bound
+  // to a node resolves to exactly that node (and never to another row that
+  // shares its alias); only unbound legacy tokens fall back to the alias.
+  // Callers have already required callerTokenIsNetwork + enforceNetworkId +
+  // callerAlias.
+  const resolveCallerNode = (): { node_id: string; network_id: string | null } | null => {
+    const bound = callerTokenId
+      ? db.get<{ bound_node_id: string | null }>(
+          "SELECT bound_node_id FROM api_tokens WHERE token_id = ?1 AND network_id = ?2",
+          callerTokenId,
+          enforceNetworkId,
+        )?.bound_node_id ?? null
+      : null;
+    if (bound) {
+      return db.get<{ node_id: string; network_id: string | null }>(
+        "SELECT node_id, network_id FROM nodes WHERE node_id = ?1 AND network_id = ?2",
+        bound,
+        enforceNetworkId,
+      ) ?? null;
+    }
+    return resolveNodeByAlias(callerAlias!, enforceNetworkId!);
+  };
+
   server.tool(
     "get_config_update",
     "Node pulls its pending config update (called from agent-node when SSE config_update doorbell arrives). RFC-024.",
@@ -3000,11 +3050,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       // Unconditional network_id filter (was previously conditional on
       // enforceNetworkId being set; the new ntok guard above guarantees
       // it's non-null so the filter is always applied).
-      const node = db.get<any>(
-        "SELECT node_id, network_id FROM nodes WHERE alias = ?1 AND network_id = ?2",
-        callerAlias,
-        enforceNetworkId,
-      );
+      const node = resolveCallerNode();
       if (!node) {
         return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, update: null }) }] };
       }
@@ -3057,11 +3103,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       // Cross-tenant guard: the ack-er must own the update being acked.
       // Resolve node by caller's alias under the enforced network.
       // Network filter is unconditional (guard above guarantees non-null).
-      const node = db.get<any>(
-        "SELECT node_id FROM nodes WHERE alias = ?1 AND network_id = ?2",
-        callerAlias,
-        enforceNetworkId,
-      );
+      const node = resolveCallerNode();
       if (!node) {
         // Silently ignore stale ack — return ok so the node doesn't retry forever.
         return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, ignored: "alias_unknown" }) }] };
@@ -3113,12 +3155,22 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   const RULES_FILE_MAX_BYTES = 256 * 1024;
   const RULES_REQUEST_STALE_MS = 60_000;
 
+  // Node skills view — skills_list / skill_read ride the same queue + doorbell.
+  // `content` carries the skill NAME for skill_read (never a path; the node
+  // validates it again against [A-Za-z0-9._-] and resolves it under its own
+  // runtime's skills roots — node-skills.ts).
+  const SKILL_NAME_RE = /^[A-Za-z0-9._-]{1,64}$/;
+  const isSkillsOp = (op: string) => op === "skills_list" || op === "skill_read";
+
   const enqueueRulesFileRequest = (
-    op: "read" | "write",
+    op: "read" | "write" | "skills_list" | "skill_read",
     a: { node_id?: string; child_node_id?: string; alias?: string; network_id?: string; content?: string },
   ) => {
     const effectiveNetId = getNetworkId(a.network_id);
-    if (!canWrite(effectiveNetId)) return writeDeniedReply(effectiveNetId, `${op} rules file`);
+    if (!canWrite(effectiveNetId)) return writeDeniedReply(effectiveNetId, isSkillsOp(op) ? `${op} node skills` : `${op} rules file`);
+    if (op === "skill_read" && (typeof a.content !== "string" || !SKILL_NAME_RE.test(a.content) || a.content === "." || a.content === "..")) {
+      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "invalid_skill_name", reason: "name must match [A-Za-z0-9._-]{1,64} and not be . or .." }) }] };
+    }
 
     // Target: a `nodes` row by node_id (original path), or — app#225 follow-up —
     // an alias. An alias resolves to its `nodes` row when there is one; otherwise
@@ -3140,21 +3192,21 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       node = resolved.row as any;
     } else {
       const scopeNet = effectiveNetId || "default";
-      const byAlias = db.get<{ node_id: string; alias: string; network_id: string | null }>(
-        "SELECT node_id, alias, network_id FROM nodes WHERE alias = ?1 AND network_id = ?2",
-        a.alias,
-        scopeNet,
-      );
+      const byAlias = resolveNodeByAlias(a.alias, scopeNet);
       if (byAlias) {
         node = byAlias;
       } else {
         const session = db.get<{ alias: string; network_id: string | null }>(
-          "SELECT alias, network_id FROM sessions WHERE alias = ?1 AND network_id = ?2 AND rules_file_capable = 1 ORDER BY updated_at DESC LIMIT 1",
+          isSkillsOp(op)
+            ? "SELECT alias, network_id FROM sessions WHERE alias = ?1 AND network_id = ?2 AND skills_capable = 1 ORDER BY updated_at DESC LIMIT 1"
+            : "SELECT alias, network_id FROM sessions WHERE alias = ?1 AND network_id = ?2 AND rules_file_capable = 1 ORDER BY updated_at DESC LIMIT 1",
           a.alias,
           scopeNet,
         );
         if (!session) {
-          return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "rules_file_target_not_found", alias: a.alias, message: "no node with this alias in the network, and no session with this alias that can serve rules files (its channel server may be too old)" }) }] };
+          return isSkillsOp(op)
+            ? { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "skills_target_not_found", alias: a.alias, message: "no node with this alias in the network, and no session with this alias that can serve its skills (its channel server may be too old)" }) }] }
+            : { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "rules_file_target_not_found", alias: a.alias, message: "no node with this alias in the network, and no session with this alias that can serve rules files (its channel server may be too old)" }) }] };
         }
         node = { node_id: `session:${session.alias}`, alias: session.alias, network_id: session.network_id };
       }
@@ -3172,8 +3224,12 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
     // 单飞 + 陈旧回收，同 update_node_config 的 F-B：节点掉线时旧行永远
     // 非终态，不回收就把这个节点锁死。
+    // Separate single-flight lanes: the client opens the rules file and the
+    // skills list together; one must not block the other.
     const inFlight = db.get<{ request_id: string; created_at: number; pulled_at: number | null }>(
-      "SELECT request_id, created_at, pulled_at FROM node_rules_requests WHERE node_id = ?1 AND status IN ('pending', 'in_progress') ORDER BY created_at DESC LIMIT 1",
+      isSkillsOp(op)
+        ? "SELECT request_id, created_at, pulled_at FROM node_rules_requests WHERE node_id = ?1 AND status IN ('pending', 'in_progress') AND op IN ('skills_list', 'skill_read') ORDER BY created_at DESC LIMIT 1"
+        : "SELECT request_id, created_at, pulled_at FROM node_rules_requests WHERE node_id = ?1 AND status IN ('pending', 'in_progress') AND op IN ('read', 'write') ORDER BY created_at DESC LIMIT 1",
       nodeId,
     );
     if (inFlight) {
@@ -3191,7 +3247,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     const networkId = node.network_id || "default";
     db.run(
       `INSERT INTO node_rules_requests (request_id, node_id, network_id, op, content, status, created_at, created_by_token) VALUES (?1, ?2, ?3, ?4, ?5, 'pending', ?6, ?7)`,
-      [requestId, nodeId, networkId, op, op === "write" ? a.content! : null, Date.now(), callerTokenId || "unknown"],
+      [requestId, nodeId, networkId, op, op === "write" || op === "skill_read" ? a.content! : null, Date.now(), callerTokenId || "unknown"],
     );
     pushEvent(node.alias, { type: "rules_file", request_id: requestId }, networkId);
     return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, request_id: requestId, op }) }] };
@@ -3220,6 +3276,29 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     async ({ node_id, child_node_id, alias, content, network_id }) => enqueueRulesFileRequest("write", { node_id, child_node_id, alias, content, network_id }),
   );
 
+  server.tool(
+    "list_node_skills",
+    "Ask a node to list the skills its runtime loads (name, scope project|user|system, display path, frontmatter description). Read-only; no path argument. Poll get_rules_file_result — content is JSON {skills:[…]}.",
+    {
+      ...NODE_ID_ALIAS_FIELDS,
+      alias: z.string().min(1).max(200).optional().describe("Target by alias instead of node_id — resolves to the node row, or to a session that reported skills_capable."),
+      network_id: z.string().max(200).optional(),
+    },
+    async ({ node_id, child_node_id, alias, network_id }) => enqueueRulesFileRequest("skills_list", { node_id, child_node_id, alias, network_id }),
+  );
+
+  server.tool(
+    "read_node_skill",
+    "Ask a node for one skill's SKILL.md by name. Read-only; the node resolves the name under its own runtime's skills roots — no path argument. Poll get_rules_file_result — content is JSON {name, scope, path_rel, description, content}.",
+    {
+      ...NODE_ID_ALIAS_FIELDS,
+      alias: z.string().min(1).max(200).optional().describe("Target by alias instead of node_id — resolves to the node row, or to a session that reported skills_capable."),
+      name: z.string().min(1).max(64).describe("Skill directory name, [A-Za-z0-9._-]."),
+      network_id: z.string().max(200).optional(),
+    },
+    async ({ node_id, child_node_id, alias, name, network_id }) => enqueueRulesFileRequest("skill_read", { node_id, child_node_id, alias, content: name, network_id }),
+  );
+
   server.tool(
     "get_rules_file_request",
     "Node pulls its oldest pending rules-file request (called from agent-node when the SSE rules_file doorbell arrives). app#225.",
@@ -3232,11 +3311,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       if (!callerAlias) {
         return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "alias_required" }) }] };
       }
-      const node = db.get<any>(
-        "SELECT node_id FROM nodes WHERE alias = ?1 AND network_id = ?2",
-        callerAlias,
-        enforceNetworkId,
-      );
+      const node = resolveCallerNode();
       // app#225 follow-up — no `nodes` row: this is a session-only target
       // (claude-code). Its queue key is `session:<alias>`, always paired with the
       // caller's network so a same-named alias in another network never matches.
@@ -3261,7 +3336,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
             request: {
               request_id: req.request_id,
               op: req.op,
-              ...(req.op === "write" ? { content: req.content ?? "" } : {}),
+              ...(req.op === "write" || req.op === "skill_read" ? { content: req.content ?? "" } : {}),
             },
           }),
         }],
@@ -3287,11 +3362,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       if (!callerAlias) {
         return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "alias_required" }) }] };
       }
-      const node = db.get<any>(
-        "SELECT node_id FROM nodes WHERE alias = ?1 AND network_id = ?2",
-        callerAlias,
-        enforceNetworkId,
-      );
+      const node = resolveCallerNode();
       const queueKey: string = node ? node.node_id : `session:${callerAlias}`;
       const req = db.get<any>(
         "SELECT request_id, node_id, network_id, status FROM node_rules_requests WHERE request_id = ?1",
@@ -3356,7 +3427,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
             status,
             file_name: row.file_name ?? null,
             exists: row.file_exists === null || row.file_exists === undefined ? null : row.file_exists === 1,
-            ...(status === "done" && row.op === "read" ? { content: row.result_content ?? "" } : {}),
+            ...(status === "done" && row.op !== "write" ? { content: row.result_content ?? "" } : {}),
             error: row.error ?? null,
             age_ms: ageMs,
           }),