@sleep2agi/commhub-server 0.9.0-preview.105 → 0.9.0-preview.107

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.105",
+  "version": "0.9.0-preview.107",
   "description": "CommHub Server — AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and MCP tools (17 collaboration-core + node/provider ops tools; authoritative list: docs-site/docs/api/mcp-tools.md).",
   "type": "module",
   "main": "src/index.ts",

package/src/api-host-supervisors-runtime-readiness.test.ts

@@ -0,0 +1,182 @@
+// #622 —— daemon 逐 runtime 自检(runtime_readiness)从 report_status 一路走到
+// /api/host-supervisors。三件事:
+//   1. report_status 的 zod 形状收得宽:坏的 runtime_readiness 只丢它自己,
+//      绝不拒掉整份 report(否则一台 daemon 发了个奇怪的诊断字段就在 hub 上失联);
+//   2. 新字段会被**保留**(daemon_capabilities 不是 strict,schema 里没声明的键会被
+//      静默剥掉 —— 不加 schema 就永远到不了 REST);
+//   3. REST 只在 daemon 报了时输出,旧 daemon 的行里**没有**这个键;
+//      can_create_nodes 语义不变。
+
+import { describe, expect, test, beforeAll, afterAll } from "bun:test";
+import "./require-explicit-test-db.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { register, login } from "./auth.js";
+import { db } from "./db.js";
+import { registerTools } from "./tools.js";
+import { sanitizeRuntimeReadiness } from "./runtime-readiness.js";
+
+function captureToolSchemas(): Record<string, any> {
+  const mcp = new McpServer({ name: "schema-probe", version: "0" }) as any;
+  const schemas: Record<string, any> = {};
+  const origTool = mcp.tool.bind(mcp);
+  mcp.tool = (name: string, desc: string, schema: any, handler: any) => {
+    schemas[name] = schema;
+    return origTool(name, desc, schema, handler);
+  };
+  registerTools(mcp, undefined, null, null, null, false, "tok_schema_probe");
+  return schemas;
+}
+const schemas = captureToolSchemas();
+const snapSchema = () => schemas.report_status.config_snapshot;
+const base = { flags: {}, config_update_capable: false, peer_reply_inbox_capable: true };
+
+const READY = {
+  ok: true, state: "ready", reason: "可以创建", version: "2.1.290",
+  checked_at: "2026-10-06T03:00:00.000Z", cli: "found", auth: "present", network: "reachable",
+};
+const MISSING = {
+  ok: false, state: "missing_cli", reason: "新节点的 PATH 上找不到可用的 grok 命令", checked_at: "2026-10-06T03:00:00.000Z",
+  cli: "missing", auth: "present", network: "skipped",
+};
+
+describe("#622 report_status schema —— runtime_readiness", () => {
+  test("合法值透传(没被 daemon_capabilities 的非 strict 剥掉)", () => {
+    const parsed = snapSchema().parse({ ...base, daemon_capabilities: {
+      can_create_nodes: true,
+      runtime_readiness: { "claude-code-cli": READY, "grok-build-acp": MISSING, "codex-sdk": { ...READY, shared_login_count: 27 } },
+    } });
+    expect(parsed.daemon_capabilities.runtime_readiness["claude-code-cli"].state).toBe("ready");
+    expect(parsed.daemon_capabilities.runtime_readiness["grok-build-acp"].state).toBe("missing_cli");
+    expect(parsed.daemon_capabilities.runtime_readiness["codex-sdk"].shared_login_count).toBe(27);
+    expect(parsed.daemon_capabilities.can_create_nodes).toBe(true);
+  });
+
+  test("🔴 坏形状绝不拒整份 report —— 只丢这一格", () => {
+    for (const bad of [
+      "string", 42, null, [], { x: "notobj" },
+      Object.fromEntries(Array.from({ length: 40 }, (_, i) => [`rt${i}`, READY])),
+    ]) {
+      const parsed = snapSchema().parse({ ...base, daemon_capabilities: { can_create_nodes: true, runtime_readiness: bad } });
+      expect(parsed.daemon_capabilities.can_create_nodes).toBe(true);
+      expect(parsed.daemon_capabilities.runtime_readiness).toBeUndefined();
+    }
+  });
+
+  test("单个字段坏:schema 不拒整份;读取侧消毒把它兜成 unknown", () => {
+    const parsed = snapSchema().parse({ ...base, daemon_capabilities: {
+      can_create_nodes: true,
+      runtime_readiness: { a: { ok: "yes", state: 7, reason: "x".repeat(5000), shared_login_count: -3 } },
+    } });
+    expect(parsed.daemon_capabilities.can_create_nodes).toBe(true);
+    const a = sanitizeRuntimeReadiness(parsed.daemon_capabilities.runtime_readiness)!.a;
+    expect(a.ok).toBe(false);
+    expect(a.state).toBe("unknown");
+    expect(a.reason.length).toBe(600);
+    expect(a.shared_login_count).toBeUndefined();
+  });
+
+  test("总字节超 16 KB:整格丢掉(异常 daemon 不能往库里塞大对象)", () => {
+    const big = { a: { ...READY, reason: "x".repeat(20_000) } };
+    const parsed = snapSchema().parse({ ...base, daemon_capabilities: { can_create_nodes: true, runtime_readiness: big } });
+    expect(parsed.daemon_capabilities.runtime_readiness).toBeUndefined();
+    expect(parsed.daemon_capabilities.can_create_nodes).toBe(true);
+  });
+});
+
+describe("#622 sanitizeRuntimeReadiness(读取侧)", () => {
+  test("不认识的 state → unknown;ok 只有 ready 时才可能为真", () => {
+    const s = sanitizeRuntimeReadiness({
+      a: { ok: true, state: "something_new", reason: "r" },
+      b: { ok: true, state: "no_network", reason: "r" },
+    })!;
+    expect(s.a.state).toBe("unknown");
+    expect(s.a.ok).toBe(false);
+    expect(s.b.ok).toBe(false);
+  });
+  test("没报 / 空 → undefined(调用方据此不输出键)", () => {
+    expect(sanitizeRuntimeReadiness(undefined)).toBeUndefined();
+    expect(sanitizeRuntimeReadiness({})).toBeUndefined();
+    expect(sanitizeRuntimeReadiness([])).toBeUndefined();
+  });
+  test("未知枚举值的 cli/auth/network 被丢掉", () => {
+    const s = sanitizeRuntimeReadiness({ a: { ...READY, cli: "/home/x/bin/claude", network: "maybe" } })!;
+    expect(s.a.cli).toBeUndefined();
+    expect(s.a.network).toBeUndefined();
+    expect(s.a.auth).toBe("present");
+  });
+});
+
+let BASE = "";
+let server: any = null;
+let userToken = "";
+let userNetworkId = "";
+let userId = "";
+
+beforeAll(async () => {
+  process.env.HOST = "127.0.0.1";
+  const suffix = `${Date.now()}_${Math.floor(Math.random() * 1000)}`;
+  const password = "BootstrapPw123Aa!";
+  const seed = register(`rr_seed_${suffix}`, password, undefined, "seed");
+  if (!seed.ok) throw new Error("seed failed");
+  db.run("UPDATE users SET role = 'admin' WHERE username = ?1", [`rr_seed_${suffix}`]);
+  const u = register(`rr_u_${suffix}`, password, undefined, "seed");
+  if (!u.ok || !u.token) throw new Error("user register failed");
+  userToken = u.token;
+  userNetworkId = u.network_id ?? "";
+  userId = login(`rr_u_${suffix}`, password).user!.user_id;
+  const { bootServer } = await import("./server.js");
+  server = bootServer({ port: 0, hostname: "127.0.0.1" });
+  BASE = `http://127.0.0.1:${server.port}`;
+  await new Promise((r) => setTimeout(r, 100));
+});
+
+afterAll(() => {
+  try { server?.stop?.(true); } catch {}
+});
+
+function seedDaemon(alias: string, snapshot: object): void {
+  db.run(
+    `INSERT OR REPLACE INTO nodes (
+       node_id, node_name, alias, runtime, model, config_path,
+       channels, server, hostname, network_id, config_revision, config_snapshot
+     ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12)`,
+    [`rr_n_${alias}`, alias, alias, "claude-agent-sdk", null, "/tmp/cfg.json", "[]", "test-host", "test-host",
+     userNetworkId, 0, JSON.stringify(snapshot)],
+  );
+  db.run(
+    `INSERT OR REPLACE INTO api_tokens (token_id, token_hash, user_id, network_id, name, scope)
+     VALUES (?1, ?2, ?3, ?4, ?5, ?6)`,
+    [`rr_t_${alias}`, `hash_rr_${alias}`, userId, userNetworkId, `node:${alias}`, "network"],
+  );
+}
+
+async function listDaemons(): Promise<any[]> {
+  const res = await fetch(`${BASE}/api/host-supervisors`, { headers: { Authorization: `Bearer ${userToken}` } });
+  const body = await res.json();
+  if (!body.ok) throw new Error("list failed: " + JSON.stringify(body));
+  return body.daemons;
+}
+
+describe("#622 /api/host-supervisors 输出 runtime_readiness", () => {
+  test("新 daemon:逐 runtime 透传;can_create_nodes 不受影响", async () => {
+    db.run("DELETE FROM nodes WHERE network_id = ?1", [userNetworkId]);
+    seedDaemon("rr-new", { role: "host_supervisor", daemon_capabilities: {
+      runtimes_supported: ["claude-code-cli", "grok-build-acp"],
+      can_create_nodes: true,
+      runtime_readiness: { "claude-code-cli": READY, "grok-build-acp": MISSING },
+    } });
+    const d = (await listDaemons()).find((x) => x.alias === "rr-new");
+    expect(d.can_create_nodes).toBe(true);
+    expect(d.runtime_readiness["claude-code-cli"]).toEqual(READY);
+    expect(d.runtime_readiness["grok-build-acp"].state).toBe("missing_cli");
+    expect(d.runtime_readiness["grok-build-acp"].ok).toBe(false);
+  });
+
+  test("🔴 旧 daemon(不报):响应里没有这个键 —— 不是 {}、不是 null", async () => {
+    db.run("DELETE FROM nodes WHERE network_id = ?1", [userNetworkId]);
+    seedDaemon("rr-old", { role: "host_supervisor", daemon_capabilities: { runtimes_supported: ["claude-agent-sdk"], can_create_nodes: true } });
+    const d = (await listDaemons()).find((x) => x.alias === "rr-old");
+    expect(d.can_create_nodes).toBe(true);
+    expect("runtime_readiness" in d).toBe(false);
+  });
+});

package/src/config-apply-validate.test.ts

@@ -249,6 +249,15 @@ describe("validatePatch — per-flag enum / range", () => {
     expect(validatePatch(undefined, { timeout: 3_600_001 })?.field).toBe("flags.timeout");
     expect(validatePatch(undefined, { timeout: 60.5 })?.field).toBe("flags.timeout");
   });
+  test("timeout: 0 = no limit; 1..999 is seconds-shaped and rejected (#605)", () => {
+    expect(validatePatch(undefined, { timeout: 0 })).toBeNull();
+    expect(validatePatch(undefined, { timeout: 1000 })).toBeNull();
+    for (const v of [1, 600, 999]) {
+      const r = validatePatch(undefined, { timeout: v });
+      expect(r?.field).toBe("flags.timeout");
+      expect(r?.reason).toContain("milliseconds");
+    }
+  });
 });
 
 describe("validatePatch — combinations", () => {

package/src/config-apply-validate.ts

@@ -5,6 +5,8 @@
 // tools.ts wrap these with auth checks (SEC-1 network scope, ntok_/utok_
 // caller identity, role gates).
 
+import { isValidTimeoutMs, TIMEOUT_MS_REASON } from "./create-node-validate.js";
+
 /**
  * Fields the dashboard may change. Anything not in this list is rejected
  * by hub-side validation regardless of role — the UI cannot smuggle
@@ -239,8 +241,10 @@ export function validatePatch(
         }
         break;
       case "timeout":
-        if (typeof val !== "number" || !Number.isInteger(val) || val < 0 || val > 3_600_000) {
-          return { field: "flags.timeout", reason: "must be an integer ms in [0, 3_600_000]" };
+        // #605 —— 与 create_node 同一把尺子(create-node-validate.ts isValidTimeoutMs):
+        // 毫秒,0 或 1000..3_600_000;1..999 是「按秒填了」的形状,拒绝而不是给一个亚秒超时。
+        if (!isValidTimeoutMs(val)) {
+          return { field: "flags.timeout", reason: TIMEOUT_MS_REASON };
         }
         break;
     }

package/src/create-node-validate.test.ts

@@ -3,7 +3,7 @@ import {
   ValidationError,
   validateName, validateRuntime, validateModel, validateFlagValue, RUNTIMES,
   validateEnvRefs, validateChannelsP1, serializeEnvLocal, buildAnetArgs,
-  MAX_ENV_KEYS_PER_NODE,
+  MAX_ENV_KEYS_PER_NODE, validateFlagsForRuntime, COPRESENCE_FLAG_RUNTIMES,
 } from "./create-node-validate.js";
 
 const okSecret = (k: string, _net: string, key: string) => k === key ? `value-of-${k}` : undefined;
@@ -69,6 +69,30 @@ describe("validateFlagValue (§4.2.2)", () => {
     expect(() => validateFlagValue("permissionMode", "plan")).not.toThrow();
     expect(() => validateFlagValue("permissionMode", "anything-else")).toThrow(ValidationError);
   });
+  // #605 —— agent-node 按毫秒读 flags.timeout(默认 300000)。这里曾收 1..86400(秒的形状):
+  // 600 原样到子节点 = 0.6 秒超时;600000(10 分钟)反被拒。现在与 update_node_config 同一把尺子。
+  test("timeout is milliseconds: 0 or 1000..3_600_000 (#605)", () => {
+    for (const v of [0, 1000, 300_000, 600_000, 3_600_000]) {
+      expect(() => validateFlagValue("timeout", v)).not.toThrow();
+    }
+    for (const v of [1, 600, 999, 86_400 * 1000 + 1, 3_600_001, -1, 1500.5, "600000", null]) {
+      expect(() => validateFlagValue("timeout", v)).toThrow(ValidationError);
+    }
+    try { validateFlagValue("timeout", 600); throw new Error("unreachable"); }
+    catch (e) {
+      expect(e).toBeInstanceOf(ValidationError);
+      expect((e as ValidationError).code).toBe("flag_value_invalid");
+      expect(String((e as ValidationError).detail?.reason)).toContain("milliseconds");
+    }
+  });
+  test("timeout range matches update_node_config's (#605)", async () => {
+    const { validatePatch } = await import("./config-apply-validate.js");
+    for (const v of [0, 1, 600, 999, 1000, 600_000, 3_600_000, 3_600_001, -1, 1.5]) {
+      let createOk = true;
+      try { validateFlagValue("timeout", v); } catch { createOk = false; }
+      expect({ v, ok: createOk }).toEqual({ v, ok: validatePatch(undefined, { timeout: v }) === null });
+    }
+  });
 });
 
 describe("validateEnvRefs (§4.4.7 + B1 G7/G8 sub-cases)", () => {
@@ -273,3 +297,38 @@ describe("#1298 RUNTIMES —— 七个都放行，且与 CLI 侧一致", () => {
     expect(() => validateRuntime("")).toThrow();
   });
 });
+
+// #584 —— app「Codex（TUI 共存）」经 daemon 建出来的是无头节点:create_node 没有任何字段能表达「要共存」。
+describe("#584 flags.copresence —— 建节点时的共存开关", () => {
+  test("is a known flag key and must be boolean", () => {
+    expect(() => validateFlagValue("copresence", true)).not.toThrow();
+    expect(() => validateFlagValue("copresence", false)).not.toThrow();
+    for (const bad of ["true", 1, null, {}]) {
+      try { validateFlagValue("copresence", bad); throw new Error("did not throw"); }
+      catch (e) { expect((e as ValidationError).code).toBe("flag_value_invalid"); }
+    }
+  });
+  test("only codex-app-server accepts it — elsewhere it would be swallowed silently", () => {
+    expect(() => validateFlagsForRuntime("codex-app-server", { copresence: true })).not.toThrow();
+    expect(() => validateFlagsForRuntime("claude-agent-sdk", { permissionMode: "default" })).not.toThrow();
+    expect(() => validateFlagsForRuntime("claude-agent-sdk", undefined)).not.toThrow();
+    for (const rt of ["claude-agent-sdk", "claude-code-cli", "codex-sdk", "grok-build-acp", "grok-build-cli", "opencode-cli"]) {
+      try { validateFlagsForRuntime(rt, { copresence: true }); throw new Error(`did not throw for ${rt}`); }
+      catch (e) {
+        expect((e as ValidationError).code).toBe("flag_not_applicable_to_runtime");
+        expect((e as ValidationError).detail).toMatchObject({ field: "copresence", runtime: rt, applicable: [...COPRESENCE_FLAG_RUNTIMES] });
+      }
+    }
+  });
+  test("buildAnetArgs emits the CLI's boolean `--copresence` (no value), and nothing for false", () => {
+    expect(buildAnetArgs({ name: "cx", runtime: "codex-app-server", flags: { copresence: true } }))
+      .toEqual(["node", "create", "cx", "--runtime", "codex-app-server", "--copresence"]);
+    expect(buildAnetArgs({ name: "cx", runtime: "codex-app-server", flags: { copresence: false } }))
+      .toEqual(["node", "create", "cx", "--runtime", "codex-app-server"]);
+    expect(() => buildAnetArgs({ name: "cx", runtime: "codex-sdk", flags: { copresence: true } })).toThrow(ValidationError);
+  });
+  test("the old request shape (no flag) is unchanged", () => {
+    expect(buildAnetArgs({ name: "cx", runtime: "codex-app-server", flags: { permissionMode: "default" } }))
+      .toEqual(["node", "create", "cx", "--runtime", "codex-app-server", "--permission-mode", "default"]);
+  });
+});

package/src/create-node-validate.ts

@@ -46,7 +46,16 @@ export const RUNTIMES = [
 ] as const;
 export type Runtime = typeof RUNTIMES[number];
 
-export const FLAG_KEYS = ["permissionMode", "dangerouslySkipPermissions", "maxTurns", "budget", "timeout"] as const;
+// #584 —— `copresence` 是**建节点时**的开关,不是 agent 的运行参数:为 true 时 daemon 把它写成子节点
+// config 的 `codexCopresence: true`,之后一条 `anet node start` 就起共享 TUI(app 向导的「Codex（TUI 共存）」)。
+// 🔴 故意放在 flags 里而不是 node_spec 顶层:老 hub 的 zod 会静默丢弃未知顶层字段、老 daemon 也静默忽略
+//    —— 那正是 #584 的形状(用户选了共存,拿到无头节点,没有任何报错)。flags 的未知键在老 hub(这份
+//    FLAG_KEYS)和老 daemon(buildAnetArgsDaemon)都**拒绝**,新 app 撞到老组件得到的是一条报错。
+export const FLAG_KEYS = ["permissionMode", "dangerouslySkipPermissions", "maxTurns", "budget", "timeout", "copresence"] as const;
+
+/** #584 —— 只有这些 runtime 认 `flags.copresence`。目前只有 codex-app-server 的共存靠 config 字段
+ *  (`codexCopresence`)决定;grok-build-cli / opencode-cli 各有自己的字段,接进来之前一律拒,不静默吞。 */
+export const COPRESENCE_FLAG_RUNTIMES = ["codex-app-server"] as const;
 export type FlagKey = typeof FLAG_KEYS[number];
 
 export const PERMISSION_MODES = ["default", "acceptEdits", "plan", "bypassPermissions"] as const;
@@ -99,6 +108,23 @@ export function validateModel(s: unknown): asserts s is string | undefined | nul
   }
 }
 
+/**
+ * #605 —— `flags.timeout` 的单位是**毫秒**:agent-node 就是这么读的(cli.ts currentClaudeTimeoutMs /
+ * currentCodexTimeoutMs → util/timeout.ts resolveTimeoutMs、runtime/opencode-timeout.ts,默认 300000)。
+ * 这里曾按「秒」收 1..86400:填 600 想要 10 分钟的人拿到 0.6 秒、每个任务都超时;真正的毫秒值被拒。
+ *
+ * 范围与 update_node_config(config-apply-validate.ts)/ agent-node config-apply 同一把尺子:
+ * 0(不设上限)或 TIMEOUT_MS_MIN..TIMEOUT_MS_MAX。1..999 拒绝 —— 旧客户端按秒发的小值分辨不出意图,
+ * 不偷偷乘 1000,但也不再让任何人悄悄拿到一个亚秒超时。
+ */
+export const TIMEOUT_MS_MIN = 1000;
+export const TIMEOUT_MS_MAX = 3_600_000;
+export const TIMEOUT_MS_REASON =
+  `timeout is in milliseconds: 0 (no limit) or an integer ${TIMEOUT_MS_MIN}..${TIMEOUT_MS_MAX} (e.g. 600000 = 10 min)`;
+export function isValidTimeoutMs(v: unknown): v is number {
+  return typeof v === "number" && Number.isInteger(v) && (v === 0 || (v >= TIMEOUT_MS_MIN && v <= TIMEOUT_MS_MAX));
+}
+
 export function validateFlagValue(k: string, v: unknown): void {
   switch (k) {
     case "permissionMode":
@@ -120,15 +146,29 @@ export function validateFlagValue(k: string, v: unknown): void {
       }
       return;
     case "timeout":
-      if (!Number.isInteger(v) || (v as number) < 1 || (v as number) > 86400) {
-        throw new ValidationError("flag_value_invalid", { field: k, reason: "must be integer 1..86400" });
+      if (!isValidTimeoutMs(v)) {
+        throw new ValidationError("flag_value_invalid", { field: k, reason: TIMEOUT_MS_REASON });
       }
       return;
+    case "copresence":
+      if (typeof v !== "boolean") throw new ValidationError("flag_value_invalid", { field: k, reason: "must be boolean" });
+      return;
     default:
       throw new ValidationError("flag_key_unknown", { field: k });
   }
 }
 
+/** #584 —— 逐键校验之外的跨字段一条:`copresence` 只对 COPRESENCE_FLAG_RUNTIMES 有意义。
+ *  在别的 runtime 上收下它而什么都不做,就是又一个「选了共存、拿到无头」。 */
+export function validateFlagsForRuntime(runtime: string, flags: Record<string, unknown> | undefined | null): void {
+  if (!flags || !Object.prototype.hasOwnProperty.call(flags, "copresence")) return;
+  if (!(COPRESENCE_FLAG_RUNTIMES as readonly string[]).includes(runtime)) {
+    throw new ValidationError("flag_not_applicable_to_runtime", {
+      field: "copresence", runtime, applicable: [...COPRESENCE_FLAG_RUNTIMES],
+    });
+  }
+}
+
 // §4.4.7 — env_refs 7-step gate. networkSecretsGet is injected so
 // callers can supply either a real DB lookup (hub) or a fixture (tests).
 // The 6th step also reports the resolved value size; we return the
@@ -281,8 +321,11 @@ export function buildAnetArgs(spec: NodeSpec): string[] {
         throw new ValidationError("flag_key_unknown", { field: k });
       }
       validateFlagValue(k, v);
+      // `anet node create --copresence` 是布尔开关,不吃值。
+      if (k === "copresence") { if (v === true) args.push("--copresence"); continue; }
       args.push(`--${kebab(k)}`, String(v));
     }
+    validateFlagsForRuntime(spec.runtime, spec.flags);
   }
   return args;
 }

package/src/db.ts

@@ -2104,3 +2104,23 @@ export function logTaskEvent(taskId: string, fromStatus: string | null, toStatus
 if (db.dialect === "postgres") {
   for (const table of ["nodes", "user_inbox"]) db.exec(`ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS rowid BIGSERIAL`);
 }
+
+// Board #625: common SQLite/PostgreSQL DDL. Adoption records authority, not processes.
+db.exec(`
+  CREATE TABLE IF NOT EXISTS node_daemon_bindings (
+    request_id TEXT PRIMARY KEY,
+    network_id TEXT NOT NULL,
+    node_id TEXT NOT NULL,
+    daemon_node_id TEXT NOT NULL,
+    workdir TEXT NOT NULL,
+    requested_by TEXT NOT NULL,
+    status TEXT NOT NULL CHECK (status IN ('pending','active','refused','revoked')),
+    error TEXT,
+    created_at BIGINT NOT NULL,
+    updated_at BIGINT NOT NULL
+  );
+  CREATE UNIQUE INDEX IF NOT EXISTS idx_ndb_live_node
+    ON node_daemon_bindings(node_id) WHERE status IN ('pending','active');
+  CREATE INDEX IF NOT EXISTS idx_ndb_daemon_network
+    ON node_daemon_bindings(daemon_node_id,network_id,status);
+`);

package/src/mcp-context-cost-http.test.ts

@@ -25,7 +25,8 @@ if (!activeDbPath) throw new Error("mcp-context-cost requires COMMHUB_DB (or COM
  * 上限跟着收到用户这一档(~1.7 KB 余量);节点 / 全部工具的上限在 tool-audience-http.test.ts。
  * 加工具或加说明超过它,就在这里改数字并在 PR 里说为什么。
  */
-const TOOLS_LIST_MAX_BYTES = 56_500;
+// Board #625: two human adoption tools; measured 58 tools / 56,615 B.
+const TOOLS_LIST_MAX_BYTES = 57_500;
 /** 单个工具(名字 + 描述 + 输入 schema)的上限;最大的是 report_status(节点心跳,~8.4 KB 的遥测结构)。 */
 const TOOL_MAX_BYTES = 9_000;
 /** 单条工具描述的上限(说明写进参数的 describe,或者拆短)。 */

package/src/node-daemon-bindings.test.ts

@@ -0,0 +1,132 @@
+import { beforeEach, afterAll, expect, test } from "bun:test";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { db } from "./db.js";
+import { registerTools } from "./tools.js";
+import { buildControllableMap } from "./node-lifecycle-controllable.js";
+
+const NET = "net_adoption_test", USER = "u_adoption_test", CHILD = "n_adoption_child", DAEMON = "node_adoption_daemon";
+function cleanup() {
+  for (const table of ["node_daemon_bindings", "node_stop_requests", "node_start_requests", "node_create_requests", "audit_log", "sessions", "nodes", "api_tokens", "network_members", "networks"])
+    db.run(`DELETE FROM ${table} WHERE network_id=?1`, [NET]);
+  db.run("DELETE FROM users WHERE user_id=?1", [USER]);
+}
+beforeEach(() => {
+  cleanup();
+  db.run("INSERT INTO users(user_id,username,password_hash,role) VALUES(?1,?1,'x','user')", [USER]);
+  db.run("INSERT INTO networks(network_id,network_name,owner_id) VALUES(?1,?1,?2)", [NET, USER]);
+  db.run("INSERT INTO network_members(user_id,network_id,role) VALUES(?1,?2,'owner')", [USER, NET]);
+  for (const [id, alias, snap] of [[DAEMON, "adoption-daemon", { role: "host_supervisor", daemon_capabilities: { adopt_capable: true } }], [CHILD, "adoption-child", {}]] as const) {
+    db.run(`INSERT INTO nodes(node_id,node_name,alias,network_id,owner_user_id,hostname,config_snapshot,lifecycle_state) VALUES(?1,?2,?2,?3,?4,'test-host',?5,'active')`, [id, alias, NET, USER, JSON.stringify(snap)]);
+  }
+  db.run("INSERT INTO sessions(resume_id,session_id,alias,network_id,status,last_seen_at) VALUES('adoption-session','adoption-session','adoption-daemon',?1,'idle',datetime('now'))", [NET]);
+  db.run("INSERT INTO api_tokens(token_id,user_id,network_id,scope,name,token_hash) VALUES('adoption-token',?1,?2,'network','node:adoption-daemon','adoption-hash')", [USER, NET]);
+});
+afterAll(cleanup);
+function handlers(kind: "user" | "daemon" | "stranger" = "user") {
+  const server = new McpServer({ name: "adoption-test", version: "0" }) as any;
+  const out: any = {}, original = server.tool.bind(server);
+  server.tool = (name: string, desc: string, schema: any, handler: any) => { out[name] = handler; return original(name, desc, schema, handler); };
+  registerTools(server, undefined, kind === "daemon" ? NET : null, kind === "user" ? USER : null, null, kind === "daemon", kind === "daemon" ? "adoption-token" : null);
+  return out;
+}
+const call = async (handler: any, args: any = {}) => JSON.parse((await handler(args)).content[0].text);
+const request = () => call(handlers().request_adopt_node, { node_id: CHILD, daemon_node_id: DAEMON, workdir: "/workspace/project" });
+async function adopt() {
+  const r = await request(); expect(r.ok).toBe(true);
+  expect(await call(handlers("daemon").ack_adopt_request, { request_id: r.request_id, status: "adopted" })).toMatchObject({ ok: true, status: "active" });
+  return r.request_id;
+}
+
+test("unbound node_ cannot use an explicitly supplied daemon (witnessed red on main)", async () => {
+  db.run("UPDATE nodes SET node_id='node_unbound_child' WHERE node_id=?1", [CHILD]);
+  expect(await call(handlers().stop_node, { child_node_id: "node_unbound_child", daemon_node_id: DAEMON, network_id: NET })).toMatchObject({ ok: false, error: "daemon_not_resolvable" });
+  expect(db.all("SELECT * FROM node_stop_requests WHERE network_id=?1", NET)).toHaveLength(0);
+});
+test("two-phase binding, daemon-bound pull, controllable map, adopted delete refused", async () => {
+  const r = await request(); expect(r.ok).toBe(true);
+  expect(await call(handlers().stop_node, { child_node_id: CHILD, daemon_node_id: DAEMON, network_id: NET })).toMatchObject({ ok: false });
+  expect(await call(handlers("daemon").get_adopt_request, { request_id: r.request_id })).toMatchObject({ ok: true, node_id: CHILD, alias: "adoption-child", workdir: "/workspace/project" });
+  expect(await call(handlers().get_adopt_request, { request_id: r.request_id })).toMatchObject({ ok: false });
+  expect(await call(handlers("daemon").ack_adopt_request, { request_id: r.request_id, status: "adopted" })).toMatchObject({ ok: true });
+  expect((await call(handlers("daemon").list_my_children)).children).toContainEqual({ child_node_id: CHILD, alias: "adoption-child", lifecycle_state: "active", managed: "adopted" });
+  expect(buildControllableMap([], [{ node_id: CHILD, daemon_node_id: DAEMON }]).get(CHILD)).toBe(DAEMON);
+  expect(await call(handlers().delete_node, { child_node_id: CHILD, confirm_alias: "adoption-child", network_id: NET })).toMatchObject({ ok: false, error: "adopted_node_delete_unsupported" });
+  expect(db.get<any>("SELECT lifecycle_state FROM nodes WHERE node_id=?1", CHILD).lifecycle_state).toBe("active");
+});
+test("adopted stop/start complete through existing protocol; revocation removes authority", async () => {
+  await adopt(); const u = handlers(), d = handlers("daemon");
+  const stop = await call(u.stop_node, { child_node_id: CHILD, network_id: NET }); expect(stop.ok).toBe(true);
+  expect((await call(d.get_stop_request, { request_id: stop.request_id })).ok).toBe(true);
+  expect((await call(d.ack_stop_request, { request_id: stop.request_id, status: "stopped" })).ok).toBe(true);
+  expect((await call(d.list_my_children)).children[0].lifecycle_state).toBe("stopped");
+  const start = await call(u.start_node, { child_node_id: CHILD, network_id: NET }); expect(start.ok).toBe(true);
+  expect((await call(d.get_start_request, { request_id: start.request_id })).ok).toBe(true);
+  expect((await call(d.ack_start_request, { request_id: start.request_id, status: "started", child_pid: 4321 })).ok).toBe(true);
+  expect((await call(u.unadopt_node, { node_id: CHILD })).ok).toBe(true);
+  expect((await call(d.list_my_children)).children).toHaveLength(0);
+  expect((await call(u.stop_node, { child_node_id: CHILD, daemon_node_id: DAEMON, network_id: NET })).ok).toBe(false);
+});
+test("pending cancellation cannot be resurrected; duplicate pending refuses", async () => {
+  const r = await request(); expect(r.ok).toBe(true);
+  expect((await request()).error).toBe("node_already_managed");
+  expect((await call(handlers().unadopt_node, { node_id: CHILD })).ok).toBe(true);
+  expect((await call(handlers("daemon").ack_adopt_request, { request_id: r.request_id, status: "adopted" })).error).toBe("request_not_pending");
+});
+test("human-only and owner/admin fail closed; admin exception audited", async () => {
+  const args = { node_id: CHILD, daemon_node_id: DAEMON, workdir: "/workspace/project" };
+  expect((await call(handlers("daemon").request_adopt_node, args)).ok).toBe(false);
+  expect((await call(handlers("stranger").request_adopt_node, args)).ok).toBe(false);
+  db.run("UPDATE network_members SET role='member' WHERE network_id=?1", [NET]);
+  db.run("UPDATE nodes SET owner_user_id=NULL WHERE node_id=?1", [CHILD]);
+  expect((await request()).error).toBe("adopt_forbidden");
+  db.run("UPDATE network_members SET role='owner' WHERE network_id=?1", [NET]);
+  expect((await request()).ok).toBe(true);
+  expect(db.get("SELECT action FROM audit_log WHERE action='adopt_by_admin' AND network_id=?1", NET)).not.toBeNull();
+});
+test("viewer owner cannot request; membership loss before ack cannot activate", async () => {
+  db.run("UPDATE network_members SET role='viewer' WHERE network_id=?1", [NET]);
+  expect((await request()).error).toBe("adopt_forbidden");
+  db.run("UPDATE network_members SET role='owner' WHERE network_id=?1", [NET]);
+  const r = await request(); expect(r.ok).toBe(true);
+  db.run("DELETE FROM network_members WHERE network_id=?1", [NET]);
+  expect((await call(handlers("daemon").ack_adopt_request, { request_id: r.request_id, status: "adopted" })).error).toBe("adopt_forbidden");
+});
+test("wrong daemon cannot pull/ack; refusal releases reservation; in-flight unadopt is refused", async () => {
+  const r = await request(); expect(r.ok).toBe(true);
+  db.run("UPDATE node_daemon_bindings SET daemon_node_id='other-daemon' WHERE request_id=?1", [r.request_id]);
+  const d = handlers("daemon");
+  expect((await call(d.get_adopt_request, { request_id: r.request_id })).error).toBe("request_not_found");
+  expect((await call(d.ack_adopt_request, { request_id: r.request_id, status: "adopted" })).error).toBe("request_not_found");
+  db.run("UPDATE node_daemon_bindings SET daemon_node_id=?1 WHERE request_id=?2", [DAEMON, r.request_id]);
+  expect((await call(d.ack_adopt_request, { request_id: r.request_id, status: "refused", error: "adopt_roots_not_configured" })).status).toBe("refused");
+  await adopt();
+  expect((await call(handlers().stop_node, { child_node_id: CHILD, network_id: NET })).ok).toBe(true);
+  expect((await call(handlers().unadopt_node, { node_id: CHILD })).error).toBe("node_lifecycle_in_flight");
+});
+test("old daemon, hostname mismatch, stale heartbeat and cross-network daemon rejected", async () => {
+  db.run("UPDATE nodes SET config_snapshot='null' WHERE node_id=?1", [DAEMON]);
+  expect((await request()).error).toBe("daemon_not_adopt_capable");
+  db.run("UPDATE nodes SET config_snapshot='{}' WHERE node_id=?1", [DAEMON]);
+  expect((await request()).error).toBe("daemon_not_adopt_capable");
+  db.run("UPDATE nodes SET config_snapshot=?1,hostname='different' WHERE node_id=?2", [JSON.stringify({ role: "host_supervisor", daemon_capabilities: { adopt_capable: true } }), DAEMON]);
+  expect((await request()).error).toBe("hostname_mismatch");
+  db.run("UPDATE nodes SET hostname='test-host' WHERE node_id=?1", [DAEMON]);
+  db.run("UPDATE sessions SET last_seen_at='2000-01-01 00:00:00' WHERE network_id=?1", [NET]);
+  expect((await request()).error).toBe("daemon_offline");
+  expect((await call(handlers().request_adopt_node, { node_id: CHILD, daemon_node_id: "other_network_daemon", workdir: "/workspace/project" })).error).toBe("daemon_not_found");
+});
+test("network boundaries apply to both human request and daemon pull/ack", async () => {
+  const r = await request(); expect(r.ok).toBe(true);
+  db.run("UPDATE node_daemon_bindings SET network_id='net_other_adoption_test' WHERE request_id=?1", [r.request_id]);
+  try {
+    const d = handlers("daemon");
+    expect((await call(d.get_adopt_request, { request_id: r.request_id })).error).toBe("request_not_found");
+    expect((await call(d.ack_adopt_request, { request_id: r.request_id, status: "adopted" })).error).toBe("request_not_found");
+  } finally { db.run("UPDATE node_daemon_bindings SET network_id=?1 WHERE request_id=?2", [NET, r.request_id]); }
+  db.run("UPDATE nodes SET network_id='net_other_adoption_test' WHERE node_id=?1", [DAEMON]);
+  try { expect((await request()).error).toBe("daemon_not_found"); }
+  finally { db.run("UPDATE nodes SET network_id=?1 WHERE node_id=?2", [NET, DAEMON]); }
+  db.run("UPDATE nodes SET network_id='net_other_adoption_test' WHERE node_id=?1", [CHILD]);
+  try { expect((await request()).error).toBe("adopt_forbidden"); }
+  finally { db.run("UPDATE nodes SET network_id=?1 WHERE node_id=?2", [NET, CHILD]); }
+});