@sleep2agi/commhub-server 0.9.0-preview.6 → 0.9.0-preview.60

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

package/src/node-id-alias.test.ts

@@ -0,0 +1,188 @@
+// #1281 — 子节点生命周期工具的参数名统一（node_id ⇄ child_node_id）。
+//
+// 分叉现状（origin/main 2976adb2）：stop_node / start_node / delete_node 用
+// `child_node_id`，restart_node / update_node_config 用 `node_id`，指向同一个
+// 子节点。调用方按一个工具的习惯给另一个传就吃 -32602。修复：5 个工具都同时
+// 接受两个名字（canonical = node_id，child_node_id 兼容 alias），解析收敛到一个
+// 模块级 helper resolveNodeIdArg。
+//
+// 两向 witnessed-red（本文件即判据）：
+//   · schema 层：每个工具的**历史用名**始终 parse 成功（证明没破已发布契约），
+//     **新增别名**在修复前 parse 失败（缺必填字段）、修复后成功。
+//   · handler 层：resolveNodeIdArg 纯函数 —— 二选一至少一必填、都传须相等。
+//   · 真实 handler 路径：stop_node 用 node_id / child_node_id 都能穿到
+//     resolveDaemonForChild（不再被 node_id_required 挡），都传冲突 → node_id_conflict。
+//
+// 对 pre-fix 见红的证明方式（评审可复现）：把 tools.ts 里任一工具的
+// `...NODE_ID_ALIAS_FIELDS` 还原成原来的单名字段（如 stop_node 的
+// `child_node_id: z.string()...regex(...)`），本文件对应工具的「新增别名 parse 成功」
+// 断言立即变红 —— 证明该断言有判别力，不是恒真。
+
+import { describe, expect, test, beforeAll } from "bun:test";
+import { mkdtempSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+
+process.env.COMMHUB_DB = process.env.COMMHUB_DB || (mkdtempSync(join(tmpdir(), "anet-1281-")) + "/commhub.db");
+
+import { z } from "zod/v4";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerTools, resolveNodeIdArg } from "./tools.js";
+
+type ToolHandler = (args: any) => Promise<{ content: { type: "text"; text: string }[] }>;
+
+// Capture BOTH the raw zod shape and the handler for every tool, so the
+// schema-layer assertions run against the exact object server.tool received.
+function buildCaptured() {
+  const schemas: Record<string, any> = {};
+  const handlers: Record<string, ToolHandler> = {};
+  const server = new McpServer({ name: "t1281", version: "0" }) as any;
+  const origTool = server.tool.bind(server);
+  server.tool = (name: string, _desc: string, schema: any, handler: ToolHandler) => {
+    schemas[name] = schema; handlers[name] = handler;
+    return origTool(name, _desc, schema, handler);
+  };
+  const origRegisterTool = server.registerTool?.bind(server);
+  if (origRegisterTool) {
+    server.registerTool = (name: string, cfg: any, handler: ToolHandler) => {
+      schemas[name] = cfg?.inputSchema ?? cfg; handlers[name] = handler;
+      return origRegisterTool(name, cfg, handler);
+    };
+  }
+  registerTools(server, undefined, null, "user_1281", null, false, null);
+  return { schemas, handlers };
+}
+
+let SCHEMAS: Record<string, any> = {};
+let HANDLERS: Record<string, ToolHandler> = {};
+beforeAll(() => { const c = buildCaptured(); SCHEMAS = c.schemas; HANDLERS = c.handlers; });
+
+async function call(name: string, args: any) {
+  const r = await HANDLERS[name](args);
+  return JSON.parse(r.content[0].text);
+}
+
+// Per tool: the historically-required id name, the newly-added alias, and
+// the OTHER required fields the shape needs so a safeParse isolates the id
+// field rather than tripping on an unrelated missing field.
+const TOOLS = [
+  { name: "stop_node",          historic: "child_node_id", added: "node_id",        extra: {} },
+  { name: "start_node",         historic: "child_node_id", added: "node_id",        extra: {} },
+  { name: "delete_node",        historic: "child_node_id", added: "node_id",        extra: { confirm_alias: "some-alias" } },
+  { name: "restart_node",       historic: "node_id",       added: "child_node_id",  extra: {} },
+  { name: "update_node_config", historic: "node_id",       added: "child_node_id",  extra: { base_revision: 0, patch: {} } },
+];
+
+const VALID_ID = "node_test_1281";
+
+describe("#1281 schema layer — every lifecycle tool accepts BOTH node_id and child_node_id", () => {
+  for (const t of TOOLS) {
+    test(`${t.name}: historic name '${t.historic}' still parses (published contract intact)`, () => {
+      const shape = z.object(SCHEMAS[t.name]);
+      const r = shape.safeParse({ [t.historic]: VALID_ID, ...t.extra });
+      expect(r.success).toBe(true);
+    });
+
+    test(`${t.name}: added alias '${t.added}' parses (was -32602 pre-#1281 → RED without the fix)`, () => {
+      const shape = z.object(SCHEMAS[t.name]);
+      const r = shape.safeParse({ [t.added]: VALID_ID, ...t.extra });
+      expect(r.success).toBe(true);
+    });
+
+    test(`${t.name}: both names present + equal parses (schema layer permissive; conflict caught in handler)`, () => {
+      const shape = z.object(SCHEMAS[t.name]);
+      const r = shape.safeParse({ node_id: VALID_ID, child_node_id: VALID_ID, ...t.extra });
+      expect(r.success).toBe(true);
+    });
+  }
+});
+
+describe("#1281 resolveNodeIdArg — the single resolution helper", () => {
+  test("node_id only → resolves to node_id", () => {
+    expect(resolveNodeIdArg({ node_id: "node_a" })).toEqual({ ok: true, node_id: "node_a" });
+  });
+  test("child_node_id only → resolves to it (back-compat)", () => {
+    expect(resolveNodeIdArg({ child_node_id: "node_b" })).toEqual({ ok: true, node_id: "node_b" });
+  });
+  test("both present + EQUAL → resolves (no conflict)", () => {
+    expect(resolveNodeIdArg({ node_id: "node_c", child_node_id: "node_c" })).toEqual({ ok: true, node_id: "node_c" });
+  });
+  test("both present + DIFFERENT → node_id_conflict (catches A/B fat-finger)", () => {
+    const r = resolveNodeIdArg({ node_id: "node_a", child_node_id: "node_b" });
+    expect(r.ok).toBe(false);
+    expect((r as any).error).toBe("node_id_conflict");
+  });
+  test("neither present → node_id_required", () => {
+    const r = resolveNodeIdArg({});
+    expect(r.ok).toBe(false);
+    expect((r as any).error).toBe("node_id_required");
+  });
+});
+
+describe("#1281 real handler path — stop_node routes both names to the same place", () => {
+  // stop_node calls resolveNodeIdArg FIRST, then resolveDaemonForChild. A
+  // fabricated id has no create-request row → daemon_not_resolvable. The
+  // point is that BOTH names get PAST the id gate to that same downstream
+  // error (proving the alias flows through), and the two error branches fire.
+  test("node_id (new name) flows through → daemon_not_resolvable, NOT node_id_required", async () => {
+    const r = await call("stop_node", { node_id: VALID_ID });
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe("daemon_not_resolvable");
+  });
+  test("child_node_id (old name) flows through → daemon_not_resolvable (back-compat intact)", async () => {
+    const r = await call("stop_node", { child_node_id: VALID_ID });
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe("daemon_not_resolvable");
+  });
+  test("neither → node_id_required (before any daemon resolution)", async () => {
+    const r = await call("stop_node", { force: true });
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe("node_id_required");
+  });
+  test("both differ → node_id_conflict (before any daemon resolution)", async () => {
+    const r = await call("stop_node", { node_id: "node_a", child_node_id: "node_b" });
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe("node_id_conflict");
+  });
+});
+
+describe("app#196 —— 「解析不到 daemon」的两种情况必须给不同的话", () => {
+  // 🔴 生产实测(2026-08-28):218 个节点里 207 个是 `n_…`(有人直接
+  //    `anet node start` 起的),它们**根本没有 daemon**。原先这两种情况
+  //    打印同一句 `pass daemon_node_id explicitly` —— 对那 207 个来说,
+  //    **这句建议的前提是假的**,照着做只会走进死路。
+  const HAND_STARTED = "n_73687f17";      // 手工起的节点,真实形状
+  const DAEMON_CHILD = "node_test_1281";  // daemon 建的子节点
+
+  test("手工起的节点 → not_daemon_managed,并且**不**建议传 daemon_node_id", async () => {
+    const r = await call("stop_node", { node_id: HAND_STARTED });
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe("not_daemon_managed");
+    // 🔴 这一条是本组的核心:旧文案的那句建议**不能**再出现在这条路径上。
+    expect(r.message).not.toContain("pass daemon_node_id explicitly");
+    // 而且要告诉他真正能走的那条路。
+    expect(r.message).toContain("anet node stop");
+  });
+
+  test("daemon 建的子节点(无 create-request 行) → 仍是 daemon_not_resolvable", async () => {
+    const r = await call("stop_node", { node_id: DAEMON_CHILD });
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe("daemon_not_resolvable");
+    expect(r.message).toContain("pass daemon_node_id explicitly");
+  });
+
+  test("delete_node 走同一条判别(两个调用点不能只改一个)", async () => {
+    const r = await call("delete_node", { node_id: HAND_STARTED, confirm_alias: "x" });
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe("not_daemon_managed");
+  });
+
+  // 🔴 反向见证:两种情况必须**真的不同**。若有人把判别改成恒定一支,
+  //    上面三条里至少一条会红 —— 但那还不够明显,所以这里直接断言两者不等。
+  test("两种情况的 error 与 message 都不相同", async () => {
+    const a = await call("stop_node", { node_id: HAND_STARTED });
+    const b = await call("stop_node", { node_id: DAEMON_CHILD });
+    expect(a.error).not.toBe(b.error);
+    expect(a.message).not.toBe(b.message);
+  });
+});

package/src/node-lifecycle-controllable.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+import {
+  childNodeIdForCreateRequest,
+  buildControllableMap,
+  isLifecycleControllable,
+} from "./node-lifecycle-controllable.js";
+
+// app#196 —— 桌面端对 218 个节点里的 207 个（95%）显示了「停止/重启/删除」，
+// 而那三个工具的 schema 是 regex(/^node_[a-z0-9_-]+$/)，那 207 个是 n_ 开头，
+// 点下去只会看到一段 zod 正则原文。
+describe("childNodeIdForCreateRequest —— 推导规则", () => {
+  test("cr_ 前缀 → node_ 前缀，其余部分逐字保留", () => {
+    // 🔴 这一对是 2026-08-28 生产 hub 日志里真实的 create-node finalize 行，
+    //    不是我按注释造的。
+    expect(childNodeIdForCreateRequest("cr_59723b24-8372-4270-9b3c-1552e592a09f"))
+      .toBe("node_59723b24-8372-4270-9b3c-1552e592a09f");
+  });
+  test("不是 cr_ 开头的一律 null —— 不猜、不截断", () => {
+    expect(childNodeIdForCreateRequest("node_abc")).toBeNull();
+    expect(childNodeIdForCreateRequest("n_abc")).toBeNull();
+    expect(childNodeIdForCreateRequest("abc")).toBeNull();
+    expect(childNodeIdForCreateRequest("cr_")).toBeNull();   // 只有前缀，没有主体
+  });
+  test("非字符串输入不抛，返回 null", () => {
+    for (const v of [undefined, null, 123, {}, []]) {
+      expect(childNodeIdForCreateRequest(v as any)).toBeNull();
+    }
+  });
+});
+
+describe("isLifecycleControllable —— 判据不是 id 前缀", () => {
+  const map = buildControllableMap([
+    { request_id: "cr_aaa", daemon_node_id: "node_daemon_x" },
+    { request_id: "cr_bbb", daemon_node_id: "node_daemon_y" },
+    { request_id: "not-a-request", daemon_node_id: "node_daemon_z" },  // 应被丢弃
+  ]);
+
+  test("有创建记录的 → 可控", () => {
+    expect(isLifecycleControllable("node_aaa", null, map)).toBe(true);
+    expect(map.get("node_aaa")).toBe("node_daemon_x");
+  });
+
+  test("🔴 光有 node_ 前缀但没有创建记录 → 不可控", () => {
+    // 这条是本模块存在的理由：前缀是实现细节，不是判据。
+    expect(isLifecycleControllable("node_never_created", null, map)).toBe(false);
+  });
+
+  test("手工起的 n_ 节点 → 不可控（那 207 个）", () => {
+    expect(isLifecycleControllable("n_22b777bf", null, map)).toBe(false);
+  });
+
+  test("🔴 daemon 自己可控 —— 它在 node_create_requests 里没有记录", () => {
+    // 漏掉这条会把 3 个 daemon 从可控名单里误删。
+    expect(isLifecycleControllable("node_daemon_39bd1eeae3ee", "host_supervisor", map)).toBe(true);
+    // 正控：同一个 id 但 role 不是 host_supervisor ⇒ 仍不可控，
+    // 证明上面那条过是因为 role，不是因为 id 恰好带 node_ 前缀。
+    expect(isLifecycleControllable("node_daemon_39bd1eeae3ee", null, map)).toBe(false);
+  });
+
+  test("坏的 request_id 不会污染映射", () => {
+    expect(map.has("node_not-a-request")).toBe(false);
+    expect(map.size).toBe(2);
+  });
+});

package/src/node-lifecycle-controllable.ts

@@ -0,0 +1,51 @@
+/**
+ * app#196 —— 哪些节点能走 stop_node / restart_node / delete_node。
+ *
+ * 抽成独立模块而不是写在 /api/nodes 的路由里,因为路由里的内联逻辑测不到 ——
+ * 现有的 api-nodes-shape.test.ts 是直跑 handler 的 SQL,拿不到映射步骤。
+ * 🔴 「不可测」本身就是一个设计信号,不是测试的问题。
+ */
+
+/** 子节点 id 由创建请求 id 确定性推导。
+ *
+ * 🔴 这条规则我用真实一对验过,不是只读注释:
+ *    cr_59723b24-8372-4270-9b3c-1552e592a09f → node_59723b24-8372-4270-9b3c-…
+ *    (2026-08-28 生产 hub 日志的 `create-node finalize` 行)
+ *
+ * 非 `cr_` 开头的一律返回 null —— 不猜,不截断。 */
+export function childNodeIdForCreateRequest(requestId: unknown): string | null {
+  if (typeof requestId !== "string") return null;
+  if (!requestId.startsWith("cr_")) return null;
+  const rest = requestId.slice(3);
+  if (!rest) return null;
+  return `node_${rest}`;
+}
+
+/** 由创建记录建出「child node_id → daemon node_id」的映射。 */
+export function buildControllableMap(
+  createRequests: Array<{ request_id?: unknown; daemon_node_id?: unknown }>,
+): Map<string, string> {
+  const m = new Map<string, string>();
+  for (const cr of createRequests) {
+    const child = childNodeIdForCreateRequest(cr?.request_id);
+    if (!child) continue;
+    m.set(child, typeof cr?.daemon_node_id === "string" ? cr.daemon_node_id : "");
+  }
+  return m;
+}
+
+/** 一个节点能不能走生命周期操作。
+ *
+ * 🔴 判据**不是 id 前缀**。前缀是实现细节;判据是 node_create_requests 里真有创建记录。
+ *
+ * 例外:daemon 自己(role=host_supervisor)也能被 restart/stop,而它在
+ * node_create_requests 里**没有**记录(它不是被别的 daemon 创建的)—— 单独放行。
+ * 漏掉这一条会把可控的 daemon 判成不可控。 */
+export function isLifecycleControllable(
+  nodeId: unknown,
+  role: unknown,
+  controllable: Map<string, string>,
+): boolean {
+  if (role === "host_supervisor") return true;
+  return typeof nodeId === "string" && controllable.has(nodeId);
+}