@poolzin/pool-bot 2026.2.23 → 2026.2.25

package/dist/config/io.js

@@ -2,19 +2,25 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { isDeepStrictEqual } from "node:util";
 import JSON5 from "json5";
+import { loadDotEnv } from "../infra/dotenv.js";
+import { resolveRequiredHomeDir } from "../infra/home-dir.js";
 import { loadShellEnvFallback, resolveShellEnvFallbackTimeoutMs, shouldDeferShellEnvFallback, shouldEnableShellEnvFallback, } from "../infra/shell-env.js";
+import { VERSION } from "../version.js";
 import { DuplicateAgentDirError, findDuplicateAgentDirs } from "./agent-dirs.js";
+import { rotateConfigBackups } from "./backup-rotation.js";
 import { applyCompactionDefaults, applyContextPruningDefaults, applyAgentDefaults, applyLoggingDefaults, applyMessageDefaults, applyModelDefaults, applySessionDefaults, applyTalkApiKey, } from "./defaults.js";
-import { VERSION } from "../version.js";
-import { MissingEnvVarError, resolveConfigEnvVars } from "./env-substitution.js";
-import { collectConfigEnvVars } from "./env-vars.js";
+import { restoreEnvVarRefs } from "./env-preserve.js";
+import { MissingEnvVarError, containsEnvVarReference, resolveConfigEnvVars, } from "./env-substitution.js";
+import { applyConfigEnvVars } from "./env-vars.js";
 import { ConfigIncludeError, resolveConfigIncludes } from "./includes.js";
 import { findLegacyConfigIssues } from "./legacy.js";
+import { applyMergePatch } from "./merge-patch.js";
 import { normalizeConfigPaths } from "./normalize-paths.js";
 import { resolveConfigPath, resolveDefaultConfigCandidates, resolveStateDir } from "./paths.js";
 import { applyConfigOverrides } from "./runtime-overrides.js";
-import { validateConfigObjectWithPlugins } from "./validation.js";
+import { validateConfigObjectRawWithPlugins, validateConfigObjectWithPlugins, } from "./validation.js";
 import { comparePoolbotVersions } from "./version.js";
 // Re-export for backwards compatibility
 export { CircularIncludeError, ConfigIncludeError } from "./includes.js";
@@ -36,10 +42,8 @@ const SHELL_ENV_EXPECTED_KEYS = [
     "SLACK_APP_TOKEN",
     "POOLBOT_GATEWAY_TOKEN",
     "POOLBOT_GATEWAY_PASSWORD",
-    "CLAWDBOT_GATEWAY_TOKEN",
-    "CLAWDBOT_GATEWAY_PASSWORD",
 ];
-const CONFIG_BACKUP_COUNT = 5;
+const CONFIG_AUDIT_LOG_FILENAME = "config-audit.jsonl";
 const loggedInvalidConfigs = new Set();
 function hashConfigRaw(raw) {
     return crypto
@@ -50,11 +54,13 @@ function hashConfigRaw(raw) {
 export function resolveConfigSnapshotHash(snapshot) {
     if (typeof snapshot.hash === "string") {
         const trimmed = snapshot.hash.trim();
-        if (trimmed)
+        if (trimmed) {
             return trimmed;
+        }
     }
-    if (typeof snapshot.raw !== "string")
+    if (typeof snapshot.raw !== "string") {
         return null;
+    }
     return hashConfigRaw(snapshot.raw);
 }
 function coerceConfig(value) {
@@ -63,29 +69,217 @@ function coerceConfig(value) {
     }
     return value;
 }
-async function rotateConfigBackups(configPath, ioFs) {
-    if (CONFIG_BACKUP_COUNT <= 1)
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasConfigMeta(value) {
+    if (!isPlainObject(value)) {
+        return false;
+    }
+    const meta = value.meta;
+    return isPlainObject(meta);
+}
+function resolveGatewayMode(value) {
+    if (!isPlainObject(value)) {
+        return null;
+    }
+    const gateway = value.gateway;
+    if (!isPlainObject(gateway) || typeof gateway.mode !== "string") {
+        return null;
+    }
+    const trimmed = gateway.mode.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function cloneUnknown(value) {
+    return structuredClone(value);
+}
+function createMergePatch(base, target) {
+    if (!isPlainObject(base) || !isPlainObject(target)) {
+        return cloneUnknown(target);
+    }
+    const patch = {};
+    const keys = new Set([...Object.keys(base), ...Object.keys(target)]);
+    for (const key of keys) {
+        const hasBase = key in base;
+        const hasTarget = key in target;
+        if (!hasTarget) {
+            patch[key] = null;
+            continue;
+        }
+        const targetValue = target[key];
+        if (!hasBase) {
+            patch[key] = cloneUnknown(targetValue);
+            continue;
+        }
+        const baseValue = base[key];
+        if (isPlainObject(baseValue) && isPlainObject(targetValue)) {
+            const childPatch = createMergePatch(baseValue, targetValue);
+            if (isPlainObject(childPatch) && Object.keys(childPatch).length === 0) {
+                continue;
+            }
+            patch[key] = childPatch;
+            continue;
+        }
+        if (!isDeepStrictEqual(baseValue, targetValue)) {
+            patch[key] = cloneUnknown(targetValue);
+        }
+    }
+    return patch;
+}
+function collectEnvRefPaths(value, path, output) {
+    if (typeof value === "string") {
+        if (containsEnvVarReference(value)) {
+            output.set(path, value);
+        }
         return;
-    const backupBase = `${configPath}.bak`;
-    const maxIndex = CONFIG_BACKUP_COUNT - 1;
-    await ioFs.unlink(`${backupBase}.${maxIndex}`).catch(() => {
-        // best-effort
-    });
-    for (let index = maxIndex - 1; index >= 1; index -= 1) {
-        await ioFs.rename(`${backupBase}.${index}`, `${backupBase}.${index + 1}`).catch(() => {
-            // best-effort
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => {
+            collectEnvRefPaths(item, `${path}[${index}]`, output);
         });
+        return;
+    }
+    if (isPlainObject(value)) {
+        for (const [key, child] of Object.entries(value)) {
+            const childPath = path ? `${path}.${key}` : key;
+            collectEnvRefPaths(child, childPath, output);
+        }
+    }
+}
+function collectChangedPaths(base, target, path, output) {
+    if (Array.isArray(base) && Array.isArray(target)) {
+        const max = Math.max(base.length, target.length);
+        for (let index = 0; index < max; index += 1) {
+            const childPath = path ? `${path}[${index}]` : `[${index}]`;
+            if (index >= base.length || index >= target.length) {
+                output.add(childPath);
+                continue;
+            }
+            collectChangedPaths(base[index], target[index], childPath, output);
+        }
+        return;
+    }
+    if (isPlainObject(base) && isPlainObject(target)) {
+        const keys = new Set([...Object.keys(base), ...Object.keys(target)]);
+        for (const key of keys) {
+            const childPath = path ? `${path}.${key}` : key;
+            const hasBase = key in base;
+            const hasTarget = key in target;
+            if (!hasTarget || !hasBase) {
+                output.add(childPath);
+                continue;
+            }
+            collectChangedPaths(base[key], target[key], childPath, output);
+        }
+        return;
+    }
+    if (!isDeepStrictEqual(base, target)) {
+        output.add(path);
+    }
+}
+function parentPath(value) {
+    if (!value) {
+        return "";
+    }
+    if (value.endsWith("]")) {
+        const index = value.lastIndexOf("[");
+        return index > 0 ? value.slice(0, index) : "";
+    }
+    const index = value.lastIndexOf(".");
+    return index >= 0 ? value.slice(0, index) : "";
+}
+function isPathChanged(path, changedPaths) {
+    if (changedPaths.has(path)) {
+        return true;
+    }
+    let current = parentPath(path);
+    while (current) {
+        if (changedPaths.has(current)) {
+            return true;
+        }
+        current = parentPath(current);
     }
-    await ioFs.rename(backupBase, `${backupBase}.1`).catch(() => {
+    return changedPaths.has("");
+}
+function restoreEnvRefsFromMap(value, path, envRefMap, changedPaths) {
+    if (typeof value === "string") {
+        if (!isPathChanged(path, changedPaths)) {
+            const original = envRefMap.get(path);
+            if (original !== undefined) {
+                return original;
+            }
+        }
+        return value;
+    }
+    if (Array.isArray(value)) {
+        let changed = false;
+        const next = value.map((item, index) => {
+            const updated = restoreEnvRefsFromMap(item, `${path}[${index}]`, envRefMap, changedPaths);
+            if (updated !== item) {
+                changed = true;
+            }
+            return updated;
+        });
+        return changed ? next : value;
+    }
+    if (isPlainObject(value)) {
+        let changed = false;
+        const next = {};
+        for (const [key, child] of Object.entries(value)) {
+            const childPath = path ? `${path}.${key}` : key;
+            const updated = restoreEnvRefsFromMap(child, childPath, envRefMap, changedPaths);
+            if (updated !== child) {
+                changed = true;
+            }
+            next[key] = updated;
+        }
+        return changed ? next : value;
+    }
+    return value;
+}
+function resolveConfigAuditLogPath(env, homedir) {
+    return path.join(resolveStateDir(env, homedir), "logs", CONFIG_AUDIT_LOG_FILENAME);
+}
+function resolveConfigWriteSuspiciousReasons(params) {
+    const reasons = [];
+    if (!params.existsBefore) {
+        return reasons;
+    }
+    if (typeof params.previousBytes === "number" &&
+        typeof params.nextBytes === "number" &&
+        params.previousBytes >= 512 &&
+        params.nextBytes < Math.floor(params.previousBytes * 0.5)) {
+        reasons.push(`size-drop:${params.previousBytes}->${params.nextBytes}`);
+    }
+    if (!params.hasMetaBefore) {
+        reasons.push("missing-meta-before-write");
+    }
+    if (params.gatewayModeBefore && !params.gatewayModeAfter) {
+        reasons.push("gateway-mode-removed");
+    }
+    return reasons;
+}
+async function appendConfigWriteAuditRecord(deps, record) {
+    try {
+        const auditPath = resolveConfigAuditLogPath(deps.env, deps.homedir);
+        await deps.fs.promises.mkdir(path.dirname(auditPath), { recursive: true, mode: 0o700 });
+        await deps.fs.promises.appendFile(auditPath, `${JSON.stringify(record)}\n`, {
+            encoding: "utf-8",
+            mode: 0o600,
+        });
+    }
+    catch {
         // best-effort
-    });
+    }
 }
 function warnOnConfigMiskeys(raw, logger) {
-    if (!raw || typeof raw !== "object")
+    if (!raw || typeof raw !== "object") {
         return;
+    }
     const gateway = raw.gateway;
-    if (!gateway || typeof gateway !== "object")
+    if (!gateway || typeof gateway !== "object") {
         return;
+    }
     if ("token" in gateway) {
         logger.warn('Config uses "gateway.token". This key is ignored; use "gateway.auth.token" instead.');
     }
@@ -103,26 +297,21 @@ function stampConfigVersion(cfg) {
 }
 function warnIfConfigFromFuture(cfg, logger) {
     const touched = cfg.meta?.lastTouchedVersion;
-    if (!touched)
+    if (!touched) {
         return;
+    }
     const cmp = comparePoolbotVersions(VERSION, touched);
-    if (cmp === null)
+    if (cmp === null) {
         return;
-    if (cmp < 0) {
-        logger.warn(`Config was last written by a newer Poolbot (${touched}); current version is ${VERSION}.`);
     }
-}
-function applyConfigEnv(cfg, env) {
-    const entries = collectConfigEnvVars(cfg);
-    for (const [key, value] of Object.entries(entries)) {
-        if (env[key]?.trim())
-            continue;
-        env[key] = value;
+    if (cmp < 0) {
+        logger.warn(`Config was last written by a newer Pool Bot (${touched}); current version is ${VERSION}.`);
     }
 }
 function resolveConfigPathForDeps(deps) {
-    if (deps.configPath)
+    if (deps.configPath) {
         return deps.configPath;
+    }
     return resolveConfigPath(deps.env, resolveStateDir(deps.env, deps.homedir));
 }
 function normalizeDeps(overrides = {}) {
@@ -130,11 +319,19 @@ function normalizeDeps(overrides = {}) {
         fs: overrides.fs ?? fs,
         json5: overrides.json5 ?? JSON5,
         env: overrides.env ?? process.env,
-        homedir: overrides.homedir ?? os.homedir,
+        homedir: overrides.homedir ?? (() => resolveRequiredHomeDir(overrides.env ?? process.env, os.homedir)),
         configPath: overrides.configPath ?? "",
         logger: overrides.logger ?? console,
     };
 }
+function maybeLoadDotEnvForConfig(env) {
+    // Only hydrate dotenv for the real process env. Callers using injected env
+    // objects (tests/diagnostics) should stay isolated.
+    if (env !== process.env) {
+        return;
+    }
+    loadDotEnv({ quiet: true });
+}
 export function parseConfigJson5(raw, json5 = JSON5) {
     try {
         return { ok: true, parsed: json5.parse(raw) };
@@ -143,6 +340,23 @@ export function parseConfigJson5(raw, json5 = JSON5) {
         return { ok: false, error: String(err) };
     }
 }
+function resolveConfigIncludesForRead(parsed, configPath, deps) {
+    return resolveConfigIncludes(parsed, configPath, {
+        readFile: (candidate) => deps.fs.readFileSync(candidate, "utf-8"),
+        parseJson: (raw) => deps.json5.parse(raw),
+    });
+}
+function resolveConfigForRead(resolvedIncludes, env) {
+    // Apply config.env to process.env BEFORE substitution so ${VAR} can reference config-defined vars.
+    if (resolvedIncludes && typeof resolvedIncludes === "object" && "env" in resolvedIncludes) {
+        applyConfigEnvVars(resolvedIncludes, env);
+    }
+    return {
+        resolvedConfigRaw: resolveConfigEnvVars(resolvedIncludes, env),
+        // Capture env snapshot after substitution for write-time ${VAR} restoration.
+        envSnapshotForRestore: { ...env },
+    };
+}
 export function createConfigIO(overrides = {}) {
     const deps = normalizeDeps(overrides);
     const requestedConfigPath = resolveConfigPathForDeps(deps);
@@ -152,6 +366,7 @@ export function createConfigIO(overrides = {}) {
     const configPath = candidatePaths.find((candidate) => deps.fs.existsSync(candidate)) ?? requestedConfigPath;
     function loadConfig() {
         try {
+            maybeLoadDotEnvForConfig(deps.env);
             if (!deps.fs.existsSync(configPath)) {
                 if (shouldEnableShellEnvFallback(deps.env) && !shouldDeferShellEnvFallback(deps.env)) {
                     loadShellEnvFallback({
@@ -166,21 +381,11 @@ export function createConfigIO(overrides = {}) {
             }
             const raw = deps.fs.readFileSync(configPath, "utf-8");
             const parsed = deps.json5.parse(raw);
-            // Resolve $include directives before validation
-            const resolved = resolveConfigIncludes(parsed, configPath, {
-                readFile: (p) => deps.fs.readFileSync(p, "utf-8"),
-                parseJson: (raw) => deps.json5.parse(raw),
-            });
-            // Apply config.env to process.env BEFORE substitution so ${VAR} can reference config-defined vars
-            if (resolved && typeof resolved === "object" && "env" in resolved) {
-                applyConfigEnv(resolved, deps.env);
-            }
-            // Substitute ${VAR} env var references
-            const substituted = resolveConfigEnvVars(resolved, deps.env);
-            const resolvedConfig = substituted;
+            const { resolvedConfigRaw: resolvedConfig } = resolveConfigForRead(resolveConfigIncludesForRead(parsed, configPath, deps), deps.env);
             warnOnConfigMiskeys(resolvedConfig, deps.logger);
-            if (typeof resolvedConfig !== "object" || resolvedConfig === null)
+            if (typeof resolvedConfig !== "object" || resolvedConfig === null) {
                 return {};
+            }
             const preValidationDuplicates = findDuplicateAgentDirs(resolvedConfig, {
                 env: deps.env,
                 homedir: deps.homedir,
@@ -218,7 +423,7 @@ export function createConfigIO(overrides = {}) {
             if (duplicates.length > 0) {
                 throw new DuplicateAgentDirError(duplicates);
             }
-            applyConfigEnv(cfg, deps.env);
+            applyConfigEnvVars(cfg, deps.env);
             const enabled = shouldEnableShellEnvFallback(deps.env) || cfg.env?.shellEnv?.enabled === true;
             if (enabled && !shouldDeferShellEnvFallback(deps.env)) {
                 loadShellEnvFallback({
@@ -244,23 +449,27 @@ export function createConfigIO(overrides = {}) {
             return {};
         }
     }
-    async function readConfigFileSnapshot() {
+    async function readConfigFileSnapshotInternal() {
+        maybeLoadDotEnvForConfig(deps.env);
         const exists = deps.fs.existsSync(configPath);
         if (!exists) {
             const hash = hashConfigRaw(null);
             const config = applyTalkApiKey(applyModelDefaults(applyCompactionDefaults(applyContextPruningDefaults(applyAgentDefaults(applySessionDefaults(applyMessageDefaults({})))))));
             const legacyIssues = [];
             return {
-                path: configPath,
-                exists: false,
-                raw: null,
-                parsed: {},
-                valid: true,
-                config,
-                hash,
-                issues: [],
-                warnings: [],
-                legacyIssues,
+                snapshot: {
+                    path: configPath,
+                    exists: false,
+                    raw: null,
+                    parsed: {},
+                    resolved: {},
+                    valid: true,
+                    config,
+                    hash,
+                    issues: [],
+                    warnings: [],
+                    legacyIssues,
+                },
             };
         }
         try {
@@ -269,118 +478,169 @@ export function createConfigIO(overrides = {}) {
             const parsedRes = parseConfigJson5(raw, deps.json5);
             if (!parsedRes.ok) {
                 return {
-                    path: configPath,
-                    exists: true,
-                    raw,
-                    parsed: {},
-                    valid: false,
-                    config: {},
-                    hash,
-                    issues: [{ path: "", message: `JSON5 parse failed: ${parsedRes.error}` }],
-                    warnings: [],
-                    legacyIssues: [],
+                    snapshot: {
+                        path: configPath,
+                        exists: true,
+                        raw,
+                        parsed: {},
+                        resolved: {},
+                        valid: false,
+                        config: {},
+                        hash,
+                        issues: [{ path: "", message: `JSON5 parse failed: ${parsedRes.error}` }],
+                        warnings: [],
+                        legacyIssues: [],
+                    },
                 };
             }
             // Resolve $include directives
             let resolved;
             try {
-                resolved = resolveConfigIncludes(parsedRes.parsed, configPath, {
-                    readFile: (p) => deps.fs.readFileSync(p, "utf-8"),
-                    parseJson: (raw) => deps.json5.parse(raw),
-                });
+                resolved = resolveConfigIncludesForRead(parsedRes.parsed, configPath, deps);
             }
             catch (err) {
                 const message = err instanceof ConfigIncludeError
                     ? err.message
                     : `Include resolution failed: ${String(err)}`;
                 return {
-                    path: configPath,
-                    exists: true,
-                    raw,
-                    parsed: parsedRes.parsed,
-                    valid: false,
-                    config: coerceConfig(parsedRes.parsed),
-                    hash,
-                    issues: [{ path: "", message }],
-                    warnings: [],
-                    legacyIssues: [],
+                    snapshot: {
+                        path: configPath,
+                        exists: true,
+                        raw,
+                        parsed: parsedRes.parsed,
+                        resolved: coerceConfig(parsedRes.parsed),
+                        valid: false,
+                        config: coerceConfig(parsedRes.parsed),
+                        hash,
+                        issues: [{ path: "", message }],
+                        warnings: [],
+                        legacyIssues: [],
+                    },
                 };
             }
-            // Apply config.env to process.env BEFORE substitution so ${VAR} can reference config-defined vars
-            if (resolved && typeof resolved === "object" && "env" in resolved) {
-                applyConfigEnv(resolved, deps.env);
-            }
-            // Substitute ${VAR} env var references
-            let substituted;
+            let readResolution;
             try {
-                substituted = resolveConfigEnvVars(resolved, deps.env);
+                readResolution = resolveConfigForRead(resolved, deps.env);
             }
             catch (err) {
                 const message = err instanceof MissingEnvVarError
                     ? err.message
                     : `Env var substitution failed: ${String(err)}`;
                 return {
-                    path: configPath,
-                    exists: true,
-                    raw,
-                    parsed: parsedRes.parsed,
-                    valid: false,
-                    config: coerceConfig(resolved),
-                    hash,
-                    issues: [{ path: "", message }],
-                    warnings: [],
-                    legacyIssues: [],
+                    snapshot: {
+                        path: configPath,
+                        exists: true,
+                        raw,
+                        parsed: parsedRes.parsed,
+                        resolved: coerceConfig(resolved),
+                        valid: false,
+                        config: coerceConfig(resolved),
+                        hash,
+                        issues: [{ path: "", message }],
+                        warnings: [],
+                        legacyIssues: [],
+                    },
                 };
             }
-            const resolvedConfigRaw = substituted;
+            const resolvedConfigRaw = readResolution.resolvedConfigRaw;
             const legacyIssues = findLegacyConfigIssues(resolvedConfigRaw);
             const validated = validateConfigObjectWithPlugins(resolvedConfigRaw);
             if (!validated.ok) {
                 return {
+                    snapshot: {
+                        path: configPath,
+                        exists: true,
+                        raw,
+                        parsed: parsedRes.parsed,
+                        resolved: coerceConfig(resolvedConfigRaw),
+                        valid: false,
+                        config: coerceConfig(resolvedConfigRaw),
+                        hash,
+                        issues: validated.issues,
+                        warnings: validated.warnings,
+                        legacyIssues,
+                    },
+                };
+            }
+            warnIfConfigFromFuture(validated.config, deps.logger);
+            return {
+                snapshot: {
                     path: configPath,
                     exists: true,
                     raw,
                     parsed: parsedRes.parsed,
-                    valid: false,
-                    config: coerceConfig(resolvedConfigRaw),
+                    // Use resolvedConfigRaw (after $include and ${ENV} substitution but BEFORE runtime defaults)
+                    // for config set/unset operations (issue #6070)
+                    resolved: coerceConfig(resolvedConfigRaw),
+                    valid: true,
+                    config: normalizeConfigPaths(applyTalkApiKey(applyModelDefaults(applyAgentDefaults(applySessionDefaults(applyLoggingDefaults(applyMessageDefaults(validated.config))))))),
                     hash,
-                    issues: validated.issues,
+                    issues: [],
                     warnings: validated.warnings,
                     legacyIssues,
-                };
-            }
-            warnIfConfigFromFuture(validated.config, deps.logger);
-            return {
-                path: configPath,
-                exists: true,
-                raw,
-                parsed: parsedRes.parsed,
-                valid: true,
-                config: normalizeConfigPaths(applyTalkApiKey(applyModelDefaults(applyAgentDefaults(applySessionDefaults(applyLoggingDefaults(applyMessageDefaults(validated.config))))))),
-                hash,
-                issues: [],
-                warnings: validated.warnings,
-                legacyIssues,
+                },
+                envSnapshotForRestore: readResolution.envSnapshotForRestore,
             };
         }
         catch (err) {
             return {
-                path: configPath,
-                exists: true,
-                raw: null,
-                parsed: {},
-                valid: false,
-                config: {},
-                hash: hashConfigRaw(null),
-                issues: [{ path: "", message: `read failed: ${String(err)}` }],
-                warnings: [],
-                legacyIssues: [],
+                snapshot: {
+                    path: configPath,
+                    exists: true,
+                    raw: null,
+                    parsed: {},
+                    resolved: {},
+                    valid: false,
+                    config: {},
+                    hash: hashConfigRaw(null),
+                    issues: [{ path: "", message: `read failed: ${String(err)}` }],
+                    warnings: [],
+                    legacyIssues: [],
+                },
             };
         }
     }
-    async function writeConfigFile(cfg) {
+    async function readConfigFileSnapshot() {
+        const result = await readConfigFileSnapshotInternal();
+        return result.snapshot;
+    }
+    async function readConfigFileSnapshotForWrite() {
+        const result = await readConfigFileSnapshotInternal();
+        return {
+            snapshot: result.snapshot,
+            writeOptions: {
+                envSnapshotForRestore: result.envSnapshotForRestore,
+                expectedConfigPath: configPath,
+            },
+        };
+    }
+    async function writeConfigFile(cfg, options = {}) {
         clearConfigCache();
-        const validated = validateConfigObjectWithPlugins(cfg);
+        let persistCandidate = cfg;
+        const { snapshot } = await readConfigFileSnapshotInternal();
+        let envRefMap = null;
+        let changedPaths = null;
+        if (snapshot.valid && snapshot.exists) {
+            const patch = createMergePatch(snapshot.config, cfg);
+            persistCandidate = applyMergePatch(snapshot.resolved, patch);
+            try {
+                const resolvedIncludes = resolveConfigIncludes(snapshot.parsed, configPath, {
+                    readFile: (candidate) => deps.fs.readFileSync(candidate, "utf-8"),
+                    parseJson: (raw) => deps.json5.parse(raw),
+                });
+                const collected = new Map();
+                collectEnvRefPaths(resolvedIncludes, "", collected);
+                if (collected.size > 0) {
+                    envRefMap = collected;
+                    changedPaths = new Set();
+                    collectChangedPaths(snapshot.config, cfg, "", changedPaths);
+                }
+            }
+            catch {
+                envRefMap = null;
+            }
+        }
+        const validated = validateConfigObjectRawWithPlugins(persistCandidate);
         if (!validated.ok) {
             const issue = validated.issues[0];
             const pathLabel = issue?.path ? issue.path : "<root>";
@@ -392,41 +652,171 @@ export function createConfigIO(overrides = {}) {
                 .join("\n");
             deps.logger.warn(`Config warnings:\n${details}`);
         }
+        // Restore ${VAR} env var references that were resolved during config loading.
+        // Read the current file (pre-substitution) and restore any references whose
+        // resolved values match the incoming config — so we don't overwrite
+        // "${ANTHROPIC_API_KEY}" with "sk-ant-..." when the caller didn't change it.
+        //
+        // We use only the root file's parsed content (no $include resolution) to avoid
+        // pulling values from included files into the root config on write-back.
+        // Apply env restoration to validated.config (which has runtime defaults stripped
+        // per issue #6070) rather than the raw caller input.
+        let cfgToWrite = validated.config;
+        try {
+            if (deps.fs.existsSync(configPath)) {
+                const currentRaw = await deps.fs.promises.readFile(configPath, "utf-8");
+                const parsedRes = parseConfigJson5(currentRaw, deps.json5);
+                if (parsedRes.ok) {
+                    // Use env snapshot from when config was loaded (if available) to avoid
+                    // TOCTOU issues where env changes between load and write. Falls back to
+                    // live env if no snapshot exists (e.g., first write before any load).
+                    const envForRestore = options.envSnapshotForRestore ?? deps.env;
+                    cfgToWrite = restoreEnvVarRefs(cfgToWrite, parsedRes.parsed, envForRestore);
+                }
+            }
+        }
+        catch {
+            // If reading the current file fails, write cfg as-is (no env restoration)
+        }
         const dir = path.dirname(configPath);
         await deps.fs.promises.mkdir(dir, { recursive: true, mode: 0o700 });
-        const json = JSON.stringify(applyModelDefaults(stampConfigVersion(cfg)), null, 2)
-            .trimEnd()
-            .concat("\n");
-        const tmp = path.join(dir, `${path.basename(configPath)}.${process.pid}.${crypto.randomUUID()}.tmp`);
-        await deps.fs.promises.writeFile(tmp, json, {
-            encoding: "utf-8",
-            mode: 0o600,
+        const outputConfig = envRefMap && changedPaths
+            ? restoreEnvRefsFromMap(cfgToWrite, "", envRefMap, changedPaths)
+            : cfgToWrite;
+        // Do NOT apply runtime defaults when writing — user config should only contain
+        // explicitly set values. Runtime defaults are applied when loading (issue #6070).
+        const stampedOutputConfig = stampConfigVersion(outputConfig);
+        const json = JSON.stringify(stampedOutputConfig, null, 2).trimEnd().concat("\n");
+        const nextHash = hashConfigRaw(json);
+        const previousHash = resolveConfigSnapshotHash(snapshot);
+        const changedPathCount = changedPaths?.size;
+        const previousBytes = typeof snapshot.raw === "string" ? Buffer.byteLength(snapshot.raw, "utf-8") : null;
+        const nextBytes = Buffer.byteLength(json, "utf-8");
+        const hasMetaBefore = hasConfigMeta(snapshot.parsed);
+        const hasMetaAfter = hasConfigMeta(stampedOutputConfig);
+        const gatewayModeBefore = resolveGatewayMode(snapshot.resolved);
+        const gatewayModeAfter = resolveGatewayMode(stampedOutputConfig);
+        const suspiciousReasons = resolveConfigWriteSuspiciousReasons({
+            existsBefore: snapshot.exists,
+            previousBytes,
+            nextBytes,
+            hasMetaBefore,
+            gatewayModeBefore,
+            gatewayModeAfter,
         });
-        if (deps.fs.existsSync(configPath)) {
-            await rotateConfigBackups(configPath, deps.fs.promises);
-            await deps.fs.promises.copyFile(configPath, `${configPath}.bak`).catch(() => {
-                // best-effort
+        const logConfigOverwrite = () => {
+            if (!snapshot.exists) {
+                return;
+            }
+            const isVitest = deps.env.VITEST === "true";
+            const shouldLogInVitest = deps.env.CLAWDBOT_TEST_CONFIG_OVERWRITE_LOG === "1";
+            if (isVitest && !shouldLogInVitest) {
+                return;
+            }
+            const changeSummary = typeof changedPathCount === "number" ? `, changedPaths=${changedPathCount}` : "";
+            deps.logger.warn(`Config overwrite: ${configPath} (sha256 ${previousHash ?? "unknown"} -> ${nextHash}, backup=${configPath}.bak${changeSummary})`);
+        };
+        const logConfigWriteAnomalies = () => {
+            if (suspiciousReasons.length === 0) {
+                return;
+            }
+            // Tests often write minimal configs (missing meta, etc); keep output quiet unless requested.
+            const isVitest = deps.env.VITEST === "true";
+            const shouldLogInVitest = deps.env.CLAWDBOT_TEST_CONFIG_WRITE_ANOMALY_LOG === "1";
+            if (isVitest && !shouldLogInVitest) {
+                return;
+            }
+            deps.logger.warn(`Config write anomaly: ${configPath} (${suspiciousReasons.join(", ")})`);
+        };
+        const auditRecordBase = {
+            ts: new Date().toISOString(),
+            source: "config-io",
+            event: "config.write",
+            configPath,
+            pid: process.pid,
+            ppid: process.ppid,
+            cwd: process.cwd(),
+            argv: process.argv.slice(0, 8),
+            execArgv: process.execArgv.slice(0, 8),
+            watchMode: deps.env.CLAWDBOT_WATCH_MODE === "1",
+            watchSession: typeof deps.env.CLAWDBOT_WATCH_SESSION === "string" &&
+                deps.env.CLAWDBOT_WATCH_SESSION.trim().length > 0
+                ? deps.env.CLAWDBOT_WATCH_SESSION.trim()
+                : null,
+            watchCommand: typeof deps.env.CLAWDBOT_WATCH_COMMAND === "string" &&
+                deps.env.CLAWDBOT_WATCH_COMMAND.trim().length > 0
+                ? deps.env.CLAWDBOT_WATCH_COMMAND.trim()
+                : null,
+            existsBefore: snapshot.exists,
+            previousHash: previousHash ?? null,
+            nextHash,
+            previousBytes,
+            nextBytes,
+            changedPathCount: typeof changedPathCount === "number" ? changedPathCount : null,
+            hasMetaBefore,
+            hasMetaAfter,
+            gatewayModeBefore,
+            gatewayModeAfter,
+            suspicious: suspiciousReasons,
+        };
+        const appendWriteAudit = async (result, err) => {
+            const errorCode = err && typeof err === "object" && "code" in err && typeof err.code === "string"
+                ? err.code
+                : undefined;
+            const errorMessage = err && typeof err === "object" && "message" in err && typeof err.message === "string"
+                ? err.message
+                : undefined;
+            await appendConfigWriteAuditRecord(deps, {
+                ...auditRecordBase,
+                result,
+                nextHash: result === "failed" ? null : auditRecordBase.nextHash,
+                nextBytes: result === "failed" ? null : auditRecordBase.nextBytes,
+                errorCode,
+                errorMessage,
             });
-        }
+        };
+        const tmp = path.join(dir, `${path.basename(configPath)}.${process.pid}.${crypto.randomUUID()}.tmp`);
         try {
-            await deps.fs.promises.rename(tmp, configPath);
-        }
-        catch (err) {
-            const code = err.code;
-            // Windows doesn't reliably support atomic replace via rename when dest exists.
-            if (code === "EPERM" || code === "EEXIST") {
-                await deps.fs.promises.copyFile(tmp, configPath);
-                await deps.fs.promises.chmod(configPath, 0o600).catch(() => {
+            await deps.fs.promises.writeFile(tmp, json, {
+                encoding: "utf-8",
+                mode: 0o600,
+            });
+            if (deps.fs.existsSync(configPath)) {
+                await rotateConfigBackups(configPath, deps.fs.promises);
+                await deps.fs.promises.copyFile(configPath, `${configPath}.bak`).catch(() => {
                     // best-effort
                 });
+            }
+            try {
+                await deps.fs.promises.rename(tmp, configPath);
+            }
+            catch (err) {
+                const code = err.code;
+                // Windows doesn't reliably support atomic replace via rename when dest exists.
+                if (code === "EPERM" || code === "EEXIST") {
+                    await deps.fs.promises.copyFile(tmp, configPath);
+                    await deps.fs.promises.chmod(configPath, 0o600).catch(() => {
+                        // best-effort
+                    });
+                    await deps.fs.promises.unlink(tmp).catch(() => {
+                        // best-effort
+                    });
+                    logConfigOverwrite();
+                    logConfigWriteAnomalies();
+                    await appendWriteAudit("copy-fallback");
+                    return;
+                }
                 await deps.fs.promises.unlink(tmp).catch(() => {
                     // best-effort
                 });
-                return;
+                throw err;
             }
-            await deps.fs.promises.unlink(tmp).catch(() => {
-                // best-effort
-            });
+            logConfigOverwrite();
+            logConfigWriteAnomalies();
+            await appendWriteAudit("rename");
+        }
+        catch (err) {
+            await appendWriteAudit("failed", err);
             throw err;
         }
     }
@@ -434,35 +824,41 @@ export function createConfigIO(overrides = {}) {
         configPath,
         loadConfig,
         readConfigFileSnapshot,
+        readConfigFileSnapshotForWrite,
         writeConfigFile,
     };
 }
 // NOTE: These wrappers intentionally do *not* cache the resolved config path at
-// module scope. `POOLBOT_CONFIG_PATH` / `CLAWDBOT_CONFIG_PATH` (and friends) are expected to work even
+// module scope. `CLAWDBOT_CONFIG_PATH` (and friends) are expected to work even
 // when set after the module has been imported (tests, one-off scripts, etc.).
 const DEFAULT_CONFIG_CACHE_MS = 200;
 let configCache = null;
 function resolveConfigCacheMs(env) {
-    const raw = env.POOLBOT_CONFIG_CACHE_MS?.trim() || env.CLAWDBOT_CONFIG_CACHE_MS?.trim();
-    if (raw === "" || raw === "0")
+    const raw = env.CLAWDBOT_CONFIG_CACHE_MS?.trim();
+    if (raw === "" || raw === "0") {
         return 0;
-    if (!raw)
+    }
+    if (!raw) {
         return DEFAULT_CONFIG_CACHE_MS;
+    }
     const parsed = Number.parseInt(raw, 10);
-    if (!Number.isFinite(parsed))
+    if (!Number.isFinite(parsed)) {
         return DEFAULT_CONFIG_CACHE_MS;
+    }
     return Math.max(0, parsed);
 }
 function shouldUseConfigCache(env) {
-    if (env.POOLBOT_DISABLE_CONFIG_CACHE?.trim() || env.CLAWDBOT_DISABLE_CONFIG_CACHE?.trim())
+    if (env.CLAWDBOT_DISABLE_CONFIG_CACHE?.trim()) {
         return false;
+    }
     return resolveConfigCacheMs(env) > 0;
 }
-function clearConfigCache() {
+export function clearConfigCache() {
     configCache = null;
 }
 export function loadConfig() {
-    const configPath = resolveConfigPath();
+    const io = createConfigIO();
+    const configPath = io.configPath;
     const now = Date.now();
     if (shouldUseConfigCache(process.env)) {
         const cached = configCache;
@@ -470,7 +866,7 @@ export function loadConfig() {
             return cached.config;
         }
     }
-    const config = createConfigIO({ configPath }).loadConfig();
+    const config = io.loadConfig();
     if (shouldUseConfigCache(process.env)) {
         const cacheMs = resolveConfigCacheMs(process.env);
         if (cacheMs > 0) {
@@ -484,11 +880,15 @@ export function loadConfig() {
     return config;
 }
 export async function readConfigFileSnapshot() {
-    return await createConfigIO({
-        configPath: resolveConfigPath(),
-    }).readConfigFileSnapshot();
+    return await createConfigIO().readConfigFileSnapshot();
+}
+export async function readConfigFileSnapshotForWrite() {
+    return await createConfigIO().readConfigFileSnapshotForWrite();
 }
-export async function writeConfigFile(cfg) {
-    clearConfigCache();
-    await createConfigIO({ configPath: resolveConfigPath() }).writeConfigFile(cfg);
+export async function writeConfigFile(cfg, options = {}) {
+    const io = createConfigIO();
+    const sameConfigPath = options.expectedConfigPath === undefined || options.expectedConfigPath === io.configPath;
+    await io.writeConfigFile(cfg, {
+        envSnapshotForRestore: sameConfigPath ? options.envSnapshotForRestore : undefined,
+    });
 }