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

package/src/admin-delete-network-http.test.ts

@@ -0,0 +1,228 @@
+// Hub 管理员删别人的**空**网络(清理旧测试账号留下的个人网络)。
+// 真 HTTP:走 DELETE /api/networks/:id,库和上传目录都是本文件私有的临时目录。
+//   bun test server/src/admin-delete-network-http.test.ts
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const PRIVATE_DIR = mkdtempSync(join(tmpdir(), "anet-admin-delete-network-"));
+process.env.COMMHUB_DB ||= join(PRIVATE_DIR, "hub.db");
+process.env.COMMHUB_UPLOADS_DIR = join(PRIVATE_DIR, "uploads");
+
+let server: ReturnType<typeof Bun.serve>;
+let base = "";
+let db: typeof import("./db.js").db;
+let auth: typeof import("./auth.js");
+let adminToken = "";
+let adminUserId = "";
+let adminNetworkId = "";
+let memberToken = "";
+let memberUserId = "";
+let memberNodeToken = "";
+const stamp = Date.now();
+
+function del(networkId: string, token: string) {
+  return fetch(`${base}/api/networks/${networkId}`, { method: "DELETE", headers: { Authorization: `Bearer ${token}` } });
+}
+
+function memberNetwork(name: string): string {
+  const created = auth.createNetwork(memberUserId, `${name}-${stamp}`);
+  expect(created.ok).toBe(true);
+  return created.network_id!;
+}
+
+function rowCount(table: string, networkId: string): number {
+  return db.get<{ cnt: number }>(`SELECT COUNT(*) AS cnt FROM ${table} WHERE network_id = ?1`, networkId)!.cnt;
+}
+
+// 同 admin-networks-http.test.ts:register() 跑 KDF + bootServer,给 30s 而不是 bun 默认 5s。
+beforeAll(async () => {
+  ({ db } = await import("./db.js"));
+  auth = await import("./auth.js");
+
+  // 第一个注册的是 Hub 管理员;第二个是普通用户,不在管理员的网络里。
+  const admin = auth.register(`admin_delnet_${stamp}`, "AdminDelNet-Strong-1!", undefined, "admin");
+  expect(admin.ok).toBe(true);
+  adminToken = admin.token!;
+  adminNetworkId = admin.network_id!;
+  adminUserId = db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", `admin_delnet_${stamp}`)!.user_id;
+
+  const member = auth.register(`member_delnet_${stamp}`, "MemberDelNet-Strong-1!", undefined, "member");
+  expect(member.ok).toBe(true);
+  memberToken = member.token!;
+  memberUserId = db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", `member_delnet_${stamp}`)!.user_id;
+  expect(db.get<{ role: string }>("SELECT role FROM users WHERE user_id = ?1", adminUserId)!.role).toBe("admin");
+  expect(db.get<{ role: string }>("SELECT role FROM users WHERE user_id = ?1", memberUserId)!.role).not.toBe("admin");
+  // free 档只能拥有 2 个网络;本文件要给它建七八个。plan 只影响配额,不影响任何权限判定。
+  db.run("UPDATE users SET plan = 'pro' WHERE user_id = ?1", [memberUserId]);
+
+  const minted = auth.createNetworkTokenForNode(memberUserId, member.network_id!, "delnet-node");
+  expect(minted.ok).toBe(true);
+  memberNodeToken = minted.token!;
+
+  const mod = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { server?.stop(true); } catch {}
+  try { rmSync(PRIVATE_DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("DELETE /api/networks/:id — hub admin override for empty foreign networks", () => {
+  test("admin deletes an empty foreign network: 200, network + members + scoped tokens gone, audit has admin_override", async () => {
+    const netId = memberNetwork("empty");
+    const minted = auth.createNetworkTokenForNode(memberUserId, netId, "leftover-node");
+    expect(minted.ok).toBe(true);
+    expect(rowCount("network_members", netId)).toBe(1);
+    expect(rowCount("api_tokens", netId)).toBe(1);
+
+    const res = await del(netId, adminToken);
+    const body = await res.json() as any;
+    expect(res.status).toBe(200);
+    expect(body.ok).toBe(true);
+    expect(body.admin_override).toBe(true);
+
+    expect(db.get("SELECT 1 AS x FROM networks WHERE network_id = ?1", netId)).toBeFalsy();
+    expect(rowCount("network_members", netId)).toBe(0);
+    expect(rowCount("api_tokens", netId)).toBe(0);
+    // 被删网络的节点令牌不再能解析。
+    expect(auth.resolveToken(minted.token!)).toBeFalsy();
+
+    const audit = db.get<{ user_id: string; detail: string; network_id: string }>(
+      "SELECT user_id, detail, network_id FROM audit_log WHERE action = 'network_deleted' AND target_id = ?1", netId);
+    expect(audit).toBeTruthy();
+    expect(audit!.user_id).toBe(adminUserId);
+    const detail = JSON.parse(audit!.detail);
+    expect(detail.admin_override).toBe(true);
+    expect(detail.owner_id).toBe(memberUserId);
+  });
+
+  test("admin is refused with 409 and counts when the network has a node and a session", async () => {
+    const netId = memberNetwork("busy");
+    db.run("INSERT INTO nodes (node_id, node_name, alias, network_id, created_at, updated_at) VALUES (?1, ?2, ?2, ?3, datetime('now'), datetime('now'))",
+      [`node-${stamp}`, `busy-node-${stamp}`, netId]);
+    db.run("INSERT INTO sessions (resume_id, alias, network_id) VALUES (?1, ?2, ?3)", [`resume-${stamp}`, `busy-node-${stamp}`, netId]);
+
+    const res = await del(netId, adminToken);
+    const body = await res.json() as any;
+    expect(res.status).toBe(409);
+    expect(body.ok).toBe(false);
+    expect(body.counts).toEqual({ nodes: 1, sessions: 1 });
+    expect(body.error).toContain("nodes=1");
+    expect(db.get("SELECT 1 AS x FROM networks WHERE network_id = ?1", netId)).toBeTruthy();
+    expect(rowCount("network_members", netId)).toBe(1);
+  });
+
+  test("admin is refused when the only content left is an uploaded file (disk index, not the DB)", async () => {
+    const netId = memberNetwork("files");
+    const indexDir = join(process.env.COMMHUB_UPLOADS_DIR!, ".index");
+    mkdirSync(indexDir, { recursive: true });
+    writeFileSync(join(indexDir, `f${stamp}.json`), JSON.stringify({ file_id: `f${stamp}`, network_id: netId }));
+
+    const res = await del(netId, adminToken);
+    const body = await res.json() as any;
+    expect(res.status).toBe(409);
+    expect(body.counts).toEqual({ files: 1 });
+    expect(db.get("SELECT 1 AS x FROM networks WHERE network_id = ?1", netId)).toBeTruthy();
+  });
+
+  test("admin cannot delete the 'default' network even when it is empty", async () => {
+    db.run("INSERT INTO networks (network_id, network_name, owner_id) VALUES ('default', ?1, ?2)", [`legacy-default-${stamp}`, memberUserId]);
+    const res = await del("default", adminToken);
+    expect(res.status).toBe(409);
+    expect(((await res.json()) as any).error).toContain("default");
+    expect(db.get("SELECT 1 AS x FROM networks WHERE network_id = 'default'")).toBeTruthy();
+  });
+
+  test("a non-admin user cannot delete someone else's network", async () => {
+    const res = await del(adminNetworkId, memberToken);
+    expect(res.status).toBe(400);
+    expect(((await res.json()) as any).error).toBe("not your network");
+    expect(db.get("SELECT 1 AS x FROM networks WHERE network_id = ?1", adminNetworkId)).toBeTruthy();
+  });
+
+  test("a node token is refused with user_token_required", async () => {
+    const netId = memberNetwork("ntok");
+    const res = await del(netId, memberNodeToken);
+    expect(res.status).toBe(403);
+    expect(((await res.json()) as any).error).toBe("user_token_required");
+    expect(db.get("SELECT 1 AS x FROM networks WHERE network_id = ?1", netId)).toBeTruthy();
+  });
+
+  test("owner path is unchanged: owner deletes own network (even with a node row), sessions still block it", async () => {
+    const withNode = memberNetwork("owner-node");
+    db.run("INSERT INTO nodes (node_id, node_name, alias, network_id, created_at, updated_at) VALUES (?1, ?2, ?2, ?3, datetime('now'), datetime('now'))",
+      [`owner-node-${stamp}`, `owner-node-${stamp}`, withNode]);
+    const ok = await del(withNode, memberToken);
+    expect(ok.status).toBe(200);
+    expect(await ok.json()).toEqual({ ok: true });
+
+    const withSession = memberNetwork("owner-session");
+    db.run("INSERT INTO sessions (resume_id, alias, network_id) VALUES (?1, ?2, ?3)", [`owner-resume-${stamp}`, `owner-s-${stamp}`, withSession]);
+    const blocked = await del(withSession, memberToken);
+    expect(blocked.status).toBe(400);
+    expect(((await blocked.json()) as any).error).toContain("active session");
+  });
+
+  test("admin deleting its OWN network goes through the owner path (no admin_override)", async () => {
+    const created = auth.createNetwork(adminUserId, `admin-own-${stamp}`);
+    expect(created.ok).toBe(true);
+    const res = await del(created.network_id!, adminToken);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true });
+  });
+
+  // #2144 —— Agent 分组(#2131)的三张表。
+  function addGroup(netId: string, tag: string): string {
+    const groupId = `grp-${tag}-${stamp}`;
+    db.run("INSERT INTO agent_groups (group_id, network_id, name) VALUES (?1, ?2, ?3)", [groupId, netId, `g-${tag}`]);
+    db.run("INSERT INTO agent_group_members (group_id, node_id) VALUES (?1, ?2)", [groupId, `node-${tag}-${stamp}`]);
+    db.run("INSERT INTO network_member_group_grants (network_id, user_id, group_id) VALUES (?1, ?2, ?3)", [netId, memberUserId, groupId]);
+    return groupId;
+  }
+  function groupRows(netId: string, groupId: string) {
+    return {
+      agent_groups: rowCount("agent_groups", netId),
+      agent_group_members: db.get<{ cnt: number }>("SELECT COUNT(*) AS cnt FROM agent_group_members WHERE group_id = ?1", groupId)!.cnt,
+      network_member_group_grants: rowCount("network_member_group_grants", netId),
+    };
+  }
+
+  test("#2144 admin is refused with 409 counts.agent_groups when the network has an agent group", async () => {
+    const netId = memberNetwork("grouped");
+    const groupId = addGroup(netId, "admin-blocked");
+    const res = await del(netId, adminToken);
+    const body = await res.json() as any;
+    expect(res.status).toBe(409);
+    expect(body.counts).toEqual({ agent_groups: 1 });
+    expect(db.get("SELECT 1 AS x FROM networks WHERE network_id = ?1", netId)).toBeTruthy();
+    expect(groupRows(netId, groupId)).toEqual({ agent_groups: 1, agent_group_members: 1, network_member_group_grants: 1 });
+  });
+
+  test("#2144 admin delete of an otherwise-empty network cleans orphan group grants", async () => {
+    const netId = memberNetwork("orphan-grant");
+    db.run("INSERT INTO network_member_group_grants (network_id, user_id, group_id) VALUES (?1, ?2, ?3)", [netId, memberUserId, `grp-gone-${stamp}`]);
+    const res = await del(netId, adminToken);
+    const body = await res.json() as any;
+    expect(res.status).toBe(200);
+    expect(body.cleaned.network_member_group_grants).toBe(1);
+    expect(rowCount("network_member_group_grants", netId)).toBe(0);
+  });
+
+  test("#2144 owner delete removes the network's groups, group members and group grants, and leaves other networks' groups", async () => {
+    const netId = memberNetwork("owner-grouped");
+    const groupId = addGroup(netId, "owner");
+    const otherNet = memberNetwork("owner-grouped-other");
+    const otherGroup = addGroup(otherNet, "other");
+
+    const res = await del(netId, memberToken);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true });
+    expect(db.get("SELECT 1 AS x FROM networks WHERE network_id = ?1", netId)).toBeFalsy();
+    expect(groupRows(netId, groupId)).toEqual({ agent_groups: 0, agent_group_members: 0, network_member_group_grants: 0 });
+    expect(groupRows(otherNet, otherGroup)).toEqual({ agent_groups: 1, agent_group_members: 1, network_member_group_grants: 1 });
+  });
+});

package/src/admin-networks-http.test.ts

@@ -0,0 +1,88 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { NETWORK_REST_COLUMNS } from "./rest-projections.js";
+
+const PRIVATE_DB_DIR = mkdtempSync(join(tmpdir(), "anet-admin-networks-"));
+process.env.COMMHUB_DB ||= join(PRIVATE_DB_DIR, "hub.db");
+
+let server: ReturnType<typeof Bun.serve>;
+let base = "";
+let adminToken = "";
+let memberToken = "";
+let nodeToken = "";
+let adminNetworkId = "";
+let memberNetworkId = "";
+
+async function listNetworks(token: string): Promise<any[]> {
+  const response = await fetch(`${base}/api/networks`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  expect(response.status).toBe(200);
+  const body = await response.json() as any;
+  expect(body.ok).toBe(true);
+  return body.networks;
+}
+
+// 30s 而不是 bun 默认的 5s:这个 hook 跑 register()(KDF)+bootServer(),
+// 本机空载基线 ~620ms,而 2026-08-17 与 2026-08-31 两次 CI 上它被 5s 上限打死
+// (0 pass / 1 fail / Ran 1 test —— 见 #928、#1627)。5247ms 是**被截断的下界**,
+// 不是测量值,所以余量按基线的 ~48x 取,而不是按那个数取。
+beforeAll(async () => {
+  const { db } = await import("./db.js");
+  const { createNetworkTokenForNode, register } = await import("./auth.js");
+
+  // The first registered user is the global Hub admin. The second user owns a
+  // separate network and is intentionally not a member of the admin's network.
+  const admin = register(`admin_networks_${Date.now()}`, "AdminNetworks-Strong-1!", undefined, "admin");
+  expect(admin.ok).toBe(true);
+  adminToken = admin.token!;
+  adminNetworkId = admin.network_id!;
+
+  const member = register(`member_networks_${Date.now()}`, "MemberNetworks-Strong-1!", undefined, "member");
+  expect(member.ok).toBe(true);
+  memberToken = member.token!;
+  memberNetworkId = member.network_id!;
+
+  const memberUserId = db.get<{ user_id: string }>(
+    "SELECT user_id FROM users WHERE username LIKE 'member_networks_%' ORDER BY created_at DESC LIMIT 1",
+  )!.user_id;
+  const minted = createNetworkTokenForNode(memberUserId, memberNetworkId, "admin-networks-node");
+  expect(minted.ok).toBe(true);
+  nodeToken = minted.token!;
+
+  const mod = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { server?.stop(true); } catch {}
+  try { rmSync(PRIVATE_DB_DIR, { recursive: true, force: true }); } catch {}
+});
+
+describe("GET /api/networks global-admin visibility (#94)", () => {
+  test("global admin utok sees every network without losing public shape", async () => {
+    const rows = await listNetworks(adminToken);
+    expect(new Set(rows.map((row) => row.network_id))).toEqual(new Set([adminNetworkId, memberNetworkId]));
+
+    const own = rows.find((row) => row.network_id === adminNetworkId);
+    const foreign = rows.find((row) => row.network_id === memberNetworkId);
+    expect(own.member_role).toBe("owner");
+    expect(foreign.member_role).toBe("admin");
+    expect(Object.keys(foreign).sort()).toEqual([...NETWORK_REST_COLUMNS, "member_role", "name"].sort());
+  });
+
+  test("ordinary utok remains limited to member networks", async () => {
+    const rows = await listNetworks(memberToken);
+    expect(rows.map((row) => row.network_id)).toEqual([memberNetworkId]);
+    expect(rows.some((row) => row.network_id === adminNetworkId)).toBe(false);
+  });
+
+  test("network token remains limited to its bound network", async () => {
+    const rows = await listNetworks(nodeToken);
+    expect(rows.map((row) => row.network_id)).toEqual([memberNetworkId]);
+    expect(rows.some((row) => row.network_id === adminNetworkId)).toBe(false);
+  });
+});

package/src/adoption-candidates-http.test.ts

@@ -0,0 +1,137 @@
+import { afterAll, beforeAll, 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(), "adoption-candidates-"));
+process.env.COMMHUB_DB ||= join(dir, "hub.db");
+process.env.COMMHUB_AUTH_TOKEN ||= "adoption-candidates-master-fixture";
+const WORKDIR = "/home/example/adoption-candidate-workdir-654";
+const SECRET = "ntok_should_not_surface";
+let hub: { stop: (closeActiveConnections?: boolean) => void; port: number }, base: string;
+let db: any, owner: any, member: any, nodeOwner: any, other: any, daemonToken: string;
+const ids = { daemon: "n_cand_daemon", hand: "n_cand_hand", foreign: "n_cand_foreign" };
+
+const get = async (path: string, token = owner.token) => {
+  const res = await fetch(base + path, { headers: { Authorization: `Bearer ${token}` } });
+  return { status: res.status, body: await res.json() as any, text: "" };
+};
+const raw = async (path: string, token = owner.token) => {
+  const res = await fetch(base + path, { headers: { Authorization: `Bearer ${token}` } });
+  const text = await res.text();
+  return { status: res.status, text, body: JSON.parse(text) };
+};
+
+function snapshot(candidates: unknown, adopt = true) {
+  return JSON.stringify({
+    role: "host_supervisor",
+    daemon_capabilities: { adopt_capable: adopt, adoption_candidates: candidates },
+  });
+}
+
+beforeAll(async () => {
+  ({ db } = await import("./db.js"));
+  const { register } = await import("./auth.js");
+  const suffix = Date.now();
+  owner = register(`cand_owner_${suffix}`, "CandFixture-Strong1!");
+  member = register(`cand_member_${suffix}`, "CandFixture-Strong1!");
+  nodeOwner = register(`cand_node_owner_${suffix}`, "CandFixture-Strong1!");
+  other = register(`cand_other_${suffix}`, "CandFixture-Strong1!");
+  expect(owner.ok && member.ok && nodeOwner.ok && other.ok).toBe(true);
+  for (const user of [owner, member, nodeOwner, other]) 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) VALUES(?1,?2,'member')", [owner.network_id, member.user.user_id]);
+  db.run("INSERT INTO network_members(network_id,user_id,role) VALUES(?1,?2,'member')", [owner.network_id, nodeOwner.user.user_id]);
+  const candidate = { node_id: ids.hand, alias: "hand-node", workdir: WORKDIR, runtime: "claude-agent-sdk", launch_hint: "tmux", token: SECRET, env: { API_KEY: SECRET } };
+  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)",
+    [ids.daemon, "cand-daemon", owner.network_id, owner.user.user_id, snapshot([candidate, { node_id: "n_missing", alias: "nope", workdir: "/tmp/nope", launch_hint: "bare" }])]);
+  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','{}')",
+    [ids.hand, "hand-node", owner.network_id, nodeOwner.user.user_id]);
+  db.run("INSERT INTO nodes(node_id,node_name,alias,network_id,owner_user_id,hostname) VALUES(?1,?2,?2,?3,?4,'other-host')",
+    [ids.foreign, "foreign-node", other.network_id, other.user.user_id]);
+  db.run("INSERT INTO sessions(resume_id,alias,node_id,network_id,status,last_seen_at) VALUES('cand-daemon-session','cand-daemon',?1,?2,'idle',datetime('now'))",
+    [ids.daemon, owner.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('cand-daemon-token',?1,?2,'network','node:cand-daemon',?3)",
+    [owner.user.user_id, owner.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("owner and node owner see the candidate; the report token stays out", async () => {
+  for (const token of [owner.token, nodeOwner.token]) {
+    const r = await raw(`/api/adoption-candidates?network_id=${owner.network_id}`, token);
+    expect(r.status).toBe(200);
+    expect(r.body.count).toBe(1);
+    expect(r.body.candidates).toEqual([{
+      node_id: ids.hand, alias: "hand-node", daemon_node_id: ids.daemon, daemon_alias: "cand-daemon",
+      hostname: "fixture-host", workdir: WORKDIR, runtime: "claude-agent-sdk", launch_hint: "tmux",
+    }]);
+    expect(r.text).not.toContain(SECRET);
+    expect(r.text).toContain(WORKDIR);
+  }
+  const supervisors = await raw(`/api/host-supervisors?network_id=${owner.network_id}`);
+  expect(supervisors.body.daemons.find((d: any) => d.daemon_node_id === ids.daemon).adoption_discovery).toBe(true);
+  expect(supervisors.text).not.toContain(WORKDIR);
+  expect(supervisors.text).not.toContain(SECRET);
+  const nodes = await raw(`/api/nodes?network_id=${owner.network_id}`);
+  expect(nodes.text).not.toContain("adoption_candidate");
+  expect(nodes.text).not.toContain(WORKDIR);
+});
+
+test("member, other network, daemon token, and query token do not receive the workdir", async () => {
+  const memberRes = await raw(`/api/adoption-candidates?network_id=${owner.network_id}`, member.token);
+  expect(memberRes.status).toBe(200);
+  expect(memberRes.body.candidates).toEqual([]);
+  expect(memberRes.text).not.toContain(WORKDIR);
+  const otherRes = await raw(`/api/adoption-candidates?network_id=${owner.network_id}`, other.token);
+  expect(otherRes.status).toBe(403);
+  expect(otherRes.text).not.toContain(WORKDIR);
+  expect((await get("/api/adoption-candidates", daemonToken)).status).toBe(403);
+  expect((await get("/api/adoption-candidates", process.env.COMMHUB_AUTH_TOKEN!)).status).toBe(403);
+  const queryOnly = await fetch(base + `/api/adoption-candidates?network_id=${owner.network_id}&token=${encodeURIComponent(owner.token)}`);
+  expect([401, 403]).toContain(queryOnly.status);
+});
+
+test("offline, hostname, alias, binding, and created-node filters drop the hint", async () => {
+  const path = `/api/adoption-candidates?network_id=${owner.network_id}`;
+  db.run("UPDATE sessions SET last_seen_at='2000-01-01 00:00:00' WHERE alias='cand-daemon'");
+  expect((await get(path)).body.candidates).toEqual([]);
+  db.run("UPDATE sessions SET last_seen_at=datetime('now') WHERE alias='cand-daemon'");
+  expect((await get(path)).body.count).toBe(1);
+
+  db.run("UPDATE nodes SET hostname='elsewhere' WHERE node_id=?1", [ids.hand]);
+  expect((await get(path)).body.candidates).toEqual([]);
+  db.run("UPDATE nodes SET hostname='fixture-host' WHERE node_id=?1", [ids.hand]);
+
+  db.run("UPDATE nodes SET config_snapshot=?1 WHERE node_id=?2", [snapshot([{ node_id: ids.hand, alias: "other-name", workdir: WORKDIR, launch_hint: "stopped" }]), ids.daemon]);
+  expect((await get(path)).body.candidates).toEqual([]);
+  db.run("UPDATE nodes SET config_snapshot=?1 WHERE node_id=?2", [snapshot([{ node_id: ids.hand, alias: "hand-node", workdir: WORKDIR, runtime: "claude-agent-sdk", launch_hint: "tmux", token: SECRET }]), ids.daemon]);
+  expect((await get(path)).body.count).toBe(1);
+
+  db.run(`INSERT INTO node_daemon_bindings(request_id,network_id,node_id,daemon_node_id,workdir,requested_by,status,created_at,updated_at)
+    VALUES('adopt_cand_pending',?1,?2,?3,?4,?5,'pending',1,1)`, [owner.network_id, ids.hand, ids.daemon, WORKDIR, owner.user.user_id]);
+  expect((await get(path)).body.candidates).toEqual([]);
+  db.run("UPDATE node_daemon_bindings SET status='revoked' WHERE request_id='adopt_cand_pending'");
+  expect((await get(path)).body.count).toBe(1);
+
+  db.run(`INSERT INTO node_create_requests(request_id,daemon_node_id,child_node_id,child_name,network_id,runtime,flags_json,env_keys,status,created_at,created_by_token)
+    VALUES('cr_cand_hand',?1,?2,'hand-node',?3,'claude-agent-sdk','{}','[]','succeeded',1,'private')`, [ids.daemon, ids.hand, owner.network_id]);
+  expect((await get(path)).body.candidates).toEqual([]);
+  db.run("DELETE FROM node_create_requests WHERE request_id='cr_cand_hand'");
+  expect((await get(path)).body.count).toBe(1);
+});
+
+test("discovery flag is absent unless the daemon actually reported a list", async () => {
+  const path = `/api/host-supervisors?network_id=${owner.network_id}`;
+  db.run("UPDATE nodes SET config_snapshot=?1 WHERE node_id=?2", [JSON.stringify({ role: "host_supervisor", daemon_capabilities: { adopt_capable: true } }), ids.daemon]);
+  expect((await get(path)).body.daemons[0].adoption_discovery).toBeUndefined();
+  expect((await get(path)).body.daemons[0].adopt_capable).toBe(true);
+  db.run("UPDATE nodes SET config_snapshot=?1 WHERE node_id=?2", [snapshot([], true), ids.daemon]);
+  expect((await get(path)).body.daemons[0].adoption_discovery).toBe(true);
+  expect((await get(`/api/adoption-candidates?network_id=${owner.network_id}`)).body.candidates).toEqual([]);
+  const limited = await get(path, member.token);
+  expect(limited.body.daemons.find((d: any) => d.daemon_node_id === ids.daemon).adoption_discovery).toBe(true);
+});

package/src/adoption-candidates.ts

@@ -0,0 +1,158 @@
+// Board #654 — project daemon-reported hand-started adoption candidates.
+//
+// The daemon report is a hint, not authority. This module does not adopt,
+// bind, signal, start, or stop. Co-presence / three-stage nodes are not
+// part of the report contract: discovery on the daemon excludes them.
+// `GET /api/nodes` managed/adoption and `/api/node-lifecycle-requests`
+// stay records of requests that already exist; they are not this list.
+import { z } from "zod/v4";
+import { db } from "./db.js";
+import { getUserNetworkRole } from "./auth.js";
+import { parseDbTimestampMs } from "./db-timestamp.js";
+import { addAgentNetworkScope, addHumanNetworkScope, type RestNetworkScope } from "./network-scope.js";
+
+const HINTS = new Set(["bare", "tmux", "stopped", "unverified"]);
+const ONLINE_MS = 5 * 60_000;
+const MAX_PUBLIC = 64;
+
+export interface AdoptionCandidateReport {
+  node_id: string;
+  alias: string;
+  workdir: string;
+  runtime: string | null;
+  launch_hint: "bare" | "tmux" | "stopped" | "unverified";
+}
+
+export function sanitizeAdoptionCandidate(raw: unknown): AdoptionCandidateReport | null {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const row = raw as Record<string, unknown>;
+  const { node_id, alias, workdir, launch_hint } = row;
+  if (typeof node_id !== "string" || node_id.length < 1 || node_id.length > 128 || /[\x00-\x1f\x7f]/.test(node_id)) return null;
+  if (typeof alias !== "string" || alias.length < 1 || alias.length > 128 || /[\x00-\x1f\x7f/\\]/.test(alias)
+      || alias === "." || alias === ".." || alias.startsWith("-")) return null;
+  if (typeof workdir !== "string" || !workdir.startsWith("/") || workdir.length > 1024 || /[\x00-\x1f]/.test(workdir)) return null;
+  if (typeof launch_hint !== "string" || !HINTS.has(launch_hint)) return null;
+  let runtime: string | null = null;
+  if (row.runtime != null) {
+    if (typeof row.runtime !== "string" || row.runtime.length < 1 || row.runtime.length > 64 || !/^[A-Za-z0-9._-]+$/.test(row.runtime)) return null;
+    runtime = row.runtime;
+  }
+  return { node_id, alias, workdir, runtime, launch_hint: launch_hint as AdoptionCandidateReport["launch_hint"] };
+}
+
+const adoptionCandidateItemSchema = z.object({
+  node_id: z.string().min(1).max(128),
+  alias: z.string().min(1).max(128),
+  workdir: z.string().regex(/^\/[^\u0000-\u001f]{0,1023}$/),
+  runtime: z.string().min(1).max(64).nullable().optional(),
+  launch_hint: z.enum(["bare", "tmux", "stopped", "unverified"]),
+}).strip().catch(null);
+
+/** Ingest path for report_status. One bad item becomes null; a bad list never fails the heartbeat.
+ * No transform: tools/list JSON Schema cannot represent one. Readers drop nulls. */
+export const adoptionCandidatesReportSchema = z.array(adoptionCandidateItemSchema).max(32).optional().catch(undefined);
+
+function snapshotValue(snapshot: unknown): Record<string, any> | null {
+  try {
+    const parsed = typeof snapshot === "string" ? JSON.parse(snapshot) : snapshot;
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch { return null; }
+}
+
+export function snapshotReportsAdoptionDiscovery(snapshot: unknown): boolean {
+  const caps = snapshotValue(snapshot)?.daemon_capabilities;
+  return caps?.adopt_capable === true && Array.isArray(caps.adoption_candidates);
+}
+
+function reportedCandidates(snapshot: unknown): AdoptionCandidateReport[] {
+  const raw = snapshotValue(snapshot)?.daemon_capabilities?.adoption_candidates;
+  if (!Array.isArray(raw)) return [];
+  const out: AdoptionCandidateReport[] = [];
+  for (const item of raw) {
+    const clean = sanitizeAdoptionCandidate(item);
+    if (clean) out.push(clean);
+    if (out.length >= 32) break;
+  }
+  return out;
+}
+
+type NodeRow = {
+  node_id: string; alias: string; hostname: string | null; network_id: string;
+  owner_user_id?: string | null; config_snapshot?: string | null; last_seen_at?: string | null;
+};
+
+export function listAdoptionCandidates(
+  scope: RestNetworkScope,
+  viewer: { userId: string; isAdmin: boolean },
+  nowMs = Date.now(),
+): { ok: true; candidates: Array<AdoptionCandidateReport & { daemon_node_id: string; daemon_alias: string; hostname: string }>; count: number } {
+  const daemonParams: any[] = [];
+  let daemonSql = `SELECT n.node_id, n.alias, n.hostname, n.network_id, n.config_snapshot, s.last_seen_at
+    FROM nodes n
+    LEFT JOIN sessions s ON s.alias = n.alias AND (s.network_id = n.network_id OR s.network_id IS NULL)
+    WHERE EXISTS (
+      SELECT 1 FROM api_tokens t
+      WHERE t.network_id = n.network_id AND t.name = 'node:' || n.alias AND t.revoked_at IS NULL
+    )`;
+  daemonSql = addHumanNetworkScope(daemonSql, daemonParams, scope, "n.network_id");
+  const daemonRows = db.all<NodeRow>(daemonSql, ...daemonParams);
+  const daemons = new Map<string, NodeRow>();
+  for (const row of daemonRows) {
+    const prev = daemons.get(row.node_id);
+    if (!prev || parseDbTimestampMs(row.last_seen_at ?? "") > parseDbTimestampMs(prev.last_seen_at ?? "")) daemons.set(row.node_id, row);
+  }
+
+  const nodeParams: any[] = [];
+  let nodeSql = "SELECT n.node_id, n.alias, n.hostname, n.network_id, n.owner_user_id, n.config_snapshot FROM nodes n WHERE 1=1";
+  nodeSql = addAgentNetworkScope(nodeSql, nodeParams, scope, { network: "n.network_id", alias: "n.alias", nodeId: "n.node_id" });
+  const visible = new Map(db.all<NodeRow>(nodeSql, ...nodeParams).map((n) => [n.node_id, n]));
+
+  const managed = new Set<string>();
+  const bindingParams: any[] = [];
+  let bindingSql = `SELECT b.node_id FROM node_daemon_bindings b
+    JOIN nodes n ON n.node_id = b.node_id AND n.network_id = b.network_id
+    WHERE b.status IN ('pending','active')`;
+  bindingSql = addHumanNetworkScope(bindingSql, bindingParams, scope, "b.network_id");
+  for (const row of db.all<{ node_id: string }>(bindingSql, ...bindingParams)) managed.add(row.node_id);
+  const createdParams: any[] = [];
+  let createdSql = `SELECT COALESCE(c.child_node_id, CASE WHEN substr(c.request_id,1,3)='cr_' THEN 'node_' || substr(c.request_id,4) END) AS node_id
+    FROM node_create_requests c WHERE 1=1`;
+  createdSql = addHumanNetworkScope(createdSql, createdParams, scope, "c.network_id");
+  for (const row of db.all<{ node_id: string | null }>(createdSql, ...createdParams)) if (row.node_id) managed.add(row.node_id);
+
+  const roles = new Map<string, string | null>();
+  const maySee = (node: NodeRow) => {
+    if (viewer.isAdmin) return true;
+    if (node.owner_user_id && node.owner_user_id === viewer.userId) return true;
+    if (!roles.has(node.network_id)) roles.set(node.network_id, getUserNetworkRole(viewer.userId, node.network_id));
+    const role = roles.get(node.network_id);
+    return role === "owner" || role === "admin";
+  };
+
+  const candidates: Array<AdoptionCandidateReport & { daemon_node_id: string; daemon_alias: string; hostname: string }> = [];
+  const seen = new Set<string>();
+  for (const daemon of daemons.values()) {
+    const snap = snapshotValue(daemon.config_snapshot);
+    if (snap?.role !== "host_supervisor" || snap.daemon_capabilities?.adopt_capable !== true) continue;
+    if (!daemon.hostname) continue;
+    const seenAt = parseDbTimestampMs(daemon.last_seen_at ?? "");
+    if (!Number.isFinite(seenAt) || nowMs - seenAt > ONLINE_MS) continue;
+    for (const reported of reportedCandidates(daemon.config_snapshot)) {
+      if (candidates.length >= MAX_PUBLIC) break;
+      const node = visible.get(reported.node_id);
+      if (!node || node.network_id !== daemon.network_id || node.alias !== reported.alias) continue;
+      if (!node.hostname || node.hostname !== daemon.hostname) continue;
+      if (snapshotValue(node.config_snapshot)?.role === "host_supervisor") continue;
+      if (managed.has(node.node_id) || !maySee(node)) continue;
+      const key = `${daemon.node_id}\0${node.node_id}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      candidates.push({
+        node_id: node.node_id, alias: node.alias, daemon_node_id: daemon.node_id, daemon_alias: daemon.alias,
+        hostname: daemon.hostname, workdir: reported.workdir, runtime: reported.runtime, launch_hint: reported.launch_hint,
+      });
+    }
+  }
+  candidates.sort((a, b) => a.alias.localeCompare(b.alias) || a.node_id.localeCompare(b.node_id) || a.daemon_node_id.localeCompare(b.daemon_node_id));
+  return { ok: true, candidates, count: candidates.length };
+}