Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
107 KB
Raw Blame
import { readFileSync, writeFileSync, mkdirSync, chmodSync, existsSync, renameSync } from 'fs';
import { isAbsolute, join } from 'path';
import { homedir } from 'os';
import type { EngineConfig, EmbeddingColumnConfig } from './types.ts';
import { applyDbPlaneReadSideMerge, type DbPlaneEngineReader } from './config-db-merge.ts';
import { loadConfigSnapshot } from './config-snapshot.ts';
import { loadGbrainEnvFile } from './gbrain-env-file.ts';
import { dotenvValuesForKey } from './env-trust.ts';
import { REMOTE_PRIVATE_PAGES_KEY } from './search/private-visibility.ts';
import { RUNTIME_READER_CONFIG_KEYS } from './config-runtime-keys.ts';
import { mergeServeCliSocket, mergeServeVectorPrewarm } from './published-config.ts';
export { MERGED_CONFIG_BY_ENGINE } from './published-config.ts';

/**
 * Where is the active DB URL coming from? Pure introspection, no connection
 * attempt. Used by `gbrain doctor --fast` so the user gets a precise message
 * instead of the misleading "No database configured" when GBRAIN_DATABASE_URL
 * (or DATABASE_URL) is actually set.
 *
 * Precedence matches loadConfig(): env vars win over config-file URL. Returns
 * null only when NO source provides a URL at all.
 */
export type DbUrlSource =
  | 'env:GBRAIN_DATABASE_URL'
  | 'env:DATABASE_URL'
  | 'config-file'
  | 'config-file-path' // PGLite: config file present, no URL but database_path set
  | null;

// Internal aliases retained for backwards compatibility with the existing call
// sites below. They forward to the exported configDir()/configPath() so
// GBRAIN_HOME is honored uniformly. Lazy: never call homedir() at module scope.
function getConfigDir() { return configDir(); }
function getConfigPath() { return configPath(); }

export interface GBrainConfig {
  engine: 'postgres' | 'pglite';
  /** File-plane hook-lane keys (read by engine-free hook/push children).
   * `gbrain config set` routes these two dotted keys here, not to the DB. */
  push?: { allow_unverified_remote?: boolean };
  hooks?: { stop_push_debounce_min?: number | string };
  /** #7242 terminal hook (minions/terminal-hook.ts): file plane only, read by `gbrain jobs work`. */
  minions?: { terminal_hook?: string[] | { argv: string[]; timeout_ms?: number } };
  /** Ambient-writeback MIRROR of the DB-plane `memory.*` keys — `gbrain
   * config set memory.*` dual-writes both planes so the engine-free Stop-hook
   * child and the stdio boot resolve see the same truth the serve does. The
   * DB plane stays authoritative (the serve-side harvest gate re-checks it).
   * Resolved by src/core/facts/writeback-config.ts. */
  /** Declared brain audience MIRROR (WP8; DB plane authoritative like
   * `memory.*`): the engine-free bootstrap-harness lane gates its
   * ambient-writeback enable-nudge on it — a shared-declared brain is never
   * nudged. Written by `gbrain config set brain.audience personal|shared`. */
  brain?: { audience?: string };
  memory?: {
    auto_writeback?: string;
    auto_writeback_transient_ttl?: string;
    /** Visibility POSTURE cache stamped by `config set memory.*` (which has
     * the engine to resolve the DB-plane facts.default_visibility) so the
     * engine-free bootstrap-harness renderer can embed it. Doctor's
     * block-drift check catches staleness against DB truth. */
    visibility_posture?: string;
  };
  /**
   * Third-party integration gates, file-plane (read by engine-free hook
   * children). `integrations.memorable.enabled` gates the optional
   * session-end relay to a locally-installed `memorable` CLI — absent or
   * anything other than literal `true` means OFF (fail-closed). The boolean
   * alone is NOT sufficient: the gate also requires the gbrain-authored
   * consent stamp (`~/.gbrain/integrations/hooks/memorable-consent.json`,
   * written only by `gbrain config set`'s disclosure flow — deliberately
   * outside this file, which the external CLI rewrites). See
   * memorableGateAllowed in core/context/hook-heartbeat.ts.
   */
  integrations?: { memorable?: { enabled?: boolean } };
  /** Monthly backup-coverage check. File-plane for engine-free hook children. */
  backup?: { check_enabled?: boolean | string; check_interval_days?: number | string };
  /** #5232: CLI write wait in ms (file plane; persistence/write-wait.ts). */
  persistence?: { write_wait_ms?: number | string };
  migrate?: { graduation?: boolean }; // `migrate.graduation false`: legacy copier instead of graduation (file plane, read pre-connect)
  doctor?: { default_budget_ms?: number | string }; // #6803: non-interactive CLI doctor --json check-run cap (file plane, read pre-connect; 0 off)
  /** A4 user preapprovals (file plane only; set by the trusted local CLI; read by core/consent.ts). */
  consent?: { preapprove?: { paid?: { max_usd_per_run?: number }; persistent_install?: boolean } };
  database_url?: string;
  database_path?: string;
  openai_api_key?: string;
  anthropic_api_key?: string;
  /**
   * OpenRouter API key. File-plane slot so `gbrain config set
   * openrouter_api_key X` (or config.json) reaches the openrouter recipe:
   * file plane → loadConfig env merge → buildGatewayConfig env dict → recipe
   * reads OPENROUTER_API_KEY.
   */
  openrouter_api_key?: string;

  voyage_api_key?: string;
  /**
   * Alibaba DashScope API key (#3500). File-plane slot so config.json's
   * `dashscope_api_key` reaches the dashscope / dashscope-rerank recipes:
   * file plane → buildGatewayConfig env dict → recipe reads
   * DASHSCOPE_API_KEY. Same fold pattern (and same DB-plane caveat) as
   * voyage_api_key above.
   */
  dashscope_api_key?: string;
  deepseek_api_key?: string;
  /**
   * LiteLLM proxy API key. File-plane slot folded into the gateway env as
   * LITELLM_API_KEY (optional in the litellm recipe — proxies may run
   * unauthenticated locally). Closed alongside litellm's chat touchpoint
   * (v0.42.61.0): once litellm became a full chat provider, daemon/launchd/
   * MCP contexts hit the same config-plane gap voyage did (#2662). Same
   * fold pattern (and same DB-plane caveat) as voyage_api_key above.
   */
  litellm_api_key?: string;
  /**
   * Together AI API key. File-plane slot folded into the gateway env as
   * TOGETHER_API_KEY (required by the together recipe). Same fold pattern
   * (and same DB-plane caveat) as voyage_api_key above.
   */
  together_api_key?: string;
  /**
   * Google Gemini API key (#3500). File-plane slot folded into the gateway
   * env as GOOGLE_GENERATIVE_AI_API_KEY (the name the google recipe reads).
   * buildGatewayConfig also accepts process-env GEMINI_API_KEY — the name
   * Google's own docs/SDKs use — as an alias for
   * GOOGLE_GENERATIVE_AI_API_KEY. Same fold pattern (and same DB-plane
   * caveat) as voyage_api_key above.
   */
  google_api_key?: string;
  /**
   * Azure OpenAI API key (#4031). File-plane slot folded into the gateway env
   * as AZURE_OPENAI_API_KEY (the name the azure-openai recipe reads). Same
   * fold pattern (and same DB-plane caveat) as voyage_api_key above. Key-based
   * auth alternative to the Entra flow below.
   */
  azure_openai_api_key?: string;
  /** Azure OpenAI (keyless/Entra). Non-secret endpoint/deployment + Entra opt-in;
   * bearer token is minted at request time via `az` — no secret stored here. */
  azure_openai_endpoint?: string;
  azure_openai_deployment?: string;
  azure_openai_use_entra?: string;

  embedding_model?: string;
  embedding_dimensions?: number;
  /**
   * v0.37 (D9): user opted into deferred-setup mode at init time via
   * `gbrain init --no-embedding`. When true, embed callsites and `gbrain
   * import` refuse with a `gbrain config set embedding_model <id>` hint
   * rather than proceeding with a default that may not match a real key.
   * Mutually exclusive with `embedding_model` being set — init writes one
   * or the other, never both.
   */
  embedding_disabled?: boolean;
  expansion_model?: string;
  /**
   * Default chat model for `gateway.chat()` callers (v0.27+).
   * Default: "anthropic:claude-sonnet-4-6" (dateless per Anthropic's v0.31.12+ model-ID format).
   */
  chat_model?: string;
  /**
   * Optional chat fallback chain for `chatWithFallback()` (v0.27+): tried in
   * order when a chat call fails or refuses. Each entry is a "provider:modelId"
   * string. Judge, critic and eval call sites pin their model (allowFallback).
   */
  chat_fallback_chain?: string[];
  /** `false`: the chain still covers errors but never forwards a refused request. Default true (env, file, DB). */
  chat_fallback_on_refusal?: boolean;
  /** Optional base URL overrides for openai-compatible providers (keyed by recipe id). */
  provider_base_urls?: Record<string, string>;
  /** Optional chat request providerOptions overrides keyed by recipe id or "recipe:modelId". */
  provider_chat_options?: Record<string, Record<string, unknown>>;
  /**
   * MEMORY_VERBS v1 (Cathedral 1): default MCP tool surface for `gbrain serve`.
   * 'verbs' = exactly the 7 protocol verbs (the quickstart surface);
   * 'starter' (WP4) = the ~20-op daily-driver set (STARTER_OPS in
   * src/mcp/surface.ts); 'full' (default) = every operation. The `--surface`
   * flag overrides per-run. On the OAuth HTTP transport this resolves the
   * server CEILING (D2): per-client row surfaces can narrow below it but
   * never widen past it.
   */
  mcp_surface?: 'verbs' | 'starter' | 'full';
  /**
   * MEMORY_VERBS v1 [D6C]: ISO timestamp stamped by `gbrain init` so
   * `gbrain protocol stats` can derive real TTHW (install → first verb call).
   */
  protocol_installed_at?: string;
  /**
   * Optional storage backend config (S3/Supabase/local). Shape matches
   * `StorageConfig` in `./storage.ts`. Typed as `unknown` here to avoid
   * a cyclic import; callers pass this through `createStorage()` which
   * validates the shape at runtime.
   */
  storage?: unknown;
  /**
   * v0.25.0 — session capture settings. Read via file-plane `loadConfig()`
   * at process boot (NOT `gbrain config set` which writes the DB plane —
   * those are different stores). Edit `~/.gbrain/config.json` directly.
   * All fields default to ON — capture and scrubbing both opt-out.
   */
  /**
   * v0.41 — autopilot daemon configuration. Currently houses the nightly
   * quality probe feature flag (default OFF — opt-in to protect API spend
   * on fresh installs). Flag is gated INSIDE the autopilot tick body;
   * absence means "do not run nightly probe."
   */
  autopilot?: {
    nightly_quality_probe?: {
      /** Enable the nightly probe in the autopilot loop. Defaults to false. */
      enabled?: boolean;
      /**
       * Run-level cap (USD) over every paid call of one probe run (LongMemEval
       * and judges). Default 5; a set value is a user cap (unpriced → no_pricing).
       */
      max_usd?: number;
    };
    /**
     * v0.41.16.0 — nightly conversation-parser probe. Per D10: default ON
     * for `search.mode=tokenmax` brains, opt-in for conservative/balanced.
     * ~$0.05/night with the committed fixtures × Haiku polish. Gated
     * INSIDE the autopilot tick body, like nightly_quality_probe.
     */
    conversation_parser_probe?: {
      /** Enable for non-tokenmax modes. Defaults to false. */
      enabled?: boolean;
    };
    /**
     * v0.42.x (#1685 GAP D) — extract_atoms backlog auto-drain. Default ON so a
     * pack-gated silent backlog never piles up unseen; daily-spend-capped so the
     * Haiku spend stays bounded. Read via the DB plane (`engine.getConfig`) at
     * each autopilot tick. Disable with `gbrain config set autopilot.auto_drain.enabled false`.
     */
    auto_drain?: {
      /** Master switch. Default true. */
      enabled?: boolean;
      /** Per-drain wallclock budget in seconds. Default 120. */
      window_seconds?: number;
      /** Backlog must exceed this to trigger a drain. Default 25. */
      threshold?: number;
      /** Daily spend cap (USD); bounds drains/day = floor(cap / ~$0.30). Default 2.0. */
      max_usd_per_day?: number;
    };
    /**
     * v0.42 — extract frontmatter (`sources:`/`related:` etc.) link edges too, not
     * just body links, on every extraction path: the incremental cycle, sync's
     * inline extract, the GitHub/Google source inline extracts, the extract_stale
     * minion, `gbrain maintain`, and a flagless stale extract sweep
     * (src/core/extract-frontmatter.ts resolves it once for all of them).
     * Keeps externally-edited YAML edges fresh without a full rescan. Default
     * false (body links only). Read via the file/DB plane, file wins. Enable with
     * `gbrain config set autopilot.incremental_extract_include_frontmatter <bool>`.
     */
    incremental_extract_include_frontmatter?: boolean;
  };
  eval?: {
    /** false disables capture entirely. Defaults to true. */
    capture?: boolean;
    /** false disables PII scrubbing before insert. Defaults to true. */
    scrub_pii?: boolean;
  };
  /**
   * Adaptive return-sizing (search/return-policy.ts, default OFF). DB-plane
   * `search.adaptive_return*` rows nest here via loadConfigWithEngine (file > DB).
   */
  search?: {
    adaptive_return?: boolean;
    adaptive_return_entity_max?: number;
    adaptive_return_other_max?: number;
    adaptive_return_min_keep?: number;
    /** #5824 rollback switch (search/vector-legacy-guard.ts); file > DB, env wins over both. */
    vector_legacy_guard?: boolean;
    /** #6132 pgvector iterative scan mode (search/hnsw-iterative-scan.ts); file > DB, env wins over both. */
    hnsw_iterative_scan?: string;
    /** #5989 CJK keyword arm deadline in ms (search/cjk-keyword-deadline.ts); file > DB. */
    cjk_keyword_deadline_ms?: number;
    /** #6495 Postgres keyword/title statement_timeout in ms (postgres-engine/keyword-statement-timeout.ts); file > DB, resolved per connection. */
    keyword_statement_timeout_ms?: number;
  };

  /**
   * v0.42 — self-upgrade settings (file plane; read on the hot path before any
   * DB connect, so it must live here, not the DB plane). `mode` is the only
   * knob most users touch: `notify` (default — emit a marker + 4-option prompt),
   * `auto` (silent quiet-hours/idle upgrade; opt-in), `off` (never check).
   * The rest are state the self-upgrade machinery manages.
   */
  self_upgrade?: {
    mode?: 'auto' | 'notify' | 'off';
    channel?: 'stable' | 'alpha' | 'latest';
    /** Set true once the upgrade-time consent prompt has been shown. */
    mode_prompted?: boolean;
    /** Quiet-hours window for the autopilot silent channel. */
    quiet_hours?: { start?: number; end?: number; tz?: string };
    /** Versions that failed a prior auto-upgrade; never auto-retried. */
    failed_versions?: string[];
    /** Pre-swap breadcrumb so a crash-on-launch version is attributable. */
    attempting_version?: string;
    /** Epoch ms of the last auto-channel check (24h throttle). */
    last_check_ts?: number;
    last_applied_version?: string;
    /** #8776: a launcher outside gbrain's service starts autopilot again when it exits (`gbrain upgrade` hands it over). */
    autopilot_launcher?: 'external';
  };

  /**
   * v0.27.1 — multimodal ingestion flags. Default off; opt-in.
   *
   * Unlike `embedding_model` / `embedding_dimensions` (which size the
   * schema and must be set before initSchema), these flags only affect
   * runtime behavior. They live in the DB plane primarily — `gbrain config
   * set embedding_multimodal true` flips the gate without touching the file.
   * loadConfigWithEngine() merges DB config on top of file/env. Env vars
   * still win as the operator escape hatch.
   */
  embedding_multimodal?: boolean;
  /** Model override for multimodal embeddings (e.g. "voyage:voyage-multimodal-3"). */
  embedding_multimodal_model?: string;
  /** DB-plane `serve.cli_socket`: the serve opens the warm CLI socket without `--cli-socket` (see published-config.ts). */
  serve_cli_socket?: boolean;
  /** DB-plane `serve.vector_prewarm`: the serve prewarms the HNSW indexes into shared_buffers once at start (core/vector-prewarm.ts), default off. */
  serve_vector_prewarm?: boolean;

  /**
   * v0.42 (#1981) — Retrieval Reflex. The context engine's deterministic
   * per-turn entity-pointer injection. Default ON (absent key = enabled).
   *
   * IMPORTANT: this is a FILE-PLANE / env gate only. The context engine reads
   * it via the synchronous `loadConfig()` during `assemble()`, which never
   * touches the DB. So `gbrain config set retrieval_reflex false` (DB plane)
   * does NOT disable the reflex — set it in `~/.gbrain/config.json` or via
   * `GBRAIN_RETRIEVAL_REFLEX=false`.
   */
  retrieval_reflex?: boolean;
  /** Max pointers injected per turn (default 3). File-plane only. */
  retrieval_reflex_max_pointers?: number;
  /**
   * v0.43 (#2095) — how many recent turns the reflex extracts entities from
   * (default 4). 1 reproduces the legacy current-turn-only behavior (and the
   * legacy slug+title suppression). File-plane / env
   * (GBRAIN_RETRIEVAL_REFLEX_WINDOW_TURNS) only — same plane as the other
   * reflex knobs.
   */
  retrieval_reflex_window_turns?: number;
  /**
   * v0.46.15 (identity wave) — kill switch for the reflex's lexical recall
   * arms (lowercase weak-candidate alias arm + surname arm). Default ON
   * (absent = enabled); `false` reproduces pre-wave resolution exactly.
   * File-plane / env (GBRAIN_RETRIEVAL_REFLEX_LEXICAL_ARMS) only — same
   * plane as the other reflex knobs; a false-fire regression in production
   * reverts on the next turn with a config edit, no redeploy.
   */
  retrieval_reflex_lexical_arms?: boolean;
  /**
   * 2026-08 fix wave — kill switch for the reflex's volunteer arm (Arm 2:
   * confidence-gated volunteered pages fused after the pointer budget, parity
   * with the claude-code turn-context lane). Default ON (absent = enabled).
   * File-plane / env (GBRAIN_RETRIEVAL_REFLEX_VOLUNTEER) only — same plane as
   * the other reflex knobs; the incident lever is the env var.
   */
  retrieval_reflex_volunteer?: boolean;
  embedding_image_ocr?: boolean;
  embedding_image_ocr_model?: string;

  /**
   * v0.36 — embedding-column registry (D7). Maps a content_chunks column
   * name to its provider + dimensions + pgvector type. Both keys live in
   * the DB plane (`gbrain config set ...`) so users can flip without
   * editing files. Resolver merges this with `BUILTIN_EMBEDDING_COLUMNS`
   * (which derive their provider from `embedding_model` /
   * `embedding_multimodal_model`).
   *
   * Validation lives in `src/core/search/embedding-column.ts` per D12 —
   * keys must match `/^[a-z_][a-z0-9_]*$/`, type in {vector, halfvec},
   * dimensions 1..8192, provider parseable as `provider:model`.
   */
  embedding_columns?: Record<string, EmbeddingColumnConfig>;
  /**
   * v0.36 — name of the column hybridSearch uses by default. Per-call
   * `SearchOpts.embeddingColumn` overrides this; absent => 'embedding'.
   * Validated against the merged `embedding_columns` registry at config-
   * set time and on hybridSearch entry.
   */
  search_embedding_column?: string;

  /**
   * v0.41 content-sanity tunables. Read via file/env/DB plane (D1: lint
   * lifts to DB config when reachable). Resolution order:
   * env > file > DB > defaults from `src/core/content-sanity.ts`.
   *
   * Both lint AND ingest go through the same effective resolution so a
   * `gbrain config set content_sanity.bytes_block N` flips both surfaces
   * uniformly. CI without `~/.gbrain/` falls through to env/defaults.
   */
  content_sanity?: {
    /** Stderr warn + lint `huge-page` rule fires above this (UTF-8 bytes
     *  of compiled_truth + timeline). Default: 50_000. Env override:
     *  `GBRAIN_PAGE_WARN_BYTES`. */
    bytes_warn?: number;
    /** Soft-block: page writes with `frontmatter.embed_skip` set but
     *  embedder skips on next sweep. Default: 500_000. Env override:
     *  `GBRAIN_PAGE_BLOCK_BYTES`. */
    bytes_block?: number;
    /** Master switch for the built-in junk-pattern set. Default: true.
     *  Env override: `GBRAIN_NO_JUNK_PATTERNS=1` flips to false. */
    junk_patterns_enabled?: boolean;
    /** #4702 — built-in junk-pattern names to skip individually (e.g.
     *  `['access_denied']` for a brain whose pages quote that error rather
     *  than being it). Finer than `junk_patterns_enabled: false` (the
     *  coarser knob, which drops EVERY pattern) and than the `disabled`
     *  kill-switch (which also drops the load-bearing size gates). Unknown
     *  names are ignored. DB plane accepts a JSON array or a comma-
     *  separated list: `gbrain config set content_sanity.disabled_patterns
     *  access_denied,error_title`. */
    disabled_patterns?: string[];
    /** Master kill-switch for all sanity checks. When true, ingest emits
     *  loud stderr per page but lets everything through. Default: false.
     *  Env override: `GBRAIN_NO_SANITY=1` flips to true. */
    disabled?: boolean;
    /** Disposition for high-confidence junk (Cloudflare/CAPTCHA pattern or
     *  operator literal). `quarantine` (default) = page lands hidden +
     *  reviewable; `reject` = hard-block (throw → sync-failure). Issue #1699.
     *  No env override (a destructive flip belongs in explicit config). */
    junk_disposition?: 'quarantine' | 'reject';
    /** Max markup:total ratio before the fuzzy markup-heavy FLAG fires
     *  (page stays searchable, agent warned). Default: 0.85. Env override:
     *  `GBRAIN_MAX_MARKUP_RATIO`. */
    max_markup_ratio?: number;
    /** Master switch for the prose/markup pass. Default: true. When false,
     *  no markup-heavy flagging happens (patterns + oversize still apply). */
    prose_check_enabled?: boolean;
  };

  /**
   * v0.41.2.1 — dream cycle config (synthesize + patterns phases).
   * Read-precedence per key: file > DB > defaults. There are no
   * `GBRAIN_DREAM_*` env vars; do not add an env layer without first
   * extending `loadConfig()` to read them.
   *
   * Existing consumers (synthesize.ts, patterns.ts) read these keys
   * directly via `engine.getConfig()`, so they already see DB-plane
   * values. The structured shape here exists so consumers that read
   * the merged config object (e.g. extract-atoms.ts) see the values
   * uniformly without per-call-site `engine.getConfig()` fallbacks.
   *
   * Closes PR #1416's "silent dream.* config misses on DB-plane writes"
   * for the merged-config code path.
   */
  dream?: {
    synthesize?: {
      session_corpus_dir?: string;
      meeting_transcripts_dir?: string;
      verdict_model?: string;
      max_prompt_tokens?: number;
      max_chunks_per_transcript?: number;
      subagent_timeout_ms?: number;
      subagent_wait_timeout_ms?: number;
    };
    patterns?: {
      lookback_days?: number;
      min_evidence?: number;
    };
  };

  /**
   * #2119-class read-side (also #2137/#4297) — flat map of DB-plane `cycle.*`
   * knobs, keyed by the path UNDER the `cycle.` prefix (e.g.
   * `cycle.extract_atoms.budget_usd` → `cycle['extract_atoms.budget_usd']`),
   * values raw strings (each consumer owns its parse, as with
   * `engine.getConfig()`). Populated by `loadConfigWithEngine()`; per-leaf
   * precedence file > DB (no env layer). See src/core/config-db-merge.ts.
   */
  cycle?: Record<string, string>;

  /**
   * Thin-client mode (multi-topology v1). When set, this install does NOT
   * have a local DB; it talks to a remote `gbrain serve --http` over MCP.
   * The CLI dispatch guard in `src/cli.ts` checks for this field BEFORE
   * `connectEngine` and refuses any DB-bound subcommand. The `engine` field
   * above is still populated (default-inferred) but never used.
   *
   * Two URLs because OAuth discovery + `/token` live at the issuer root,
   * while tool dispatch lives at `/mcp`. They compose from a common base
   * in the typical setup but the config keeps them explicit so reverse-proxy
   * topologies work.
   *
   * `oauth_client_secret` can also be supplied via the
   * `GBRAIN_REMOTE_CLIENT_SECRET` env var (preferred for headless agents);
   * env-var value wins when both are present.
   */
  remote_mcp?: {
    issuer_url: string;
    mcp_url: string;
    oauth_client_id: string;
    oauth_client_secret?: string;
  };

  /**
   * v0.38 — active schema pack name (D13 tier 6 in the 7-tier resolution
   * chain). The pack drives type inference, alias closure for search,
   * link-verb regexes, expert-routing flags, and enrichment dispatch.
   * Default: `gbrain-base` (reproduces pre-v0.38 hardcoded behavior).
   *
   * Resolution priority (highest → lowest, per D13):
   *   1. Per-call SearchOpts.schema_pack (CLI-only; rejected for remote callers)
   *   2. GBRAIN_SCHEMA_PACK env var
   *   3. Per-source DB config `schema_pack.source.<id>`
   *   4. Brain-wide DB config `schema_pack`
   *   5. gbrain.yml `schema:` section
   *   6. THIS field (~/.gbrain/config.json)
   *   7. Default 'gbrain-base'
   *
   * `gbrain config set schema_pack <name>` writes the DB plane (tier 4);
   * editing this file directly writes tier 6. Env var (tier 2) is the
   * operator escape hatch.
   */
  schema_pack?: string;

  /**
   * PR1 — MCP skill-catalog publishing. Lets a thin MCP client (Codex desktop,
   * Claude Code, Perplexity) discover and follow this agent repo's skills over
   * `gbrain serve`. See `src/core/skill-catalog.ts` for the trust-boundary memo.
   */
  mcp?: {
    /**
     * #4748 — deployment-specific identity and routing guidance appended to
     * the canonical operating contract in the MCP initialize response (all
     * three transports). Distinguishes brains sharing one tool catalog.
     * `GBRAIN_MCP_INSTRUCTIONS` env overrides this slot; blank/absent keeps
     * the initialize response byte-identical to the canonical contract.
     */
    instructions?: string;
    /**
     * Gate for `list_skills` / `get_skill` over a REMOTE transport. Runtime
     * default is OFF (absent key → OFF) so an upgrade never silently grants
     * existing read tokens host-skill read. `gbrain init` writes `true` for new
     * installs; the upgrade migration prompts existing owners to enable it.
     * Local CLI callers (`ctx.remote === false`) bypass the gate entirely.
     */
    publish_skills?: boolean;
    /**
     * Gate for the `advisor` op over a REMOTE transport (#2180). Separate from
     * `publish_skills` because the advisor exposes operational diagnostics
     * (version drift, stalled jobs, embedding-key presence), not prose skills.
     * Default OFF; local CLI callers bypass. The MCP advisor is read-only.
     */
    publish_advisor?: boolean;
    /**
     * Explicit skills-dir override. Wins over autodetect — makes which skills
     * get published deterministic across laptop / daemon / container launches.
     * When unset, the ops autodetect (remote callers exclude the install-path
     * tier so a hosted gbrain never serves its own bundled dev skills).
     */
    skills_dir?: string;
    /**
     * WP3 — unknown tool-call argument posture for MCP dispatch.
     *   'warn' (default / absent): unknown params are accepted; each call
     *     collects `_meta.warnings` + a model-visible notice block, and the
     *     request logs as 'success_with_warnings'.
     *   'reject': unknown params return `invalid_params` (with a
     *     did-you-mean suggestion), and tool schemas are emitted with
     *     `additionalProperties: false`.
     * Dual-plane: DB plane (`gbrain config set mcp.strict_params ...`) wins
     * over this file slot. See src/mcp/validate-params.ts.
     */
    strict_params?: 'warn' | 'reject';
    /**
     * WP4 (D2 / plan OQ1) — default surface for OAuth clients whose
     * `oauth_clients.surface` row value is NULL. oauth_clients carries no
     * DCR-origin marker, so this applies to ALL null-surface clients (not
     * just dynamically-registered ones); operators pre-seed important
     * clients with `gbrain auth rescope-client <id> --surface full`.
     * Unset (default) = null-surface clients get the server ceiling —
     * pre-WP4 behavior, existing clients untouched. Dual-plane: the DB
     * plane (`gbrain config set mcp.default_surface_dcr starter`) wins
     * over this file slot. Always bounded by the server ceiling (D2).
     */
    default_surface_dcr?: 'verbs' | 'starter' | 'full';
    /** Tools listed to agents (callable set unchanged; request_tools reaches the rest). Dual-plane, DB > file. */
    advertised_surface?: 'verbs' | 'starter' | 'full';
    /** Search/query row shape for remote MCP callers: 'lean' (default) | 'full'. Dual-plane, DB > file. */
    result_rows?: 'lean' | 'full';
    /** Stdio `request_tools {surface}` widens the session's tool surface (default true). Dual-plane, DB > file. */
    allow_session_widen?: boolean | string;
  };
}

/**
 * True when this install is configured as a thin client of a remote
 * `gbrain serve --http`. Single source of truth for the "is this a
 * thin-client install?" check used by the CLI dispatch guard, doctor
 * branch, and remote subcommands.
 */
/**
 * The ONE robust negative parse for boolean env kill switches (2026-08 wave
 * DRY sweep — previously copy-pasted at four sites with cross-referencing
 * comments): case-insensitive false/0/off/no, so an operator typing FALSE or
 * off mid-incident never gets a silent no-op (adversarial F11). An env value
 * that is unset or empty is NOT "disabled" — callers gate on presence first.
 */
export function isEnvDisabled(value: string): boolean {
  return /^(false|0|off|no)$/i.test(value.trim());
}

export function isThinClient(config: GBrainConfig | null): boolean {
  return !!config?.remote_mcp;
}

/**
 * Load config with credential precedence: env vars > config file.
 * Plugin config is handled by the plugin runtime injecting env vars.
 */
// v0.36.x #1086: translate legacy `provider` + `model` config shape (seen in
// pre-v0.32 docs and some community templates) to the canonical
// `embedding_model: "<provider>:<model>"`. Without this translation, sync
// and embed silently fell through to the hardcoded OpenAI default, blocking
// Voyage / Cohere / Mistral users from using their configured provider.
function migrateLegacyEmbeddingConfig(raw: Record<string, unknown>): Record<string, unknown> {
  if (raw.embedding_model !== undefined) return raw;
  const provider = typeof raw.provider === 'string' ? raw.provider : undefined;
  const model = typeof raw.model === 'string' ? raw.model : undefined;
  if (!provider || !model) return raw;
  // Strip the legacy keys to avoid downstream confusion. Emit a one-line
  // stderr nudge so the operator updates their config to the canonical shape.
  const rest = { ...raw };
  delete rest.provider;
  delete rest.model;
  rest.embedding_model = `${provider}:${model}`;
  console.warn(
    `[config] legacy "provider" + "model" detected; using "${rest.embedding_model}".` +
    ` Rewrite ~/.gbrain/config.json to: "embedding_model": "${rest.embedding_model}".`,
  );
  return rest;
}

/**
 * File-only config loader. Reads ~/.gbrain/config.json and applies the
 * legacy embedding-config migration shim. Does NOT merge env vars, does
 * NOT infer engine kind from DATABASE_URL.
 *
 * Used by `gbrain init`'s config-merge path (B.4) where loading
 * `loadConfig()` would poison the saved file with transient env state
 * (e.g. a CI run with DATABASE_URL set writes a Postgres config.json
 * for a PGLite brain). Read-path callers should keep using `loadConfig()`
 * because env vars are the canonical operator escape hatch at runtime.
 *
 * v0.37 fix wave (CDX-5 from round 1). Pinned by test/config-file-only-loader.test.ts.
 */
export function loadConfigFileOnly(): GBrainConfig | null {
  try {
    const raw = readFileSync(getConfigPath(), 'utf-8');
    const parsed = JSON.parse(raw) as Record<string, unknown>;
    return migrateLegacyEmbeddingConfig(parsed) as unknown as GBrainConfig;
  } catch {
    return null;
  }
}

/**
 * #427 guard — DATABASE_URL hijack via Bun's cwd .env auto-load.
 *
 * Bun merges `.env` files from the process cwd into process.env before any
 * user code runs, so running gbrain inside any checkout whose `.env` defines
 * DATABASE_URL (Next.js, Hono, Supabase, most web apps) would silently
 * retarget the brain at that app's database — `apply-migrations` could write
 * gbrain's schema into a production app database (the v0.42.8 report on #427).
 * The cwd-.env parser (`CWD_DOTENV_FILES`, `dotenvValuesForKey`) lives in
 * env-trust.ts beside the key-presence security quarantine; both symbols are
 * re-exported here so import sites never chase the move. This guard keeps
 * VALUE-match semantics: a DATABASE_URL equal to a cwd-.env assignment is
 * file-origin; a deliberate export that happens to EQUAL it would have chosen
 * the same database anyway, and GBRAIN_DATABASE_URL is never auto-ignored.
 */
export { CWD_DOTENV_FILES, dotenvValuesForKey } from './env-trust.ts';

let warnedCwdEnvDbUrlIgnored = false;

/**
 * The env-provided DB URL gbrain should honor, with the #427 guard applied:
 * a DATABASE_URL whose value matches an assignment in a cwd .env file is
 * treated as belonging to the project in cwd, not to gbrain, and ignored
 * with a one-time stderr notice. GBRAIN_DATABASE_URL is always honored.
 * `dir` is injectable for tests; callers use the default.
 */
export function effectiveEnvDatabaseUrl(dir: string = process.cwd()): string | undefined {
  if (process.env.GBRAIN_DATABASE_URL) return process.env.GBRAIN_DATABASE_URL;
  const url = process.env.DATABASE_URL;
  if (!url) return undefined;
  if (dotenvValuesForKey('DATABASE_URL', dir).has(url)) {
    if (!warnedCwdEnvDbUrlIgnored) {
      warnedCwdEnvDbUrlIgnored = true;
      console.warn(
        '[config] Ignoring DATABASE_URL auto-loaded by Bun from a .env file in the current ' +
        'directory — it belongs to the project here, not to gbrain. Using the engine from ' +
        '~/.gbrain/config.json instead. To point gbrain at that database deliberately, set ' +
        'GBRAIN_DATABASE_URL.',
      );
    }
    return undefined;
  }
  return url;
}

/**
 * The #427 shadow predicate, single-homed: a bare DATABASE_URL exists in the
 * process env but the cwd-.env guard excluded it (and GBRAIN_DATABASE_URL is
 * unset) — the "init inside a web-app checkout" confusion shape. Consumers:
 * engine-status, db-repair, the CLI's no-config marker site.
 */
export function envShadowDetected(dir: string = process.cwd()): boolean {
  return (
    typeof process.env.DATABASE_URL === 'string' &&
    process.env.DATABASE_URL.length > 0 &&
    !process.env.GBRAIN_DATABASE_URL &&
    effectiveEnvDatabaseUrl(dir) === undefined
  );
}

export function loadConfig(): GBrainConfig | null {
  // #3893 (reimplemented from @y2688): fill process.env from the
  // operator-owned ~/.gbrain/.env BEFORE the env-over-file merge below, so
  // secrets can live outside config.json. Shell-exported env always wins
  // (the loader never overrides an existing var), and cwd .env files stay
  // untrusted (#427 guard above).
  loadGbrainEnvFile(getConfigDir);

  let fileConfig: GBrainConfig | null = null;
  try {
    const raw = readFileSync(getConfigPath(), 'utf-8');
    const parsed = JSON.parse(raw) as Record<string, unknown>;
    fileConfig = migrateLegacyEmbeddingConfig(parsed) as unknown as GBrainConfig;
  } catch { /* no config file */ }

  // Try env vars (cwd-.env-origin DATABASE_URL excluded — see #427 guard above)
  const dbUrl = effectiveEnvDatabaseUrl();

  if (!fileConfig && !dbUrl) return null;
  // GBRA-377: a file holding only skills.resolver settings is no brain; every other file keeps its file-plane reads.
  if (!dbUrl && fileConfig && Object.keys(fileConfig).every((k) => k === 'skills')) return null;

  // Infer engine type. A DATABASE_URL-style env var is always a Postgres
  // connection target and must override a file-backed PGLite engine
  // selection; otherwise direct-script / operator paths can silently hit
  // the local PGLite brain while claiming to use the env URL. The PGLite
  // database_path is also cleared when dbUrl is set so toEngineConfig
  // doesn't pass a stale path through alongside the URL.
  const inferredEngine: 'postgres' | 'pglite' = dbUrl
    ? 'postgres'
    : fileConfig?.engine || (fileConfig?.database_path ? 'pglite' : 'postgres');

  // Merge: env vars override config file. READ only — never mutate process.env.
  const merged = {
    ...fileConfig,
    engine: inferredEngine,
    ...(dbUrl ? { database_url: dbUrl } : {}),
    ...(dbUrl ? { database_path: undefined } : {}),
    ...(process.env.OPENAI_API_KEY ? { openai_api_key: process.env.OPENAI_API_KEY } : {}),
    ...(process.env.ANTHROPIC_API_KEY ? { anthropic_api_key: process.env.ANTHROPIC_API_KEY } : {}),
    ...(process.env.OPENROUTER_API_KEY ? { openrouter_api_key: process.env.OPENROUTER_API_KEY } : {}),
    ...(process.env.GBRAIN_EMBEDDING_MODEL ? { embedding_model: process.env.GBRAIN_EMBEDDING_MODEL } : {}),
    ...(process.env.GBRAIN_EMBEDDING_DIMENSIONS ? { embedding_dimensions: parseInt(process.env.GBRAIN_EMBEDDING_DIMENSIONS, 10) } : {}),
    ...(process.env.GBRAIN_EXPANSION_MODEL ? { expansion_model: process.env.GBRAIN_EXPANSION_MODEL } : {}),
    ...(process.env.GBRAIN_CHAT_MODEL ? { chat_model: process.env.GBRAIN_CHAT_MODEL } : {}),
    ...(process.env.GBRAIN_CHAT_FALLBACK_CHAIN
      ? { chat_fallback_chain: process.env.GBRAIN_CHAT_FALLBACK_CHAIN.split(',').map(s => s.trim()).filter(Boolean) }
      : {}),
    ...(process.env.GBRAIN_CHAT_FALLBACK_ON_REFUSAL?.trim()
      ? { chat_fallback_on_refusal: !isEnvDisabled(process.env.GBRAIN_CHAT_FALLBACK_ON_REFUSAL) }
      : {}),
    ...(process.env.GBRAIN_EMBEDDING_MULTIMODAL
      ? { embedding_multimodal: process.env.GBRAIN_EMBEDDING_MULTIMODAL === 'true' }
      : {}),
    ...(process.env.GBRAIN_EMBEDDING_IMAGE_OCR
      ? { embedding_image_ocr: process.env.GBRAIN_EMBEDDING_IMAGE_OCR === 'true' }
      : {}),
    ...(process.env.GBRAIN_EMBEDDING_MULTIMODAL_MODEL
      ? { embedding_multimodal_model: process.env.GBRAIN_EMBEDDING_MULTIMODAL_MODEL }
      : {}),
    ...(process.env.GBRAIN_EMBEDDING_IMAGE_OCR_MODEL
      ? { embedding_image_ocr_model: process.env.GBRAIN_EMBEDDING_IMAGE_OCR_MODEL }
      : {}),
    ...(process.env.GBRAIN_RETRIEVAL_REFLEX
      ? { retrieval_reflex: !(process.env.GBRAIN_RETRIEVAL_REFLEX === 'false' || process.env.GBRAIN_RETRIEVAL_REFLEX === '0') }
      : {}),
    ...(process.env.GBRAIN_RETRIEVAL_REFLEX_WINDOW_TURNS &&
      Number.isFinite(Number(process.env.GBRAIN_RETRIEVAL_REFLEX_WINDOW_TURNS))
      ? { retrieval_reflex_window_turns: Number(process.env.GBRAIN_RETRIEVAL_REFLEX_WINDOW_TURNS) }
      : {}),
    ...(process.env.GBRAIN_RETRIEVAL_REFLEX_LEXICAL_ARMS
      ? {
          // Incident escape hatch — shared isEnvDisabled parse (also used by
          // reflex.ts:lexicalArmsEnabled/volunteerEnabled).
          retrieval_reflex_lexical_arms: !isEnvDisabled(process.env.GBRAIN_RETRIEVAL_REFLEX_LEXICAL_ARMS),
        }
      : {}),
    ...(process.env.GBRAIN_RETRIEVAL_REFLEX_VOLUNTEER
      ? {
          retrieval_reflex_volunteer: !isEnvDisabled(process.env.GBRAIN_RETRIEVAL_REFLEX_VOLUNTEER),
        }
      : {}),
    ...(process.env.GBRAIN_REMOTE_CLIENT_SECRET && fileConfig?.remote_mcp
      ? { remote_mcp: { ...fileConfig.remote_mcp, oauth_client_secret: process.env.GBRAIN_REMOTE_CLIENT_SECRET } }
      : {}),
  };

  // v0.41 content-sanity env overrides. Built up as a sparse object so
  // env presence wins over file/DB only for the specific keys set,
  // matching the precedence pattern used elsewhere in loadConfig.
  // The env vars use natural names (GBRAIN_NO_SANITY=1 is more
  // operator-friendly than GBRAIN_CONTENT_SANITY_DISABLED=true).
  const envContentSanity: GBrainConfig['content_sanity'] = {};
  if (process.env.GBRAIN_PAGE_WARN_BYTES) {
    const n = parseInt(process.env.GBRAIN_PAGE_WARN_BYTES, 10);
    if (Number.isFinite(n) && n > 0) envContentSanity.bytes_warn = n;
  }
  if (process.env.GBRAIN_PAGE_BLOCK_BYTES) {
    const n = parseInt(process.env.GBRAIN_PAGE_BLOCK_BYTES, 10);
    if (Number.isFinite(n) && n > 0) envContentSanity.bytes_block = n;
  }
  if (process.env.GBRAIN_NO_JUNK_PATTERNS === '1') {
    envContentSanity.junk_patterns_enabled = false;
  }
  if (process.env.GBRAIN_NO_SANITY === '1') {
    envContentSanity.disabled = true;
  }
  if (process.env.GBRAIN_MAX_MARKUP_RATIO) {
    const n = parseFloat(process.env.GBRAIN_MAX_MARKUP_RATIO);
    if (Number.isFinite(n) && n > 0 && n <= 1) envContentSanity.max_markup_ratio = n;
  }
  // Only attach the field when at least one env var was set, so the
  // sparse-merge semantics elsewhere in loadConfigWithEngine work
  // (env presence => "this key already has a value, don't read DB").
  if (Object.keys(envContentSanity).length > 0) {
    (merged as GBrainConfig).content_sanity = {
      ...(fileConfig?.content_sanity ?? {}),
      ...envContentSanity,
    };
  }

  return merged as GBrainConfig;
}

// #2119 read-side merge list re-exported so callers keep one config surface.
export { DB_MERGED_PROVIDER_KEY_FIELDS } from './config-db-merge.ts';

/**
 * DB-plane rows for the vector/keyword scan knobs nested under `search` (file
 * plane wins): the #5824 legacy guard, the #6132 iterative scan mode and the
 * #5989 CJK keyword deadline.
 */
async function mergeSearchScanKnobs(
  mergedSearch: NonNullable<GBrainConfig['search']>,
  dbStr: (key: string) => Promise<string | undefined>,
  dbBoolStrict: (key: string) => Promise<boolean | undefined>,
): Promise<void> {
  const dbVectorLegacyGuard = await dbBoolStrict('search.vector_legacy_guard');
  if (mergedSearch.vector_legacy_guard === undefined && dbVectorLegacyGuard !== undefined) mergedSearch.vector_legacy_guard = dbVectorLegacyGuard;
  const dbHnswIterativeScan = await dbStr('search.hnsw_iterative_scan');
  if (mergedSearch.hnsw_iterative_scan === undefined && dbHnswIterativeScan !== undefined) mergedSearch.hnsw_iterative_scan = dbHnswIterativeScan;
  const dbCjkDeadline = Number(await dbStr('search.cjk_keyword_deadline_ms'));
  if (mergedSearch.cjk_keyword_deadline_ms === undefined && Number.isFinite(dbCjkDeadline) && dbCjkDeadline > 0) mergedSearch.cjk_keyword_deadline_ms = dbCjkDeadline;
  const dbKeywordTimeout = Number(await dbStr('search.keyword_statement_timeout_ms'));
  if (mergedSearch.keyword_statement_timeout_ms === undefined && Number.isFinite(dbKeywordTimeout) && dbKeywordTimeout > 0) mergedSearch.keyword_statement_timeout_ms = dbKeywordTimeout;
}
/**
 * v0.27.1 — async config loader that overlays DB-plane config on top of the
 * file/env config. Used by `gbrain` CLI's connectEngine() AFTER engine.connect()
 * so flags written via `gbrain config set` actually take effect. Unlike the
 * sync loadConfig(), this needs an engine handle to read the config table.
 *
 * Precedence: env > file > DB > defaults. Env stays the operator escape hatch;
 * file is the durable per-machine config; DB is the user-mutable runtime knob.
 *
 * Participating DB-plane keys: multimodal/OCR flags, provider_base_urls.*,
 * the embedding-column registry, content_sanity.*, dream.*, eval.*, and the
 * #2119-class read-side set (provider credentials, chat/expansion pins,
 * chat_fallback_chain, flat cycle.* — see src/core/config-db-merge.ts, which
 * also documents why embedding_model/dims must NEVER join any list, #4287).
 */
export async function loadConfigWithEngine(
  // DbPlaneEngineReader: { getConfig; listConfigKeys?; getAllConfig?;
  // executeRaw? } — the optional getAllConfig serves every read below from
  // one snapshot; the optional executeRaw lets the #2119 merge batch its
  // reads in one query when no snapshot is available.
  engine: DbPlaneEngineReader,
  base?: GBrainConfig | null,
): Promise<GBrainConfig | null> {
  // Codex /ship finding #3: when there's no file config AND no env DB URL,
  // loadConfig() returns null and the DB merge would be skipped — env-only
  // installs (engine wired via direct SDK pass) wouldn't see DB-plane
  // overrides like `embedding_columns` / `search_embedding_column` set via
  // `gbrain config set`. Since we have a live engine here, synthesize a
  // minimal base config so the DB-plane merge still runs. The synthesized
  // config has no auth or model fields; DB-plane keys overlay correctly
  // and downstream callers either find them or fall through to defaults.
  // Also applies when callers pass an explicit null for `base`.
  const fileConfig: GBrainConfig =
    (base !== undefined ? base : loadConfig()) ??
    ({ engine: 'postgres' } as GBrainConfig);

  // This function reads two dozen config keys. One key per round trip is free
  // on PGLite and is most of the wall clock on a hosted Postgres, so read the
  // whole table once and answer every key from that. See config-snapshot.ts.
  //
  // Quiet failure below is deliberate and unchanged: when the snapshot is
  // unavailable (a pre-v36 brain mid-migration, or an engine from outside this
  // repo) every read falls back to a per-key getConfig(), same as before.
  const snapshot = await loadConfigSnapshot(engine);

  function dbRaw(key: string): Promise<string | null | undefined> {
    if (snapshot) return Promise.resolve(snapshot[key]);
    return Promise.resolve(engine.getConfig(key));
  }
  async function dbBool(key: string): Promise<boolean | undefined> {
    try {
      const v = await dbRaw(key);
      if (v === undefined || v === null || v === '') return undefined;
      return v === 'true';
    } catch {
      return undefined;
    }
  }
  async function dbStr(key: string): Promise<string | undefined> {
    try {
      const v = await dbRaw(key);
      if (v === undefined || v === null || v === '') return undefined;
      return v;
    } catch {
      return undefined;
    }
  }
  async function dbPrefixMap(prefix: string): Promise<Record<string, string> | undefined> {
    let keys: string[];
    if (snapshot) {
      keys = Object.keys(snapshot);
    } else if (typeof engine.listConfigKeys === 'function') {
      try {
        keys = await engine.listConfigKeys(prefix);
      } catch {
        return undefined;
      }
    } else {
      return undefined;
    }

    const out: Record<string, string> = {};
    for (const key of keys.sort()) {
      if (!key.startsWith(prefix)) continue;
      const leaf = key.slice(prefix.length);
      if (!leaf) continue;
      const value = await dbStr(key);
      if (value !== undefined) out[leaf] = value;
    }
    return Object.keys(out).length > 0 ? out : undefined;
  }

  const dbMultimodal = await dbBool('embedding_multimodal');
  const dbMultimodalModel = await dbStr('embedding_multimodal_model');
  const dbOcr = await dbBool('embedding_image_ocr');
  const dbOcrModel = await dbStr('embedding_image_ocr_model');
  const dbProviderBaseUrls = await dbPrefixMap('provider_base_urls.');
  // v0.36 (D7) — embedding-column registry merge. Stored as JSON string in
  // the config table. Parse + shape-check here; full registry validation
  // (regex on keys, type/dim/provider field shapes) runs in the resolver at
  // first use so a malformed DB row doesn't kill engine connect.
  const dbEmbeddingColumns = await dbStr('embedding_columns');
  const dbSearchEmbeddingColumn = await dbStr('search_embedding_column');

  // DB applies only when env did NOT win. Env presence is detected by the
  // sync loadConfig() already setting the field. For each flag, prefer the
  // existing fileConfig value when defined; otherwise fall through to DB.
  const merged: GBrainConfig = { ...fileConfig };
  if (merged.embedding_multimodal === undefined && dbMultimodal !== undefined) {
    merged.embedding_multimodal = dbMultimodal;
  }
  if (merged.embedding_multimodal_model === undefined && dbMultimodalModel !== undefined) {
    merged.embedding_multimodal_model = dbMultimodalModel;
  }
  if (merged.embedding_image_ocr === undefined && dbOcr !== undefined) {
    merged.embedding_image_ocr = dbOcr;
  }
  if (merged.embedding_image_ocr_model === undefined && dbOcrModel !== undefined) {
    merged.embedding_image_ocr_model = dbOcrModel;
  }
  if (dbProviderBaseUrls !== undefined) {
    const next = { ...(merged.provider_base_urls ?? {}) };
    for (const [providerId, baseUrl] of Object.entries(dbProviderBaseUrls)) {
      if (next[providerId] === undefined) next[providerId] = baseUrl;
    }
    if (Object.keys(next).length > 0) {
      merged.provider_base_urls = next;
    }
  }
  if (merged.embedding_columns === undefined && dbEmbeddingColumns !== undefined) {
    try {
      const parsed = JSON.parse(dbEmbeddingColumns);
      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
        merged.embedding_columns = parsed as Record<string, EmbeddingColumnConfig>;
      } else {
        console.warn('[gbrain] config: embedding_columns DB value is not a JSON object; ignoring');
      }
    } catch (err) {
      console.warn(`[gbrain] config: embedding_columns DB value is not valid JSON; ignoring (${(err as Error).message})`);
    }
  }
  if (merged.search_embedding_column === undefined && dbSearchEmbeddingColumn !== undefined) {
    merged.search_embedding_column = dbSearchEmbeddingColumn;
  }

  // v0.41 content-sanity DB-plane merge (D1: lint lifts to read these
  // when reachable). Per-key sparse-merge: env/file wins per individual
  // key; DB fills the gaps. The container object is constructed only if
  // at least one source provides a value, mirroring the env-merge logic
  // in loadConfig().
  async function dbInt(key: string): Promise<number | undefined> {
    const v = await dbStr(key);
    if (v === undefined) return undefined;
    const n = parseInt(v, 10);
    return Number.isFinite(n) && n > 0 ? n : undefined;
  }
  async function dbNum(key: string): Promise<number | undefined> {
    const v = await dbStr(key);
    if (v === undefined) return undefined;
    const n = Number(v);
    return Number.isNaN(n) ? undefined : n;
  }
  const dbWarnBytes = await dbInt('content_sanity.bytes_warn');
  const dbBlockBytes = await dbInt('content_sanity.bytes_block');
  const dbJunkEnabled = await dbBool('content_sanity.junk_patterns_enabled');
  const dbSanityDisabled = await dbBool('content_sanity.disabled');
  const dbJunkDisposition = await dbStr('content_sanity.junk_disposition');
  const dbMaxMarkupRatioStr = await dbStr('content_sanity.max_markup_ratio');
  const dbProseCheckEnabled = await dbBool('content_sanity.prose_check_enabled');
  // #4702: per-pattern opt-out. Accepts a JSON array ('["access_denied"]')
  // or a comma-separated list ('access_denied,error_title'); malformed JSON
  // falls back to the comma parse so a hand-typed value still lands.
  const dbDisabledPatternsStr = await dbStr('content_sanity.disabled_patterns');
  let dbDisabledPatterns: string[] | undefined;
  if (dbDisabledPatternsStr !== undefined) {
    const raw = dbDisabledPatternsStr.trim();
    if (raw.startsWith('[')) {
      try {
        const parsed = JSON.parse(raw);
        if (Array.isArray(parsed)) {
          dbDisabledPatterns = parsed.filter((x): x is string => typeof x === 'string');
        }
      } catch { /* fall through to comma parse */ }
    }
    if (dbDisabledPatterns === undefined) {
      dbDisabledPatterns = raw.split(',').map(s => s.trim()).filter(Boolean);
    }
  }

  const existingCS = merged.content_sanity ?? {};
  const mergedCS: NonNullable<GBrainConfig['content_sanity']> = { ...existingCS };
  if (mergedCS.bytes_warn === undefined && dbWarnBytes !== undefined) {
    mergedCS.bytes_warn = dbWarnBytes;
  }
  if (mergedCS.bytes_block === undefined && dbBlockBytes !== undefined) {
    mergedCS.bytes_block = dbBlockBytes;
  }
  if (mergedCS.junk_patterns_enabled === undefined && dbJunkEnabled !== undefined) {
    mergedCS.junk_patterns_enabled = dbJunkEnabled;
  }
  if (mergedCS.disabled === undefined && dbSanityDisabled !== undefined) {
    mergedCS.disabled = dbSanityDisabled;
  }
  if (
    mergedCS.junk_disposition === undefined &&
    (dbJunkDisposition === 'quarantine' || dbJunkDisposition === 'reject')
  ) {
    mergedCS.junk_disposition = dbJunkDisposition;
  }
  if (mergedCS.max_markup_ratio === undefined && dbMaxMarkupRatioStr !== undefined) {
    const n = parseFloat(dbMaxMarkupRatioStr);
    if (Number.isFinite(n) && n > 0 && n <= 1) mergedCS.max_markup_ratio = n;
  }
  if (mergedCS.prose_check_enabled === undefined && dbProseCheckEnabled !== undefined) {
    mergedCS.prose_check_enabled = dbProseCheckEnabled;
  }
  if (mergedCS.disabled_patterns === undefined && dbDisabledPatterns !== undefined) {
    mergedCS.disabled_patterns = dbDisabledPatterns;
  }
  if (Object.keys(mergedCS).length > 0) {
    merged.content_sanity = mergedCS;
  }

  // v0.41.2.1 — dream.* DB-plane merge. Precedence is file > DB > defaults
  // per key (NO env layer; see GBrainConfig.dream JSDoc). Without this,
  // `extract-atoms.ts` and any other consumer that reads the merged config
  // (vs calling `engine.getConfig()` directly) silently misses dream.*
  // config set via `gbrain config set`.
  const dbSessionCorpusDir = await dbStr('dream.synthesize.session_corpus_dir');
  const dbMeetingTranscriptsDir = await dbStr('dream.synthesize.meeting_transcripts_dir');
  const dbVerdictModel = await dbStr('dream.synthesize.verdict_model');
  const dbMaxPromptTokens = await dbInt('dream.synthesize.max_prompt_tokens');
  const dbMaxChunksPerTranscript = await dbInt('dream.synthesize.max_chunks_per_transcript');
  const dbSubagentTimeoutMs = await dbNum('dream.synthesize.subagent_timeout_ms');
  const dbSubagentWaitTimeoutMs = await dbNum('dream.synthesize.subagent_wait_timeout_ms');
  const dbLookbackDays = await dbInt('dream.patterns.lookback_days');
  const dbMinEvidence = await dbInt('dream.patterns.min_evidence');

  const existingDream = merged.dream ?? {};
  const existingSynth = existingDream.synthesize ?? {};
  const existingPatterns = existingDream.patterns ?? {};
  const mergedSynth: NonNullable<NonNullable<GBrainConfig['dream']>['synthesize']> = { ...existingSynth };
  const mergedPatterns: NonNullable<NonNullable<GBrainConfig['dream']>['patterns']> = { ...existingPatterns };

  if (mergedSynth.session_corpus_dir === undefined && dbSessionCorpusDir !== undefined) {
    mergedSynth.session_corpus_dir = dbSessionCorpusDir;
  }
  if (mergedSynth.meeting_transcripts_dir === undefined && dbMeetingTranscriptsDir !== undefined) {
    mergedSynth.meeting_transcripts_dir = dbMeetingTranscriptsDir;
  }
  if (mergedSynth.verdict_model === undefined && dbVerdictModel !== undefined) {
    mergedSynth.verdict_model = dbVerdictModel;
  }
  if (mergedSynth.max_prompt_tokens === undefined && dbMaxPromptTokens !== undefined) {
    mergedSynth.max_prompt_tokens = dbMaxPromptTokens;
  }
  if (mergedSynth.max_chunks_per_transcript === undefined && dbMaxChunksPerTranscript !== undefined) {
    mergedSynth.max_chunks_per_transcript = dbMaxChunksPerTranscript;
  }
  if (mergedSynth.subagent_timeout_ms === undefined && dbSubagentTimeoutMs !== undefined) {
    mergedSynth.subagent_timeout_ms = dbSubagentTimeoutMs;
  }
  if (mergedSynth.subagent_wait_timeout_ms === undefined && dbSubagentWaitTimeoutMs !== undefined) {
    mergedSynth.subagent_wait_timeout_ms = dbSubagentWaitTimeoutMs;
  }
  if (mergedPatterns.lookback_days === undefined && dbLookbackDays !== undefined) {
    mergedPatterns.lookback_days = dbLookbackDays;
  }
  if (mergedPatterns.min_evidence === undefined && dbMinEvidence !== undefined) {
    mergedPatterns.min_evidence = dbMinEvidence;
  }

  // Only construct the dream container when at least one leaf was populated
  // — mirrors the content_sanity pattern so empty brains keep `cfg.dream`
  // undefined.
  if (Object.keys(mergedSynth).length > 0 || Object.keys(mergedPatterns).length > 0) {
    const mergedDream: NonNullable<GBrainConfig['dream']> = {};
    if (Object.keys(mergedSynth).length > 0) mergedDream.synthesize = mergedSynth;
    if (Object.keys(mergedPatterns).length > 0) mergedDream.patterns = mergedPatterns;
    merged.dream = mergedDream;
  }

  // #1475 — eval.* DB-plane merge. Both keys are in KNOWN_CONFIG_KEYS, so
  // `gbrain config set eval.capture true` is accepted and stored, and
  // `gbrain config get` reads it back (it queries engine.getConfig directly
  // and prints `source: db plane`). But the runtime gates read the MERGED
  // config — isEvalCaptureEnabled/isEvalScrubEnabled take `ctx.config` — so
  // without a merge branch here the write was accepted, echoed back, and had
  // no effect: capture stayed off unless GBRAIN_CONTRIBUTOR_MODE=1 was also
  // exported, which is what the config was supposed to make unnecessary.
  //
  // Both directions matter. `false` is not "unset": eval.capture=false is the
  // documented opt-out for a brain that has CONTRIBUTOR_MODE exported, and
  // eval.scrub_pii=false is an explicit privacy decision. dbBool already
  // distinguishes them ('' / null / undefined → undefined).
  // Strict, not `dbBool`. `dbBool` maps every non-empty value other than the
  // exact string 'true' to FALSE, and `config set` stores whatever it is given
  // — so `gbrain config set eval.scrub_pii TRUE` (or `1`, or a typo like
  // `tru`) would arrive here as `false` and silently DISABLE PII scrubbing.
  // Measured: 'true'→true, 'false'→false, and 'tru' / 'TRUE' / '1' / 'yes' all
  // →false under dbBool. Before this merge existed those values were inert, so
  // adopting dbBool here would newly activate that footgun on a privacy knob.
  // An unrecognised value is treated as unset, which falls back to the
  // documented default (scrub on, capture per CONTRIBUTOR_MODE) — fail-safe.
  //
  // Deliberately scoped to the two keys this change introduces. The same
  // looseness applies to the other dbBool keys, but tightening those is a
  // behavior change for existing brains and belongs in its own PR.
  async function dbBoolStrict(key: string): Promise<boolean | undefined> {
    try {
      const v = await dbRaw(key);
      if (v === 'true') return true;
      if (v === 'false') return false;
      return undefined;
    } catch {
      return undefined;
    }
  }

  const dbEvalCapture = await dbBoolStrict('eval.capture');
  const dbEvalScrubPii = await dbBoolStrict('eval.scrub_pii');

  const mergedEval: NonNullable<GBrainConfig['eval']> = { ...(merged.eval ?? {}) };
  if (mergedEval.capture === undefined && dbEvalCapture !== undefined) {
    mergedEval.capture = dbEvalCapture;
  }
  if (mergedEval.scrub_pii === undefined && dbEvalScrubPii !== undefined) {
    mergedEval.scrub_pii = dbEvalScrubPii;
  }
  // Same container discipline as dream/content_sanity: a brain that sets
  // neither key keeps `cfg.eval` undefined, so `config show` does not sprout
  // an empty object and downstream `config?.eval?.x === undefined` reads are
  // unchanged.
  if (Object.keys(mergedEval).length > 0) {
    merged.eval = mergedEval;
  }

  // #4605 — search.adaptive_return* DB-plane merge, same class as #1475: the
  // keys are registered and stored, but return-policy.ts reads the NESTED
  // `cfg.search.*` of THIS merged object (via hybrid.ts), so without this the
  // row was accepted, echoed by `config get`, and never read. Strict bool;
  // caps must be finite numbers (return-policy clamps); file > DB; no empty container.
  const mergedSearch: NonNullable<GBrainConfig['search']> = { ...(merged.search ?? {}) };
  const dbAdaptiveReturn = await dbBoolStrict('search.adaptive_return');
  if (mergedSearch.adaptive_return === undefined && dbAdaptiveReturn !== undefined) {
    mergedSearch.adaptive_return = dbAdaptiveReturn;
  }
  for (const cap of ['adaptive_return_entity_max', 'adaptive_return_other_max', 'adaptive_return_min_keep'] as const) {
    if (mergedSearch[cap] !== undefined) continue;
    const n = Number(await dbStr(`search.${cap}`));
    if (Number.isFinite(n)) mergedSearch[cap] = n;
  }
  await mergeSearchScanKnobs(mergedSearch, dbStr, dbBoolStrict);
  if (Object.keys(mergedSearch).length > 0) {
    merged.search = mergedSearch;
  }

  // #2119-class read-side merge (also #2137/#4297): provider credentials,
  // chat/expansion pins, chat_fallback_chain, flat cycle.* (env > file > DB).
  // Served from the SAME snapshot as the reads above when available (zero
  // extra round trips, and the merge can't disagree with the dbStr/dbBool
  // reads); otherwise one batched, ~30s-memoized read per engine handle
  // (D2 remediation).
  await applyDbPlaneReadSideMerge(
    merged,
    snapshot
      ? {
          getConfig: async (key) => snapshot[key] ?? null,
          listConfigKeys: async (prefix) =>
            Object.keys(snapshot).filter((k) => k.startsWith(prefix)),
        }
      : engine,
  );

  return mergeServeVectorPrewarm(mergeServeCliSocket(merged, snapshot), snapshot);
}

/**
 * v0.37 (D6): canonical list of known config keys for `gbrain config set`
 * validation. Includes both the static GBrainConfig fields (file plane)
 * and well-known DB-plane keys.
 *
 * This is NOT a runtime allow-list applied to reads — gateway/reader code
 * still tolerates extra keys. It's the suggestion source for "did you mean"
 * Levenshtein on `set`. Missing keys can be passed through with `--force`.
 *
 * When adding a new persistent config key:
 *   1. Add it to the GBrainConfig interface (if file-plane) OR document it
 *      below (if DB-plane).
 *   2. Add the canonical name to this list so `gbrain config set` accepts it
 *      without `--force`.
 */
export const KNOWN_CONFIG_KEYS: readonly string[] = [
  // File-plane (GBrainConfig static fields)
  'engine',
  'database_url',
  'database_path',
  'openai_api_key',
  'anthropic_api_key',
  'openrouter_api_key',
  'voyage_api_key',
  'dashscope_api_key',
  'deepseek_api_key',
  'litellm_api_key',
  'together_api_key',
  'google_api_key',
  'azure_openai_api_key',
  'azure_openai_endpoint',
  'azure_openai_deployment',
  'azure_openai_use_entra',
  'embedding_model',
  'embedding_dimensions',
  'embedding_disabled',
  'expansion_model',
  'chat_model',
  'chat_fallback_chain',
  'chat_fallback_on_refusal',
  'provider_base_urls',
  // Integration gates (file-plane, hook-lane)
  'integrations.memorable.enabled',
  // MEMORY_VERBS v1 (Cathedral 1)
  'mcp_surface',
  'protocol_installed_at',
  'provider_chat_options',
  'storage',
  'schema_pack',
  'eval',
  'eval.capture',
  'eval.scrub_pii',
  'embedding_multimodal',
  'embedding_multimodal_model',
  // #5691: per-brain query instruction (DB plane; read by search/query-prefix.ts).
  'embedding_query_prefix',
  'embedding_image_ocr',
  'embedding_image_ocr_model',
  'embedding_columns',
  'search_embedding_column',
  'remote_mcp',
  'sync',
  'sync.repo_path',
  'import.require_configured_root',
  'sync.last_commit',
  // Opt-out for the put_page/capture disk write-through (write-through.ts):
  // 'false' makes every page write DB-only. For brains whose host repo is a
  // shared working tree where stray root-level .md artifacts are unwanted.
  'sync.write_through',
  // Gateway-native subagent loop toggle (routes subagent jobs through the
  // provider-agnostic gateway.toolLoop for non-Anthropic providers). The
  // subagent handler's error message tells users to `config set` this, so it
  // must be a known key or `config set` rejects it without --force.
  'agent.use_gateway_loop',
  // #2778: per-turn output-token cap for the subagent loop (default 8192).
  'agent.max_output_tokens',
  // #4921: subagent per-turn chat timeout (minions/handler-timeouts.ts, default 30 min).
  'ai.chat.per_turn_timeout_ms',
  'context.proactive_brief', // DB-plane, default off: wave 5 D5 brief (src/core/context/proactive-brief.ts)
  // File-plane bootstrap hook-lane keys (routed to ~/.gbrain/config.json by
  // `config set` — engine-free hook/push children read loadConfigFileOnly).
  'push.allow_unverified_remote',
  'hooks.stop_push_debounce_min',
  // File-plane backup-check keys (routed to ~/.gbrain/config.json by `config
  // set` — the engine-free render sites read loadConfigFileOnly). Default ON /
  // 30 days; interval clamps to >=1 day at read time (backup/status-file.ts).
  'backup.check_enabled',
  'backup.check_interval_days',
  'backup.remote_timeout_ms', // #6907: DB plane, read by the backup coverage compute (backup/repository.ts); 500-30000, default 2000
  // DB-plane search-mode knobs: one row per key mode.ts reads (its
  // KNOB_CONFIG_KEY, hand-mirrored so this module stays import-light; pinned
  // equal by test/config-search-registry.test.ts). camelCase where the code
  // reads camelCase (#4605 — snake_case rows here had no reader).
  'search.mode',
  'search.cache.enabled',
  'search.cache.similarity_threshold',
  'search.cache.ttl_seconds',
  'search.intentWeighting',
  'search.keywordOrFallback',
  'search.tokenBudget',
  'search.expansion',
  'search.searchLimit',
  'search.reranker.enabled',
  'search.reranker.model',
  'search.reranker.top_n_in',
  'search.reranker.top_n_out',
  'search.reranker.timeout_ms',
  // W3: confidence-gated reranking (mode.ts reads; `off` | `shadow`, and δ in [0, 1]).
  'search.reranker.gate',
  'search.reranker.gate_min_gap',
  'search.floor_ratio',
  'search.title_boost',
  'search.evidence_cosine_floor',
  'search.cross_modal.both_mode_text_weight',
  'search.cross_modal.both_mode_image_weight',
  'search.image_query.text_refinement_weight',
  'search.image_query.image_refinement_weight',
  'search.unified_multimodal',
  'search.unified_multimodal_only',
  'search.cross_modal.llm_intent',
  'search.graph_signals',
  'search.contextual_retrieval',
  'search.contextual_retrieval_disabled',
  'search.relational_retrieval',
  'search.relational_retrieval_depth',
  // DB-plane search.* singletons read directly via engine.getConfig
  // (commands/upgrade.ts, ops/image.ts, ops/search.ts, private-visibility.ts,
  // last-retrieved.ts).
  'search.mode_upgrade_notice_shown',
  'search.mode_source',
  'search.image_query.max_bytes',
  'search.image_query.daily_budget_usd_per_client',
  'search.image_query.remote_max_bytes',
  'search.mcp_keyword_only',
  'search.remote_page_cap', // GBRA-156: distinct-page cap of a remote search/query without limit (search/remote-page-cap.ts)
  REMOTE_PRIVATE_PAGES_KEY,
  'search.track_retrieval',
  // Retrieval feedback (feedback/settings.ts).
  'feedback.enabled', 'feedback.learn', 'feedback.influence', 'feedback.implicit', 'feedback.alpha',
  'feedback.max_ratings_per_hour', 'feedback.event_retention_days', 'feedback.rating_prompt', 'feedback.notice_shown',
  // #4415: per-brain query-intent pattern extensions (JSON bank→regex[]),
  // merged over the shipped banks in src/core/search/query-intent.ts.
  'search.intent_patterns',
  // Per-brain source-boost map (`prefix:factor,...`; `none` drops the
  // defaults), read by search/mode.ts loadSearchModeConfig and ops/search.ts.
  'search.source_boosts',
  // #5428 opt-in single-token alias hop (`true` enables), read by
  // search/mode.ts loadSearchModeConfig.
  'search.alias_token_hop',
  // 2026-08 fix wave (E5a): the adaptive-return / autocut / CRAG knobs were
  // read by the search path but never registered — `gbrain config set`
  // rejected them, making the documented config plane a no-op. Read sites:
  // return-policy.ts (adaptive_return*), mode.ts (autocut*), ops/search.ts
  // (crag_*). NOTE: `search.crag_think` (default off) runs `think` — an LLM
  // call — on weak-graded local queries when enabled; it respects
  // spend.posture, but enabling it is a per-query spend decision.
  // `search.crag_escalation` (default off) also spends when enabled: the
  // high-ceiling re-run sets expansion=true (one LLM multi-query call per
  // weak-graded query), and unlike crag_think it is reachable by remote
  // callers — attacker-shaped weak queries drive that spend (ship security
  // review). See docs/operations/spend-controls.md.
  // #5824 one-release rollback, latched per engine (search/vector-legacy-guard.ts).
  'search.vector_legacy_guard',
  'search.hnsw_iterative_scan',
  'search.cjk_keyword_deadline_ms',
  'search.keyword_statement_timeout_ms',
  'search.keyword_timeout_negative_cache_seconds', // #6495: the longest skip in seconds, default 600, 0 = off; #7082: a serve's background re-run ends it sooner (postgres-engine/keyword-timeout-cache.ts)
  'search.adaptive_return',
  'search.adaptive_return_entity_max',
  'search.adaptive_return_other_max',
  'search.adaptive_return_min_keep',
  'search.autocut',
  'search.autocut_jump',
  'search.autocut_min_keep',
  'search.autocut_min_top',
  // Ranker wave: shared RRF weight budget for expansion variant lists (mode.ts reads; `legacy` | (0, 4]).
  'search.expansion_variant_budget',
  // Ranker wave (R1): relational-arm rows re-pinned above reranked text rows (mode.ts reads; `off` | 0..10).
  'search.relational_rerank_pin',
  // Multi-hop planner (mode.ts reads; boolean) and typed one-hop orientation (boolean; unset follows the planner).
  'search.relational_planner',
  'search.relational_orient_onehop',
  // Multi-hop chain slots: chain rows leading page 1 when a chain fired (mode.ts reads; 0..10).
  'search.relational_chain_slots',
  'search.collapse', // result-time collapse of twins, redirect stubs and document copies (mode.ts reads; boolean)
  'search.rank_priors', // rank priors after the reranker (mode.ts reads; boolean)
  'search.keyword_phrase', // keyword phrase factor, #7175 (mode.ts reads; boolean)
  'search.qualified_aliases', // qualified alias hop (mode.ts reads; boolean)
  'search.title_qualified', // qualified title boost (mode.ts reads; boolean)
  'search.diverse_pool_depth', // session-diverse pool before the reranker (mode.ts reads; `off` | 0..100; 0 = off)
  // Ranker wave (Phase E2): keyword-arm confidence floor — weak keyword arm fuses at half weight (mode.ts reads; `off` | (0, 1]).
  'search.keyword_arm_confidence_floor',
  // Ranker wave (Phase E3): metadata boost gate — `lexical` skips post-fusion metadata boosts when the vector arm was the only voter (mode.ts reads; `always` | `lexical`).
  'search.metadata_boost_gate',
  'search.crag_escalation',
  'search.crag_think',
  // Evidence delivery (search/evidence-delivery.ts): default unit (auto),
  // window radius, default/auto/remote-max token budgets; think reads its own unit.
  'search.return_unit',
  'search.return_window',
  'search.return_budget_default',
  'search.return_budget_conversation',
  'search.return_budget_max_remote',
  'search.auto_packing',
  'search.long_page_unit', 'search.long_page_min_chars', // F2: delivery unit for long (rendered body >= min_chars, default 20000) non-conversation hits under an implied auto: off (default) | window | section | page (search/evidence-delivery.ts)
  'search.evidence_date_header', // C1: one-line date header per delivered block (default off; search/evidence-date.ts)
  'search.evidence_titles', 'search.query_budget_unit', // GBRA-205, default off: titles on page date headers and think <page> tags (search/evidence-date.ts); query token_budget as the delivery hard cap, chunk | auto (search/evidence-packing.ts)
  'search.evidence_tail_trim', // GBRA-156: protected top-3 tail trim of auto conversation blocks (default off; search/evidence-tail-trim.ts)
  'search.entity_anchoring', // entity-anchored retrieval for entity-scoped current-state query/search (default off; search/entity-anchor.ts)
  'search.query_facts_arm', // query adds matching active facts as rows in spare capacity (default on; search/facts-arm.ts)
  'search.saved_facts_supersede', // search saved_facts: a newer fact with a correction cue goes ahead of the fact it corrects, labelled corrected_by (default on; search/saved-facts-match.ts)
  'search.temporal_fact_reserve', // temporal-cue queries reserve up to 15% of the token budget for question-ranked dated facts (default off; search/facts-arm.ts)
  'search.query_facts_block', 'search.fact_source_pages', // GBRA-205: a dated facts block (up to 22% of a query budget) ahead of the pages, default on; matched facts' source conversations join the hits, default off (search/facts-arm.ts)
  'search.page_rank_cut', // W5: whole_pages (default) | off — page unit + caller token_budget stops adding pages once their whole pages fill factor x the budget (search/page-rank-cut.ts)
  'search.page_rank_cut_factor', // W5: whole_pages target = factor x the budget (default 1.5)
  'think.return_unit',
  'think.pages_budget_chars', // #5461: total chars for the synthesize pages block (4000-200000, default 12000; soft: the 600-char floor wins); think/pages-budget.ts
  'think.excerpt_ceiling_chars', // #5461: per-page excerpt cap for the synthesize pages block (600-200000, default 2400); think/pages-budget.ts
  // Models tier system (v0.31.12)
  'models.default',
  'models.tier.utility',
  'models.tier.reasoning',
  'models.tier.deep',
  'models.tier.subagent',
  'models.aliases',
  'models.dream.synthesize',
  'models.dream.extract_atoms',
  'cycle.extract_atoms.budget_usd',
  // #4907: synthesize_concepts phase budget (finite USD > 0, default 1.5); cycle/phase-config-values.ts.
  'cycle.synthesize_concepts.budget_usd',
  'cycle.extract_atoms.max_source_chars',
  'cycle.extract_atoms.page_discovery_budget',
  // #4540: per-item extractor caps (defaults 50000 chars / 4096 tokens) plus
  // an optional between-item pacing sleep (ms, default 0). Read via
  // engine.getConfig in src/core/cycle/extract-atoms.ts.
  'cycle.extract_atoms.max_input_chars',
  'cycle.extract_atoms.max_output_tokens',
  'cycle.extract_atoms.pacing_ms',
  'models.dream.patterns',
  'models.dream.synthesize_verdict',
  // #4152: preferred triage-model key (explicit pre-read in loadSynthConfig;
  // wins over models.dream.synthesize_verdict + dream.synthesize.verdict_model).
  'models.dream.triage',
  'models.drift',
  'models.auto_think',
  'models.standing_questions',
  'models.think', 'models.fence_repair', // models.fence_repair: #6188 Tier 3 fence repair model (fence-repair/llm.ts), tier deep
  'models.subagent',
  'models.expansion',
  'models.contextual_synopsis',
  'models.chat',
  'models.brainstorm.judge',
  'models.eval.longmemeval', 'models.eval.cross_modal.slot_a', 'models.eval.cross_modal.slot_b', 'models.eval.cross_modal.slot_c', // #5872 D12 probe judge slots
  'facts.extraction_model',
  'recall.question_admission', // recall `question` admission rule: reserve (default) | facts_arm (facts/question-recall.ts)
  'recall.confidence_weighting', 'recall.group_by_entity', // #2941/#2953 switches, on | off, default off (facts/recall-config.ts)
  // Brain-wide kill switch for fact extraction, read by
  // src/core/facts/extract.ts:isFactsExtractionEnabled and honored by
  // sweep.ts, operations.ts and transcripts/ingest-facts.ts. That function's
  // own docstring tells operators to flip it with
  // `gbrain config set facts.extraction_enabled false` — which was rejected
  // as an unknown key until this registration.
  'facts.extraction_enabled',
  // Open-loop engine kill switch: LLM commitment/decision extraction over
  // google-source email pages (default ON for google sources; deterministic
  // thread detection is unaffected). `gbrain config set loops.extraction_enabled false`.
  'loops.extraction_enabled',
  // #5445: brain-wide Gmail labels (names or ids, comma/JSON list) whose threads
  // never enter paid loop extraction; a source's g_loops_exclude_labels wins.
  'loops.extraction_exclude_labels',
  // W14 P4.6b: USD per UTC day that loops_extract jobs may spend, brain-wide
  // (default 2.00; 0 = no paid loop extraction). Validated in google/loops-spend.ts.
  'loops.extraction_max_usd_per_day',
  // #5012: boolean, default false (off). On, Gmail Updates mail opens a reply-owed loop only for a sender the owner wrote to.
  'loops.updates_require_reciprocity',
  // #2113: output-token cap for the per-turn facts extractor (default 4000).
  'facts.extraction_max_tokens',
  // Automatic facts drain caps (src/core/facts/drain.ts FACTS_DRAIN_KEYS).
  'facts.drain_budget_usd', 'facts.drain_daily_budget_usd', 'facts.drain_max_jobs',
  'facts.absorb_retry.max_resubmits', // C-9: re-submits per dead page-write facts-absorb job (default 3; 0 disables; facts/dead-absorb-retry.ts)
  // #3852: operator-set system-prompt appendix for the facts extractor (e.g.
  // a durable-vs-ephemeral rubric for agent work-session transcripts).
  // Composes with BOTH honest-notability prompt variants.
  'facts.extraction_prompt_appendix',
  // #3852: kill-switch for the deterministic junk gate on extracted fact text
  // (plan narration / provider error strings / meta-chatter). Default on.
  'facts.extraction_junk_filter',
  // B-16: confidence stored for an extracted candidate whose confidence is
  // missing or non-numeric (a number in 0..1). Unset keeps the legacy 1.0.
  'facts.extraction_missing_confidence',
  'extraction.date_grounding', 'facts.attribution', // extraction prompt variants (facts/extract.ts getExtractorVariant)
  // [ENG-8] Brain-level default visibility for facts writes when the caller
  // didn't specify one: 'private' (default) | 'world'. Resolved by
  // src/core/facts/visibility.ts; explicit caller values always win.
  'facts.default_visibility',
  'storage.git_lfs', // G7a: a git-canonical door commit under a Git LFS rule commits the LFS pointer; default off refuses it (persistence/git-declared.ts)
  'visibility.honor_aliases', // remote page reads honor `access`/`confidentiality` aliases on pages without `visibility`; default on, false opts out (search/private-visibility.ts)
  'facts.entity_inference', 'facts.unbacked_entity_keys', // #5836 subject inference kill switch (subject-infer.ts); GBRA-574 conversation name keys (entities/resolve-on-save.ts)
  'facts.candidate_fusion', // C2: 'rrf_free' (default, cosine arm) | 'interleave' (cosine + keyword; facts/single-prepare.ts)
  'facts.supersession_thresholds', // JSON {"provider:model@dims": number | "off"} (facts/supersession-threshold.ts)
  'facts.page_write_notability_filter', // #6231: tiers page-write extraction keeps (facts/notability-filter.ts)
  // Ambient memory writeback (opt-in, default OFF): 'off' | 'salient' | 'all'.
  // DUAL-PLANE: `gbrain config set` writes the DB plane (authoritative — the
  // serve-side harvest gate re-checks it) AND mirrors into the file plane's
  // `memory` slot (read by the engine-free Stop-hook child and the stdio
  // serve's boot resolve). Resolved by src/core/facts/writeback-config.ts.
  'memory.auto_writeback',
  // TTL the instruction template tells agents to pass on TRANSIENT facts
  // (health/location/travel/mood/near-term schedule). Duration shorthand
  // only ('3d', '12h'), positive, capped at 365d; default '3d'.
  'memory.auto_writeback_transient_ttl',
  // Fire-once sentinel for the ambient-writeback consent nudge (WP8):
  // stamped 'true' after the init/post-upgrade ask has been shown once.
  'memory.auto_writeback_notice_shown',
  'memory.agent_writeback', // GBRA-219: DB-only override of what AGENTS are told (inherit|off|salient|all); never the capture lanes (facts/writeback-settings.ts)
  // Always-loaded core memory + context-pressure notice (docs/guides/core-memory.md#configuration).
  'memory.core.enabled', 'memory.core.max_chars', 'memory.core.remote_edit',
  'memory.pressure.enabled', 'memory.pressure.warn_ratio', 'memory.pressure.context_window',
  // Declared brain audience: 'personal' | 'shared'. Set by the operator, by
  // company-brainify's Phase-5 handoff (shared), or from the bootstrap
  // interview. Declaration beats the conservative client-count heuristic in
  // src/core/facts/writeback-audience.ts; the consent nudge fires only on
  // personal brains and never auto-enables anything.
  'brain.audience',
  // Conversation parser LLM fallback. Deliberately register the exact key,
  // not a conversation_parser.* prefix: fallback is the only opt-in consumer.
  'conversation_parser.llm_fallback_enabled',
  // Dream cycle config
  'dream.synthesize.session_corpus_dir', 'dream.synthesize.conversation_pages', // #4419 conversation pages feed synthesis
  'dream.synthesize.meeting_transcripts_dir',
  'dream.synthesize.last_completion_ts',
  'dream.synthesize.verdict_model',
  'dream.synthesize.max_prompt_tokens',
  'dream.synthesize.max_chunks_per_transcript',
  // #2415: top-level namespace for synthesize/patterns output (default 'wiki').
  'dream.synthesize.output_root',
  'dream.synthesize.subagent_timeout_ms',
  'dream.synthesize.subagent_wait_timeout_ms',
  // #4152 two-stage cascade: subagent turn budget (default 16) + opt-in
  // per-source daily submission cap (default 0 = disabled; 200 recommended
  // for busy deployments).
  'dream.synthesize.max_turns',
  'dream.synthesize.max_submissions_per_source_per_day',
  // #4216/#4194 dream-wave knobs: synthesis execution mode ('oneshot'
  // default | 'agentic'), pre-retrieval link-candidate manifest (default on),
  // and inline-drain concurrency (default 1; clamped [1,8]; PGLite forced 1).
  'dream.synthesize.mode',
  'dream.synthesize.link_manifest',
  'dream.synthesize.quote_verify',
  'dream.quote_verify',
  'think.quote_verify', 'dream.attribution_checks', // #5425 [UC4] mechanical attribution checks, default off (cycle/attribution-checks.ts)
  'dream.synthesize.inline_concurrency',
  // #4152 triage knobs. The triage model's preferred key is
  // `models.dream.triage` (models.* prefix, registered via the models.dream.*
  // family); these tune the gate + sampling + pass budget.
  'dream.triage.threshold',
  'dream.triage.rescue_floor',
  'dream.triage.rescue_min_segments',
  'dream.triage.rescue_content_types',
  'dream.triage.max_chars',
  'dream.triage.max_tokens',
  'dream.triage.max_ms',
  'dream.triage.concurrency',
  // #4494: propose_takes extractor output caps (defaults 2048/4096, floor
  // 256, retry clamped >= base). Thinking models spend reasoning tokens
  // inside maxTokens, so the hardcoded defaults truncated every dense page.
  'dream.propose_takes.max_tokens',
  'dream.propose_takes.retry_max_tokens',
  // #5958: per-call extractor timeout (whole ms 1000..300000; unset scales with the output cap); cycle/phase-config-values.ts.
  'dream.propose_takes.call_timeout_ms',
  'dream.patterns.lookback_days',
  'dream.patterns.min_evidence',
  // #2782-family: patterns-phase subagent timeouts (mirror of the
  // dream.synthesize.* pair from #1594).
  'dream.patterns.subagent_timeout_ms',
  'dream.patterns.subagent_wait_timeout_ms',
  'dream.patterns.min_interval_hours', 'dream.patterns.child_read_budget_kb', // #6297: hours (default 6) / KB (default 200), 0 = off; cycle/phase-config-values.ts
  'dream.claim_conflicts.mode', 'dream.claim_conflicts.max_pairs', // GBRA-216: propose | off (default off) / pairs per source per run (default 500); facts/claim-conflicts.ts
  // Paid-loop breaker: dead submissions of one dream key within 24h before
  // it is refused (default 3; 0 disables). `gbrain dream reset-key` clears one.
  'dream.breaker.max_dead_submissions',
  'dream.write_deferral.enabled', 'embed.restamp.enabled', // GBRA-224 W3 self-heal switches, default on (heal-audit.ts healEnabled)
  // Emotional weight (v0.29)
  'emotional_weight.high_tags',
  'emotional_weight.user_holder',
  // Cycle phase config
  // #4348: IANA timezone that owns the dream-cycle calendar day (summary
  // bucketing). Unset → host timezone → UTC. Validated at set time.
  'cycle.timezone',
  'cycle.consolidate.enabled', // #6667: default on; read in cycle/phases/consolidate.ts
  'cycle.consolidate.cluster_threshold', // #5363: (0, 1], default 0.85; read + validated in cycle/phases/consolidate.ts
  // A11: IANA timezone for offset-less frontmatter datetimes in effective_date.
  // Unset → UTC (date-only values are always UTC calendar dates). Validated at set time.
  'brain.timezone',
  // A12 (opt-in, default off): undated new pages in git-backed sources take the
  // file's git first-commit date as their effective-date fallback on full import.
  'sync.git_first_commit_dates',
  'cycle.grade_takes.write_gstack_learnings',
  // #4102: off switch for the propose_takes LLM phase (default ON; the
  // phase ships in the default list). Read by src/core/cycle/propose-takes.ts.
  'cycle.propose_takes.enabled',
  'cycle.propose_takes.types', // #5213: JSON array of page types propose_takes scans (unset = every type); read in cycle/propose-takes.ts
  'cycle.lint.enabled', // #6369: default on; an explicit falsy value skips the cycle's lint phase (cycle/lint-fix-setting.ts; `dream --phase lint --once` bypasses)
  'autopilot.git_pull', // #6451: default on; an explicit falsy value stops automatic sync from pulling remote sources (persistence/automatic-sync-policy.ts)
  // Content sanity (v0.41)
  'content_sanity.bytes_warn',
  'content_sanity.bytes_block',
  'content_sanity.junk_patterns_enabled',
  'content_sanity.disabled',
  // Content-quality gate (v0.42, issue #1699)
  'content_sanity.junk_disposition',
  'content_sanity.max_markup_ratio',
  'content_sanity.prose_check_enabled',
  // #4702: per-pattern opt-out (JSON array or comma-separated names) —
  // finer than junk_patterns_enabled (all patterns) / disabled (kill-switch).
  'content_sanity.disabled_patterns',
  // #5575 write gate (local-only): quarantine|flag|reject|off and flag|off; read by import-screen.ts.
  'write_gate.external_mode',
  'write_gate.agent_mode',
  // #5575 read side (local-only): label|filter and suppress|allow; read by eligibility/policy.ts.
  'trust.read_policy',
  'trust.agent_activation',
  // MCP skill-catalog publishing (PR1)
  'mcp.publish_skills',
  'mcp.publish_skills_prompted',
  'mcp.skills_dir',
  // MCP advisor publishing (#2180): separate gate from publish_skills because
  // the advisor exposes operational diagnostics (version/jobs/key presence),
  // not prose skills. Default OFF; read-only over MCP.
  'mcp.publish_advisor',
  'mcp.publish_memory_settings', // GBRA-219: operator grant for set_memory_writeback over MCP (admin scope too); default off
  // WP3 — unknown tool-call argument posture ('warn' default | 'reject').
  // Read dual-plane by src/mcp/validate-params.ts (DB > file > 'warn').
  'mcp.strict_params',
  'mcp.result_rows', // C1 row shape, read dual-plane by src/mcp/result-rows.ts
  'mcp.allow_session_widen', // stdio request_tools session widening (default on), read dual-plane by src/mcp/surface.ts
  'entity.name_variants', // #7160 entity card name-variant arm and possible_duplicates (default on; verbs/entity-variants.ts)
  'entity.names_references', 'entity.record_types', 'entity.row_page_status', // names-row referenced_by_count + card `next` (default on); canonical page types listed as `records` (default empty); F3 page_status on context_pack/get_backlinks rows (default on); src/core/entity-references-config.ts
  'mcp.instructions_governing_rule', // instruction 7: in_effect (default: the record in effect on the date asked about governs) | newest (the earlier recency sentence); src/mcp/instructions.ts
  // Skill-nag suppression (#2180): brain-resident pack install nag off-switch.
  'skillpack.nag_disabled',
  // Self-upgrade (v0.42; file plane, read on the hot path)
  'self_upgrade.mode',
  'self_upgrade.channel',
  'self_upgrade.mode_prompted',
  'self_upgrade.quiet_hours',
  'self_upgrade.failed_versions',
  'self_upgrade.attempting_version',
  'self_upgrade.last_check_ts',
  'self_upgrade.last_applied_version',
  'self_upgrade.autopilot_launcher',
  // Misc
  'artifacts_sync_mode',
  'cross_project_learnings',
  // Link resolution (issue #972; cross_source is issue #2589)
  'link_resolution',
  'link_resolution.global_basename',
  'link_resolution.cross_source',
  // Spend controls (v0.42.42.0, issue #2139). Previously `--force`-only — the
  // operator had to discover these by reading source. Registered so `config
  // set` accepts them directly. See docs/operations/spend-controls.md.
  'spend.posture',
  'pricing.overrides',
  // Life Chronicle (#2390, #5876): automatic event extraction, on by default
  // (unset = on). The documented opt-out is `gbrain config set auto_chronicle
  // false`; read by core/chronicle/config.ts.
  'auto_chronicle',
  // Auto-link toggle read by the put_page post-hook (link-extraction.ts),
  // reconcile-links, and sweep. The documented off-switch is `gbrain config
  // set auto_link false` — same unregistered-key class as auto_chronicle.
  'auto_link',
  // Entity mention index (core/mentions/policy.ts): off switch, +type/-type linkable types, names never linked, pages never linked (#5829),
  // aliases never derived, multi-word declared aliases, identity siblings; search's alias fan-out cap and generated-page demotion.
  'mentions.auto_link', 'mentions.entity_types', 'mentions.ignore', 'mentions.exclude_slugs', 'mentions.alias_deny', 'mentions.multiword_aliases',
  'mentions.sibling_merge', 'search.alias_fanout_max', 'search.demote_generated',
  // #4987: the write-path timeline extractor's off switch (read by
  // isAutoTimelineEnabled); registered so `gbrain config set auto_timeline off`
  // works without --force, as the compiled-truth guide documents.
  'auto_timeline',
  // Wanted pages: record unresolved authored links and wake their origins
  // when the target appears (src/core/wanted-links.ts). On by default; the
  // off switch is `gbrain config set wanted_pages.enabled false`.
  'wanted_pages.enabled',
  // Remote writes (the persistence `links` effect) record missing mention targets too. On by default (held-out verdict H8).
  'wanted_pages.remote',
  // context_pack cards list the newest pages dated after the entity page that mention it (src/core/mentions/newer-mentions.ts). On by default.
  'mentions.newer_on_cards',
  // Line grammar (src/core/line-grammar.ts): typed relation lines, off by default
  // (held-out verdict H3); undeclared relation types fall back to inference unless allowed.
  'line_grammar.enabled',
  'line_grammar.allow_undeclared_types',
  // Validity ranges on typed relation lines stored as dated edge transitions
  // (core/link-effective.ts). On by default (held-out verdict H7); applies while line_grammar.enabled is on.
  'line_grammar.effective_ranges',
  // put_page "did you mean an existing page?" advisory on creates (core/similar-pages.ts). Off by default (held-out verdict H5b).
  'put_page.similar_pages',
  // #5584: skillopt optimizer output cap (default 32000 thinking / 4096 otherwise).
  'skillopt.reflect_max_tokens',
  // #5585: skillopt strict model provenance (true|1|yes|on; other values count as on).
  'skillopt.models_strict',
  // #2606: chronicle judge output-token cap (default 4000). Event-dense
  // pages overflowed the old hardcoded 1500 and were misrecorded as
  // no_events; the cap is now configurable and truncation is surfaced.
  'chronicle.judge_max_tokens',
  'chronicle.job_budget_usd', 'chronicle.auto_daily_limit', 'chronicle.auto_recent_days', 'chronicle.auto_settle_seconds', // #5876 rails (chronicle/config.ts validates)
  'chronicle.max_events_per_page', // #5329: events published per page extraction (default 25); the surplus is counted over_cap
  // Takes bootstrap (v0.41.18.0, A12). The onboard remediation's two-gate
  // consent reads this key, and enabling it is the documented path to
  // `gbrain takes extract --from-pages` — same unregistered-key class.
  'takes.bootstrap_enabled',
  // #5885: `embed --stale` (cycle embed phase, migration drain) also embeds
  // stale takes; `false` turns that off (GBRAIN_EMBED_TAKES=0 overrides).
  'takes.auto_embed',
  // B-14: USD cap for one takes-bootstrap run's classifier calls (default 5.0;
  // 0 disables). Read by src/core/extract-takes-from-pages.ts.
  'takes.bootstrap_budget_usd',
  // Orphan reporting scope. These are consumed by core/orphan-policy.ts and
  // documented there as the per-brain override path.
  'orphans.exclude_prefixes',
  'orphans.exclude_slugs',
  'sync.cost_gate_min_usd',
  'sync.admission', // #6712 PR 4b: normal | imports_only | classify_only, what a managed pass admits (persistence/sync-admission.ts)
  'sync.max_deletes', 'sync.max_delete_ratio', 'sync.apply_held_deletions', // #7130 delete caps (sync-reconcile.ts), GBRA-133 held-deletion switch (persistence/sync-held-deletions.ts); per source: <key>.source.<id>
  'purge.retention_hours', // #7130: hours a soft-deleted page waits before the autopilot purge phase may purge it (default 72)
  'cycle.purge.mcp_request_log_retention_days', // #6770: opt-in request-log retention, 30-3650 days (mcp-request-log-retention.ts)
  'sync.federated_v2',
  'sync.include_working_tree',
  'sync.metafile_pages', // GBRA-150: typed (default) | off, whether a nested folder-scaffolding file with type:/title: frontmatter is a page (core/sync.ts)
  'sync.level_reuse', // GBRA-133 wave 4: true (default) | false, whether a resident pass patches the tree listing its last pass read (persistence/sync-tree-reuse.ts)
  // #5984: managed Postgres sync publishes pages in bulk groups (on by default; each page keeps its own request).
  'sync.bulk',
  'sync.bulk_size',
  // #6858 ask 6: on-commit sync in the resident serve and its freshness target (src/core/sync-config-keys.ts).
  'sync.on_commit', 'sync.freshness_target_seconds', 'sync.on_commit.sources', // GBRA-133 PR 2a: notifier exclusions (notifier/resident.ts)
  // #6712 PR 2: rollback keys (src/core/sync-config-keys.ts; windows in wire-skew.ts): readable and honored, not tunables.
  'sync.job_drain', 'sync.waive_batch', 'sync.foreground_priority',
  'sync.lanes', 'persistence.single_write_group', 'persistence.preadmit_cache', // the last two: write-path kill switches (persistence/switches.ts)
  // Persisted indexing scope (comma/newline-separated glob list; trailing '/'
  // normalizes to a '/**' subtree glob). Read best-effort at the top of
  // performSyncInner and UNIONED with any per-call --exclude so internal
  // callers (autopilot, minion sync jobs, dream cycle) honor the same scope.
  // Registering it here is what makes `gbrain config set sync.exclude ...`
  // work — the operator path to the feature (unregistered-key class).
  'sync.exclude',
  // #4901: the dot-directory WAIVER's persisted twin (unioned with the per-call
  // include-hidden flag, which bulk sync refuses); registered so `config set` accepts it.
  'sync.include_hidden',
  // #5988: Git sync holds (read by readSyncHoldPolicy). `sync.holds=fail`
  // restores fail-closed blocking. Detail, escalation and the parser-regression
  // stop are tuned by GBRAIN_SYNC_* env since #6712 PR 2 (RETIRED_SYNC_KEYS).
  'sync.holds', 'sync.slug_conflicts.auto_remove', // #6865: sync-time removal of a stray slug: line naming no page (repair/slug-autoheal.ts); default on
  'sync.origin_twins.auto_resolve', // #6948: sync-time merge of verified duplicate-origin twins (repair/origin-twins-heal.ts); default on
  'fences.normalize', // #6188: inline Tier 1 fence normalization (fence-repair/config.ts); default on
  'fences.repair.enabled', 'fences.repair.llm', // #6188: the fence_repair cycle phase and its Tier 3 model step (fence-repair/config.ts); default on
  'fences.repair.max_usd_per_page', 'fences.repair.max_usd_per_day', // #6188: Tier 3 fence repair caps; 0 = no model spend
  // GBRA-161: the generation primitive's restore window, shrink floor, item cap and retirement valve (generations/config.ts); PR 4 (#7065): synthesis retire_previous, default on
  'generations.restore_days', 'generations.shrink_floor', 'generations.max_items', 'generations.valve.max_per_run', 'generations.valve.max_ratio', 'generations.synthesis.retire_previous',
  // #2179: clamp window for DCR-requested per-client token TTLs. Read by
  // `gbrain serve --http` at startup; unset min defaults to 300s, unset max
  // defaults fail-closed to max(--token-ttl, min).
  'oauth.dcr_ttl_min_seconds',
  'oauth.dcr_ttl_max_seconds',
  'embed.backfill_cooldown_min',
  'embed.backfill_max_usd_per_source_24h',
  'embed.backfill_max_usd',
  // GBRA-438: free unattended upkeep on/off and its daily embedding cap (core/maintenance/run.ts).
  'maintenance.auto', 'maintenance.embed_daily_usd',
  // Brain-level default source. Read by source-resolver.ts tier 5
  // (`engine.getConfig('sources.default')`) and written by
  // `gbrain sources default <id>`. Listed here so `gbrain config set`
  // stops claiming "Nothing in gbrain reads this" for a key the resolver
  // reads on every unqualified call.
  'sources.default',
  // Alias/undeclared explicit-type warnings at sync/import (default on).
  // Read by performSync + runImport summary aggregation; 'false'/'0'/'off'
  // silences both surfaces (schema lint rules stay active).
  'schema.type_warnings',
  // #4795 reindex-search-vector marker (doctor fts_reindex_incomplete reads it); `config unset` is the escape hatch.
  'fts.reindex_in_progress',
  // #5470: managed-write journal caps + receipt retention, read by
  // persistence/limits.ts (JOURNAL_CONFIG_KEYS; drift-guarded by test).
  'persistence.limits.principal_outstanding', 'persistence.limits.brain_outstanding',
  'persistence.limits.principal_intent_bytes', 'persistence.limits.brain_intent_bytes',
  'persistence.limits.principal_lifetime_ids', 'persistence.limits.brain_lifetime_ids',
  'persistence.limits.principal_terminal_bytes', 'persistence.limits.brain_terminal_bytes',
  'persistence.limits.brain_recovery_bytes', 'persistence.limits.worktree_recovery_bytes', 'persistence.limits.principal_staged_bytes', 'persistence.limits.brain_staged_bytes', 'persistence.limits.principal_uploads', 'persistence.limits.upload_idle_seconds', 'persistence.limits.upload_max_seconds',
  'persistence.receipt_retention_days', 'persistence.housekeeping.receipt_target_bytes', 'persistence.unbound_write', 'persistence.max_claim_ms', // #5254: persistence/unbound-source.ts; #6176: persistence/claim-phase.ts
  'persistence.sync_preparation_ms', 'persistence.maintenance_preparation_ms', 'persistence.preparation_ceiling_ms', 'persistence.max_preparation_attempts', 'persistence.preparation_deadlines', 'persistence.max_transient_retries', // #6278: persistence/preparation-budget.ts, switches.ts; transient-retry.ts
  'persistence.publication_ceiling_ms', 'persistence.terminal_failures.window_days', 'persistence.terminal_failures.spike_factor', 'persistence.terminal_failures.spike_min', // #6405: persistence/sync-drain.ts (in-pass publication ceiling); #6650: persistence/terminal-failures.ts
  'persistence.capacity.warn_days', 'persistence.capacity.fail_days', 'persistence.capacity.background_pause_pct', // #6696: persistence/capacity-forecast.ts, admission-origin.ts
  'persistence.maintenance.compaction_stale_hours', // #6696 (A11): persistence/compaction-pass.ts, doctor persistence_compaction
  'persistence.maintenance.refusal_breaker_threshold', // #6696 (A12): persistence/refusal-breaker.ts
  'persistence.single_consumer', // #6317: persistence/switches.ts, consumer-election.ts (one full consumer per host; off by default)
  // shared-skills migration inventory bounds (src/core/shared-skills/inventory-limits.ts)
  'shared_skills.inventory.max_files', 'shared_skills.inventory.max_total_bytes', 'shared_skills.inventory.max_file_bytes', 'shared_skills.inventory.max_entries', 'shared_skills.migration.enabled', // #6466: false declines the 0.53.0 migration (commands/migrations/opt-out.ts)
  'persistence.write_wait_ms', // #5232: file plane, persistence/write-wait.ts
  'migrate.graduation', // file plane, src/commands/migrate-graduation.ts (engine graduation opt-out)
  'doctor.default_budget_ms', 'doctor.entry_budget_ms', 'doctor.orphan_ratio.full_scan_max_pages', 'doctor.background_refresh', // #6803: file plane (commands/doctor/default-budget.ts); DB plane (doctor/budget.ts, checks/orphan-estimate.ts)
  'consent.preapprove.paid.max_usd_per_run', 'consent.preapprove.persistent_install', // A4: file plane, core/consent.ts
  // F4b: PGLite row-delta ANALYZE (src/core/planner-stats.ts); F4a: get_health memo TTL (src/core/health-memo.ts, 0 disables).
  'planner.auto_analyze', 'planner.first_read_budget_ms', 'import.analyze_every_pages', 'health.cache_ttl_ms',
  // Wave B segmented page storage (src/core/page-body/limits.ts PAGE_BODY_CONFIG_KEYS; switch defaults off).
  'pages.segmented_storage', 'pages.max_bytes', 'pages.flip_retire_max_rows', 'versions.segmented_max_per_page', 'versions.segmented_max_pinned_bytes',
  ...RUNTIME_READER_CONFIG_KEYS, // #6780: getConfig() runtime knobs (config-runtime-keys.ts)
];

/**
 * v0.37 (D6): well-known prefix patterns for DB-plane keys that have
 * unbounded sub-keys. Used as a softer gate before falling back to
 * Levenshtein suggestion in `gbrain config set`.
 */
export const KNOWN_CONFIG_KEY_PREFIXES: readonly string[] = [
  'search.',           // search.* (mode, cache.*, etc.); config set refuses unregistered leaves (commands/config/enumerated-keys.ts)
  'graph.',            // graph.edge_validity (temporal typed-edge read policy, src/core/link-validity.ts)
  'models.',           // models.* (tier, aliases, per-task)
  'dream.',            // dream.synthesize.*, dream.patterns.*
  'cycle.',            // cycle.<phase>.*
  'embedding_columns.', // per-column overrides
  'provider_base_urls.', // per-provider base URL overrides
  'provider_chat_options.', // per-provider / per-model chat providerOptions
  'content_sanity.',    // v0.41 content-sanity tunables; enumerated like search.
  'mcp.',               // mcp.publish_skills, mcp.skills_dir (PR1 skill catalog)
  'autopilot.',         // autopilot.nightly_quality_probe.*, autopilot.auto_drain.* (#1685)
  'chronicle.',         // Life Chronicle knobs; config set refuses leaves outside CHRONICLE_CONFIG_KEYS (#5876)
  'self_upgrade.',      // v0.42 self-upgrade (mode, quiet_hours, state)
  // Queue admission control (per-name sub-keys):
  //   minions.coalesce_params.<name>, minions.ttl_waiting_hours.<name>,
  //   minions.quota_max_waiting.<name>, plus the one-time
  //   minions.ttl_notice_shown flag. Booleans via the canonical truthiness
  //   parser; numeric 0 disables.
  'minions.',
  'pace.',              // pace.mode + PACE_MODE_CONFIG_KEYS (src/core/pace-mode.ts)
  'decide.',            // System One decide.* (validated by src/core/ai/decide/config.ts DECIDE_CONFIG_KEYS)
  'sync.max_deletes.source.', 'sync.max_delete_ratio.source.', 'sync.apply_held_deletions.source.', 'persistence.adopt_local_edits.source.', // #7130 per-source delete caps, GBRA-133 per-source held-deletion switch, GST-1601 per-source local-edit adoption
  'sources.auto_reconcile.source.', // GST-2250: per-source opt-out of automatic publishing by git-reconcile and refresh (false keeps local commits unpublished; sync goes on)
  'connectors.',        // chat-connectors: source_id, sync_floor_min, embed_kickoff_min_pages, doctor_stale_hours, <provider>.{auto_sync,last_sync_at,auth_error_at,watermark_iso} (no secrets — creds are file-plane)
];

/**
 * Canonical truthiness for DB-plane boolean config values (#2753).
 *
 * Config values arrive as opaque strings from `gbrain config set`, so every
 * reader has to decide what counts as "on". Left to each call site those sets
 * drift, and the drift is silent in the worst possible way: the doctor accepted
 * `yes`/`on` while the subagent worker accepted only `true`/`1`, so
 * `gbrain config set agent.use_gateway_loop yes` produced a healthy doctor
 * report AND a runtime refusal of the very job the setting was supposed to
 * enable. One parser, used by every reader, is what keeps a green health check
 * honest.
 *
 * Accepts `true` / `1` / `yes` / `on` (case-insensitive, surrounding whitespace
 * trimmed). Everything else — including `null`, non-strings, and the empty
 * string — is false, so an unset or garbled value fails closed.
 */
export function isConfigTruthy(raw: unknown): boolean {
  return typeof raw === 'string'
    && ['true', '1', 'yes', 'on'].includes(raw.trim().toLowerCase());
}

export function saveConfig(config: GBrainConfig): void {
  mkdirSync(getConfigDir(), { recursive: true });
  // Atomic write (tmp + rename): long-lived workers re-read this file per job
  // (gateway env refresh, keyed/keyless classification) — a truncate-then-write
  // here could be read torn, making a keyed install classify as keyless and
  // calmly consume work it should retry.
  const tmp = `${getConfigPath()}.tmp-${process.pid}`;
  writeFileSync(tmp, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
  renameSync(tmp, getConfigPath());
  try {
    chmodSync(getConfigPath(), 0o600);
  } catch {
    // chmod may fail on some platforms
  }
  // v0.35.8.0: ensure the per-home `.gitignore` exists on every config-write
  // path. Cheap, idempotent, doesn't clobber user edits. Catches the case
  // where `~/.gbrain/` lives inside a git worktree (Conductor + gstack
  // workspaces hit this) so `git add` doesn't accidentally stage the brain.
  // The doctor check `home_dir_in_worktree` surfaces vectors this can't
  // close (already-tracked files, screenshots, backups, `git add -f`).
  ensureGitignore();
}

/**
 * Idempotently lay down `~/.gbrain/.gitignore` containing the single line `*`.
 * Honors GBRAIN_HOME via `configDir()`. Best-effort: errors are logged to
 * stderr and never block the caller. Never clobbers a `.gitignore` whose
 * content the user has customized.
 *
 * Called from:
 *   - `saveConfig()` so any config-writing path lays it down.
 *   - `gbrain post-upgrade` so existing users get it on next upgrade.
 *
 * What this DOES cover: a casual `git add ~/.gbrain` from inside an enclosing
 * worktree — the directory-local `.gitignore` blocks everything below it.
 *
 * What this does NOT cover (the CHANGELOG names these honestly):
 *   - Files already tracked before the .gitignore landed (no remediation here).
 *   - Screenshots, sync folders (Dropbox/iCloud), Time Machine backups.
 *   - `git add -f ~/.gbrain` (deliberate force-add bypasses .gitignore).
 *   - Out-of-band copy operations (rsync, cp -r, scp).
 *
 * The doctor check `home_dir_in_worktree` surfaces these vectors at audit
 * time so the user can act on them.
 */
export function ensureGitignore(): void {
  try {
    const dir = configDir();
    const file = join(dir, '.gitignore');
    mkdirSync(dir, { recursive: true });
    if (existsSync(file)) {
      // Don't clobber user customization. Only write when the file is missing
      // OR when its content is empty (zero-byte placeholder).
      try {
        const existing = readFileSync(file, 'utf-8');
        if (existing.trim().length > 0) return;
      } catch {
        // Read failed but file exists — leave it alone to be safe.
        return;
      }
    }
    writeFileSync(file, '*\n', { mode: 0o600 });
    try { chmodSync(file, 0o600); } catch { /* platform-specific */ }
  } catch (e) {
    // Best-effort: log to stderr, never block the caller.
    const msg = e instanceof Error ? e.message : String(e);
    process.stderr.write(`[gbrain] ensureGitignore failed (${msg}); continuing\n`);
  }
}

export function toEngineConfig(config: GBrainConfig): EngineConfig {
  return {
    engine: config.engine,
    database_url: config.database_url,
    database_path: config.database_path,
    keyword_statement_timeout_ms: config.search?.keyword_statement_timeout_ms,
  };
}

export function configDir(): string {
  // Allow override for tests, Docker, and multi-tenant deployments.
  // GBRAIN_HOME is a parent dir; we always append '.gbrain' ourselves so
  // setting GBRAIN_HOME=/tmp/x yields configDir() === '/tmp/x/.gbrain'.
  // Validates the override: must be absolute, no '..' segments.
  const override = process.env.GBRAIN_HOME;
  if (override && override.trim()) {
    const trimmed = override.trim();
    if (!isAbsolute(trimmed)) {
      throw new Error(`GBRAIN_HOME must be an absolute path; got: ${trimmed}`);
    }
    if (trimmed.split(/[\\/]/).includes('..')) {
      throw new Error(`GBRAIN_HOME must not contain '..' segments; got: ${trimmed}`);
    }
    return join(trimmed, '.gbrain');
  }
  return join(homedir(), '.gbrain');
}

export function configPath(): string {
  return join(configDir(), 'config.json');
}

/**
 * Sugar for joining paths under the active gbrain home. Use this anywhere you
 * would otherwise write `join(homedir(), '.gbrain', ...rest)`. Honors
 * GBRAIN_HOME, validates input, and centralizes the convention so future
 * audits stay simple.
 */
export function gbrainPath(...segments: string[]): string {
  return join(configDir(), ...segments);
}

/**
 * Introspect where the active DB URL would come from if we tried to connect.
 * Never throws, never connects. Env vars take precedence (matches loadConfig).
 */
export function getDbUrlSource(): DbUrlSource {
  if (process.env.GBRAIN_DATABASE_URL) return 'env:GBRAIN_DATABASE_URL';
  // Same #427 guard as loadConfig: a DATABASE_URL that Bun auto-loaded from
  // a cwd .env file is not an operator-provided source. Keeping this in
  // lockstep with loadConfig matters because doctor uses this to tell the
  // user where the URL came from — reporting env:DATABASE_URL while
  // loadConfig ignores it would send them debugging the wrong layer.
  if (effectiveEnvDatabaseUrl()) return 'env:DATABASE_URL';
  if (!existsSync(configPath())) return null;
  try {
    const raw = readFileSync(configPath(), 'utf-8');
    const parsed = JSON.parse(raw) as Partial<GBrainConfig>;
    if (parsed.database_url) return 'config-file';
    if (parsed.database_path) return 'config-file-path';
    return null;
  } catch {
    // Config file exists but is unreadable/malformed — treat as null source.
    return null;
  }
}