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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.121",
+  "version": "0.9.0-preview.122",
   "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/clone-node.test.ts

@@ -0,0 +1,248 @@
+// Hub #938 — clone_node on the same daemon: new token, rename collision,
+// cross-daemon refusal. Handler-level, same shape as stop-delete-node.test.ts.
+import { afterAll, beforeEach, describe, expect, test } from "bun:test";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { db, hashToken } from "./db.js";
+import { peekPendingEnvBlob, stopBackgroundTimersForTest } from "./create-node.js";
+import { registerTools } from "./tools.js";
+import { sessionContractForRuntime } from "./clone-node.js";
+
+const NET = "net_clone_938";
+const USER = "u_clone_938";
+const DAEMON = "node_clone_daemon_a";
+const DAEMON_B = "node_clone_daemon_b";
+const DAEMON_ALIAS = "clone-daemon-a";
+const DAEMON_B_ALIAS = "clone-daemon-b";
+const DAEMON_TOK = "tok_clone_daemon_a";
+const SOURCE = "node_clone_source";
+const SOURCE_ALIAS = "src-child";
+const SOURCE_TOKEN = "ntok_source_SHOULD_NOT_COPY";
+const OTHER = "node_clone_other";
+const OTHER_ALIAS = "other-child";
+
+interface ToolHandler { (args: any, extra?: any): Promise<{ content: Array<{ type: "text"; text: string }> }>; }
+interface Reply { ok?: boolean; error?: string; [k: string]: unknown; }
+
+function cleanup() {
+  for (const n of [NET]) {
+    try { db.run("DELETE FROM node_create_requests WHERE network_id = ?1", [n]); } catch {}
+    try { db.run("DELETE FROM audit_log WHERE network_id = ?1", [n]); } catch {}
+    try { db.run("DELETE FROM nodes WHERE network_id = ?1", [n]); } catch {}
+    try { db.run("DELETE FROM api_tokens WHERE network_id = ?1", [n]); } catch {}
+    try { db.run("DELETE FROM network_members WHERE network_id = ?1", [n]); } catch {}
+    try { db.run("DELETE FROM networks WHERE network_id = ?1", [n]); } catch {}
+  }
+  try { db.run("DELETE FROM users WHERE user_id = ?1", [USER]); } catch {}
+  stopBackgroundTimersForTest();
+}
+
+beforeEach(cleanup);
+afterAll(cleanup);
+
+function seed() {
+  db.run(
+    `INSERT INTO users (user_id, username, password_hash, role, created_at) VALUES (?1, ?2, 'x', 'user', datetime('now'))`,
+    [USER, USER],
+  );
+  db.run(
+    `INSERT INTO networks (network_id, network_name, owner_id, created_at) VALUES (?1, ?2, ?3, datetime('now'))`,
+    [NET, NET, USER],
+  );
+  db.run(
+    `INSERT INTO network_members (user_id, network_id, role, joined_at) VALUES (?1, ?2, 'admin', datetime('now'))`,
+    [USER, NET],
+  );
+  const snap = JSON.stringify({
+    role: "member",
+    runtime: "claude-agent-sdk",
+    model: "claude-sonnet",
+    flags: { permissionMode: "acceptEdits", timeout: 60000, apiKey: "sk-do-not-copy" },
+    channels: ["server:commhub", "feishu:bot-secret"],
+  });
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, runtime, model, channels, config_snapshot, hostname, created_at, updated_at, lifecycle_state)
+     VALUES (?1, ?2, ?3, ?4, 'claude-agent-sdk', 'claude-sonnet', ?5, ?6, 'host-a', datetime('now'), datetime('now'), 'active')`,
+    [SOURCE, SOURCE_ALIAS, SOURCE_ALIAS, NET, JSON.stringify(["server:commhub", "feishu:bot-secret"]), snap],
+  );
+  db.run(
+    `INSERT INTO api_tokens (token_id, user_id, network_id, scope, name, token_hash, role) VALUES (?1, ?2, ?3, 'network', ?4, ?5, 'child')`,
+    ["tok_clone_source", USER, NET, `node:${SOURCE_ALIAS}`, hashToken(SOURCE_TOKEN)],
+  );
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, config_snapshot, hostname, created_at, updated_at, lifecycle_state)
+     VALUES (?1, ?2, ?2, ?3, ?4, 'host-a', datetime('now'), datetime('now'), 'active')`,
+    [DAEMON, DAEMON_ALIAS, NET, JSON.stringify({ role: "host_supervisor", daemon_capabilities: { can_create_nodes: true, runtimes_supported: ["claude-agent-sdk", "opencode-cli"] } })],
+  );
+  db.run(
+    `INSERT INTO api_tokens (token_id, user_id, network_id, scope, name, token_hash) VALUES (?1, ?2, ?3, 'network', ?4, ?5)`,
+    [DAEMON_TOK, USER, NET, `node:${DAEMON_ALIAS}`, `hash_${DAEMON_TOK}`],
+  );
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, config_snapshot, hostname, created_at, updated_at, lifecycle_state)
+     VALUES (?1, ?2, ?2, ?3, ?4, 'host-b', datetime('now'), datetime('now'), 'active')`,
+    [DAEMON_B, DAEMON_B_ALIAS, NET, JSON.stringify({ role: "host_supervisor" })],
+  );
+  db.run(
+    `INSERT INTO nodes (node_id, node_name, alias, network_id, config_snapshot, hostname, created_at, updated_at, lifecycle_state)
+     VALUES (?1, ?2, ?2, ?3, '{}', 'host-a', datetime('now'), datetime('now'), 'active')`,
+    [OTHER, OTHER_ALIAS, NET],
+  );
+  db.run(
+    `INSERT INTO node_create_requests(request_id,daemon_node_id,child_name,network_id,runtime,model,flags_json,env_keys,status,created_at,created_by_token,child_node_id)
+     VALUES('cr_clone_source', ?1, ?2, ?3, 'claude-agent-sdk', 'claude-sonnet', ?4, '[]', 'succeeded', 1, 't', ?5)`,
+    [DAEMON, SOURCE_ALIAS, NET, JSON.stringify({ permissionMode: "plan" }), SOURCE],
+  );
+}
+
+function handlers(daemonBound = false): Record<string, ToolHandler> {
+  const server = new McpServer({ name: "test", version: "0" }) as any;
+  const tools: Record<string, ToolHandler> = {};
+  const orig = server.tool.bind(server);
+  server.tool = (name: string, desc: string, schema: any, handler: ToolHandler) => {
+    tools[name] = handler;
+    return orig(name, desc, schema, handler);
+  };
+  registerTools(server, undefined, daemonBound ? NET : null, USER, null, daemonBound, daemonBound ? DAEMON_TOK : null);
+  return tools;
+}
+
+async function call(handler: ToolHandler, args: any): Promise<Reply> {
+  const r = await handler(args);
+  return JSON.parse(r.content[0].text) as Reply;
+}
+
+describe("clone_node — happy path (Hub #938)", () => {
+  test("mints a new token, keeps the source token, records clone directives", async () => {
+    seed();
+    const tools = handlers();
+    const r = await call(tools.clone_node, {
+      source_node_id: SOURCE,
+      name: "cloned-child",
+      network_id: NET,
+    });
+    expect(r.ok).toBe(true);
+    expect(r.daemon_node_id).toBe(DAEMON);
+    expect(r.child_name).toBe("cloned-child");
+    expect(r.copy_session).toBe(true);
+    expect(r.workdir_policy).toBe("new_empty");
+    expect(r.session_contract).toMatchObject({ mode: "transcript_when_present", runtime: "claude-agent-sdk" });
+    const contract = r.contract as { token: string; workdir: string; session: string };
+    expect(contract.token).toContain("new ntok_");
+    expect(contract.workdir).toContain("new empty directory");
+    expect(contract.session).toContain("jsonl");
+
+    const requestId = r.request_id as string;
+    const row = db.get<{ clone_json: string; runtime: string; flags_json: string; child_token_id: string; status: string }>(
+      `SELECT clone_json, runtime, flags_json, child_token_id, status FROM node_create_requests WHERE request_id = ?1`,
+      requestId,
+    );
+    expect(row?.status).toBe("pending");
+    expect(row?.runtime).toBe("claude-agent-sdk");
+    const flags = JSON.parse(row!.flags_json);
+    expect(flags.permissionMode).toBe("acceptEdits");
+    expect(flags.timeout).toBe(60000);
+    expect(JSON.stringify(flags)).not.toContain("sk-do-not-copy");
+    const meta = JSON.parse(row!.clone_json);
+    expect(meta).toMatchObject({
+      source_node_id: SOURCE,
+      source_alias: SOURCE_ALIAS,
+      copy_session: true,
+      workdir_policy: "new_empty",
+      channels: ["server:commhub"],
+    });
+    expect(JSON.stringify(meta.channels)).not.toContain("feishu");
+
+    const blob = peekPendingEnvBlob(requestId);
+    expect(blob?.env_blob).toEqual({});
+    expect(blob?.child_token.startsWith("ntok_")).toBe(true);
+    expect(blob?.child_token).not.toBe(SOURCE_TOKEN);
+    const minted = db.get<{ token_hash: string }>(
+      `SELECT token_hash FROM api_tokens WHERE token_id = ?1`, row!.child_token_id,
+    );
+    expect(minted?.token_hash).toBe(hashToken(blob!.child_token));
+    expect(minted?.token_hash).not.toBe(hashToken(SOURCE_TOKEN));
+    const sourceTok = db.get<{ revoked_at: string | null }>(
+      `SELECT revoked_at FROM api_tokens WHERE token_id = 'tok_clone_source'`,
+    );
+    expect(sourceTok?.revoked_at ?? null).toBeNull();
+
+    const daemonTools = handlers(true);
+    const listed = await call(daemonTools.list_my_pending_create_requests, {});
+    expect(listed.ok).toBe(true);
+    expect(listed.requests).toEqual([]);
+    expect(listed.clone_requests).toEqual([
+      expect.objectContaining({ request_id: requestId, child_name: "cloned-child" }),
+    ]);
+    const refused = await call(daemonTools.get_create_request, { request_id: requestId });
+    expect(refused).toMatchObject({ ok: false, error: "clone_request" });
+    expect(peekPendingEnvBlob(requestId)?.child_token).toBe(blob?.child_token);
+    const pulled = await call(daemonTools.get_create_request, { request_id: requestId, expect_clone: true });
+    expect(pulled.ok).toBe(true);
+    expect(pulled.child_token).toBe(blob?.child_token);
+    expect((pulled.clone as { source_alias: string }).source_alias).toBe(SOURCE_ALIAS);
+    expect(peekPendingEnvBlob(requestId)).toBeNull();
+  });
+});
+
+describe("clone_node — rename collision", () => {
+  test("refuses the source name, an existing alias, and an inflight create name", async () => {
+    seed();
+    db.run(
+      `INSERT INTO node_create_requests(request_id,daemon_node_id,child_name,network_id,runtime,model,flags_json,env_keys,status,created_at,created_by_token)
+       VALUES('cr_clone_inflight', ?1, 'pending-name', ?2, 'claude-agent-sdk', 'm', '{}', '[]', 'pending', ?3, 't')`,
+      [DAEMON, NET, Date.now()],
+    );
+    const tools = handlers();
+    const same = await call(tools.clone_node, { source_node_id: SOURCE, name: SOURCE_ALIAS, network_id: NET });
+    expect(same).toMatchObject({ ok: false, error: "node_name_conflict", reason: "same_as_source" });
+    const taken = await call(tools.clone_node, { source_node_id: SOURCE, name: OTHER_ALIAS, network_id: NET });
+    expect(taken).toMatchObject({ ok: false, error: "node_name_conflict", reason: "alias_taken" });
+    const inflight = await call(tools.clone_node, { source_node_id: SOURCE, name: "pending-name", network_id: NET });
+    expect(inflight).toMatchObject({ ok: false, error: "node_name_conflict", reason: "inflight_create" });
+    const n = db.get<{ n: number }>(
+      `SELECT COUNT(*) AS n FROM node_create_requests WHERE child_name = 'cloned-child'`,
+    );
+    expect(n?.n).toBe(0);
+  });
+});
+
+describe("clone_node — cross-daemon refused", () => {
+  test("a daemon_node_id other than the source's daemon is refused", async () => {
+    seed();
+    const tools = handlers();
+    const r = await call(tools.clone_node, {
+      source_node_id: SOURCE,
+      name: "cloned-child",
+      daemon_node_id: DAEMON_B,
+      network_id: NET,
+    });
+    expect(r.ok).toBe(false);
+    expect(r.error).toBe("cross_daemon_refused");
+    expect(r.source_daemon_node_id).toBe(DAEMON);
+    expect(r.requested_daemon_node_id).toBe(DAEMON_B);
+    const n = db.get<{ n: number }>(
+      `SELECT COUNT(*) AS n FROM api_tokens WHERE name = 'node:cloned-child'`,
+    );
+    expect(n?.n ?? 0).toBe(0);
+  });
+
+  test("omitting daemon_node_id stays on the source daemon", async () => {
+    seed();
+    const tools = handlers();
+    const r = await call(tools.clone_node, { source_node_id: SOURCE, name: "cloned-child", network_id: NET });
+    expect(r.ok).toBe(true);
+    expect(r.daemon_node_id).toBe(DAEMON);
+  });
+});
+
+describe("session contract is honest per runtime", () => {
+  test("OpenCode is an aliased server session, not a transcript fork", () => {
+    const c = sessionContractForRuntime("opencode-cli");
+    expect(c.mode).toBe("id_aliased");
+    expect(c.detail).toContain("not a private deep copy");
+  });
+
+  test("an unknown runtime does not claim a session copy", () => {
+    expect(sessionContractForRuntime("not-a-runtime").mode).toBe("unsupported");
+  });
+});

package/src/clone-node.ts

@@ -0,0 +1,289 @@
+// Hub #938 — clone a daemon child into a new node on the SAME daemon.
+//
+// Contract (also what `clone_node` returns as `contract`):
+//
+//   Identity     new node_id (minted like create_node: `node_<request id>`),
+//                new alias, new ntok_. The source token is never copied and
+//                never placed in the env blob.
+//   Copied       runtime, model / provider ref (the model string, including
+//                `provider/model`), flags that pass the create_node flag
+//                checks, and commhub channel specs (string entries that are
+//                the network itself). Secret-looking flag values are dropped.
+//   Not copied   token, secrets.env, inline secret env values (key names may
+//                remain as env refs with no value), non-commhub channel
+//                specs (those carry per-node bot credentials).
+//   Session      `copy_session` defaults to true. What that can actually do
+//                depends on the runtime — see `sessionContractForRuntime`.
+//                The daemon performs the copy; this module only states the
+//                capability so the caller is not told a deep copy happened
+//                when the vendor store cannot be forked.
+//   Workdir      `new_empty` (default) or `share_source`. The daemon chooses
+//                the path; this module only records the policy.
+//
+// Workdir policy, decided on the daemon because only it knows the source
+// directory:
+//
+//   new_empty (default)
+//     A new empty directory under the same parent as the source workdir:
+//     `dirname(sourceWorkdir)/<ascii folder>`. The folder name is the new
+//     alias when that alias is already an ASCII directory name, otherwise
+//     the usual `node-<hash>` slug. Nothing inside the source workdir is
+//     copied (no rules file, no checkout).
+//     When the source has no project workdir of its own — it was created
+//     in the daemon cwd — there is no sibling project to sit beside. The
+//     clone is then placed at `<daemon cwd>/clone-work/<ascii folder>`,
+//     still a new empty directory under the daemon root. That is the only
+//     case that does not use the source's parent.
+//
+//   share_source
+//     Explicit opt-in. The clone's cwd is the source workdir. Two nodes
+//     share that checkout. The token is still new. Session files that are
+//     keyed by cwd do not need to be relocated.
+//
+// Cross-daemon: the clone is dispatched only to the daemon that created
+// the source (`node_create_requests.daemon_node_id` of the succeeded row).
+// Passing a different `daemon_node_id` is `cross_daemon_refused`. A node
+// with no succeeded create row on a daemon is `source_not_daemon_child`.
+
+import {
+  FLAG_KEYS,
+  validateFlagValue,
+  validateFlagsForRuntime,
+  validateModel,
+  validateName,
+  validateRuntime,
+  ValidationError,
+} from "./create-node-validate.js";
+
+export const CLONE_WORKDIR_POLICIES = ["new_empty", "share_source"] as const;
+export type CloneWorkdirPolicy = typeof CLONE_WORKDIR_POLICIES[number];
+
+const SECRET_VALUE_RX = /^(sk-|utok_|ntok_|atok_|ak-|gsk_|key-|Bearer\s)/i;
+
+export interface CloneSourceFacts {
+  nodeId: string;
+  alias: string;
+  role: string | null;
+  runtime: string | null;
+  model: string | null;
+  flags: Record<string, unknown>;
+  channels: unknown;
+  /** Daemon that owns the succeeded create row, or null if this node is not a daemon child. */
+  owningDaemonId: string | null;
+  /** Aliases / node names already present in the network. */
+  existingNames: readonly string[];
+  /** child_name values with a pending/delivered create on the owning daemon. */
+  inflightNames: readonly string[];
+}
+
+export interface CloneAsk {
+  newName: string;
+  copySession: boolean;
+  workdirPolicy: CloneWorkdirPolicy;
+  /** When set, must equal the owning daemon. */
+  requestedDaemonId: string | null;
+}
+
+export interface SessionContract {
+  /** Stable code. Not a claim that a private transcript fork already exists. */
+  mode: "transcript_when_present" | "id_aliased" | "unsupported";
+  runtime: string;
+  /** What resume/continue will do, in one sentence the caller can show. */
+  detail: string;
+}
+
+export type CloneDecision =
+  | { ok: false; error: string; detail?: Record<string, unknown> }
+  | {
+      ok: true;
+      daemonNodeId: string;
+      name: string;
+      runtime: string;
+      model: string | null;
+      flags: Record<string, unknown>;
+      channels: string[];
+      droppedChannels: string[];
+      copySession: boolean;
+      workdirPolicy: CloneWorkdirPolicy;
+      sessionContract: SessionContract;
+    };
+
+export function sessionContractForRuntime(runtime: string): SessionContract {
+  if (runtime === "claude-agent-sdk" || runtime === "claude-code-cli") {
+    return {
+      mode: "transcript_when_present",
+      runtime,
+      detail: "Claude resume is the session id plus ~/.claude/projects/<cwd>/<id>.jsonl. The daemon copies that file into the clone's cwd key and writes the same session id. If the file is not on disk, the id is not copied: a bare id would bind an empty session, not continue the old one.",
+    };
+  }
+  if (runtime === "codex-sdk" || runtime === "codex-app-server") {
+    return {
+      mode: "transcript_when_present",
+      runtime,
+      detail: "Codex resume needs the rollout file under the new node's CODEX_HOME. The daemon copies that rollout and keeps the thread id when the file is present. auth.json is not copied. If there is no rollout, the thread id is not copied. This is not `anet node codex fork` (that rewrites a new thread id).",
+    };
+  }
+  if (runtime === "grok-build-acp" || runtime === "grok-build-cli") {
+    return {
+      mode: "transcript_when_present",
+      runtime,
+      detail: "Grok resume needs the session directory under the grok home, keyed by cwd. The daemon copies that directory and keeps the session id when it exists. If it does not, the id is not copied: grok refuses to resume a missing directory.",
+    };
+  }
+  if (runtime === "opencode-cli") {
+    return {
+      mode: "id_aliased",
+      runtime,
+      detail: "OpenCode sessions live in the OpenCode server, not in the node directory. The daemon copies the session id so session/load addresses that same server session. That is not a private deep copy: both nodes share one server-side transcript. There is no local transcript to fork.",
+    };
+  }
+  return {
+    mode: "unsupported",
+    runtime,
+    detail: "This runtime has no clone session copy. The new node starts without a session id.",
+  };
+}
+
+function safeFlags(runtime: string, raw: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(raw)) {
+    if (!(FLAG_KEYS as readonly string[]).includes(k)) continue;
+    if (typeof v === "string" && SECRET_VALUE_RX.test(v)) continue;
+    try {
+      validateFlagValue(k, v);
+    } catch {
+      continue;
+    }
+    out[k] = v;
+  }
+  validateFlagsForRuntime(runtime, out);
+  return out;
+}
+
+/** Commhub channel specs only. Anything else can carry a bot credential. */
+export function safeChannels(raw: unknown): { kept: string[]; dropped: string[] } {
+  if (!Array.isArray(raw)) return { kept: [], dropped: [] };
+  const kept: string[] = [];
+  const dropped: string[] = [];
+  for (const ch of raw) {
+    if (typeof ch !== "string") {
+      dropped.push(typeof ch);
+      continue;
+    }
+    if (ch.includes("commhub") || ch.startsWith("server:")) kept.push(ch);
+    else dropped.push(ch.slice(0, 80));
+  }
+  return { kept, dropped };
+}
+
+function readRole(snapshot: unknown): string | null {
+  if (!snapshot || typeof snapshot !== "object") return null;
+  const role = (snapshot as { role?: unknown }).role;
+  return typeof role === "string" ? role : null;
+}
+
+export function factsFromRows(input: {
+  node: { node_id: string; alias: string | null; node_name?: string | null; runtime?: string | null; model?: string | null; channels?: string | null; config_snapshot?: string | null };
+  createRow: { daemon_node_id: string; runtime: string; model: string | null; flags_json: string; child_name: string } | null;
+  existingNames: readonly string[];
+  inflightNames: readonly string[];
+}): CloneSourceFacts {
+  let snap: Record<string, unknown> = {};
+  try {
+    const parsed = input.node.config_snapshot ? JSON.parse(input.node.config_snapshot) : null;
+    if (parsed && typeof parsed === "object") snap = parsed as Record<string, unknown>;
+  } catch { /* snapshot is display state; the create row still stands */ }
+  let createFlags: Record<string, unknown> = {};
+  try {
+    const parsed = input.createRow ? JSON.parse(input.createRow.flags_json) : {};
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) createFlags = parsed as Record<string, unknown>;
+  } catch { /* ignore */ }
+  const snapFlags = snap.flags && typeof snap.flags === "object" && !Array.isArray(snap.flags)
+    ? snap.flags as Record<string, unknown>
+    : {};
+  const runtime = (typeof snap.runtime === "string" && snap.runtime) ? snap.runtime
+    : (input.node.runtime || input.createRow?.runtime || null);
+  const model = (typeof snap.model === "string" || snap.model === null) ? (snap.model as string | null)
+    : (input.node.model ?? input.createRow?.model ?? null);
+  const channels = Array.isArray(snap.channels) ? snap.channels
+    : (input.node.channels ? safeParseArray(input.node.channels) : []);
+  return {
+    nodeId: input.node.node_id,
+    alias: input.node.alias || input.node.node_name || input.createRow?.child_name || "",
+    role: readRole(snap),
+    runtime,
+    model,
+    flags: { ...createFlags, ...snapFlags },
+    channels,
+    owningDaemonId: input.createRow?.daemon_node_id ?? null,
+    existingNames: input.existingNames,
+    inflightNames: input.inflightNames,
+  };
+}
+
+function safeParseArray(raw: string): unknown[] {
+  try {
+    const v = JSON.parse(raw);
+    return Array.isArray(v) ? v : [];
+  } catch {
+    return [];
+  }
+}
+
+/** Pure. Throws ValidationError for a bad new name, model, or runtime. */
+export function decideClone(source: CloneSourceFacts, ask: CloneAsk): CloneDecision {
+  if (!source.alias) {
+    return { ok: false, error: "source_alias_missing", detail: { source_node_id: source.nodeId } };
+  }
+  if (source.role === "host_supervisor") {
+    return { ok: false, error: "cannot_clone_daemon", detail: { source_node_id: source.nodeId } };
+  }
+  if (!source.owningDaemonId) {
+    return { ok: false, error: "source_not_daemon_child", detail: { source_node_id: source.nodeId } };
+  }
+  if (ask.requestedDaemonId && ask.requestedDaemonId !== source.owningDaemonId) {
+    return {
+      ok: false,
+      error: "cross_daemon_refused",
+      detail: { source_daemon_node_id: source.owningDaemonId, requested_daemon_node_id: ask.requestedDaemonId },
+    };
+  }
+  const name = validateName(ask.newName);
+  if (name === source.alias) {
+    return { ok: false, error: "node_name_conflict", detail: { name, reason: "same_as_source" } };
+  }
+  if (source.existingNames.includes(name)) {
+    return { ok: false, error: "node_name_conflict", detail: { name, reason: "alias_taken" } };
+  }
+  if (source.inflightNames.includes(name)) {
+    return { ok: false, error: "node_name_conflict", detail: { name, reason: "inflight_create" } };
+  }
+  if (!source.runtime) {
+    return { ok: false, error: "source_runtime_unknown", detail: { source_node_id: source.nodeId } };
+  }
+  validateRuntime(source.runtime);
+  validateModel(source.model);
+  const flags = safeFlags(source.runtime, source.flags);
+  const channels = safeChannels(source.channels);
+  return {
+    ok: true,
+    daemonNodeId: source.owningDaemonId,
+    name,
+    runtime: source.runtime,
+    model: source.model ?? null,
+    flags,
+    channels: channels.kept,
+    droppedChannels: channels.dropped,
+    copySession: ask.copySession,
+    workdirPolicy: ask.workdirPolicy,
+    sessionContract: sessionContractForRuntime(source.runtime),
+  };
+}
+
+export function parseWorkdirPolicy(raw: unknown): CloneWorkdirPolicy {
+  if (raw === undefined || raw === null || raw === "") return "new_empty";
+  if (raw === "new_empty" || raw === "share_source") return raw;
+  throw new ValidationError("workdir_policy_invalid", { value: typeof raw === "string" ? raw.slice(0, 40) : typeof raw, allowed: [...CLONE_WORKDIR_POLICIES] });
+}
+
+export { ValidationError };