Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
85.4 KB
Raw Blame
import type { GBrainConfig } from '../core/config.ts';
import type { BrainEngine } from '../core/engine.ts';
import { loadConfig, loadConfigWithEngine } from '../core/config.ts';
import { isLegacyModelKey, reportLegacyModelWrite, unsetModelFilePin } from './config/model-pin-shadow.ts';
import {
  getEmbeddingColumnRegistry,
  validateColumnKey,
  validateColumnConfig,
  quoteIdentifier,
  EmbeddingColumnNotRegisteredError,
  EmbeddingColumnConfigError,
} from '../core/search/embedding-column.ts';

import { redactPgUrl } from '../core/url-redact.ts';
import { PUBLISH_GATE_KEYS } from '../mcp/publish-gates.ts';
import { isConsentConfigKey, setConsentPreapproval, unsetConsentPreapproval } from '../core/consent-preapproval.ts';
import { WRITER_ADMIN_LOCK_KEY } from '../core/persistence/admin-contract.ts';
import { CONFIG_SUBCOMMANDS, ROUTERS, subcommandHelpRequested } from '../cli/subcommands.ts';
import {
  SELF_UPGRADE_CONFIG_LEAVES,
  isSelfUpgradeConfigLeaf,
  parseSelfUpgradeConfigValue,
  selfUpgradeModeEnvOverride,
} from '../core/self-upgrade.ts';

// v0.36.x #892: sensitive config-key allowlist. The `show` path used a
// loose `.includes('key')` check that also redacts (works); the `set` path
// previously printed the raw value to stderr, leaking API keys via shell
// history + scrollback. This helper is the single source of truth so the
// two surfaces can't drift again. Match on word-segments to avoid
// false-positives (e.g. `monkey` doesn't match `key`).
// #8920: plurals (apiKeys, tokens), acronyms (APIKey, apikey) and credential, authorization and passphrase match too,
// except after a count word (max_tokens, max_output_tokens, budget_tokens, max_pending_per_credential), which names
// a limit rather than a secret.
const SECRET_WORD = /^(key|secret|token|password|pwd|passwd|auth)$/;
const SECRET_WORD_8920 = /^(keys|secrets|tokens|passwords|credentials?|authorization|passphrases?|apikeys?)$/;
const COUNT_WORDS = new Set(['max', 'min', 'budget', 'limit', 'avg', 'total', 'count', 'num', 'input', 'output', 'prompt', 'context', 'completion', 'reasoning', 'per']);
export function isSensitiveConfigKey(key: string): boolean {
  const words = key.replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2').replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase().split(/[._-]+/);
  // Whole-word matches: foo_key, foo.key, key_foo, key, api_key, secretAccessKey, ...
  return words.some((word, i) => SECRET_WORD.test(word) || (SECRET_WORD_8920.test(word) && !words.slice(0, i).some(w => COUNT_WORDS.has(w))));
}

/**
 * Vendor credential keys that `buildGatewayConfig` folds into the gateway env.
 * That seam reads the FILE plane (~/.gbrain/config.json) plus process.env and
 * never the DB plane, so `config set <vendor>_api_key` must not write the DB:
 * it would report success, `config get` would read it straight back, and every
 * provider call would still fail "requires <VENDOR>_API_KEY".
 *
 * Same bug class the v0.37.11.0 wave closed for embedding_model. That field
 * could only be fixed by refusing, because changing it needs a wipe-and-reinit.
 * A credential carries no such constraint, so the honest fix is to route the
 * write to the plane the consumer actually reads.
 *
 * Keep in sync with the `envFromConfig` mappings in
 * src/core/ai/build-gateway-config.ts.
 */
/** Dotted keys that are FILE-plane canonical (nested under a group in
 * ~/.gbrain/config.json) — read by engine-free processes via
 * loadConfigFileOnly. ONE list for both the `set` and `unset` lanes so the
 * next key cannot be added to only one branch (which would silently route
 * `unset` to the DB plane). */
const FILE_PLANE_DOTTED_KEYS: ReadonlySet<string> = new Set([
  'push.allow_unverified_remote',
  'hooks.stop_push_debounce_min',
  'backup.check_enabled',
  'backup.check_interval_days',
  // #4748: resolveMcpInstructions reads ONLY the file plane (all three MCP
  // transports build their initialize response from loadConfig()); the
  // `mcp.` prefix made a DB-plane write accepted and silently ignored.
  'mcp.instructions',
  // #5232: the CLI resolves its write wait before choosing a transport, engine-free.
  'persistence.write_wait_ms',
  // Engine graduation opt-out: the pre-connect migrate router reads it engine-free.
  'migrate.graduation', 'doctor.default_budget_ms', // #6803: the CLI doctor reads it pre-connect (commands/doctor/default-budget.ts)
  'minions.terminal_hook', // #7242: a command the worker runs; local file plane only, never the shared DB plane (minions/terminal-hook.ts)
]);

/** #5489: every self_upgrade.* reader (cli.ts startup check, autopilot,
 * doctor) reads the file plane, so the whole prefix is file-plane: a
 * registered leaf is written there and an unregistered one is refused,
 * never written to a DB row nothing reads. */
const SELF_UPGRADE_KEY_PREFIX = 'self_upgrade.';

/** GBRA-377: skills.resolver.* are file-plane only, set|unset|get before any engine (logic in core/setup/skill-resolver-config.ts). */
const runSkillResolverKey = async (args: string[]) => (await import('../core/setup/skill-resolver-config.ts')).runSkillResolverConfigKey(args, (await import('../core/config.ts')).configDir());
/** The single membership test the get/set/unset lanes share. */
function isFilePlaneDottedKey(key: string): boolean {
  return FILE_PLANE_DOTTED_KEYS.has(key) || key.startsWith(SELF_UPGRADE_KEY_PREFIX) || key.startsWith('skills.resolver.') || isConsentConfigKey(key);
}

/** Delete the DB-plane row of a file-plane key: a `config set` from before
 * the key was routed (#5489, #4748) wrote it there and nothing reads it.
 * Best-effort: the file-plane write already succeeded, so a DB failure warns
 * and the command still succeeds. */
async function dropStaleDbRow(engine: BrainEngine, key: string): Promise<number> {
  try {
    return await engine.unsetConfig(key);
  } catch (e) {
    console.error(`[config] WARN: could not check for a stale DB-plane row for ${key} (${e instanceof Error ? e.message : String(e)}); nothing reads one.`);
    return 0;
  }
}

function warnSelfUpgradeModeEnvOverride(): void {
  const env = selfUpgradeModeEnvOverride();
  if (env) {
    console.error(`[config] note: GBRAIN_SELF_UPGRADE_MODE=${env} is set and overrides the file; the effective mode stays ${env} while it is set.`);
  }
}

/** Remove a file-plane dotted key from ~/.gbrain/config.json; true when the
 * file held it. Splits at the FIRST dot, so `self_upgrade.quiet_hours.start`
 * never deletes `quiet_hours`. */
async function unsetFilePlaneKey(key: string): Promise<boolean> {
  if (isConsentConfigKey(key)) return unsetConsentPreapproval(key);
  const { loadConfigFileOnly, saveConfig } = await import('../core/config.ts');
  const cfg = loadConfigFileOnly();
  const dot = key.indexOf('.');
  const top = key.slice(0, dot) as 'push' | 'hooks' | 'backup' | 'mcp' | 'self_upgrade' | 'persistence' | 'migrate' | 'doctor' | 'minions';
  const leaf = key.slice(dot + 1);
  const branch = cfg?.[top] as Record<string, unknown> | undefined;
  if (!cfg || !branch || !(leaf in branch)) return false;
  delete branch[leaf];
  saveConfig(cfg);
  return true;
}

/** Ambient-writeback keys are DUAL-PLANE (OV2-5): the DB plane is
 * authoritative (the serve-side harvest gate re-checks it before any
 * extraction) while the file plane mirrors it for the engine-free readers
 * (Stop-hook child, stdio boot resolve, the bootstrap-harness advisory's
 * audience gate). ONE leaf list derives both the Set and the unset lane's
 * types so a new key cannot be dual-written on one lane and single-deleted
 * (or silently mistyped) on the other. Write order: file first, then DB —
 * a DB failure leaves the planes briefly diverged and says so (doctor
 * surfaces plane drift). */
const MEMORY_DUAL_PLANE_LEAVES = ['auto_writeback', 'auto_writeback_transient_ttl'] as const;
const MEMORY_DUAL_PLANE_KEYS: ReadonlySet<string> = new Set(
  MEMORY_DUAL_PLANE_LEAVES.map((l) => `memory.${l}`),
);
/** `brain.audience` mirrors the same dual-plane rule (WP8): the declared
 * audience must be readable by the ENGINE-FREE bootstrap-harness lane so a
 * shared-declared brain never gets the enable-nudge advisory. */
const BRAIN_AUDIENCE_KEY = 'brain.audience';


/** `embedding_disabled` is dual-plane too: the DB row is authoritative (a
 * mounted brain has no other plane) and the host's file mirror keeps the
 * engine-free readers in step. Runtime gates treat `true` on EITHER plane as
 * disabled, so set and unset always write both and `get` reports that
 * effective value. */
const EMBEDDING_DISABLED_KEY = 'embedding_disabled';

async function setEmbeddingDisabled(engine: BrainEngine, value: string): Promise<void> {
  const normalized = value.trim().toLowerCase();
  if (normalized !== 'true' && normalized !== 'false') {
    console.error(`[config] ${EMBEDDING_DISABLED_KEY} must be true or false (got '${value}'). Nothing was written.`);
    process.exit(1);
  }
  const { loadConfigFileOnly, saveConfig } = await import('../core/config.ts');
  const hostPlane = await hostBrainSelected();
  const cfg = loadConfigFileOnly();
  if (hostPlane && cfg) {
    if (normalized === 'true') cfg.embedding_disabled = true;
    else delete cfg.embedding_disabled;
    saveConfig(cfg);
  }
  try {
    await engine.setConfig(EMBEDDING_DISABLED_KEY, normalized);
  } catch (e) {
    console.error(`[config] ERROR: ${hostPlane ? 'file plane written but ' : ''}the DB-plane write failed (${e instanceof Error ? e.message : String(e)}).`);
    console.error(`[config] The planes now disagree and embedding stays off while either says true — re-run this command once the database is reachable.`);
    process.exit(1);
  }
  console.log(`Set ${EMBEDDING_DISABLED_KEY} = ${normalized} (${hostPlane ? 'file + db planes' : 'db plane only — mounted brain'})`);
  if (normalized === 'false' && cfg && !cfg.embedding_model?.trim()) {
    const { embeddingEnablement } = await import('../core/readiness.ts');
    const { shellQuote } = await import('../core/agent-output.ts');
    const fix = embeddingEnablement({ ...cfg, embedding_disabled: false });
    if (fix.argv) console.log(`No embedding model is configured yet. Turn on semantic search (pages and facts are kept): ${shellQuote(fix.argv)}`);
  }
}

async function unsetEmbeddingDisabled(engine: BrainEngine): Promise<void> {
  const { loadConfigFileOnly, saveConfig } = await import('../core/config.ts');
  const cfg = loadConfigFileOnly();
  const fileHad = (await hostBrainSelected()) && cfg !== null && EMBEDDING_DISABLED_KEY in cfg;
  if (fileHad) {
    delete cfg!.embedding_disabled;
    saveConfig(cfg!);
  }
  const dbDeleted = await engine.unsetConfig(EMBEDDING_DISABLED_KEY);
  if (!fileHad && dbDeleted === 0) {
    console.error(`Config key not found: ${EMBEDDING_DISABLED_KEY}`);
    process.exit(1);
  }
  console.log(`Unset ${EMBEDDING_DISABLED_KEY} (${[fileHad ? 'file plane' : null, dbDeleted > 0 ? 'db plane' : null].filter(Boolean).join(' + ')})`);
}

/** The effective `embedding_disabled` and where it comes from; null when neither plane holds it. */
async function effectiveEmbeddingDisabled(engine: BrainEngine): Promise<{ value: boolean; note: string } | null> {
  const file = loadConfig()?.embedding_disabled;
  const db = await engine.getConfig(EMBEDDING_DISABLED_KEY);
  if (file === undefined && db === null) return null;
  const value = file === true || db === 'true';
  const planes = `file: ${file === undefined ? 'unset' : String(file)}, db: ${db ?? 'unset'}`;
  const agree = db === null || file === undefined || String(file === true) === db;
  return { value, note: agree
    ? `effective value (${planes}); either plane's true turns embedding off`
    : `planes disagree (${planes}); embedding stays off while either says true. Re-sync: gbrain config set ${EMBEDDING_DISABLED_KEY} <true|false>` };
}

const SCHEMA_PACK_SOURCE_LABEL: Record<string, string> = {
  env: 'GBRAIN_SCHEMA_PACK env', 'db-config': 'db plane (gbrain config set schema_pack)', 'gbrain-yml': 'gbrain.yml',
  'home-config': 'file plane (~/.gbrain/config.json)', default: 'built-in default',
};

/** The brain-wide schema pack the runtime resolves (the same tiers `gbrain schema active` uses). */
async function effectiveSchemaPack(engine: BrainEngine): Promise<{ value: string; note: string }> {
  const { readDbSchemaPack } = await import('../core/schema-pack/engine-resolution.ts');
  const { resolveActivePackNameOnly } = await import('../core/schema-pack/load-active.ts');
  const resolution = resolveActivePackNameOnly({ cfg: loadConfig(), remote: false, dbConfig: await readDbSchemaPack(engine) });
  return { value: resolution.pack_name, note: `${SCHEMA_PACK_SOURCE_LABEL[resolution.source] ?? resolution.source}; the tier gbrain schema active resolves` };
}

/** Ambient-writeback posture re-stamp (red-team review, this wave): the
 * engine-free bootstrap-harness renderer reads `memory.visibility_posture`
 * from the file mirror, previously refreshed ONLY by `config set memory.*` —
 * so a later `facts.default_visibility` flip left installed instruction
 * blocks ordering the OLD posture (visibility is an EXPLICIT param in the
 * block, so a stale 'world' stamp silently widens an operator's new private
 * default) and doctor's drift warn named a bootstrap re-run that could never
 * converge. Re-stamping on every facts.default_visibility set/unset closes
 * the loop. Best-effort and gated on the mirror already existing: a failed
 * stamp never breaks the DB write that persisted, and brains that never
 * touched ambient writeback don't grow a `memory` slot. */
/** The machine-global config.json mirror belongs to the HOST brain: a
 * `config set/unset --brain <mount>` (or GBRAIN_BRAIN_ID / .gbrain-mount)
 * writes the MOUNT's DB row without touching the host's engine-free readers
 * — enabling ambient writeback on a team mount must never opt the host's
 * Stop hook into banking host conversations (codex re-review, this wave).
 * Unresolvable brain selection also skips the mirror (fail toward not
 * mutating host state); doctor's plane-compare names the re-sync if the
 * HOST's own planes ever diverge. */
async function hostBrainSelected(): Promise<boolean> {
  try {
    const { resolveBrainId } = await import('../core/brain-resolver.ts');
    const { HOST_BRAIN_ID } = await import('../core/brain-registry.ts');
    const { getCliOptions } = await import('../core/cli-options.ts');
    return resolveBrainId(getCliOptions().brain ?? null) === HOST_BRAIN_ID;
  } catch {
    return false;
  }
}

async function restampVisibilityPosture(newRaw: string | null): Promise<void> {
  try {
    if (!(await hostBrainSelected())) return; // a mount's posture never stamps the host mirror
    const { loadConfigFileOnly, saveConfig } = await import('../core/config.ts');
    const { visibilityPostureFromRaw } = await import('../core/facts/writeback-config.ts');
    const cfg = loadConfigFileOnly();
    if (!cfg?.memory) return;
    cfg.memory.visibility_posture = visibilityPostureFromRaw(newRaw).visibility;
    saveConfig(cfg);
  } catch { /* best-effort — the authoritative DB write already landed */ }
}

export const FILE_PLANE_API_KEYS: readonly string[] = [
  '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', // #4031: mergedProviderEnv reads the file plane only
];

export function redactConfigValue(key: string, value: string): string {
  // Both scheme spellings — the old local regex only matched postgresql://,
  // so a postgres:// DSN's password echoed in the clear. redactPgUrl is the
  // canonical single home (drops the whole userinfo, both schemes).
  if (/postgres(ql)?:\/\//.test(value)) return redactPgUrl(value);
  if (isSensitiveConfigKey(key)) return '***';
  // #8920: userinfo (user:pass@) in a URL of any other scheme; an `@` after the host (a path, query or fragment) is not userinfo.
  return value.replace(/([a-z][a-z0-9+.-]*:\/\/)[^/?#\s]*@/gi, '$1***@');
}

/** An object config value with every sensitive field masked at any depth (#7346: storage.secretAccessKey). */
function redactNestedConfig(value: unknown): unknown {
  if (Array.isArray(value)) return value.map(redactNestedConfig);
  if (value === null || typeof value !== 'object') return value;
  return Object.fromEntries(Object.entries(value).map(([k, v]) => [k,
    typeof v === 'string' ? redactConfigValue(k, v) : v !== null && v !== undefined && isSensitiveConfigKey(k) ? '***' : redactNestedConfig(v)]));
}

// #3661: the flags `config set` actually honors. Everything else that looks
// like a flag is rejected before the write — see the gate in the `set` branch.
const CONFIG_SET_KNOWN_FLAGS = ['--force', '--coverage-override', '--yes'];

/**
 * db-availability loop (5c): the DB-connection keys are FILE-plane canonical —
 * `loadConfig()` never reads them from the DB plane, so the old fall-through
 * to `engine.setConfig` was a silent no-op that even read back "correctly"
 * via `config get` (from the DB plane). Worse, it was CIRCULAR: `config` sat
 * behind connectEngine, so "fix your URL with config set database_url" died
 * on the exact connection error it was meant to fix.
 *
 *   database_url / database_path → ROUTED to the file plane (the
 *     FILE_PLANE_API_KEYS pattern — the intent is satisfiable as typed);
 *     engine is inferred from whichever key was set.
 *   engine → HARD-REFUSED with the recipe (the embedding_model treatment):
 *     a direct engine flip without a data migration splits the brain across
 *     two stores. No --force escape.
 *
 * Returns true when the key was handled (caller returns). Engine-free by
 * construction — dispatched BEFORE connectEngine via tryRunConfigEngineFree.
 */
export async function handleDbPlaneRoutedKeys(key: string, value: string): Promise<boolean> {
  if (key === 'engine') {
    console.error('[config] engine is INFERRED from database_url / database_path — it is never set directly.');
    console.error('[config] To move your data between engines:  gbrain migrate --to <postgres|pglite>');
    console.error('[config] To point at a different database:   gbrain config set database_url <conn>  (or gbrain init --url <conn>)');
    console.error('[config] No --force escape: an engine flip without a data migration splits the brain across two stores.');
    process.exit(1);
  }
  if (key !== 'database_url' && key !== 'database_path') return false;
  if (key === 'database_url' && !/^postgres(ql)?:\/\//.test(value)) {
    console.error('[config] database_url must be a postgres:// or postgresql:// connection string.');
    process.exit(1);
  }
  const { isThinClient, loadConfigFileOnly, saveConfig } = await import('../core/config.ts');
  const cfg = (loadConfigFileOnly() ?? {}) as Parameters<typeof saveConfig>[0] & Record<string, unknown>;
  // Thin-client guard (same bar as db-repair and init's re-run refusal):
  // writing a local engine + URL into a remote_mcp config would create the
  // hybrid local/remote state init explicitly refuses to create.
  if (isThinClient(cfg as Parameters<typeof isThinClient>[0])) {
    console.error('[config] this machine is a thin client (remote MCP) — a local database_url would conflict with the remote setup.');
    console.error('[config] To convert it to a local brain deliberately: gbrain init --url <conn> --force');
    process.exit(1);
  }
  const priorEngine = cfg.engine;
  const priorPath = typeof cfg.database_path === 'string' ? cfg.database_path : null;
  if (key === 'database_url') {
    cfg.database_url = value;
    cfg.engine = 'postgres';
    delete cfg.database_path;
  } else {
    cfg.database_path = value;
    cfg.engine = 'pglite';
    delete cfg.database_url;
  }
  saveConfig(cfg);
  console.log(`Set ${key} = ${redactConfigValue(key, value)} (file plane: ~/.gbrain/config.json; engine inferred: ${cfg.engine})`);
  const { gbrainPath } = await import('../core/config.ts');
  const { inspectGraduationPath } = await import('../core/persistence/graduation-custody.ts');
  const graduated = priorEngine === 'pglite' && key === 'database_url' && inspectGraduationPath(priorPath ?? gbrainPath('brain.pglite')).state === 'graduated';
  if (graduated) {
    console.error('[config] note: this brain was moved to Postgres by engine graduation; this config now points at it. Restart any MCP client that runs gbrain serve from this config.');
  } else if (priorEngine && priorEngine !== cfg.engine) {
    // Pointing at the other engine's plane is a legitimate re-point, but it
    // does NOT move data — say so, or the flip reads as a lossless switch.
    console.error(
      `[config] note: engine flipped ${priorEngine} → ${cfg.engine}. Existing ${priorEngine} data was NOT moved — ` +
        `to move it, use: gbrain migrate --to ${cfg.engine === 'postgres' ? 'supabase' : 'pglite'}`,
    );
  }
  return true;
}

/**
 * Engine-free `config set` dispatch for the DB-connection keys. Called from
 * handleCliOnly BEFORE connectEngine — these are exactly the keys you need
 * to change when the engine can't connect. Returns true when handled.
 */
export async function tryRunConfigEngineFree(args: string[]): Promise<boolean> {
  if (args[1]?.startsWith('skills.resolver.')) return runSkillResolverKey(args);
  if (args[0] !== 'set') return false;
  const key = args[1];
  const value = args.slice(2).find((a) => !a.startsWith('-'));
  if (!key || value === undefined) return false; // let the engine path print usage
  if (key !== 'database_url' && key !== 'database_path' && key !== 'engine') return false;
  return handleDbPlaneRoutedKeys(key, value);
}

/**
 * System One: decide.* keys validate at set time (enums, numeric ranges), and a
 * decide.slots.* write prints the requested-versus-effective mode line after it
 * persists (best-effort). #5876: auto_chronicle and chronicle.* gate paid
 * extraction, so they validate here too, and an explicit auto_chronicle set
 * records the operator's answer to the default-on change.
 */
const setLineGrammarConfig = async (engine: BrainEngine, key: string, value: string) => (await import('./config-line-grammar.ts')).setLineGrammarConfig(engine, key, value);

async function setConfigWithDecideHooks(engine: BrainEngine, key: string, value: string, force = false): Promise<void> {
  if (await setLineGrammarConfig(engine, key, value)) return;
  if (key === 'sync.admission') return (await import('./config/sync-admission-value.ts')).setSyncAdmissionValue(engine, value);
  if (key === 'sync.metafile_pages') return (await import('./config/sync-metafile-pages-value.ts')).setMetafilePagesValue(engine, value);
  if (/^sync\.(max_delete(s|_ratio)|apply_held_deletions)(\.source\..+)?$/.test(key) || key === 'purge.retention_hours') {
    const err = (await import('../core/sync-reconcile.ts')).deleteSafetyConfigRefusal(key, value);
    if (err) { console.error(`[config] ${err}`); process.exit(1); }
  }
  if (key.startsWith('decide.')) {
    const { validateDecideConfigValue } = await import('../core/ai/decide/config.ts');
    const err = validateDecideConfigValue(key, value);
    if (err) { console.error(`[config] ${err}`); process.exit(1); }
  }
  (await import('./config/enumerated-keys.ts')).refuseUnregisteredEnumeratedKey(key, force);
  if (key.startsWith('generations.')) await (await import('./config/generations-values.ts')).refuseGenerationsValue(key, value);
  const searchRefusal = key.startsWith('search.') ? (await import('../core/search/config-values.ts')).searchConfigValueRefusal(key, value) : null;
  if (searchRefusal) {
    const { exitCliError, usageError } = await import('../cli/cli-error.ts');
    exitCliError(usageError(searchRefusal.message, `Re-run with a valid value, e.g. gbrain config set ${key} ${searchRefusal.example}.`,
      { fix: { argv: ['gbrain', 'config', 'get', key], consent: [], actor: 'agent', why: 'Shows the value in effect; nothing was written.', requires_exclusive: false } }), 'config');
  }
  if (key === 'auto_chronicle' || key.startsWith('chronicle.')) await refuseInvalidChronicleValue(key, value, force);
  if (key.startsWith('fences.')) {
    const { validateFenceConfigValue } = await import('../core/fence-repair/config.ts');
    const err = validateFenceConfigValue(key, value);
    if (err) { console.error(`[config] ${err}`); process.exit(1); }
  }
  if (key.startsWith('loops.')) (await import('./config/loops-values.ts')).refuseInvalidLoopsConfigValue(key, value);
  if (key === 'dream.claim_conflicts.mode') { const err = (await import('../core/facts/claim-conflicts.ts')).claimConflictsModeRefusal(value); if (err) { console.error(`[config] ${err}`); process.exit(1); } }
  if (key.startsWith('recall.')) { const err = (await import('../core/facts/recall-config.ts')).recallConfigValueRefusal(key, value); if (err) { console.error(`[config] ${err}`); process.exit(1); } }
  if (key === 'sync.slug_conflicts.auto_remove') { const err = (await import('../core/repair/slug-autoheal.ts')).slugAutoRemoveValueRefusal(value); if (err) { console.error(`[config] ${err}`); process.exit(1); } }
  if (key === 'sync.origin_twins.auto_resolve') { const err = (await import('../core/repair/origin-twins-heal.ts')).originAutoResolveValueRefusal(value); if (err) { console.error(`[config] ${err}`); process.exit(1); } }
  if (key === 'sync.repo_path') { const err = (await import('../core/sync-config-keys.ts')).syncRepoPathRefusal(value); if (err) { console.error(`[config] ${err}`); process.exit(1); } }
  if (key === 'cycle.purge.mcp_request_log_retention_days') { const err = (await import('../core/mcp-request-log-retention.ts')).mcpLogRetentionRefusal(value); if (err) { console.error(`[config] ${err}`); process.exit(1); } }
  if (key.startsWith('search.')) (await import('./config/keyword-timeout-value.ts')).refuseInvalidKeywordTimeoutValue(key, value);
  if (key === 'persistence.max_claim_ms') {
    const { validateMaxClaimConfigValue } = await import('../core/persistence/claim-phase.ts');
    const err = validateMaxClaimConfigValue(key, value);
    if (err) { console.error(`[config] ${err}`); process.exit(1); }
  }
  if (key.startsWith('persistence.')) await (await import('./config/preparation-keys.ts')).refuseInvalidPreparationValue(engine, key, value);
  if (key.startsWith('facts.')) await (await import('./config/facts-values.ts')).refuseInvalidFactsConfigValue(key, value);
  await engine.setConfig(key, value);
  if (key === 'search.contextual_retrieval') console.log((await import('./config/contextual-mode-hint.ts')).contextualModeHint());
  if (key === 'auto_chronicle') await acknowledgeAutoChronicle(engine, value);
  if (!key.startsWith('decide.slots.')) return;
  try {
    const { printEffectiveModeLines } = await import('./decide.ts');
    await printEffectiveModeLines(engine, key.split('.')[2]);
  } catch { /* the value already persisted */ }
}

const AUTO_CHRONICLE_UNSET_NOTE = '\nauto_chronicle now uses its default, which is ON: eligible new or changed meeting, conversation and calendar pages each get one paid extraction call.' +
  '\nTo turn automatic extraction off, run: gbrain config set auto_chronicle false';

/** #5876: refuse unknown chronicle.* leaves (unless forced) and out-of-range values; nothing is written. */
async function refuseInvalidChronicleValue(key: string, value: string, force: boolean): Promise<void> {
  const { validateChronicleConfigValue, CHRONICLE_CONFIG_KEYS } = await import('../core/chronicle/config.ts');
  if (key.startsWith('chronicle.') && !CHRONICLE_CONFIG_KEYS.includes(key) && !force) {
    const { suggestNearest } = await import('../core/levenshtein.ts');
    const suggestion = suggestNearest(key, [...CHRONICLE_CONFIG_KEYS], 3);
    console.error(`[config] Unknown config key "${key}".${suggestion ? ` Did you mean "${suggestion}"?` : ''}`);
    console.error(`[config] chronicle keys: ${CHRONICLE_CONFIG_KEYS.join(', ')}. Nothing was written.`);
    process.exit(1);
  }
  const err = validateChronicleConfigValue(key, value);
  if (err) { console.error(`[config] ${err}`); process.exit(1); }
}

/**
 * #5876: an explicit `config set auto_chronicle` answers the default-on change, which clears the
 * durable doctor/advisor `auto_chronicle_default_on` notice. Best-effort: the value already persisted.
 */
async function acknowledgeAutoChronicle(engine: BrainEngine, value: string): Promise<void> {
  const { CHRONICLE_ACK_KEY, autoChronicleSetting } = await import('../core/chronicle/config.ts');
  try { await engine.setConfig(CHRONICLE_ACK_KEY, new Date().toISOString()); } catch { /* the notice stays; harmless */ }
  if (autoChronicleSetting(value) === 'on') {
    console.log('Automatic event extraction is on: each eligible new or changed meeting, conversation or calendar page gets one paid chat call, bounded by chronicle.job_budget_usd per page and chronicle.auto_daily_limit per day.');
    console.log('To turn it off: gbrain config set auto_chronicle false');
  } else {
    console.log('Automatic event extraction is off. To extract history on request (paid; ask the user first): gbrain chronicle-backfill --dry-run');
  }
}

/** #5232: the CLI write wait is file-plane so the engine-free CLI reads it before choosing a transport. */
async function setFileWriteWait(cfg: GBrainConfig, value: string, saveConfig: (cfg: GBrainConfig) => void): Promise<void> {
  const { MAX_WRITE_WAIT_MS, WRITE_WAIT_CONFIG_KEY, WRITE_WAIT_ENV } = await import('../core/persistence/write-wait.ts');
  const n = /^\d+$/.test(value.trim()) ? Number(value) : NaN;
  if (!Number.isSafeInteger(n) || n > MAX_WRITE_WAIT_MS) {
    console.error(`[config] ${WRITE_WAIT_CONFIG_KEY} must be a whole number of milliseconds from 0 to ${MAX_WRITE_WAIT_MS}`);
    process.exit(1);
  }
  cfg.persistence = { ...(cfg.persistence ?? {}), write_wait_ms: n };
  saveConfig(cfg);
  console.log(`Set ${WRITE_WAIT_CONFIG_KEY} = ${n} (file plane: ~/.gbrain/config.json; --wait and ${WRITE_WAIT_ENV} override it)`);
}

/** `config set` for the FILE_PLANE_DOTTED_KEYS and the memorable consent
 * gate: every one of these is read from ~/.gbrain/config.json by an
 * engine-free reader, so the write never touches the engine. */
async function setFilePlaneKey(key: string, value: string, tail: string[]): Promise<void> {
  const { loadConfigFileOnly, saveConfig, isConfigTruthy } = await import('../core/config.ts');
  const cfg = (loadConfigFileOnly() ?? { engine: 'pglite' }) as Parameters<typeof saveConfig>[0];
  if (key === 'integrations.memorable.enabled') {
    // Same file-plane rule as the other hook-lane keys: the session-end
    // relay gate is read by engine-free hook children via loadConfig.
    //
    // Enabling is a CONSENT event, not just a config write: the relay
    // hands session tool-call traces to a closed-source third-party CLI
    // that sends them off-machine. The gate requires a gbrain-authored
    // consent stamp that ONLY this flow writes (the memorable CLI flips
    // the boolean out-of-band on `memorable enable`, but it can never
    // write the stamp — see hook-heartbeat.ts's consent-stamp section).
    const hb = await import('../core/context/hook-heartbeat.ts');
    const on = isConfigTruthy(value);
    if (!on) {
      cfg.integrations = { ...(cfg.integrations ?? {}), memorable: { ...(cfg.integrations?.memorable ?? {}), enabled: false } };
      saveConfig(cfg);
      await hb.clearMemorableConsent();
      console.log(`Set ${key} = false (file plane: ~/.gbrain/config.json)`);
      console.log('Relay disabled and the disclosure consent was revoked — re-enabling shows the disclosure again.');
      return;
    }
    if (!(await hb.memorableConsentValid())) {
      console.log(hb.MEMORABLE_DISCLOSURE_TEXT);
      const preConsented = tail.includes('--yes');
      if (!preConsented) {
        if (!process.stdin.isTTY) {
          // Skillpack trust-prompt posture: a non-interactive session
          // cannot consent on the operator's behalf. Nothing was written.
          console.error('[config] non-interactive session and no --yes: refusing to enable a third-party relay without explicit consent. Nothing was written.');
          // Deliberately does NOT mention --yes: this line is printed INTO
          // agent sessions (the very sessions whose tool calls the relay
          // egresses), and advertising the non-interactive bypass here
          // hands a prompt-injected agent the exact string that flips the
          // gate. Operators find --yes in the docs.
          console.error('[AGENT] Relay this to your operator: run `gbrain config set integrations.memorable.enabled true` in a terminal and answer the prompt. If the user has no terminal on this machine, this can\'t be enabled from this session.');
          process.exit(1);
        }
        const { promptYesNo } = await import('../core/confirm-prompt.ts');
        const accepted = await promptYesNo('[gbrain] Enable the Memorable session-end relay? [y/N] ');
        if (!accepted) {
          console.log('Declined. Nothing was written.');
          return;
        }
      }
      const stampPath = await hb.writeMemorableConsent();
      console.log(`Consent recorded: ${stampPath}`);
    }
    cfg.integrations = { ...(cfg.integrations ?? {}), memorable: { ...(cfg.integrations?.memorable ?? {}), enabled: true } };
    saveConfig(cfg);
    console.log(`Set ${key} = true (file plane: ~/.gbrain/config.json)`);
    console.log(
      'Session-end traces will now be offered to the locally-installed `memorable` CLI, ' +
        'which sends redacted tool calls off-machine to its extraction API. ' +
        'Turn off: gbrain config set integrations.memorable.enabled false (or GBRAIN_MEMORABLE=0)',
    );
  } else if (isConsentConfigKey(key)) {
    // A4 user preapprovals: host file plane only, written by this trusted local CLI.
    try {
      console.log(setConsentPreapproval(key, value, { remote: false }));
    } catch (e) {
      const { message, suggestion } = e as { message: string; suggestion?: string };
      console.error(`[config] ${message}${suggestion ? ` ${suggestion}` : ''}`);
      process.exit(1);
    }
  } else if (key === 'push.allow_unverified_remote') {
    const on = isConfigTruthy(value);
    cfg.push = { ...(cfg.push ?? {}), allow_unverified_remote: on };
    saveConfig(cfg);
    console.log(`Set ${key} = ${on} (file plane: ~/.gbrain/config.json)`);
    if (on) {
      console.log(
        'WARNING: workspace pushes now SKIP repo-visibility verification. ' +
          'This trusts the remote on your word — unset it once verification works: ' +
          'gbrain config set push.allow_unverified_remote false',
      );
    }
  } else if (key === 'backup.check_enabled') {
    const on = isConfigTruthy(value);
    cfg.backup = { ...(cfg.backup ?? {}), check_enabled: on };
    saveConfig(cfg);
    console.log(`Set ${key} = ${on} (file plane: ~/.gbrain/config.json)`);
  } else if (key === 'persistence.write_wait_ms') { await setFileWriteWait(cfg, value, saveConfig);
  } else if (key === 'minions.terminal_hook') { (await import('../core/minions/terminal-hook.ts')).setTerminalHookConfig(cfg, value, saveConfig);
  } else if (key === 'doctor.default_budget_ms') { (await import('./doctor/default-budget.ts')).setDoctorDefaultBudget(cfg, value, saveConfig);
  } else if (key === 'migrate.graduation') {
    const on = isConfigTruthy(value);
    cfg.migrate = { ...(cfg.migrate ?? {}), graduation: on };
    saveConfig(cfg);
    console.log(`Set ${key} = ${on} (file plane: ~/.gbrain/config.json)`);
    if (!on) console.log('PGLite -> Postgres moves now use the legacy copier, which refuses brains with write history. Turn graduation back on: gbrain config unset migrate.graduation');
  } else if (key === 'backup.check_interval_days') {
    const n = Number.parseInt(value, 10);
    if (!Number.isFinite(n) || n < 1) {
      console.error(`[config] ${key} must be an integer >= 1 (days between automatic backup checks)`);
      process.exit(1);
    }
    cfg.backup = { ...(cfg.backup ?? {}), check_interval_days: n };
    saveConfig(cfg);
    console.log(`Set ${key} = ${n} (file plane: ~/.gbrain/config.json)`);
  } else if (key === 'mcp.instructions') {
    // #4748: deployment identity appended to the MCP initialize contract.
    // Takes effect on the next `gbrain serve` start (the response is
    // built once per process from loadConfig()).
    cfg.mcp = { ...(cfg.mcp ?? {}), instructions: value };
    saveConfig(cfg);
    console.log(`Set ${key} (file plane: ~/.gbrain/config.json) — restart \`gbrain serve\` to apply`);
  } else if (key.startsWith(SELF_UPGRADE_KEY_PREFIX)) {
    const leaf = key.slice(SELF_UPGRADE_KEY_PREFIX.length);
    if (!isSelfUpgradeConfigLeaf(leaf)) {
      const { suggestNearest } = await import('../core/levenshtein.ts');
      const suggestion = suggestNearest(key, SELF_UPGRADE_CONFIG_LEAVES.map((l) => `${SELF_UPGRADE_KEY_PREFIX}${l}`), 3);
      console.error(`[config] Unknown config key "${key}".${suggestion ? ` Did you mean "${suggestion}"?` : ''}`);
      console.error(`[config] self_upgrade keys: ${SELF_UPGRADE_CONFIG_LEAVES.join(', ')}. Nothing was written.`);
      process.exit(1);
    }
    const parsed = parseSelfUpgradeConfigValue(leaf, value);
    if (!parsed.ok) {
      console.error(`[config] ${key} ${parsed.error}`);
      process.exit(1);
    }
    cfg.self_upgrade = { ...(cfg.self_upgrade ?? {}), [leaf]: parsed.value };
    saveConfig(cfg);
    console.log(`Set ${key} = ${JSON.stringify(parsed.value)} (file plane: ~/.gbrain/config.json)`);
    if (leaf === 'mode') warnSelfUpgradeModeEnvOverride();
  } else {
    const n = Number.parseInt(value, 10);
    if (!Number.isFinite(n) || n < 0) {
      console.error(`[config] ${key} must be an integer >= 0 (minutes; 0 = push every turn)`);
      process.exit(1);
    }
    cfg.hooks = { ...(cfg.hooks ?? {}), stop_push_debounce_min: n };
    saveConfig(cfg);
    console.log(`Set ${key} = ${n} (file plane: ~/.gbrain/config.json)`);
  }
}

/**
 * Thin-client `config` dispatch. `self_upgrade.*` is machine-local:
 * self-upgrade runs engine-free on every install shape, a thin client
 * included, so `config set|unset|get self_upgrade.<key>` edit this machine's
 * ~/.gbrain/config.json. Every other key, and any flag, keeps the host-plane
 * refusal. Returns true when handled.
 */
export async function tryRunConfigThinClient(args: string[]): Promise<boolean> {
  if (args[1]?.startsWith('skills.resolver.')) return runSkillResolverKey(args);
  const [action, key, ...rest] = args;
  if (!key || !key.startsWith(SELF_UPGRADE_KEY_PREFIX) || rest.some((a) => a.startsWith('-'))) return false;
  if (action === 'set' && rest.length === 1) {
    await setFilePlaneKey(key, rest[0], rest);
    return true;
  }
  if (action === 'unset' && rest.length === 0) {
    if (!(await unsetFilePlaneKey(key))) {
      console.error(`Config key not found: ${key}`);
      process.exit(1);
    }
    console.log(`Unset ${key} (file plane)`);
    if (key === `${SELF_UPGRADE_KEY_PREFIX}mode`) warnSelfUpgradeModeEnvOverride();
    return true;
  }
  if (action === 'get' && rest.length === 0) {
    const { loadConfigFileOnly } = await import('../core/config.ts');
    const branch = loadConfigFileOnly()?.self_upgrade as Record<string, unknown> | undefined;
    const val = branch?.[key.slice(SELF_UPGRADE_KEY_PREFIX.length)];
    if (val === undefined || val === null) {
      console.error(`Config key not found: ${key}`);
      process.exit(1);
    }
    console.log(typeof val === 'string' ? val : JSON.stringify(val));
    console.error('[config] source: file plane (~/.gbrain/config.json)');
    return true;
  }
  return false;
}

/** `config show`: file/env values, with the effective DB-aware value for the dual-plane keys. */
async function showConfig(engine: BrainEngine): Promise<void> {
  const config = loadConfig();
  if (!config) {
    console.error('No config found. Run: gbrain init');
    process.exit(1);
  }
  console.log('GBrain config:');
  const effective: Record<string, { value: unknown; note: string }> = {};
  try {
    effective.schema_pack = await effectiveSchemaPack(engine);
    const disabled = await effectiveEmbeddingDisabled(engine);
    if (disabled) effective[EMBEDDING_DISABLED_KEY] = disabled;
  } catch { /* DB plane unreadable: show the file/env values alone */ }
  const shown = { ...config } as Record<string, unknown>;
  for (const [k, e] of Object.entries(effective)) shown[k] = e.value;
  for (const [k, v] of Object.entries(shown)) {
    if (effective[k]) { console.log(`  ${k}: ${String(v)}    (${effective[k]!.note})`); continue; }
    // #575: objects interpolated into the template literal printed
    // `[object Object]` — render them as JSON instead. Sensitive keys
    // stay redacted whether the value is a string or an object.
    const display = typeof v === 'string'
      ? redactConfigValue(k, v)
      : v !== null && typeof v === 'object'
        ? (isSensitiveConfigKey(k) ? '***' : JSON.stringify(redactNestedConfig(v)))
        : v;
    console.log(`  ${k}: ${display}`);
  }
}

export { CONFIG_SUBCOMMANDS as SUBCOMMANDS } from '../cli/subcommands.ts';

const USAGE = `Usage: gbrain config [show|get|set|unset] <key> [value]
       gbrain config unset --pattern <prefix>

Subcommands:
  show                         Print the effective configuration
  get <key> [--raw]            Print one value (--raw: no secret redaction)
  set <key> <value>            Write a value. --force accepts an unknown key;
                               --coverage-override (or --yes) passes the embedding
                               coverage gate; --yes accepts a disclosure prompt;
                               chat_model/expansion_model warn when outranked (--json)
  unset <key>                  Remove one key (a model key with --file: its config.json pin)
  unset --pattern <prefix>     Remove every key under a prefix`;

export function printUsage(): void {
  console.log(USAGE);
}

export async function runConfig(engine: BrainEngine, args: string[]) {
  if (subcommandHelpRequested(args, ROUTERS.config)) { printUsage(); return; }
  const action = args[0] as (typeof CONFIG_SUBCOMMANDS)[number] | undefined;

  // The writer admin lock is reserved for `gbrain sources writer lock|unlock`; --force is no escape.
  if (action === 'set' || action === 'unset') {
    const patternAt = action === 'unset' ? args.indexOf('--pattern') : -1;
    const target = patternAt >= 0 ? args[patternAt + 1] : args.filter(a => a !== '--raw')[1];
    if (target && (patternAt >= 0 ? WRITER_ADMIN_LOCK_KEY.startsWith(target) : target === WRITER_ADMIN_LOCK_KEY)) {
      console.error(`[config] ${WRITER_ADMIN_LOCK_KEY} is reserved: only \`gbrain sources writer lock\` and \`gbrain sources writer unlock\` on the brain host change it.`);
      console.error(`[config] ${patternAt >= 0 ? `The pattern "${target}" covers that key. Nothing was deleted.` : 'Nothing was written.'}`);
      process.exit(1);
    }
  }

  if (action === 'show') {
    await showConfig(engine);
    return;
  }

  // v0.32.3 [CDX-7+8]: `unset` is required before `gbrain search modes
  // --reset` can implement its contract. Two shapes:
  //   gbrain config unset <key>             — single-key delete
  //   gbrain config unset --pattern <pfx>   — prefix-bulk delete
  if (action === 'unset') {
    const flagIdx = args.indexOf('--pattern');
    if (flagIdx !== -1) {
      const prefix = args[flagIdx + 1];
      if (!prefix || prefix.length === 0) {
        console.error('Usage: gbrain config unset --pattern <prefix>');
        process.exit(1);
      }
      const keys = (await engine.listConfigKeys(prefix)).filter(k => !k.startsWith('_internal.'));
      // Dual-plane keys matching the prefix must ALSO leave the file mirror
      // (codex re-review, this wave): a DB-only pattern delete would report
      // success while the engine-free Stop hook keeps reading the mirror's
      // enabled value — the exact bypass the single-key dual-plane branch
      // below exists to prevent. Swept even when the DB had no matching rows
      // (a previously-failed dual-write leaves the key file-only).
      const fileSwept: string[] = [];
      const dualPlaneMatches = [...MEMORY_DUAL_PLANE_KEYS, BRAIN_AUDIENCE_KEY].filter((k) => k.startsWith(prefix));
      // Mount selection never sweeps the host's machine-local mirror
      // (codex re-review) — same rule as the single-key dual-plane lanes.
      if (dualPlaneMatches.length > 0 && (await hostBrainSelected())) {
        const { loadConfigFileOnly, saveConfig } = await import('../core/config.ts');
        const cfg = loadConfigFileOnly();
        if (cfg) {
          for (const k of dualPlaneMatches) {
            if (k === BRAIN_AUDIENCE_KEY) {
              if (cfg.brain && 'audience' in cfg.brain) { delete cfg.brain.audience; fileSwept.push(k); }
            } else {
              const leaf = k.slice('memory.'.length) as (typeof MEMORY_DUAL_PLANE_LEAVES)[number];
              if (cfg.memory && leaf in cfg.memory) { delete cfg.memory[leaf]; fileSwept.push(k); }
            }
          }
          if (fileSwept.length > 0) saveConfig(cfg);
        }
      }
      if (keys.length === 0 && fileSwept.length === 0) {
        console.log(`No keys match prefix "${prefix}".`);
        return;
      }
      const deleted = await (await import('./config-line-grammar.ts')).unsetConfigKeys(engine, keys);
      console.log(`Unset ${deleted} key(s) matching "${prefix}":`);
      for (const k of keys) console.log(`  - ${k}`);
      for (const k of fileSwept) {
        if (!keys.includes(k)) console.log(`  - ${k} (file mirror)`);
      }
      if (fileSwept.length > 0) console.log(`File mirror cleared for: ${fileSwept.join(', ')}`);
      return;
    }

    const key = args[1];
    if (!key) {
      console.error('Usage: gbrain config unset <key> | --pattern <prefix>');
      process.exit(1);
    }
    if (key === EMBEDDING_DISABLED_KEY) {
      await unsetEmbeddingDisabled(engine);
      return;
    }
    if (isLegacyModelKey(key) && args.includes('--file')) return unsetModelFilePin(key);
    if (MEMORY_DUAL_PLANE_KEYS.has(key) || key === BRAIN_AUDIENCE_KEY) {
      // Dual-plane delete, mirroring the dual-plane set: file mirror AND the
      // authoritative DB row both go. "Not found" only when neither had it.
      const { loadConfigFileOnly, saveConfig } = await import('../core/config.ts');
      const cfg = loadConfigFileOnly();
      let fileHad = false;
      // Mount selection never touches the host's machine-local mirror —
      // same rule as the dual-plane set lane (codex re-review).
      if (await hostBrainSelected()) {
        if (key === BRAIN_AUDIENCE_KEY) {
          if (cfg?.brain && 'audience' in cfg.brain) {
            delete cfg.brain.audience;
            saveConfig(cfg);
            fileHad = true;
          }
        } else {
          const leaf = key.slice('memory.'.length) as (typeof MEMORY_DUAL_PLANE_LEAVES)[number];
          if (cfg?.memory && leaf in cfg.memory) {
            delete cfg.memory[leaf];
            saveConfig(cfg);
            fileHad = true;
          }
        }
      }
      let dbDeleted = 0;
      try {
        dbDeleted = await engine.unsetConfig(key);
      } catch (e) {
        // Same posture as the dual-plane set lane (adversarial review, this
        // wave): the DB row is the authoritative runtime value — a failed
        // delete after the file delete succeeded means the revocation did
        // NOT take effect, so say it and exit non-zero instead of a raw
        // stack (or worse, a success line).
        console.error(`[config] ERROR: file plane cleared but the DB-plane delete failed (${e instanceof Error ? e.message : String(e)}).`);
        console.error(`[config] The authoritative runtime value is UNCHANGED — re-run this command once the database is reachable.`);
        process.exit(1);
      }
      if (fileHad || dbDeleted > 0) {
        console.log(`Unset ${key} (${[fileHad ? 'file plane' : null, dbDeleted > 0 ? 'db plane' : null].filter(Boolean).join(' + ')})`);
        if (key === 'memory.auto_writeback') {
          for (const line of (await import('../core/facts/writeback-config.ts')).writebackUnsetMessage()) console.log(line);
        }
      } else {
        console.error(`Config key not found: ${key}`);
        process.exit(1);
      }
      return;
    }
    if (isFilePlaneDottedKey(key)) {
      const fileHad = await unsetFilePlaneKey(key);
      const dbDeleted = await dropStaleDbRow(engine, key);
      if (fileHad || dbDeleted > 0) {
        console.log(`Unset ${key} (${[fileHad ? 'file plane' : null, dbDeleted > 0 ? 'stale db-plane row' : null].filter(Boolean).join(' + ')})`);
        if (key === `${SELF_UPGRADE_KEY_PREFIX}mode`) warnSelfUpgradeModeEnvOverride();
      } else {
        console.error(`Config key not found: ${key}`);
        process.exit(1);
      }
      return;
    }
    if (key === 'integrations.memorable.enabled') {
      // File-plane like `set` (the gate's readers are engine-free hook
      // children) — the pre-fix fall-through hit the DB plane, printed
      // "Config key not found", and left the file-plane `true` active.
      // Unset is a REVOCATION: the consent stamp goes with the flag.
      const { loadConfigFileOnly, saveConfig } = await import('../core/config.ts');
      const hb = await import('../core/context/hook-heartbeat.ts');
      const cfg = loadConfigFileOnly();
      const memorable = cfg?.integrations?.memorable as Record<string, unknown> | undefined;
      await hb.clearMemorableConsent();
      if (cfg && memorable && 'enabled' in memorable) {
        delete memorable.enabled;
        saveConfig(cfg);
        console.log(`Unset ${key} (file plane) — disclosure consent revoked`);
      } else {
        // The stamp was still cleared above — deliberate: the CLI's full-file
        // config rewrites can drop the flag while the stamp survives, and an
        // orphaned stamp would let a later out-of-band re-enable skip the
        // disclosure. Unset always revokes; say so even on the miss.
        console.error(`Config key not found: ${key} (disclosure consent revoked regardless)`);
        process.exit(1);
      }
      return;
    }
    if (FILE_PLANE_API_KEYS.includes(key)) {
      const { loadConfigFileOnly, saveConfig } = await import('../core/config.ts');
      const cfg = loadConfigFileOnly() as unknown as Record<string, unknown> | null;
      if (cfg && key in cfg) {
        delete cfg[key];
        saveConfig(cfg as unknown as Parameters<typeof saveConfig>[0]);
        console.log(`Unset ${key} (file plane)`);
      } else {
        console.error(`Config key not found: ${key}`);
        process.exit(1);
      }
      return;
    }
    const n = await (await import('./config-line-grammar.ts')).unsetConfigKeys(engine, [key], { single: true });
    if (n > 0) {
      console.log(`Unset ${key}${key === 'auto_chronicle' ? AUTO_CHRONICLE_UNSET_NOTE : ''}`);
      if (key === 'facts.default_visibility') await restampVisibilityPosture(null);
    } else {
      console.error(`Config key not found: ${key}`);
      process.exit(1);
    }
    return;
  }

  // #3943: `--raw` (get's redaction opt-out) may appear before the key, so
  // strip it from the positional scan rather than reading args[1] blindly.
  const rawFlag = args.includes('--raw');
  const positionals = args.filter((a) => a !== '--raw');
  const key = positionals[1];
  const value = positionals[2];
  if ((action === 'get' || action === 'set') && key) (await import('../core/questions/auto-think-migration.ts')).noteAutoThinkReplacement(key);
  if ((action === 'get' || action === 'set') && key && await (await import('../core/sync-config-keys.ts')).handleSyncKeyConfig(engine, action, key)) return; // #6712 PR 2

  if (action === 'get' && (key === EMBEDDING_DISABLED_KEY || key === 'schema_pack')) {
    const effective = key === 'schema_pack' ? await effectiveSchemaPack(engine) : await effectiveEmbeddingDisabled(engine);
    if (!effective) {
      console.error(`Config key not found: ${key}`);
      process.exit(1);
    }
    console.log(String(effective.value));
    console.error(`[config] source: ${effective.note}`);
    return;
  }
  if (action === 'get' && key) {
    // #2120: `get` used to read only the DB plane, so a runtime-effective key
    // in ~/.gbrain/config.json (or env) reported not-found. Resolve the way
    // the runtime does — env/file plane wins over DB (loadConfig() already
    // overlays env onto the file) — and report which plane answered on
    // stderr, keeping stdout a bare value for scripts.
    if (key === 'mcp.publish_wakeshift') return (await import('./wakeshift.ts')).printWakeshiftGate();
    const filePlane = loadConfig() as Record<string, unknown> | null;
    // Dotted keys (push.allow_unverified_remote, hooks.stop_push_debounce_min)
    // are stored NESTED by `set`; resolve the path so `get`/`unset` see them.
    const resolveDotted = (obj: Record<string, unknown> | null, k: string): unknown => {
      if (!obj) return undefined;
      if (k in obj) return obj[k];
      return k.split('.').reduce<unknown>((acc, seg) => (acc && typeof acc === 'object' ? (acc as Record<string, unknown>)[seg] : undefined), obj);
    };
    const fileVal = resolveDotted(filePlane, key);
    const dbVal = await engine.getConfig(key);
    // Dual-plane ambient-writeback keys are DB-AUTHORITATIVE at runtime
    // (adversarial review, this wave): reporting the file mirror here after
    // a failed dual-write would show 'off' while every runtime surface still
    // serves the previous DB value — exactly the lie the off switch's
    // non-zero exit exists to prevent. Everything else keeps the #2120
    // file/env-wins resolution.
    // Publish-gate keys (#5358) are DB-authoritative too: readPublishGate
    // resolves DB > file, so a file-first answer would print a stale mirror
    // while the gate already hides the tools.
    const dbAuthoritative = MEMORY_DUAL_PLANE_KEYS.has(key) || key === BRAIN_AUDIENCE_KEY || (PUBLISH_GATE_KEYS as ReadonlySet<string>).has(key);
    // File-plane keys have no DB reader: a DB row is a stale pre-routing
    // write, never the answer (#5489).
    const fileOnly = isFilePlaneDottedKey(key);
    const hasStaleDbRow = fileOnly && dbVal !== null && dbVal !== undefined;
    const val = dbAuthoritative
      ? (dbVal ?? fileVal)
      : fileOnly
        ? fileVal
        : (fileVal !== undefined && fileVal !== null ? fileVal : dbVal);
    if (key === 'memory.agent_writeback' && (val === null || val === undefined)) return (await import('./config-agent-writeback.ts')).printUnsetAgentWriteback(engine);
    if (val !== null && val !== undefined) {
      // #3943: redact by default like `show`/`set` — `get` output lands in
      // agent transcripts and shell history; scripts opt out with the flag.
      const out = typeof val === 'string' ? val : JSON.stringify(rawFlag ? val : redactNestedConfig(val));
      console.log(rawFlag ? out : redactConfigValue(key, out));
      if (dbAuthoritative) {
        console.error(`[config] source: ${dbVal !== null && dbVal !== undefined ? 'db plane (authoritative for this key)' : 'file mirror (no DB row)'}${await writebackLanesNote(engine, key)}`);
        if (dbVal !== null && dbVal !== undefined && fileVal !== undefined && fileVal !== null && String(fileVal) !== String(dbVal)) {
          console.error(`[config] WARN: file mirror disagrees ('${String(fileVal)}') — planes diverged; re-run: gbrain config set ${key} ${String(dbVal)}`);
        }
      } else if (fileVal !== undefined && fileVal !== null) {
        const shadow = hasStaleDbRow
          ? ` — a stale DB-plane row also exists and nothing reads it (gbrain config unset ${key} removes it)`
          : dbVal !== null && dbVal !== undefined
            ? ' — a DB-plane value also exists and is shadowed at runtime'
            : '';
        console.error(`[config] source: file/env plane (~/.gbrain/config.json or env)${shadow}`);
      } else {
        console.error(`[config] source: db plane`);
      }
    } else {
      if (hasStaleDbRow) {
        console.error(`[config] a stale DB-plane row holds '${redactConfigValue(key, String(dbVal))}', but nothing reads it; the runtime default applies. Remove it: gbrain config unset ${key}`);
      }
      console.error(`Config key not found: ${key}`);
      process.exit(1);
    }
  } else if (action === 'set' && key && value) {
    // #3661: `config set` dropped flags it does not implement and wrote
    // anyway. `--dry-run` — honored by sync/import/extract/quarantine/pages —
    // printed the usual "Set <key> = <value>" confirmation and persisted the
    // mutation, so a caller probing a value silently changed live config.
    // Unknown flags are now refused BEFORE any validation or write runs —
    // regardless of whether they land after the value
    // (`config set <key> <value> --dry-run`) or before it
    // (`config set <key> --dry-run <value>`). Scan every token after the
    // key and resolve the value as the first non-flag one, so a flag
    // sitting in the value slot can't slip through as literal config
    // content.
    const tail = args.slice(2);
    const unknownFlags = tail.filter(a => a.startsWith('-') && !CONFIG_SET_KNOWN_FLAGS.includes(a) && !(a === '--json' && isLegacyModelKey(key)));
    if (unknownFlags.length > 0) {
      for (const flag of unknownFlags) {
        console.error(`[config] unknown flag: ${flag}`);
      }
      console.error(`[config] \`gbrain config set\` accepts: ${CONFIG_SET_KNOWN_FLAGS.join(', ')}.`);
      console.error(`[config] Nothing was written.`);
      process.exit(1);
    }
    const value = tail.find(a => !a.startsWith('-')) ?? args[2];

    // Bootstrap hook-lane keys are FILE-plane canonical: they are read by
    // engine-free processes (the harness hook children and the detached
    // `sources push` child) via loadConfigFileOnly, which never sees the DB
    // plane — and the DB plane is unreadable anyway while a `gbrain serve`
    // holds the single-writer lock. Route them to ~/.gbrain/config.json.
    // `integrations.memorable.enabled` is deliberately NOT in
    // FILE_PLANE_DOTTED_KEYS: that set is shared with the UNSET lane, where
    // the generic file-plane branch would swallow the key before its
    // dedicated branch below — which must win, because unset is a consent
    // REVOCATION (it clears the disclosure stamp, not just the flag).
    // Ambient-writeback keys DUAL-WRITE (OV2-5): file mirror first (the
    // engine-free readers' plane), then the authoritative DB row. A DB
    // failure leaves the planes briefly diverged — reported, not hidden.
    if (key === EMBEDDING_DISABLED_KEY) return setEmbeddingDisabled(engine, value);
    if (key === BRAIN_AUDIENCE_KEY) {
      // Dual-plane like memory.* (WP8): the engine-free harness lane gates
      // its enable-nudge advisory on the file-plane declared audience.
      const { loadConfigFileOnly, saveConfig } = await import('../core/config.ts');
      const cfg = (loadConfigFileOnly() ?? { engine: 'pglite' }) as Parameters<typeof saveConfig>[0];
      const audience = value.trim().toLowerCase();
      if (audience !== 'personal' && audience !== 'shared') {
        console.error(`[config] ${key} must be personal | shared (got '${value}'). Nothing was written.`);
        process.exit(1);
      }
      const hostPlane = await hostBrainSelected();
      if (hostPlane) {
        cfg.brain = { ...(cfg.brain ?? {}), audience };
        saveConfig(cfg);
      } else {
        console.log(`[config] mounted brain selected — the machine-local mirror belongs to the host brain and is untouched (DB row only).`);
      }
      try {
        await engine.setConfig(key, audience);
      } catch (e) {
        // Non-zero exit (adversarial review, this wave): the DB plane is
        // authoritative for engine-backed readers — reporting success here
        // would let `config get` show the file value while runtime
        // classification still reads the old declaration.
        console.error(`[config] ERROR: ${hostPlane ? 'file plane written but ' : ''}the DB-plane write failed (${e instanceof Error ? e.message : String(e)}).`);
        console.error(`[config] The authoritative runtime value is UNCHANGED — re-run this command once the database is reachable.`);
        process.exit(1);
      }
      console.log(`Set ${key} = ${audience} (${hostPlane ? 'file + db planes' : 'db plane only — mounted brain'})`);
      return (await import('./archive-rescope.ts')).rescopeArchiveAfter(engine);
    }
    if (key === 'memory.agent_writeback') return (await import('./config-agent-writeback.ts')).setAgentWritebackFromCli(engine, value);
    if (MEMORY_DUAL_PLANE_KEYS.has(key)) {
      const { loadConfigFileOnly, saveConfig } = await import('../core/config.ts');
      const cfg = (loadConfigFileOnly() ?? { engine: 'pglite' }) as Parameters<typeof saveConfig>[0];
      let normalized: string;
      if (key === 'memory.auto_writeback') {
        const { WRITEBACK_MODES } = await import('../core/facts/writeback-config.ts');
        normalized = value.trim().toLowerCase();
        if (!(WRITEBACK_MODES as readonly string[]).includes(normalized)) {
          console.error(`[config] ${key} must be one of: ${WRITEBACK_MODES.join(' | ')} (got '${value}'). Nothing was written.`);
          process.exit(1);
        }
        // WP8: on a shared-classified brain, enabling ambient capture gets a
        // caution (members' words get persisted) — never a refusal.
        if (normalized !== 'off') {
          try {
            const { classifyBrainAudience } = await import('../core/facts/writeback-audience.ts');
            const audience = await classifyBrainAudience(engine, cfg);
            if (audience.audience === 'shared') {
              console.error('[config] CAUTION: this brain looks like a company/team brain (' + audience.reasons.join('; ') + ').');
              console.error('[config] Ambient writeback persists what people say to agents on this brain into a store other');
              console.error('[config] authorized agents can read. Check `facts.default_visibility` and your ACCESS_POLICY.md');
              console.error('[config] before relying on it. Proceeding as requested.');
            }
          } catch { /* classifier is advisory — never blocks an explicit set */ }
        }
      } else {
        // Same predicate as the resolver's degrade path — ONE home in
        // ttl-parse.ts so config-set rejection and runtime fallback agree.
        const { isValidTransientTtl } = await import('../core/facts/ttl-parse.ts');
        normalized = value.trim();
        if (!isValidTransientTtl(normalized)) {
          console.error(`[config] ${key} must be a positive duration shorthand no longer than 365d (e.g. '3d', '12h'; got '${value}'). Nothing was written.`);
          process.exit(1);
        }
      }
      // Stamp the resolved visibility POSTURE into the mirror while we hold
      // an engine: the engine-free bootstrap-harness renderer embeds it in
      // the managed instruction block. A failed read keeps any prior stamp;
      // with NO prior stamp it fail-closes to 'private' — the file resolver
      // defaults an ABSENT stamp to 'world' (F5's readable-unset rule), so
      // leaving it absent here would let a transient blip on an explicitly
      // private brain render world-widening instructions (codex re-review,
      // this wave). A wrongly-private stamp on a world brain only costs a
      // doctor drift warn; the reverse widens facts.
      let posture: string | undefined = cfg.memory?.visibility_posture;
      try {
        const { visibilityPostureFromRaw } = await import('../core/facts/writeback-config.ts');
        posture = visibilityPostureFromRaw(await engine.getConfig('facts.default_visibility')).visibility;
      } catch {
        posture = posture ?? 'private';
      }
      const hostPlane = await hostBrainSelected();
      if (hostPlane) {
        cfg.memory = {
          ...(cfg.memory ?? {}),
          [key.slice('memory.'.length)]: normalized,
          ...(posture ? { visibility_posture: posture } : {}),
        };
        saveConfig(cfg);
      } else {
        // The mirror gates the HOST's engine-free Stop hook — enabling a
        // mount must not opt the host's conversations into banking.
        console.log(`[config] mounted brain selected — the machine-local mirror belongs to the host brain and is untouched (DB row only; the mount's serve reads the DB plane).`);
      }
      try {
        await engine.setConfig(key, normalized);
      } catch (e) {
        // Non-zero exit (adversarial review, this wave): the serve-side gate
        // and the instruction lanes read the DB plane — exiting 0 here would
        // report an off switch as flipped while every runtime surface still
        // serves the PREVIOUS value, and `config get` (file plane) would
        // corroborate the lie. Loud failure is the only honest outcome.
        console.error(`[config] ERROR: ${hostPlane ? 'file plane written but ' : ''}the DB-plane write failed (${e instanceof Error ? e.message : String(e)}).`);
        console.error(`[config] The authoritative runtime value is UNCHANGED (still the previous DB value) — re-run this command once the database is reachable.`);
        process.exit(1);
      }
      console.log(`Set ${key} = ${normalized} (${hostPlane ? 'file + db planes' : 'db plane only — mounted brain'})`);
      if (key === 'memory.auto_writeback' && normalized !== 'off') {
        console.log('Ambient writeback enabled. Running stdio serves pick it up on restart; HTTP serves on the next request.');
        console.log('To install the managed harness instruction blocks: gbrain bootstrap harness --yes');
      }
      if (key === 'memory.auto_writeback' && normalized === 'off') {
        // The off switch gates instructions + extraction immediately, but
        // previously-installed harness instruction blocks keep directing new
        // sessions until converged — say so (red-team review, this wave).
        for (const line of (await import('../core/facts/writeback-config.ts')).writebackOffMessage()) console.log(line);
      }
      return;
    }
    if (isFilePlaneDottedKey(key) || key === 'integrations.memorable.enabled') {
      await setFilePlaneKey(key, value, tail);
      if (isFilePlaneDottedKey(key) && (await dropStaleDbRow(engine, key)) > 0) {
        console.log(`Removed a stale DB-plane row for ${key} (an earlier \`config set\` wrote it there; nothing reads it).`);
      }
      return;
    }
    // DB-connection keys route to the file plane (or refuse, for `engine`) —
    // single home in handleDbPlaneRoutedKeys, shared with the engine-free
    // pre-connectEngine dispatch.
    if (await handleDbPlaneRoutedKeys(key, value)) return;

    // Vendor credentials are file-plane canonical (see FILE_PLANE_API_KEYS).
    // Routed, not refused: unlike embedding_model there is nothing to re-init,
    // so the user's intent is satisfiable exactly as typed.
    if (FILE_PLANE_API_KEYS.includes(key)) {
      const { loadConfigFileOnly, saveConfig } = await import('../core/config.ts');
      const cfg = (loadConfigFileOnly() ?? { engine: 'pglite' }) as Parameters<typeof saveConfig>[0];
      (cfg as unknown as Record<string, unknown>)[key] = value;
      saveConfig(cfg);
      // #892: redact — the raw secret must not reach scrollback or shell history.
      console.log(`Set ${key} = ${redactConfigValue(key, value)} (file plane: ~/.gbrain/config.json)`);
      return;
    }

    // v0.37.11.0 fix wave (Lane C.2 + CDX2-13): refuse writes to schema-sizing
    // fields unconditionally. These fields size the `content_chunks.embedding`
    // column at init time and are file-plane canonical. `gbrain config set
    // embedding_model X` writes the DB plane, which the embed pipeline
    // never reads — silent lie that took users hours to diagnose.
    //
    // No `--force` escape hatch (CDX2-13): keeping a known-no-op DB-only
    // write preserves the split-brain footgun the wave exists to close.
    if (key === 'embedding_model' || key === 'embedding_dimensions') await refuseSchemaSizingKey(key, value);

    // v0.37.10.0 (D6): strict unknown-key rejection with --force escape hatch.
    // Catches the silent-no-op class for namespaced typos like `embedding.provider`,
    // `embedding.model`, `embedding.dimensions` — Levenshtein suggests the canonical
    // key (`embedding_model`, `embedding_dimensions`) when one is within edit
    // distance ≤ 3, after which the v0.37.11.0 hard-refuse above kicks in for those
    // specific schema-sizing fields.
    const forceFlag = args.includes('--force');
    if (!forceFlag) {
      const { KNOWN_CONFIG_KEYS, KNOWN_CONFIG_KEY_PREFIXES } = await import('../core/config.ts');
      const isKnown = KNOWN_CONFIG_KEYS.includes(key);
      const matchesPrefix = KNOWN_CONFIG_KEY_PREFIXES.some(p => key.startsWith(p));
      if (!isKnown && !matchesPrefix) {
        console.error(`[config] Unknown config key "${key}".`);
        // #3748: `budget.*` (e.g. budget.daily_cap_usd) appeared once in old
        // release notes but was never registered and has NO readers — a
        // --force write would set a "cap" that caps nothing, which for a
        // spend control is worse than a rejection. Route the operator to the
        // controls that actually exist.
        if (key === 'budget' || key.startsWith('budget.')) {
          console.error(`[config] budget.* keys are not live controls — nothing in gbrain reads them, so a cap written here caps nothing.`);
          console.error(`[config] The live spend controls are \`gbrain config set spend.posture <gated|tokenmax>\` and the per-command gates in docs/operations/spend-controls.md.`);
        } else {
          const { suggestNearest } = await import('../core/levenshtein.ts');
          const suggestion = suggestNearest(key, KNOWN_CONFIG_KEYS, 3);
          if (suggestion) {
            console.error(`[config] Did you mean "${suggestion}"?`);
          } else {
            console.error(`[config] No similar known key. Run \`gbrain config show\` to see currently-set keys.`);
          }
        }
        console.error(`[config] If this is intentional (downstream tooling, forward-compat), re-run with --force.`);
        process.exit(1);
      }
    } else {
      // --force: accept but warn loudly so the user sees what they're doing.
      const { KNOWN_CONFIG_KEYS, KNOWN_CONFIG_KEY_PREFIXES } = await import('../core/config.ts');
      const isKnown = KNOWN_CONFIG_KEYS.includes(key);
      const matchesPrefix = KNOWN_CONFIG_KEY_PREFIXES.some(p => key.startsWith(p));
      if (!isKnown && !matchesPrefix) {
        console.error(`[config] WARN: writing unknown key "${key}" with --force. Nothing in gbrain reads this.`);
        if (key === 'budget' || key.startsWith('budget.')) {
          // #3748: an operator who believes this caps spend has NO cap at all.
          console.error(`[config] WARN: budget.* is NOT a spend cap — the live controls are spend.posture + docs/operations/spend-controls.md.`);
        }
      }
    }

    // v0.36 (D12 + D14): validate embedding-column keys at set time so a
    // bad config gets rejected loud + early. The `--coverage-override`
    // flag lets the user proceed past the < 90% gate when they know
    // they're mid-backfill.
    const coverageOverride =
      args.includes('--coverage-override') || args.includes('--yes');

    // #6290: provider_chat_options rows are one JSON object per selector; a dotted leaf would be inert.
    if (key.startsWith('provider_chat_options.')) await import('../core/config-db-merge.ts').then(m => m.assertProviderChatOptionsSetValue(key, value)).catch((error: Error) => { console.error(`[config] ${error.message}`); process.exit(1); });
    // #5470: every admission parses the journal caps; a malformed value
    // would refuse all managed writes, so reject it here.
    const { JOURNAL_CONFIG_KEYS, UPLOAD_CONFIG_KEYS, parseJournalConfigValue } = await import('../core/persistence/limits.ts');
    if (JOURNAL_CONFIG_KEYS.includes(key) || UPLOAD_CONFIG_KEYS.includes(key)) {
      try { parseJournalConfigValue(key, value); }
      catch (error) { console.error(`[config] ${(error as Error).message}`); process.exit(1); }
    }

    // Core memory and pressure keys are read on every session/turn; reject bad values here.
    if (key.startsWith('memory.core.') || key.startsWith('memory.pressure.')) {
      const { validateCoreConfigValue } = await import('../core/core-memory.ts');
      const { validatePressureConfigValue } = await import('../core/context/pressure.ts');
      const problem = validateCoreConfigValue(key, value) ?? validatePressureConfigValue(key, value);
      if (problem) { console.error(`[config] ${problem} Nothing was written.`); process.exit(1); }
    }

    // The shared-skills migration reads these bounds on every run; refuse a malformed or over-ceiling value.
    const { INVENTORY_LIMIT_KEYS, parseInventoryLimitValue } = await import('../core/shared-skills/inventory-limits.ts');
    if (INVENTORY_LIMIT_KEYS.includes(key)) {
      try { parseInventoryLimitValue(key, value); }
      catch (error) { (await import('../cli/cli-error.ts')).exitCliError(error, 'config'); }
    }

    // #4907: a phase knob the phase would ignore is refused before the write.
    const [{ PHASE_CONFIG_KEYS, parsePhaseConfigValue }, { CYCLE_GUARDED_KEYS, assertCycleConfigValue }] = await Promise.all([import('../core/cycle/phase-config-values.ts'), import('../core/cycle/config-guards.ts')]);
    if (PHASE_CONFIG_KEYS.includes(key) || CYCLE_GUARDED_KEYS.includes(key)) { // #6134/#6177: lint_exclude paths, the last_run state key
      try { if (PHASE_CONFIG_KEYS.includes(key)) parsePhaseConfigValue(key, value); else assertCycleConfigValue(key, value); }
      catch (error) { (await import('../cli/cli-error.ts')).exitCliError(error, 'config'); }
    }

    // #5254: an unknown value would silently keep refusing unbound writes.
    const { UNBOUND_WRITE_KEY, parseUnboundWriteValue } = await import('../core/persistence/unbound-source.ts');
    if (key === UNBOUND_WRITE_KEY) {
      try { parseUnboundWriteValue(value); }
      catch (error) { console.error(`[config] ${(error as Error).message}`); process.exit(1); }
    }

    // #4348: validate cycle.timezone at set time — resolveCycleDate falls
    // back loudly at run time, but the typo should be rejected here, at the
    // moment the operator can fix it.
    if (key === 'cycle.timezone' || key === 'brain.timezone') {
      const { isValidTimeZone } = await import('../core/cycle/cycle-date.ts');
      if (!isValidTimeZone(value)) {
        console.error(
          `[config] ${key} must be a valid IANA timezone ` +
          `(for example Asia/Kolkata or America/Los_Angeles; got '${value}').`,
        );
        process.exit(1);
      }
    }

    // #5363: the consolidate phase falls back to 0.85 on a malformed value;
    // refuse it here, where the operator can fix it.
    if (key === 'cycle.consolidate.cluster_threshold') {
      const { parseClusterThreshold } = await import('../core/cycle/phases/consolidate.ts');
      try { parseClusterThreshold(value); }
      catch (error) { console.error(`[config] ${(error as Error).message}`); process.exit(1); }
    }

    // #5461: think falls back to the default budget on a malformed value (and warns); refuse it here.
    if (key === 'think.pages_budget_chars' || key === 'think.excerpt_ceiling_chars') {
      const { pagesBudgetConfigError } = await import('../core/think/pages-budget.ts');
      const error = pagesBudgetConfigError(key, value);
      if (error) { console.error(`[config] ${error}`); process.exit(1); }
    }

    // Validate sources.default at set time. This key is read by
    // source-resolver.ts tier 5 on EVERY unqualified call, and tier 5 calls
    // assertSourceExists — so a syntactically valid but non-existent id set
    // here would make every later unqualified command throw, far from the
    // typo that caused it. `gbrain sources default <id>` already validates;
    // config set is the lower-level door to the same key and must not be a
    // way around that check.
    if (key === 'sources.default') {
      const { isValidSourceId } = await import('../core/source-id.ts');
      if (!isValidSourceId(value)) {
        console.error(
          `[config] sources.default must be 1-32 lowercase alphanumerics with ` +
          `optional interior hyphens (got '${value}').\n` +
          `[config]   gbrain sources default <id>   # preferred — validates and reports`,
        );
        process.exit(1);
      }
      // No .catch() here: a connection failure or SQL regression must NOT be
      // reported as "source is not registered". fetchSource already absorbs
      // the one expected legacy-column case; anything else is a real error and
      // should surface as itself.
      const { fetchSource } = await import('../core/sources-load.ts');
      const src = await fetchSource(engine, value);
      if (!src) {
        // NOTE: keep flag literals out of this message. The generated flag
        // registry (#2185) scans command sources for flag tokens, so naming a
        // flag in prose would silently grant it to `gbrain config`.
        console.error(
          `[config] source "${value}" is not registered; refusing to set sources.default.\n` +
          `[config]   gbrain sources list      # see registered sources\n` +
          `[config]   gbrain sources add       # register one first`,
        );
        process.exit(1);
      }
    }

    // v0.42.42.0 (#2139): validate spend.posture at set time so a typo
    // ('tokenMax', 'max') doesn't silently fall back to gated.
    if (key === 'spend.posture') {
      const { isValidSpendPosture } = await import('../core/spend-posture.ts');
      if (!isValidSpendPosture(value)) {
        console.error(
          `[config] spend.posture must be 'gated' or 'tokenmax' (got '${value}').\n` +
          `[config]   gbrain config set spend.posture tokenmax   # cost gates become informational\n` +
          `[config]   gbrain config set spend.posture gated       # default — gates enforce`,
        );
        process.exit(1);
      }
    }

    if (key === 'embedding_columns') {
      try {
        const parsed = JSON.parse(value);
        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
          throw new Error('embedding_columns must be a JSON object');
        }
        // D12: validate every key + entry shape before persisting.
        for (const [k, entry] of Object.entries(parsed)) {
          validateColumnKey(k);
          validateColumnConfig(k, entry);
        }
      } catch (err) {
        if (err instanceof EmbeddingColumnConfigError) {
          console.error(`[config] ${err.message}`);
        } else {
          console.error(
            `[config] embedding_columns rejected: ${(err as Error).message}`,
          );
          console.error(
            `[config] Expected JSON shape: {"<column_name>": {"provider": "...", "dimensions": N, "type": "vector" | "halfvec"}, ...}`,
          );
        }
        process.exit(1);
      }
    }

    if (key === 'search_embedding_column') {
      // Validate against the merged registry (file + DB plane + builtins).
      // We re-read merged config so a prior `gbrain config set
      // embedding_columns ...` is visible.
      const fileCfg = loadConfig();
      const mergedCfg = fileCfg
        ? await loadConfigWithEngine(engine, fileCfg).catch(() => fileCfg)
        : null;
      if (mergedCfg) {
        let registry: ReturnType<typeof getEmbeddingColumnRegistry>;
        try {
          registry = getEmbeddingColumnRegistry(mergedCfg);
        } catch (err) {
          console.error(
            `[config] Existing embedding_columns is invalid; refusing to set search_embedding_column. ` +
              `Fix the registry first. (${(err as Error).message})`,
          );
          process.exit(1);
        }
        // Object.hasOwn so inherited keys ('constructor', 'toString', etc.)
        // cannot pass the registry-lookup gate.
        if (!Object.hasOwn(registry, value)) {
          const known = Object.keys(registry).sort().join(', ') || '(none)';
          console.error(
            `[config] Unknown embedding column "${value}". ` +
              `Declared columns: ${known}. ` +
              `Add it via: gbrain config set embedding_columns '<JSON>'`,
          );
          process.exit(1);
        }

        // D14 coverage gate. Probe the column's NULL-rate; refuse when
        // coverage < 90% unless `--coverage-override` or `--yes` is
        // present.
        try {
          const covRows = await engine.executeRaw<{ pct: number; total: number }>(
            `SELECT (
               COUNT(*) FILTER (WHERE ${quoteIdentifier(value)} IS NOT NULL)::float
               / NULLIF(COUNT(*), 0) * 100
             )::float AS pct,
             COUNT(*)::int AS total
             FROM content_chunks`,
          );
          const pct = covRows[0]?.pct ?? 0;
          const total = covRows[0]?.total ?? 0;
          if (total > 0 && pct < 90 && !coverageOverride) {
            console.error(
              `[config] Column "${value}" is ${pct.toFixed(1)}% populated (${total} total chunks).`,
            );
            console.error(
              `[config] Switching the default to a low-coverage column silently degrades search.`,
            );
            console.error(
              `[config] Ask the user first; to switch anyway, pass --coverage-override:`,
            );
            console.error(
              `[config]   gbrain config set search_embedding_column ${value} --coverage-override`,
            );
            process.exit(1);
          }
        } catch (err) {
          // Coverage probe failure shouldn't block when the column shape
          // is otherwise valid (e.g. the column was JUST added, no chunks
          // yet, NULLIF guard returns NULL → pct=0 BUT total=0 short-
          // circuits above). If the SQL itself errors (column ALTER race,
          // permission), warn but proceed.
          console.error(
            `[config] WARN: coverage probe failed (${(err as Error).message}); proceeding.`,
          );
        }
      }
    }

    // v0.40.3.0 (D3 + Phase 2B): capture the OLD search.mode BEFORE the
    // setConfig so summarizeTransition() can classify the kind correctly.
    // Read fails silently → oldMode null → treated as broadening.
    let oldSearchMode: string | null = null;
    if (key === 'search.mode') {
      try {
        oldSearchMode = await engine.getConfig('search.mode');
      } catch {
        // ignore — null is the correct "never seen" semantic.
      }
    }

    await setConfigWithDecideHooks(engine, key, value, forceFlag);
    // #892: keep credentials out of confirmation output and scrollback. #6795: a model pin says whether it took effect.
    if (isLegacyModelKey(key)) await reportLegacyModelWrite(engine, key, value, tail.includes('--json'));
    else console.log(`Set ${key} = ${redactConfigValue(key, value)}`);
    if (key === 'facts.default_visibility') await restampVisibilityPosture(value);

    // v0.40.3.0 (D3 + Phase 2B): mode-switch UX. Fires only on
    // search.mode writes. Honors GBRAIN_NO_MODE_SWITCH_UX=1 + non-TTY.
    // The hook is best-effort — UX failures must NEVER break a config
    // set that already persisted.
    if (key === 'search.mode') {
      try {
        const [{ runModeSwitchUx }, { isSearchMode }] = await Promise.all([import('../core/search/mode-switch-ux.ts'), import('../core/search/mode.ts')]);
        if (isSearchMode(value)) await engine.setConfig('search.mode_source', 'operator');
        await runModeSwitchUx({
          oldMode: oldSearchMode && isSearchMode(oldSearchMode) ? oldSearchMode : null,
          newMode: value,
          engine,
          isTty: Boolean(process.stdout.isTTY && process.stdin.isTTY),
          // CLI doesn't thread --yes here today; --yes would skip the
          // prompt and print the preview command (it never spends).
          yesFlag: false,
        });
      } catch (err) {
        console.error(`[mode-switch] UX hook failed (non-fatal): ${(err as Error).message}`);
      }
    }
  } else {
    console.error(USAGE);
    process.exit(1);
  }
}

/**
 * `config set embedding_model|embedding_dimensions` is refused (a DB-plane
 * write is a silent no-op). The recipe comes from readiness (A7): enabling is
 * in place and keeps pages and DB-only facts; switching an active model is a
 * previewed migration. Never a wipe.
 */
async function refuseSchemaSizingKey(key: 'embedding_model' | 'embedding_dimensions', value: string): Promise<never> {
  const { loadConfig } = await import('../core/config.ts');
  const { embeddingEnablement } = await import('../core/readiness.ts');
  const { shellQuote } = await import('../core/agent-output.ts');
  const cfg = loadConfig() ?? ({ engine: 'pglite' } as GBrainConfig);
  const requested = key === 'embedding_model' ? { embedding_model: value } : { embedding_dimensions: Number(value) };
  const active = !cfg.embedding_disabled ? cfg.embedding_model?.trim() : undefined;
  console.error(`[config] ${key} is a file-plane field that sizes the schema.`);
  console.error(`[config] Setting it in the DB has no effect on the embed pipeline (silent no-op).`);
  console.error(`[config]`);
  if (active) {
    const to = key === 'embedding_model' ? value : active;
    const dim = key === 'embedding_dimensions' ? ['--dim', value] : [];
    console.error(`[config] This brain already embeds with ${active}. Switching is a re-embed migration (pages and facts are kept); preview it first:`);
    console.error(`[config]   ${shellQuote(['gbrain', 'migrate', 'embeddings', '--to', to, ...dim, '--dry-run'])}`);
  } else {
    const fix = embeddingEnablement({ ...cfg, ...requested } as GBrainConfig);
    console.error(`[config] To turn embeddings on in place:`);
    if (fix.argv) console.error(`[config]   ${shellQuote(fix.argv)}`);
    console.error(`[config] ${fix.why}`);
    for (const input of fix.inputs ?? []) console.error(`[config] Needs ${input.name}: ${input.how}`);
  }
  console.error(`[config]`);
  console.error(`[config] No --force escape: silently writing a no-op preserves the bug class this rejection closes.`);
  process.exit(1);
}

/** #6091: the per-lane effective state of `memory.auto_writeback`, appended to `config get`'s stderr source line. */
async function writebackLanesNote(engine: BrainEngine, key: string): Promise<string> {
  if (key !== 'memory.auto_writeback') return '';
  const { captureLaneSummary, resolveWritebackConfig } = await import('../core/facts/writeback-config.ts');
  return `; capture lanes: ${captureLaneSummary(await resolveWritebackConfig(engine, loadConfig(), { gate: true }))}${await (await import('./config-agent-writeback.ts')).agentWritebackNote(engine)}`;
}