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

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

@@ -1,25 +1,39 @@
 import { describe, expect, test } from "bun:test";
 import {
   ValidationError,
-  validateName, validateRuntime, validateModel, validateFlagValue,
+  validateName, validateRuntime, validateModel, validateFlagValue, RUNTIMES,
   validateEnvRefs, validateChannelsP1, serializeEnvLocal, buildAnetArgs,
-  MAX_ENV_KEYS_PER_NODE,
+  MAX_ENV_KEYS_PER_NODE, validateFlagsForRuntime, validateOpenCodeV2ProviderModel, COPRESENCE_FLAG_RUNTIMES,
 } from "./create-node-validate.js";
 
 const okSecret = (k: string, _net: string, key: string) => k === key ? `value-of-${k}` : undefined;
 const allow = (k: string) => new Set<string>([k, "ANTHROPIC_API_KEY", "OPENAI_API_KEY"]);
 
-describe("validateName (§4.2.2)", () => {
-  test("good names", () => {
-    for (const n of ["a", "demo-bot", "node_1", "z2", "abc-def-ghi"]) {
+describe("validateName (§4.2.2, #652 Unicode names)", () => {
+  test("good names — incl. Chinese, upper case, digits first", () => {
+    for (const n of ["a", "demo-bot", "node_1", "z2", "abc-def-ghi", "测试", "研发助手A", "Demo", "1demo", "测".repeat(64)]) {
       expect(() => validateName(n)).not.toThrow();
     }
   });
-  test("rejects shell-injection-like names", () => {
-    for (const n of [";rm -rf /", "demo bot", "Demo", "1demo", "-demo", "demo;rm", "demo$INJECT", "x".repeat(65)]) {
+  test("returns the trimmed name", () => {
+    expect(validateName("  测试 ")).toBe("测试");
+  });
+  test("rejects shell-injection-like and path-like names with a reason", () => {
+    for (const n of [";rm -rf /", "demo bot", "-demo", "demo;rm", "demo$INJECT", "x".repeat(65), "测".repeat(65),
+      "a/b", "a\\b", "a:b", ".hidden", "..", "a\u0000b", "a`id`", "", "   "]) {
       expect(() => validateName(n)).toThrow(ValidationError);
     }
   });
+  test("error carries reason + offending char + a readable message", () => {
+    try { validateName("a/b"); throw new Error("no throw"); }
+    catch (e: any) {
+      expect(e).toBeInstanceOf(ValidationError);
+      expect(e.code).toBe("node_name_invalid");
+      expect(e.detail.reason).toBe("forbidden_char");
+      expect(e.detail.char).toBe("/");
+      expect(String(e.detail.message)).toContain("/");
+    }
+  });
 });
 
 describe("validateRuntime / validateModel (§4.2.2)", () => {
@@ -35,6 +49,15 @@ describe("validateRuntime / validateModel (§4.2.2)", () => {
     expect(() => validateModel("gpt-4o")).not.toThrow();
     expect(() => validateModel("bad model")).toThrow(ValidationError);
     expect(() => validateModel("x;rm")).toThrow(ValidationError);
+    // provider/model(OpenCode 共存;桌面向导 0.2.61 起发这种形状,Vincent 2026-09-08 撞到 model_invalid)
+    expect(() => validateModel("opencode/mimo-v2.5-free")).not.toThrow();
+    expect(() => validateModel("anthropic/claude-sonnet-4")).not.toThrow();
+    expect(() => validateModel("a/b/c")).toThrow(ValidationError);      // 只许一个斜杠
+    expect(() => validateModel("/model")).toThrow(ValidationError);     // 不能以斜杠开头
+    expect(() => validateModel("provider/")).toThrow(ValidationError);  // 不能以斜杠结尾
+    expect(() => validateModel("../x")).toThrow(ValidationError);       // 纯点段(路径穿越形状)
+    expect(() => validateModel("x/.")).toThrow(ValidationError);
+    expect(() => validateModel("open code/m")).toThrow(ValidationError);
     expect(() => validateModel("")).toThrow(ValidationError);
   });
 });
@@ -60,6 +83,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)", () => {
@@ -169,6 +216,41 @@ describe("buildAnetArgs (§4.2.2 F2 — fully validated argv)", () => {
     expect(args).toContain("--permission-mode");
     expect(args[args.indexOf("--permission-mode") + 1]).toBe("plan");
   });
+  test("OpenCode V2 requires provider/model only after unsafe opt-in", () => {
+    let unsafe = "";
+    try {
+      buildAnetArgs({ name: "v2", runtime: "opencode-cli", flags: { opencodeGeneration: "v2" } });
+    } catch (e) { unsafe = (e as ValidationError).code; }
+    expect(unsafe).toBe("opencode_v2_requires_unsafe_opt_in");
+    let missing = "";
+    try {
+      buildAnetArgs({ name: "v2", runtime: "opencode-cli", flags: { opencodeGeneration: "v2", opencodeUnsafeTools: true } });
+    } catch (e) { missing = (e as ValidationError).code; }
+    expect(missing).toBe("opencode_v2_requires_provider_model");
+    let bare = "";
+    try {
+      buildAnetArgs({ name: "v2", runtime: "opencode-cli", model: "opencode", flags: { opencodeGeneration: "v2", opencodeUnsafeTools: true } });
+    } catch (e) { bare = (e as ValidationError).code; }
+    expect(bare).toBe("opencode_v2_requires_provider_model");
+    const args = buildAnetArgs({
+      name: "v2", runtime: "opencode-cli", model: "stub/model",
+      flags: { opencodeGeneration: "v2", opencodeUnsafeTools: true },
+    });
+    expect(args).toContain("stub/model");
+    expect(() => validateOpenCodeV2ProviderModel("opencode-cli", undefined, { opencodeGeneration: "v2" })).not.toThrow();
+    expect(() => validateOpenCodeV2ProviderModel("claude-agent-sdk", undefined, { opencodeGeneration: "v2", opencodeUnsafeTools: true })).not.toThrow();
+    expect(buildAnetArgs({ name: "x", runtime: "opencode-cli" })).toEqual(["node", "create", "x", "--runtime", "opencode-cli"]);
+  });
+  test("omitted model is allowed and does not emit --model", () => {
+    const args = buildAnetArgs({
+      name: "x", runtime: "codex-sdk",
+      flags: { permissionMode: "plan" },
+    });
+    expect(args).toEqual(["node", "create", "x", "--runtime", "codex-sdk", "--permission-mode", "plan"]);
+  });
+  test("empty model is still rejected", () => {
+    expect(() => buildAnetArgs({ name: "x", runtime: "codex-sdk", model: "" })).toThrow(ValidationError);
+  });
   test("rejects bad name with shell metachar", () => {
     expect(() => buildAnetArgs({ name: ";rm -rf /", runtime: "claude-agent-sdk", model: "x" })).toThrow(ValidationError);
   });
@@ -185,3 +267,107 @@ describe("buildAnetArgs (§4.2.2 F2 — fully validated argv)", () => {
     } as any)).toThrow(ValidationError);
   });
 });
+
+// ─── runtime_invalid 要说清「允许哪些」和「还有什么路」 ────────────────
+//
+// 2026-08-28 实测：从 Dashboard 建一个 codex-app-server 节点，用户拿到的是
+//   {"ok":false,"error":"runtime_invalid","value":"codex-app-server"}
+// 而目标机器的 daemon 日志里一行都没有 —— 请求被 hub 拦在最前面，
+// 用户无从知道①哪些允许②是不是打错了③有没有别的办法。
+// 🔴 2026-08-28:这一节原本拿 `codex-app-server` / `opencode-cli` 当"非法 runtime"的例子。
+//    #1298 把 hub 的 RUNTIMES 从 3 个放开到 7 个之后,那两个变成了合法值,这两条测试因此红了 ——
+//    **测试正确地抓到了行为变更**。修法是换例子,不是削弱断言:
+//    意图仍然是「非法 runtime 要给可操作的报错」,只是例子换成永远不会合法的字符串。
+describe("validateRuntime — 报错要可操作", () => {
+  function thrown(v: unknown): any {
+    try { validateRuntime(v); } catch (e: any) { return e; }
+    throw new Error("expected validateRuntime to throw");
+  }
+
+  test("非法 runtime 的报错带上允许集合", () => {
+    const e = thrown("definitely-not-a-runtime");
+    expect(e.code).toBe("runtime_invalid");
+    expect(Array.isArray(e.detail?.allowed)).toBe(true);
+    // 🔴 断言它等于 RUNTIMES 本身,而不是等于一份手抄的清单 ——
+    //    手抄的那份会漂,漂了之后报错会理直气壮地告诉用户一组错的名字。
+    expect(e.detail.allowed).toEqual([...RUNTIMES]);
+  });
+
+  test("报错带上一条出路提示", () => {
+    const e = thrown("another-bogus-runtime");
+    expect(typeof e.detail?.hint).toBe("string");
+    expect(e.detail.hint.length).toBeGreaterThan(10);
+    // 提示必须点名那条真实存在的路,否则它只是安慰话
+    expect(e.detail.hint).toContain("anet node create");
+  });
+
+  test("仍然回报用户传进来的那个值（便于识别是不是打错了）", () => {
+    const e = thrown("codex-app-servr");   // 故意少一个 e
+    expect(e.detail.value).toBe("codex-app-servr");
+  });
+
+  test("🔴 合法 runtime 一个都不能被这次改动误伤", () => {
+    for (const r of RUNTIMES) {
+      expect(() => validateRuntime(r)).not.toThrow();
+    }
+    // 正控：非字符串必须仍然被拒 —— 否则上面那条循环全过也说明不了什么
+    expect(() => validateRuntime(123 as any)).toThrow();
+    expect(() => validateRuntime(undefined as any)).toThrow();
+  });
+});
+
+// #1298 —— daemon 远程创建放开到 7 个 runtime（Vincent 2026-08-28 定，
+// 理由是兜底排错：节点不动了，人要能进去跟 Codex / Claude Code 对话）。
+describe("#1298 RUNTIMES —— 七个都放行，且与 CLI 侧一致", () => {
+  test("三个共存 runtime 不再被拒", () => {
+    for (const r of ["codex-app-server", "grok-build-cli", "opencode-cli"]) {
+      expect(() => validateRuntime(r)).not.toThrow();
+    }
+  });
+  test("原有四个仍然放行（放开不该顺手改坏别的）", () => {
+    for (const r of ["claude-agent-sdk", "claude-code-cli", "codex-sdk", "grok-build-acp"]) {
+      expect(() => validateRuntime(r)).not.toThrow();
+    }
+  });
+  test("🔴 恰好七个 —— 多一个少一个都要有人解释", () => {
+    expect(RUNTIMES.length).toBe(7);
+    // 正控：不在名单里的仍然被拒，证明上面不是"什么都放行"
+    expect(() => validateRuntime("definitely-not-a-runtime")).toThrow();
+    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

@@ -8,6 +8,9 @@
 // payload (RFC §4.6).
 
 import { isReservedEnvKey } from "./shared/reserved-env.js";
+import { checkNodeName } from "./shared/node-name.js";
+import { CODEX_CONFIG_ONLY_FLAG_KEYS, validateCodexConfigFlag } from "./codex-config-flags.js";
+import { validProviderInitialization } from './shared/provider-initialization.js';
 
 export class ValidationError extends Error {
   constructor(public code: string, public detail?: Record<string, unknown>) {
@@ -17,10 +20,50 @@ export class ValidationError extends Error {
 }
 
 // §4.2.2 — structural enums.
-export const RUNTIMES = ["claude-agent-sdk", "codex-sdk", "grok-build-acp"] as const;
+// #1298 —— daemon 远程创建允许的 runtime。2026-08-28 从 3 个放开到 7 个。
+//
+// 放开之前挡着的问题是「daemon 建出来的是**无人值守**的后台进程,而三个共存 runtime
+// 的本质是人和 agent 共用一个 TUI 会话 —— 建出来给谁用?」
+//
+// Vincent 2026-08-28 定,理由是**兜底排错**:
+//   「某个节点突然不动了,人可以进去看。在 daemon 还没那么靠谱的情况下,
+//     这非常重要 —— 至少可以跟 Codex 和 Claude Code 对话。」
+// 🔴 关键在于 **attach 是「建好之后」的动作,不是「建的时候」的前提**。
+//
+// 支撑读数(2026-08-28 实测舰队):`通信牛` 跑 codex-app-server(共存 runtime),
+// **764 次成功完成任务**,当天仍在跑 —— 比两个普通 runtime 的节点(61 次 / 3 次)
+// 都多一个量级。⇒ 任务链路不需要人坐在屏幕前。
+//
+// 🔴 这七个名字与 `agent-network/src/normalize-runtime.ts` 的 `RuntimeName` 一致。
+//    那边是 CLI 侧的全集;两边分叉过一次(daemon 侧的 VALID_RUNTIMES 早就是 7 个,
+//    只有这里还是 3 个,而记录此事的 #1298 正文写的是「三道闸都关着」——
+//    **一份快照式的盘点,只在写下的那一刻是真的**)。
+export const RUNTIMES = [
+  "claude-agent-sdk",
+  "claude-code-cli",
+  "codex-sdk",
+  "codex-app-server",
+  "grok-build-acp",
+  "grok-build-cli",
+  "opencode-cli",
+] 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", "opencodeGeneration", "opencodeUnsafeTools",
+  "approvalPolicy", "sandboxMode", "skipGitRepoCheck", "copresenceFullAccess", "modelReasoningEffort",
+  "daemonProvider",
+] 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;
@@ -31,29 +74,85 @@ export const MAX_ENV_VALUE_BYTES = 16 * 1024;
 const ENV_KEY_RE = /^[A-Z][A-Z0-9_]{0,63}$/;
 
 // §4.2.2 name + model.
-const NAME_RE = /^[a-z][a-z0-9_-]{0,63}$/;
-const MODEL_RE = /^[a-zA-Z0-9._:\-]+$/;
+// Board #652 — the name rule lives in ./shared/node-name.ts (byte-identical copy in
+// agent-node/src/shared/, drift-tested). It used to be /^[a-z][a-z0-9_-]{0,63}$/ here.
+// OpenCode 共存的模型带 provider 前缀(`opencode/mimo-v2.5-free`,agent-node parseModelRef 按第一个 `/` 切),
+// 桌面向导 0.2.61 起就发这种形状 —— 允许**恰好一个**斜杠分隔的两段;每段仍是原字符集,且不能是纯点(`..`/`.`)。
+const MODEL_SEGMENT = "[a-zA-Z0-9._:\\-]+";
+const MODEL_RE = new RegExp(`^${MODEL_SEGMENT}(?:/${MODEL_SEGMENT})?$`);
+const MODEL_DOT_ONLY_SEGMENT = /(^|\/)\.+(\/|$)/;
 
-export function validateName(s: unknown): asserts s is string {
-  if (typeof s !== "string" || !NAME_RE.test(s)) {
-    throw new ValidationError("node_name_invalid", { value: typeof s === "string" ? s.slice(0, 80) : typeof s });
+/** Board #652 — returns the normalized (trimmed) name the caller must store and forward. */
+export function validateName(s: unknown): string {
+  const r = checkNodeName(s);
+  if (!r.ok) {
+    throw new ValidationError("node_name_invalid", {
+      value: typeof s === "string" ? s.slice(0, 80) : typeof s,
+      reason: r.error,
+      ...(r.char !== undefined ? { char: r.char } : {}),
+      message: r.message,
+    });
   }
+  return r.name;
 }
 
 export function validateRuntime(s: unknown): asserts s is Runtime {
   if (typeof s !== "string" || !(RUNTIMES as readonly string[]).includes(s)) {
-    throw new ValidationError("runtime_invalid", { value: typeof s === "string" ? s.slice(0, 80) : typeof s });
+    // 🔴 原来只回一个 `runtime_invalid` + 用户传进来的那个值 —— **不说允许哪些,
+    //    也不说还有没有别的路**。2026-08-28 实测:从 Dashboard 建一个
+    //    `codex-app-server` 节点,用户拿到的就是
+    //      {"ok":false,"error":"runtime_invalid","value":"codex-app-server"}
+    //    而目标机器的 daemon 日志里一行都没有(请求根本没到)。
+    //    用户无从知道:①哪些是允许的 ②这个名字是不是打错了 ③有没有别的办法。
+    //
+    // `allowed` 直接由 RUNTIMES 展开,不是手写的第二份清单 ——
+    // 🔴 手写一份会漂移,而漂移之后报错会**理直气壮地告诉用户一组错的名字**。
+    throw new ValidationError("runtime_invalid", {
+      value: typeof s === "string" ? s.slice(0, 80) : typeof s,
+      allowed: [...RUNTIMES],
+      // 这句提示的前提是查过的:`agent-network/src/normalize-runtime.ts` 的
+      // `RuntimeName` / `SUPPORTED_RUNTIME_NAMES` 是 7 个,包含此处不放行的那几个,
+      // 所以「在目标机器上直接建」确实是一条真实存在的路,不是安慰话。
+      hint: "daemon 远程创建目前只放行以上 runtime；其余 runtime 可以在目标机器上直接 `anet node create --runtime <name>` 创建。",
+    });
   }
 }
 
-export function validateModel(s: unknown): asserts s is string {
-  if (typeof s !== "string" || s.length === 0 || s.length > 100 || !MODEL_RE.test(s)) {
+export function validateModel(s: unknown): asserts s is string | undefined | null {
+  if (s === undefined || s === null) return;
+  if (typeof s !== "string" || s.length === 0 || s.length > 100 || !MODEL_RE.test(s) || MODEL_DOT_ONLY_SEGMENT.test(s)) {
     throw new ValidationError("model_invalid", { value: typeof s === "string" ? s.slice(0, 80) : typeof s });
   }
 }
 
+/**
+ * #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 'daemonProvider':
+      if (!validProviderInitialization(v)) throw new ValidationError('flag_value_invalid', { field: k });
+      return;
+    case "opencodeGeneration":
+      if (v !== "v1" && v !== "v2") throw new ValidationError("flag_value_invalid", { field: k, reason: "must be v1 or v2" });
+      return;
+    case "opencodeUnsafeTools":
+      if (typeof v !== "boolean") throw new ValidationError("flag_value_invalid", { field: k, reason: "must be boolean" });
+      return;
     case "permissionMode":
       if (typeof v !== "string" || !(PERMISSION_MODES as readonly string[]).includes(v)) {
         throw new ValidationError("flag_value_invalid", { field: k, reason: "must be one of default/acceptEdits/plan/bypassPermissions" });
@@ -73,15 +172,82 @@ 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:
+      if (CODEX_CONFIG_ONLY_FLAG_KEYS.has(k)) {
+        const fail = validateCodexConfigFlag(k, v, null);
+        if (fail) throw new ValidationError("flag_value_invalid", { field: k, reason: fail.reason });
+        return;
+      }
       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) return;
+  if (flags.daemonProvider !== undefined && (runtime !== 'codex-app-server' || flags.copresence !== true)) {
+    throw new ValidationError('flag_not_applicable_to_runtime', { field: 'daemonProvider', runtime, applicable: ['codex-app-server copresence'] });
+  }
+  // Strict flags envelope: old Hub/daemon reject these keys rather than dropping
+  // unknown node_spec fields. Opt-in must be explicit on this create request.
+  for (const field of ["opencodeGeneration", "opencodeUnsafeTools"]) {
+    if (!Object.prototype.hasOwnProperty.call(flags, field)) continue;
+    validateFlagValue(field, flags[field]);
+    if (runtime !== "opencode-cli") throw new ValidationError("flag_not_applicable_to_runtime", { field, runtime, applicable: ["opencode-cli"] });
+  }
+  if (Object.prototype.hasOwnProperty.call(flags, "opencodeUnsafeTools") && flags.opencodeGeneration !== "v2") {
+    throw new ValidationError("opencode_unsafe_requires_v2", { reason: "opencodeUnsafeTools requires explicit opencodeGeneration=v2" });
+  }
+  if (flags.opencodeGeneration === "v2" && flags.opencodeUnsafeTools !== true) {
+    throw new ValidationError("opencode_v2_requires_unsafe_opt_in", { reason: "V2 preview enables every local tool; trusted tasks only. Explicit opencodeUnsafeTools=true required." });
+  }
+  if (Object.prototype.hasOwnProperty.call(flags, "copresence") && !(COPRESENCE_FLAG_RUNTIMES as readonly string[]).includes(runtime)) {
+    throw new ValidationError("flag_not_applicable_to_runtime", {
+      field: "copresence", runtime, applicable: [...COPRESENCE_FLAG_RUNTIMES],
+    });
+  }
+  for (const [k, v] of Object.entries(flags)) {
+    if (!CODEX_CONFIG_ONLY_FLAG_KEYS.has(k)) continue;
+    const fail = validateCodexConfigFlag(k, v, runtime);
+    if (fail) throw new ValidationError("flag_value_invalid", { field: k, reason: fail.reason });
+  }
+}
+
+/**
+ * V2 co-presence start requires OpenCode's own `provider/model`.
+ * Call only after the unsafe-opt-in check: a missing opt-in stays
+ * `opencode_v2_requires_unsafe_opt_in`. This API does not take an anet
+ * provider preset or a vault key (#2565 owns presets).
+ */
+export function validateOpenCodeV2ProviderModel(
+  runtime: string,
+  model: unknown,
+  flags: Record<string, unknown> | undefined | null,
+): void {
+  if (runtime !== "opencode-cli" || !flags || typeof flags !== "object") return;
+  if (flags.opencodeGeneration !== "v2" || flags.opencodeUnsafeTools !== true) return;
+  const native = typeof model === "string"
+    && model.length > 0
+    && model.length <= 100
+    && MODEL_RE.test(model)
+    && !MODEL_DOT_ONLY_SEGMENT.test(model)
+    && model.includes("/")
+    && model.indexOf("/") === model.lastIndexOf("/");
+  if (!native) {
+    throw new ValidationError("opencode_v2_requires_provider_model", {
+      reason: "OpenCode V2 uses the installed OpenCode provider/model (exactly one slash, for example provider/model). This API does not take an anet provider preset.",
+    });
+  }
+}
+
 // §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
@@ -144,7 +310,7 @@ export function validateEnvRefs(
   return out;
 }
 
-// §4.4.7 — safe serializer for .env.local. Dotenv-quoted with escape
+// §4.4.7 — safe serializer for the node secrets.env file. Dotenv-quoted with escape
 // for backslash / double-quote / newline / carriage-return so that a
 // value containing `\n"evil=KEY2"` cannot pollute the next line.
 export function serializeEnvLocal(env: Record<string, string>): string {
@@ -158,6 +324,40 @@ export function serializeEnvLocal(env: Record<string, string>): string {
   }).join("\n") + "\n";
 }
 
+// app「新建节点」工作目录 —— hub 只判**形状**(daemon 才知道那台机器的 $HOME、系统目录、
+// 目录里住没住别的节点,那几条在 agent-node/src/runtime/child-workdir.ts)。
+// 这里挡的是「根本不像一条路径」的输入,让它在派发前就失败,而不是占一个请求行再被 daemon 拒。
+export const MAX_WORKDIR_LEN = 1024;
+export function validateWorkdir(s: unknown): asserts s is string | undefined | null {
+  if (s === undefined || s === null) return;
+  if (typeof s !== "string") throw new ValidationError("workdir_invalid", { reason: "must be string" });
+  const v = s.trim();
+  if (v.length === 0 || v.length > MAX_WORKDIR_LEN) {
+    throw new ValidationError("workdir_invalid", { reason: `length 1..${MAX_WORKDIR_LEN}` });
+  }
+  if (/[\u0000-\u001f\u007f]/.test(v)) throw new ValidationError("workdir_invalid", { reason: "control character" });
+  const shapeOk = v.startsWith("/") || v === "~" || v.startsWith("~/") || /^[A-Za-z]:[\\/]/.test(v);
+  if (!shapeOk) {
+    throw new ValidationError("workdir_invalid", { reason: "must be absolute (/…, ~/…, or C:\\…)", value: v.slice(0, 80) });
+  }
+}
+
+/** daemon 自报的默认工作目录根(`daemon_capabilities.default_workdir_root`),消毒后返回;
+ *  没报 / 形状不对 = null。**非 null 即表示该 daemon 认 `node_spec.workdir`** ——
+ *  create_node 的「老 daemon 不收 workdir」门和 /api/host-supervisors 的透出共用这一个判据。 */
+export function daemonDefaultWorkdirRoot(configSnapshot: unknown): string | null {
+  try {
+    const snap = typeof configSnapshot === "string" ? JSON.parse(configSnapshot) : configSnapshot;
+    const v = (snap as any)?.daemon_capabilities?.default_workdir_root;
+    if (typeof v !== "string" || v.length === 0 || v.length > MAX_WORKDIR_LEN) return null;
+    if (/[\u0000-\u001f\u007f]/.test(v)) return null;
+    if (!(v.startsWith("/") || /^[A-Za-z]:[\\/]/.test(v))) return null;
+    return v;
+  } catch {
+    return null;
+  }
+}
+
 // §4.2.5 — channels fail-closed in P1.
 export function validateChannelsP1(channels: unknown): void {
   if (channels === undefined || channels === null) return;
@@ -173,7 +373,7 @@ export function validateChannelsP1(channels: unknown): void {
 export interface NodeSpec {
   name: string;
   runtime: Runtime;
-  model: string;
+  model?: string | null;
   flags?: Record<string, unknown>;
   channels?: unknown;
 }
@@ -187,20 +387,32 @@ function kebab(k: string): string {
 // shell, no string concat). Each value has already passed type/enum
 // validation, so String() coercion is safe.
 export function buildAnetArgs(spec: NodeSpec): string[] {
+  for (const field of ["opencodeGeneration", "opencodeUnsafeTools"]) {
+    if (Object.prototype.hasOwnProperty.call(spec, field)) throw new ValidationError("flag_location_invalid", { field, reason: "use node_spec.flags" });
+  }
   validateName(spec.name);
   validateRuntime(spec.runtime);
   validateModel(spec.model);
   validateChannelsP1(spec.channels);
+  if (spec.flags?.daemonProvider !== undefined && (!validProviderInitialization(spec.flags.daemonProvider)
+    || spec.model !== spec.flags.daemonProvider.model)) throw new ValidationError('provider_create_model_mismatch');
 
-  const args: string[] = ["node", "create", spec.name, "--runtime", spec.runtime, "--model", spec.model];
+  const args: string[] = ["node", "create", spec.name, "--runtime", spec.runtime];
+  if (spec.model) args.push("--model", spec.model);
   if (spec.flags && typeof spec.flags === "object") {
     for (const [k, v] of Object.entries(spec.flags)) {
       if (!(FLAG_KEYS as readonly string[]).includes(k)) {
         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; }
+      if (k === "opencodeUnsafeTools") { if (v === true) args.push("--opencode-unsafe-tools"); continue; }
+      if (CODEX_CONFIG_ONLY_FLAG_KEYS.has(k) || k === 'daemonProvider') continue;
       args.push(`--${kebab(k)}`, String(v));
     }
+    validateFlagsForRuntime(spec.runtime, spec.flags);
   }
+  validateOpenCodeV2ProviderModel(spec.runtime, spec.model, spec.flags);
   return args;
 }