@sleep2agi/commhub-server 0.9.0-preview.13 → 0.9.0-preview.130

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,53 @@
+/**
+ * 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 }>,
+  bindings: Array<{ node_id: string; daemon_node_id: string }> = [],
+): Map<string, string> {
+  const m = new Map<string, string>();
+  for (const binding of bindings) m.set(binding.node_id, binding.daemon_node_id);
+  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);
+}

package/src/node-lifecycle-read-http.test.ts

@@ -0,0 +1,245 @@
+import { beforeAll, afterAll, expect, test } from "bun:test";
+import { mkdtempSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+const dir = mkdtempSync(join(tmpdir(), "lifecycle-read-"));
+process.env.COMMHUB_DB ||= join(dir, "hub.db");
+process.env.COMMHUB_AUTH_TOKEN ||= "lifecycle-read-master-fixture";
+let hub: ReturnType<typeof Bun.serve>, base: string;
+let db: any, a: any, b: any, limited: any, daemonToken: string;
+const ids = { active: "n_read_active", created: "node_read_created", manual: "node_read_manual", daemon: "n_read_daemon" };
+const get = async (path: string, token = a.token) => {
+  const res = await fetch(base + path, { headers: { Authorization: `Bearer ${token}` } });
+  return { status: res.status, body: await res.json() as any };
+};
+const query = (kind: string, selector: string) => `/api/node-lifecycle-requests?kind=${kind}&${selector}`;
+
+beforeAll(async () => {
+  ({ db } = await import("./db.js"));
+  const { register } = await import("./auth.js");
+  const suffix = Date.now();
+  a = register(`read_owner_${suffix}`, "ReadFixture-Strong1!");
+  b = register(`read_other_${suffix}`, "ReadFixture-Strong1!");
+  limited = register(`read_limited_${suffix}`, "ReadFixture-Strong1!");
+  expect(a.ok && b.ok && limited.ok).toBe(true);
+  for (const user of [a, b, limited]) db.run("UPDATE users SET role='user' WHERE user_id=?1", [user.user.user_id]);
+  db.run("INSERT INTO network_members(network_id,user_id,role,agent_access) VALUES(?1,?2,'viewer','granted')", [a.network_id, limited.user.user_id]);
+  for (const [key, id] of Object.entries(ids)) db.run(
+    "INSERT INTO nodes(node_id,node_name,alias,network_id,owner_user_id,hostname,config_snapshot) VALUES(?1,?2,?2,?3,?4,'fixture-host',?5)",
+    [id, `read-${key}`, a.network_id, a.user.user_id, key === "daemon" ? JSON.stringify({ role: "host_supervisor", daemon_capabilities: { adopt_capable: true } }) : "{}"]);
+  for (const status of ["active", "pending", "refused", "revoked"]) {
+    const id = status === "active" ? ids.active : `n_read_${status}`;
+    if (status !== "active") db.run("INSERT INTO nodes(node_id,node_name,alias,network_id) VALUES(?1,?1,?2,?3)", [id, `read-${status}`, a.network_id]);
+    db.run(`INSERT INTO node_daemon_bindings(request_id,network_id,node_id,daemon_node_id,workdir,requested_by,status,error,created_at,updated_at)
+      VALUES(?1,?2,?3,?4,'/private/fixture',?5,?6,?7,1,2)`,
+      [`adopt_read_${status}`, a.network_id, id, ids.daemon, a.user.user_id, status, status === "refused" ? "adopt_start_evidence_missing" : null]);
+  }
+  db.run(`INSERT INTO node_create_requests(request_id,daemon_node_id,child_name,network_id,runtime,flags_json,env_keys,status,created_at,created_by_token)
+    VALUES('cr_read_created',?1,'created',?2,'codex-sdk','{}','[]','succeeded',1,'private-token')`, [ids.daemon, a.network_id]);
+  db.run(`INSERT INTO node_stop_requests(request_id,network_id,daemon_node_id,child_node_id,child_alias,action,created_by_token,status,error,created_at,acked_at)
+    VALUES('stop_read_failed',?1,?2,?3,'read-active','stop','private-token','stop_failed','adopt_explicit_private_socket_required',3,4)`, [a.network_id, ids.daemon, ids.active]);
+  db.run(`INSERT INTO node_start_requests(request_id,network_id,daemon_node_id,child_node_id,child_alias,created_by_token,status,error,created_at,acked_at)
+    VALUES('start_read_failed',?1,?2,?3,'read-active','private-token','start_failed','adopt_start_evidence_missing',5,6)`, [a.network_id, ids.daemon, ids.active]);
+  db.run("INSERT INTO sessions(resume_id,alias,node_id,network_id,status,last_seen_at) VALUES('read-daemon-session','read-daemon',?1,?2,'idle',datetime('now'))", [ids.daemon, a.network_id]);
+  const { generateNetworkToken, hashToken } = await import("./db.js");
+  daemonToken = generateNetworkToken();
+  db.run("INSERT INTO api_tokens(token_id,user_id,network_id,scope,name,token_hash) VALUES('read-daemon-token',?1,?2,'network','node:read-daemon',?3)", [a.user.user_id, a.network_id, hashToken(daemonToken)]);
+  const { bootServer } = await import("./server.js");
+  hub = bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${hub.port}`;
+}, 30_000);
+afterAll(() => hub?.stop(true));
+
+test("public errors redact free text for granted viewers on every projection", async () => {
+  db.run("INSERT INTO network_member_agent_grants(network_id,user_id,node_id,can_message) VALUES(?1,?2,?3,0)", [a.network_id, limited.user.user_id, ids.active]);
+  try {
+    for (const error of [
+      "/private/fixture/secret on fixture-host",
+      "not_my_child: daemon has no local record of fixture-node (fixture-id) — no children-map entry and no config at /private/fixture/fixture-node/config.json; refusing to signal processes by alias.",
+      "bin: ENOENT: /private/fixture/bin/anet on fixture-host",
+      "adopt_unknown_secret", "adopt_start_timeout: /private/fixture", "", "adopt_start_timeout", null,
+      "adopted_node_delete_unsupported", "adopt_codex_readopt_required", "adopt_stop_receipt_changed",
+      "adopt_codex_external_start_unproven", "adopt_codex_launch_failed", "adopt_codex_launch_timeout",
+      "adopt_codex_port_unproven", "adopt_codex_start_superseded", "adopt_codex_binding_generation_unproven",
+      "adopt_codex_start_evidence_missing", "adopt_codex_start_evidence_changed",
+      "adopt_codex_session_conflict", "adopt_codex_port_unavailable", "adopt_codex_stage_still_running",
+      "adopt_codex_identity_unproven",
+      "TUI session mismatch", "opencode_launch_health:TUI session mismatch", "opencode_tui_session_mismatch",
+    ]) {
+      const publicCodes = ["adopt_start_timeout", "adopted_node_delete_unsupported", "adopt_codex_readopt_required", "adopt_stop_receipt_changed", "opencode_tui_session_mismatch",
+        "adopt_codex_external_start_unproven", "adopt_codex_launch_failed", "adopt_codex_launch_timeout",
+        "adopt_codex_port_unproven", "adopt_codex_start_superseded", "adopt_codex_binding_generation_unproven",
+        "adopt_codex_start_evidence_missing", "adopt_codex_start_evidence_changed",
+        "adopt_codex_session_conflict", "adopt_codex_port_unavailable", "adopt_codex_stage_still_running",
+        "adopt_codex_identity_unproven"];
+      const expected = error === null || publicCodes.includes(error) ? error : "lifecycle_error";
+      for (const [kind, table, request] of [
+        ["adopt", "node_daemon_bindings", "adopt_read_active"],
+        ["start", "node_start_requests", "start_read_failed"],
+        ["stop", "node_stop_requests", "stop_read_failed"],
+      ]) {
+        db.run(`UPDATE ${table} SET error=?1 WHERE request_id=?2`, [error, request]);
+        for (const selector of [`request_id=${request}`, `node_id=${ids.active}`]) {
+          const r = await get(query(kind, selector), limited.token);
+          expect(r.status).toBe(200);
+          expect(r.body.request.error).toBe(expected);
+        }
+      }
+      const nodes = (await get(`/api/nodes?network_id=${a.network_id}`, limited.token)).body.nodes;
+      expect(nodes[0].adoption.error).toBe(expected);
+    }
+  } finally {
+    db.run("DELETE FROM network_member_agent_grants WHERE user_id=?1 AND node_id=?2", [limited.user.user_id, ids.active]);
+    db.run("UPDATE node_daemon_bindings SET error=NULL WHERE request_id='adopt_read_active'");
+    db.run("UPDATE node_start_requests SET error='adopt_start_evidence_missing' WHERE request_id='start_read_failed'");
+    db.run("UPDATE node_stop_requests SET error='adopt_explicit_private_socket_required' WHERE request_id='stop_read_failed'");
+  }
+});
+
+test("created projection prefers recorded child id and only falls back for legacy null", async () => {
+  const read = async () => (await get(`/api/nodes?network_id=${a.network_id}`)).body.nodes;
+  try {
+    expect((await read()).find((n: any) => n.node_id === ids.created).managed).toBe("created");
+    db.run("UPDATE node_create_requests SET child_node_id=?1 WHERE request_id='cr_read_created'", [ids.manual]);
+    let nodes = await read();
+    expect(nodes.find((n: any) => n.node_id === ids.manual).managed).toBe("created");
+    expect(nodes.find((n: any) => n.node_id === ids.created).managed).toBe("none");
+    db.run("UPDATE node_create_requests SET child_node_id='missing-child' WHERE request_id='cr_read_created'");
+    expect((await read()).find((n: any) => n.node_id === ids.created).managed).toBe("none");
+    db.run("UPDATE node_create_requests SET child_node_id=?1,network_id=?2 WHERE request_id='cr_read_created'", [ids.manual, b.network_id]);
+    nodes = await read();
+    expect(nodes.find((n: any) => n.node_id === ids.manual).managed).toBe("none");
+  } finally {
+    db.run("UPDATE node_create_requests SET child_node_id=NULL,network_id=?1 WHERE request_id='cr_read_created'", [a.network_id]);
+  }
+});
+
+test("authenticated port-0 HTTP projects actual authority, never an id prefix", async () => {
+  const { status, body } = await get(`/api/nodes?network_id=${a.network_id}`);
+  expect(status).toBe(200);
+  const rows = body.nodes;
+  expect(rows.find((r: any) => r.node_id === ids.created)).toMatchObject({ managed: "created", adoption: null, lifecycle_controllable: true });
+  expect(rows.find((r: any) => r.node_id === ids.manual)).toMatchObject({ managed: "none", adoption: null, lifecycle_controllable: false });
+  expect(rows.find((r: any) => r.node_id === ids.active)).toMatchObject({ managed: "adopted", adoption: { status: "active", request_id: "adopt_read_active" }, lifecycle_controllable: true });
+  for (const status of ["pending", "refused", "revoked"]) expect(rows.find((r: any) => r.node_id === `n_read_${status}`)).toMatchObject({ managed: "none", adoption: { status } });
+});
+test("adopt query preserves all persisted states, request id and bounded projection", async () => {
+  for (const status of ["pending", "active", "refused", "revoked"]) {
+    const r = await get(query("adopt", `request_id=adopt_read_${status}`));
+    expect(r.status).toBe(200);
+    expect(r.body.request).toMatchObject({ kind: "adopt", status, request_id: `adopt_read_${status}` });
+    expect(r.body.request.workdir).toBeUndefined();
+    expect(r.body.request.requested_by).toBeUndefined();
+  }
+});
+test("start/stop returns daemon failure codes; node selector returns latest, not success fiction", async () => {
+  for (const [kind, error] of [["start", "adopt_start_evidence_missing"], ["stop", "adopt_explicit_private_socket_required"]]) {
+    const r = await get(query(kind, `node_id=${ids.active}`));
+    expect(r.status).toBe(200);
+    expect(r.body.request).toMatchObject({ status: `${kind}_failed`, error, node_id: ids.active });
+    expect(r.body.request.created_by_token).toBeUndefined();
+  }
+  expect((await get(query("start", `node_id=${ids.manual}`))).body.request).toBeNull();
+});
+test("cross-network request and node guesses do not disclose data", async () => {
+  for (const kind of ["adopt", "start", "stop"]) {
+    const id = kind === "adopt" ? "adopt_read_active" : `${kind}_read_failed`;
+    const denied = await get(query(kind, `request_id=${id}`), b.token);
+    expect(denied.status).toBe(404);
+    expect(denied.body).toEqual((await get(query(kind, "request_id=nonexistent"), b.token)).body);
+    expect((await get(query(kind, `node_id=${ids.active}`), b.token)).status).toBe(404);
+    expect((await get(query(kind, `request_id=${id}&network_id=${a.network_id}`), b.token)).status).toBe(403);
+  }
+});
+test("fork receipt uses the same authenticated node visibility and redacts corrupt storage", async () => {
+  const receipt = { state: "forked", old_thread_id: "01a11846-d796-72f1-af68-8d9215a65dc8", new_thread_id: "01a11900-0000-7000-8000-000000000001" };
+  const path = query("start", "request_id=start_read_failed");
+  try {
+    db.run("UPDATE node_start_requests SET fork_recovery_json=?1,fork_result_json=?2 WHERE request_id='start_read_failed'",
+      [JSON.stringify({ kind: "fork_on_missing_ordinal", confirmed: true }), JSON.stringify(receipt)]);
+    expect((await get(path)).body.request.fork_recovery).toEqual({ requested: true, result: receipt });
+    expect((await get(path, b.token)).status).toBe(404);
+    expect((await get(path, limited.token)).status).toBe(404);
+    expect((await get(path, daemonToken)).status).toBe(403);
+    db.run("INSERT INTO network_member_agent_grants(network_id,user_id,node_id,can_message) VALUES(?1,?2,?3,0)", [a.network_id, limited.user.user_id, ids.active]);
+    expect((await get(path, limited.token)).body.request.fork_recovery.result).toEqual(receipt);
+    db.run("UPDATE node_start_requests SET fork_result_json=?1 WHERE request_id='start_read_failed'", [JSON.stringify({ ...receipt, snapshot: "/private/secret" })]);
+    const corrupted = await get(path, limited.token);
+    expect(corrupted.body.request.fork_recovery.result).toEqual({ state: "unknown", reason: "result_invalid" });
+    expect(JSON.stringify(corrupted)).not.toContain("/private");
+    // Corrupt confirmation cannot assert requested:true, but must not erase an
+    // independently valid recorded fork (nor make the request look ordinary).
+    for (const raw of ["broken /private/secret", "null", "{}", JSON.stringify({ kind: "fork_on_missing_ordinal", confirmed: false }),
+      JSON.stringify({ kind: "fork_on_missing_ordinal", confirmed: true, snapshot: "/private/secret" })]) {
+      db.run("UPDATE node_start_requests SET fork_recovery_json=?1,fork_result_json=?2 WHERE request_id='start_read_failed'", [raw, JSON.stringify(receipt)]);
+      const invalid = await get(path, limited.token);
+      expect(invalid.body.request.fork_recovery).toEqual({ requested: null, result: receipt });
+      expect(JSON.stringify(invalid)).not.toContain("/private");
+    }
+  } finally {
+    db.run("DELETE FROM network_member_agent_grants WHERE user_id=?1 AND node_id=?2", [limited.user.user_id, ids.active]);
+    db.run("UPDATE node_start_requests SET fork_recovery_json=NULL,fork_result_json=NULL WHERE request_id='start_read_failed'");
+  }
+});
+test("same-network restricted viewer without node grants cannot read requests", async () => {
+  for (const kind of ["adopt", "start", "stop"]) {
+    expect((await get(query(kind, `node_id=${ids.active}&network_id=${a.network_id}`), limited.token)).status).toBe(404);
+    const id = kind === "adopt" ? "adopt_read_active" : `${kind}_read_failed`;
+    expect((await get(query(kind, `request_id=${id}&network_id=${a.network_id}`), limited.token)).status).toBe(404);
+  }
+  expect((await get(`/api/nodes?network_id=${a.network_id}`, limited.token)).body.nodes).toEqual([]);
+});
+test("current node grant allows reads; revocation immediately closes them", async () => {
+  db.run("INSERT INTO network_member_agent_grants(network_id,user_id,node_id,can_message) VALUES(?1,?2,?3,0)", [a.network_id, limited.user.user_id, ids.active]);
+  try {
+    expect((await get(query("adopt", "request_id=adopt_read_active"), limited.token)).status).toBe(200);
+    const nodes = (await get(`/api/nodes?network_id=${a.network_id}`, limited.token)).body.nodes;
+    expect(nodes).toHaveLength(1);
+    expect(nodes[0].managed).toBe("adopted");
+  } finally { db.run("DELETE FROM network_member_agent_grants WHERE user_id=?1 AND node_id=?2", [limited.user.user_id, ids.active]); }
+  expect((await get(query("adopt", "request_id=adopt_read_active"), limited.token)).status).toBe(404);
+});
+test("daemon and legacy master do not gain the new user read surface", async () => {
+  for (const token of [daemonToken, process.env.COMMHUB_AUTH_TOKEN!]) {
+    expect((await get(query("adopt", "request_id=adopt_read_active"), token)).status).toBe(403);
+    const nodes = (await get(`/api/nodes?network_id=${a.network_id}`, token)).body.nodes;
+    expect(nodes.length).toBeGreaterThan(0);
+    expect(nodes.every((n: any) => !("managed" in n) && !("adoption" in n))).toBe(true);
+  }
+  expect((await get(query("adopt", "request_id=adopt_read_active"), "invalid")).status).toBe(401);
+  const queryOnly = await fetch(base + query("adopt", `request_id=adopt_read_active&token=${encodeURIComponent(a.token)}`));
+  expect([401, 403]).toContain(queryOnly.status);
+});
+test("host-supervisors capability respects user token and node visibility; absent stays absent", async () => {
+  const path = `/api/host-supervisors?network_id=${a.network_id}`;
+  expect((await get(path)).body.daemons.find((d: any) => d.daemon_node_id === ids.daemon).adopt_capable).toBe(true);
+  for (const token of [limited.token, daemonToken]) {
+    const r = await get(path, token);
+    expect((r.body.daemons ?? []).every((d: any) => !("adopt_capable" in d))).toBe(true);
+  }
+  db.run("UPDATE nodes SET config_snapshot=?1 WHERE node_id=?2", [JSON.stringify({ role: "host_supervisor", daemon_capabilities: { adopt_capable: false } }), ids.daemon]);
+  expect((await get(path)).body.daemons[0].adopt_capable).toBe(false);
+  db.run("UPDATE nodes SET config_snapshot=?1 WHERE node_id=?2", [JSON.stringify({ role: "host_supervisor" }), ids.daemon]);
+  expect((await get(path)).body.daemons[0].adopt_capable).toBeUndefined();
+});
+test("invalid selectors rejected rather than listing every lifecycle request", async () => {
+  for (const suffix of ["", "kind=adopt", "kind=other&node_id=x", "kind=start&request_id=x&node_id=y", "kind=stop&node_id=x&node_id=y", "kind=start&request_id=x&node_id=", "kind=adopt&node_id=%20"])
+    expect((await get(`/api/node-lifecycle-requests?${suffix}`)).status).toBe(400);
+});
+test("request state refresh exposes pending, completion and binding-missing failure without caching", async () => {
+  for (const [kind, statuses] of [["start", ["pending", "delivered", "started", "start_failed", "timeout"]], ["stop", ["pending", "delivered", "stopped", "stop_failed", "noop_not_my_child"]]] as const) {
+    for (const status of statuses) {
+      const error = status.endsWith("failed") ? "adopt_active_binding_required" : null;
+      db.run(`UPDATE node_${kind}_requests SET status=?1,error=?2 WHERE request_id=?3`, [status, error, `${kind}_read_failed`]);
+      expect((await get(query(kind, `request_id=${kind}_read_failed`))).body.request).toMatchObject({ status, error });
+    }
+  }
+});
+test("join refuses a request whose stored network disagrees with its target node", async () => {
+  db.run("UPDATE node_start_requests SET network_id=?1 WHERE request_id='start_read_failed'", [b.network_id]);
+  try {
+    expect((await get(query("start", "request_id=start_read_failed"))).status).toBe(404);
+    expect((await get(query("start", "request_id=start_read_failed"), b.token)).status).toBe(404);
+  } finally { db.run("UPDATE node_start_requests SET network_id=?1 WHERE request_id='start_read_failed'", [a.network_id]); }
+});

package/src/node-lifecycle-read.ts

@@ -0,0 +1,121 @@
+import { db } from "./db.js";
+import { addAgentNetworkScope, type RestNetworkScope } from "./network-scope.js";
+import { forkRecoveryRequestSchema, publicForkResult } from "./codex-fork-contract.js";
+
+// Exact public codes only; daemon exception text must never reach node viewers.
+const publicLifecycleErrors = new Set([
+  "codex_fork_confirmation_invalid", "codex_fork_recovery_unsupported", "codex_fork_cli_unsupported",
+  "codex_fork_result_invalid", "codex_fork_outcome_unknown",
+  "adopted_node_delete_unsupported", "adopt_codex_readopt_required", "adopt_stop_receipt_changed",
+  "adopt_codex_external_start_unproven", "adopt_codex_launch_failed", "adopt_codex_launch_timeout",
+  "adopt_codex_port_unproven", "adopt_codex_start_superseded", "adopt_codex_binding_generation_unproven",
+  "adopt_codex_start_evidence_missing", "adopt_codex_start_evidence_changed",
+  "adopt_codex_session_conflict", "adopt_codex_port_unavailable", "adopt_codex_stage_still_running",
+  "adopt_codex_identity_unproven",
+  "adopt_active_binding_required", "adopt_binding_unavailable",
+  "adopt_binding_revoked_during_start", "adopt_explicit_private_socket_required",
+  "adopt_start_evidence_missing", "adopt_stop_evidence_missing",
+  "adopt_launch_mode_mismatch", "adopt_lifecycle_verification_failed",
+  "adopt_process_generation_changed", "adopt_process_still_running",
+  "adopt_process_stop_timeout", "adopt_process_tree_unstable",
+  "adopt_registry_identity_mismatch", "adopt_self_process_refused",
+  "adopt_start_timeout", "adopt_tmux_session_still_exists",
+  "adopt_local_verification_failed", "adopt_roots_not_configured",
+  "adopt_workdir_outside_roots", "adopt_workdir_not_absolute",
+  "adopt_alias_invalid", "adopt_alias_mismatch", "adopt_config_invalid",
+  "adopt_config_network_mismatch", "adopt_network_mismatch",
+  "adopt_hub_invalid", "adopt_hub_missing", "adopt_hub_mismatch",
+  "adopt_identity_ambiguous", "adopt_identity_not_found", "adopt_identity_changed",
+  "adopt_path_not_regular", "adopt_path_owner_mismatch", "adopt_path_writable_by_others",
+  "adopt_process_argv_mismatch", "adopt_process_home_mismatch",
+  "adopt_process_identity_mismatch", "adopt_process_changed",
+  "adopt_tmux_socket_mismatch", "adopt_pane_invalid", "adopt_pane_unverified",
+  "adopt_pane_process_mismatch", "adopt_socket_directory_unsafe", "adopt_socket_unsafe",
+  "adopt_pid_changed", "adopt_pid_invalid", "adopt_pidfile_unsafe",
+  "opencode_tui_session_mismatch",
+  "adopt_proc_invalid", "adopt_proc_unreadable", "adopt_platform_unsupported",
+  "adopt_registry_conflict", "adopt_registry_entry_invalid", "adopt_registry_invalid",
+  "adopt_registry_unsafe", "adopt_config_env_invalid", "adopt_env_file_invalid",
+  "adopt_env_file_unsafe", "adopt_request_mismatch", "adopt_ack_rejected",
+]);
+function publicLifecycleError(error: unknown): string | null {
+  return error == null ? null
+    : typeof error === "string" && publicLifecycleErrors.has(error) ? error : "lifecycle_error";
+}
+
+type Adoption = { request_id: string; daemon_node_id: string; status: string; error: string | null };
+export type LifecycleProjection = { managed: "created" | "adopted" | "none"; adoption: Adoption | null };
+const scopeNodes = (sql: string, params: any[], scope: RestNetworkScope) =>
+  addAgentNetworkScope(sql, params, scope, { network: "n.network_id", nodeId: "n.node_id", alias: "n.alias" });
+
+/** Called only for authenticated human readers. Same visibility as /api/nodes;
+ * constant query count, no id-prefix or host-name inference of authority. */
+export function lifecycleProjections(scope: RestNetworkScope): Map<string, LifecycleProjection> {
+  const result = new Map<string, LifecycleProjection>();
+  const bp: any[] = [];
+  const bindings = db.all<Adoption & { node_id: string }>(scopeNodes(
+    `SELECT b.node_id,b.request_id,b.daemon_node_id,b.status,b.error
+       FROM node_daemon_bindings b JOIN nodes n ON n.node_id=b.node_id AND n.network_id=b.network_id
+      WHERE 1=1`, bp, scope) + " ORDER BY b.created_at DESC,b.request_id DESC", ...bp);
+  for (const b of bindings) {
+    let projection = result.get(b.node_id);
+    if (!projection) {
+      projection = { managed: "none", adoption: { request_id: b.request_id, daemon_node_id: b.daemon_node_id, status: b.status, error: publicLifecycleError(b.error) } };
+      result.set(b.node_id, projection);
+    }
+    if (b.status === "active") projection.managed = "adopted";
+  }
+  const cp: any[] = [];
+  const created = db.all<{ node_id: string }>(scopeNodes(
+    `SELECT n.node_id FROM node_create_requests c JOIN nodes n
+       ON n.node_id=COALESCE(c.child_node_id, CASE WHEN substr(c.request_id,1,3)='cr_'
+         THEN 'node_' || substr(c.request_id,4) END) AND n.network_id=c.network_id
+      WHERE 1=1`, cp, scope), ...cp);
+  for (const n of created) result.set(n.node_id, { managed: "created", adoption: result.get(n.node_id)?.adoption ?? null });
+  return result;
+}
+
+/** Read-only, selector-bound lookup. Join the live node in the SAME network,
+ * then apply its current visibility (including restricted member grants).
+ * Result fields exclude credentials, PID and config; error values separately
+ * use the exact public-code allowlist (daemon text may contain workdir paths). */
+export function lifecycleRequestResponse(url: URL, scope: RestNetworkScope): Response {
+  const kind = url.searchParams.get("kind");
+  const requestId = url.searchParams.get("request_id"), nodeId = url.searchParams.get("node_id");
+  const fail = (error: string, status: number) => Response.json({ ok: false, error }, { status });
+  if (!["adopt", "start", "stop"].includes(kind ?? "")
+      || url.searchParams.has("request_id") === url.searchParams.has("node_id")
+      || !(requestId ?? nodeId ?? "").trim()
+      || ["kind", "request_id", "node_id"].some(k => url.searchParams.getAll(k).length > 1)
+      || (requestId ?? nodeId ?? "").length > 200) return fail("invalid_lifecycle_query", 400);
+  // The table and column names below come only from this closed enum.
+  const table = kind === "adopt" ? "node_daemon_bindings" : kind === "start" ? "node_start_requests" : "node_stop_requests";
+  const nodeColumn = kind === "adopt" ? "node_id" : "child_node_id";
+  // A node lookup with no request must distinguish 'no requests' from 'not visible'.
+  if (nodeId) {
+    const params: any[] = [nodeId];
+    if (!db.get(scopeNodes("SELECT n.node_id FROM nodes n WHERE n.node_id=?1", params, scope), ...params))
+      return fail("node_not_found", 404);
+  }
+  const params: any[] = [requestId ?? nodeId];
+  const sql = scopeNodes(`SELECT r.request_id,r.${nodeColumn} AS node_id,r.network_id,r.daemon_node_id,
+      r.status,r.error,r.created_at,${kind === "adopt" ? "r.updated_at" : "r.acked_at,r.delivered_at"}
+      ${kind === "start" ? ",r.fork_recovery_json,r.fork_result_json" : ""}
+    FROM ${table} r JOIN nodes n ON n.node_id=r.${nodeColumn} AND n.network_id=r.network_id
+    WHERE r.${requestId ? "request_id" : nodeColumn}=?1${kind === "stop" ? " AND r.action='stop'" : ""}`, params, scope);
+  const row = db.get<Record<string, unknown>>(sql + " ORDER BY r.created_at DESC,r.request_id DESC LIMIT 1", ...params);
+  if (!row && requestId) return fail("request_not_found", 404);
+  if (!row) return Response.json({ ok: true, request: null });
+  const { fork_recovery_json, fork_result_json, ...publicRow } = row;
+  let confirmed: true | null = null;
+  if (kind === "start" && typeof fork_recovery_json === "string") {
+    try {
+      if (forkRecoveryRequestSchema.safeParse(JSON.parse(fork_recovery_json)).success) confirmed = true;
+    } catch { /* damaged confirmation is unknown; keep any independently valid fork evidence */ }
+  }
+  return Response.json({ ok: true, request: { kind, ...publicRow, error: publicLifecycleError(row.error),
+    ...(kind === "start" && fork_recovery_json != null ? { fork_recovery: {
+      requested: confirmed, result: publicForkResult(fork_result_json),
+    } } : {}),
+  } });
+}