@sleep2agi/commhub-server 0.9.0-preview.120 → 0.9.0-preview.122

package/src/shared/codex-inventory.ts

@@ -0,0 +1,34 @@
+// #906 key-free existing Codex inventory. Identical public contract in each package.
+export function validCodexInventory(v: any): boolean {
+  const fields = (o: any, allowed: string[]) => o && typeof o === 'object' && !Array.isArray(o)
+    && Object.keys(o).every(k => allowed.includes(k));
+  const id = (s: any) => typeof s === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$/.test(s);
+  const nullable = (s: any) => s === null || id(s);
+  if (!fields(v, ['observed_at', 'scope', 'rows', 'installation']) || !Number.isSafeInteger(v.observed_at) || v.observed_at <= 0
+    || v.scope !== 'hub_bound_nodes' || !Array.isArray(v.rows) || v.rows.length > 200
+    || new Set(v.rows.map((r: any) => r?.node_id)).size !== v.rows.length) return false;
+  if (v.installation !== undefined && (!fields(v.installation, ['status', 'version'])
+    || !['found', 'missing', 'unknown'].includes(v.installation.status)
+    || !(v.installation.version === null || (typeof v.installation.version === 'string' && /^\d+\.\d+\.\d+(?:[-+.][0-9A-Za-z.-]+)?$/.test(v.installation.version) && v.installation.version.length <= 64)))) return false;
+  for (const r of v.rows) {
+    if (!r || !id(r.node_id) || typeof r.alias !== 'string' || !/^[\p{L}\p{N}][\p{L}\p{N}_.-]{0,99}$/u.test(r.alias)) return false;
+    if (['unavailable', 'not_codex'].includes(r.status)) {
+      if (!fields(r, ['node_id', 'alias', 'status'])) return false;
+      continue;
+    }
+    if (r.status !== 'observed' || !fields(r, ['node_id', 'alias', 'status', 'runtime', 'home_ref', 'home_source',
+      'config_status', 'configured_provider', 'configured_model', 'provider_ids', 'auth_kind', 'credential_status',
+      'account_fingerprint', 'verification', 'effective_state', 'node_configured_model', 'config_revision'])) return false;
+    if (r.config_revision !== undefined && r.config_revision !== null && (typeof r.config_revision !== 'string' || !/^[a-f0-9]{64}$/.test(r.config_revision))) return false;
+    if (!nullable(r.runtime) || !/^[a-f0-9]{16}$/.test(r.home_ref)
+      || !['host_default', 'config.codexHome', 'node-codex-home', 'config.env'].includes(r.home_source)
+      || !['read', 'missing', 'unreadable'].includes(r.config_status) || !nullable(r.configured_provider)
+      || !nullable(r.configured_model) || !nullable(r.node_configured_model)
+      || !Array.isArray(r.provider_ids) || r.provider_ids.length > 101 || !r.provider_ids.every(id)
+      || !['unknown', 'chatgpt', 'api_key'].includes(r.auth_kind)
+      || !['unknown', 'present', 'unreadable'].includes(r.credential_status)
+      || !(r.account_fingerprint === null || /^[a-f0-9]{16}$/.test(r.account_fingerprint))
+      || r.verification !== 'not_checked' || r.effective_state !== 'not_checked') return false;
+  }
+  return true;
+}

package/src/shared/daemon-provider-login.ts

@@ -0,0 +1,31 @@
+// #906 managed login transport: only explicit actions and secret-free projections.
+export type LoginIntent = { action: 'start' | 'read' | 'cancel' | 'save' | 'accounts'; session_id?: string; label?: string };
+const uuid = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
+const object = (v: any) => v && typeof v === 'object' && !Array.isArray(v);
+const keys = (v: any, names: string[]) => Object.keys(v).every(k => names.includes(k));
+export function validLoginIntent(v: any): v is LoginIntent {
+  return object(v) && keys(v, ['action','session_id','label'])
+    && ['start','read','cancel','save','accounts'].includes(v.action)
+    && (v.action === 'accounts' ? v.session_id === undefined : typeof v.session_id === 'string' && uuid.test(v.session_id))
+    && (v.action === 'save' ? typeof v.label === 'string' && !!v.label.trim() && v.label.length <= 100 && !/[\x00-\x1f\x7f]/.test(v.label) : v.label === undefined);
+}
+export function validLoginReceipt(v: any, intent: LoginIntent, network: string, daemon: string): boolean {
+  if (!object(v)) return false;
+  if (intent.action === 'accounts') return keys(v, ['accounts']) && Array.isArray(v.accounts) && v.accounts.length <= 100
+    && v.accounts.every((a: any) => object(a) && keys(a, ['version','network_id','daemon_node_id','account_id','label','created_at','auth_state'])
+      && a.version === 1 && a.network_id === network && a.daemon_node_id === daemon
+      && typeof a.account_id === 'string' && uuid.test(a.account_id)
+      && typeof a.label === 'string' && a.label.length <= 100
+      && Number.isSafeInteger(a.created_at) && a.auth_state === 'not_checked');
+  if (!keys(v, ['request_id','status','error','challenge','account_id']) || v.request_id !== intent.session_id
+    || !['idle','starting','awaiting_user','verifying','authenticated','cancelled','failed'].includes(v.status)) return false;
+  if (v.error !== undefined && !['login_start_failed','login_rejected','account_read_failed','login_process_exited','login_expired'].includes(v.error)) return false;
+  if (v.account_id !== undefined && (v.status !== 'authenticated' || typeof v.account_id !== 'string' || !uuid.test(v.account_id))) return false;
+  if (intent.action === 'cancel' && v.status !== 'cancelled') return false;
+  if (intent.action === 'save' && (v.status !== 'authenticated' || !v.account_id)) return false;
+  if (v.status === 'awaiting_user') return object(v.challenge) && keys(v.challenge, ['loginId','verificationUrl','userCode'])
+    && typeof v.challenge.loginId === 'string' && uuid.test(v.challenge.loginId)
+    && v.challenge.verificationUrl === 'https://auth.openai.com/codex/device'
+    && typeof v.challenge.userCode === 'string' && /^[A-Z0-9-]{4,32}$/i.test(v.challenge.userCode);
+  return v.challenge === undefined;
+}

package/src/shared/daemon-provider-snapshot.ts

@@ -0,0 +1,52 @@
+// #906 public Provider snapshot contract. Mirrored across separately published
+// server/agent-node packages; drift is tested. No secret-shaped extension fields.
+import { validCodexInventory } from './codex-inventory.js';
+export function validateDaemonProviderSnapshot(value: unknown, networkId: string, daemonId: string): unknown {
+  const fail = (): never => { throw new Error("invalid_provider_snapshot"); };
+  const obj = (v: any, fields: string[]) => {
+    if (!v || typeof v !== "object" || Array.isArray(v) || Object.keys(v).some(k => !fields.includes(k))) fail();
+    return v;
+  };
+  const id = (v: unknown) => typeof v === "string" && /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(v);
+  const unique = (xs: any[], key: string) => { if (new Set(xs.map(x => x[key])).size !== xs.length) fail(); };
+  const arr = (v: any, max: number, empty = false): any[] => {
+    if (!Array.isArray(v) || (!empty && !v.length) || v.length > max) fail();
+    return v;
+  };
+  const s = obj(value, ["network_id", "daemon_node_id", "revision", "source", "providers", "codex_inventory"]);
+  if (s.codex_inventory !== undefined && !validCodexInventory(s.codex_inventory)) fail();
+  if (s.network_id !== networkId || s.daemon_node_id !== daemonId || s.source !== "daemon"
+    || !Number.isSafeInteger(s.revision) || s.revision < 0) fail();
+  const providers = arr(s.providers, 100, true);
+  unique(providers, "id");
+  for (const p of providers) {
+    obj(p, ["id", "label", "enabled", "runtimes"]);
+    if (!id(p.id) || typeof p.label !== "string" || !p.label.trim() || p.label.length > 100
+      || /[\x00-\x1f\x7f]/.test(p.label) || typeof p.enabled !== "boolean") fail();
+    const runtimes = arr(p.runtimes, 8); unique(runtimes, "runtime");
+    for (const r of runtimes) {
+      obj(r, ["runtime", "auth"]); if (r.runtime !== "codex-tui") fail();
+      const auths = arr(r.auth, 32); unique(auths, "id");
+      for (const a of auths) {
+        obj(a, ["id", "kind", "models", "baseUrl", "account_id", "credential_present", "verification", "application"]);
+        if (!id(a.id) || a.verification !== "not_checked" || a.application !== "not_applied") fail();
+        const models = arr(a.models, 200);
+        if (new Set(models).size !== models.length || models.some(m => typeof m !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/.test(m))) fail();
+        if (a.kind === "chatgpt") {
+          if (p.id !== "openai" || a.baseUrl !== undefined || typeof a.credential_present !== 'boolean') fail();
+          if (a.account_id !== undefined && (typeof a.account_id !== 'string' || !/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(a.account_id))) fail();
+          if (a.credential_present && !a.account_id) fail();
+        } else if (a.kind === "api_key") {
+          if (a.account_id !== undefined) fail();
+          if (a.credential_present !== true || typeof a.baseUrl !== "string" || a.baseUrl.length > 2048) fail();
+          let u: URL; try { u = new URL(a.baseUrl); } catch { return fail(); }
+          if (u.protocol !== "https:" || u.username || u.password || u.search || u.hash) fail();
+        } else fail();
+      }
+    }
+  }
+  // JSON roundtrip detaches the validated object from mutable caller references.
+  const encoded = JSON.stringify(s);
+  if (new TextEncoder().encode(encoded).byteLength > 1024 * 1024) fail();
+  return JSON.parse(encoded);
+}

package/src/shared/provider-application.ts

@@ -0,0 +1,29 @@
+// #906 public application protocol. No paths, endpoints or credentials.
+export type ProviderApplicationSelection = {
+  node_id: string; node_revision: string; provider_id: string; auth_id: string;
+  model: string; confirm_restart: true;
+  account_id?: string;
+};
+const fields = (v: any, names: string[]) => v && typeof v === 'object' && !Array.isArray(v)
+  && Object.keys(v).length === names.length && Object.keys(v).every(k => names.includes(k));
+const id = (v: any) => typeof v === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$/.test(v);
+const hash = (v: any) => typeof v === 'string' && /^[a-f0-9]{64}$/.test(v);
+const account = (v: any) => typeof v === 'string' && /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i.test(v);
+export function validProviderApplicationSelection(v: any): v is ProviderApplicationSelection {
+  return fields(v, ['node_id', 'node_revision', 'provider_id', 'auth_id', 'model', 'confirm_restart',
+    ...(v?.account_id !== undefined ? ['account_id'] : [])])
+    && (v.account_id === undefined || (v.provider_id === 'openai' && account(v.account_id)))
+    && id(v.node_id) && hash(v.node_revision) && id(v.provider_id) && id(v.auth_id) && id(v.model)
+    && v.confirm_restart === true;
+}
+export function validProviderApplicationReceipt(v: any, requestId: string, revision: number,
+  selection: ProviderApplicationSelection): boolean {
+  return fields(v, ['status', 'request_id', 'node_id', 'provider_id', 'auth_id', 'model', 'runtime_provider',
+    'node_revision', 'provider_revision', 'verification', 'applied_at', ...(selection.account_id ? ['account_id'] : [])])
+    && v.status === 'applied' && v.request_id === requestId && v.node_id === selection.node_id
+    && v.provider_id === selection.provider_id && v.auth_id === selection.auth_id && v.model === selection.model
+    && (selection.account_id ? v.runtime_provider === 'openai' && v.account_id === selection.account_id
+      : typeof v.runtime_provider === 'string' && /^anet_[a-f0-9]{20}$/.test(v.runtime_provider))
+    && hash(v.node_revision) && v.provider_revision === revision && v.verification === 'runtime_confirmed'
+    && Number.isSafeInteger(v.applied_at) && v.applied_at > 0 && v.applied_at <= Date.now() + 30_000;
+}

package/src/tool-audience-http.test.ts

@@ -163,7 +163,7 @@ describe("what each caller sees", () => {
 
   test("node modes: readonly / restricted drop broadcast + node writes + human-only; enforce drops human-only for normal nodes", async () => {
     const ro = new Set((await listTools(T.node_readonly)).names);
-    for (const n of ["broadcast", "update_node_config", "create_node", "upsert_provider"]) expect([n, ro.has(n)]).toEqual([n, false]);
+    for (const n of ["broadcast", "update_node_config", "create_node", "clone_node", "upsert_provider"]) expect([n, ro.has(n)]).toEqual([n, false]);
     for (const n of ["send_task", "requirements_update", "report_status", "get_all_status"]) expect([n, ro.has(n)]).toEqual([n, true]); // 看参数才拒的照列
     expect(new Set((await listTools(T.node_normal)).names).has("upsert_provider")).toBe(true); // log 模式:调得通,照列
     process.env.COMMHUB_NODE_PERMISSIONS = "enforce";
@@ -197,7 +197,20 @@ describe("bytes per role (#476 ceilings stay meaningful per role)", () => {
   // user 58 / 56,950 B → 57,163 B (+213). start_node adds 213 B, report_status 169 B;
   // hidden pull/ack schemas account for the remaining 948 B. Keep strict receipt validation
   // and unchanged audiences; budget only this measured addition (~130/520 B node/all margin).
-  const CEILINGS = { node: 62_500, user: 57_500, all: 79_500 } as const;
+  // Board #654 adds report_status adoption_candidates (node-only schema, no new tool).
+  // Same tree, field removed → restored: all 87 / 79,078 B → 79,591 B (+513);
+  // node 61 / 62,433 B → 62,946 B (+513); user 58 / 57,228 B unchanged
+  // (report_status is not on the user list). Budget only this measured addition
+  // (~154/509 B node/all margin).
+  // #906 registers daemon_provider_snapshot (user) plus pull/ack (protocol).
+  // Measured there: all 90 / 80,307 B; node 61 / 62,556 B; user 59 / 57,372 B,
+  // ceilings 80,800 / 63,100 / 57,500.
+  // Hub #938 adds clone_node (audience both, so it lands on the node list and
+  // the user list) plus optional expect_clone on get_create_request (protocol,
+  // so only the full list). Measured on this combined tree:
+  // all 91 / 81,228 B; node 62 / 63,281 B; user 60 / 58,169 B.
+  // Ceilings keep about 400 B of margin and nothing else.
+  const CEILINGS = { node: 63_700, user: 58_600, all: 81_700 } as const;
   test("node / user / all", async () => {
     const node = await listTools(T.node_normal);
     const user = await listTools(T.owner);

package/src/tool-audience.ts

@@ -23,6 +23,8 @@ import { NODE_TOOL_CLASS, nodeIdentity, nodePermissionsFlag, broadcastVerdict, h
 export type ToolAudience = "both" | "node" | "protocol" | "user";
 
 export const TOOL_AUDIENCE: Readonly<Record<string, ToolAudience>> = {
+  daemon_provider_snapshot: "user",
+  pull_daemon_provider_snapshots: "protocol", ack_daemon_provider_snapshot: "protocol",
   request_adopt_node: "user", unadopt_node: "user",
   get_adopt_request: "protocol", ack_adopt_request: "protocol",
   // ── 节点:用户令牌一律 network_token_required ──
@@ -51,7 +53,7 @@ export const TOOL_AUDIENCE: Readonly<Record<string, ToolAudience>> = {
   send_desktop_message: "both", broadcast: "both", get_completions: "both",
   update_node_config: "both", read_node_rules_file: "both", write_node_rules_file: "both",
   list_node_skills: "both", read_node_skill: "both", get_rules_file_result: "both",
-  restart_node: "both", list_host_supervisors: "both", create_node: "both", stop_node: "both", delete_node: "both", start_node: "both",
+  restart_node: "both", list_host_supervisors: "both", create_node: "both", clone_node: "both", stop_node: "both", delete_node: "both", start_node: "both",
   upsert_network_secret: "both", list_network_secrets: "both", upsert_provider: "both", update_provider: "both",
   list_providers: "both", probe_provider_model: "both", get_probe_results: "both",
   requirements_list: "both", requirements_people: "both", requirements_get: "both", requirements_create: "both",

package/src/tools.ts

@@ -1,6 +1,8 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { requestProviderSnapshot, requestProviderWrite, requestProviderApplication, requestProviderLogin, getProviderSnapshot, pullProviderSnapshots, ackProviderSnapshot } from "./daemon-provider-snapshots.js";
 import { requestAdopt, getAdopt, ackAdopt, unadopt, resolveManagedDaemon, activeBinding, createdDaemon } from "./node-daemon-bindings.js";
 import { runtimeReadinessSchema } from "./runtime-readiness.js";
+import { adoptionCandidatesReportSchema } from "./adoption-candidates.js";
 import { forkRecoveryRequestSchema, forkRecoveryResultSchema, publicForkResult } from "./codex-fork-contract.js";
 import { lockNodeAlias } from "./node-token-ownership.js";
 import { clearNodeFromAgentTeams, agentTeamWhoami } from "./agent-teams.js";
@@ -39,6 +41,7 @@ import {
   FLAG_KEYS,
   validateFlagValue,
   validateFlagsForRuntime,
+  validateOpenCodeV2ProviderModel,
   ValidationError,
 } from "./create-node-validate.js";
 import {
@@ -52,6 +55,7 @@ import {
   auditCreateNodeStrict,
   resolveCallerDaemonTokenBound as _resolveCallerDaemonTokenBound,
 } from "./create-node.js";
+import { decideClone, factsFromRows, parseWorkdirPolicy } from "./clone-node.js";
 import {
   vaultUpsert, vaultGet, vaultListKeys, vaultDelete,
   VaultError,
@@ -843,6 +847,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         daemon_capabilities: z.object({
           codex_fork_recovery: z.object({ protocol: z.literal(1), cli_supported: z.boolean() }).optional().catch(undefined),
           adopt_capable: z.boolean().optional(),
+          adoption_candidates: adoptionCandidatesReportSchema,
           runtimes_supported: z.array(z.string().max(64)).max(16).optional(),
           allowed_secret_keys: z.array(z.string().max(64)).max(64).optional(),
           max_concurrent_children: z.number().int().min(1).max(1000).optional(),
@@ -3196,7 +3201,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     callerNetworkId: string | null,
   ): { row: any | null; sec1Ok: boolean } => {
     const row = db.get<any>(
-      "SELECT node_id, alias, network_id, config_revision, config_snapshot FROM nodes WHERE node_id = ?1",
+      "SELECT node_id, alias, network_id, runtime, config_revision, config_snapshot FROM nodes WHERE node_id = ?1",
       nodeId,
     );
     if (!row) return { row: null, sec1Ok: false };
@@ -3326,7 +3331,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         };
       }
 
-      const validationFail = validatePatch(model, flags, channels);
+      const validationFail = validatePatch(model, flags, channels, node.runtime);
       if (validationFail) {
         return {
           content: [{
@@ -4113,6 +4118,35 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   const resolveCallerDaemonTokenBound = () =>
     _resolveCallerDaemonTokenBound({ callerTokenIsNetwork, callerTokenId, enforceNetworkId });
 
+  const providerHuman = (net?: string) => ({ userId: enforceUserId, isNode: callerTokenIsNetwork, networkId: getNetworkId(net) });
+  const providerReply = (value: unknown) => ({ content: [{ type: "text" as const, text: JSON.stringify(value) }] });
+  server.tool(
+    "daemon_provider_snapshot", "Admin Provider: refresh/put/apply/login use daemon id; read uses request id. put: revision+provider; apply: revision+node selection; login: provider={action:start|read|cancel|save|accounts,session_id?,label?}. No login tokens.",
+    { action: z.enum(["refresh", "read", "put", "apply", "login"]), id: z.string().min(1).max(200), network_id: z.string().max(200).optional(), revision: z.number().int().min(0).optional(), provider: z.unknown().optional() },
+    async ({ action, id, network_id, revision, provider }) => {
+      const human = providerHuman(network_id);
+      if (action === "read") return providerReply(getProviderSnapshot(human, id));
+      const daemon_node_id = id;
+      const result = action === 'login' ? requestProviderLogin(human, daemon_node_id, provider)
+        : action === 'apply' ? requestProviderApplication(human, daemon_node_id, revision!, provider)
+        : action === 'put' ? requestProviderWrite(human, daemon_node_id, revision!, provider) : requestProviderSnapshot(human, daemon_node_id);
+      if (result.ok) {
+        const target = db.get<{ alias: string }>("SELECT alias FROM nodes WHERE node_id=?1 AND network_id=?2", daemon_node_id, human.networkId!);
+        if (target) pushEvent(target.alias, { type: "daemon_provider_snapshot", request_id: result.request_id }, human.networkId!);
+      }
+      return providerReply(result);
+    },
+  );
+  server.tool(
+    "pull_daemon_provider_snapshots", "Daemon Provider work; advertise only implemented secure write/apply/login capabilities.", { accept_writes: z.boolean().optional(), accept_applications: z.boolean().optional(), accept_logins: z.boolean().optional() },
+    async ({ accept_writes, accept_applications, accept_logins }) => providerReply(pullProviderSnapshots(resolveCallerDaemonTokenBound(), accept_writes, accept_applications, accept_logins)),
+  );
+  server.tool(
+    "ack_daemon_provider_snapshot", "Target daemon acknowledges redacted Provider configuration readback; fixed failure code only.",
+    { request_id: z.string().min(1).max(200), snapshot: z.unknown().optional(), failed: z.boolean().optional(), applied_revision: z.number().int().min(0).optional(), application: z.unknown().optional(), login: z.unknown().optional() },
+    async ({ request_id, snapshot, failed, applied_revision, application, login }) => providerReply(ackProviderSnapshot(resolveCallerDaemonTokenBound(), request_id, snapshot, failed, applied_revision, application, login)),
+  );
+
   // Helper — map a ValidationError thrown from create-node-validate
   // into the MCP-tool-call JSON reply shape.
   const validationFailReply = (e: unknown) => {
@@ -4132,7 +4166,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   // join on api_tokens.revoked_at.
   server.tool(
     "list_host_supervisors",
-    "List host_supervisor daemon nodes in the caller's network (online status + runtimes_supported + allowed_secret_keys + telemetry; member-脱敏). RFC-026 §9.2.1.",
+    "List network daemons: status, runtimes, secret-key allowlist and telemetry (member-redacted).",
     {
       network_id: z.string().max(200).optional(),
     },
@@ -4268,7 +4302,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   // row (metadata only — no env_blob in SQL), pushEvent doorbell.
   server.tool(
     "create_node",
-    "Create a node on a host-daemon and start it. Daemon forks `anet node create + start` on the target machine; child reports back to hub. RFC-026.",
+    "Create/start a node on the target daemon; the child reports back to Hub.",
     {
       daemon_node_id: z.string().min(1).max(200),
       node_spec: z.object({
@@ -4438,6 +4472,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
           validateFlagValue(k, v);
         }
         validateFlagsForRuntime(node_spec.runtime, node_spec.flags);
+        validateOpenCodeV2ProviderModel(node_spec.runtime, node_spec.model, node_spec.flags);
       } catch (e) {
         return validationFailReply(e);
       }
@@ -4577,12 +4612,162 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     },
   );
 
+  // Hub #938 — clone a child that already lives on a daemon into a new
+  // node on THAT daemon. New alias, new ntok_. Session copy is done by
+  // the daemon from the source config on disk; this tool only records
+  // the policy and the runtime's session capability (see clone-node.ts).
+  server.tool(
+    "clone_node",
+    "Clone a daemon child into a new node on the same daemon. New name and new token. copy_session defaults to true. workdir_policy new_empty (default) or share_source. Hub #938.",
+    {
+      source_node_id: z.string().min(1).max(200),
+      name: z.string().min(1).max(256),
+      copy_session: z.boolean().optional(),
+      workdir_policy: z.enum(["new_empty", "share_source"]).optional(),
+      daemon_node_id: z.string().min(1).max(200).optional(),
+      network_id: z.string().max(200).optional(),
+    },
+    async ({ source_node_id, name, copy_session, workdir_policy, daemon_node_id, network_id: clientNetId }) => {
+      const effectiveNetId = getNetworkId(clientNetId);
+      if (!canWrite(effectiveNetId)) return writeDeniedReply(effectiveNetId, "write");
+      const callerRole = enforceUserId && effectiveNetId
+        ? getUserNetworkRole(enforceUserId, effectiveNetId)
+        : null;
+      if (callerRole !== "admin" && callerRole !== "owner") {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "insufficient_role_for_create_node", required_role: "admin", caller_role: callerRole }) }] };
+      }
+      const { row: source, sec1Ok } = resolveTargetNode(source_node_id, effectiveNetId);
+      if (!source) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "node_not_found", node_id: source_node_id }) }] };
+      }
+      if (!sec1Ok) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "cross_network_node" }) }] };
+      }
+      const createRow = db.get<{ daemon_node_id: string; runtime: string; model: string | null; flags_json: string; child_name: string }>(
+        `SELECT daemon_node_id, runtime, model, flags_json, child_name
+           FROM node_create_requests
+          WHERE child_node_id = ?1 AND network_id = ?2 AND status = 'succeeded'
+          ORDER BY created_at DESC LIMIT 1`,
+        source_node_id, source.network_id || effectiveNetId || "default",
+      );
+      const net = source.network_id || effectiveNetId || "default";
+      const nameRows = db.all<{ alias: string | null; node_name: string | null }>(
+        `SELECT alias, node_name FROM nodes WHERE network_id = ?1`,
+        net,
+      );
+      const existingNames = nameRows.flatMap((r) => [r.alias, r.node_name].filter((x): x is string => !!x));
+      const owning = createRow?.daemon_node_id ?? "";
+      const inflight = owning
+        ? db.all<{ child_name: string }>(
+          `SELECT child_name FROM node_create_requests WHERE daemon_node_id = ?1 AND status IN ('pending', 'delivered')`,
+          owning,
+        ).map((r) => r.child_name)
+        : [];
+      let policy: ReturnType<typeof parseWorkdirPolicy>;
+      try { policy = parseWorkdirPolicy(workdir_policy); }
+      catch (e) { return validationFailReply(e); }
+      const facts = factsFromRows({
+        node: source,
+        createRow: createRow ?? null,
+        existingNames,
+        inflightNames: inflight,
+      });
+      let decision;
+      try {
+        decision = decideClone(facts, {
+          newName: name,
+          copySession: copy_session !== false,
+          workdirPolicy: policy,
+          requestedDaemonId: daemon_node_id ?? null,
+        });
+      } catch (e) {
+        return validationFailReply(e);
+      }
+      if (!decision.ok) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: decision.error, ...decision.detail }) }] };
+      }
+      const { row: daemon, sec1Ok: daemonOk } = resolveTargetNode(decision.daemonNodeId, effectiveNetId);
+      if (!daemon || !daemonOk) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "daemon_not_found", daemon_node_id: decision.daemonNodeId }) }] };
+      }
+      if (!enforceUserId) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "auth_required" }) }] };
+      }
+      const childToken = generateNetworkToken();
+      const childTokenId = generateId("tok");
+      const requestId = newRequestId();
+      const networkIdForChild = daemon.network_id || net;
+      const cloneMeta = {
+        source_node_id,
+        source_alias: facts.alias,
+        copy_session: decision.copySession,
+        workdir_policy: decision.workdirPolicy,
+        channels: decision.channels,
+      };
+      db.run(
+        `INSERT INTO api_tokens (token_id, token_hash, user_id, network_id, name, scope, role, request_id, node_identity_epoch) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, 2)`,
+        [childTokenId, hashToken(childToken), enforceUserId, networkIdForChild, `node:${decision.name}`, "network", "child", requestId],
+      );
+      putPendingEnvBlob({
+        request_id: requestId,
+        daemon_node_id: decision.daemonNodeId,
+        env_blob: {},
+        child_token: childToken,
+        child_token_id: childTokenId,
+      });
+      db.run(
+        `INSERT INTO node_create_requests
+           (request_id, daemon_node_id, child_name, network_id, runtime, model, flags_json, env_keys, status, child_token_id, created_at, created_by_token, clone_json)
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, '[]', 'pending', ?8, ?9, ?10, ?11)`,
+        [
+          requestId, decision.daemonNodeId, decision.name, networkIdForChild,
+          decision.runtime, decision.model, JSON.stringify(decision.flags),
+          childTokenId, Date.now(), callerTokenId || "unknown", JSON.stringify(cloneMeta),
+        ],
+      );
+      pushEvent(daemon.alias, { type: "clone_node", request_id: requestId }, networkIdForChild);
+      auditCreateNode({
+        action: "clone_node_dispatch_attempted",
+        user_id: enforceUserId,
+        network_id: networkIdForChild,
+        target_id: requestId,
+        detail: {
+          daemon_node_id: decision.daemonNodeId,
+          source_node_id,
+          child_name: decision.name,
+          runtime: decision.runtime,
+          copy_session: decision.copySession,
+          workdir_policy: decision.workdirPolicy,
+          session_mode: decision.sessionContract.mode,
+        },
+      });
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({
+          ok: true,
+          request_id: requestId,
+          daemon_node_id: decision.daemonNodeId,
+          child_name: decision.name,
+          copy_session: decision.copySession,
+          workdir_policy: decision.workdirPolicy,
+          session_contract: decision.sessionContract,
+          contract: {
+            token: "new ntok_ minted for the clone; the source token is not copied",
+            workdir: decision.workdirPolicy === "new_empty"
+              ? "new empty directory under the source workdir's parent (or <daemon cwd>/clone-work when the source has no project workdir)"
+              : "share the source workdir (explicit)",
+            session: decision.sessionContract.detail,
+          },
+        }) }],
+      };
+    },
+  );
+
   // #1362 — daemon-side compensation for missed SSE doorbells. pushEvent is
   // intentionally best-effort; after a daemon connects or reconnects, it pulls
   // any still-pending requests bound to its own daemon token.
   server.tool(
     "list_my_pending_create_requests",
-    "Daemon lists pending create-node requests bound to itself for SSE reconnect compensation. RFC-026/#1362.",
+    "Daemon pulls its pending creates after reconnect.",
     {},
     async () => {
       const callerDaemon = resolveCallerDaemonTokenBound();
@@ -4595,10 +4780,29 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
           WHERE daemon_node_id = ?1
             AND network_id = ?2
             AND status = 'pending'
+            AND COALESCE(clone_json, '') = ''
           ORDER BY created_at ASC`,
         callerDaemon.daemonNodeId, callerDaemon.networkId,
       );
-      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, count: rows.length, requests: rows }) }] };
+      // Hub #938 — clone rows stay out of `requests` so an older daemon
+      // that replays every pending create does not spawn a blank node.
+      const clone_requests = db.all<{ request_id: string; child_name: string; created_at: number }>(
+        `SELECT request_id, child_name, created_at
+           FROM node_create_requests
+          WHERE daemon_node_id = ?1
+            AND network_id = ?2
+            AND status = 'pending'
+            AND COALESCE(clone_json, '') != ''
+          ORDER BY created_at ASC`,
+        callerDaemon.daemonNodeId, callerDaemon.networkId,
+      );
+      return { content: [{ type: "text" as const, text: JSON.stringify({
+        ok: true,
+        count: rows.length,
+        requests: rows,
+        clone_count: clone_requests.length,
+        clone_requests,
+      }) }] };
     },
   );
 
@@ -4614,7 +4818,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   // 只返回绑定到本 daemon + 本网络的 pending 行。
   server.tool(
     "list_my_pending_lifecycle_requests",
-    "Daemon lists pending stop/delete/start requests bound to itself for SSE reconnect compensation. Mirrors list_my_pending_create_requests (#1394/#1448).",
+    "Daemon pulls its pending stop/delete/start requests after reconnect.",
     {},
     async () => {
       const callerDaemon = resolveCallerDaemonTokenBound();
@@ -4666,21 +4870,30 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   // isn't a host_supervisor, reject.
   server.tool(
     "get_create_request",
-    "Daemon pulls a pending create-node request (called when SSE create_node doorbell arrives). RFC-026.",
+    "Daemon pulls a pending create-node request (called when SSE create_node doorbell arrives). RFC-026. expect_clone pulls a clone_node row.",
     {
       request_id: z.string().min(1).max(200),
+      expect_clone: z.boolean().optional(),
     },
-    async ({ request_id }) => {
+    async ({ request_id, expect_clone }) => {
       const callerDaemon = resolveCallerDaemonTokenBound();
       if (!callerDaemon.ok) {
         return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: callerDaemon.error }) }] };
       }
 
-      const row = db.get<{ request_id: string; daemon_node_id: string; status: string; child_token_id: string | null; network_id: string }>(
-        `SELECT request_id, daemon_node_id, status, child_token_id, network_id FROM node_create_requests WHERE request_id = ?1`,
+      const row = db.get<{ request_id: string; daemon_node_id: string; status: string; child_token_id: string | null; network_id: string; clone_json: string | null }>(
+        `SELECT request_id, daemon_node_id, status, child_token_id, network_id, clone_json FROM node_create_requests WHERE request_id = ?1`,
         request_id,
       );
       if (!row) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "request_not_found" }) }] };
+      const isClone = typeof row.clone_json === "string" && row.clone_json.trim().length > 0;
+      // Do not consume the env blob or flip status when the wrong handler asks.
+      if (isClone && expect_clone !== true) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "clone_request" }) }] };
+      }
+      if (!isClone && expect_clone === true) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "not_a_clone" }) }] };
+      }
       // §4.1.4 — strict daemon binding by token-derived node_id.
       if (row.daemon_node_id !== callerDaemon.daemonNodeId) {
         return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "not_your_request" }) }] };
@@ -4730,6 +4943,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
           },
           child_token: blob.child_token,
           env_blob: blob.env_blob,
+          ...(isClone ? { clone: JSON.parse(row.clone_json as string) } : {}),
         }) }],
       };
     },
@@ -5178,7 +5392,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
 
   server.tool(
     "stop_node",
-    "Stop the agent-node child process; keep config dir intact. Reversible via restart_node. RFC-027 §2.2. daemon_node_id is auto-resolved from child_node_id when omitted (looked up in node_create_requests).",
+    "Stop child, preserving config. Restart via restart_node. Omitted daemon_node_id resolves from child's create request.",
     {
       ...NODE_ID_ALIAS_FIELDS,
       // PR2 prereq: dashboard rarely knows daemon_node_id directly.
@@ -5407,7 +5621,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   // consumer of its own, so restart_node's self-doorbell cannot revive it.
   server.tool(
     "start_node",
-    "Start a stopped child through its host supervisor daemon. daemon_node_id is auto-resolved from the original create request.",
+    "Start stopped child; omitted daemon_node_id resolves from its create request.",
     {
       ...NODE_ID_ALIAS_FIELDS,
       daemon_node_id: z.string().min(1).max(200).regex(/^node_[a-z0-9_-]+$/).optional(),
@@ -5629,7 +5843,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   // token + network.
   server.tool(
     "list_my_children",
-    "Daemon pulls the alias + node_id list of children it spawned (for childrenMap rebuild after restart). RFC-027 PR1.1.",
+    "Daemon lists child alias/node_id pairs to rebuild its map.",
     {},
     async () => {
       const callerDaemon = resolveCallerDaemonTokenBound(); // board #674: token-bound snapshot, not a lease
@@ -5675,7 +5889,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   const adoptionReply = (result: unknown) => ({ content: [{ type: "text" as const, text: JSON.stringify(result) }] });
   server.tool(
     "request_adopt_node",
-    "Human owner/admin requests adoption. Only the target capable daemon may activate the binding after local verification; no process is signalled.",
+    "Owner/admin requests adoption; target daemon verifies locally before binding. No signals.",
     { node_id: z.string().min(1).max(200), daemon_node_id: z.string().min(1).max(200), workdir: z.string().min(1).max(4096) },
     async args => adoptionReply(requestAdopt(adoptionHuman(), args)),
   );
@@ -5984,7 +6198,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   // §2.3.3 — list_providers (viewer+; never returns secret VALUES).
   server.tool(
     "list_providers",
-    "List providers + models in the caller's network. Never returns secret VALUES. RFC-028.",
+    "List network Provider/model registry, never secrets. Not daemon inventory.",
     { network_id: z.string().max(200).optional() },
     async ({ network_id: clientNetId }) => {
       const effectiveNetId = getNetworkId(clientNetId);
@@ -6011,7 +6225,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   // §2.3.5 — probe_provider_model (admin+; dispatches to daemon).
   server.tool(
     "probe_provider_model",
-    "Dispatch a connectivity probe to a daemon. Mints ephemeral secret blob; daemon pulls via get_probe_request. Admin+. RFC-028.",
+    "Admin+ dispatches daemon probe; ephemeral secret pulled via get_probe_request.",
     {
       provider_id: z.string().min(1).max(200),
       model_name: z.string().min(1).max(100),
@@ -6077,7 +6291,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   // §2.3.6 — get_probe_results (viewer+; matrix renderer source).
   server.tool(
     "get_probe_results",
-    "Query probe history (optionally filtered by provider/model/daemon). Used by dashboard reachability matrix. RFC-028.",
+    "Query probe history filtered by provider/model/daemon.",
     {
       provider_id: z.string().max(200).optional(),
       model_name: z.string().max(100).optional(),
@@ -6105,7 +6319,7 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
   // §2.3.7 daemon-facing — get_probe_request.
   server.tool(
     "get_probe_request",
-    "Daemon pulls a pending probe request (called when SSE probe_provider doorbell arrives). RFC-028.",
+    "Daemon pulls pending probe on SSE probe_provider.",
     { probe_id: z.string().min(1).max(200) },
     async ({ probe_id }) => {
       const callerDaemon = _resolveCallerDaemonTokenBound({ callerTokenIsNetwork, callerTokenId, enforceNetworkId });