@sleep2agi/commhub-server 0.9.0-preview.1 → 0.9.0-preview.101

package/src/node-identity-conflict-http.test.ts

@@ -0,0 +1,269 @@
+// #507 — two live copies of one node (directory copied verbatim: same node token,
+// same alias) used to hold two SSE subscriptions on `${net}:${alias}`. Every new
+// task was pushed to BOTH (each copy ran it), and either copy's shutdown
+// report_status(offline) took the node offline under the other → alias_offline.
+//
+// Pinned here, through the real HTTP entrances (GET /events/:alias with the node
+// token, POST /mcp report_status, POST /api/task, GET /api/stats/sse):
+//   1. newest connection wins: the older node stream gets node_connection_superseded
+//      (reason superseded_by_new_connection) and is closed; /api/stats/sse shows 1.
+//   2. a new task reaches exactly ONE node subscriber; a dashboard monitor on the
+//      same channel is untouched and still sees it.
+//   3. node_identity_conflict reaches the network observer stream and
+//      /api/stats/sse.identity_conflicts, with both remotes and no token.
+//   4. offline only when the last node connection leaves; tasks in between are
+//      delivered, not alias_offline.
+//   5. same instance id = a reconnect (replaced_by_reconnect, no conflict);
+//      different ids = instance_match "different"; another node's token watching
+//      this alias never supersedes it; a plain single-node stop is offline at once.
+//
+// 跑法:cd server && COMMHUB_DB=/tmp/x.db bun test src/node-identity-conflict-http.test.ts
+//       PG:COMMHUB_TEST_PG_URL=… COMMHUB_PG_EXPERIMENTAL=1(tests/test2123-hub-postgres-ladder 里注册)
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { createNetworkTokenForNode, register } from "./auth.js";
+import { db } from "./db.js";
+
+const dir = mkdtempSync(join(tmpdir(), "anet-node-conflict-"));
+const activeDbPath = process.env.COMMHUB_DB ?? (process.env.COMMHUB_TEST_PG_URL ? "postgres" : undefined);
+if (!activeDbPath) throw new Error("node-identity-conflict requires COMMHUB_DB (or COMMHUB_TEST_PG_URL) before module import");
+
+const stamp = Date.now();
+let server: any;
+let base = "";
+let ownerToken = "", ownerId = "", NET = "";
+const nodes: Record<string, { alias: string; nodeId: string; token: string }> = {};
+
+type Sub = { events: any[]; done: boolean; abort: () => void; ready: Promise<void> };
+
+function subscribe(path: string, token: string, headers: Record<string, string> = {}): Sub {
+  const ctrl = new AbortController();
+  const sub: Sub = { events: [], done: false, abort: () => ctrl.abort(), ready: Promise.resolve() };
+  let markReady!: () => void;
+  sub.ready = new Promise<void>((r) => { markReady = r; });
+  (async () => {
+    try {
+      const res = await fetch(`${base}${path}`, { headers: { Authorization: `Bearer ${token}`, Accept: "text/event-stream", ...headers }, signal: ctrl.signal });
+      if (!res.ok || !res.body) throw new Error(`subscribe ${path} → ${res.status}`);
+      const reader = res.body.getReader();
+      const dec = new TextDecoder();
+      let buf = "";
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buf += dec.decode(value, { stream: true });
+        const lines = buf.split("\n"); buf = lines.pop() || "";
+        for (const line of lines) {
+          if (!line.startsWith("data: ")) continue;
+          const ev = JSON.parse(line.slice(6));
+          sub.events.push(ev);
+          if (ev.type === "connected") markReady();
+        }
+      }
+    } catch { /* aborted */ }
+    sub.done = true;
+    markReady();
+  })();
+  return sub;
+}
+
+async function until(cond: () => boolean, what: string, ms = 3000) {
+  const t0 = Date.now();
+  while (!cond()) {
+    if (Date.now() - t0 > ms) throw new Error(`timed out waiting for: ${what}`);
+    await new Promise((r) => setTimeout(r, 20));
+  }
+}
+const settle = () => new Promise((r) => setTimeout(r, 150));
+
+async function api(token: string, method: string, path: string, body?: unknown) {
+  const res = await fetch(`${base}${path}`, {
+    method,
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  return { status: res.status, body: await res.json().catch(() => null) as any };
+}
+
+async function tool(token: string, name: string, args: Record<string, unknown>) {
+  const res = await fetch(`${base}/mcp`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Accept: "application/json, text/event-stream", "MCP-Protocol-Version": "2025-03-26" },
+    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name, arguments: args } }),
+  });
+  const raw = await res.text();
+  const data = raw.split("\n").filter((x) => x.startsWith("data:"));
+  const payload = data.length ? JSON.parse(data.at(-1)!.slice(5).trim()) : JSON.parse(raw);
+  const text = payload.result.content[0].text;
+  if (!text.startsWith("{")) throw new Error(`${name}: ${text}`);
+  return JSON.parse(text);
+}
+
+const reportStatus = (n: { alias: string; nodeId: string; token: string }, status: string) =>
+  tool(n.token, "report_status", { resume_id: `sdk-${n.nodeId}`, alias: n.alias, status, node_id: n.nodeId, network_id: NET });
+const storedStatus = (alias: string) =>
+  db.get<{ status: string }>("SELECT status FROM sessions WHERE alias = ?1 AND network_id = ?2", alias, NET)?.status;
+let seq = 0;
+const sendTask = (alias: string) => api(ownerToken, "POST", "/api/task", { alias, task: `conflict task ${stamp} #${++seq}`, network_id: NET });
+const nodeStream = (n: { alias: string; token: string }, headers: Record<string, string> = {}) =>
+  subscribe(`/events/${encodeURIComponent(n.alias)}`, n.token, headers);
+const newTasks = (s: Sub) => s.events.filter((e) => e.type === "new_task");
+const sseCount = async (alias: string) => (await api(nodes.a.token, "GET", "/api/stats/sse")).body.sessions[`${NET}:${alias}`] ?? 0;
+
+beforeAll(async () => {
+  process.env.COMMHUB_UPLOADS_DIR = join(dir, "uploads");
+  process.env.HOST = "127.0.0.1";
+  const owner = register(`nic_owner_${stamp}`, "NodeConflictOwner123!", undefined, "seed");
+  ownerToken = owner.token!; ownerId = owner.user!.user_id; NET = owner.network_id!;
+  for (const key of ["a", "b", "c", "d", "e"]) {
+    const alias = `nic-${key}-${stamp}`;
+    const nodeId = `n_nic_${key}_${stamp}`;
+    const minted = createNetworkTokenForNode(ownerId, NET, alias, nodeId);
+    expect(minted.ok).toBe(true);
+    nodes[key] = { alias, nodeId, token: minted.token! };
+  }
+  const mod: any = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+  for (const n of Object.values(nodes)) expect((await reportStatus(n, "idle")).ok).toBe(true);
+}, 30_000);
+
+afterAll(() => {
+  try { server?.stop?.(true); } catch {}
+  try { rmSync(dir, { recursive: true, force: true }); } catch {}
+});
+
+describe("#507 two copies of one node (same token, same alias)", () => {
+  const subs: Record<string, Sub> = {};
+
+  test("newest connection wins: the older node stream is told why and closed", async () => {
+    const n = nodes.a;
+    subs.observer = subscribe(`/events/network/${NET}`, ownerToken);
+    subs.monitor = subscribe(`/events/${encodeURIComponent(n.alias)}?network_id=${NET}`, ownerToken);
+    await subs.observer.ready; await subs.monitor.ready;
+    subs.copyA = nodeStream(n, { "User-Agent": "copy-A" });
+    await subs.copyA.ready;
+    expect(await sseCount(n.alias)).toBe(2); // copy A + dashboard monitor
+
+    subs.copyB = nodeStream(n, { "User-Agent": "copy-B" });
+    await subs.copyB.ready;
+    await until(() => subs.copyA.done, "copy A's stream to be closed");
+    const notice = subs.copyA.events.find((e) => e.type === "node_connection_superseded");
+    expect(notice).toBeTruthy();
+    expect(notice.reason).toBe("superseded_by_new_connection");
+    expect(notice.instance_match).toBe("unknown");
+    expect(subs.copyB.done).toBe(false);
+    expect(subs.monitor.done).toBe(false); // a monitor is never superseded
+    expect(await sseCount(n.alias)).toBe(2); // copy B + monitor
+  });
+
+  test("a new task reaches exactly one node subscriber (the monitor still sees it)", async () => {
+    const r = await sendTask(nodes.a.alias);
+    expect(r.status).toBe(200);
+    expect(r.body.ok).toBe(true);
+    await until(() => newTasks(subs.copyB).length >= 1 && newTasks(subs.monitor).length >= 1, "new_task on copy B + monitor");
+    await settle();
+    expect(newTasks(subs.copyB).length).toBe(1);
+    expect(newTasks(subs.copyA).length).toBe(0);
+    expect(newTasks(subs.monitor).length).toBe(1);
+  });
+
+  test("node_identity_conflict reaches the observer stream and /api/stats/sse, with remotes and no token", async () => {
+    await until(() => subs.observer.events.some((e) => e.type === "node_identity_conflict"), "observer conflict event");
+    const ev = subs.observer.events.find((e) => e.type === "node_identity_conflict");
+    expect(ev.alias).toBe(nodes.a.alias);
+    expect(ev.node_id).toBe(nodes.a.nodeId);
+    expect(ev.policy).toBe("newest_connection_wins");
+    expect(ev.superseded.user_agent).toBe("copy-A");
+    expect(ev.current.user_agent).toBe("copy-B");
+    expect(ev.superseded.remote).toMatch(/^127\.0\.0\.1:\d+$/);
+    expect(ev.current.remote).toMatch(/^127\.0\.0\.1:\d+$/);
+    expect(ev.superseded.remote).not.toBe(ev.current.remote);
+    const stats = await api(nodes.a.token, "GET", "/api/stats/sse");
+    const mine = stats.body.identity_conflicts.filter((c: any) => c.alias === nodes.a.alias);
+    expect(mine.length).toBe(1);
+    expect(mine[0].network_id).toBe(NET);
+    const raw = JSON.stringify(stats.body) + JSON.stringify(ev);
+    expect(raw).not.toContain("ntok_");
+    expect(raw).not.toContain(nodes.a.token);
+    const audit = db.get<{ n: number }>("SELECT COUNT(*) AS n FROM audit_log WHERE action = 'node_identity_conflict' AND target_id = ?1", nodes.a.nodeId);
+    expect(audit?.n).toBe(1);
+  });
+
+  test("offline only when the last node connection leaves; tasks in between are delivered", async () => {
+    const n = nodes.a;
+    // Copy A (the superseded one) shuts down and says so.
+    const fromA = await reportStatus(n, "offline");
+    expect(fromA.ok).toBe(true);
+    expect(fromA.offline_deferred).toBe(true);
+    expect(storedStatus(n.alias)).not.toBe("offline");
+    const r = await sendTask(n.alias);
+    expect(r.status).toBe(200);
+    expect(r.body.ok).toBe(true);
+    expect(r.body.error).toBeUndefined();
+    await until(() => newTasks(subs.copyB).length >= 2, "second new_task on copy B");
+
+    // Copy B stops too: it reports offline while its stream is still open, then exits.
+    const fromB = await reportStatus(n, "offline");
+    expect(fromB.offline_deferred).toBe(true);
+    expect(storedStatus(n.alias)).not.toBe("offline");
+    subs.copyB.abort();
+    await until(() => storedStatus(n.alias) === "offline", "deferred offline applied once the last node stream closed");
+    expect((await sendTask(n.alias)).body.error).toBe("alias_offline");
+    subs.monitor.abort(); subs.observer.abort();
+  });
+});
+
+describe("#507 what is and is not a conflict", () => {
+  test("same instance id = a reconnect of the same process: replaced, no conflict recorded", async () => {
+    const n = nodes.b;
+    const first = nodeStream(n, { "X-Anet-Instance-Id": "inst-b-1" });
+    await first.ready;
+    const second = nodeStream(n, { "X-Anet-Instance-Id": "inst-b-1" });
+    await second.ready;
+    await until(() => first.done, "old stream replaced");
+    expect(first.events.find((e) => e.type === "node_connection_superseded")?.reason).toBe("replaced_by_reconnect");
+    const stats = await api(n.token, "GET", "/api/stats/sse");
+    expect(stats.body.identity_conflicts.filter((c: any) => c.alias === n.alias)).toEqual([]);
+    // No conflict → a stop is exactly as before: offline at once.
+    const r = await reportStatus(n, "offline");
+    expect(r.offline_deferred).toBeUndefined();
+    expect(storedStatus(n.alias)).toBe("offline");
+    second.abort();
+  });
+
+  test("different instance ids are reported as instance_match=different", async () => {
+    const n = nodes.c;
+    const first = nodeStream(n, { "X-Anet-Instance-Id": "inst-c-host1" });
+    await first.ready;
+    const second = subscribe(`/events/${encodeURIComponent(n.alias)}?instance_id=inst-c-host2`, n.token);
+    await second.ready;
+    await until(() => first.done, "old stream superseded");
+    const stats = await api(n.token, "GET", "/api/stats/sse");
+    const mine = stats.body.identity_conflicts.filter((c: any) => c.alias === n.alias);
+    expect(mine.length).toBe(1);
+    expect(mine[0].instance_match).toBe("different");
+    expect(mine[0].superseded.instance_id).toBe("inst-c-host1");
+    expect(mine[0].current.instance_id).toBe("inst-c-host2");
+    second.abort();
+  });
+
+  test("another node's token watching this alias never supersedes the node", async () => {
+    const n = nodes.d;
+    const own = nodeStream(n);
+    await own.ready;
+    const watcher = subscribe(`/events/${encodeURIComponent(n.alias)}`, nodes.e.token);
+    await watcher.ready;
+    await settle();
+    expect(own.done).toBe(false);
+    expect(own.events.some((e) => e.type === "node_connection_superseded")).toBe(false);
+    watcher.abort();
+    // And a plain single-node stop (no conflict) is offline immediately, as before.
+    const r = await reportStatus(n, "offline");
+    expect(r.offline_deferred).toBeUndefined();
+    expect(storedStatus(n.alias)).toBe("offline");
+    own.abort();
+  });
+});

package/src/node-identity-conflict.ts

@@ -0,0 +1,142 @@
+// #507 — two live processes holding the same node identity (a node directory
+// copied verbatim and started elsewhere: same node token, same alias).
+//
+// push.ts enforces "at most one node-scoped SSE subscriber per (network, alias)",
+// newest connection wins (policy + rationale next to enforceSingleNodeSubscriber).
+// This module is the Hub-side bookkeeping around that:
+//
+//   1. node_identity_conflict — every supersede between connections that are not
+//      provably the same process is logged, written to audit_log, pushed to the
+//      network observer stream (dashboard) and kept in a small ring that
+//      GET /api/stats/sse returns. Carries both connections' remote info; never
+//      a token.
+//
+//   2. offline while another copy is still connected — a copy's shutdown
+//      report_status(offline) used to mark the node offline even though the other
+//      copy was connected, so new tasks got alias_offline. While a conflict is
+//      recent for that alias and a node-scoped subscriber is still connected, the
+//      offline is DEFERRED: stored status stays as it was, and the offline is
+//      applied only when the last node-scoped subscriber leaves (or dropped when the
+//      surviving copy reports a fresh status). Outside a conflict window nothing
+//      changes: a normal single-node stop marks offline immediately, as before.
+
+import { db, logAudit } from "./db.js";
+import {
+  hasNodeSubscriber,
+  onNodeIdentityConflict,
+  onNodeSubscribersDrained,
+  pushEvent,
+  pushNetworkObserverEvent,
+  type NodeIdentityConflict,
+} from "./push.js";
+
+/** How long after a conflict an offline report is treated as "maybe the other copy". */
+export const CONFLICT_WINDOW_MS = 10 * 60 * 1000;
+const RING_MAX = 50;
+/** Observer/audit emission is rate-limited per alias (logs are not). A flapping
+ *  pair supersedes about once a second; one event a minute is enough to see it. */
+const EMIT_EVERY_MS = 60 * 1000;
+
+const ring: NodeIdentityConflict[] = [];
+const lastConflictAt = new Map<string, number>();
+const lastEmittedAt = new Map<string, number>();
+const pendingOffline = new Map<string, { resumeId: string; at: number }>();
+
+const k = (alias: string, networkId: string | null | undefined) => `${networkId || "global"}:${alias}`;
+
+function publicInfo(i: NodeIdentityConflict["current"]) {
+  return {
+    instance_id: i.instanceId,
+    remote: i.remote,
+    user_agent: i.userAgent,
+    connected_at: new Date(i.connectedAt).toISOString(),
+  };
+}
+
+export function conflictPayload(c: NodeIdentityConflict) {
+  return {
+    type: "node_identity_conflict",
+    alias: c.alias,
+    node_id: c.nodeId,
+    instance_match: c.instanceMatch,
+    policy: "newest_connection_wins",
+    superseded: publicInfo(c.superseded),
+    current: publicInfo(c.current),
+    at: new Date(c.at).toISOString(),
+  };
+}
+
+function handleConflict(c: NodeIdentityConflict): void {
+  const key = k(c.alias, c.networkId);
+  lastConflictAt.set(key, c.at);
+  ring.push(c);
+  if (ring.length > RING_MAX) ring.splice(0, ring.length - RING_MAX);
+  const payload = conflictPayload(c);
+  console.warn(`[node_identity_conflict] ${c.key} node_id=${c.nodeId ?? "?"} instance_match=${c.instanceMatch} ` +
+    `superseded=${c.superseded.remote ?? "?"}(${c.superseded.instanceId ?? "no-instance-id"}) ` +
+    `by=${c.current.remote ?? "?"}(${c.current.instanceId ?? "no-instance-id"}) — ` +
+    `two processes are using this node's identity (copied node directory?); newest connection kept`);
+  const last = lastEmittedAt.get(key) ?? 0;
+  if (c.at - last < EMIT_EVERY_MS) return;
+  lastEmittedAt.set(key, c.at);
+  pushNetworkObserverEvent(c.networkId, payload);
+  logAudit(null, null, "node_identity_conflict", "node", c.nodeId ?? c.alias, JSON.stringify(payload), c.current.remote ?? undefined, c.networkId ?? undefined);
+}
+
+function handleDrained(alias: string, networkId: string | null): void {
+  const key = k(alias, networkId);
+  const pending = pendingOffline.get(key);
+  if (!pending) return;
+  pendingOffline.delete(key);
+  try {
+    db.run(
+      "UPDATE sessions SET status = 'offline', updated_at = datetime('now') WHERE resume_id = ?1 AND alias = ?2 AND network_id = ?3",
+      [pending.resumeId, alias, networkId ?? "default"],
+    );
+    console.log(`[node_identity_conflict] ${key} last node connection gone → deferred offline applied`);
+    pushEvent(alias, { type: "status_update", alias, status: "offline", progress: null, host: null, process_telemetry: null }, networkId);
+  } catch (e: any) {
+    console.log(`[node_identity_conflict] deferred offline failed for ${key}: ${e?.message || e}`);
+  }
+}
+
+onNodeIdentityConflict(handleConflict);
+onNodeSubscribersDrained(handleDrained);
+
+/** report_status hook. Returns true when an offline report must NOT be stored now
+ *  (another copy of this node is still connected); it is then applied when the last
+ *  node-scoped subscriber leaves. Any non-offline report clears a pending offline. */
+export function deferOfflineIfAnotherCopyConnected(
+  alias: string,
+  networkId: string | null | undefined,
+  status: string,
+  resumeId: string,
+  now = Date.now(),
+): boolean {
+  const key = k(alias, networkId);
+  if (status !== "offline") {
+    pendingOffline.delete(key);
+    return false;
+  }
+  const conflictAt = lastConflictAt.get(key);
+  if (conflictAt === undefined || now - conflictAt > CONFLICT_WINDOW_MS) return false;
+  if (!hasNodeSubscriber(alias, networkId)) return false;
+  pendingOffline.set(key, { resumeId, at: now });
+  console.warn(`[node_identity_conflict] ${key} report_status(offline) deferred: a node connection is still open ` +
+    `and a second copy was seen ${Math.round((now - conflictAt) / 1000)}s ago`);
+  return true;
+}
+
+/** Recent conflicts, newest last, optionally limited to one network. */
+export function recentNodeIdentityConflicts(networkId?: string | null) {
+  return ring
+    .filter((c) => networkId === undefined || c.networkId === networkId)
+    .map((c) => ({ network_id: c.networkId, ...conflictPayload(c) }));
+}
+
+export function __resetNodeIdentityConflictsForTest(): void {
+  ring.length = 0;
+  lastConflictAt.clear();
+  lastEmittedAt.clear();
+  pendingOffline.clear();
+}

package/src/node-identity-mismatch.test.ts

@@ -0,0 +1,74 @@
+// report_status must not relabel a nodes row that belongs to another node.
+//
+// Shape seen in production: node A's config carries a node_id that another
+// node B reported first (a copied config / a colliding hand-backfilled id).
+// The row is B's alias + B's config_path, unowned (pre-RFC-036). When A starts
+// reporting node_id, upsertNodeWithSec1Guard's COALESCE would overwrite the
+// alias with A's — B's row silently becomes A's. identity_mismatch refuses it.
+//
+// Run with: COMMHUB_DB=/tmp/identity-mismatch.db bun test src/node-identity-mismatch.test.ts
+
+import { beforeEach, describe, expect, test } from "bun:test";
+import { db } from "./db.js";
+import { upsertNodeWithSec1Guard } from "./tools.js";
+
+const NET = "net_identity";
+
+function row(node_id: string, alias: string, config_path: string | null, owner: string | null = null) {
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, runtime, config_path, network_id, owner_user_id) VALUES (?1, ?2, ?2, 'codex-app-server-sdk', ?3, ?4, ?5)`,
+    [node_id, alias, config_path, NET, owner],
+  );
+}
+const read = (id: string) => db.get<{ alias: string; runtime: string | null; config_path: string | null }>(
+  "SELECT alias, runtime, config_path FROM nodes WHERE node_id = ?1", id,
+)!;
+
+beforeEach(() => { db.run("DELETE FROM nodes"); });
+
+describe("upsertNodeWithSec1Guard — identity_mismatch", () => {
+  test("different alias + different config_path ⇒ refused, row untouched", () => {
+    row("n_shared01", "node-b", "/work/b/.anet/nodes/node-b/config.json");
+    const out = upsertNodeWithSec1Guard({
+      node_id: "n_shared01", callerNetworkId: NET, alias: "node-a", runtime: "claude-code",
+      config_path: "/work/a/.anet/nodes/node-a/config.json",
+    });
+    expect(out).toMatchObject({ result: "refused", reason: "identity_mismatch" });
+    expect(read("n_shared01")).toEqual({ alias: "node-b", runtime: "codex-app-server-sdk", config_path: "/work/b/.anet/nodes/node-b/config.json" });
+  });
+
+  test("same alias, different config_path (the node moved dirs) ⇒ updated", () => {
+    row("n_moved01", "node-a", "/old/.anet/nodes/node-a/config.json");
+    const out = upsertNodeWithSec1Guard({ node_id: "n_moved01", callerNetworkId: NET, alias: "node-a", config_path: "/new/.anet/nodes/node-a/config.json" });
+    expect(out.result).toBe("updated");
+    expect(read("n_moved01").config_path).toBe("/new/.anet/nodes/node-a/config.json");
+  });
+
+  test("different alias, same config_path ⇒ updated (not the collision shape)", () => {
+    row("n_same01", "old-name", "/w/.anet/nodes/x/config.json");
+    expect(upsertNodeWithSec1Guard({ node_id: "n_same01", callerNetworkId: NET, alias: "new-name", config_path: "/w/.anet/nodes/x/config.json" }).result).toBe("updated");
+    expect(read("n_same01").alias).toBe("new-name");
+  });
+
+  test("row without config_path (token-mint row) ⇒ first reporter fills it in", () => {
+    row("n_mint01", "node-a", null);
+    expect(upsertNodeWithSec1Guard({ node_id: "n_mint01", callerNetworkId: NET, alias: "node-a", config_path: "/w/a/config.json" }).result).toBe("updated");
+    expect(read("n_mint01").config_path).toBe("/w/a/config.json");
+  });
+
+  test("reporter without config_path ⇒ no evidence, legacy behaviour kept", () => {
+    row("n_nocfg01", "node-b", "/w/b/config.json");
+    expect(upsertNodeWithSec1Guard({ node_id: "n_nocfg01", callerNetworkId: NET, alias: "node-a" }).result).toBe("updated");
+  });
+
+  test("new node_id ⇒ inserted", () => {
+    expect(upsertNodeWithSec1Guard({ node_id: "n_fresh01", callerNetworkId: NET, alias: "node-a", config_path: "/w/a/config.json" }).result).toBe("inserted");
+    expect(read("n_fresh01").alias).toBe("node-a");
+  });
+
+  test("owner mismatch still wins first (existing gate unchanged)", () => {
+    row("n_owned01", "node-b", "/w/b/config.json", "usr_b");
+    expect(upsertNodeWithSec1Guard({ node_id: "n_owned01", callerNetworkId: NET, callerUserId: "usr_a", alias: "node-a", config_path: "/w/a/config.json" }))
+      .toMatchObject({ result: "refused", reason: "owner_mismatch" });
+  });
+});

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