@edspencer/paddock 0.0.1 → 0.57.0

package/packages/server/dist/config.js

@@ -0,0 +1,625 @@
+/**
+ * Paddock server configuration, sourced from an optional YAML instance-config
+ * file with environment overrides on top (precedence: file < env), and sane
+ * defaults beneath both.
+ *
+ * Everything is resolved once at startup so the rest of the app can import a
+ * frozen object. Paths are normalised to absolute.
+ *
+ * **Retired settings are IGNORED, never fatal** (#549). Config is pull-based on
+ * both layers: env vars are read by name via {@link envOr}, and the YAML file is
+ * parsed into a loose record whose keys are only ever read, never enumerated or
+ * validated against a schema. So a setting Paddock has since deleted is simply
+ * never looked at — boot succeeds and the value has no effect. This is a property
+ * of the resolution shape rather than a compatibility shim, so it needs no
+ * per-key upkeep as settings come and go. The cost is that a typo'd key is
+ * equally silent; that trade is deliberate — an operator should not be hard-failed
+ * out of a running instance by a stale line in an old env file. Pinned by
+ * `test/unit/config.test.ts`.
+ */
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
+import YAML from "yaml";
+import { DEFAULT_DRIVE_MODE, isKnownDriveMode, isKnownModel, } from "./models.js";
+import { DEFAULT_MAX_SPAWN_DEPTH, isValidMaxSpawnDepth } from "./spawn-capability.js";
+import { DEFAULT_ENVIRONMENT_PROMPT } from "./environment-prompt.js";
+import { DEFAULT_RECOVERY } from "./recovery-config.js";
+import { DEFAULT_CURATION } from "./curation-config.js";
+import { resolveManagementApiConfig, } from "./management-config.js";
+import { DEFAULT_ATTACHMENTS, sanitizeAllowedTypes, } from "./attachments-config.js";
+function abs(p) {
+    return path.isAbsolute(p) ? p : path.resolve(process.cwd(), p);
+}
+/**
+ * Canonicalize a path: resolve symlinks in the deepest EXISTING ancestor, then
+ * re-append the not-yet-created tail. This matters because Claude Code records
+ * session transcripts under the *real* working directory (e.g. macOS maps
+ * `/tmp` -> `/private/tmp`), and SessionDiscoveryService encodes the configured
+ * working_directory to find them. Without canonicalization the configured path
+ * and the recorded path diverge and session discovery returns nothing.
+ *
+ * On Linux (the deploy target) this is typically a no-op, but it keeps paddock
+ * portable and robust against symlinked data roots.
+ */
+function canonical(p) {
+    const absolute = abs(p);
+    let dir = absolute;
+    const tail = [];
+    // Walk up to the first existing ancestor.
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        try {
+            const real = fs.realpathSync(dir);
+            return tail.length ? path.join(real, ...tail.reverse()) : real;
+        }
+        catch {
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                return absolute; // reached root without resolving
+            tail.push(path.basename(dir));
+            dir = parent;
+        }
+    }
+}
+function envOr(name, fallback) {
+    const v = process.env[name];
+    return v && v.trim().length > 0 ? v : fallback;
+}
+/** An env var's trimmed value, or undefined when unset/blank. */
+function envOpt(name) {
+    const v = process.env[name];
+    return v && v.trim().length > 0 ? v.trim() : undefined;
+}
+/**
+ * Fold a config-file value in as the fallback beneath a hardcoded default. The
+ * file value is stringified — so the exact same parsing/coercion an env value
+ * would get applies — and used when present and non-blank; otherwise the
+ * hardcoded default. Env still wins because callers pass the result as the
+ * `envOr` fallback (which is only consulted when the env var is unset).
+ */
+function fileOr(fileVal, fallback) {
+    if (fileVal === undefined || fileVal === null)
+        return fallback;
+    const s = String(fileVal);
+    return s.trim().length > 0 ? s : fallback;
+}
+/** A config-file value as a trimmed string, or undefined when absent/blank. */
+function fileOpt(fileVal) {
+    if (fileVal === undefined || fileVal === null)
+        return undefined;
+    const s = String(fileVal).trim();
+    return s.length > 0 ? s : undefined;
+}
+/** Default filename for the instance-config file, resolved under the data dir. */
+const DEFAULT_CONFIG_FILENAME = "paddock.config.yaml";
+/**
+ * Load the optional YAML instance-config file that provides the BASE layer for
+ * {@link PaddockConfig} (issue #270 / DD-5). Env vars still override every value
+ * (precedence file < env).
+ *
+ * Path resolution: an explicit `PADDOCK_CONFIG` env var wins; otherwise
+ * `<dataDir>/paddock.config.yaml`. When no file exists at the default location
+ * the result is an empty object, so an env-only deployment behaves exactly as
+ * before — this is a no-op for existing installs. An explicit `PADDOCK_CONFIG`
+ * that points at a missing file is treated as a misconfiguration (a clear error)
+ * rather than silently ignored.
+ *
+ * A present-but-malformed file (unparseable YAML, or a top-level scalar/list
+ * instead of a mapping) throws a clear Error rather than starting up with a
+ * half-empty config.
+ */
+export function loadConfigFile(dataDir) {
+    const explicit = envOpt("PADDOCK_CONFIG");
+    const configPath = explicit ? abs(explicit) : path.join(dataDir, DEFAULT_CONFIG_FILENAME);
+    let raw;
+    try {
+        raw = fs.readFileSync(configPath, "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            // Missing default file → env-only, unchanged behaviour. A missing file
+            // that was EXPLICITLY requested is an operator error worth surfacing.
+            if (explicit) {
+                throw new Error(`PADDOCK_CONFIG points at a config file that does not exist: ${configPath}`);
+            }
+            return {};
+        }
+        throw new Error(`Failed to read Paddock config file ${configPath}: ${err.message}`);
+    }
+    let parsed;
+    try {
+        parsed = YAML.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Failed to parse Paddock config file ${configPath} as YAML: ${err.message}`);
+    }
+    // An empty (or comments-only) file parses to null → treat as "no overrides".
+    if (parsed === null || parsed === undefined)
+        return {};
+    if (typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error(`Paddock config file ${configPath} must contain a YAML mapping (got ${Array.isArray(parsed) ? "a list" : typeof parsed}).`);
+    }
+    // A valueless key (`brand:` / `auth:` with nothing after it) parses to `null`.
+    // Treat such an empty section (or scalar) as ABSENT — drop it so it falls back
+    // to env/defaults — rather than passing `null` through to a loader that expects
+    // an object (which would crash with an unclear TypeError). Deeper `null`s and
+    // wrong-typed sections already degrade to defaults via fileOr/fileOpt.
+    const obj = parsed;
+    for (const key of Object.keys(obj)) {
+        if (obj[key] === null)
+            delete obj[key];
+    }
+    return obj;
+}
+/**
+ * Resolve the provider-agnostic auth config from `PADDOCK_AUTH_*` env vars.
+ * Everything is optional; the default is `none` (fully open). Validation of
+ * mode-specific requirements (e.g. a JWKS URL in jwt mode) happens in the auth
+ * plugin so a misconfig surfaces as a clear startup error rather than a
+ * silently-open server.
+ */
+function loadAuthConfig(file = {}) {
+    const rawMode = envOr("PADDOCK_AUTH_MODE", fileOr(file.mode, "none")).toLowerCase();
+    const mode = rawMode === "trusted-header" || rawMode === "jwt" ? rawMode : "none";
+    return {
+        mode,
+        userHeader: envOr("PADDOCK_AUTH_USER_HEADER", fileOr(file.userHeader, "X-Forwarded-User")),
+        emailHeader: envOpt("PADDOCK_AUTH_EMAIL_HEADER") ?? fileOpt(file.emailHeader),
+        groupsHeader: envOpt("PADDOCK_AUTH_GROUPS_HEADER") ?? fileOpt(file.groupsHeader),
+        jwtHeader: envOr("PADDOCK_AUTH_JWT_HEADER", fileOr(file.jwtHeader, "Authorization")),
+        jwksUrl: envOpt("PADDOCK_AUTH_JWKS_URL") ?? fileOpt(file.jwksUrl),
+        jwtIssuer: envOpt("PADDOCK_AUTH_JWT_ISSUER") ?? fileOpt(file.jwtIssuer),
+        jwtAudience: envOpt("PADDOCK_AUTH_JWT_AUDIENCE") ?? fileOpt(file.jwtAudience),
+        usernameClaim: envOpt("PADDOCK_AUTH_USERNAME_CLAIM") ?? fileOpt(file.usernameClaim),
+        groupsClaim: envOr("PADDOCK_AUTH_GROUPS_CLAIM", fileOr(file.groupsClaim, "groups")),
+    };
+}
+/**
+ * Resolve the dangerously-open opt-in from `PADDOCK_DANGEROUSLY_ALLOW_OPEN`
+ * (#435). Off by default; accepts the shared 1/true/yes truthy convention. When
+ * set, the bind-safety guard downgrades its refusal (non-loopback + auth=none)
+ * to a loud boot warning instead of failing closed.
+ */
+function loadDangerouslyAllowOpen() {
+    const raw = envOr("PADDOCK_DANGEROUSLY_ALLOW_OPEN", "false").toLowerCase();
+    return raw === "1" || raw === "true" || raw === "yes";
+}
+/**
+ * Resolve the voice-dictation (Whisper) capability from env. Defaults to `off`,
+ * so a plain instance never shows a mic button. The mode defaults to `remote`
+ * when an endpoint is configured (the common case — point it at a shared whisper
+ * server), and can be forced with `PADDOCK_WHISPER_MODE`. Accepts local/remote/off.
+ */
+function loadTranscriptionConfig(file = {}) {
+    const endpoint = envOpt("PADDOCK_WHISPER_ENDPOINT") ?? fileOpt(file.endpoint);
+    const rawMode = envOr("PADDOCK_WHISPER_MODE", fileOr(file.mode, endpoint ? "remote" : "off")).toLowerCase();
+    const mode = rawMode === "local" || rawMode === "remote" ? rawMode : "off";
+    return {
+        mode,
+        model: envOr("PADDOCK_WHISPER_MODEL", fileOr(file.model, "base")),
+        endpoint,
+        apiKey: envOpt("PADDOCK_WHISPER_API_KEY") ?? fileOpt(file.apiKey),
+        language: envOpt("PADDOCK_WHISPER_LANGUAGE") ?? fileOpt(file.language),
+        maxUploadBytes: Number(envOr("PADDOCK_WHISPER_MAX_UPLOAD_BYTES", fileOr(file.maxUploadBytes, String(25 * 1024 * 1024)))),
+    };
+}
+/**
+ * Resolve per-instance branding from env. Defaults preserve today's look, so a
+ * plain instance is unchanged; an operator running several instances from one
+ * image sets `PADDOCK_BRAND_*` in each instance's env to tell them apart.
+ */
+function loadBrandConfig(file = {}) {
+    return {
+        name: envOr("PADDOCK_BRAND_NAME", fileOr(file.name, "Paddock")),
+        logo: envOr("PADDOCK_BRAND_LOGO", fileOr(file.logo, "🐎")),
+        accent: envOr("PADDOCK_BRAND_ACCENT", fileOr(file.accent, "#c2603c")),
+    };
+}
+/**
+ * Default location of the built web SPA, resolved RELATIVE TO THIS MODULE:
+ * `packages/server/{src,dist}/config.js` -> `packages/web/dist`. The same hop
+ * works from both the `tsx src/` and `node dist/` layouts, so neither needs a
+ * `PADDOCK_WEB_DIST` override.
+ *
+ * Takes the module URL as a parameter purely so a test can exercise install
+ * paths this repo's own checkout does not have.
+ *
+ * **`fileURLToPath`, NOT `new URL(url).pathname`.** The raw pathname is
+ * percent-ENCODED, so an install path containing a space or any non-ASCII
+ * character (`/opt/my paddock/`, `~/Développement/`) yields a literal `%20`
+ * that resolves to a directory which does not exist. The failure is SILENT:
+ * `app.ts` degrades to API-only mode with only a log warning, so the user gets
+ * a blank page and no explanation of why. `fileURLToPath` also decodes the
+ * `/C:/...` drive-letter form on Windows. This is irrelevant when the path is
+ * the Docker image's fixed `/app`, and load-bearing the moment the package is
+ * installed under an arbitrary user directory (`npx`, global install).
+ */
+export function resolveDefaultWebDist(moduleUrl) {
+    return path.resolve(path.dirname(fileURLToPath(moduleUrl)), "../../web/dist");
+}
+export function loadPaddockConfig() {
+    // The optional YAML instance-config file provides the BASE layer; env vars
+    // override it (precedence file < env). The file is located under the data dir,
+    // so resolve a BOOTSTRAP data dir from env/default first to find it — the file
+    // may then re-base the data dir for the resolved config below.
+    const bootstrapDataDir = abs(envOr("PADDOCK_DATA_DIR", "./data"));
+    const file = loadConfigFile(bootstrapDataDir);
+    // Ensure the data root exists first so symlinks (e.g. /tmp -> /private/tmp on
+    // macOS) resolve consistently for every derived path below.
+    const dataRoot = abs(envOr("PADDOCK_DATA_DIR", fileOr(file.dataDir, "./data")));
+    try {
+        fs.mkdirSync(dataRoot, { recursive: true });
+    }
+    catch {
+        /* best-effort; downstream mkdirs will surface real errors */
+    }
+    // working_directory of keeper agents MUST be canonical so session discovery
+    // (which encodes the real path) can find Claude transcripts.
+    const dataDir = canonical(dataRoot);
+    const projectsRoot = canonical(envOr("PADDOCK_PROJECTS_DIR", fileOr(file.projectsRoot, path.join(dataRoot, "projects"))));
+    const stateDir = canonical(envOr("PADDOCK_STATE_DIR", fileOr(file.stateDir, path.join(dataRoot, ".herdctl"))));
+    const herdctlConfigPath = canonical(envOr("PADDOCK_HERDCTL_CONFIG", fileOr(file.herdctlConfigPath, path.join(dataRoot, "herdctl.yaml"))));
+    // The ONE Claude home for this process (#588): paddock's transcript symlinks,
+    // the engine's session discovery and session adoption all resolve against this
+    // exact value. NOT canonical()-ed: `claudeHome()` is also what the CLI runtime
+    // and Claude Code itself see, and canonicalising would silently diverge from
+    // the literal path they encode into `<home>/projects/<encoded-cwd>`.
+    const resolvedClaudeHome = claudeHome();
+    const defaultWebDist = resolveDefaultWebDist(import.meta.url);
+    return Object.freeze({
+        port: Number(envOr("PORT", fileOr(file.port, "4000"))),
+        // Safe by default (#435): bind loopback unless explicitly told otherwise, so
+        // a fresh source/tarball run is network-closed. Non-loopback + no auth is then
+        // gated by the bind-safety guard (see bind-safety.ts). Existing deployments
+        // that set HOST/PADDOCK_HOST are unaffected — only the DEFAULT changed from
+        // 0.0.0.0. (The container image keeps ENV HOST=0.0.0.0: the network namespace
+        // is its boundary and Docker can't reach 127.0.0.1 inside the container.)
+        host: envOr("HOST", envOr("PADDOCK_HOST", fileOr(file.host, "127.0.0.1"))),
+        dangerouslyAllowOpen: loadDangerouslyAllowOpen(),
+        dataDir,
+        projectsRoot,
+        stateDir,
+        herdctlConfigPath,
+        webDist: abs(envOr("PADDOCK_WEB_DIST", fileOr(file.webDist, defaultWebDist))),
+        claudeHome: resolvedClaudeHome,
+        auth: loadAuthConfig(file.auth),
+        transcription: loadTranscriptionConfig(file.transcription),
+        brand: loadBrandConfig(file.brand),
+        models: loadModels(file.models),
+        driveMode: loadDriveMode(file.driveMode),
+        nativeSystemPrompt: loadNativeSystemPrompt(file.nativeSystemPrompt),
+        environmentPrompt: loadEnvironmentPrompt(file.environmentPrompt),
+        selfMcpEnabled: loadSelfMcpEnabled(file.selfMcpEnabled),
+        selfMcpWriteEnabled: loadSelfMcpEnabled(file.selfMcpEnabled) && loadSelfMcpWriteEnabled(file.selfMcpWriteEnabled),
+        // Projects tool implies write implies read — the tool is appended in the write
+        // block, so both outer gates must be on for it to mean anything (issue #467).
+        selfMcpProjectsEnabled: loadSelfMcpEnabled(file.selfMcpEnabled) &&
+            loadSelfMcpWriteEnabled(file.selfMcpWriteEnabled) &&
+            loadSelfMcpProjectsEnabled(file.selfMcpProjectsEnabled),
+        maxSpawnDepth: loadMaxSpawnDepth(file.maxSpawnDepth),
+        scheduleMutationEnabled: loadScheduleMutationEnabled(file.scheduleMutationEnabled),
+        ...(() => {
+            // #312 M1: resolved against the real environment (token material is only
+            // ever an `env:` reference). Diagnostics ride along for app.ts to log.
+            const { config, errors, warnings } = resolveManagementApiConfig(file.managementApi, process.env);
+            return { managementApi: config, managementApiDiagnostics: { errors, warnings } };
+        })(),
+        hooksMcpEnabled: loadHooksMcpEnabled(file.hooksMcpEnabled),
+        recovery: loadRecoveryConfig(file.recovery),
+        attachments: loadAttachmentsConfig(file.attachments),
+        curation: loadCurationConfig(file.curation),
+        logLevel: envOr("LOG_LEVEL", fileOr(file.logLevel, "info")),
+        browserMcp: loadBrowserMcp(file.browserMcp),
+        openapi: loadOpenApiConfig(file.openapi),
+        sweepMinIntervalMs: loadSweepMinIntervalMs(file.sweepMinIntervalMs),
+        gitAuthor: {
+            name: envOr("PADDOCK_GIT_AUTHOR_NAME", fileOr(file.gitAuthor?.name, "Paddock")),
+            email: envOr("PADDOCK_GIT_AUTHOR_EMAIL", fileOr(file.gitAuthor?.email, "paddock@localhost")),
+        },
+        githubClientId: envOpt("PADDOCK_GITHUB_CLIENT_ID") ?? fileOpt(file.githubClientId),
+    });
+}
+// CurationConfig + DEFAULT_CURATION now live in ./curation-config.ts (issue #384),
+// alongside the per-project override resolver — mirroring recovery-config.ts.
+/** Resolve one positive-integer budget from env < file < built-in default. */
+function loadCurationNum(envName, file, def) {
+    const raw = envOpt(envName) ?? fileOpt(file);
+    if (raw === undefined)
+        return def;
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : def;
+}
+/** Resolve the curation token budgets (issue #379), precedence env < file < default. */
+function loadCurationConfig(file) {
+    return {
+        overviewMaxTokens: loadCurationNum("PADDOCK_CURATION_OVERVIEW_MAX_TOKENS", file?.overviewMaxTokens, DEFAULT_CURATION.overviewMaxTokens),
+        changelogMaxTokens: loadCurationNum("PADDOCK_CURATION_CHANGELOG_MAX_TOKENS", file?.changelogMaxTokens, DEFAULT_CURATION.changelogMaxTokens),
+        claudeMaxTokens: loadCurationNum("PADDOCK_CURATION_CLAUDEMD_MAX_TOKENS", file?.claudeMaxTokens, DEFAULT_CURATION.claudeMaxTokens),
+    };
+}
+/**
+ * Resolve the post-turn sweep's minimum interval from
+ * `PADDOCK_SWEEP_MIN_INTERVAL_MS` (issue #269 fold). Returns `undefined` when
+ * unset or invalid (non-finite / negative) so the SweepService default (5 min)
+ * applies — preserving the pre-fold `envIntervalMs()` semantics exactly.
+ */
+function loadSweepMinIntervalMs(file) {
+    const raw = envOpt("PADDOCK_SWEEP_MIN_INTERVAL_MS") ?? fileOpt(file);
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+/**
+ * Resolve whether keeper agents receive the Playwright browser MCP
+ * (issue #269 fold). The env var keeps its exact literal-'1' semantics (any
+ * other set value — including `true` — disables it, matching pre-loader
+ * behaviour); only when the env var is UNSET does the config file provide the
+ * base, using the 1/true/yes convention shared by the other boolean knobs.
+ */
+function loadBrowserMcp(file) {
+    const env = process.env.PADDOCK_BROWSER_MCP;
+    if (env !== undefined)
+        return env === "1";
+    const raw = fileOpt(file)?.toLowerCase();
+    return raw === "1" || raw === "true" || raw === "yes";
+}
+/**
+ * Resolve the OpenAPI reference config. `enabled` defaults OFF (opt-in):
+ * publishing the API surface is a deliberate choice, so it only mounts when
+ * `PADDOCK_OPENAPI_ENABLED` / YAML is a truthy value (1/true/yes/on). `path`
+ * (the UI route prefix) defaults `/open-api`; it is normalized to a leading
+ * slash with no trailing slash.
+ */
+function loadOpenApiConfig(file) {
+    const rawEnabled = (process.env.PADDOCK_OPENAPI_ENABLED ??
+        (file?.enabled === undefined ? undefined : String(file.enabled)))?.toLowerCase();
+    const enabled = rawEnabled === "1" || rawEnabled === "true" || rawEnabled === "yes" || rawEnabled === "on";
+    let path = envOpt("PADDOCK_OPENAPI_PATH") ?? fileOpt(file?.path) ?? "/open-api";
+    if (!path.startsWith("/"))
+        path = "/" + path;
+    if (path.length > 1 && path.endsWith("/"))
+        path = path.slice(0, -1);
+    return { enabled, path };
+}
+/**
+ * Resolve the instance-default max spawn depth from `PADDOCK_MAX_SPAWN_DEPTH`
+ * (issue #262). Defaults to {@link DEFAULT_MAX_SPAWN_DEPTH} (`1`); a
+ * missing/blank/out-of-range value falls back to the default rather than failing
+ * startup. A per-project override still wins at dispatch.
+ */
+function loadMaxSpawnDepth(file) {
+    const raw = envOpt("PADDOCK_MAX_SPAWN_DEPTH") ?? fileOpt(file);
+    if (raw === undefined)
+        return DEFAULT_MAX_SPAWN_DEPTH;
+    const n = Number(raw);
+    return isValidMaxSpawnDepth(n) ? n : DEFAULT_MAX_SPAWN_DEPTH;
+}
+/**
+ * Resolve a boolean recovery knob (issue #301) with the shared 1/true/yes
+ * convention, env over file over the built-in default. Mirrors the other boolean
+ * loaders; factored so each recovery flag reads identically.
+ */
+function loadRecoveryBool(env, file, fallback) {
+    const raw = envOr(env, fileOr(file, String(fallback))).toLowerCase();
+    return raw === "1" || raw === "true" || raw === "yes";
+}
+/**
+ * Resolve a non-negative-integer recovery knob (issue #301). A missing/blank/
+ * non-finite/negative value falls back to the default rather than failing
+ * startup — defensive, like {@link loadMaxSpawnDepth}.
+ */
+function loadRecoveryInt(env, file, fallback) {
+    const raw = envOpt(env) ?? fileOpt(file);
+    if (raw === undefined)
+        return fallback;
+    const n = Number(raw);
+    return Number.isInteger(n) && n >= 0 ? n : fallback;
+}
+/**
+ * Resolve the instance-default keeper-chat recovery config (issue #301). Layer 2
+ * (`surfaceKilledTask`) defaults ON, Layer 3 (`autoReDrive`) defaults OFF; the
+ * guards default per {@link DEFAULT_RECOVERY}. Each field is env-over-file-over-
+ * default, and a per-project `recovery` override still wins at dispatch
+ * (resolveRecoveryConfig). Malformed values degrade to the default, never fatal.
+ */
+function loadRecoveryConfig(file) {
+    const f = file ?? {};
+    return {
+        surfaceKilledTask: loadRecoveryBool("PADDOCK_RECOVERY_SURFACE", f.surfaceKilledTask, DEFAULT_RECOVERY.surfaceKilledTask),
+        autoReDrive: loadRecoveryBool("PADDOCK_RECOVERY_AUTODRIVE", f.autoReDrive, DEFAULT_RECOVERY.autoReDrive),
+        debounceMs: loadRecoveryInt("PADDOCK_RECOVERY_DEBOUNCE_MS", f.debounceMs, DEFAULT_RECOVERY.debounceMs),
+        maxRetries: loadRecoveryInt("PADDOCK_RECOVERY_MAX_RETRIES", f.maxRetries, DEFAULT_RECOVERY.maxRetries),
+        limboTimeoutMs: loadRecoveryInt("PADDOCK_RECOVERY_LIMBO_MS", f.limboTimeoutMs, DEFAULT_RECOVERY.limboTimeoutMs),
+    };
+}
+/**
+ * Resolve a positive-integer attachment knob (issue #328). A missing/blank/
+ * non-integer/< 1 value falls back to the default rather than failing startup —
+ * defensive, like {@link loadRecoveryInt} (but size/count must be ≥ 1).
+ */
+function loadAttachmentsInt(env, file, fallback) {
+    const raw = envOpt(env) ?? fileOpt(file);
+    if (raw === undefined)
+        return fallback;
+    const n = Number(raw);
+    return Number.isInteger(n) && n >= 1 ? n : fallback;
+}
+/**
+ * Resolve the `allowedTypes` list (issue #328). The env var is comma-separated
+ * (`PADDOCK_ATTACHMENTS_ALLOWED_TYPES=image/*,.pdf`); the YAML file takes a real
+ * array (or a comma-separated string, coerced the same way). An empty/invalid
+ * value falls back to the default (allow-all) — never "deny all".
+ */
+function loadAllowedTypes(file, fallback) {
+    const env = envOpt("PADDOCK_ATTACHMENTS_ALLOWED_TYPES");
+    const raw = env !== undefined ? env.split(",") : Array.isArray(file) ? file : typeof file === "string" ? file.split(",") : undefined;
+    return sanitizeAllowedTypes(raw) ?? fallback;
+}
+/**
+ * Resolve the instance-default inbound-attachment config (issue #328). Enabled +
+ * allow-all by default; each field is env-over-file-over-default, and a
+ * per-project `attachments` override still wins at request time
+ * (resolveAttachmentsConfig). Malformed values degrade to the default, never fatal.
+ */
+function loadAttachmentsConfig(file) {
+    const f = file ?? {};
+    const enabledRaw = envOr("PADDOCK_ATTACHMENTS_ENABLED", fileOr(f.enabled, String(DEFAULT_ATTACHMENTS.enabled))).toLowerCase();
+    return {
+        enabled: enabledRaw === "1" || enabledRaw === "true" || enabledRaw === "yes",
+        maxFileSizeMb: loadAttachmentsInt("PADDOCK_ATTACHMENTS_MAX_FILE_SIZE_MB", f.maxFileSizeMb, DEFAULT_ATTACHMENTS.maxFileSizeMb),
+        maxFilesPerMessage: loadAttachmentsInt("PADDOCK_ATTACHMENTS_MAX_FILES_PER_MESSAGE", f.maxFilesPerMessage, DEFAULT_ATTACHMENTS.maxFilesPerMessage),
+        allowedTypes: loadAllowedTypes(f.allowedTypes, DEFAULT_ATTACHMENTS.allowedTypes),
+    };
+}
+/**
+ * Resolve the per-deployment schedule-mutation gate (issue #265 / DD-7). Defaults
+ * OFF so a plain instance can't have its schedules mutated programmatically; an
+ * operator opts in with `PADDOCK_SCHEDULE_MUTATION=1` (or the config file). Accepts
+ * 1/true/yes. Static `project.yaml` schedules are armed regardless of this flag.
+ */
+function loadScheduleMutationEnabled(file) {
+    const raw = envOr("PADDOCK_SCHEDULE_MUTATION", fileOr(file, "false")).toLowerCase();
+    return raw === "1" || raw === "true" || raw === "yes";
+}
+/**
+ * Resolve the instance-default hook-management MCP gate (Epic G / G5, GG-4).
+ * Defaults OFF so a plain instance never advertises the hook tools; opt in with
+ * `PADDOCK_HOOKS_MCP=1` (or the config file), and a per-project `hooksMcpEnabled`
+ * override still wins at dispatch. Accepts 1/true/yes. Only meaningful when the
+ * self-MCP write tools are also enabled (the hook tools live on that server).
+ */
+function loadHooksMcpEnabled(file) {
+    const raw = envOr("PADDOCK_HOOKS_MCP", fileOr(file, "false")).toLowerCase();
+    return raw === "1" || raw === "true" || raw === "yes";
+}
+/**
+ * Resolve whether keepers additionally get the self-management MCP WRITE tools
+ * (issue #214 Phase 2). Defaults OFF; only takes effect when `PADDOCK_SELF_MCP`
+ * is also on (write implies read — enforced at the call site above). Accepts
+ * 1/true/yes.
+ */
+function loadSelfMcpWriteEnabled(file) {
+    const raw = envOr("PADDOCK_SELF_MCP_WRITE", fileOr(file, "false")).toLowerCase();
+    return raw === "1" || raw === "true" || raw === "yes";
+}
+/**
+ * Resolve whether keepers additionally get the self-management MCP PROJECT tools
+ * (issue #467 — `create_project`). Defaults OFF; only takes effect when
+ * `PADDOCK_SELF_MCP` and `PADDOCK_SELF_MCP_WRITE` are also on (enforced at the call
+ * site above). Accepts 1/true/yes.
+ */
+function loadSelfMcpProjectsEnabled(file) {
+    const raw = envOr("PADDOCK_SELF_MCP_PROJECTS", fileOr(file, "false")).toLowerCase();
+    return raw === "1" || raw === "true" || raw === "yes";
+}
+/**
+ * Resolve whether keepers get the read-only self-management MCP (issue #214).
+ * Defaults to OFF so a plain instance never advertises it; opt in per instance
+ * with `PADDOCK_SELF_MCP=1`. Accepts 1/true/yes.
+ */
+function loadSelfMcpEnabled(file) {
+    const raw = envOr("PADDOCK_SELF_MCP", fileOr(file, "false")).toLowerCase();
+    return raw === "1" || raw === "true" || raw === "yes";
+}
+/**
+ * Resolve whether keeper agents use the native system prompt + CLAUDE.md
+ * hierarchy (issue #176). Defaults to `true` (native) on every instance so a
+ * seeded instance-wide + per-project `CLAUDE.md` is auto-loaded; set
+ * `PADDOCK_NATIVE_PROMPT` to 0/false/no to fall back to the terse replace
+ * prompt.
+ */
+function loadNativeSystemPrompt(file) {
+    const raw = envOr("PADDOCK_NATIVE_PROMPT", fileOr(file, "true")).toLowerCase();
+    return !(raw === "0" || raw === "false" || raw === "no");
+}
+/**
+ * Resolve the environment system prompt (issue #635): env
+ * `PADDOCK_ENVIRONMENT_PROMPT` over the `environmentPrompt:` file key over the
+ * built-in {@link DEFAULT_ENVIRONMENT_PROMPT}.
+ *
+ * Deliberately does NOT use `envOr`/`fileOr`. Those fold a blank value to the
+ * fallback, which would make opting out impossible — blank is the opt-out here,
+ * so precedence is decided on *definedness*, not on emptiness:
+ *
+ *  - `PADDOCK_ENVIRONMENT_PROMPT` **defined at all** (even empty) wins outright.
+ *    That is why the field is declared `envShadowWhenDefined` in
+ *    instance-config.ts — same rule as `PADDOCK_BROWSER_MCP` — so the Settings
+ *    screen renders it read-only in exactly the cases where it really is.
+ *  - Otherwise a `string` file value wins, empty included. A non-string (a YAML
+ *    number, a mapping, `null` from a bare `environmentPrompt:`) is ignored
+ *    rather than stringified — `"null"` is not a prompt anyone meant to write.
+ *  - Otherwise the built-in default.
+ *
+ * The value is used verbatim: no trimming, no normalization. An operator's
+ * trailing newline or leading indentation survives the round-trip, because the
+ * text is going into a prompt where whitespace is content.
+ */
+function loadEnvironmentPrompt(file) {
+    const env = process.env.PADDOCK_ENVIRONMENT_PROMPT;
+    if (env !== undefined)
+        return env;
+    if (typeof file === "string")
+        return file;
+    return DEFAULT_ENVIRONMENT_PROMPT;
+}
+/**
+ * Resolve the instance model allow-list (issue #457 Step 2), precedence
+ * env `PADDOCK_MODELS` (comma-separated ids) over YAML `models:` (a string array,
+ * or a comma-separated string coerced the same way) over the default (undefined ⇒
+ * every catalog model is offered). Each id is validated against the catalog with
+ * {@link isKnownModel}; unknown/blank/duplicate ids are dropped. If nothing valid
+ * survives — or the list was unset — the result is `undefined`, which downstream
+ * ({@link import("./models.js").resolveModels}) treats as "offer the full catalog",
+ * so an instance is never left with zero models.
+ */
+function loadModels(file) {
+    const env = envOpt("PADDOCK_MODELS");
+    const raw = env !== undefined
+        ? env.split(",")
+        : Array.isArray(file)
+            ? file.map((v) => String(v))
+            : typeof file === "string"
+                ? file.split(",")
+                : undefined;
+    if (raw === undefined)
+        return undefined;
+    const seen = new Set();
+    const ids = [];
+    for (const item of raw) {
+        const id = item.trim();
+        if (!id || seen.has(id) || !isKnownModel(id))
+            continue;
+        seen.add(id);
+        ids.push(id);
+    }
+    // Empty after filtering (all unknown/blank) ⇒ fall back to the full catalog.
+    return ids.length > 0 ? ids : undefined;
+}
+/**
+ * Resolve the global keeper drive mode from `PADDOCK_DRIVE_MODE`. Defaults
+ * to `session` (DEFAULT_DRIVE_MODE, #316); an unrecognized value falls back
+ * to the default rather than failing startup. A per-project `driveMode` still
+ * overrides this at dispatch.
+ */
+function loadDriveMode(file) {
+    const raw = (envOpt("PADDOCK_DRIVE_MODE") ?? fileOpt(file))?.toLowerCase();
+    return raw && isKnownDriveMode(raw) ? raw : DEFAULT_DRIVE_MODE;
+}
+/**
+ * Resolve the Claude home from the environment — `CLAUDE_HOME`, else
+ * `~/.claude`.
+ *
+ * This is the RESOLVER, not the accessor. It is read once by
+ * {@link loadPaddockConfig} into {@link PaddockConfig.claudeHome}; runtime code
+ * should thread `cfg.claudeHome` rather than call this again, so paddock and the
+ * engine can never end up resolving two different homes (#588). It stays a
+ * function (not a constant) because `os.homedir()` must be read at call time —
+ * tests and processes that mutate `HOME` depend on that.
+ */
+export function claudeHome() {
+    return process.env.CLAUDE_HOME ?? path.join(os.homedir(), ".claude");
+}