@sleep2agi/commhub-server 0.9.0-preview.4 → 0.9.0-preview.40

package/src/node-attrs-validate.ts

@@ -0,0 +1,88 @@
+// Boundary validation for node DISPLAY attributes (display_name / team /
+// tags). Mirrors `avatar-validate.ts` in spirit: this is the only place
+// that decides what a client is allowed to store, and it trusts nothing.
+//
+// Two different postures on purpose:
+//
+//   display_name / team — SCALAR fields the user typed. A wrong TYPE here
+//     is a client bug, so it is REJECTED (400) rather than coerced: silently
+//     turning `{}` into "[object Object]" would persist garbage the user
+//     never typed and can't explain.
+//
+//   tags — a LIST. Same reasoning as the `channels` patch in tools.ts: the
+//     wire contract wants junk dropped instead of failing the whole request,
+//     so one fat-fingered entry from a dashboard doesn't 400 the save. Each
+//     element is narrowed independently (typeof → trim → length cap →
+//     dedup), so nothing non-string can reach the database.
+
+/** Max stored length of display_name / team. */
+export const MAX_ATTR_LEN = 120;
+/** Max stored length of a single tag. */
+export const MAX_TAG_LEN = 64;
+/** Max number of tags kept per node. */
+export const MAX_TAGS = 16;
+
+export type ScalarAttrResult =
+  | { ok: true; value: string | null }
+  | { ok: false; reason: string };
+
+/**
+ * Narrow an optional scalar display attribute.
+ *   undefined      → not part of this patch (caller leaves the column alone)
+ *   null / ""      → explicit clear
+ *   non-string     → rejected (never coerced)
+ *   over-long      → rejected (the user should see it, not silently lose text)
+ */
+export function validateScalarAttr(raw: unknown, field: string): ScalarAttrResult {
+  if (raw === undefined) return { ok: true, value: null };
+  if (raw === null) return { ok: true, value: null };
+  if (typeof raw !== "string") {
+    return { ok: false, reason: `${field} must be a string or null` };
+  }
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return { ok: true, value: null };
+  if (trimmed.length > MAX_ATTR_LEN) {
+    return { ok: false, reason: `${field} exceeds ${MAX_ATTR_LEN} characters` };
+  }
+  // Control characters would corrupt any log line / table cell that renders
+  // the value; strip rather than reject (they are almost always a paste
+  // artefact, not user intent).
+  // eslint-disable-next-line no-control-regex
+  const clean = trimmed.replace(/[\u0000-\u001f\u007f]+/g, " ").trim();
+  return { ok: true, value: clean.length > 0 ? clean : null };
+}
+
+/**
+ * Narrow an untrusted tags array. NEVER throws, never rejects the request:
+ * unusable entries are dropped. Returns the canonical list to store.
+ */
+export function narrowTags(raw: unknown): string[] {
+  if (!Array.isArray(raw)) return [];
+  const out: string[] = [];
+  const seen = new Set<string>();
+  for (const item of raw) {
+    if (typeof item !== "string") continue; // numbers/objects/arrays/null
+    // eslint-disable-next-line no-control-regex
+    const t = item.replace(/[\u0000-\u001f\u007f]+/g, " ").trim();
+    if (t.length === 0) continue;
+    if (t.length > MAX_TAG_LEN) continue; // absurd entry — drop, don't truncate
+    const key = t.toLowerCase(); // case-fold for dedup, keep first spelling
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(t);
+    if (out.length >= MAX_TAGS) break;
+  }
+  return out;
+}
+
+/** Parse the stored tags column back into an array. Storage is JSON text;
+ *  anything unparseable (hand-edited DB, older format) reads as empty so a
+ *  dashboard can always `.map()` without a guard. */
+export function parseStoredTags(stored: unknown): string[] {
+  if (typeof stored !== "string" || stored.length === 0) return [];
+  try {
+    return narrowTags(JSON.parse(stored));
+  } catch {
+    return [];
+  }
+}

package/src/node-attrs.test.ts

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

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

@@ -0,0 +1,147 @@
+// #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");
+  });
+});

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