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

package/src/tools.ts

@@ -1,8 +1,48 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod/v4";
-import { db, uuidv4, logTaskEvent, chainReplyToParent } from "./db.js";
+import { db, uuidv4, logTaskEvent, chainReplyToParent, hashToken, generateId, generateNetworkToken } from "./db.js";
 import { pushEvent } from "./push.js";
-import { getUserNetworkRole } from "./auth.js";
+import { assertNodeActive } from "./lifecycle-guard.js";
+import { getUserNetworkRole, createNetworkTokenForNode } from "./auth.js";
+import {
+  buildAnetArgs as _unused_buildAnetArgs,           // ensure module is loaded
+  validateName as validateChildName,
+  validateRuntime,
+  validateModel,
+  validateChannelsP1,
+  validateEnvRefs,
+  FLAG_KEYS,
+  validateFlagValue,
+  ValidationError,
+} from "./create-node-validate.js";
+import {
+  putPendingEnvBlob,
+  takePendingEnvBlob,
+  newRequestId,
+  finalizeCreateOnFirstRegister,
+  startPendingEnvGcTimer,
+  startSweeperTimer,
+  auditCreateNode,
+  auditCreateNodeStrict,
+  resolveCallerDaemonTokenBound as _resolveCallerDaemonTokenBound,
+} from "./create-node.js";
+import {
+  vaultUpsert, vaultGet, vaultListKeys, vaultDelete,
+  VaultError,
+} from "./vault.js";
+import { stripHostLocalPathsForCrossHostSafe } from "./uploads.js";
+import {
+  validateBaseUrl as _validateBaseUrl,
+  SUPPORTED_VENDORS,
+  ProbeValidationError,
+} from "./probe-validate.js";
+import {
+  putPendingProbeSecret,
+  newProbeId,
+  finalizeProbeAck,
+  startPendingProbeGcTimer,
+  startProbeSweeperTimer,
+} from "./probe.js";
 import { canonicalAliasExists, cleanupRenamedAliasSession, resolveCanonicalAlias } from "./rename.js";
 import {
   ALLOWED_FLAGS,
@@ -24,7 +64,12 @@ function parseMetaJson(value: unknown): unknown | null {
 
 function normalizeMetaJson(meta: unknown): string | null {
   if (!meta || typeof meta !== "object") return null;
-  try { return JSON.stringify(meta); } catch { return null; }
+  // #222 cross-host safety — strip `path` from meta.attachments[] when
+  // `file_id` is also present. Shared helper lives in uploads.ts so the
+  // REST handler in index.ts can apply the identical sanitization
+  // (otherwise REST and MCP transports would have different meta_json
+  // shapes for the same send).
+  try { return JSON.stringify(stripHostLocalPathsForCrossHostSafe(meta)); } catch { return null; }
 }
 
 export function registerTools(server: McpServer, clientIP?: string, enforceNetworkId?: string | null, enforceUserId?: string | null, callerAlias?: string | null, callerTokenIsNetwork = false, callerTokenId?: string | null) {
@@ -104,6 +149,14 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
     return { networkId: null, networkIds: getReadableNetworkIds() };
   };
 
+  // RFC-027 §2.3 race-free invariant — assertNodeActive lives in
+  // server/src/lifecycle-guard.ts so REST handlers in server/src/index.ts
+  // can use the SAME code path. PR1.1 had it inline here; PR1.2a
+  // (#346 review catch) extracted because the closure scope made it
+  // unreachable from REST and left the §2.3 race open on dashboard
+  // Dispatch (POST /api/task + /api/broadcast). Per
+  // [[feedback_grep_all_sites_before_apply_guard]].
+
   const addReadScope = (sql: string, params: any[], scope: ReadScope, column = "network_id"): string => {
     if (scope.networkId) {
       sql += ` AND ${column} = ?${params.length + 1}`;
@@ -257,6 +310,21 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         flags: z.record(z.unknown()).optional(),
         config_revision: z.number().int().min(0).optional(),
         config_update_capable: z.boolean().optional(),
+        // RFC-026 P2 / #338 — daemon role surfaced for hub /api/nodes
+        // discovery (#337 extracts this field). "host_supervisor" =
+        // anet daemon. Default-stripping zod would drop this otherwise.
+        role: z.string().max(64).optional().nullable(),
+        // RFC-026 §9.3 / #338 PR3 — daemon self-declare nested under
+        // `daemon_capabilities` (canonical shape per existing hub reads
+        // at tools.ts:2010/2075 — PR1/PR2 placed these top-level, hub
+        // never saw them, max_concurrent_children stayed default + the
+        // allowlists stayed unenforced. PR3 nit ① per 通信龙).
+        // Soft caps avoid abuse via attacker daemon.
+        daemon_capabilities: z.object({
+          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(),
+        }).optional(),
       }).optional().describe("RFC-024 — masked node config snapshot"),
     },
     async ({ resume_id, alias, status, task, output, score, progress, server: srv, hostname: hn, agent: ag, project_dir: pd, version: ver, tmux_name: tmux, node_id, session_id, config_path, channels, model: mdl, node_name: nn, network_id: netId, host, process_telemetry: proc, config_snapshot: cfgSnap }) => {
@@ -815,6 +883,12 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         return { content: [{ type: "text" as const, text: JSON.stringify(payload) }] };
       }
 
+      // RFC-027 §2.3 inbox-enqueue lifecycle guard (PR1.1 site 1/6).
+      {
+        const lc = assertNodeActive(targetAlias, effectiveNetId ?? null);
+        if (!lc.ok) return { content: [{ type: "text" as const, text: JSON.stringify(lc) }] };
+      }
+
       console.log(`[${ts()}] ${from_session} → send_task → ${targetAlias}: ${task.slice(0, 60)}${priority === "high" ? " [HIGH]" : ""}${canonical.renamed ? ` [renamed from ${alias}]` : ""}`);
       const id = uuidv4();
       const fromNodeId = resolveNodeIdForAlias(from_session, effectiveNetId);
@@ -910,6 +984,11 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       const targetAlias = canonical.alias;
       const target = resolveDeliveryTarget(targetAlias, effectiveNetId);
       if (target.state === "not_found") return deliveryTargetReply(target)!;
+      // RFC-027 §2.3 inbox-enqueue lifecycle guard (PR1.1 site 2/6).
+      {
+        const lc = assertNodeActive(targetAlias, effectiveNetId ?? null);
+        if (!lc.ok) return { content: [{ type: "text" as const, text: JSON.stringify(lc) }] };
+      }
       console.log(`[${ts()}] ${from_session} → send_message → ${targetAlias}: ${message.slice(0, 60)}${canonical.renamed ? ` [renamed from ${alias}]` : ""}`);
       const id = uuidv4();
       db.run(
@@ -1001,6 +1080,11 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
         }
       }
       const replyTargetNodeId = resolveNodeIdForAlias(alias, effectiveNetId);
+      // RFC-027 §2.3 inbox-enqueue lifecycle guard (PR1.1 site 3/6).
+      {
+        const lc = assertNodeActive(alias, effectiveNetId ?? null);
+        if (!lc.ok) return { content: [{ type: "text" as const, text: JSON.stringify(lc) }] };
+      }
       const replyLogged = db.transaction(() => {
         db.run(
           `INSERT INTO inbox (id, session_name, node_id, type, priority, content, from_session, in_reply_to, requires_response, network_id)
@@ -1135,6 +1219,11 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       if (!["failed", "expired", "cancelled"].includes(task.status)) {
         return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: `task status is ${task.status}, not retryable` }) }] };
       }
+      // RFC-027 §2.3 inbox-enqueue lifecycle guard (PR1.1 site 4/6).
+      {
+        const lc = assertNodeActive(task.to_name, effectiveNetId ?? task.network_id ?? null);
+        if (!lc.ok) return { content: [{ type: "text" as const, text: JSON.stringify(lc) }] };
+      }
       db.transaction(() => {
         // Reset task status
         const updateParams: any[] = [task_id];
@@ -1282,6 +1371,11 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       const reassignedAlias = canonical.alias;
       const target = resolveDeliveryTarget(reassignedAlias, effectiveNetId ?? task.network_id ?? null);
       const newNodeId = target.state === "not_found" ? null : (target.session?.node_id ?? null);
+      // RFC-027 §2.3 inbox-enqueue lifecycle guard (PR1.1 site 5/6).
+      {
+        const lc = assertNodeActive(reassignedAlias, effectiveNetId ?? task.network_id ?? null);
+        if (!lc.ok) return { content: [{ type: "text" as const, text: JSON.stringify(lc) }] };
+      }
       db.transaction(() => {
         // Ack old inbox to prevent original agent from picking it up
         const inboxParams: any[] = [task_id];
@@ -1327,6 +1421,12 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       const ids: string[] = [];
 
       for (const t of targets) {
+        // RFC-027 §2.3 inbox-enqueue lifecycle guard (PR1.1 site 6/6).
+        // Broadcast skips non-active recipients silently rather than
+        // failing the entire send — broadcast semantics are best-effort
+        // per-recipient and a stopped node simply gets nothing.
+        const lc = assertNodeActive(t.alias, effectiveNetId ?? t.network_id ?? null);
+        if (!lc.ok) continue;
         const id = uuidv4();
         db.run(
           `INSERT INTO inbox (id, session_name, node_id, type, priority, content, from_session, network_id)
@@ -1418,7 +1518,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 FROM nodes WHERE node_id = ?1",
+      "SELECT node_id, alias, network_id, config_revision, config_snapshot FROM nodes WHERE node_id = ?1",
       nodeId,
     );
     if (!row) return { row: null, sec1Ok: false };
@@ -1741,16 +1841,1513 @@ export function registerTools(server: McpServer, clientIP?: string, enforceNetwo
       }
       const updateId = `cu_${uuidv4()}`;
       const networkId = node.network_id || "default";
-      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, '{}', 'restart_only', ?4, 'pending', ?5, ?6)`,
-        [updateId, nodeId, networkId, node.config_revision || 0, Date.now(), callerTokenId || "unknown"],
-      );
+      // RFC-027 PR1.2a latent fix (#346 ack): restart_node must reset
+      // lifecycle_state to 'active'. Otherwise a node that was previously
+      // stop_node'd → 'stopped' would, after restart, stay marked
+      // 'stopped' in the nodes table → the 6 MCP + 2 REST inbox guards
+      // would refuse every routing attempt → node silently unreachable
+      // (no error to operator, just no traffic). Pair the schema flip
+      // with the config_updates INSERT inside one tx so we don't
+      // half-commit if the dispatch INSERT throws.
+      db.transaction(() => {
+        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, '{}', 'restart_only', ?4, 'pending', ?5, ?6)`,
+          [updateId, nodeId, networkId, node.config_revision || 0, Date.now(), callerTokenId || "unknown"],
+        );
+        db.run(
+          `UPDATE nodes SET lifecycle_state = 'active' WHERE node_id = ?1`,
+          [nodeId],
+        );
+      });
       pushEvent(node.alias, { type: "restart", update_id: updateId }, networkId);
       return {
         content: [{ type: "text" as const, text: JSON.stringify({ ok: true, update_id: updateId, apply_mode: "restart_only" }) }],
       };
     },
   );
+
+  // ── RFC-026 P1 — create-node + host-daemon (3 MCP tools) ──────────
+  // Background timers (GC + sweeper) are idempotent + cheap; safe to
+  // call on every registerTools invocation (statless mode re-registers
+  // per request). They unref themselves so don't hold the event loop.
+  startPendingEnvGcTimer();
+  startSweeperTimer();
+
+  // §4.1.4 C2 — caller daemon resolved via token-bound identity (NOT
+  // alias). Thin closure over the module-level helper so callers in
+  // this scope can use the captured request-level vars. The pure
+  // helper lives in create-node.ts so unit tests call exactly the
+  // same code path the tools do (per 通信龙 PR #299 nit 1 — no inline-
+  // mirror SQL in tests).
+  const resolveCallerDaemonTokenBound = () =>
+    _resolveCallerDaemonTokenBound({ callerTokenIsNetwork, callerTokenId, enforceNetworkId });
+
+  // Helper — map a ValidationError thrown from create-node-validate
+  // into the MCP-tool-call JSON reply shape.
+  const validationFailReply = (e: unknown) => {
+    if (e instanceof ValidationError) {
+      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: e.code, ...(e.detail || {}) }) }] };
+    }
+    throw e;
+  };
+
+  // RFC-026 §9.2.1 / #338 PR2 — list_host_supervisors.
+  // Surfaces host_supervisor daemons in the caller's network with
+  // online flag + declared capabilities. Replaces the prior `node_daemon_`
+  // prefix heuristic (dashboard /api/anet/node-create) + the role-extract
+  // path on /api/nodes (#337). Member脱敏 strips host_telemetry IP /
+  // cpu / mem (per RFC-026 §6 #3 — daemons can leak internal topology
+  // to non-admin readers). Revoked daemon ntoks filtered out via
+  // 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.",
+    {
+      network_id: z.string().max(200).optional(),
+    },
+    async ({ network_id: clientNetId }) => {
+      // SEC-1 — use resolveReadScope, NOT getNetworkId. getNetworkId is
+      // for write-tool helpers and pairs with `canWrite`; READ tools that
+      // bypass canWrite and trust getNetworkId leak across tenants
+      // (PR2 v1 BLOCKER per 通信龙 audit — utok_ caller with
+      // enforceNetworkId=null could pass any network_id and read daemon
+      // names + allowed_secret_keys for tenants they're not a member of).
+      // resolveReadScope checks network_members for the user + denies
+      // on non-membership, mirroring REST resolveRestNetworkScope.
+      const readScope = resolveReadScope(clientNetId);
+      if (readScope.denied) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: readScope.denied }) }] };
+      }
+      // Caller role for 脱敏 decision (admin/owner = full, others = masked).
+      // Use the resolved scope's networkId (the verified one), not the
+      // unchecked clientNetId.
+      const scopedNetId = readScope.networkId ?? null;
+      const callerRole = enforceUserId && scopedNetId
+        ? getUserNetworkRole(enforceUserId, scopedNetId)
+        : null;
+      // Network-bound tokens get full telemetry within their bound network
+      // (already gate-locked by enforceNetworkId path of resolveReadScope).
+      const isPrivileged = callerRole === "admin" || callerRole === "owner" || (!enforceUserId);
+
+      // Pull candidate daemons. Active-token EXISTS subquery handles BOTH
+      // revoked daemon ntoks (revoked_at set) AND DELETEd token rows
+      // (the standard revokeToken path deletes the row, not flagging
+      // revoked_at — PR2 v1 SHOULD-FIX per 通信龙 audit). EXISTS naturally
+      // dedupes if a daemon ever had multiple tokens (e.g. rotation; nit ⚪).
+      let sql = `
+        SELECT
+          n.node_id, n.alias, n.hostname, n.network_id,
+          n.runtimes_supported, n.allowed_secret_keys,
+          n.created_at, n.updated_at,
+          s.last_seen_at AS session_last_seen,
+          s.status AS session_status,
+          s.cpu_cores AS session_cpu_cores,
+          s.mem_total_gb AS session_mem_total_gb,
+          s.ip AS session_ip,
+          n.config_snapshot
+        FROM nodes n
+        LEFT JOIN sessions s ON s.alias = n.alias AND (s.network_id = n.network_id OR s.network_id IS NULL)
+        WHERE EXISTS (
+          SELECT 1 FROM api_tokens t
+          WHERE t.network_id = n.network_id
+            AND t.name = 'node:' || n.alias
+            AND t.revoked_at IS NULL
+        )
+      `;
+      const sqlParams: any[] = [];
+      sql = addReadScope(sql, sqlParams, readScope, "n.network_id");
+      sql += ` ORDER BY n.updated_at DESC`;
+      const rows = db.all<Record<string, any>>(sql, ...sqlParams);
+
+      // Filter to role=host_supervisor (read from config_snapshot;
+      // schema-promoted columns runtimes_supported/allowed_secret_keys
+      // are pre-extracted but role isn't a first-class column).
+      const nowMs = Date.now();
+      const ONLINE_MS = 60_000;
+      const daemons = rows
+        .map(r => {
+          let snapRole: string | null = null;
+          if (r.config_snapshot) {
+            try {
+              const parsed = typeof r.config_snapshot === "string" ? JSON.parse(r.config_snapshot) : r.config_snapshot;
+              snapRole = typeof parsed?.role === "string" ? parsed.role : null;
+            } catch { /* malformed snapshot — role stays null */ }
+          }
+          return { row: r, role: snapRole };
+        })
+        .filter(({ role }) => role === "host_supervisor")
+        .map(({ row: r }) => {
+          // online = sessions.last_seen_at within ONLINE_MS
+          let online = false;
+          let lastSeenAt: string | null = null;
+          if (r.session_last_seen) {
+            lastSeenAt = r.session_last_seen;
+            const t = Date.parse(r.session_last_seen);
+            if (!isNaN(t)) online = (nowMs - t) <= ONLINE_MS;
+          }
+          // Parse self-declare arrays (default to [] for pre-PR2 daemons)
+          let runtimes: string[] = [];
+          let secrets: string[] = [];
+          try {
+            if (r.runtimes_supported) {
+              const parsed = JSON.parse(r.runtimes_supported);
+              runtimes = Array.isArray(parsed) ? parsed.filter((s: unknown) => typeof s === "string") : [];
+            }
+          } catch { /* malformed — empty */ }
+          try {
+            if (r.allowed_secret_keys) {
+              const parsed = JSON.parse(r.allowed_secret_keys);
+              secrets = Array.isArray(parsed) ? parsed.filter((s: unknown) => typeof s === "string") : [];
+            }
+          } catch { /* malformed — empty */ }
+          // host_telemetry — member脱敏 drops IP/cpu/mem
+          const telemetry: Record<string, unknown> = {
+            alert_level: online ? "green" : "gray",
+          };
+          if (isPrivileged) {
+            telemetry.cpu_cores = r.session_cpu_cores ?? null;
+            telemetry.mem_gb = r.session_mem_total_gb ?? null;
+            telemetry.ip_internal = r.session_ip ?? null;
+          }
+          return {
+            daemon_node_id: r.node_id,
+            alias: r.alias,
+            hostname: r.hostname,
+            online,
+            last_seen_at: lastSeenAt,
+            runtimes_supported: runtimes,
+            allowed_secret_keys: secrets,
+            host_telemetry: telemetry,
+          };
+        });
+
+      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, daemons, count: daemons.length }) }] };
+    },
+  );
+
+  // §2.5 step 1+2 — dashboard-facing tool. Validates spec, mint
+  // child-ntok, stash env_blob in pendingEnvBlobs Map, write request
+  // 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.",
+    {
+      daemon_node_id: z.string().min(1).max(200),
+      node_spec: z.object({
+        name: z.string().min(1).max(64),
+        runtime: z.string().min(1).max(64),
+        model: z.string().min(1).max(100),
+        flags: z.record(z.unknown()).optional(),
+        env_refs: z.array(z.string().max(64)).optional(),
+        channels: z.array(z.unknown()).optional(),
+      }),
+      network_id: z.string().max(200).optional(),
+    },
+    async ({ daemon_node_id, node_spec, network_id: clientNetId }) => {
+      const effectiveNetId = getNetworkId(clientNetId);
+      if (!canWrite(effectiveNetId)) return writeDeniedReply(effectiveNetId, "write");
+
+      // §4.1.1 — admin+ for create_node (creating a node = pulling new
+      // resource + burning API quota, one level above edit single flag)
+      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 }) }] };
+      }
+
+      // Daemon must exist + must be in caller's network + must be
+      // online with role=host_supervisor capability.
+      const { row: daemon, sec1Ok } = resolveTargetNode(daemon_node_id, effectiveNetId);
+      if (!daemon) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "daemon_not_found", daemon_node_id }) }] };
+      }
+      if (!sec1Ok) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "cross_network_node" }) }] };
+      }
+
+      // Read daemon's host_supervisor capability + allowlist from its
+      // last reported config_snapshot. PR3 (#338) canonical path is
+      // `daemon_capabilities.runtimes_supported` (RFC-026 §9.3).
+      // Pre-PR3 daemons (preview.10 and earlier) place these at the
+      // TOP level of the snapshot rather than nested — those reads
+      // return undefined here and `daemonAllowedRuntimes` stays null
+      // (permissive — no allowlist enforcement); they fall back to
+      // §4.2.2 structural validation only, identical to pre-PR3
+      // behavior. No regression on in-flight daemons.
+      let daemonAllowList = new Set<string>();
+      let daemonAllowedRuntimes: string[] | null = null;
+      try {
+        const snap = daemon.config_snapshot ? JSON.parse(daemon.config_snapshot) : null;
+        const caps = snap?.daemon_capabilities;
+        if (Array.isArray(caps?.allowed_secret_keys)) {
+          daemonAllowList = new Set(caps.allowed_secret_keys);
+        }
+        if (Array.isArray(caps?.runtimes_supported)) {
+          daemonAllowedRuntimes = caps.runtimes_supported;
+        }
+      } catch { /* permissive fallback */ }
+
+      // §4.2.2 — structural validation (catches name/runtime/model/
+      // flag injection at the hub edge). Daemon repeats this; double
+      // layer per RFC §4.2.2.
+      try {
+        validateChildName(node_spec.name);
+        validateRuntime(node_spec.runtime);
+        validateModel(node_spec.model);
+        validateChannelsP1((node_spec as any).channels);
+        for (const [k, v] of Object.entries(node_spec.flags || {})) {
+          if (!(FLAG_KEYS as readonly string[]).includes(k)) throw new ValidationError("flag_key_unknown", { field: k });
+          validateFlagValue(k, v);
+        }
+      } catch (e) {
+        return validationFailReply(e);
+      }
+
+      // P1 daemon-side allowlist: if daemon publishes allowed_runtimes,
+      // enforce at hub for fast-fail; daemon repeats.
+      if (daemonAllowedRuntimes && !daemonAllowedRuntimes.includes(node_spec.runtime)) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "runtime_not_in_local_allowlist", runtime: node_spec.runtime, allowed: daemonAllowedRuntimes }) }] };
+      }
+
+      // §4.4.7 — env_refs strict (7-step gate) + resolve to env_blob.
+      let envBlob: Record<string, string> = {};
+      const envRefs = (node_spec as any).env_refs;
+      try {
+        envBlob = validateEnvRefs(envRefs, {
+          callerNetworkId: effectiveNetId || "default",
+          daemonAllowList,
+          networkSecretsGet: (_net: string, _key: string) => undefined, // P1: no vault yet — see note below
+        });
+      } catch (e) {
+        return validationFailReply(e);
+      }
+      // P1 NOTE — network_secrets vault is RFC §4.4 / §2.4 future
+      // work. For now if dashboard sends env_refs we'll reject as
+      // not-in-vault (above). When the vault lands, replace the
+      // `networkSecretsGet: () => undefined` line with the real DB
+      // lookup; nothing else in this tool needs to change.
+
+      // Single-flight per (daemon, child_name): partial unique index
+      // uniq_ncr_inflight already prevents racing INSERT, but we
+      // surface a friendly error rather than letting the DB constraint
+      // raise.
+      const existing = db.get<{ request_id: string; status: string }>(
+        `SELECT request_id, status FROM node_create_requests WHERE daemon_node_id = ?1 AND child_name = ?2 AND status IN ('pending', 'delivered') ORDER BY created_at DESC LIMIT 1`,
+        daemon_node_id, node_spec.name,
+      );
+      if (existing) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "node_name_conflict", existing_request_id: existing.request_id, existing_status: existing.status }) }] };
+      }
+
+      // §4.2.4 — daemon_max_children backpressure (best-effort: count
+      // currently-active children for this daemon).
+      const maxChildren = (() => {
+        try {
+          const snap = daemon.config_snapshot ? JSON.parse(daemon.config_snapshot) : null;
+          const m = snap?.daemon_capabilities?.max_concurrent_children;
+          return (typeof m === "number" && m > 0) ? m : 20;
+        } catch { return 20; }
+      })();
+      const childCount = db.get<{ n: number }>(
+        `SELECT COUNT(*) AS n FROM node_create_requests WHERE daemon_node_id = ?1 AND status IN ('pending', 'delivered', 'succeeded')`,
+        daemon_node_id,
+      )?.n || 0;
+      if (childCount >= maxChildren) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "daemon_max_children", current: childCount, max: maxChildren }) }] };
+      }
+
+      // §2.5 step 2 + §4.4 F1 — mint child-ntok + stash env_blob in
+      // Map (NOT in DB). Token row marked role='child' + request_id
+      // for sweeper traceability per §4.4.8 impl note.
+      const childToken = generateNetworkToken();
+      const childTokenId = generateId("tok");
+      const networkIdForChild = daemon.network_id || effectiveNetId || "default";
+      const requestId = newRequestId();
+      // Use the dashboard caller's user_id as the token's user_id so
+      // resolveToken returns sane role / network on the child's side
+      // (audit trail = whoever created it).
+      if (!enforceUserId) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "auth_required" }) }] };
+      }
+      db.run(
+        `INSERT INTO api_tokens (token_id, token_hash, user_id, network_id, name, scope, role, request_id) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)`,
+        [childTokenId, hashToken(childToken), enforceUserId, networkIdForChild, `node:${node_spec.name}`, "network", "child", requestId]
+      );
+
+      putPendingEnvBlob({
+        request_id: requestId,
+        daemon_node_id,
+        env_blob: envBlob,
+        child_token: childToken,
+        child_token_id: childTokenId,
+      });
+
+      // Write metadata-only row. env_blob field deliberately ABSENT
+      // from the schema (see db.ts CREATE TABLE) — F1 lock.
+      const envKeys = Object.keys(envBlob);
+      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)
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, 'pending', ?9, ?10, ?11)`,
+        [
+          requestId, daemon_node_id, node_spec.name, networkIdForChild,
+          node_spec.runtime, node_spec.model, JSON.stringify(node_spec.flags || {}),
+          JSON.stringify(envKeys), childTokenId, Date.now(), callerTokenId || "unknown",
+        ],
+      );
+
+      // SSE doorbell — daemon will pull via get_create_request.
+      // Payload carries ONLY request_id (no secret); daemon current
+      // SSE handler resolves the rest via MCP call.
+      pushEvent(daemon.alias, { type: "create_node", request_id: requestId }, networkIdForChild);
+
+      // §4.5 audit — dispatch succeeded
+      auditCreateNode({
+        action: "create_node_dispatched",
+        user_id: enforceUserId,
+        network_id: networkIdForChild,
+        target_id: requestId,
+        detail: {
+          daemon_node_id,
+          child_name: node_spec.name,
+          runtime: node_spec.runtime,
+          model: node_spec.model,
+          flag_keys: Object.keys(node_spec.flags || {}),
+          env_keys: envKeys,
+        },
+      });
+
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({ ok: true, request_id: requestId }) }],
+      };
+    },
+  );
+
+  // §2.5 step 3 — daemon-facing pull. Returns full spec + env_blob +
+  // child_ntok in one shot. Map evicted on take (one-shot consume).
+  //
+  // §4.1.4 C2 token-bound daemon resolution (PR #299 BLOCKER #1, 通信牛):
+  // We MUST resolve the caller daemon via token-bound identity, NOT
+  // alias. alias is NOT a security boundary — two daemons with the same
+  // alias in different networks (or attacker-named-itself-the-same)
+  // would otherwise resolve to the wrong row. Same class as the prior
+  // report_status cross-tenant re-home bug.
+  //
+  // Resolution chain: caller's ntok (callerTokenId + callerTokenIsNetwork)
+  // → api_tokens row → joins to nodes via name='node:<alias>' AND
+  // network_id matches → unique daemon node row scoped to caller's
+  // network. If the ntok isn't bound to a node, or the joined node
+  // 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.",
+    {
+      request_id: z.string().min(1).max(200),
+    },
+    async ({ request_id }) => {
+      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`,
+        request_id,
+      );
+      if (!row) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "request_not_found" }) }] };
+      // §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" }) }] };
+      }
+      // Additional network-scope guard (defense in depth: row's
+      // network_id MUST equal caller's network).
+      if (row.network_id !== callerDaemon.networkId) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "cross_network_request" }) }] };
+      }
+      if (row.status !== "pending") {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "request_not_pending", current_status: row.status }) }] };
+      }
+
+      // Take env_blob from Map; this is the one-shot consume per F1.
+      // takePendingEnvBlob ALSO checks daemon binding (belt+braces).
+      const blob = takePendingEnvBlob(request_id, callerDaemon.daemonNodeId);
+      if (!blob) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "env_blob_unavailable" }) }] };
+      }
+      // Hydrate spec from row.
+      const specRow = db.get<{ child_name: string; runtime: string; model: string; flags_json: string }>(
+        `SELECT child_name, runtime, model, flags_json FROM node_create_requests WHERE request_id = ?1`,
+        request_id,
+      );
+      if (!specRow) {
+        // Should never happen given the earlier row read.
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "request_vanished" }) }] };
+      }
+      // Mark delivered (so sweeper distinguishes F-1 from F-2).
+      db.run(
+        `UPDATE node_create_requests SET status = 'delivered', delivered_at = ?1 WHERE request_id = ?2 AND status = 'pending'`,
+        [Date.now(), request_id],
+      );
+
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({
+          ok: true,
+          request_id,
+          node_spec: {
+            name: specRow.child_name,
+            runtime: specRow.runtime,
+            model: specRow.model,
+            flags: JSON.parse(specRow.flags_json),
+            channels: [],
+          },
+          child_token: blob.child_token,
+          env_blob: blob.env_blob,
+        }) }],
+      };
+    },
+  );
+
+  // §2.5 step 4 — daemon reports outcome. Note: 'succeeded' is set
+  // automatically by hub when the child first registers (content-match
+  // in upsertNodeWithSec1Guard); daemon's ack here is for explicit
+  // failures (fork crashed, etc.). Daemon should still call this on
+  // success too — it's a useful idempotent confirmation + lets hub
+  // record fork-side info.
+  server.tool(
+    "ack_create_request",
+    "Daemon acks a create-node request (called after fork). status='started' | 'failed' | 'rejected' | 'runtime_capability_check_failed'. RFC-026 §9.3 D2.",
+    {
+      request_id: z.string().min(1).max(200),
+      // RFC-026 §9.3 D2 — runtime_capability_check_failed signals the
+      // daemon spawned the child OK but it died within FAIL_FAST_MS
+      // (5s in agent-node v2.5.0-preview.11+), indicating a
+      // declaration↔reality gap on this daemon's runtimes_supported.
+      // Treated terminal like 'failed' but fires a distinct audit_log
+      // action so dashboards can highlight "lying daemons" separately
+      // from generic spawn failures.
+      status: z.enum(["started", "failed", "rejected", "runtime_capability_check_failed"]),
+      error: z.string().max(1000).optional(),
+      child_pid: z.number().int().optional(),
+      runtime: z.string().max(64).optional(),   // populated by daemon when status=runtime_capability_check_failed
+    },
+    async ({ request_id, status, error: ackError, child_pid: _pid, runtime: ackRuntime }) => {
+      const callerDaemon = resolveCallerDaemonTokenBound();
+      if (!callerDaemon.ok) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: callerDaemon.error }) }] };
+      }
+      const row = db.get<{ daemon_node_id: string; status: string; child_token_id: string | null; network_id: string }>(
+        `SELECT daemon_node_id, status, child_token_id, network_id 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" }) }] };
+      if (row.daemon_node_id !== callerDaemon.daemonNodeId) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "not_your_request" }) }] };
+      }
+      if (row.network_id !== callerDaemon.networkId) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "cross_network_request" }) }] };
+      }
+      const ackedAt = Date.now();
+      if (status === "started") {
+        // Don't flip to 'succeeded' here — that happens via content-
+        // match when the child actually registers. We just stamp ack.
+        db.run(
+          `UPDATE node_create_requests SET acked_at = ?1 WHERE request_id = ?2 AND status IN ('delivered', 'pending')`,
+          [ackedAt, request_id],
+        );
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, status: "awaiting_register" }) }] };
+      }
+      // failed / rejected / runtime_capability_check_failed — revoke
+      // child-ntok + mark request terminal.
+      if (row.child_token_id) {
+        db.run(`UPDATE api_tokens SET revoked_at = datetime('now') WHERE token_id = ?1 AND revoked_at IS NULL`, [row.child_token_id]);
+      }
+      db.run(
+        `UPDATE node_create_requests SET status = ?1, error = ?2, acked_at = ?3 WHERE request_id = ?4 AND status IN ('pending', 'delivered')`,
+        [status, ackError || null, ackedAt, request_id],
+      );
+      // RFC-026 §9.3 D2 — surface declaration↔reality gap on a
+      // distinct audit_log action so dashboards / operators can spot
+      // chronically-lying daemons separate from generic spawn-failed.
+      if (status === "runtime_capability_check_failed") {
+        auditCreateNode({
+          action: "daemon_capability_lied",
+          user_id: null,
+          network_id: row.network_id,
+          target_id: request_id,
+          detail: {
+            daemon_node_id: row.daemon_node_id,
+            runtime: ackRuntime || null,
+            error: ackError ? ackError.slice(0, 500) : null,
+            acked_at: ackedAt,
+          },
+        });
+      }
+      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, status }) }] };
+    },
+  );
+
+  // ─── RFC-027 §2 — stop/delete node lifecycle ───────────────────────
+  //
+  // Two user-facing MCP tools (stop_node, delete_node) + two daemon-
+  // facing tools (get_stop_request, ack_stop_request). State machine
+  // per §2.3 — nodes.lifecycle_state ∈ {active, stopping, stopped,
+  // deleting}. row-gone implies deleted. Security per §4:
+  //   §4.1 SEC-1: trust-root SQL join, not getNetworkId
+  //   §4.2 D6:    delete_node refuses target.role==host_supervisor
+  //   §4.3 D4:    in-flight inbox default-refuse + force+audit
+  //   §4.4 D7:    daemon writes backup chmod 700, sweeper真删
+  //   §4.5 D8:    audit_log in same SQLite tx as state UPDATE
+  //
+  // The dispatcher logic shared by stop_node + delete_node lives in
+  // dispatchStopOrDelete; the two tool handlers thin-wrap it with
+  // their respective action discriminator.
+  type DispatchAction = "stop" | "delete";
+  type DispatchArgs = {
+    action: DispatchAction;
+    child_node_id: string;
+    daemon_node_id: string;
+    force: boolean;
+    grace_seconds: number;
+    delete_config: boolean;
+    confirm_alias?: string;
+  };
+  // RFC-027 PR2 prereq — auto-resolve daemon_node_id from child_node_id.
+  // The dashboard (and most callers of stop_node / delete_node) shouldn't
+  // need to track the daemon→child mapping themselves; the hub has it on
+  // node_create_requests at child creation time. Returns null when no
+  // creation record exists (orphan node row OR pre-RFC-026 node) — caller
+  // must then pass daemon_node_id explicitly. node_id derivation:
+  // `node_${request_id.replace(/^cr_/,"")}` (see create-node-daemon.ts
+  // and PR1 BLOCKER-1 fix), so we reverse it: `cr_${node_id.slice(5)}`.
+  const resolveDaemonForChild = (child_node_id: string): string | null => {
+    if (!child_node_id.startsWith("node_")) return null;
+    const requestId = `cr_${child_node_id.slice(5)}`;
+    const row = db.get<{ daemon_node_id: string }>(
+      `SELECT daemon_node_id FROM node_create_requests WHERE request_id = ?1`,
+      requestId,
+    );
+    return row?.daemon_node_id ?? null;
+  };
+
+  const dispatchStopOrDelete = (args: DispatchArgs, clientNetId?: string | null) => {
+    // §4.1 — SEC-1 trust-root join: resolve target node row WITHIN the
+    // caller's scope. resolveReadScope returns 'denied' if the caller
+    // doesn't belong to clientNetId; for the row-existence test we
+    // re-join with member's networks so an attacker can't probe by
+    // node_id from a network they don't belong to.
+    const scope = resolveReadScope(clientNetId);
+    if (scope.denied) {
+      return { ok: false, error: "forbidden_cross_tenant", message: scope.denied };
+    }
+    const nodeQ: any[] = [args.child_node_id];
+    let nodeSql = `SELECT node_id, alias, network_id, lifecycle_state, config_snapshot, runtimes_supported
+      FROM nodes WHERE node_id = ?1`;
+    nodeSql = addReadScope(nodeSql, nodeQ, scope);
+    const node = db.get<{
+      node_id: string;
+      alias: string;
+      network_id: string;
+      lifecycle_state: string | null;
+      config_snapshot: string | null;
+    }>(nodeSql, ...nodeQ);
+    if (!node) return { ok: false, error: "forbidden_cross_tenant", message: "node not found in your networks" };
+
+    // Caller must hold a write-capable role on the resolved network
+    // (admin/owner/member; viewer denied). canWrite walks getUserNetworkRole.
+    if (!canWrite(node.network_id)) {
+      return { ok: false, error: "permission_denied", message: "viewer role cannot stop/delete nodes" };
+    }
+
+    // §4.2 D6 — delete refuses targets whose role is host_supervisor.
+    // Stop is allowed against any node per RFC table (host_supervisor's
+    // stop is functionally a no-op anyway: the daemon's children_map
+    // only tracks its child nodes, never the daemon itself).
+    //
+    // PR1 SF-4 (#345 review) — fail-CLOSED on role read. The first cut
+    // parsed config_snapshot and treated parse-fail / missing-field as
+    // role=null which slipped through the gate. A daemon row with a
+    // corrupt snapshot would then be deletable via delete_node. Fix:
+    // - read role via two independent paths (snapshot.role + the
+    //   indexed `runtimes_supported` column whose presence ≈ daemon)
+    // - if EITHER path indicates host_supervisor → refuse
+    // - if snapshot parsed but role missing AND the node has any
+    //   daemon-shape evidence (non-null runtimes_supported column,
+    //   present in any node_create_requests as daemon_node_id) →
+    //   refuse defensively. The defense-in-depth daemon-side
+    //   children_map miss is the second layer; the hub gate must
+    //   itself fail-closed when role is ambiguous.
+    if (args.action === "delete") {
+      let role: string | null = null;
+      let snapshotParseFailed = false;
+      try {
+        const snap = node.config_snapshot ? JSON.parse(node.config_snapshot) : null;
+        role = typeof snap?.role === "string" ? snap.role : null;
+      } catch { snapshotParseFailed = true; }
+      const ambiguous = snapshotParseFailed || (role == null);
+      // Independent corroborating check: nodes flagged as daemons by
+      // create_node dispatchers will show up as daemon_node_id in
+      // node_create_requests. Costs one indexed query.
+      let looksLikeDaemon = false;
+      if (ambiguous) {
+        const m = db.get<{ n: number }>(
+          `SELECT COUNT(*) AS n FROM node_create_requests WHERE daemon_node_id = ?1`,
+          node.node_id,
+        );
+        if ((m?.n ?? 0) > 0) looksLikeDaemon = true;
+      }
+      if (role === "host_supervisor" || (ambiguous && looksLikeDaemon)) {
+        return {
+          ok: false, error: "cannot_delete_daemon_via_delete_node",
+          message: snapshotParseFailed
+            ? "node config_snapshot unreadable; node is referenced as a daemon — refuse delete defensively (use delete_daemon path)"
+            : "host_supervisor daemons must be removed via the dedicated delete_daemon path (RFC-027.5)",
+        };
+      }
+    }
+
+    // delete_node confirm_alias gate: dashboard's二次确认 input must
+    // match the actual alias byte-for-byte. Hub rejects mismatched
+    // input even if dashboard UI claims it's disabled.
+    if (args.action === "delete") {
+      if (typeof args.confirm_alias !== "string" || args.confirm_alias !== node.alias) {
+        return { ok: false, error: "confirm_alias_mismatch", message: "confirm_alias must equal the node's alias" };
+      }
+    }
+
+    // Daemon must exist + be in the same network. We do NOT enforce
+    // daemon.role==host_supervisor here: a child whose creator daemon
+    // got demoted should still be stoppable. The daemon will refuse
+    // with noop_not_my_child if children_map doesn't know it.
+    //
+    // PR1.2 e2e catch (BLOCKER): pushEvent keys SSE by clientKey ≈
+    // `${networkId}:${sessionName}`, and agent-node registers its SSE
+    // connection under its ALIAS (not its node_id). The create_node
+    // doorbell at line ~2197 correctly pushes via `daemon.alias`;
+    // stop_node was pushing via `daemon_node_id` so every doorbell
+    // missed every SSE client → daemon never woke up → request_id
+    // stayed 'pending' forever → child never reaped. The 24 unit tests
+    // in stop-delete-node.test.ts all mock pushEvent and inject the
+    // post-doorbell handler call directly, so single-unit coverage
+    // couldn't surface this — exactly the failure class 通信龙 said
+    // the docker e2e gate exists to catch (BLOCKER-1 同源). Load the
+    // alias along with node_id + network_id and dispatch to the alias.
+    const daemon = db.get<{ node_id: string; alias: string; network_id: string }>(
+      `SELECT node_id, alias, network_id FROM nodes WHERE node_id = ?1`, args.daemon_node_id,
+    );
+    if (!daemon) return { ok: false, error: "daemon_not_found" };
+    if (daemon.network_id !== node.network_id) {
+      // Cross-tenant child↔daemon mismatch shouldn't be possible in
+      // normal flow but is a SEC-1 hardening — refuse loud.
+      return { ok: false, error: "daemon_cross_tenant", message: "daemon and child are in different networks" };
+    }
+
+    // State machine gate.
+    const state = node.lifecycle_state ?? "active";
+    if (args.action === "stop" && state !== "active") {
+      return { ok: false, error: state === "stopping" ? "node_already_stopping" : "node_not_active", current_state: state };
+    }
+    if (args.action === "delete" && state === "deleting") {
+      return { ok: false, error: "node_already_deleting", current_state: state };
+    }
+    if (args.action === "delete" && state === "stopping") {
+      // Can't start delete while a stop is mid-flight — race-prone.
+      return { ok: false, error: "node_stopping_in_progress", current_state: state };
+    }
+
+    // §4.3 D4 — in-flight inbox check. Count unacked tasks routed to
+    // this node's alias (inbox routing uses session_name == alias).
+    // Default refuse with the count surfaced; force=true overrides
+    // and triggers the forced_stop_with_in_flight audit row.
+    // SF-5 (#345 review): legacy inbox rows may have network_id=NULL
+    // and would silently miss a network_id=?2 strict equality match.
+    // Use COALESCE so a NULL inbox row is counted against the same
+    // network as the target node (which is the only safe default
+    // — pre-multi-network rows existed in single-network mode).
+    const inFlightRow = db.get<{ n: number }>(
+      `SELECT COUNT(*) AS n FROM inbox WHERE session_name = ?1 AND acked = 0
+         AND COALESCE(network_id, ?2) = ?2`,
+      node.alias, node.network_id,
+    );
+    const inFlight = inFlightRow?.n ?? 0;
+    if (inFlight > 0 && !args.force) {
+      return { ok: false, error: "node_busy_in_flight", in_flight_count: inFlight, hint: "set force=true to override (audit logged)" };
+    }
+
+    // ── all gates passed; create request + transition state + push doorbell, transactionally ──
+    const requestId = generateId("sr");
+    const now = Date.now();
+    const newState = args.action === "stop" ? "stopping" : "deleting";
+
+    // §4.5 D8 — lifecycle UPDATE + audit INSERTs + request INSERT atomic.
+    // PR1.1: use db.transaction() (SQLiteAdapter wraps better-sqlite3's
+    // native transaction; PgAdapter ships a real BEGIN/COMMIT/ROLLBACK
+    // shim). Lets us drop the open-coded BEGIN/COMMIT + makes the
+    // SF-2 failure-injection test (mock db.run throw inside callback)
+    // reliable across both backends.
+    try {
+      db.transaction(() => {
+      db.run(
+        `INSERT INTO node_stop_requests
+           (request_id, network_id, daemon_node_id, child_node_id, child_alias, action,
+            delete_config, grace_seconds, force, in_flight_at_dispatch, created_by_token,
+            status, created_at)
+         VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, 'pending', ?12)`,
+        [
+          requestId, node.network_id, args.daemon_node_id, node.node_id, node.alias, args.action,
+          args.delete_config ? 1 : 0, args.grace_seconds, args.force ? 1 : 0, inFlight,
+          callerTokenId || "unknown", now,
+        ],
+      );
+      db.run(
+        `UPDATE nodes SET lifecycle_state = ?1 WHERE node_id = ?2`,
+        [newState, node.node_id],
+      );
+      // §4.5 D8 — audit dispatch action. Uses the STRICT variant so a
+      // failed audit INSERT propagates and triggers ROLLBACK (PR1 SF-2
+      // review catch — auditCreateNode's swallow-and-warn would have
+      // committed the lifecycle UPDATE without an audit row, leaving
+      // exactly the "deleted but no audit" window §4.5 closes).
+      auditCreateNodeStrict({
+        action: args.action === "stop" ? "stop_node_dispatched" : "delete_node_dispatched",
+        user_id: enforceUserId, network_id: node.network_id, target_id: requestId,
+        detail: {
+          child_node_id: node.node_id, child_alias: node.alias,
+          daemon_node_id: args.daemon_node_id, action: args.action,
+          force: args.force, delete_config: args.delete_config,
+          grace_seconds: args.grace_seconds, in_flight_at_dispatch: inFlight,
+          lifecycle_state_before: state, lifecycle_state_after: newState,
+          ts_request: now,
+        },
+      });
+      if (args.force && inFlight > 0) {
+        auditCreateNodeStrict({
+          action: "forced_stop_with_in_flight",
+          user_id: enforceUserId, network_id: node.network_id, target_id: requestId,
+          detail: { in_flight_count: inFlight, child_alias: node.alias },
+        });
+      }
+      });   // end db.transaction
+    } catch (e: any) {
+      return { ok: false, error: "dispatch_tx_failed", message: e?.message || String(e) };
+    }
+
+    // SSE doorbell — daemon will pull via get_stop_request.
+    // PR1.2 e2e fix: route by daemon.alias (see SELECT above for the
+    // BLOCKER explanation). Mirrors create_node's pushEvent target at
+    // line ~2197.
+    pushEvent(daemon.alias, { type: "stop_node", request_id: requestId }, node.network_id);
+    return {
+      ok: true, request_id: requestId, action: args.action,
+      lifecycle_state: newState, in_flight_at_dispatch: inFlight,
+    };
+  };
+
+  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).",
+    {
+      child_node_id: z.string().min(1).max(200).regex(/^node_[a-z0-9_-]+$/),
+      // PR2 prereq: dashboard rarely knows daemon_node_id directly.
+      // When omitted, hub resolves from the original creation record
+      // (node_create_requests.daemon_node_id keyed by this child).
+      daemon_node_id: z.string().min(1).max(200).regex(/^node_[a-z0-9_-]+$/).optional(),
+      force: z.boolean().optional().default(false),
+      grace_seconds: z.number().int().min(5).max(60).optional().default(10),
+      network_id: z.string().max(200).optional(),
+    },
+    async ({ child_node_id, daemon_node_id, force, grace_seconds, network_id: clientNetId }) => {
+      const resolved = daemon_node_id ?? resolveDaemonForChild(child_node_id);
+      if (!resolved) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({
+          ok: false, error: "daemon_not_resolvable",
+          message: "no node_create_requests row found for this child_node_id; pass daemon_node_id explicitly",
+        }) }] };
+      }
+      const r = dispatchStopOrDelete(
+        { action: "stop", child_node_id, daemon_node_id: resolved, force: force ?? false,
+          grace_seconds: grace_seconds ?? 10, delete_config: false },
+        clientNetId,
+      );
+      return { content: [{ type: "text" as const, text: JSON.stringify(r) }] };
+    },
+  );
+
+  server.tool(
+    "delete_node",
+    "Stop child + revoke ntok + delete hub row + (default) backup config to ~/.anet/deleted/<ts>-<alias>/ for 30d. confirm_alias must equal the node's alias. daemon_node_id is auto-resolved when omitted. RFC-027 §2.2.",
+    {
+      child_node_id: z.string().min(1).max(200).regex(/^node_[a-z0-9_-]+$/),
+      daemon_node_id: z.string().min(1).max(200).regex(/^node_[a-z0-9_-]+$/).optional(),
+      confirm_alias: z.string().min(1).max(200),
+      force: z.boolean().optional().default(false),
+      grace_seconds: z.number().int().min(5).max(60).optional().default(10),
+      delete_config: z.boolean().optional().default(true),
+      network_id: z.string().max(200).optional(),
+    },
+    async ({ child_node_id, daemon_node_id, confirm_alias, force, grace_seconds, delete_config, network_id: clientNetId }) => {
+      const resolved = daemon_node_id ?? resolveDaemonForChild(child_node_id);
+      if (!resolved) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({
+          ok: false, error: "daemon_not_resolvable",
+          message: "no node_create_requests row found for this child_node_id; pass daemon_node_id explicitly",
+        }) }] };
+      }
+      const r = dispatchStopOrDelete(
+        { action: "delete", child_node_id, daemon_node_id: resolved, force: force ?? false,
+          grace_seconds: grace_seconds ?? 10, delete_config: delete_config ?? true, confirm_alias },
+        clientNetId,
+      );
+      return { content: [{ type: "text" as const, text: JSON.stringify(r) }] };
+    },
+  );
+
+  server.tool(
+    "get_stop_request",
+    "Daemon pulls a pending stop/delete request (called when SSE stop_node doorbell arrives). RFC-027 §2.4.",
+    {
+      request_id: z.string().min(1).max(200),
+    },
+    async ({ request_id }) => {
+      const callerDaemon = resolveCallerDaemonTokenBound();
+      if (!callerDaemon.ok) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: callerDaemon.error }) }] };
+      }
+      const row = db.get<{
+        daemon_node_id: string; status: string; network_id: string;
+        child_node_id: string; child_alias: string; action: string;
+        delete_config: number; grace_seconds: number; force: number;
+      }>(`SELECT daemon_node_id, status, network_id, child_node_id, child_alias, action,
+                 delete_config, grace_seconds, force
+            FROM node_stop_requests WHERE request_id = ?1`, request_id);
+      if (!row) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "request_not_found" }) }] };
+      if (row.daemon_node_id !== callerDaemon.daemonNodeId) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "not_your_request" }) }] };
+      }
+      if (row.network_id !== callerDaemon.networkId) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "cross_network_request" }) }] };
+      }
+      // Stamp delivered_at on first pull (idempotent — only if still pending).
+      db.run(
+        `UPDATE node_stop_requests SET status = 'delivered', delivered_at = ?1
+           WHERE request_id = ?2 AND status = 'pending'`,
+        [Date.now(), request_id],
+      );
+      return { content: [{ type: "text" as const, text: JSON.stringify({
+        ok: true,
+        request_id,
+        child_node_id: row.child_node_id,
+        child_alias: row.child_alias,
+        action: row.action,
+        delete_config: row.delete_config === 1,
+        grace_seconds: row.grace_seconds,
+        force: row.force === 1,
+      }) }] };
+    },
+  );
+
+  server.tool(
+    "ack_stop_request",
+    "Daemon reports stop/delete completion (or per-status failure). On 'stopped' status finalizes the lifecycle: stop→stopped + keep config; delete→DB row gone + revoke ntok. RFC-027 §2.3 + §4.5.",
+    {
+      request_id: z.string().min(1).max(200),
+      status: z.enum(["stopped", "stop_failed", "noop_not_my_child"]),
+      exit_signal: z.string().max(16).optional(),
+      backup_path: z.string().max(500).optional(),
+      error: z.string().max(1000).optional(),
+    },
+    async ({ request_id, status, exit_signal, backup_path, error: ackError }) => {
+      const callerDaemon = resolveCallerDaemonTokenBound();
+      if (!callerDaemon.ok) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: callerDaemon.error }) }] };
+      }
+      const row = db.get<{
+        daemon_node_id: string; status: string; network_id: string;
+        child_node_id: string; child_alias: string; action: string;
+        in_flight_at_dispatch: number; force: number;
+      }>(`SELECT daemon_node_id, status, network_id, child_node_id, child_alias, action,
+                 in_flight_at_dispatch, force
+            FROM node_stop_requests WHERE request_id = ?1`, request_id);
+      if (!row) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "request_not_found" }) }] };
+      if (row.daemon_node_id !== callerDaemon.daemonNodeId) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "not_your_request" }) }] };
+      }
+      if (row.network_id !== callerDaemon.networkId) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "cross_network_request" }) }] };
+      }
+      const now = Date.now();
+
+      // §4.5 D8 — lifecycle UPDATE + request UPDATE + audit INSERT
+      // (+ DELETE for delete action) atomic via db.transaction().
+      // PR1.1: replaces hand-rolled BEGIN..COMMIT so PG adapter and
+      // SQLite both get correct rollback semantics from one code path.
+      try {
+        db.transaction(() => {
+          db.run(
+            `UPDATE node_stop_requests SET status = ?1, error = ?2, exit_signal = ?3,
+                                            backup_path = ?4, acked_at = ?5
+               WHERE request_id = ?6`,
+            [status, ackError || null, exit_signal || null, backup_path || null, now, request_id],
+          );
+          if (status === "stopped" && row.action === "stop") {
+            db.run(`UPDATE nodes SET lifecycle_state = 'stopped' WHERE node_id = ?1`, [row.child_node_id]);
+            auditCreateNodeStrict({
+              action: "stop_node_completed",
+              user_id: null, network_id: row.network_id, target_id: request_id,
+              detail: {
+                child_node_id: row.child_node_id, child_alias: row.child_alias,
+                exit_signal: exit_signal || null, ts_daemon_ack: now,
+                lifecycle_state_after: "stopped",
+              },
+            });
+          } else if (status === "stopped" && row.action === "delete") {
+            // Revoke the child's ntok (name='node:<alias>') in the daemon's
+            // network, then DELETE the nodes row. Token revoke pattern mirrors
+            // ack_create_request's terminal path.
+            db.run(
+              `UPDATE api_tokens SET revoked_at = datetime('now')
+                 WHERE network_id = ?1 AND name = ?2 AND revoked_at IS NULL`,
+              [row.network_id, `node:${row.child_alias}`],
+            );
+            db.run(`DELETE FROM nodes WHERE node_id = ?1`, [row.child_node_id]);
+            auditCreateNodeStrict({
+              action: "delete_node_completed",
+              user_id: null, network_id: row.network_id, target_id: request_id,
+              detail: {
+                child_node_id: row.child_node_id, child_alias: row.child_alias,
+                exit_signal: exit_signal || null, backup_path: backup_path || null,
+                ts_daemon_ack: now, lifecycle_state_after: "deleted",
+              },
+            });
+          } else if (status === "stop_failed") {
+            db.run(`UPDATE nodes SET lifecycle_state = 'stop_failed' WHERE node_id = ?1`, [row.child_node_id]);
+            // No completion audit; the failure error is on the request row.
+          }
+          // noop_not_my_child: leave lifecycle_state as-is; the hub-side
+          // sweeper / next reconciliation will pick it up. Don't transition.
+        });
+      } catch (e: any) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "finalize_tx_failed", message: e?.message || String(e) }) }] };
+      }
+
+      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, status }) }] };
+    },
+  );
+
+  // RFC-027 PR1.1 — list_my_children: daemon-only query. Returns the
+  // {child_node_id, alias, lifecycle_state} tuples for nodes whose
+  // active create-request has this daemon as daemon_node_id. Used at
+  // daemon boot to rebuild the in-memory childrenMap (PR1 dropped
+  // every entry on daemon restart → stop/delete silently no-op'd).
+  //
+  // Network-scope is the daemon's own (resolveCallerDaemonTokenBound
+  // already binds tokenIsNetwork to a single network). No SEC-1 leak:
+  // returns ONLY children whose request landed under this daemon's
+  // 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.",
+    {},
+    async () => {
+      const callerDaemon = resolveCallerDaemonTokenBound();
+      if (!callerDaemon.ok) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: callerDaemon.error }) }] };
+      }
+      // node_create_requests carries the canonical authoritative
+      // child→daemon mapping (the row id IS the request, and the
+      // child node_id derives from it deterministically via
+      // `node_${request_id.replace(/^cr_/, "")}`). Filter to children
+      // that completed registration (have a nodes row) so we don't
+      // ask the daemon to pgrep for children that never came up.
+      const rows = db.all<{ request_id: string; child_name: string; child_node_id: string; lifecycle_state: string | null }>(
+        `SELECT ncr.request_id, ncr.child_name,
+                ('node_' || substr(ncr.request_id, 4)) AS child_node_id,
+                n.lifecycle_state
+           FROM node_create_requests ncr
+           LEFT JOIN nodes n ON n.node_id = ('node_' || substr(ncr.request_id, 4))
+          WHERE ncr.daemon_node_id = ?1
+            AND ncr.network_id = ?2
+            AND ncr.status IN ('succeeded', 'delivered')
+            AND n.node_id IS NOT NULL
+            AND COALESCE(n.lifecycle_state, 'active') NOT IN ('stopped', 'stop_failed')`,
+        callerDaemon.daemonNodeId, callerDaemon.networkId,
+      );
+      const children = rows.map(r => ({
+        child_node_id: r.child_node_id,
+        alias: r.child_name,
+        lifecycle_state: r.lifecycle_state ?? "active",
+      }));
+      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, count: children.length, children }) }] };
+    },
+  );
+
+  // ── RFC-028 P1 — Provider & Model Registry + connectivity probe ──
+  // Background timers (probe GC + sweeper) idempotent; safe to call
+  // per registerTools.
+  startPendingProbeGcTimer();
+  startProbeSweeperTimer();
+
+  // Helper: zod to JSON-RPC reply for ProbeValidationError + VaultError
+  const probeFailReply = (e: unknown) => {
+    if (e instanceof ProbeValidationError) {
+      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: e.code, ...(e.detail || {}) }) }] };
+    }
+    if (e instanceof VaultError) {
+      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: e.code, message: e.message }) }] };
+    }
+    throw e;
+  };
+
+  // §2.3.4 — upsert_network_secret (OWNER-ONLY; vault write).
+  server.tool(
+    "upsert_network_secret",
+    "Write or replace a secret value in the network's vault (AES-GCM encrypted at rest). OWNER-only. RFC-028.",
+    {
+      key: z.string().min(1).max(64).regex(/^[A-Z][A-Z0-9_]{0,63}$/),
+      value: z.string().min(1).max(16 * 1024),
+      network_id: z.string().max(200).optional(),
+    },
+    async ({ key, value, network_id: clientNetId }) => {
+      const effectiveNetId = getNetworkId(clientNetId);
+      if (!canWrite(effectiveNetId)) return writeDeniedReply(effectiveNetId, "write");
+      const callerRole = enforceUserId && effectiveNetId
+        ? getUserNetworkRole(enforceUserId, effectiveNetId)
+        : null;
+      if (callerRole !== "owner") {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "secret_owner_only", required_role: "owner", caller_role: callerRole }) }] };
+      }
+      try {
+        vaultUpsert(effectiveNetId || "default", key, value);
+        auditCreateNode({
+          action: "create_node_dispatched",  // reusing audit_log shape (provider follow-up logs)
+          user_id: enforceUserId, network_id: effectiveNetId, target_id: null,
+          detail: { op: "vault_upsert", key, network_id: effectiveNetId },
+        });
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, key }) }] };
+      } catch (e) {
+        return probeFailReply(e);
+      }
+    },
+  );
+
+  // §2.3.4b — list_network_secrets (key names only; viewer+).
+  server.tool(
+    "list_network_secrets",
+    "List vault key NAMES (NEVER values) for a network. RFC-028.",
+    { network_id: z.string().max(200).optional() },
+    async ({ network_id: clientNetId }) => {
+      const effectiveNetId = getNetworkId(clientNetId);
+      if (!canWrite(effectiveNetId) && enforceUserId) {
+        // viewer-level: allow if caller has any role in network
+        const role = getUserNetworkRole(enforceUserId, effectiveNetId || "default");
+        if (!role) return writeDeniedReply(effectiveNetId, "read");
+      }
+      const keys = vaultListKeys(effectiveNetId || "default");
+      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, keys }) }] };
+    },
+  );
+
+  // §2.3.1 — upsert_provider (admin+).
+  server.tool(
+    "upsert_provider",
+    "Create or update a provider (vendor + base_url + secret_key_ref + initial models). Admin+. RFC-028.",
+    {
+      name: z.string().min(1).max(100),
+      vendor: z.string().min(1).max(64),
+      base_url: z.string().min(1).max(500),
+      secret_key_ref: z.string().min(1).max(64),
+      models: z.array(z.object({
+        model_name: z.string().min(1).max(100),
+        display_name: z.string().max(100).optional(),
+        context_window: z.number().int().min(0).optional(),
+        supports_vision: z.boolean().optional(),
+      })).optional(),
+      network_id: z.string().max(200).optional(),
+    },
+    async ({ name, vendor, base_url, secret_key_ref, models, 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_provider", required_role: "admin", caller_role: callerRole }) }] };
+      }
+      try {
+        _validateBaseUrl(vendor, base_url);
+      } catch (e) {
+        return probeFailReply(e);
+      }
+      // Verify vault key exists (best-effort; just lists names)
+      const vaultKeys = vaultListKeys(effectiveNetId || "default");
+      if (!vaultKeys.includes(secret_key_ref)) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "secret_not_in_vault", key: secret_key_ref, hint: "upsert_network_secret first" }) }] };
+      }
+      const providerId = `prov_${uuidv4()}`;
+      try {
+        db.run(
+          `INSERT INTO providers (provider_id, network_id, name, vendor, base_url, secret_key_ref, created_at, created_by, enabled)
+           VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, 1)`,
+          [providerId, effectiveNetId || "default", name, vendor, base_url, secret_key_ref, Date.now(), enforceUserId || "unknown"],
+        );
+      } catch (e: any) {
+        if (/UNIQUE constraint failed/.test(e?.message || "")) {
+          return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "provider_name_conflict", name }) }] };
+        }
+        throw e;
+      }
+      const modelIds: string[] = [];
+      if (models) {
+        for (const m of models) {
+          const mid = `pm_${uuidv4()}`;
+          db.run(
+            `INSERT INTO provider_models (model_id, provider_id, model_name, display_name, context_window, supports_vision, enabled, created_at)
+             VALUES (?1, ?2, ?3, ?4, ?5, ?6, 1, ?7)`,
+            [mid, providerId, m.model_name, m.display_name ?? null, m.context_window ?? null, m.supports_vision ? 1 : 0, Date.now()],
+          );
+          modelIds.push(mid);
+        }
+      }
+      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, provider_id: providerId, model_ids: modelIds }) }] };
+    },
+  );
+
+  // §2.3.2 — update_provider (admin+; patch semantics). RFC-028 P1.5.
+  // Single tool for editing existing providers — patch model: name/base_url/
+  // models/enabled all optional, at least one required. Vendor and
+  // secret_key_ref are IMMUTABLE via this tool (vendor change = create+delete;
+  // secret change goes through upsert_network_secret first). network_id is
+  // immutable (cross-tenant move forbidden).
+  //
+  // base_url change re-runs validateBaseUrl with vendor read from DB row
+  // (NOT from patch) — defends against trying to widen host allowlist by
+  // smuggling a new vendor name. zod .strict() on the wrapping object
+  // surfaces extras as -32602 at MCP boundary (R3 lock, same as
+  // ack_probe_request per #308 fold-in).
+  //
+  // Audit: every successful update writes audit_log with before/after diff
+  // of the changed fields ONLY (no secret values — secret isn't a patch
+  // field, no leak path).
+  server.registerTool(
+    "update_provider",
+    {
+      description: "Edit existing provider (name/base_url/models/enabled). Patch semantics — at least one field. Vendor/secret/network_id immutable. Admin+. RFC-028 P1.5.",
+      inputSchema: z.object({
+        provider_id: z.string().regex(/^prov_[a-zA-Z0-9_-]+$/).max(200),
+        network_id: z.string().max(200).optional(),
+        patch: z.object({
+          name: z.string().min(1).max(100).optional(),
+          base_url: z.string().min(1).max(500).optional(),
+          models: z.array(z.object({
+            model_name: z.string().min(1).max(100),
+            display_name: z.string().max(100).optional(),
+            context_window: z.number().int().min(0).optional(),
+            supports_vision: z.boolean().optional(),
+          })).optional(),
+          enabled: z.boolean().optional(),
+        }).strict(),
+      }).strict() as any,
+    },
+    async (args: any) => {
+      const { provider_id, network_id: clientNetId, patch } = args;
+      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_provider", required_role: "admin", caller_role: callerRole }) }] };
+      }
+
+      // Empty patch — surface noop_no_changes (don't silently succeed)
+      const patchKeys = Object.keys(patch || {});
+      if (patchKeys.length === 0) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "noop_no_changes", hint: "patch must include at least one of: name, base_url, models, enabled" }) }] };
+      }
+
+      // SEC-1: row must exist within caller's network (SQL-level enforcement)
+      const row = db.get<{ provider_id: string; vendor: string; name: string; base_url: string; enabled: number }>(
+        `SELECT provider_id, vendor, name, base_url, enabled FROM providers WHERE provider_id = ?1 AND network_id = ?2`,
+        provider_id, effectiveNetId || "default",
+      );
+      if (!row) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "provider_not_found", provider_id }) }] };
+      }
+
+      // base_url change → re-run validateBaseUrl with vendor from DB (not patch)
+      if (patch.base_url !== undefined && patch.base_url !== row.base_url) {
+        try {
+          _validateBaseUrl(row.vendor, patch.base_url);
+        } catch (e) {
+          return probeFailReply(e);
+        }
+      }
+
+      // Diff staging — collect before/after for audit (NO secret values; secret
+      // isn't a patch field). Skip fields that didn't actually change.
+      const diff: Record<string, { before: unknown; after: unknown }> = {};
+      const sets: string[] = [];
+      const params: unknown[] = [];
+      let paramIdx = 1;
+      if (patch.name !== undefined && patch.name !== row.name) {
+        sets.push(`name = ?${paramIdx++}`); params.push(patch.name);
+        diff.name = { before: row.name, after: patch.name };
+      }
+      if (patch.base_url !== undefined && patch.base_url !== row.base_url) {
+        sets.push(`base_url = ?${paramIdx++}`); params.push(patch.base_url);
+        diff.base_url = { before: row.base_url, after: patch.base_url };
+      }
+      if (patch.enabled !== undefined) {
+        const newEnabled = patch.enabled ? 1 : 0;
+        if (newEnabled !== row.enabled) {
+          sets.push(`enabled = ?${paramIdx++}`); params.push(newEnabled);
+          diff.enabled = { before: row.enabled === 1, after: patch.enabled };
+        }
+      }
+
+      // Replace models list (if supplied) atomically with the providers UPDATE
+      const willReplaceModels = patch.models !== undefined;
+      const newModelIds: string[] = [];
+
+      // No-op early return (通信牛 nit): all patch fields matched the
+      // existing row values + no models supplied → no real change to
+      // persist. Returning here means we don't write an empty-diff
+      // audit row (audit noise). Audit_log INSERT must only fire when
+      // something actually changed.
+      if (sets.length === 0 && !willReplaceModels) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, provider_id, no_changes: true, hint: "patch fields matched existing row, no-op" }) }] };
+      }
+
+      try {
+        db.exec("BEGIN");
+        if (sets.length > 0) {
+          params.push(provider_id);
+          try {
+            db.run(`UPDATE providers SET ${sets.join(", ")} WHERE provider_id = ?${paramIdx}`, params);
+          } catch (e: any) {
+            if (/UNIQUE constraint failed/.test(e?.message || "")) {
+              db.exec("ROLLBACK");
+              return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "provider_name_conflict", name: patch.name }) }] };
+            }
+            throw e;
+          }
+        }
+        if (willReplaceModels) {
+          db.run(`DELETE FROM provider_models WHERE provider_id = ?1`, [provider_id]);
+          for (const m of patch.models) {
+            const mid = `pm_${uuidv4()}`;
+            db.run(
+              `INSERT INTO provider_models (model_id, provider_id, model_name, display_name, context_window, supports_vision, enabled, created_at)
+               VALUES (?1, ?2, ?3, ?4, ?5, ?6, 1, ?7)`,
+              [mid, provider_id, m.model_name, m.display_name ?? null, m.context_window ?? null, m.supports_vision ? 1 : 0, Date.now()],
+            );
+            newModelIds.push(mid);
+          }
+          diff.models = { before: "(prior list)", after: `${patch.models.length} models replaced` };
+        }
+        db.run(
+          `INSERT INTO audit_log (user_id, username, action, target_type, target_id, detail, network_id)
+           VALUES (?1, ?2, 'update_provider', 'provider', ?3, ?4, ?5)`,
+          [enforceUserId || null, callerAlias || null, provider_id, JSON.stringify({ diff, fields_changed: Object.keys(diff) }), effectiveNetId || null],
+        );
+        db.exec("COMMIT");
+      } catch (e: any) {
+        try { db.exec("ROLLBACK"); } catch { /* ok */ }
+        throw e;
+      }
+
+      return { content: [{ type: "text" as const, text: JSON.stringify({
+        ok: true, provider_id,
+        fields_changed: Object.keys(diff),
+        models_replaced: willReplaceModels ? newModelIds.length : null,
+      }) }] };
+    },
+  );
+
+  // §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.",
+    { network_id: z.string().max(200).optional() },
+    async ({ network_id: clientNetId }) => {
+      const effectiveNetId = getNetworkId(clientNetId);
+      // viewer access: caller must be member of network (read access)
+      if (enforceUserId) {
+        const role = getUserNetworkRole(enforceUserId, effectiveNetId || "default");
+        if (!role) return writeDeniedReply(effectiveNetId, "read");
+      }
+      const providers = db.all<any>(
+        `SELECT provider_id, name, vendor, base_url, secret_key_ref, enabled FROM providers WHERE network_id = ?1 AND enabled = 1 ORDER BY name`,
+        effectiveNetId || "default",
+      );
+      const out = providers.map(p => {
+        const models = db.all<any>(
+          `SELECT model_id, model_name, display_name, context_window, supports_vision, enabled FROM provider_models WHERE provider_id = ?1 AND enabled = 1 ORDER BY model_name`,
+          p.provider_id,
+        );
+        return { ...p, in_vault: true, models };  // in_vault: true since we required it on upsert
+      });
+      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, providers: out }) }] };
+    },
+  );
+
+  // §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.",
+    {
+      provider_id: z.string().min(1).max(200),
+      model_name: z.string().min(1).max(100),
+      daemon_node_id: z.string().min(1).max(200),
+      network_id: z.string().max(200).optional(),
+    },
+    async ({ provider_id, model_name, 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_probe", required_role: "admin", caller_role: callerRole }) }] };
+      }
+      // Resolve provider + model (network-scoped). Distinguish "not found"
+      // from "disabled" so the dashboard can render the right error
+      // (P1.5 dashboard编辑/停用 needs this to explain why probe rejected).
+      const provider = db.get<any>(
+        `SELECT provider_id, vendor, base_url, secret_key_ref, enabled FROM providers WHERE provider_id = ?1 AND network_id = ?2`,
+        provider_id, effectiveNetId || "default",
+      );
+      if (!provider) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "provider_not_found", provider_id }) }] };
+      if (provider.enabled !== 1) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "provider_disabled", provider_id, hint: "update_provider with enabled:true to re-enable" }) }] };
+      const model = db.get<any>(
+        `SELECT model_id, model_name FROM provider_models WHERE provider_id = ?1 AND model_name = ?2 AND enabled = 1`,
+        provider_id, model_name,
+      );
+      if (!model) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "model_not_found", model_name }) }] };
+      // Resolve daemon (must be in caller network)
+      const { row: daemon, sec1Ok } = resolveTargetNode(daemon_node_id, effectiveNetId);
+      if (!daemon) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "daemon_not_found" }) }] };
+      if (!sec1Ok) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "cross_network_node" }) }] };
+      // Vault decrypt the API key (may throw VaultError)
+      let apiKey: string;
+      try {
+        const v = vaultGet(effectiveNetId || "default", provider.secret_key_ref);
+        if (!v) return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "secret_not_in_vault", key: provider.secret_key_ref }) }] };
+        apiKey = v;
+      } catch (e) { return probeFailReply(e); }
+      // Mint probe row + stash ephemeral blob
+      const probeId = newProbeId();
+      db.run(
+        `INSERT INTO probe_results (probe_id, provider_id, model_name, daemon_node_id, network_id, status, probed_at, probed_by_user)
+         VALUES (?1, ?2, ?3, ?4, ?5, 'pending', ?6, ?7)`,
+        [probeId, provider_id, model_name, daemon_node_id, effectiveNetId || "default", Date.now(), enforceUserId || null],
+      );
+      putPendingProbeSecret({
+        probe_id: probeId,
+        daemon_node_id,
+        provider_id,
+        vendor: provider.vendor,
+        base_url: provider.base_url,
+        model_name,
+        api_key: apiKey,
+        network_id: effectiveNetId || "default",
+      });
+      pushEvent(daemon.alias, { type: "probe_provider", probe_id: probeId }, daemon.network_id || effectiveNetId || "default");
+      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, probe_id: probeId }) }] };
+    },
+  );
+
+  // §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.",
+    {
+      provider_id: z.string().max(200).optional(),
+      model_name: z.string().max(100).optional(),
+      daemon_node_id: z.string().max(200).optional(),
+      limit: z.number().int().min(1).max(500).optional(),
+      network_id: z.string().max(200).optional(),
+    },
+    async ({ provider_id, model_name, daemon_node_id, limit, network_id: clientNetId }) => {
+      const effectiveNetId = getNetworkId(clientNetId);
+      if (enforceUserId) {
+        const role = getUserNetworkRole(enforceUserId, effectiveNetId || "default");
+        if (!role) return writeDeniedReply(effectiveNetId, "read");
+      }
+      const where: string[] = ["network_id = ?1"];
+      const params: any[] = [effectiveNetId || "default"];
+      if (provider_id)    { where.push(`provider_id = ?${params.length + 1}`); params.push(provider_id); }
+      if (model_name)     { where.push(`model_name = ?${params.length + 1}`); params.push(model_name); }
+      if (daemon_node_id) { where.push(`daemon_node_id = ?${params.length + 1}`); params.push(daemon_node_id); }
+      const sql = `SELECT probe_id, provider_id, model_name, daemon_node_id, status, latency_ms, error_label, probed_at, raw_status_code FROM probe_results WHERE ${where.join(" AND ")} ORDER BY probed_at DESC LIMIT ${limit ?? 100}`;
+      const rows = db.all<any>(sql, ...params);
+      return { content: [{ type: "text" as const, text: JSON.stringify({ ok: true, results: rows }) }] };
+    },
+  );
+
+  // §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.",
+    { probe_id: z.string().min(1).max(200) },
+    async ({ probe_id }) => {
+      const callerDaemon = _resolveCallerDaemonTokenBound({ callerTokenIsNetwork, callerTokenId, enforceNetworkId });
+      if (!callerDaemon.ok) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: callerDaemon.error }) }] };
+      }
+      // takePendingProbeSecret enforces daemon binding + evicts
+      const blob = (await import("./probe.js")).takePendingProbeSecret(probe_id, callerDaemon.daemonNodeId);
+      if (!blob) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: "probe_request_unavailable", reason: "not_found_or_wrong_daemon_or_expired" }) }] };
+      }
+      return { content: [{ type: "text" as const, text: JSON.stringify({
+        ok: true,
+        probe_id: blob.probe_id,
+        vendor: blob.vendor,
+        base_url: blob.base_url,
+        model_name: blob.model_name,
+        api_key: blob.api_key,        // ephemeral; daemon writes to .env.local or in-memory only
+      }) }] };
+    },
+  );
+
+  // §2.3.8 daemon-facing — ack_probe_request (STRICT whitelist via zod).
+  // R3 LOCK (RFC-028 v3): ack payload has EXACTLY 4 keys. We pass a
+  // ZodObject with .strict() so the MCP SDK's validateToolInput surfaces
+  // any extra field (e.g. an attacker smuggling `error_message` to leak a
+  // secret) as a -32602 Invalid params error at the protocol boundary
+  // BEFORE our handler runs. The SDK invokes z.object(shape) by default
+  // which is strip-mode; passing a fully-constructed strict object
+  // bypasses that and enforces unknownKeys='strict'.
+  server.registerTool(
+    "ack_probe_request",
+    {
+      description: "Daemon acks a probe. Schema is STRICT whitelist (no error_message; v3 R3 LOCK). RFC-028.",
+      // Strict-mode ZodObject so the MCP SDK's validateToolInput surfaces
+      // any extra field as a -32602 Invalid params error BEFORE the
+      // handler runs. server.tool() accepts only ZodRawShape (default
+      // strip-mode); registerTool() accepts a constructed ZodObject and
+      // honors its unknownKeys policy.
+      inputSchema: z.object({
+        probe_id: z.string().min(1).max(200),
+        status: z.enum(["ok", "auth_fail", "quota", "rate_limit", "network_error", "timeout", "redirect_forbidden", "vendor_5xx", "other_4xx", "tls_error", "probe_resolve_unsafe_ip", "probe_target_forbidden"]),
+        raw_status_code: z.number().int().min(100).max(599).optional(),
+        latency_ms: z.number().int().min(0).max(60_000),
+      }).strict() as any,
+    },
+    async (args: any) => {
+      const callerDaemon = _resolveCallerDaemonTokenBound({ callerTokenIsNetwork, callerTokenId, enforceNetworkId });
+      if (!callerDaemon.ok) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ ok: false, error: callerDaemon.error }) }] };
+      }
+      try {
+        const r = finalizeProbeAck(args, { network_id: callerDaemon.networkId, daemon_node_id: callerDaemon.daemonNodeId });
+        return { content: [{ type: "text" as const, text: JSON.stringify(r) }] };
+      } catch (e) {
+        return probeFailReply(e);
+      }
+    },
+  );
 }
 
 // ────────────────────────────────────────────────────────────────────
@@ -1839,10 +3436,144 @@ export function upsertNodeWithSec1Guard(input: UpsertNodeWithSec1GuardInput): Up
     ],
   );
   if (input.config_snapshot) {
+    // RFC-026 §9.3 / #338 PR2+PR3 — promote daemon self-declare fields
+    // to first-class indexable columns alongside the snapshot blob.
+    // The snapshot stays the source of truth for non-list reads; the
+    // columns exist so `list_host_supervisors` doesn't JSON.parse on
+    // every call. typeof-narrow per
+    // [[feedback_typeof_narrow_extracted_fields]] — zod narrowed but
+    // input.config_snapshot is typed `unknown` here.
+    //
+    // PR3 nit ①: read from nested `daemon_capabilities.*` (canonical
+    // per RFC §9.3 + matches existing hub create_node reads at
+    // tools.ts:2010/2075). PR2 ate from top-level keys, which the
+    // hub create_node path never read → max_concurrent_children
+    // backpressure was dead config + allowlist enforcement bypassed.
+    const snap = input.config_snapshot as Record<string, unknown> | null;
+    const caps = (snap?.daemon_capabilities ?? null) as Record<string, unknown> | null;
+    const runtimesRaw = caps?.runtimes_supported;
+    const allowedRaw = caps?.allowed_secret_keys;
+    const runtimesJson = Array.isArray(runtimesRaw) && runtimesRaw.every(s => typeof s === "string")
+      ? JSON.stringify(runtimesRaw)
+      : null;
+    const allowedJson = Array.isArray(allowedRaw) && allowedRaw.every(s => typeof s === "string")
+      ? JSON.stringify(allowedRaw)
+      : null;
     db.run(
-      `UPDATE nodes SET config_snapshot = ?1 WHERE node_id = ?2`,
-      [JSON.stringify(input.config_snapshot), input.node_id],
+      `UPDATE nodes SET config_snapshot = ?1, runtimes_supported = ?2, allowed_secret_keys = ?3 WHERE node_id = ?4`,
+      [JSON.stringify(input.config_snapshot), runtimesJson, allowedJson, input.node_id],
     );
+    // RFC-024 — finalize any pending/restarting update whose target
+    // patch is now reflected in the snapshot. Closes the
+    // restart-required-never-reaches-applied gap that 通信牛 caught:
+    // the old child acks `restarting` + exits 75; the new child boots,
+    // reads the new config, reports status — but never had the
+    // update_id to call ack_config_update(applied) itself. Hub does
+    // it on the new child's behalf by content-matching the patch
+    // against the reported snapshot.
+    finalizePendingMatchingUpdates(input.node_id, input.config_snapshot);
+  }
+  // RFC-026 §2.5 step 4 — on every register/report_status, opportunistically
+  // close out any pending create_node request whose child_name matches
+  // this incoming alias. Same content-match pattern as RFC-024's
+  // finalizePendingMatchingUpdates; the new child doesn't have the
+  // request_id, so hub does the matching on its behalf.
+  try {
+    finalizeCreateOnFirstRegister({
+      node_id: input.node_id,
+      alias: input.alias || input.node_name || "",
+      network_id: input.callerNetworkId ?? null,
+    });
+  } catch (e: any) {
+    // create-node finalize is best-effort — never block report_status
+    // on it. Log + continue.
+    console.warn(`[commhub] create-node finalize on report_status failed: ${e?.message || e}`);
   }
   return { result: existing ? "updated" : "inserted", node_id: input.node_id };
 }
+
+/**
+ * RFC-024 restart-finalize (Option A per 通信牛 final review).
+ *
+ * Called from `upsertNodeWithSec1Guard` after writing a fresh
+ * `config_snapshot` for the node. For each pending/restarting update
+ * row, parse the patch and compare every field against the snapshot.
+ * If everything in the patch is now reflected in the live snapshot,
+ * mark the update applied + bump `nodes.config_revision`. The new
+ * child doesn't need to know the update_id — content-matching against
+ * the live state IS the proof that the apply landed.
+ *
+ * Edge cases:
+ *   - Empty patch (apply_mode=restart_only from `restart_node` tool) →
+ *     ANY snapshot matches (the restart itself was the goal).
+ *   - Patch field absent from snapshot → not a match (snapshot
+ *     post-dates the apply only when every requested field shows up).
+ *   - Multiple concurrent pending rows → impossible by single-flight,
+ *     but defensive: finalize OLDEST first so the chain stays linear.
+ *
+ * Pure-ish: takes a snapshot blob (TS shape, see config-snapshot type)
+ * and runs only db.run / db.get. No external IO.
+ */
+export function finalizePendingMatchingUpdates(
+  nodeId: string,
+  snapshot: any,
+): { finalizedCount: number; finalizedIds: string[] } {
+  const pending = db.all<{
+    update_id: string;
+    patch_json: string;
+    apply_mode: string;
+    base_revision: number;
+  }>(
+    "SELECT update_id, patch_json, apply_mode, base_revision FROM node_config_updates WHERE node_id = ?1 AND status IN ('pending', 'restarting') ORDER BY created_at ASC",
+    nodeId,
+  );
+  if (pending.length === 0) return { finalizedCount: 0, finalizedIds: [] };
+
+  const snapModel: string | null | undefined = snapshot?.model;
+  const snapFlags: Record<string, unknown> = (snapshot?.flags && typeof snapshot.flags === "object") ? snapshot.flags : {};
+
+  const finalizedIds: string[] = [];
+
+  for (const row of pending) {
+    let patch: any = {};
+    try { patch = JSON.parse(row.patch_json); } catch { continue; }
+
+    let matches = true;
+    // restart_only / empty patch → any snapshot proves the restart
+    // happened, finalize unconditionally.
+    if (row.apply_mode !== "restart_only") {
+      if (patch.model !== undefined) {
+        if (snapModel !== patch.model) { matches = false; }
+      }
+      if (matches && patch.flags && typeof patch.flags === "object") {
+        for (const [k, v] of Object.entries(patch.flags as Record<string, unknown>)) {
+          // Canonical-key fallback for legacy aliases. The dashboard
+          // schema uses `budget` and `timeout`; node-side config may
+          // also carry the older `maxBudgetUsd` / `claudeTimeoutMs` /
+          // `codexTimeoutMs` keys. agent-node's buildConfigSnapshot
+          // only reports the canonical key, so we just compare on `k`.
+          if (snapFlags[k] !== v) { matches = false; break; }
+        }
+      }
+    }
+
+    if (!matches) continue;
+
+    // Promote nodes.config_revision atomically with the update row.
+    const nextRev = (db.get<{ config_revision: number }>(
+      "SELECT config_revision FROM nodes WHERE node_id = ?1",
+      nodeId,
+    )?.config_revision || 0) + 1;
+    db.run(
+      "UPDATE node_config_updates SET status = 'applied', acked_at = ?1, new_revision = ?2 WHERE update_id = ?3 AND status IN ('pending', 'restarting')",
+      [Date.now(), nextRev, row.update_id],
+    );
+    db.run("UPDATE nodes SET config_revision = ?1 WHERE node_id = ?2", [nextRev, nodeId]);
+    finalizedIds.push(row.update_id);
+    console.log(
+      `[commhub] ✓ finalize update ${row.update_id} via report_status content-match: node=${nodeId} new_revision=${nextRev} apply_mode=${row.apply_mode}`,
+    );
+  }
+
+  return { finalizedCount: finalizedIds.length, finalizedIds };
+}