comisai 1.0.37 → 1.0.41

package/node_modules/@comis/daemon/dist/rpc/config-handlers.js

@@ -1,1008 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Config and gateway infrastructure RPC handler methods.
- * Covers 10 methods:
- *   config.read, config.patch, config.apply, config.schema,
- *   config.history, config.diff, config.rollback, config.gc,
- *   gateway.restart, gateway.status
- * Extracted from daemon.ts rpcCallInner switch block
- * @module
- */
-import { isImmutableConfigPath, getConfigSchema, getConfigSections, deepMerge, AppConfigSchema, redactConfigSecrets, warnSuspiciousEnvValues, findUnresolvedEnvRefs, formatMissingEnvRefError, getManagedSectionRedirect, formatRedirectHint, } from "@comis/core";
-import { suppressError } from "@comis/shared";
-import { stringify as yamlStringify } from "yaml";
-import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
-import { dirname } from "node:path";
-import { z } from "zod";
-import { resolveProviderCredential } from "./credential-resolver.js";
-/**
- * True when the patch key writes a provider/model field.
- * Matches `<id>.provider` or `<id>.model` (leaf only — does not match
- * nested paths like modelFailover.fallbackModels.0.provider, which is
- * deliberately out-of-scope for the credential guard).
- */
-function isAgentProviderOrModelKey(key) {
-    if (!key)
-        return false;
-    return /(^|\.)(provider|model)$/.test(key);
-}
-/**
- * Resolve the provider value the patch is establishing.
- * - For `.provider` patches, the new value IS the provider.
- * - For `.model`-only patches, look up the agent's CURRENT provider
- *   (validates that the agent's existing auth chain still resolves —
- *   surfaces stale broken configs at patch time rather than at next chat).
- * Returns undefined for paths the guard doesn't validate.
- */
-function extractTargetProvider(key, newValue, currentConfig) {
-    if (key.endsWith(".provider")) {
-        return typeof newValue === "string" ? newValue : undefined;
-    }
-    if (key.endsWith(".model")) {
-        const agentId = key.split(".")[0];
-        if (!agentId)
-            return undefined;
-        // eslint-disable-next-line security/detect-object-injection -- agents map is typed Record; agentId from validated key
-        return currentConfig.agents?.[agentId]?.provider;
-    }
-    return undefined;
-}
-/**
- * Restore MCP server `env` from existing YAML when the UI patch
- * omits it (because config.read redacted secret values to "[REDACTED]").
- * Since deepMerge replaces arrays entirely, we must restore env from the
- * existing YAML before validation/write so that ${VAR_NAME} refs survive.
- */
-function restoreMcpServerEnv(patch, existingLocal) {
-    // Navigate to integrations.mcp.servers in both patch and existing
-    const patchInteg = patch.integrations;
-    const patchMcp = patchInteg?.mcp;
-    const patchServers = patchMcp?.servers;
-    if (!Array.isArray(patchServers))
-        return;
-    const existInteg = existingLocal.integrations;
-    const existMcp = existInteg?.mcp;
-    const existServers = existMcp?.servers;
-    if (!Array.isArray(existServers))
-        return;
-    // Build name→env lookup from existing YAML servers
-    const envByName = new Map();
-    for (const s of existServers) {
-        if (s && typeof s === "object" && typeof s.name === "string" && s.env) {
-            envByName.set(s.name, s.env);
-        }
-    }
-    // Restore env for patch servers that are missing it but had env in YAML
-    for (const s of patchServers) {
-        if (s && typeof s === "object") {
-            const server = s;
-            if (!server.env && typeof server.name === "string") {
-                const existingEnv = envByName.get(server.name);
-                if (existingEnv) {
-                    server.env = existingEnv;
-                }
-            }
-        }
-    }
-}
-/**
- * Reject config patches that contain duplicate MCP server names.
- * Protects against both GUI and agent tool adding servers with the same name.
- */
-function rejectDuplicateMcpServerNames(patch) {
-    const patchInteg = patch.integrations;
-    const patchMcp = patchInteg?.mcp;
-    const patchServers = patchMcp?.servers;
-    if (!Array.isArray(patchServers))
-        return;
-    const seen = new Set();
-    for (const s of patchServers) {
-        if (s && typeof s === "object") {
-            const name = s.name;
-            if (typeof name === "string") {
-                if (seen.has(name)) {
-                    throw new Error(`Duplicate MCP server name: "${name}". Each server must have a unique name.`);
-                }
-                seen.add(name);
-            }
-        }
-    }
-}
-/**
- * Token bucket rate limiter for config.patch.
- * Allows maxTokens patches per windowMs. Refills continuously.
- */
-function createTokenBucket(maxTokens, windowMs) {
-    let tokens = maxTokens;
-    let lastRefill = Date.now();
-    return {
-        tryConsume() {
-            const now = Date.now();
-            const elapsed = now - lastRefill;
-            // Refill proportionally: tokens per ms = maxTokens / windowMs
-            const refilled = (elapsed / windowMs) * maxTokens;
-            tokens = Math.min(maxTokens, tokens + refilled);
-            lastRefill = now;
-            if (tokens >= 1) {
-                tokens -= 1;
-                return { allowed: true };
-            }
-            // Calculate wait time until 1 token is available
-            const deficit = 1 - tokens;
-            const retryAfterMs = Math.ceil((deficit / maxTokens) * windowMs);
-            return { allowed: false, retryAfterMs };
-        },
-    };
-}
-/**
- * Best-effort config change webhook delivery.
- * Sends an HTTP POST to the configured webhook URL with structured payload.
- * Uses AbortSignal.timeout for timeout enforcement. Errors are logged at
- * DEBUG (never thrown) -- webhook failures must never block config writes.
- */
-async function deliverConfigWebhook(opts) {
-    const { webhookConfig, method, section, key, diff, commitSha, metadata, logger } = opts;
-    const payload = {
-        event: "config.changed",
-        method,
-        section,
-        key,
-        diff: diff ?? null,
-        commitSha: commitSha ?? null,
-        metadata: {
-            agent: metadata.agent ?? null,
-            user: metadata.user ?? null,
-            traceId: metadata.traceId ?? null,
-            summary: metadata.summary,
-        },
-        timestamp: new Date().toISOString(),
-    };
-    const body = JSON.stringify(payload);
-    const headers = { "Content-Type": "application/json" };
-    // HMAC-SHA256 signature if secret is configured
-    if (webhookConfig.secret) {
-        const { createHmac } = await import("node:crypto");
-        const sig = createHmac("sha256", webhookConfig.secret).update(body).digest("hex");
-        headers["X-Webhook-Signature"] = `sha256=${sig}`;
-    }
-    try {
-        // SECURITY: webhookConfig.url is admin-configured via daemon config (not user input).
-        // SSRF guard not applied -- only admins can set this URL.
-        const resp = await fetch(webhookConfig.url, {
-            method: "POST",
-            headers,
-            body,
-            signal: AbortSignal.timeout(webhookConfig.timeoutMs ?? 5000),
-        });
-        logger.debug({ method: "webhook.deliver", statusCode: resp.status, webhookUrl: webhookConfig.url }, "Config webhook delivered");
-    }
-    catch (e) {
-        logger.debug({ method: "webhook.deliver", err: e, webhookUrl: webhookConfig.url, hint: "Webhook delivery failed (best-effort)", errorKind: "network" }, "Config webhook delivery failed");
-    }
-}
-/**
- * Unwrap Zod schema wrappers (Optional / Nullable / Default / Pipe) to get
- * the core schema type. Uses Zod 4.x API exclusively:
- *   - ZodOptional / ZodNullable / ZodDefault → _def.innerType
- *   - ZodPipe → _def.in (Zod 4 replaced Zod 3's ZodEffects + ZodPipeline with
- *     a unified ZodPipe class, returned from both .transform() and .pipe()).
- *     Unwrap the input side so coercion targets the schema BEFORE any
- *     transform.
- *   - .refine() in Zod 4 is a no-op wrapper (returns the same class) — no
- *     handler needed.
- *
- * DO NOT reference z.ZodEffects or z.ZodPipeline: those classes do not exist
- * in Zod 4.3.6 and `instanceof` against `undefined` throws TypeError at
- * runtime.
- *
- * Capped at 10 iterations to prevent pathological nesting.
- *
- * @internal — exported only for test-only direct invocation.
- */
-export function unwrapSchema(schema) {
-    if (!schema)
-        return schema;
-    let cur = schema;
-    for (let i = 0; i < 10; i++) {
-        if (cur instanceof z.ZodOptional) {
-            const inner = cur._def?.innerType;
-            if (!inner)
-                break;
-            cur = inner;
-            continue;
-        }
-        if (cur instanceof z.ZodNullable) {
-            const inner = cur._def?.innerType;
-            if (!inner)
-                break;
-            cur = inner;
-            continue;
-        }
-        if (cur instanceof z.ZodDefault) {
-            const inner = cur._def?.innerType;
-            if (!inner)
-                break;
-            cur = inner;
-            continue;
-        }
-        if (cur instanceof z.ZodPipe) {
-            const input = cur._def?.in;
-            if (!input)
-                break;
-            cur = input;
-            continue;
-        }
-        break;
-    }
-    return cur;
-}
-/**
- * Resolve the sub-schema at (section + dot-notation key) from an
- * AppConfigSchema-shaped root. Returns undefined when the path cannot be
- * resolved (unknown section, array-index with non-numeric segment, or a walk
- * that hits a non-navigable schema type). Callers treat undefined as
- * "no coercion target known" and fall back to the legacy heuristic.
- *
- * Supports:
- *   - ZodObject → shape[key]
- *   - ZodArray → element (accepts numeric "N" or bracket-form "[N]" segments)
- *   - ZodRecord → valueType
- *
- * @internal — exported only for test-only direct invocation.
- */
-export function resolveSchemaForPath(root, section, key) {
-    let cur = unwrapSchema(root);
-    if (!(cur instanceof z.ZodObject))
-        return undefined;
-    const sectionSchema = cur.shape[section];
-    if (!sectionSchema)
-        return undefined;
-    cur = unwrapSchema(sectionSchema);
-    if (!key)
-        return cur;
-    const parts = key.split(".");
-    for (const part of parts) {
-        if (!cur)
-            return undefined;
-        if (cur instanceof z.ZodObject) {
-            cur = unwrapSchema(cur.shape[part]);
-        }
-        else if (cur instanceof z.ZodArray) {
-            if (/^\d+$/.test(part) || /^\[\d+\]$/.test(part)) {
-                // ZodArray.element is typed as $ZodType (Zod 4 base); cast to ZodTypeAny.
-                cur = unwrapSchema(cur.element);
-            }
-            else {
-                return undefined;
-            }
-        }
-        else if (cur instanceof z.ZodRecord) {
-            const rec = cur;
-            cur = unwrapSchema(rec.valueType ?? rec._def?.valueType);
-        }
-        else {
-            return undefined;
-        }
-    }
-    return cur;
-}
-/**
- * Coerce string representations of booleans and numbers to their native types,
- * guided by the target Zod sub-schema. LLMs often send "true"/"false"/"42" as
- * strings in tool-call parameters, causing Zod validation failures when the
- * schema expects boolean/number. When the target schema is ZodString (e.g.,
- * the value type of z.record(string, string)), strings pass through verbatim
- * — this prevents spurious coercion of env values like MAX_REQUESTS_PER_HOUR
- * = "20" on MCP server entries (z.record(z.string(), z.string())).
- *
- * Scalar coercion ONLY fires for ZodBoolean and ZodNumber targets. ZodLiteral,
- * ZodEnum, ZodNativeEnum, ZodDate, ZodAny, ZodUnknown, etc. pass strings
- * through unchanged (bias toward loud failure at Zod validation time rather
- * than silent coercion).
- *
- * Recursion descends via ZodObject.shape[k], ZodArray.element, and
- * ZodRecord.valueType. When schema is undefined (unresolved path), falls back
- * to the legacy type-agnostic heuristic for back-compat (e.g. scheduler.cron
- * JSON-stringified object case, tenantId ZodString pass-through).
- *
- * @param value - The value to coerce (from config.patch / config.apply params).
- * @param schema - The Zod sub-schema at this path in AppConfigSchema, or
- *   undefined when the path cannot be resolved.
- * @internal — exported only for test-only direct invocation.
- */
-export function coerceConfigValue(value, schema) {
-    const s = unwrapSchema(schema);
-    if (typeof value === "string") {
-        // Schema-guided coercion (preferred path)
-        if (s instanceof z.ZodString)
-            return value;
-        if (s instanceof z.ZodBoolean) {
-            if (value === "true")
-                return true;
-            if (value === "false")
-                return false;
-            return value;
-        }
-        if (s instanceof z.ZodNumber) {
-            if (value !== "" && !isNaN(Number(value)) && isFinite(Number(value))) {
-                return Number(value);
-            }
-            return value;
-        }
-        if (s instanceof z.ZodUnion || s instanceof z.ZodDiscriminatedUnion) {
-            const options = s.options ??
-                s._def?.options ??
-                [];
-            // If any branch accepts strings, keep as string (bias toward loud failure).
-            if (options.some((o) => unwrapSchema(o) instanceof z.ZodString))
-                return value;
-            // Otherwise fall through to JSON-parse / legacy heuristic below.
-        }
-        // JSON-stringified array/object — parse and recurse with the SAME
-        // sub-schema (parsed value sits at the same logical path).
-        if (value.startsWith("[") || value.startsWith("{")) {
-            try {
-                const parsed = JSON.parse(value);
-                return coerceConfigValue(parsed, schema);
-            }
-            catch {
-                // Not valid JSON — fall through.
-            }
-        }
-        // No schema target known → legacy heuristic (back-compat for unresolved paths).
-        if (schema === undefined) {
-            if (value === "true")
-                return true;
-            if (value === "false")
-                return false;
-            if (value !== "" && !isNaN(Number(value)) && isFinite(Number(value))) {
-                return Number(value);
-            }
-        }
-        return value;
-    }
-    if (Array.isArray(value)) {
-        // ZodArray.element is typed as $ZodType (Zod 4 base); cast to ZodTypeAny.
-        const element = s instanceof z.ZodArray ? s.element : undefined;
-        return value.map((v) => coerceConfigValue(v, element));
-    }
-    if (value !== null && typeof value === "object") {
-        const result = {};
-        for (const [k, v] of Object.entries(value)) {
-            let child;
-            if (s instanceof z.ZodObject) {
-                child = s.shape[k];
-            }
-            else if (s instanceof z.ZodRecord) {
-                const rec = s;
-                child = rec.valueType ?? rec._def?.valueType;
-            }
-            result[k] = coerceConfigValue(v, child);
-        }
-        return result;
-    }
-    return value;
-}
-/**
- * Create config and gateway RPC handlers.
- * @param deps - Injected dependencies (container, config paths)
- * @returns Record mapping method names to handler functions
- */
-export function createConfigHandlers(deps) {
-    // Rate limiter: 5 patches per 60s
-    const patchBucket = createTokenBucket(5, 60_000);
-    return {
-        "config.read": async (params) => {
-            const trustLevel = params._trustLevel;
-            if (trustLevel !== "admin") {
-                throw new Error("Admin access required for config read");
-            }
-            const startMs = Date.now();
-            const section = params.section;
-            if (section) {
-                if (!(section in deps.container.config)) {
-                    throw new Error(`Unknown config section: "${section}". Valid sections: ${getConfigSections().join(", ")}. Hint: channel settings are under "channels".`);
-                }
-                const sectionData = deps.container.config[section];
-                deps.logger.debug({ method: "config.read", durationMs: Date.now() - startMs, outcome: "success", section }, "Config section read");
-                return redactConfigSecrets(sectionData);
-            }
-            const result = {
-                config: redactConfigSecrets(deps.container.config),
-                sections: getConfigSections(),
-            };
-            deps.logger.debug({ method: "config.read", durationMs: Date.now() - startMs, outcome: "success" }, "Full config read");
-            return result;
-        },
-        "config.patch": async (params) => {
-            const trustLevel = params._trustLevel;
-            if (trustLevel !== "admin") {
-                throw new Error("Admin access required for config modification");
-            }
-            // Rate limit check
-            const bucket = patchBucket.tryConsume();
-            if (!bucket.allowed) {
-                deps.logger.warn({ method: "config.patch", hint: "Config patch rate limit exceeded, retry after cooldown", errorKind: "validation", retryAfterMs: bucket.retryAfterMs }, "Config patch rate limited");
-                throw new Error(`Config patch rate limit exceeded: max 5 patches per minute. ` +
-                    `Try again in ${Math.ceil(bucket.retryAfterMs / 1000)} seconds.`);
-            }
-            const startMs = Date.now();
-            // Prefer section/key params; fall back to legacy "path" param (dot-notation) for compat
-            const rawPath = typeof params.path === "string" ? params.path : undefined;
-            const section = (params.section ?? (rawPath ? rawPath.split(".")[0] : undefined));
-            if (!section) {
-                throw new Error('Missing required parameter "section" for config.patch');
-            }
-            const key = (params.key ?? (rawPath && rawPath.includes(".") ? rawPath.slice(rawPath.indexOf(".") + 1) : undefined));
-            const value = params.value;
-            const subSchema = resolveSchemaForPath(AppConfigSchema, section, key);
-            const coercedValue = coerceConfigValue(value, subSchema);
-            const ctx = params._context;
-            try {
-                // Check immutable paths.
-                // Backstop for direct-RPC clients (web UI, CLI). The gateway tool
-                // pre-flight and bridge metadata validator catch this earlier for
-                // LLM tool calls -- this path is reached when those layers are
-                // bypassed. Emit the same redirect hint so all clients see
-                // identical, model-agnostic recovery instructions.
-                if (isImmutableConfigPath(section, key)) {
-                    const redirect = getManagedSectionRedirect(section, key);
-                    const suffix = redirect
-                        ? ` ${formatRedirectHint(redirect)}`
-                        : " This setting requires manual operator intervention via config files.";
-                    throw new Error(`Config path "${key ? `${section}.${key}` : section}" is immutable and cannot be modified at runtime.${suffix}`);
-                }
-                // Credential guard: when a patch targets an agent's provider/model
-                // field, verify the resulting provider's API key is resolvable from
-                // at least one source pi-coding-agent will consult at runtime.
-                // Fail-loud here rather than letting an unauthorized provider
-                // config persist and explode at the next chat turn.
-                //
-                // Model-only patches with unchanged provider introduce no new
-                // credential surface — short-circuit the guard entirely. The
-                // runtime auth chain that just authenticated the LLM call making
-                // this patch will keep working. Stale-broken-config detection
-                // moves back to the next chat turn (fail-loud at the request
-                // boundary), where the message is correctly shaped for the actual
-                // failure mode (not a pre-emptive API-key prompt that is wrong for
-                // OAuth providers like openai-codex).
-                if (section === "agents" && isAgentProviderOrModelKey(key)) {
-                    const targetProvider = extractTargetProvider(key, coercedValue, deps.container.config);
-                    if (targetProvider !== undefined) {
-                        // For `.model` keys, extractTargetProvider returns the agent's
-                        // CURRENT provider (config-handlers.ts:65-69) — so the resolved
-                        // targetProvider always equals the current provider. The
-                        // model-only short-circuit therefore always fires for `.model`
-                        // keys; we still compute the equality explicitly so the
-                        // intent is readable and the check survives any future change
-                        // to extractTargetProvider's contract.
-                        const isModelOnlyPatch = key.endsWith(".model");
-                        const agentId = key.split(".")[0];
-                        // eslint-disable-next-line security/detect-object-injection -- agentId from validated key; agents map is typed Record
-                        const currentProvider = agentId
-                            ? deps.container.config.agents?.[agentId]?.provider
-                            : undefined;
-                        const providerUnchanged = currentProvider === targetProvider;
-                        if (!(isModelOnlyPatch && providerUnchanged)) {
-                            // Provider is changing (or this is a `.provider` patch where
-                            // targetProvider is the new value) — run the credential guard.
-                            // eslint-disable-next-line security/detect-object-injection -- agentId from validated key; agents map is typed Record
-                            const agentOauthProfiles = (agentId
-                                ? deps.container.config.agents?.[agentId]?.oauthProfiles
-                                : undefined);
-                            // Pre-resolve the loader has() for the configured profile so the
-                            // resolver can stay synchronous. This keeps Hexagonal port-side
-                            // validators I/O-free.
-                            // eslint-disable-next-line security/detect-object-injection -- typed Record<string, string> read; targetProvider validated above
-                            const configuredProfileId = agentOauthProfiles?.[targetProvider];
-                            let loaderHasProfile = false;
-                            if (configuredProfileId && deps.oauthCredentialStore) {
-                                const hasResult = await deps.oauthCredentialStore.has(configuredProfileId);
-                                loaderHasProfile = hasResult.ok && hasResult.value === true;
-                            }
-                            const resolution = resolveProviderCredential(targetProvider, {
-                                providerEntries: deps.container.config.providers?.entries ?? {},
-                                secretManager: deps.container.secretManager,
-                                modelsConfig: deps.container.config.models,
-                                oauthProfiles: agentOauthProfiles,
-                                oauthProfileLoader: configuredProfileId
-                                    ? { has: (id) => id === configuredProfileId && loaderHasProfile }
-                                    : undefined,
-                            });
-                            if (!resolution.ok) {
-                                deps.logger.warn({
-                                    method: "config.patch",
-                                    section,
-                                    key,
-                                    targetProvider,
-                                    hint: "Provider credential not resolvable",
-                                    errorKind: "validation",
-                                }, "Config patch rejected: missing provider credential");
-                                throw new Error(resolution.reason);
-                            }
-                        }
-                    }
-                }
-                // Build patch object (use coerced value for the actual data, keep original for audit)
-                let patch;
-                if (key) {
-                    // Support dot-notation keys: "budget.maxTokens" -> { section: { budget: { maxTokens: value } } }
-                    const keyParts = key.split(".");
-                    const nested = {};
-                    let current = nested;
-                    for (let i = 0; i < keyParts.length - 1; i++) {
-                        const child = {};
-                        current[keyParts[i]] = child;
-                        current = child;
-                    }
-                    current[keyParts[keyParts.length - 1]] = coercedValue;
-                    patch = { [section]: nested };
-                }
-                else {
-                    patch = { [section]: coercedValue };
-                }
-                // Deep merge and validate
-                const merged = deepMerge(structuredClone(deps.container.config), patch);
-                const validation = AppConfigSchema.safeParse(merged);
-                if (!validation.success) {
-                    const issues = validation.error.issues
-                        .map((i) => `${i.path.join(".")}: ${i.message}`)
-                        .join("; ");
-                    throw new Error(`Config validation failed: ${issues}`);
-                }
-                // Determine config.local.yaml path (last entry from configPaths or default)
-                const localPath = deps.configPaths.length > 0
-                    ? deps.configPaths[deps.configPaths.length - 1]
-                    : deps.defaultConfigPaths[deps.defaultConfigPaths.length - 1];
-                // Read existing local config (if exists), merge patch into it
-                let existingLocal = {};
-                if (existsSync(localPath)) {
-                    try {
-                        const raw = readFileSync(localPath, "utf-8");
-                        const { parse: parseYaml } = await import("yaml");
-                        const parsed = parseYaml(raw);
-                        if (parsed && typeof parsed === "object") {
-                            existingLocal = parsed;
-                        }
-                    }
-                    catch {
-                        // If read/parse fails, start fresh
-                    }
-                }
-                // Restore MCP server env from existing YAML when UI sends
-                // servers without env (stripped because config.read redacts secrets).
-                // Arrays replace entirely in deepMerge, so we must restore env here.
-                restoreMcpServerEnv(patch, existingLocal);
-                // Reject duplicate MCP server names in patch
-                rejectDuplicateMcpServerNames(patch);
-                // Scan for suspicious env values (bare $VAR, [REDACTED], raw keys)
-                const envWarnings = warnSuspiciousEnvValues(patch, section);
-                if (envWarnings.length > 0) {
-                    const hints = envWarnings.map((w) => `${w.path}: "${w.value}" — ${w.hint}`).join("; ");
-                    throw new Error(`Suspicious env value(s) in config patch: ${hints}. ` +
-                        `Use \${VAR_NAME} syntax to reference secrets stored via env_set.`);
-                }
-                // Reject patches that reference env vars not in the secrets store, on
-                // enabled MCP servers only. The env-substitution skip on disabled
-                // servers makes `enabled:false + ${VAR}` harmless at bootstrap; this
-                // gate forbids the partially-valid `enabled:true + missing ${VAR}`
-                // shape.
-                //
-                // We walk `patch` (not the deep-merged config) because we only
-                // validate what's being WRITTEN this RPC. `restoreMcpServerEnv` above
-                // already restored env from existing YAML for partial-update-without-
-                // env patches, so `patch.integrations.mcp.servers[].env` is the
-                // post-restore truth. Full-config validation would re-flag pre-
-                // existing valid-at-write-time refs whose secrets were later removed
-                // (out of scope, separate problem).
-                const patchInteg = patch.integrations;
-                const patchMcp = patchInteg?.mcp;
-                const patchServers = patchMcp?.servers;
-                if (Array.isArray(patchServers)) {
-                    for (const s of patchServers) {
-                        if (!s || typeof s !== "object")
-                            continue;
-                        const server = s;
-                        // McpServerEntrySchema.enabled defaults to true → absent = enabled.
-                        // Only explicit `enabled: false` skips the check (preserves the
-                        // placeholder-for-later pattern).
-                        if (server.enabled === false)
-                            continue;
-                        if (!server.env)
-                            continue;
-                        const serverName = typeof server.name === "string" ? server.name : "<unnamed>";
-                        const unresolved = findUnresolvedEnvRefs(server.env, (key) => deps.container.secretManager.get(key));
-                        if (unresolved.length > 0) {
-                            const missingNames = unresolved.map((u) => u.varName);
-                            throw new Error(formatMissingEnvRefError(serverName, missingNames));
-                        }
-                    }
-                }
-                const updatedLocal = deepMerge(existingLocal, patch);
-                // ${VAR} env var references in string values are preserved
-                // through YAML round-trip. yamlStringify writes them literally, parseYaml
-                // reads them back, and substituteEnvVars resolves them on next daemon load.
-                // Write atomically: write to temp file, then rename
-                const localDir = dirname(localPath);
-                if (!existsSync(localDir)) {
-                    mkdirSync(localDir, { recursive: true });
-                }
-                const tmpPath = localPath + ".tmp";
-                writeFileSync(tmpPath, yamlStringify(updatedLocal), { encoding: "utf-8", mode: 0o600 });
-                renameSync(tmpPath, localPath);
-                // Best-effort git versioning
-                if (deps.configGitManager) {
-                    const gitStart = Date.now();
-                    await deps.configGitManager.commit({
-                        section,
-                        key,
-                        agent: ctx?.agentId ?? params._agentId,
-                        user: ctx?.userId ?? params._userId,
-                        traceId: ctx?.traceId ?? params._traceId,
-                        summary: key
-                            ? `Changed ${section}.${key} to ${JSON.stringify(value)}`
-                            : `Updated ${section} section`,
-                    }).then(() => {
-                        deps.logger.debug({ method: "config.patch", durationMs: Date.now() - gitStart, outcome: "success", section }, "Git commit recorded");
-                    }).catch((gitErr) => {
-                        deps.logger.debug({ method: "config.patch", durationMs: Date.now() - gitStart, outcome: "failure", err: gitErr, section }, "Git commit failed (best-effort)");
-                    });
-                }
-                const durationMs = Date.now() - startMs;
-                // Emit audit event on success
-                deps.container.eventBus.emit("audit:event", {
-                    timestamp: Date.now(),
-                    agentId: ctx?.agentId ?? params._agentId ?? "system",
-                    tenantId: deps.container.config.tenantId ?? "default",
-                    actionType: "config.patch",
-                    classification: "destructive",
-                    outcome: "success",
-                    metadata: { section, key, value, durationMs },
-                });
-                deps.logger.info({ method: "config.patch", section, key, durationMs, outcome: "success" }, "Config patch applied");
-                // Best-effort webhook notification
-                if (deps.configWebhook?.url) {
-                    let webhookDiff;
-                    if (deps.configGitManager) {
-                        const diffResult = await deps.configGitManager.diff();
-                        if (diffResult.ok)
-                            webhookDiff = diffResult.value;
-                    }
-                    suppressError(deliverConfigWebhook({
-                        webhookConfig: deps.configWebhook,
-                        method: "config.patch",
-                        section,
-                        key,
-                        diff: webhookDiff,
-                        metadata: { section, key, summary: key ? `Changed ${section}.${key}` : `Updated ${section} section`, agent: ctx?.agentId, user: ctx?.userId, traceId: ctx?.traceId },
-                        logger: deps.logger,
-                    }), "best-effort config webhook delivery");
-                }
-                // Schedule daemon restart so all subsystems pick up new config atomically.
-                // 200ms delay allows the RPC response to flush over WebSocket before shutdown begins.
-                setTimeout(() => {
-                    process.kill(process.pid, "SIGUSR2");
-                }, 200);
-                return { patched: true, section, key, value, restarting: true };
-            }
-            catch (e) {
-                const durationMs = Date.now() - startMs;
-                const errMsg = e instanceof Error ? e.message : String(e);
-                // Emit audit event on failure
-                deps.container.eventBus.emit("audit:event", {
-                    timestamp: Date.now(),
-                    agentId: ctx?.agentId ?? params._agentId ?? "system",
-                    tenantId: deps.container.config.tenantId ?? "default",
-                    actionType: "config.patch",
-                    classification: "destructive",
-                    outcome: "failure",
-                    metadata: { section, key, value, error: errMsg, durationMs },
-                });
-                // DEBUG not WARN: validation errors from LLM tool calls are routine,
-                // not system failures. Audit event above captures the failure for review.
-                deps.logger.debug({ method: "config.patch", section, key, durationMs, outcome: "failure", err: e }, "Config patch failed");
-                throw e;
-            }
-        },
-        "config.apply": async (params) => {
-            // Admin trust check (same as config.patch)
-            const trustLevel = params._trustLevel;
-            if (trustLevel !== "admin") {
-                throw new Error("Admin access required for config apply");
-            }
-            // Rate limit check -- reuse the SAME patchBucket so apply+patch share the limit
-            const bucket = patchBucket.tryConsume();
-            if (!bucket.allowed) {
-                deps.logger.warn({ method: "config.apply", hint: "Config apply rate limit exceeded, retry after cooldown", errorKind: "validation", retryAfterMs: bucket.retryAfterMs }, "Config apply rate limited");
-                throw new Error(`Config apply rate limit exceeded: max 5 operations per minute. ` +
-                    `Try again in ${Math.ceil(bucket.retryAfterMs / 1000)} seconds.`);
-            }
-            const startMs = Date.now();
-            const section = params.section;
-            const value = params.value;
-            // config.apply replaces the entire section, so resolve the schema at
-            // the section level (key = undefined) to drive schema-aware coercion.
-            const subSchema = resolveSchemaForPath(AppConfigSchema, section, undefined);
-            const coercedValue = coerceConfigValue(value, subSchema);
-            const ctx = params._context;
-            try {
-                // Validate section name exists
-                if (!(section in deps.container.config)) {
-                    throw new Error(`Unknown config section: "${section}". Valid sections: ${getConfigSections().join(", ")}.`);
-                }
-                // Check immutable paths -- entire section is being replaced.
-                // Backstop for direct-RPC clients; LLM tool calls hit the same redirect
-                // earlier via gateway-tool / bridge validator.
-                if (isImmutableConfigPath(section)) {
-                    const redirect = getManagedSectionRedirect(section);
-                    const suffix = redirect
-                        ? ` ${formatRedirectHint(redirect)}`
-                        : " This section requires manual operator intervention via config files.";
-                    throw new Error(`Config section "${section}" is immutable and cannot be replaced at runtime.${suffix}`);
-                }
-                // Build replacement: replace the section entirely (NOT deep merge)
-                const currentConfig = structuredClone(deps.container.config);
-                currentConfig[section] = coercedValue;
-                // Validate entire config
-                const validation = AppConfigSchema.safeParse(currentConfig);
-                if (!validation.success) {
-                    const issues = validation.error.issues
-                        .map((i) => `${i.path.join(".")}: ${i.message}`)
-                        .join("; ");
-                    throw new Error(`Config validation failed: ${issues}`);
-                }
-                // Scan for suspicious env values (bare $VAR, [REDACTED], raw keys)
-                const envWarnings = warnSuspiciousEnvValues({ [section]: coercedValue }, section);
-                if (envWarnings.length > 0) {
-                    const hints = envWarnings.map((w) => `${w.path}: "${w.value}" — ${w.hint}`).join("; ");
-                    throw new Error(`Suspicious env value(s) in config apply: ${hints}. ` +
-                        `Use \${VAR_NAME} syntax to reference secrets stored via env_set.`);
-                }
-                // Read existing local YAML, replace the section
-                const localPath = deps.configPaths.length > 0
-                    ? deps.configPaths[deps.configPaths.length - 1]
-                    : deps.defaultConfigPaths[deps.defaultConfigPaths.length - 1];
-                let existingLocal = {};
-                if (existsSync(localPath)) {
-                    try {
-                        const raw = readFileSync(localPath, "utf-8");
-                        const { parse: parseYaml } = await import("yaml");
-                        const parsed = parseYaml(raw);
-                        if (parsed && typeof parsed === "object") {
-                            existingLocal = parsed;
-                        }
-                    }
-                    catch {
-                        // Start fresh if read/parse fails
-                    }
-                }
-                // Full replacement: overwrite the section key (not deep merge)
-                existingLocal[section] = coercedValue;
-                // ${VAR} env var references in string values are preserved
-                // through YAML round-trip. yamlStringify writes them literally, parseYaml
-                // reads them back, and substituteEnvVars resolves them on next daemon load.
-                // Write atomically
-                const localDir = dirname(localPath);
-                if (!existsSync(localDir)) {
-                    mkdirSync(localDir, { recursive: true });
-                }
-                const tmpPath = localPath + ".tmp";
-                writeFileSync(tmpPath, yamlStringify(existingLocal), { encoding: "utf-8", mode: 0o600 });
-                renameSync(tmpPath, localPath);
-                // Best-effort git commit
-                if (deps.configGitManager) {
-                    const gitStart = Date.now();
-                    await deps.configGitManager.commit({
-                        section,
-                        agent: ctx?.agentId ?? params._agentId,
-                        user: ctx?.userId ?? params._userId,
-                        traceId: ctx?.traceId ?? params._traceId,
-                        summary: `Replaced ${section} section`,
-                    }).then(() => {
-                        deps.logger.debug({ method: "config.apply", durationMs: Date.now() - gitStart, outcome: "success", section }, "Git commit recorded");
-                    }).catch((gitErr) => {
-                        deps.logger.debug({ method: "config.apply", durationMs: Date.now() - gitStart, outcome: "failure", err: gitErr, section }, "Git commit failed (best-effort)");
-                    });
-                }
-                const durationMs = Date.now() - startMs;
-                // Audit event
-                deps.container.eventBus.emit("audit:event", {
-                    timestamp: Date.now(),
-                    agentId: ctx?.agentId ?? params._agentId ?? "system",
-                    tenantId: deps.container.config.tenantId ?? "default",
-                    actionType: "config.apply",
-                    classification: "destructive",
-                    outcome: "success",
-                    metadata: { section, durationMs },
-                });
-                deps.logger.info({ method: "config.apply", section, durationMs, outcome: "success" }, "Config section replaced");
-                // Best-effort webhook notification
-                if (deps.configWebhook?.url) {
-                    let webhookDiff;
-                    if (deps.configGitManager) {
-                        const diffResult = await deps.configGitManager.diff();
-                        if (diffResult.ok)
-                            webhookDiff = diffResult.value;
-                    }
-                    suppressError(deliverConfigWebhook({
-                        webhookConfig: deps.configWebhook,
-                        method: "config.apply",
-                        section,
-                        diff: webhookDiff,
-                        metadata: { section, summary: `Replaced ${section} section`, agent: ctx?.agentId, user: ctx?.userId, traceId: ctx?.traceId },
-                        logger: deps.logger,
-                    }), "best-effort config webhook delivery");
-                }
-                // Schedule restart
-                setTimeout(() => {
-                    process.kill(process.pid, "SIGUSR2");
-                }, 200);
-                return { applied: true, section, restarting: true };
-            }
-            catch (e) {
-                const durationMs = Date.now() - startMs;
-                const errMsg = e instanceof Error ? e.message : String(e);
-                deps.container.eventBus.emit("audit:event", {
-                    timestamp: Date.now(),
-                    agentId: ctx?.agentId ?? params._agentId ?? "system",
-                    tenantId: deps.container.config.tenantId ?? "default",
-                    actionType: "config.apply",
-                    classification: "destructive",
-                    outcome: "failure",
-                    metadata: { section, error: errMsg, durationMs },
-                });
-                // DEBUG not WARN: validation errors from LLM tool calls are routine,
-                // not system failures. Audit event above captures the failure for review.
-                deps.logger.debug({ method: "config.apply", section, durationMs, outcome: "failure", err: e }, "Config apply failed");
-                throw e;
-            }
-        },
-        "config.schema": async (params) => {
-            const trustLevel = params._trustLevel;
-            if (trustLevel !== "admin") {
-                throw new Error("Admin access required for config schema");
-            }
-            const startMs = Date.now();
-            const section = params.section;
-            const schema = getConfigSchema(section);
-            const result = section
-                ? { section, schema, sections: getConfigSections() }
-                : { schema, sections: getConfigSections() };
-            deps.logger.debug({ method: "config.schema", durationMs: Date.now() - startMs, outcome: "success", section }, "Config schema read");
-            return result;
-        },
-        "gateway.restart": async (params) => {
-            const startMs = Date.now();
-            const trustLevel = params._trustLevel;
-            if (trustLevel !== "admin") {
-                throw new Error("Admin access required for gateway restart");
-            }
-            // eslint-disable-next-line no-restricted-syntax -- process.env access needed before SecretManager is available for systemd detection
-            const isSystemd = !!process.env["NOTIFY_SOCKET"];
-            // Use setTimeout to allow the rpcCall response to flush over WebSocket before shutdown begins.
-            // setImmediate fires too early and can race with the RPC response write.
-            setTimeout(() => {
-                process.kill(process.pid, "SIGUSR2");
-            }, 200);
-            deps.logger.info({ method: "gateway.restart", durationMs: Date.now() - startMs, outcome: "success", systemd: isSystemd }, "Gateway restart initiated");
-            return {
-                restarting: true,
-                systemd: isSystemd,
-                warning: isSystemd
-                    ? undefined
-                    : "Not running under systemd. Process will exit and require manual restart.",
-            };
-        },
-        "config.history": async (params) => {
-            const trustLevel = params._trustLevel;
-            if (trustLevel !== "admin") {
-                throw new Error("Admin access required for config history");
-            }
-            const startMs = Date.now();
-            if (!deps.configGitManager) {
-                deps.logger.debug({ method: "config.history", durationMs: Date.now() - startMs, outcome: "success" }, "Config history unavailable (no git)");
-                return { entries: [], error: "Config versioning not available" };
-            }
-            const limit = params.limit;
-            const section = params.section;
-            const result = await deps.configGitManager.history({ limit, section });
-            if (!result.ok) {
-                deps.logger.debug({ method: "config.history", durationMs: Date.now() - startMs, outcome: "failure", section }, "Config history query failed");
-                return { entries: [], error: result.error };
-            }
-            deps.logger.debug({ method: "config.history", durationMs: Date.now() - startMs, outcome: "success", section, entryCount: result.value.length }, "Config history read");
-            return { entries: result.value };
-        },
-        "config.diff": async (params) => {
-            const trustLevel = params._trustLevel;
-            if (trustLevel !== "admin") {
-                throw new Error("Admin access required for config diff");
-            }
-            const startMs = Date.now();
-            if (!deps.configGitManager) {
-                deps.logger.debug({ method: "config.diff", durationMs: Date.now() - startMs, outcome: "success" }, "Config diff unavailable (no git)");
-                return { diff: "", error: "Config versioning not available" };
-            }
-            const sha = params.sha;
-            const result = await deps.configGitManager.diff(sha);
-            if (!result.ok) {
-                deps.logger.debug({ method: "config.diff", durationMs: Date.now() - startMs, outcome: "failure", sha }, "Config diff query failed");
-                return { diff: "", error: result.error };
-            }
-            deps.logger.debug({ method: "config.diff", durationMs: Date.now() - startMs, outcome: "success", sha }, "Config diff read");
-            return { diff: result.value };
-        },
-        "config.rollback": async (params) => {
-            const startMs = Date.now();
-            const trustLevel = params._trustLevel;
-            if (trustLevel !== "admin") {
-                throw new Error("Admin access required for config rollback");
-            }
-            if (!deps.configGitManager) {
-                throw new Error("Config versioning not available");
-            }
-            const sha = params.sha;
-            if (!sha) {
-                throw new Error("sha parameter is required for config rollback");
-            }
-            const result = await deps.configGitManager.rollback(sha);
-            if (!result.ok) {
-                throw new Error(`Config rollback failed: ${result.error}`);
-            }
-            // Trigger daemon restart (same pattern as gateway.restart) per user decision
-            setTimeout(() => {
-                process.kill(process.pid, "SIGUSR2");
-            }, 200);
-            deps.logger.info({ method: "config.rollback", durationMs: Date.now() - startMs, outcome: "success", sha, section: "all" }, "Config rollback applied");
-            return { rolledBack: true, sha, newCommitSha: result.value, restarting: true };
-        },
-        "config.gc": async (params) => {
-            const startMs = Date.now();
-            const trustLevel = params._trustLevel;
-            if (trustLevel !== "admin") {
-                throw new Error("Admin access required for config garbage collection");
-            }
-            if (!deps.configGitManager) {
-                throw new Error("Config versioning not available");
-            }
-            // Run git garbage collection
-            const gcResult = await deps.configGitManager.gc();
-            if (!gcResult.ok) {
-                throw new Error(`Config gc failed: ${gcResult.error}`);
-            }
-            // Optional history squash
-            let squashResult;
-            const olderThan = params.olderThan;
-            if (olderThan) {
-                const squash = await deps.configGitManager.squash(olderThan);
-                if (!squash.ok) {
-                    throw new Error(`Config history squash failed: ${squash.error}`);
-                }
-                squashResult = squash.value;
-            }
-            const durationMs = Date.now() - startMs;
-            deps.logger.info({ method: "config.gc", durationMs, outcome: "success", squashedCount: squashResult?.squashedCount ?? 0 }, "Config gc complete");
-            return {
-                gc: true,
-                ...(squashResult ? { squashed: squashResult.squashedCount, newRootSha: squashResult.newRootSha } : {}),
-            };
-        },
-        "gateway.status": async (params) => {
-            const trustLevel = params._trustLevel;
-            if (trustLevel !== "admin") {
-                throw new Error("Admin access required for gateway status");
-            }
-            const startMs = Date.now();
-            const result = {
-                pid: process.pid,
-                uptime: process.uptime(),
-                memoryUsage: process.memoryUsage().rss,
-                nodeVersion: process.version,
-                configPaths: deps.configPaths,
-                sections: getConfigSections(),
-            };
-            deps.logger.debug({ method: "gateway.status", durationMs: Date.now() - startMs, outcome: "success" }, "Gateway status read");
-            return result;
-        },
-    };
-}