@sleep2agi/commhub-server 0.9.0-preview.0 → 0.9.0-preview.100

package/src/node-health-guard.ts

@@ -0,0 +1,105 @@
+// #460(#448 的子项)—— 降级节点拒收新任务。
+//
+// 现场:节点在 Hub 上 idle / in_flight=0,实际 app-server 端口没人听、TUI 变成 `sleep infinity`、
+// 或登录态 revoked —— 派过去的任务**静默排队**,谁都不知道它永远不会被执行。agent-node .94 起
+// 把这几层报上来(report_status.health,node-health-store.ts 只存内存、10 分钟 TTL);这里在**派发**
+// 那一刻读它:新鲜的健康报告说某一层坏了,就直接拒,带上是哪一层、怎么修。
+//
+// 🔴 只拒「确知坏了」的:没有报告(老 agent-node / claude-code 节点)、报告已过期(>TTL)、
+//    或某层没报(比如非共存节点没有 tui)= 不知道 = 放行。宁可像以前一样排队,
+//    也不能因为缺数据把一台正常的老节点挡在外面。
+// 🔴 只管**新任务派发**(send_task / REST /api/task / 定时任务 / retry / reassign / broadcast)。
+//    回复、send_message、ack 不经过这里 —— 降级节点发出的回复照常送达,发给它的普通消息也照常入库。
+// 逃生口:用户(不是节点令牌)可以带 force=true 强制派发 —— 比如明知 TUI 不在、但 bridge 能干活。
+//    节点令牌不能 force:不让 agent 绕过对另一个 agent 的健康判断。
+
+import { readNodeHealth, type NodeHealth } from "./node-health-store.js";
+
+export type DegradedLayer = {
+  layer: "app_server" | "tui" | "model_auth";
+  /** 机器可读的原因:app_server 的错误摘要 / tui 的 reason / model_auth 的状态。 */
+  reason: string;
+  /** 给人看的一句(中文,与 app 的「降级」徽标同一套措辞)。 */
+  label: string;
+  hint: string;
+};
+
+const TUI_LABEL: Record<string, string> = {
+  "session-missing": "TUI 会话不在",
+  "pane-dead": "TUI 已退出",
+  "sleep-placeholder": "TUI 被占位(sleep)",
+  "tmux-unavailable": "tmux 不可用",
+};
+
+/** 一份健康报告里确知坏掉的层;没报的层不算。 */
+export function degradedLayers(health: NodeHealth | null | undefined): DegradedLayer[] {
+  if (!health) return [];
+  const out: DegradedLayer[] = [];
+  if (health.app_server && health.app_server.ok === false) {
+    out.push({
+      layer: "app_server",
+      reason: (health.app_server.last_error || "unreachable").slice(0, 200),
+      label: "App Server 断开",
+      hint: "节点的 codex app-server 端口没有响应:在节点所在机器上重启该节点(anet node restart <别名>)",
+    });
+  }
+  if (health.tui && health.tui.ok === false) {
+    out.push({
+      layer: "tui",
+      reason: health.tui.reason,
+      label: TUI_LABEL[health.tui.reason] ?? "TUI 不可用",
+      hint: "共存 TUI 不在运行:在节点所在机器上重新拉起该节点的 TUI(anet node restart <别名>)",
+    });
+  }
+  if (health.model_auth === "revoked" || health.model_auth === "expired") {
+    out.push({
+      layer: "model_auth",
+      reason: health.model_auth,
+      label: health.model_auth === "revoked" ? "需要重新登录" : "登录已过期",
+      hint: "该节点自己的 CODEX_HOME 需要重新登录(在那台机器上:CODEX_HOME=<节点目录>/codex-home codex login);不要拷别的节点的 auth.json",
+    });
+  }
+  return out;
+}
+
+export type HealthGuardResult =
+  | { ok: true; forced?: true }
+  | {
+    ok: false;
+    error: "node_degraded";
+    alias: string;
+    layers: DegradedLayer[];
+    message: string;
+    hint: string;
+    health_observed_ms_ago: number;
+    /** 能不能用 force=true 绕过(只有用户令牌能)。 */
+    force_allowed: boolean;
+  };
+
+/**
+ * 派发前的健康门。networkId 用与 report_status 写入时同一个键(sessionNetId = 网络 id ?? "default")。
+ * force 只在 forceAllowed(用户令牌)时生效。
+ */
+export function assertNodeHealthy(
+  alias: string,
+  networkId: string | null | undefined,
+  opts: { force?: boolean; forceAllowed: boolean; now?: number },
+): HealthGuardResult {
+  if (!alias) return { ok: true };
+  const hit = readNodeHealth(networkId ?? "default", alias, opts.now);
+  if (!hit) return { ok: true };
+  const layers = degradedLayers(hit.health);
+  if (!layers.length) return { ok: true };
+  if (opts.force && opts.forceAllowed) return { ok: true, forced: true };
+  const labels = layers.map(l => l.label).join("、");
+  return {
+    ok: false,
+    error: "node_degraded",
+    alias,
+    layers,
+    message: `节点 ${alias} 处于降级状态(${labels}),任务不会被执行,已拒绝派发。`,
+    hint: layers[0].hint + (opts.forceAllowed ? "。确需强制派发可带 force=true。" : ""),
+    health_observed_ms_ago: hit.observed_ms_ago,
+    force_allowed: opts.forceAllowed,
+  };
+}

package/src/node-health-passthrough.test.ts

@@ -0,0 +1,115 @@
+// #448 — report_status.health passthrough (layered node health, report-only).
+//
+// Hub-side contract verified here:
+//   1. A well-formed `health` from the node's own token is kept (memory-only) and readable.
+//   2. Malformed `health` never rejects the report — the node stays online, health reads as null.
+//   3. Another node / a user login cannot speak for this node's health.
+//   4. Stale (> TTL) health reads as null, never as "healthy".
+//
+// 跑法：cd server && COMMHUB_DB=/tmp/node-health.db bun test src/node-health-passthrough.test.ts
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { db } from "./db.js";
+import { registerTools } from "./tools.js";
+import { clearNodeHealthStore, NODE_HEALTH_TTL_MS, readNodeHealth, recordNodeHealth } from "./node-health-store.js";
+
+const NET = "net_health_t";
+const OWNER = "u_health_owner";
+const NODE_A = "health-node-a";
+const NODE_B = "health-node-b";
+const NODE_A_ID = "node_health_a";
+const NODE_B_ID = "node_health_b";
+const T_A = "tok_health_node_a";
+const T_B = "tok_health_node_b";
+
+function cleanup() {
+  for (const t of ["sessions", "nodes", "api_tokens", "network_members", "networks"]) {
+    try { db.run(`DELETE FROM ${t} WHERE network_id = ?1`, [NET]); } catch {}
+  }
+  try { db.run("DELETE FROM users WHERE user_id = ?1", [OWNER]); } catch {}
+  clearNodeHealthStore();
+}
+function seed() {
+  db.run(`INSERT INTO users (user_id, username, password_hash, role, created_at) VALUES (?1, ?2, 'x', 'user', datetime('now'))`, [OWNER, OWNER]);
+  db.run(`INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?2, ?3, datetime('now'))`, [NET, NET, OWNER]);
+  db.run(`INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, 'owner', datetime('now'))`, [OWNER, NET]);
+  for (const [id, alias, tok] of [[NODE_A_ID, NODE_A, T_A], [NODE_B_ID, NODE_B, T_B]]) {
+    db.run(`INSERT INTO nodes (node_id, node_name, alias, network_id, owner_user_id, created_at, updated_at) VALUES (?1, ?2, ?3, ?4, ?5, datetime('now'), datetime('now'))`, [id, alias, alias, NET, OWNER]);
+    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, OWNER, NET, `node:${alias}`, `hash_${tok}`, id]);
+  }
+}
+
+async function connectAs(alias: string, tokenId: string) {
+  const server = new McpServer({ name: "health-test", version: "1" });
+  registerTools(server, undefined, NET, OWNER, alias, true, tokenId);
+  const client = new Client({ name: "health-client", version: "1" });
+  const [ct, st] = InMemoryTransport.createLinkedPair();
+  await server.connect(st);
+  await client.connect(ct);
+  const call = async (args: Record<string, unknown>) => {
+    const r: any = await client.callTool({ name: "report_status", arguments: args });
+    return { isError: r.isError === true, body: JSON.parse(r.content?.[0]?.text ?? "null") };
+  };
+  return { call, close: async () => { await client.close(); await server.close(); } };
+}
+
+const HEALTH = {
+  bridge: "ok",
+  app_server: { ok: false, rtt_ms: null, last_error: "connection refused" },
+  tui: { ok: false, reason: "sleep-placeholder" },
+  model_auth: "revoked",
+};
+
+beforeEach(() => { cleanup(); seed(); });
+afterAll(cleanup);
+
+describe("#448 report_status.health passthrough", () => {
+  test("node's own token: stored and readable as reported", async () => {
+    const a = await connectAs(NODE_A, T_A);
+    try {
+      const r = await a.call({ resume_id: `sdk-${NODE_A_ID}`, alias: NODE_A, status: "idle", node_id: NODE_A_ID, health: HEALTH });
+      expect(r.isError).toBe(false);
+      expect(r.body.ok).not.toBe(false);
+    } finally { await a.close(); }
+    expect(readNodeHealth(NET, NODE_A)?.health).toEqual(HEALTH as any);
+  });
+
+  test("malformed health never rejects the report (node stays online); it reads as not reported", async () => {
+    const a = await connectAs(NODE_A, T_A);
+    try {
+      for (const bad of [42, "ok", { app_server: { ok: "yes" }, model_auth: "weird", tui: [] }, { app_server: { ok: true, rtt_ms: NaN, last_error: 5 } }]) {
+        const r = await a.call({ resume_id: `sdk-${NODE_A_ID}`, alias: NODE_A, status: "idle", node_id: NODE_A_ID, health: bad });
+        expect(r.isError).toBe(false);
+      }
+    } finally { await a.close(); }
+    expect(db.get<{ s: string }>("SELECT status AS s FROM sessions WHERE alias = ?1 AND network_id = ?2", NODE_A, NET)?.s).toBe("idle");
+    // 最后一份里 app_server.ok 合法、其余两格降级成 null —— 留下的是能证实的部分,不是编出来的。
+    expect(readNodeHealth(NET, NODE_A)?.health.app_server).toEqual({ ok: true, rtt_ms: null, last_error: null });
+  });
+
+  test("another node's token cannot speak for this node", async () => {
+    const b = await connectAs(NODE_B, T_B);
+    try {
+      await b.call({ resume_id: `sdk-${NODE_A_ID}`, alias: NODE_A, status: "idle", node_id: NODE_A_ID, health: HEALTH });
+    } finally { await b.close(); }
+    expect(readNodeHealth(NET, NODE_A)).toBeNull();
+  });
+
+  test("stale health reads as null, never as healthy", () => {
+    const t0 = 1_000_000;
+    recordNodeHealth(NET, NODE_A, { bridge: "ok", model_auth: "ok" }, t0);
+    expect(readNodeHealth(NET, NODE_A, t0 + 1_000)?.observed_ms_ago).toBe(1_000);
+    expect(readNodeHealth(NET, NODE_A, t0 + NODE_HEALTH_TTL_MS + 1)).toBeNull();
+  });
+
+  test("a report without health leaves the last one (heartbeats from older code paths do not erase it)", async () => {
+    const a = await connectAs(NODE_A, T_A);
+    try {
+      await a.call({ resume_id: `sdk-${NODE_A_ID}`, alias: NODE_A, status: "idle", node_id: NODE_A_ID, health: HEALTH });
+      await a.call({ resume_id: `sdk-${NODE_A_ID}`, alias: NODE_A, status: "working", node_id: NODE_A_ID });
+    } finally { await a.close(); }
+    expect(readNodeHealth(NET, NODE_A)?.health.model_auth).toBe("revoked");
+  });
+});

package/src/node-health-store.ts

@@ -0,0 +1,72 @@
+// #448 —— agent-node 上报的分层健康(`report_status.health`)的 Hub 侧透传。
+//
+// 「在线」只说明桥进程还活着:现场 ~40 台 codex 共存节点里,有的在 Hub 上 idle / in_flight=0,
+// 实际 app-server 端口没人监听、TUI pane 变成 `sleep infinity`、或登录态 "refresh token revoked"。
+// 节点把这几层分开报上来;这里只负责**收下、按节点存最新一份、在 /api/status 和 status_update 里带出去**。
+//
+// 刻意只放内存,不加列:它是**几秒钟一变的观测值**,不是需要跨重启保留的状态 —— Hub 重启后下一次
+// 心跳(≤3 分钟,翻转时立即)就会补上;持久化一份旧观测值反而会在节点死掉后继续说「app_server ok」。
+// 同理,超过 TTL 的那份按「没报」处理(null),不按「健康」处理。
+
+import { z } from "zod/v4";
+
+export const NODE_HEALTH_TTL_MS = 10 * 60_000;
+
+// 🔴 `.catch(undefined)`:这一格是纯诊断信息,**任何形状都不许拒掉整份 report_status**
+//    (zod 对象里一个已知字段验证失败 = 整份被拒 = 节点在 Hub 上失联,#1225 的形状)。
+//    合法的透传,其余一律当没报。子对象不 strict:新节点多报的键丢掉即可。
+export const nodeHealthSchema = z.object({
+  bridge: z.literal("ok").optional(),
+  app_server: z.object({
+    ok: z.boolean(),
+    rtt_ms: z.number().nullable().catch(null),
+    last_error: z.string().max(200).nullable().catch(null),
+  }).optional().catch(undefined),
+  tui: z.object({
+    ok: z.boolean(),
+    reason: z.string().max(40),
+  }).optional().catch(undefined),
+  model_auth: z.enum(["ok", "revoked", "expired", "unknown"]).optional().catch(undefined),
+}).optional().catch(undefined);
+
+export type NodeHealth = NonNullable<z.infer<typeof nodeHealthSchema>>;
+
+const store = new Map<string, { health: NodeHealth; at: number }>();
+const keyOf = (networkId: string | null | undefined, alias: string) => `${networkId ?? "default"}\0${alias}`;
+
+// #431 —— /api/status 的记忆化(status-read-cache.ts)按这两样判断正文还对不对:任何一次上报 → 版本 +1;
+// 任何一份报告过 TTL 的那一刻(degraded / health 字段会消失)→ 由 nodeHealthNextExpiryAt 给出的时刻失效。
+let version = 0;
+export function nodeHealthVersion(): number { return version; }
+/** 最早一份还没过期的报告的过期时刻(ms);一份都没有 → Infinity。 */
+export function nodeHealthNextExpiryAt(now = Date.now()): number {
+  let next = Infinity;
+  for (const v of store.values()) {
+    const at = v.at + NODE_HEALTH_TTL_MS;
+    if (at >= now && at < next) next = at;
+  }
+  return next;
+}
+
+export function recordNodeHealth(networkId: string | null | undefined, alias: string, health: NodeHealth, now = Date.now()): void {
+  version++;
+  store.set(keyOf(networkId, alias), { health, at: now });
+  // 有界:按 TTL 顺手清掉过期的,别让改过名/删掉的节点在内存里攒着。
+  if (store.size > 256) {
+    for (const [k, v] of store) if (now - v.at > NODE_HEALTH_TTL_MS) store.delete(k);
+  }
+}
+
+/** 最新一份;没有或已过 TTL → null(读的人必须把它当「不知道」,而不是「健康」)。 */
+export function readNodeHealth(
+  networkId: string | null | undefined, alias: string, now = Date.now(),
+): { health: NodeHealth; observed_ms_ago: number } | null {
+  const hit = store.get(keyOf(networkId, alias));
+  if (!hit) return null;
+  const age = now - hit.at;
+  if (age > NODE_HEALTH_TTL_MS) { store.delete(keyOf(networkId, alias)); return null; }
+  return { health: hit.health, observed_ms_ago: Math.max(0, age) };
+}
+
+/** 测试用。 */
+export function clearNodeHealthStore(): void { store.clear(); version++; }

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