@sleep2agi/commhub-server 0.9.0-preview.1 → 0.9.0-preview.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sleep2agi/commhub-server",
-  "version": "0.9.0-preview.1",
+  "version": "0.9.0-preview.3",
   "description": "CommHub Server \u2014 AI Agent communication hub with MCP protocol, multi-network isolation, user auth, and 17 MCP tools.",
   "type": "module",
   "main": "src/index.ts",
@@ -48,6 +48,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "bun-types": "^1.3.13",
-    "hono": "^4.12.25"
+    "hono": "^4.12.25",
+    "zod": "^4.4.3"
   }
 }

package/src/auth.ts

@@ -211,7 +211,9 @@ export function resolveToken(token: string): { user: AuthUser; networkId: string
     `SELECT t.token_id, t.user_id, t.network_id, t.scope, t.name AS token_name,
             u.username, u.display_name, u.email, u.role
      FROM api_tokens t JOIN users u ON t.user_id = u.user_id
-     WHERE t.token_hash = ?1 AND (t.expires_at IS NULL OR t.expires_at > datetime('now'))`,
+     WHERE t.token_hash = ?1
+       AND (t.expires_at IS NULL OR t.expires_at > datetime('now'))
+       AND t.revoked_at IS NULL`,
     tHash);
 
   if (!row) return null;

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

@@ -16,7 +16,7 @@
 
 import { describe, expect, test, beforeEach } from "bun:test";
 import { db, uuidv4 } from "./db.js";
-import { upsertNodeWithSec1Guard } from "./tools.js";
+import { upsertNodeWithSec1Guard, finalizePendingMatchingUpdates } from "./tools.js";
 
 function insertNode(opts: { node_id?: string; alias: string; network_id: string | null }): string {
   const id = opts.node_id ?? uuidv4();
@@ -445,6 +445,168 @@ describe("SEC trust-root — REAL driver via upsertNodeWithSec1Guard (catches gu
   });
 });
 
+// ─────────────────────────────────────────────────────────────────────
+// finalizePendingMatchingUpdates — Option A restart-finalize matcher
+// (通信牛 #290 final CHANGE_REQ 2026-06-28). Real-driver tests: drive
+// the helper that production report_status delegates to + assert on
+// the persisted state. Same single-source-of-truth pattern as
+// upsertNodeWithSec1Guard (prevents inline-mirror test drift).
+// ─────────────────────────────────────────────────────────────────────
+describe("finalizePendingMatchingUpdates — Option A restart-finalize via content match", () => {
+  function insertPendingUpdate(opts: {
+    update_id?: string;
+    node_id: string;
+    network_id: string;
+    patch: any;
+    apply_mode: "hot" | "restart" | "restart_only";
+    status?: "pending" | "restarting";
+  }): string {
+    const id = opts.update_id ?? `cu_${uuidv4()}`;
+    db.run(
+      `INSERT INTO node_config_updates (update_id, node_id, network_id, patch_json, apply_mode, base_revision, status, created_at, created_by_token) VALUES (?1, ?2, ?3, ?4, ?5, 0, ?6, ?7, 'test')`,
+      [id, opts.node_id, opts.network_id, JSON.stringify(opts.patch), opts.apply_mode, opts.status ?? "pending", Date.now()],
+    );
+    return id;
+  }
+
+  test("empty patch (restart_only) → finalizes on ANY snapshot (restart itself = goal)", () => {
+    const nid = insertNode({ alias: "n1", network_id: "netA" });
+    const uid = insertPendingUpdate({
+      node_id: nid, network_id: "netA", patch: {}, apply_mode: "restart_only", status: "restarting",
+    });
+    const r = finalizePendingMatchingUpdates(nid, { model: "any", flags: {} });
+    expect(r.finalizedCount).toBe(1);
+    expect(r.finalizedIds).toContain(uid);
+    const row = db.get<any>("SELECT status, new_revision FROM node_config_updates WHERE update_id = ?1", uid);
+    expect(row.status).toBe("applied");
+    expect(row.new_revision).toBe(1);
+    const node = db.get<any>("SELECT config_revision FROM nodes WHERE node_id = ?1", nid);
+    expect(node.config_revision).toBe(1);
+  });
+
+  test("model patch + snapshot.model matches → finalized", () => {
+    const nid = insertNode({ alias: "n2", network_id: "netA" });
+    const uid = insertPendingUpdate({
+      node_id: nid, network_id: "netA",
+      patch: { model: "claude-opus-4-new", flags: {} },
+      apply_mode: "restart",
+    });
+    const r = finalizePendingMatchingUpdates(nid, {
+      model: "claude-opus-4-new", flags: { maxTurns: 50 },
+    });
+    expect(r.finalizedCount).toBe(1);
+    expect(db.get<any>("SELECT status FROM node_config_updates WHERE update_id = ?1", uid).status).toBe("applied");
+  });
+
+  test("model patch + snapshot.model DIFFERENT → NOT finalized (left pending)", () => {
+    const nid = insertNode({ alias: "n3", network_id: "netA" });
+    const uid = insertPendingUpdate({
+      node_id: nid, network_id: "netA",
+      patch: { model: "claude-opus-4-new", flags: {} },
+      apply_mode: "restart",
+    });
+    const r = finalizePendingMatchingUpdates(nid, {
+      model: "claude-sonnet-3-old", flags: {},
+    });
+    expect(r.finalizedCount).toBe(0);
+    expect(db.get<any>("SELECT status FROM node_config_updates WHERE update_id = ?1", uid).status).toBe("pending");
+  });
+
+  test("flags patch + every flag matches snapshot → finalized", () => {
+    const nid = insertNode({ alias: "n4", network_id: "netA" });
+    const uid = insertPendingUpdate({
+      node_id: nid, network_id: "netA",
+      patch: { flags: { maxTurns: 99, budget: 500 } },
+      apply_mode: "hot",
+    });
+    const r = finalizePendingMatchingUpdates(nid, {
+      flags: { maxTurns: 99, budget: 500, dangerouslySkipPermissions: true },
+    });
+    expect(r.finalizedCount).toBe(1);
+    expect(db.get<any>("SELECT status FROM node_config_updates WHERE update_id = ?1", uid).status).toBe("applied");
+  });
+
+  test("flags patch + ONE flag mismatch → NOT finalized (any field absent = no match)", () => {
+    const nid = insertNode({ alias: "n5", network_id: "netA" });
+    const uid = insertPendingUpdate({
+      node_id: nid, network_id: "netA",
+      patch: { flags: { maxTurns: 99, budget: 500 } },
+      apply_mode: "hot",
+    });
+    const r = finalizePendingMatchingUpdates(nid, {
+      flags: { maxTurns: 99, budget: 999 },  // budget wrong
+    });
+    expect(r.finalizedCount).toBe(0);
+    expect(db.get<any>("SELECT status FROM node_config_updates WHERE update_id = ?1", uid).status).toBe("pending");
+  });
+
+  test("flags patch + flag absent from snapshot → NOT finalized", () => {
+    const nid = insertNode({ alias: "n6", network_id: "netA" });
+    const uid = insertPendingUpdate({
+      node_id: nid, network_id: "netA",
+      patch: { flags: { permissionMode: "auto" } },
+      apply_mode: "restart",
+    });
+    const r = finalizePendingMatchingUpdates(nid, {
+      flags: { maxTurns: 50 },  // permissionMode missing entirely
+    });
+    expect(r.finalizedCount).toBe(0);
+    expect(db.get<any>("SELECT status FROM node_config_updates WHERE update_id = ?1", uid).status).toBe("pending");
+  });
+
+  test("no pending update → no-op (idempotent on routine heartbeats)", () => {
+    const nid = insertNode({ alias: "n7", network_id: "netA" });
+    const r = finalizePendingMatchingUpdates(nid, { model: "x", flags: { maxTurns: 50 } });
+    expect(r.finalizedCount).toBe(0);
+  });
+
+  test("restarting status finalizes too (not just pending)", () => {
+    const nid = insertNode({ alias: "n8", network_id: "netA" });
+    const uid = insertPendingUpdate({
+      node_id: nid, network_id: "netA",
+      patch: { model: "new" },
+      apply_mode: "restart",
+      status: "restarting",
+    });
+    const r = finalizePendingMatchingUpdates(nid, { model: "new", flags: {} });
+    expect(r.finalizedCount).toBe(1);
+    expect(db.get<any>("SELECT status FROM node_config_updates WHERE update_id = ?1", uid).status).toBe("applied");
+  });
+
+  test("two nodes with separate pending updates → finalize only matching one", () => {
+    const nidA = insertNode({ alias: "match-this", network_id: "netA" });
+    const nidB = insertNode({ alias: "leave-alone", network_id: "netA" });
+    const uidA = insertPendingUpdate({
+      node_id: nidA, network_id: "netA",
+      patch: { model: "matched-model" },
+      apply_mode: "restart",
+    });
+    const uidB = insertPendingUpdate({
+      node_id: nidB, network_id: "netA",
+      patch: { model: "different-model" },
+      apply_mode: "restart",
+    });
+    finalizePendingMatchingUpdates(nidA, { model: "matched-model", flags: {} });
+    expect(db.get<any>("SELECT status FROM node_config_updates WHERE update_id = ?1", uidA).status).toBe("applied");
+    expect(db.get<any>("SELECT status FROM node_config_updates WHERE update_id = ?1", uidB).status).toBe("pending");
+  });
+
+  test("config_revision bumps to base+1 for single finalize (multi-pending blocked by F-C index)", () => {
+    // F-C partial unique index (db.ts) prevents two non-terminal updates
+    // for the same node, so the multi-finalize scenario is unreachable
+    // at the DB layer. This test pins that ONE pending finalize → revision = base + 1.
+    const nid = insertNode({ alias: "n10", network_id: "netA" });
+    insertPendingUpdate({
+      node_id: nid, network_id: "netA",
+      patch: { model: "v1" },
+      apply_mode: "restart",
+    });
+    const r = finalizePendingMatchingUpdates(nid, { model: "v1", flags: {} });
+    expect(r.finalizedCount).toBe(1);
+    expect(db.get<any>("SELECT config_revision FROM nodes WHERE node_id = ?1", nid).config_revision).toBe(1);
+  });
+});
+
 describe("F-B polish — reaper anchors on COALESCE(acked_at, created_at), not created_at", () => {
   // 通信龙 catch: reaper threshold = 60s and drain hard-cap = 60s overlap.
   // A healthy-but-slow restart (drain 60s + respawn time) could exceed

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

@@ -0,0 +1,187 @@
+import { describe, expect, test } from "bun:test";
+import {
+  ValidationError,
+  validateName, validateRuntime, validateModel, validateFlagValue,
+  validateEnvRefs, validateChannelsP1, serializeEnvLocal, buildAnetArgs,
+  MAX_ENV_KEYS_PER_NODE,
+} 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"]) {
+      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)]) {
+      expect(() => validateName(n)).toThrow(ValidationError);
+    }
+  });
+});
+
+describe("validateRuntime / validateModel (§4.2.2)", () => {
+  test("runtime enum", () => {
+    expect(() => validateRuntime("claude-agent-sdk")).not.toThrow();
+    expect(() => validateRuntime("bash")).toThrow(ValidationError);
+    expect(() => validateRuntime("")).toThrow(ValidationError);
+  });
+  test("model with dots, colons, dashes OK; bad chars rejected", () => {
+    expect(() => validateModel("claude-opus-4.6")).not.toThrow();
+    expect(() => validateModel("claude-opus-4-6")).not.toThrow();
+    expect(() => validateModel("vendor:model")).not.toThrow();
+    expect(() => validateModel("gpt-4o")).not.toThrow();
+    expect(() => validateModel("bad model")).toThrow(ValidationError);
+    expect(() => validateModel("x;rm")).toThrow(ValidationError);
+    expect(() => validateModel("")).toThrow(ValidationError);
+  });
+});
+
+describe("validateFlagValue (§4.2.2)", () => {
+  test("budget decimal allowed", () => {
+    expect(() => validateFlagValue("budget", 5.5)).not.toThrow();
+    expect(() => validateFlagValue("budget", 0)).not.toThrow();
+    expect(() => validateFlagValue("budget", 1001)).toThrow(ValidationError);
+    expect(() => validateFlagValue("budget", -1)).toThrow(ValidationError);
+  });
+  test("maxTurns integer 1..9999", () => {
+    expect(() => validateFlagValue("maxTurns", 50)).not.toThrow();
+    expect(() => validateFlagValue("maxTurns", 5.5)).toThrow(ValidationError);
+    expect(() => validateFlagValue("maxTurns", 0)).toThrow(ValidationError);
+    expect(() => validateFlagValue("maxTurns", "DROP TABLE")).toThrow(ValidationError);
+  });
+  test("dangerouslySkipPermissions boolean", () => {
+    expect(() => validateFlagValue("dangerouslySkipPermissions", true)).not.toThrow();
+    expect(() => validateFlagValue("dangerouslySkipPermissions", "true")).toThrow(ValidationError);
+  });
+  test("permissionMode enum", () => {
+    expect(() => validateFlagValue("permissionMode", "plan")).not.toThrow();
+    expect(() => validateFlagValue("permissionMode", "anything-else")).toThrow(ValidationError);
+  });
+});
+
+describe("validateEnvRefs (§4.4.7 + B1 G7/G8 sub-cases)", () => {
+  test("good keys resolve", () => {
+    const env = validateEnvRefs(["ANTHROPIC_API_KEY"], {
+      callerNetworkId: "n", daemonAllowList: allow("ANTHROPIC_API_KEY"),
+      networkSecretsGet: (n, k) => okSecret("ANTHROPIC_API_KEY", n, k),
+    });
+    expect(env).toEqual({ ANTHROPIC_API_KEY: "value-of-ANTHROPIC_API_KEY" });
+  });
+  test("G7: PATH rejected (exact denylist)", () => {
+    expect(() => validateEnvRefs(["PATH"], {
+      callerNetworkId: "n", daemonAllowList: allow("PATH"),
+      networkSecretsGet: () => "evil:/tmp/bin",
+    })).toThrow(ValidationError);
+  });
+  test("G8: LD_PRELOAD / DYLD_* / BUN_* / NPM_* / NODE_OPTIONS rejected (prefix)", () => {
+    for (const k of ["LD_PRELOAD", "DYLD_INSERT_LIBRARIES", "BUN_INSTALL", "NPM_TOKEN", "NPM_CONFIG_REGISTRY", "NODE_PATH", "NODE_OPTIONS"]) {
+      expect(() => validateEnvRefs([k], {
+        callerNetworkId: "n", daemonAllowList: new Set([k]),
+        networkSecretsGet: () => "x",
+      })).toThrow(ValidationError);
+    }
+  });
+  test("G1 bad regex (lowercase / digit-first / too long)", () => {
+    for (const k of ["path", "1KEY", "_KEY", "a".repeat(65)]) {
+      expect(() => validateEnvRefs([k], {
+        callerNetworkId: "n", daemonAllowList: new Set([k]), networkSecretsGet: () => "x",
+      })).toThrow(ValidationError);
+    }
+  });
+  test("G2 duplicate", () => {
+    expect(() => validateEnvRefs(["A_KEY", "A_KEY"], {
+      callerNetworkId: "n", daemonAllowList: new Set(["A_KEY"]), networkSecretsGet: () => "x",
+    })).toThrow(ValidationError);
+  });
+  test("G3 over max count", () => {
+    const refs = Array.from({ length: MAX_ENV_KEYS_PER_NODE + 1 }, (_, i) => `KEY_${i}`);
+    const allowAll = new Set(refs);
+    expect(() => validateEnvRefs(refs, {
+      callerNetworkId: "n", daemonAllowList: allowAll, networkSecretsGet: () => "x",
+    })).toThrow(ValidationError);
+  });
+  test("G4 not in vault", () => {
+    expect(() => validateEnvRefs(["ANTHROPIC_API_KEY"], {
+      callerNetworkId: "n", daemonAllowList: allow("ANTHROPIC_API_KEY"),
+      networkSecretsGet: () => undefined,
+    })).toThrow(ValidationError);
+  });
+  test("G5 not in daemon allowlist", () => {
+    expect(() => validateEnvRefs(["OPENAI_API_KEY"], {
+      callerNetworkId: "n", daemonAllowList: new Set(["ANTHROPIC_API_KEY"]),
+      networkSecretsGet: () => "x",
+    })).toThrow(ValidationError);
+  });
+  test("undefined/empty refs is OK (no env at all)", () => {
+    expect(validateEnvRefs(undefined, { callerNetworkId: "n", daemonAllowList: new Set(), networkSecretsGet: () => undefined })).toEqual({});
+    expect(validateEnvRefs([], { callerNetworkId: "n", daemonAllowList: new Set(), networkSecretsGet: () => undefined })).toEqual({});
+  });
+});
+
+describe("serializeEnvLocal (§4.4.7 G6 — safe escape)", () => {
+  test("newline in secret value escapes to literal \\n, no line pollution", () => {
+    const out = serializeEnvLocal({ KEY: 'foo\nevil="KEY2"' });
+    // The \n must be the 2-char literal `\n` in the file, NOT an actual
+    // newline. There must be NO bare `evil=` token on its own line.
+    expect(out).toBe('KEY="foo\\nevil=\\"KEY2\\""\n');
+    expect(out.split("\n").length).toBe(2);  // 1 data line + trailing empty
+  });
+  test("backslash escaped first (so subsequent escapes survive)", () => {
+    expect(serializeEnvLocal({ KEY: "a\\b" })).toBe('KEY="a\\\\b"\n');
+  });
+  test("multi-key", () => {
+    expect(serializeEnvLocal({ A: "x", B: "y" })).toBe('A="x"\nB="y"\n');
+  });
+});
+
+describe("validateChannelsP1 (§4.2.5 C5)", () => {
+  test("empty / omitted OK", () => {
+    expect(() => validateChannelsP1([])).not.toThrow();
+    expect(() => validateChannelsP1(undefined)).not.toThrow();
+    expect(() => validateChannelsP1(null)).not.toThrow();
+  });
+  test("non-empty rejected (any element)", () => {
+    expect(() => validateChannelsP1(["telegram"])).toThrow(ValidationError);
+    expect(() => validateChannelsP1([null])).toThrow(ValidationError);
+    expect(() => validateChannelsP1([{}])).toThrow(ValidationError);
+  });
+  test("not-an-array rejected", () => {
+    expect(() => validateChannelsP1("telegram")).toThrow(ValidationError);
+  });
+});
+
+describe("buildAnetArgs (§4.2.2 F2 — fully validated argv)", () => {
+  test("happy path", () => {
+    const args = buildAnetArgs({
+      name: "demo-bot", runtime: "claude-agent-sdk", model: "claude-opus-4-6",
+      flags: { maxTurns: 50, budget: 5 },
+    });
+    expect(args).toEqual(["node", "create", "demo-bot", "--runtime", "claude-agent-sdk", "--model", "claude-opus-4-6", "--max-turns", "50", "--budget", "5"]);
+  });
+  test("permissionMode kebab-case", () => {
+    const args = buildAnetArgs({
+      name: "x", runtime: "codex-sdk", model: "gpt-4o",
+      flags: { permissionMode: "plan" },
+    });
+    expect(args).toContain("--permission-mode");
+    expect(args[args.indexOf("--permission-mode") + 1]).toBe("plan");
+  });
+  test("rejects bad name with shell metachar", () => {
+    expect(() => buildAnetArgs({ name: ";rm -rf /", runtime: "claude-agent-sdk", model: "x" })).toThrow(ValidationError);
+  });
+  test("rejects bad flag key", () => {
+    expect(() => buildAnetArgs({
+      name: "x", runtime: "claude-agent-sdk", model: "x",
+      flags: { evilKey: 1 } as any,
+    })).toThrow(ValidationError);
+  });
+  test("rejects channels at build time too (E end-to-end injection)", () => {
+    expect(() => buildAnetArgs({
+      name: "x", runtime: "claude-agent-sdk", model: "x",
+      channels: ["telegram"],
+    } as any)).toThrow(ValidationError);
+  });
+});

package/src/create-node-validate.ts

@@ -0,0 +1,206 @@
+// RFC-026 v4 §4.2.2 (F2 structured) + §4.4.7 (C1+B1 env_refs) + §4.2.6
+// (B2 fork wrapper) — pure validators + arg builder. No DB access. Used
+// by hub create_node MCP tool (RPC entry) AND by daemon get_create_request
+// (re-check, defense in depth).
+//
+// All validation errors throw ValidationError with a stable `code` field
+// that the MCP tool surface maps to a JSON {ok:false, error: <code>}
+// payload (RFC §4.6).
+
+import { isReservedEnvKey } from "./shared/reserved-env.js";
+
+export class ValidationError extends Error {
+  constructor(public code: string, public detail?: Record<string, unknown>) {
+    super(`${code}${detail ? ` ${JSON.stringify(detail)}` : ""}`);
+    this.name = "ValidationError";
+  }
+}
+
+// §4.2.2 — structural enums.
+export const RUNTIMES = ["claude-agent-sdk", "codex-sdk", "grok-build-acp"] as const;
+export type Runtime = typeof RUNTIMES[number];
+
+export const FLAG_KEYS = ["permissionMode", "dangerouslySkipPermissions", "maxTurns", "budget", "timeout"] as const;
+export type FlagKey = typeof FLAG_KEYS[number];
+
+export const PERMISSION_MODES = ["default", "acceptEdits", "plan", "bypassPermissions"] as const;
+
+// §4.4.7 — env_refs limits.
+export const MAX_ENV_KEYS_PER_NODE = 32;
+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._:\-]+$/;
+
+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 });
+  }
+}
+
+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 });
+  }
+}
+
+export function validateModel(s: unknown): asserts s is string {
+  if (typeof s !== "string" || s.length === 0 || s.length > 100 || !MODEL_RE.test(s)) {
+    throw new ValidationError("model_invalid", { value: typeof s === "string" ? s.slice(0, 80) : typeof s });
+  }
+}
+
+export function validateFlagValue(k: string, v: unknown): void {
+  switch (k) {
+    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" });
+      }
+      return;
+    case "dangerouslySkipPermissions":
+      if (typeof v !== "boolean") throw new ValidationError("flag_value_invalid", { field: k, reason: "must be boolean" });
+      return;
+    case "maxTurns":
+      if (!Number.isInteger(v) || (v as number) < 1 || (v as number) > 9999) {
+        throw new ValidationError("flag_value_invalid", { field: k, reason: "must be integer 1..9999" });
+      }
+      return;
+    case "budget":
+      if (typeof v !== "number" || !Number.isFinite(v) || (v as number) < 0 || (v as number) > 1000) {
+        throw new ValidationError("flag_value_invalid", { field: k, reason: "must be number 0..1000 (decimals OK)" });
+      }
+      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" });
+      }
+      return;
+    default:
+      throw new ValidationError("flag_key_unknown", { field: k });
+  }
+}
+
+// §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
+// resolved-but-not-yet-used map keyed by env-key so the caller can build
+// env_blob without re-querying.
+export interface EnvRefsContext {
+  callerNetworkId: string;
+  daemonAllowList: ReadonlySet<string>;
+  networkSecretsGet: (networkId: string, key: string) => string | undefined;
+}
+export function validateEnvRefs(
+  refs: unknown,
+  ctx: EnvRefsContext,
+): Record<string, string> {
+  if (!Array.isArray(refs)) {
+    if (refs === undefined || refs === null) return {};
+    throw new ValidationError("env_refs_invalid", { reason: "must be array" });
+  }
+  // ① regex
+  for (const k of refs) {
+    if (typeof k !== "string" || !ENV_KEY_RE.test(k)) {
+      throw new ValidationError("env_key_invalid", { key: typeof k === "string" ? k.slice(0, 64) : typeof k });
+    }
+  }
+  // ② reserved denylist (v4 B1)
+  for (const k of refs) {
+    if (isReservedEnvKey(k)) {
+      throw new ValidationError("env_key_reserved", { key: k });
+    }
+  }
+  // ③ duplicate detection (must come before ④ count gate to give a
+  //    truthful error code rather than "too many" for dup-spam).
+  const seen = new Set<string>();
+  for (const k of refs as string[]) {
+    if (seen.has(k)) throw new ValidationError("env_key_duplicate", { key: k });
+    seen.add(k);
+  }
+  // ④ count cap
+  if (seen.size > MAX_ENV_KEYS_PER_NODE) {
+    throw new ValidationError("env_key_too_many", { count: seen.size, max: MAX_ENV_KEYS_PER_NODE });
+  }
+  const out: Record<string, string> = {};
+  // ⑤ vault presence + ⑥ value size cap
+  for (const k of seen) {
+    const v = ctx.networkSecretsGet(ctx.callerNetworkId, k);
+    if (v === undefined) throw new ValidationError("secret_not_in_vault", { key: k });
+    if (Buffer.byteLength(v, "utf8") > MAX_ENV_VALUE_BYTES) {
+      throw new ValidationError("secret_too_large", { key: k, max: MAX_ENV_VALUE_BYTES });
+    }
+    out[k] = v;
+  }
+  // ⑦ daemon allowlist (per-host whitelist of which secrets this
+  //    machine is allowed to receive; declared in daemon config by the
+  //    host operator)
+  for (const k of seen) {
+    if (!ctx.daemonAllowList.has(k)) {
+      throw new ValidationError("secret_not_in_daemon_allowlist", { key: k });
+    }
+  }
+  return out;
+}
+
+// §4.4.7 — safe serializer for .env.local. 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 {
+  return Object.entries(env).map(([k, v]) => {
+    const esc = String(v)
+      .replace(/\\/g, "\\\\")   // 1) backslashes first (or later escapes get un-escaped)
+      .replace(/"/g, '\\"')     // 2) double-quotes
+      .replace(/\n/g, "\\n")    // 3) newline → literal \n
+      .replace(/\r/g, "\\r");   // 4) carriage return → literal \r
+    return `${k}="${esc}"`;
+  }).join("\n") + "\n";
+}
+
+// §4.2.5 — channels fail-closed in P1.
+export function validateChannelsP1(channels: unknown): void {
+  if (channels === undefined || channels === null) return;
+  if (!Array.isArray(channels)) {
+    throw new ValidationError("channels_not_supported_in_p1", { reason: "expected array or omitted" });
+  }
+  if (channels.length > 0) {
+    throw new ValidationError("channels_not_supported_in_p1", { received: channels.length, p3_tracker: "RFC-026 §5 P3" });
+  }
+}
+
+// §4.2.2 — fully validated NodeSpec, ready to feed into buildAnetArgs.
+export interface NodeSpec {
+  name: string;
+  runtime: Runtime;
+  model: string;
+  flags?: Record<string, unknown>;
+  channels?: unknown;
+}
+
+// kebab-case helper for flag names. permissionMode → permission-mode.
+function kebab(k: string): string {
+  return k.replace(/([A-Z])/g, "-$1").toLowerCase();
+}
+
+// §4.2.2 — build the argv that gets fed verbatim to execFile (no
+// shell, no string concat). Each value has already passed type/enum
+// validation, so String() coercion is safe.
+export function buildAnetArgs(spec: NodeSpec): string[] {
+  validateName(spec.name);
+  validateRuntime(spec.runtime);
+  validateModel(spec.model);
+  validateChannelsP1(spec.channels);
+
+  const args: string[] = ["node", "create", spec.name, "--runtime", spec.runtime, "--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);
+      args.push(`--${kebab(k)}`, String(v));
+    }
+  }
+  return args;
+}