@nexus-cortex/core 4.93.0 → 4.95.0

package/dist/config/SettingsLoader.js

@@ -8,7 +8,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import { fileURLToPath } from 'url';
-import { DEFAULT_SETTINGS, validateSetting, getSettingMetadata } from './SettingsSchema.js';
+import { DEFAULT_SETTINGS, SETTINGS_METADATA, validateSetting, getSettingMetadata } from './SettingsSchema.js';
 /**
  * Parse .env file content into key-value pairs
  */
@@ -49,20 +49,89 @@ export function getGlobalConfigDir() {
 export function getGlobalEnvPath() {
     return path.join(getGlobalConfigDir(), '.env');
 }
+/**
+ * Resolve the shipped `.env.defaults` — the read-live default config layer.
+ *
+ * This file is committed + ships in the package and is READ directly (never copied
+ * into the user's .env), so a package upgrade ships new defaults automatically. It is
+ * loaded as the LOWEST-precedence layer (below the user's ~/.cortex/.env, below the
+ * real shell env) and also overlays DEFAULT_SETTINGS as the effective floor.
+ *
+ * Search order mirrors the (legacy) seed: the caller's packageRoot, then cwd, then
+ * CORE's own root — core is a dependency of every entry point and is build-synced
+ * with the root canonical, so the file exists for any current/future bin even when
+ * the calling package doesn't ship its own copy.
+ */
+export function resolveDefaultsEnvPath(packageRoot) {
+    const cwd = process.cwd();
+    const coreOwnRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+    return [
+        packageRoot ? path.join(packageRoot, '.env.defaults') : undefined,
+        path.join(cwd, '.env.defaults'),
+        path.join(coreOwnRoot, '.env.defaults'),
+    ].find((p) => !!p && fs.existsSync(p));
+}
+/**
+ * The keys-only seed for a fresh `~/.cortex/.env`: the secret keys + a short header,
+ * NO levers. Harness defaults ship in `.env.defaults` and are read live, so freezing
+ * them into the user's file is exactly what blocks upgrades from propagating new
+ * defaults. Seeding only the keys keeps the file sparse — an upgrade brings new
+ * defaults with nothing to regenerate and no keys to re-enter.
+ */
+export function keysOnlyStub() {
+    const secretKeys = SETTINGS_METADATA.filter(m => m.secret).map(m => m.key);
+    const header = '# Nexus Cortex — your keys & overrides\n' +
+        '#\n' +
+        '# Put your provider API keys here (or run: cortex config set <KEY> <value>).\n' +
+        '# Harness DEFAULTS are NOT in this file — they ship in the package (.env.defaults)\n' +
+        '# and are read live, so upgrades bring new defaults with nothing to regenerate and\n' +
+        '# no keys to re-enter. Only set a lever here to DIVERGE from the shipped default;\n' +
+        '# an uncommented KEY=value here overrides it.\n' +
+        '\n';
+    return header + secretKeys.map(k => `${k}=`).join('\n') + '\n';
+}
+let _effectiveDefaults;
+/**
+ * `DEFAULT_SETTINGS` overlaid with the shipped `.env.defaults` — the EFFECTIVE floor.
+ *
+ * The read-live default layer reaches most levers through `process.env` (bootstrapEnv
+ * loads `.env.defaults` as the lowest base file), but a handful of merge keys don't
+ * consult `process.env`. Overlaying `.env.defaults` onto `DEFAULT_SETTINGS` makes the
+ * shipped file authoritative for EVERY lever. Secrets are untouched (they are Omitted
+ * from `DEFAULT_SETTINGS`, so the loop never visits them). Cached — the shipped file
+ * does not change at runtime.
+ */
+export function getEffectiveDefaults() {
+    if (_effectiveDefaults)
+        return _effectiveDefaults;
+    const d = { ...DEFAULT_SETTINGS };
+    const shipped = resolveDefaultsEnvPath();
+    if (shipped) {
+        try {
+            const parsed = parseEnvFile(fs.readFileSync(shipped, 'utf-8'));
+            for (const k of Object.keys(DEFAULT_SETTINGS)) {
+                const v = parsed[k];
+                if (v !== undefined && v !== '')
+                    d[k] = v;
+            }
+        }
+        catch { /* keep the hardcoded floor */ }
+    }
+    _effectiveDefaults = d;
+    return d;
+}
 /**
  * THE canonical .env → process.env bootstrap for every CLI/TUI entry point.
  *
  * One implementation, so a consumer never hand-rolls dotenv loading (and can't
- * forget the global `~/.cortex/.env`). This function ONLY READS + layers existing
- * .env files into process.env — it never CREATES one. The global `~/.cortex/.env`
- * is seeded SEPARATELY, on first run, by the bin: `packages/cli/bin/cortex.js`
- * copies the shipped `.env.example` → `~/.cortex/.env` when that file is missing
- * (the Docker image does the same copy at build time). All bins call this ONCE at
- * startup; a change here takes effect for every launcher.
+ * forget the global `~/.cortex/.env`). It seeds a KEYS-ONLY `~/.cortex/.env` on first
+ * run (below), then READS + layers the .env files into process.env. All bins call this
+ * ONCE at startup; a change here takes effect for every launcher.
  *
- * Precedence (highest → lowest): a `.env.local` beside any of the base files wins
- * over everything; then project `./.env` (or `packageRoot/.env`) beats the global
- * `~/.cortex/.env`. Matches `loadEnvFile()`'s layering.
+ * Precedence (highest → lowest): a `.env.local` beside any of the base files wins over
+ * everything; then project `./.env` (or `packageRoot/.env`) beats the global
+ * `~/.cortex/.env`, which beats the shipped `.env.defaults` (the read-live default
+ * layer, appended last). Matches `loadEnvFile()`'s layering.
  *
  * FIRST-WINS over the real environment: a value already present in `process.env`
  * (e.g. a key the hosting container injected) is NEVER overwritten by a base .env
@@ -75,48 +144,39 @@ export function getGlobalEnvPath() {
  */
 export function bootstrapEnv(packageRoot) {
     const cwd = process.cwd();
-    // FIRST-ACTIVATION SEED: the first time ANY entry point activates the library
-    // (server, `cortex`, `cortex-cli`, `fuzzycortex`, `neoncortex`, …), create BOTH
-    // .env files from the shipped `.env.example` when missing — the global
-    // `~/.cortex/.env` AND a USER-FINDABLE `packageRoot/.env` (the install dir the user
-    // can open in a file manager). Byte-identical at creation, so no conflict; the user
-    // edits the install-dir copy and it presides over the global (precedence below).
-    // Delete either file and the next activation re-seeds it. Best-effort — a read-only
-    // location is skipped, and a real injected env still works (blank template = unset).
-    // 🔴 GUARANTEED TEMPLATE (operator directive: the seed must work "no matter how
-    // the library or published npm package is invoked"): the calling package's own
-    // .env.example is preferred, but 4 of 5 entry-point packages historically did
-    // NOT ship one — the server entry point silently skipped seeding, so bench/task
-    // containers (server-direct boots) never got a .env at all (found 2026-08-31
-    // via the TB2.1 SearchTools dead-door). CORE ships the template itself
-    // (build-synced from the repo root) and is a dependency of every entry point,
-    // so this fallback makes the seed unconditional for any current or future bin.
-    const coreOwnRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
-    const examplePath = [
-        packageRoot ? path.join(packageRoot, '.env.example') : undefined,
-        path.join(cwd, '.env.example'),
-        path.join(coreOwnRoot, '.env.example'),
-    ].find((p) => !!p && fs.existsSync(p));
-    if (examplePath) {
-        const seedTargets = [
-            getGlobalEnvPath(), // global ~/.cortex/.env
-            ...(packageRoot ? [path.join(packageRoot, '.env')] : []), // user-findable install-dir .env
-        ];
-        for (const target of seedTargets) {
-            try {
-                if (!fs.existsSync(target)) {
-                    fs.mkdirSync(path.dirname(target), { recursive: true });
-                    fs.copyFileSync(examplePath, target);
-                }
-            }
-            catch { /* read-only dir — skip; the file just won't exist for this launch */ }
+    // FIRST-ACTIVATION SEED — a KEYS-ONLY `~/.cortex/.env` (somewhere to put secrets),
+    // NOT a copy of every lever. The first time ANY entry point activates the library
+    // (server, `cortex`, `cortex-cli`, `fuzzycortex`, `neoncortex`, …) and no global
+    // config exists yet, write the sparse keys stub. Harness DEFAULTS are read live from
+    // the shipped `.env.defaults` (loaded below as the lowest layer) — freezing them into
+    // the user's file is exactly what USED to block upgrades from propagating new
+    // defaults, so we no longer seed levers or a `packageRoot/.env` copy. Best-effort —
+    // a read-only home is skipped, and a real injected key still works (blank = unset).
+    const defaultsPath = resolveDefaultsEnvPath(packageRoot);
+    try {
+        const target = getGlobalEnvPath();
+        if (!fs.existsSync(target)) {
+            fs.mkdirSync(path.dirname(target), { recursive: true });
+            fs.writeFileSync(target, keysOnlyStub(), 'utf-8');
         }
     }
-    // Base files, HIGHEST precedence first (first-wins → earlier entries win).
+    catch { /* read-only home — skip; the file just won't exist for this launch */ }
+    // 🔴 NO auto-migration here. `migrateGlobalConfigToSparse()` used to run at bootstrap and
+    // COLLAPSE a full-snapshot ~/.cortex/.env in place — which silently mutated a live/working
+    // config (it clobbered the dev config 2026-09-06). Migration is now OPT-IN only (a deliberate
+    // `cortex config migrate` command with a diff + confirm); bootstrap must NEVER modify the
+    // user's config. Propagation for the common case already works without it: any lever a user
+    // did not override flows from the shipped `.env.defaults` (read-live) on upgrade.
+    // Base files, HIGHEST precedence first (first-wins → earlier entries win). The
+    // shipped `.env.defaults` is appended LAST = lowest precedence: it is the read-live
+    // default layer, below the user's files and below the real injected env — so a user
+    // override (or a bench env-override) always wins, and unset levers flow from the
+    // shipped defaults.
     const baseFiles = [
         path.join(cwd, '.env'),
         ...(packageRoot ? [path.join(packageRoot, '.env')] : []),
         getGlobalEnvPath(),
+        ...(defaultsPath ? [defaultsPath] : []),
     ];
     // `.local` overrides beside each base location (these DO override existing env).
     const localFiles = [
@@ -297,6 +357,124 @@ export function writeEnvSettings(projectPath, settings) {
     }
     return results;
 }
+/**
+ * Surgically REMOVE a setting's line from the .env file (delete the `KEY=...` line and
+ * its value), preserving every other line and all comments. This is the correct "reset
+ * to default" in the read-live model: deleting a user's override line makes the lever
+ * fall back to the shipped `.env.defaults` — so the user rejoins the default flow and
+ * picks up future improvements. (Writing the current default VALUE would re-freeze it.)
+ * A key that isn't present is a no-op success.
+ */
+export function removeEnvSetting(projectPath, key) {
+    const envPath = path.join(projectPath, '.env');
+    if (!fs.existsSync(envPath)) {
+        return { success: true, newValue: '' }; // nothing to remove
+    }
+    let content;
+    try {
+        content = fs.readFileSync(envPath, 'utf-8');
+    }
+    catch (error) {
+        return { success: false, error: `Failed to read .env file: ${error.message}`, newValue: '' };
+    }
+    const previousValue = parseEnvFile(content)[key];
+    if (previousValue === undefined) {
+        return { success: true, newValue: '' }; // key not set — nothing to remove
+    }
+    // Drop the KEY=... line (allow leading whitespace); leave comments/other lines intact.
+    const keyLine = new RegExp(`^[ \\t]*${key}=.*(?:\\r?\\n)?`, 'm');
+    const newContent = content.replace(keyLine, '');
+    try {
+        fs.writeFileSync(envPath, newContent, 'utf-8');
+        return { success: true, previousValue, newValue: '' };
+    }
+    catch (error) {
+        return { success: false, error: `Failed to write .env file: ${error.message}`, previousValue, newValue: '' };
+    }
+}
+/** Set a single setting in the GLOBAL ~/.cortex/.env (surgical, sparse). The canonical
+ *  write target for every /config surface — harness config is global (identical from any
+ *  directory), so a user's choice lives in one place and survives package updates. */
+export function setGlobalSetting(key, value) {
+    return writeEnvSetting(getGlobalConfigDir(), key, value);
+}
+/** Remove a single setting's override line from the GLOBAL ~/.cortex/.env (reset-to-default). */
+export function removeGlobalSetting(key) {
+    return removeEnvSetting(getGlobalConfigDir(), key);
+}
+/** The SHIPPED default value for a lever, read from the live `.env.defaults` (covers every
+ *  lever, including the ones not in DEFAULT_SETTINGS). '' if the file/key is absent. Used
+ *  to restore a lever to its shipped default after removing a user override. */
+export function getShippedDefault(key) {
+    const p = resolveDefaultsEnvPath();
+    if (!p)
+        return '';
+    try {
+        return parseEnvFile(fs.readFileSync(p, 'utf-8'))[key] ?? '';
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * ONE-TIME migration for EXISTING users upgrading to the read-live model. The old install
+ * seeded a FULL copy of every lever into `~/.cortex/.env`, which now FREEZES those levers
+ * (a user value beats the shipped `.env.defaults`), so an upgrade would never reach them.
+ *
+ * This collapses that full snapshot back to SPARSE: a lever line is removed when its value
+ * equals a DEFAULT — either the new shipped default (`.env.defaults`) OR the hardcoded
+ * `DEFAULT_SETTINGS` floor (which still holds the OLD pre-reson defaults). Matching either
+ * means the user never deliberately chose it, so removing it lets the lever inherit the
+ * current shipped default (and every future one). Genuine divergences and ALL API keys are
+ * preserved untouched. Marker-gated (`~/.cortex/.env-migrated`) so it runs exactly once;
+ * best-effort (never blocks boot); only acts on a FULL snapshot, never a sparse file.
+ */
+export function migrateGlobalConfigToSparse() {
+    const dir = getGlobalConfigDir();
+    const marker = path.join(dir, '.env-migrated');
+    const envPath = getGlobalEnvPath();
+    try {
+        if (fs.existsSync(marker) || !fs.existsSync(envPath))
+            return { migrated: false, removed: 0 };
+        const shippedPath = resolveDefaultsEnvPath();
+        const shipped = shippedPath ? parseEnvFile(fs.readFileSync(shippedPath, 'utf-8')) : {};
+        const userEnv = parseEnvFile(fs.readFileSync(envPath, 'utf-8'));
+        const secretKeys = new Set(SETTINGS_METADATA.filter(m => m.secret).map(m => m.key));
+        const leverEntries = Object.entries(userEnv).filter(([k]) => !secretKeys.has(k));
+        // Only act on a FULL snapshot (the old copy-seed signature) — never disturb a file the
+        // user has already curated down to a few sparse overrides.
+        if (leverEntries.length <= 15) {
+            try {
+                fs.writeFileSync(marker, `skipped (sparse) ${new Date().toISOString()}\n`);
+            }
+            catch { /* ignore */ }
+            return { migrated: false, removed: 0 };
+        }
+        const toRemove = leverEntries
+            .filter(([k, v]) => {
+            const shippedVal = shipped[k];
+            const floorVal = DEFAULT_SETTINGS[k];
+            return (shippedVal !== undefined && shippedVal === v) || (floorVal !== undefined && floorVal === v);
+        })
+            .map(([k]) => k);
+        if (toRemove.length > 0) {
+            try {
+                fs.copyFileSync(envPath, envPath + '.pre-migrate-backup');
+            }
+            catch { /* best-effort */ }
+            for (const k of toRemove)
+                removeEnvSetting(dir, k);
+        }
+        try {
+            fs.writeFileSync(marker, `migrated ${new Date().toISOString()} removed=${toRemove.length}\n`);
+        }
+        catch { /* ignore */ }
+        return { migrated: true, removed: toRemove.length };
+    }
+    catch {
+        return { migrated: false, removed: 0 };
+    }
+}
 /**
  * Get Google/Gemini API key with proper fallback
  * Priority: GEMINI_API_KEY (recommended by Google) -> GOOGLE_API_KEY (legacy)
@@ -315,6 +493,9 @@ export function mergeWithDefaults(env) {
     if (!process.env.GEMINI_API_KEY && process.env.GOOGLE_API_KEY) {
         process.env.GEMINI_API_KEY = process.env.GOOGLE_API_KEY;
     }
+    // Effective floor = hardcoded DEFAULT_SETTINGS overlaid with the shipped .env.defaults
+    // (read-live). Used below wherever a value falls through to the code default.
+    const D = getEffectiveDefaults();
     return {
         // API Keys (no defaults, use empty string if not set)
         ANTHROPIC_API_KEY: env.ANTHROPIC_API_KEY || process.env.ANTHROPIC_API_KEY || '',
@@ -332,98 +513,98 @@ export function mergeWithDefaults(env) {
         CLOUDFLARE_ACCOUNT_ID: env.CLOUDFLARE_ACCOUNT_ID || process.env.CLOUDFLARE_ACCOUNT_ID || '',
         NVIDIA_API_KEY: env.NVIDIA_API_KEY || process.env.NVIDIA_API_KEY || '',
         // Anthropic Authentication
-        ANTHROPIC_AUTH_METHOD: env.ANTHROPIC_AUTH_METHOD || process.env.ANTHROPIC_AUTH_METHOD || DEFAULT_SETTINGS.ANTHROPIC_AUTH_METHOD,
+        ANTHROPIC_AUTH_METHOD: env.ANTHROPIC_AUTH_METHOD || process.env.ANTHROPIC_AUTH_METHOD || D.ANTHROPIC_AUTH_METHOD,
         CLAUDE_CODE_OAUTH_TOKEN: env.CLAUDE_CODE_OAUTH_TOKEN || process.env.CLAUDE_CODE_OAUTH_TOKEN || '',
         // Prompt Caching
-        ANTHROPIC_PROMPT_CACHING: env.ANTHROPIC_PROMPT_CACHING || process.env.ANTHROPIC_PROMPT_CACHING || DEFAULT_SETTINGS.ANTHROPIC_PROMPT_CACHING,
+        ANTHROPIC_PROMPT_CACHING: env.ANTHROPIC_PROMPT_CACHING || process.env.ANTHROPIC_PROMPT_CACHING || D.ANTHROPIC_PROMPT_CACHING,
         // Model Configuration
-        DEFAULT_MODEL_ID: env.DEFAULT_MODEL_ID || DEFAULT_SETTINGS.DEFAULT_MODEL_ID,
-        HELPER_MODEL_ID: env.HELPER_MODEL_ID || DEFAULT_SETTINGS.HELPER_MODEL_ID,
+        DEFAULT_MODEL_ID: env.DEFAULT_MODEL_ID || D.DEFAULT_MODEL_ID,
+        HELPER_MODEL_ID: env.HELPER_MODEL_ID || D.HELPER_MODEL_ID,
         // System Settings
-        DEBUG: env.DEBUG || DEFAULT_SETTINGS.DEBUG,
-        USE_EMOJI: env.USE_EMOJI || DEFAULT_SETTINGS.USE_EMOJI,
-        PROJECT_PATH: env.PROJECT_PATH || DEFAULT_SETTINGS.PROJECT_PATH,
+        DEBUG: env.DEBUG || D.DEBUG,
+        USE_EMOJI: env.USE_EMOJI || D.USE_EMOJI,
+        PROJECT_PATH: env.PROJECT_PATH || D.PROJECT_PATH,
         // Reactive Mentorship
-        MENTORSHIP_ENABLED: env.MENTORSHIP_ENABLED || DEFAULT_SETTINGS.MENTORSHIP_ENABLED,
-        MENTORSHIP_TRIGGER_ON_ERROR: env.MENTORSHIP_TRIGGER_ON_ERROR || DEFAULT_SETTINGS.MENTORSHIP_TRIGGER_ON_ERROR,
-        MENTORSHIP_ERROR_THRESHOLD: env.MENTORSHIP_ERROR_THRESHOLD || DEFAULT_SETTINGS.MENTORSHIP_ERROR_THRESHOLD,
-        MENTORSHIP_KEYWORDS_ENABLED: env.MENTORSHIP_KEYWORDS_ENABLED || DEFAULT_SETTINGS.MENTORSHIP_KEYWORDS_ENABLED,
-        MENTORSHIP_CUSTOM_KEYWORDS: env.MENTORSHIP_CUSTOM_KEYWORDS || DEFAULT_SETTINGS.MENTORSHIP_CUSTOM_KEYWORDS,
-        MENTORSHIP_HELPER_MODEL: env.MENTORSHIP_HELPER_MODEL || DEFAULT_SETTINGS.MENTORSHIP_HELPER_MODEL,
-        MENTORSHIP_TURN_BASED_ENABLED: env.MENTORSHIP_TURN_BASED_ENABLED || DEFAULT_SETTINGS.MENTORSHIP_TURN_BASED_ENABLED,
-        MENTORSHIP_TURN_INTERVAL: env.MENTORSHIP_TURN_INTERVAL || DEFAULT_SETTINGS.MENTORSHIP_TURN_INTERVAL,
-        MENTORSHIP_INTERLEAVED_THINKING: env.MENTORSHIP_INTERLEAVED_THINKING || DEFAULT_SETTINGS.MENTORSHIP_INTERLEAVED_THINKING,
-        MENTORSHIP_PATTERN_DETECTION: env.MENTORSHIP_PATTERN_DETECTION || DEFAULT_SETTINGS.MENTORSHIP_PATTERN_DETECTION,
-        MENTORSHIP_PATTERN_THRESHOLD: env.MENTORSHIP_PATTERN_THRESHOLD || DEFAULT_SETTINGS.MENTORSHIP_PATTERN_THRESHOLD,
-        MENTORSHIP_ACTIVE_DISCOVERY: env.MENTORSHIP_ACTIVE_DISCOVERY || DEFAULT_SETTINGS.MENTORSHIP_ACTIVE_DISCOVERY,
+        MENTORSHIP_ENABLED: env.MENTORSHIP_ENABLED || D.MENTORSHIP_ENABLED,
+        MENTORSHIP_TRIGGER_ON_ERROR: env.MENTORSHIP_TRIGGER_ON_ERROR || D.MENTORSHIP_TRIGGER_ON_ERROR,
+        MENTORSHIP_ERROR_THRESHOLD: env.MENTORSHIP_ERROR_THRESHOLD || D.MENTORSHIP_ERROR_THRESHOLD,
+        MENTORSHIP_KEYWORDS_ENABLED: env.MENTORSHIP_KEYWORDS_ENABLED || D.MENTORSHIP_KEYWORDS_ENABLED,
+        MENTORSHIP_CUSTOM_KEYWORDS: env.MENTORSHIP_CUSTOM_KEYWORDS || D.MENTORSHIP_CUSTOM_KEYWORDS,
+        MENTORSHIP_HELPER_MODEL: env.MENTORSHIP_HELPER_MODEL || D.MENTORSHIP_HELPER_MODEL,
+        MENTORSHIP_TURN_BASED_ENABLED: env.MENTORSHIP_TURN_BASED_ENABLED || D.MENTORSHIP_TURN_BASED_ENABLED,
+        MENTORSHIP_TURN_INTERVAL: env.MENTORSHIP_TURN_INTERVAL || D.MENTORSHIP_TURN_INTERVAL,
+        MENTORSHIP_INTERLEAVED_THINKING: env.MENTORSHIP_INTERLEAVED_THINKING || D.MENTORSHIP_INTERLEAVED_THINKING,
+        MENTORSHIP_PATTERN_DETECTION: env.MENTORSHIP_PATTERN_DETECTION || D.MENTORSHIP_PATTERN_DETECTION,
+        MENTORSHIP_PATTERN_THRESHOLD: env.MENTORSHIP_PATTERN_THRESHOLD || D.MENTORSHIP_PATTERN_THRESHOLD,
+        MENTORSHIP_ACTIVE_DISCOVERY: env.MENTORSHIP_ACTIVE_DISCOVERY || D.MENTORSHIP_ACTIVE_DISCOVERY,
         // Turn Summary & Prediction
-        TURN_SUMMARY_PREDICTION: env.TURN_SUMMARY_PREDICTION || DEFAULT_SETTINGS.TURN_SUMMARY_PREDICTION,
+        TURN_SUMMARY_PREDICTION: env.TURN_SUMMARY_PREDICTION || D.TURN_SUMMARY_PREDICTION,
         // Canon (reactive session capture)
-        CANON_AUTO_SYNC: env.CANON_AUTO_SYNC || process.env.CANON_AUTO_SYNC || DEFAULT_SETTINGS.CANON_AUTO_SYNC,
-        CANON_AUTO_SYNC_DEBOUNCE_MS: env.CANON_AUTO_SYNC_DEBOUNCE_MS || process.env.CANON_AUTO_SYNC_DEBOUNCE_MS || DEFAULT_SETTINGS.CANON_AUTO_SYNC_DEBOUNCE_MS,
-        CANON_STORE: env.CANON_STORE || process.env.CANON_STORE || DEFAULT_SETTINGS.CANON_STORE,
-        CANON_REPO: env.CANON_REPO || process.env.CANON_REPO || DEFAULT_SETTINGS.CANON_REPO,
+        CANON_AUTO_SYNC: env.CANON_AUTO_SYNC || process.env.CANON_AUTO_SYNC || D.CANON_AUTO_SYNC,
+        CANON_AUTO_SYNC_DEBOUNCE_MS: env.CANON_AUTO_SYNC_DEBOUNCE_MS || process.env.CANON_AUTO_SYNC_DEBOUNCE_MS || D.CANON_AUTO_SYNC_DEBOUNCE_MS,
+        CANON_STORE: env.CANON_STORE || process.env.CANON_STORE || D.CANON_STORE,
+        CANON_REPO: env.CANON_REPO || process.env.CANON_REPO || D.CANON_REPO,
         // Context Management
-        THINKING_AS_TEXT_FALLBACK: env.THINKING_AS_TEXT_FALLBACK || process.env.THINKING_AS_TEXT_FALLBACK || DEFAULT_SETTINGS.THINKING_AS_TEXT_FALLBACK,
+        THINKING_AS_TEXT_FALLBACK: env.THINKING_AS_TEXT_FALLBACK || process.env.THINKING_AS_TEXT_FALLBACK || D.THINKING_AS_TEXT_FALLBACK,
         // Session Configuration
-        SESSION_STORAGE_DIR: env.SESSION_STORAGE_DIR || DEFAULT_SETTINGS.SESSION_STORAGE_DIR,
-        MCP_AUTO_INJECT: env.MCP_AUTO_INJECT || DEFAULT_SETTINGS.MCP_AUTO_INJECT,
-        AUTORESEARCH_AGENTS: env.AUTORESEARCH_AGENTS || DEFAULT_SETTINGS.AUTORESEARCH_AGENTS,
-        SYSTEM_MESSAGE_DOC_MAX_BYTES: env.SYSTEM_MESSAGE_DOC_MAX_BYTES || DEFAULT_SETTINGS.SYSTEM_MESSAGE_DOC_MAX_BYTES,
-        MEMORY_ARCHIVE_MAX_BYTES: env.MEMORY_ARCHIVE_MAX_BYTES || DEFAULT_SETTINGS.MEMORY_ARCHIVE_MAX_BYTES,
+        SESSION_STORAGE_DIR: env.SESSION_STORAGE_DIR || D.SESSION_STORAGE_DIR,
+        MCP_AUTO_INJECT: env.MCP_AUTO_INJECT || D.MCP_AUTO_INJECT,
+        AUTORESEARCH_AGENTS: env.AUTORESEARCH_AGENTS || D.AUTORESEARCH_AGENTS,
+        SYSTEM_MESSAGE_DOC_MAX_BYTES: env.SYSTEM_MESSAGE_DOC_MAX_BYTES || D.SYSTEM_MESSAGE_DOC_MAX_BYTES,
+        MEMORY_ARCHIVE_MAX_BYTES: env.MEMORY_ARCHIVE_MAX_BYTES || D.MEMORY_ARCHIVE_MAX_BYTES,
         // Loop Control
-        MAX_TOOL_ITERATIONS: env.MAX_TOOL_ITERATIONS || DEFAULT_SETTINGS.MAX_TOOL_ITERATIONS,
-        MAX_CONSECUTIVE_ERRORS: env.MAX_CONSECUTIVE_ERRORS || DEFAULT_SETTINGS.MAX_CONSECUTIVE_ERRORS,
-        TOOL_BUDGET_SOFT: env.TOOL_BUDGET_SOFT || DEFAULT_SETTINGS.TOOL_BUDGET_SOFT,
-        TOOL_TIMEOUT_MS: env.TOOL_TIMEOUT_MS || DEFAULT_SETTINGS.TOOL_TIMEOUT_MS,
-        MAX_LOOP_REPETITIONS: env.MAX_LOOP_REPETITIONS || DEFAULT_SETTINGS.MAX_LOOP_REPETITIONS,
+        MAX_TOOL_ITERATIONS: env.MAX_TOOL_ITERATIONS || D.MAX_TOOL_ITERATIONS,
+        MAX_CONSECUTIVE_ERRORS: env.MAX_CONSECUTIVE_ERRORS || D.MAX_CONSECUTIVE_ERRORS,
+        TOOL_BUDGET_SOFT: env.TOOL_BUDGET_SOFT || D.TOOL_BUDGET_SOFT,
+        TOOL_TIMEOUT_MS: env.TOOL_TIMEOUT_MS || D.TOOL_TIMEOUT_MS,
+        MAX_LOOP_REPETITIONS: env.MAX_LOOP_REPETITIONS || D.MAX_LOOP_REPETITIONS,
         // Web Tools
-        WEB_TOOLS_MODEL: env.WEB_TOOLS_MODEL || process.env.WEB_TOOLS_MODEL || DEFAULT_SETTINGS.WEB_TOOLS_MODEL,
+        WEB_TOOLS_MODEL: env.WEB_TOOLS_MODEL || process.env.WEB_TOOLS_MODEL || D.WEB_TOOLS_MODEL,
         // Server-Side Tools
-        ENABLE_SERVER_SIDE_TOOLS: env.ENABLE_SERVER_SIDE_TOOLS || process.env.ENABLE_SERVER_SIDE_TOOLS || DEFAULT_SETTINGS.ENABLE_SERVER_SIDE_TOOLS,
-        XAI_API_MODE: env.XAI_API_MODE || process.env.XAI_API_MODE || DEFAULT_SETTINGS.XAI_API_MODE,
-        OPENAI_API_MODE: env.OPENAI_API_MODE || process.env.OPENAI_API_MODE || DEFAULT_SETTINGS.OPENAI_API_MODE,
+        ENABLE_SERVER_SIDE_TOOLS: env.ENABLE_SERVER_SIDE_TOOLS || process.env.ENABLE_SERVER_SIDE_TOOLS || D.ENABLE_SERVER_SIDE_TOOLS,
+        XAI_API_MODE: env.XAI_API_MODE || process.env.XAI_API_MODE || D.XAI_API_MODE,
+        OPENAI_API_MODE: env.OPENAI_API_MODE || process.env.OPENAI_API_MODE || D.OPENAI_API_MODE,
         // Agent Team Monitoring
-        AGENT_TMUX_MONITOR: env.AGENT_TMUX_MONITOR || process.env.AGENT_TMUX_MONITOR || DEFAULT_SETTINGS.AGENT_TMUX_MONITOR,
+        AGENT_TMUX_MONITOR: env.AGENT_TMUX_MONITOR || process.env.AGENT_TMUX_MONITOR || D.AGENT_TMUX_MONITOR,
         // PTC / Code Execution / Deferred Loading
-        ENABLE_PTC: env.ENABLE_PTC || process.env.ENABLE_PTC || DEFAULT_SETTINGS.ENABLE_PTC,
-        ENABLE_WEBTOOLS: env.ENABLE_WEBTOOLS || process.env.ENABLE_WEBTOOLS || DEFAULT_SETTINGS.ENABLE_WEBTOOLS,
-        VISION_HELPER_MODEL: env.VISION_HELPER_MODEL || process.env.VISION_HELPER_MODEL || DEFAULT_SETTINGS.VISION_HELPER_MODEL,
-        TOOL_TIMEOUT_MODE: env.TOOL_TIMEOUT_MODE || process.env.TOOL_TIMEOUT_MODE || DEFAULT_SETTINGS.TOOL_TIMEOUT_MODE,
-        VISION_HANDOFF_MAX: env.VISION_HANDOFF_MAX || process.env.VISION_HANDOFF_MAX || DEFAULT_SETTINGS.VISION_HANDOFF_MAX,
-        CORTEX_SLICE_NUDGE: env.CORTEX_SLICE_NUDGE || process.env.CORTEX_SLICE_NUDGE || DEFAULT_SETTINGS.CORTEX_SLICE_NUDGE,
-        ENABLE_LOCAL_CODE_EXECUTION: env.ENABLE_LOCAL_CODE_EXECUTION || process.env.ENABLE_LOCAL_CODE_EXECUTION || DEFAULT_SETTINGS.ENABLE_LOCAL_CODE_EXECUTION,
-        ENABLE_DEFERRED_TOOL_LOADING: env.ENABLE_DEFERRED_TOOL_LOADING || process.env.ENABLE_DEFERRED_TOOL_LOADING || DEFAULT_SETTINGS.ENABLE_DEFERRED_TOOL_LOADING,
+        ENABLE_PTC: env.ENABLE_PTC || process.env.ENABLE_PTC || D.ENABLE_PTC,
+        ENABLE_WEBTOOLS: env.ENABLE_WEBTOOLS || process.env.ENABLE_WEBTOOLS || D.ENABLE_WEBTOOLS,
+        VISION_HELPER_MODEL: env.VISION_HELPER_MODEL || process.env.VISION_HELPER_MODEL || D.VISION_HELPER_MODEL,
+        TOOL_TIMEOUT_MODE: env.TOOL_TIMEOUT_MODE || process.env.TOOL_TIMEOUT_MODE || D.TOOL_TIMEOUT_MODE,
+        VISION_HANDOFF_MAX: env.VISION_HANDOFF_MAX || process.env.VISION_HANDOFF_MAX || D.VISION_HANDOFF_MAX,
+        CORTEX_SLICE_NUDGE: env.CORTEX_SLICE_NUDGE || process.env.CORTEX_SLICE_NUDGE || D.CORTEX_SLICE_NUDGE,
+        ENABLE_LOCAL_CODE_EXECUTION: env.ENABLE_LOCAL_CODE_EXECUTION || process.env.ENABLE_LOCAL_CODE_EXECUTION || D.ENABLE_LOCAL_CODE_EXECUTION,
+        ENABLE_DEFERRED_TOOL_LOADING: env.ENABLE_DEFERRED_TOOL_LOADING || process.env.ENABLE_DEFERRED_TOOL_LOADING || D.ENABLE_DEFERRED_TOOL_LOADING,
         // Model Router
-        MODEL_ROUTER_ENABLED: env.MODEL_ROUTER_ENABLED || process.env.MODEL_ROUTER_ENABLED || DEFAULT_SETTINGS.MODEL_ROUTER_ENABLED,
-        MODEL_ROUTER_STRATEGY: env.MODEL_ROUTER_STRATEGY || process.env.MODEL_ROUTER_STRATEGY || DEFAULT_SETTINGS.MODEL_ROUTER_STRATEGY,
-        MODEL_ROUTER_RECORD: env.MODEL_ROUTER_RECORD || process.env.MODEL_ROUTER_RECORD || DEFAULT_SETTINGS.MODEL_ROUTER_RECORD,
-        ROUTER_MIN_CONFIDENCE: env.ROUTER_MIN_CONFIDENCE || process.env.ROUTER_MIN_CONFIDENCE || DEFAULT_SETTINGS.ROUTER_MIN_CONFIDENCE,
-        ROUTER_MIN_SAMPLES: env.ROUTER_MIN_SAMPLES || process.env.ROUTER_MIN_SAMPLES || DEFAULT_SETTINGS.ROUTER_MIN_SAMPLES,
-        MODEL_ROUTER_EXPLORATION: env.MODEL_ROUTER_EXPLORATION || process.env.MODEL_ROUTER_EXPLORATION || DEFAULT_SETTINGS.MODEL_ROUTER_EXPLORATION,
-        MODEL_ROUTER_EXCLUDE: env.MODEL_ROUTER_EXCLUDE ?? process.env.MODEL_ROUTER_EXCLUDE ?? DEFAULT_SETTINGS.MODEL_ROUTER_EXCLUDE,
+        MODEL_ROUTER_ENABLED: env.MODEL_ROUTER_ENABLED || process.env.MODEL_ROUTER_ENABLED || D.MODEL_ROUTER_ENABLED,
+        MODEL_ROUTER_STRATEGY: env.MODEL_ROUTER_STRATEGY || process.env.MODEL_ROUTER_STRATEGY || D.MODEL_ROUTER_STRATEGY,
+        MODEL_ROUTER_RECORD: env.MODEL_ROUTER_RECORD || process.env.MODEL_ROUTER_RECORD || D.MODEL_ROUTER_RECORD,
+        ROUTER_MIN_CONFIDENCE: env.ROUTER_MIN_CONFIDENCE || process.env.ROUTER_MIN_CONFIDENCE || D.ROUTER_MIN_CONFIDENCE,
+        ROUTER_MIN_SAMPLES: env.ROUTER_MIN_SAMPLES || process.env.ROUTER_MIN_SAMPLES || D.ROUTER_MIN_SAMPLES,
+        MODEL_ROUTER_EXPLORATION: env.MODEL_ROUTER_EXPLORATION || process.env.MODEL_ROUTER_EXPLORATION || D.MODEL_ROUTER_EXPLORATION,
+        MODEL_ROUTER_EXCLUDE: env.MODEL_ROUTER_EXCLUDE ?? process.env.MODEL_ROUTER_EXCLUDE ?? D.MODEL_ROUTER_EXCLUDE,
         // Endturn Gate / Training
-        CORTEX_ENDTURN_GATE: env.CORTEX_ENDTURN_GATE || process.env.CORTEX_ENDTURN_GATE || DEFAULT_SETTINGS.CORTEX_ENDTURN_GATE,
-        CORTEX_TOOL_PROFILE: env.CORTEX_TOOL_PROFILE || process.env.CORTEX_TOOL_PROFILE || DEFAULT_SETTINGS.CORTEX_TOOL_PROFILE,
+        CORTEX_ENDTURN_GATE: env.CORTEX_ENDTURN_GATE || process.env.CORTEX_ENDTURN_GATE || D.CORTEX_ENDTURN_GATE,
+        CORTEX_TOOL_PROFILE: env.CORTEX_TOOL_PROFILE || process.env.CORTEX_TOOL_PROFILE || D.CORTEX_TOOL_PROFILE,
         // Decision Store
-        CORTEX_RECORD_DECISIONS: env.CORTEX_RECORD_DECISIONS || process.env.CORTEX_RECORD_DECISIONS || DEFAULT_SETTINGS.CORTEX_RECORD_DECISIONS,
-        CORTEX_LOOKUP_PRIOR_DECISIONS: env.CORTEX_LOOKUP_PRIOR_DECISIONS || process.env.CORTEX_LOOKUP_PRIOR_DECISIONS || DEFAULT_SETTINGS.CORTEX_LOOKUP_PRIOR_DECISIONS,
-        CORTEX_DECISIONS_MAX_BYTES: env.CORTEX_DECISIONS_MAX_BYTES || process.env.CORTEX_DECISIONS_MAX_BYTES || DEFAULT_SETTINGS.CORTEX_DECISIONS_MAX_BYTES,
+        CORTEX_RECORD_DECISIONS: env.CORTEX_RECORD_DECISIONS || process.env.CORTEX_RECORD_DECISIONS || D.CORTEX_RECORD_DECISIONS,
+        CORTEX_LOOKUP_PRIOR_DECISIONS: env.CORTEX_LOOKUP_PRIOR_DECISIONS || process.env.CORTEX_LOOKUP_PRIOR_DECISIONS || D.CORTEX_LOOKUP_PRIOR_DECISIONS,
+        CORTEX_DECISIONS_MAX_BYTES: env.CORTEX_DECISIONS_MAX_BYTES || process.env.CORTEX_DECISIONS_MAX_BYTES || D.CORTEX_DECISIONS_MAX_BYTES,
         // Runtime
-        CORTEX_MODE: env.CORTEX_MODE || DEFAULT_SETTINGS.CORTEX_MODE,
-        CORTEX_UPDATE_POLICY: env.CORTEX_UPDATE_POLICY || process.env.CORTEX_UPDATE_POLICY || DEFAULT_SETTINGS.CORTEX_UPDATE_POLICY,
-        YOLO: env.YOLO || process.env.YOLO || DEFAULT_SETTINGS.YOLO,
-        AUTO_RESUME: env.AUTO_RESUME || process.env.AUTO_RESUME || DEFAULT_SETTINGS.AUTO_RESUME,
-        PORT: env.PORT || process.env.PORT || DEFAULT_SETTINGS.PORT,
-        CORTEX_SERVER_URL: env.CORTEX_SERVER_URL || DEFAULT_SETTINGS.CORTEX_SERVER_URL,
-        DEBUG_PAYLOAD: env.DEBUG_PAYLOAD || process.env.DEBUG_PAYLOAD || DEFAULT_SETTINGS.DEBUG_PAYLOAD,
-        DEBUG_THINKING: env.DEBUG_THINKING || process.env.DEBUG_THINKING || DEFAULT_SETTINGS.DEBUG_THINKING,
-        ENABLE_SMOKE_TESTS: env.ENABLE_SMOKE_TESTS || process.env.ENABLE_SMOKE_TESTS || DEFAULT_SETTINGS.ENABLE_SMOKE_TESTS,
+        CORTEX_MODE: env.CORTEX_MODE || D.CORTEX_MODE,
+        CORTEX_UPDATE_POLICY: env.CORTEX_UPDATE_POLICY || process.env.CORTEX_UPDATE_POLICY || D.CORTEX_UPDATE_POLICY,
+        YOLO: env.YOLO || process.env.YOLO || D.YOLO,
+        AUTO_RESUME: env.AUTO_RESUME || process.env.AUTO_RESUME || D.AUTO_RESUME,
+        PORT: env.PORT || process.env.PORT || D.PORT,
+        CORTEX_SERVER_URL: env.CORTEX_SERVER_URL || D.CORTEX_SERVER_URL,
+        DEBUG_PAYLOAD: env.DEBUG_PAYLOAD || process.env.DEBUG_PAYLOAD || D.DEBUG_PAYLOAD,
+        DEBUG_THINKING: env.DEBUG_THINKING || process.env.DEBUG_THINKING || D.DEBUG_THINKING,
+        ENABLE_SMOKE_TESTS: env.ENABLE_SMOKE_TESTS || process.env.ENABLE_SMOKE_TESTS || D.ENABLE_SMOKE_TESTS,
         // Git / PR access control
-        GIT_ALLOWED_REPOS: env.GIT_ALLOWED_REPOS || process.env.GIT_ALLOWED_REPOS || DEFAULT_SETTINGS.GIT_ALLOWED_REPOS,
-        GIT_ALLOWED_ACTIONS: env.GIT_ALLOWED_ACTIONS || process.env.GIT_ALLOWED_ACTIONS || DEFAULT_SETTINGS.GIT_ALLOWED_ACTIONS,
+        GIT_ALLOWED_REPOS: env.GIT_ALLOWED_REPOS || process.env.GIT_ALLOWED_REPOS || D.GIT_ALLOWED_REPOS,
+        GIT_ALLOWED_ACTIONS: env.GIT_ALLOWED_ACTIONS || process.env.GIT_ALLOWED_ACTIONS || D.GIT_ALLOWED_ACTIONS,
         GIT_AUTH_TOKEN: env.GIT_AUTH_TOKEN || process.env.GIT_AUTH_TOKEN || '',
-        GIT_HOST: env.GIT_HOST || process.env.GIT_HOST || DEFAULT_SETTINGS.GIT_HOST,
+        GIT_HOST: env.GIT_HOST || process.env.GIT_HOST || D.GIT_HOST,
         GITHUB_WEBHOOK_SECRET: env.GITHUB_WEBHOOK_SECRET || process.env.GITHUB_WEBHOOK_SECRET || '',
     };
 }
@@ -581,27 +762,46 @@ export class SettingsLoader {
         return results;
     }
     /**
-     * Reset a setting to its default value
+     * Remove a setting's override line (reset-to-default). Deletes the user's override so
+     * the lever falls back to the shipped `.env.defaults` — the correct reset in the
+     * read-live model (writing the current default value would re-freeze it).
      */
+    remove(key) {
+        const result = removeEnvSetting(this.projectPath, key);
+        if (result.success)
+            this.reload();
+        return result;
+    }
+    /** Alias — reset a single setting to the shipped default by removing the override. */
     resetToDefault(key) {
-        const defaultValue = DEFAULT_SETTINGS[key];
-        if (defaultValue === undefined) {
-            return {
-                success: false,
-                error: `No default value for ${key}`,
-                newValue: ''
-            };
-        }
-        return this.set(key, defaultValue);
+        return this.remove(key);
+    }
+    /**
+     * True if this key is set as an override in the user's OWN .env file (vs flowing from
+     * the shipped .env.defaults). Powers the "your override / shipped default" display.
+     */
+    isUserOverride(key) {
+        return readEnvFileAt(path.join(this.projectPath, '.env'))[key] !== undefined;
+    }
+    /** All keys the user has overridden in their own .env file (one read — for a display
+     *  that needs to mark many rows without re-reading the file per row). */
+    getOverriddenKeys() {
+        return Object.keys(readEnvFileAt(path.join(this.projectPath, '.env')));
     }
     /**
-     * Reset all settings to defaults
+     * Reset all LEVERS to defaults by removing their override lines (API keys preserved),
+     * so every lever falls back to the shipped `.env.defaults`.
      */
     resetAllToDefaults() {
         const results = {};
-        for (const [key, value] of Object.entries(DEFAULT_SETTINGS)) {
-            results[key] = this.set(key, value);
+        const secretKeys = new Set(SETTINGS_METADATA.filter(m => m.secret).map(m => m.key));
+        const fileEnv = readEnvFileAt(path.join(this.projectPath, '.env'));
+        for (const key of Object.keys(fileEnv)) {
+            if (secretKeys.has(key))
+                continue; // preserve API keys
+            results[key] = removeEnvSetting(this.projectPath, key);
         }
+        this.reload();
         return results;
     }
     /**