@gaunt-sloth/core 2.0.0-alpha.9 → 2.0.0-beta.0

package/dist/config/loader.js

@@ -1,69 +1,160 @@
 /**
  * @packageDocumentation
  * Configuration discovery + the layered load/merge pipeline (global + project layers,
- * format fall-through JSON → JS → MJS, schema validation, deep-merge with defaults).
+ * format fall-through JSON → JSONC → JS → MJS, schema validation, deep-merge with defaults).
  * Extracted from the former `config.ts` god-file; behaviour is unchanged.
  */
-import { GSLOTH_DIR, GSLOTH_SETTINGS_DIR, USER_PROJECT_CONFIG_JS, USER_PROJECT_CONFIG_JSON, USER_PROJECT_CONFIG_MJS, USER_PROJECT_CONFIG_TS, } from '#src/constants.js';
+import { GSLOTH_DIR, GSLOTH_SETTINGS_DIR, USER_PROJECT_CONFIG_JS, USER_PROJECT_CONFIG_JSON, USER_PROJECT_CONFIG_JSONC, USER_PROJECT_CONFIG_MJS, USER_PROJECT_CONFIG_TS, } from '#src/constants.js';
 import { StatusLevel } from '#src/core/types.js';
 import { displayDebug, displayError, displayInfo, displayWarning, setConsoleLevel, } from '#src/utils/consoleUtils.js';
-import { findUnknownTopLevelKeys, formatConfigValidationError, preMapDeprecatedConfigNames, rawGthConfigSchema, validateRawGthConfig, } from '#src/config/schema.js';
+import { findApprovalsGrammarIssues, findApprovalsRaterProfiles, findDeprecatedConfigIssues, findUnknownTopLevelKeys, formatConfigValidationError, formatDeprecatedConfigIssues, isRecordConfig, rawGthConfigSchema, unresolvedRaterProfileMessage, validateRawGthConfig, } from '#src/config/schema.js';
 import { parseJsonc } from '#src/config/jsonc.js';
+import { isMissingProviderKeyError, MissingProviderKeyError } from '#src/config/providerKeys.js';
+import { ConfigDiscoveryError, isConfigDiscoveryError } from '#src/config/configDiscovery.js';
 import { getGslothConfigReadPath, importExternalFile } from '#src/utils/fileUtils.js';
-import { getGlobalGslothConfigReadPath } from '#src/utils/globalConfigUtils.js';
-import { error, exit, getCurrentWorkDir, isTTY, setProjectDir, setUseColour, } from '#src/utils/systemUtils.js';
+import { getGlobalGslothConfigReadPath, getGlobalGslothDir } from '#src/utils/globalConfigUtils.js';
+import { env, getCurrentWorkDir, isStdoutTTY, isTTY, setProjectDir, setUseColour, } from '#src/utils/systemUtils.js';
+import { resolveUseColour } from '#src/config/colour.js';
+import { resolveUseMouse } from '#src/config/mouse.js';
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { dirname, resolve } from 'node:path';
+import { dirname, resolve, sep } from 'node:path';
 import { DEFAULT_CONFIG } from '#src/config/defaults.js';
+/**
+ * CFG-56 — the identity profile the GLOBAL layer is read under, which is NOT simply
+ * `identityProfile`: only a `--global` run relocates the global layer into
+ * `~/.gsloth/.gsloth-settings/<name>/`. Without `--global`, `-i <name>` selects a PROJECT-layer
+ * directory and the global layer stays the plain `~/.gsloth/.gsloth.config.*` — which is exactly
+ * what a run does ({@link applyGlobalConfigBase} reads it with no profile). Every reader of the
+ * global layer goes through this so the diagnostics (`gth config validate`, the `tui` reader,
+ * first-run detection) cannot scope it differently from the run.
+ */
+function globalLayerProfile(commandLineConfigOverrides) {
+    return commandLineConfigOverrides.global ? commandLineConfigOverrides.identityProfile : undefined;
+}
+/**
+ * The `~/.gsloth/.gsloth-settings/<profile>/` directory as shown to a user in an error message or
+ * a layer label. Composed with the path helpers, so a Windows home dir does not surface as a
+ * mixed-separator `C:\Users\x\.gsloth/.gsloth-settings/sec/`.
+ */
+function globalProfileDirLabel(profile) {
+    return `${resolve(getGlobalGslothDir(), GSLOTH_SETTINGS_DIR, profile)}${sep}`;
+}
 /**
  * Validate (and normalize) a freshly loaded raw config layer (global or project)
  * against {@link rawGthConfigSchema}, the single source of truth for the on-disk
  * config shape.
  *
  * Steps, in order:
- * 1. B3 pre-map: map deprecated key names one-way to their canonical names (root +
- *    per-command) via {@link preMapDeprecatedConfigNames}, emitting a deprecation
- *    `displayWarning` for each occurrence. This runs FIRST so renamed keys are not
- *    later mistaken for unknown keys.
+ * 1. Deprecated-shape reject (GS2-28): a removed pre-2.0 shape — a top-level command key
+ *    or a deprecated `*Provider*` name (root + per-command), detected by
+ *    {@link findDeprecatedConfigIssues} — is a HARD error naming the canonical replacement +
+ *    migration path. 2.0 dropped back-compat coercion, so these fail rather than
+ *    remap. Runs FIRST so a deprecated name never merely surfaces as an unknown-key warning.
+ * 1b. Approvals rule-grammar reject (EXT-71): a bare string in `allow`/`deny`/`escalate`, or a
+ *    configured `mcpServers` key named `*`, detected by {@link findApprovalsGrammarIssues} — a
+ *    HARD error, before the parse so its message (which shows the object form of the string the
+ *    user wrote) is the only one they see.
  * 2. Unknown top-level keys: warn (do NOT fail) so likely typos are surfaced while
  *    forward-compatible / extension keys still pass through untouched.
- * 3. Schema parse: on a genuine type mismatch on a known field, emit a friendly,
- *    path-scoped error and exit (matching the loader's existing invalid-config
- *    behaviour). Validation is shape-only — the loose schema preserves unknown keys,
- *    so the original `raw` (pre-mapped) is returned unchanged on success.
+ * 3. Schema parse: on a genuine type mismatch on a known field, a friendly, path-scoped
+ *    error. Validation is shape-only — the loose schema preserves unknown keys,
+ *    so the original `raw` is returned unchanged on success.
+ *
+ * CFG-36 / CFG-47 — every hard failure above RAISES a {@link ConfigDiscoveryError} rather than
+ * printing and calling `exit(1)`, and so does every other "config present and unusable" site in this
+ * file. Config loading is a library operation: the caller chooses the exit code (the CLI's top-level
+ * guard prints the message and exits 1; `gth eval` classifies it as a harness error and exits 2).
+ * **This file no longer calls `exit` at all** — that is the invariant, and it is easier to keep than
+ * a list of which sites do. Because these throw, every `catch` between here and a top level must
+ * re-raise them rather than fall through to another format or treat the layer as absent — see the
+ * {@link isConfigDiscoveryError} re-raises in {@link loadGlobalRawConfig}, {@link initConfig},
+ * {@link tryModuleConfig} and {@link tryJsonConfig}. Swallowing one would silently downgrade a hard
+ * config error to a different (or absent) config, which is the false-green this change exists to
+ * prevent.
  *
- * @param raw The freshly loaded config layer (mutated in place by the pre-map).
+ * @param raw The freshly loaded config layer (read-only here).
  * @param sourceLabel Human-readable source name for messages (e.g. the filename).
+ * @param options Profile-resolution scope for this layer — see {@link ProfileScopeOptions}.
+ * @throws ConfigDiscoveryError when the layer carries a hard configuration error.
  */
-function validateRawConfigLayer(raw, sourceLabel) {
-    const { config, warnings } = preMapDeprecatedConfigNames(raw);
-    for (const warning of warnings) {
-        displayWarning(warning);
-    }
-    const unknownKeys = findUnknownTopLevelKeys(config);
-    if (unknownKeys.length > 0) {
-        displayWarning(`Unknown top-level config ${unknownKeys.length === 1 ? 'key' : 'keys'} in ${sourceLabel}: ` +
-            `${unknownKeys.join(', ')}. ${unknownKeys.length === 1 ? 'It is' : 'They are'} kept as-is ` +
-            'but ignored by Gaunt Sloth; check for typos.');
+function validateRawConfigLayer(raw, sourceLabel, options) {
+    // Only an object config can carry deprecated/unknown keys; a null/array/primitive config skips
+    // the scans (they'd throw a raw TypeError) and falls to safeParse, which emits a clean
+    // "expected object" error + exit — never a coercion to {} (which would wrongly pass).
+    if (isRecordConfig(raw)) {
+        const deprecatedIssues = findDeprecatedConfigIssues(raw);
+        if (deprecatedIssues.length > 0) {
+            throw new ConfigDiscoveryError(`Invalid configuration in ${sourceLabel}:\n${formatDeprecatedConfigIssues(deprecatedIssues)}`, { sourceLabel });
+        }
+        // EXT-71 — the rule-grammar errors that must be seen BEFORE the schema parse: a bare string in
+        // a rule list (whose message shows the object form of that same string) and a reserved `*`
+        // MCP server name. Checked in the same place as the deprecated scan, and in `gth config
+        // validate` too, so the validator can never green-light a config a real run refuses.
+        const grammarIssues = findApprovalsGrammarIssues(raw);
+        if (grammarIssues.length > 0) {
+            throw new ConfigDiscoveryError(`Invalid configuration in ${sourceLabel}:\n${formatDeprecatedConfigIssues(grammarIssues)}`, { sourceLabel });
+        }
+        const unknownKeys = findUnknownTopLevelKeys(raw);
+        if (unknownKeys.length > 0) {
+            displayWarning(`Unknown top-level config ${unknownKeys.length === 1 ? 'key' : 'keys'} in ${sourceLabel}: ` +
+                `${unknownKeys.join(', ')}. ${unknownKeys.length === 1 ? 'It is' : 'They are'} kept as-is ` +
+                'but ignored by Gaunt Sloth; check for typos.');
+        }
     }
-    const result = rawGthConfigSchema.safeParse(config);
+    const result = rawGthConfigSchema.safeParse(raw);
     if (!result.success) {
-        displayError(`Invalid configuration in ${sourceLabel}:\n${formatConfigValidationError(result.error)}`);
-        exit(1);
+        throw new ConfigDiscoveryError(`Invalid configuration in ${sourceLabel}:\n${formatConfigValidationError(result.error)}`, { sourceLabel });
+    }
+    // CFG-26 — `approvals.rater` STRICT resolution (GS2-62): a named profile that does not
+    // resolve to a real profile config is a hard error, never a silent fallback to the main model.
+    // Checked HERE rather than in the zod schema on purpose — resolution needs the filesystem and
+    // `schema.ts` must stay pure (it also feeds `z.toJSONSchema`).
+    //
+    // CFG-56 — the resolution SCOPE travels with the layer. Under `--global` a rater profile must
+    // resolve under `~/.gsloth/.gsloth-settings/`, exactly as `validateConfig`'s `resolveProfile`
+    // hook resolves it: an unscoped check here would accept a project profile in a run whose whole
+    // purpose is to bypass project config, and reject a global one that `gth -g config validate`
+    // just called valid.
+    if (isRecordConfig(raw)) {
+        for (const ref of findApprovalsRaterProfiles(raw)) {
+            if (!resolveIdentityProfileConfigPath(ref.profile, options)) {
+                throw new ConfigDiscoveryError(`Invalid configuration in ${sourceLabel}:\n` +
+                    `  - ${ref.path}: ${unresolvedRaterProfileMessage(ref, options?.globalOnly ? globalProfileDirLabel(ref.profile) : undefined)}`, { sourceLabel, identityProfile: ref.profile });
+            }
+        }
     }
-    return config;
+    return raw;
 }
 /**
- * Project config file lookup order, highest precedence first. JSON wins, then the
- * `configure()`-style module formats (JS → MJS → TS). Used to pick THE config within a dir.
+ * Project config file lookup order, highest precedence first. JSON wins, then its `.jsonc`
+ * spelling (GS2-69 — same {@link parseJsonc} parse either way), then the `configure()`-style
+ * module formats (JS → MJS → TS). Used to pick THE config within a dir.
  */
 const PROJECT_CONFIG_FORMATS = [
     USER_PROJECT_CONFIG_JSON,
+    USER_PROJECT_CONFIG_JSONC,
     USER_PROJECT_CONFIG_JS,
     USER_PROJECT_CONFIG_MJS,
     USER_PROJECT_CONFIG_TS,
 ];
+/**
+ * GS2-69 — the lookup order for the two JSON-family filenames wherever they are probed as a
+ * pair (the global `~/.gsloth` lookup and its read-side mirror). `.json` first, so it wins
+ * when both exist — matching {@link PROJECT_CONFIG_FORMATS}.
+ */
+const JSON_CONFIG_FILENAMES = [
+    USER_PROJECT_CONFIG_JSON,
+    USER_PROJECT_CONFIG_JSONC,
+];
+/**
+ * True when `path` belongs to the JSONC-parsing branch (a `.json` OR `.jsonc` file, GS2-69) as
+ * opposed to the `configure()`-module importer. Single-sources the run-path gate so an explicit
+ * `-c foo.jsonc` can never fall through to the module importer again.
+ */
+function isJsonConfigPath(path) {
+    return path.endsWith('.json') || path.endsWith('.jsonc');
+}
 /**
  * Dir-aware version of {@link getGslothConfigReadPath} for ancestor dirs during the up-tree
  * walk. Mirrors its `.gsloth/.gsloth-settings[/<profile>]/<filename>` resolution but against an
@@ -96,6 +187,25 @@ function resolveConfigPath(baseDir, filename, identityProfile) {
         ? getGslothConfigReadPath(filename, identityProfile)
         : resolveProjectConfigPathInDir(baseDir, filename, identityProfile);
 }
+/**
+ * Yield each directory to search during config discovery, from cwd up to (and INCLUDING) the stop
+ * boundary — a dir containing `.git` (the git root), the user's home dir, or the filesystem root,
+ * whichever comes first (the dir at the boundary is itself searched, then ascent stops). Single-
+ * sources the up-tree boundary so {@link findProjectConfigPath} and
+ * {@link resolveIdentityProfileConfigPath} can never drift on where the walk starts or stops.
+ */
+function* walkConfigSearchDirs() {
+    const home = homedir();
+    let dir = getCurrentWorkDir();
+    for (;;) {
+        yield dir;
+        const parent = dirname(dir);
+        if (existsSync(resolve(dir, '.git')) || dir === home || parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+}
 /**
  * Find THE project config by walking up from cwd toward a stop boundary, returning the FIRST
  * match (first-match-win: nearest dir, then format precedence within that dir — NOT a merged
@@ -108,10 +218,19 @@ function resolveConfigPath(baseDir, filename, identityProfile) {
  *
  * A `customConfigPath` override wins outright (no walking).
  *
+ * NOTE (identity profile): with an `identityProfile` set, each dir's per-format resolver
+ * ({@link resolveConfigPath}) tries the profile path `.gsloth/.gsloth-settings/<profile>/<file>`
+ * but FALLS BACK to the plain `<dir>/<file>` when the profile file is absent. So a match here does
+ * NOT prove the named profile itself has a config — it may be a plain (non-profile) config. Use
+ * {@link resolveIdentityProfileConfigPath} when you need to know a profile specifically resolved.
+ *
  * @returns the matched `{ dir, path }`, or `undefined` when no project config exists within the
  * boundary.
  */
 export function findProjectConfigPath(commandLineConfigOverrides) {
+    if (commandLineConfigOverrides.global) {
+        return undefined;
+    }
     if (commandLineConfigOverrides.customConfigPath) {
         return existsSync(commandLineConfigOverrides.customConfigPath)
             ? {
@@ -120,24 +239,101 @@ export function findProjectConfigPath(commandLineConfigOverrides) {
             }
             : undefined;
     }
-    const home = homedir();
-    let dir = getCurrentWorkDir();
     // Walk up: search each dir, then stop at the boundary (git root / home / fs root).
-    for (;;) {
+    for (const dir of walkConfigSearchDirs()) {
         for (const filename of PROJECT_CONFIG_FORMATS) {
             const candidate = resolveConfigPath(dir, filename, commandLineConfigOverrides.identityProfile);
             if (existsSync(candidate)) {
                 return { dir, path: candidate };
             }
         }
-        const parent = dirname(dir);
-        if (existsSync(resolve(dir, '.git')) || dir === home || parent === dir) {
-            break;
+    }
+    return undefined;
+}
+/**
+ * STRICT existence check for an EXPLICITLY-named identity profile: does
+ * `.gsloth/.gsloth-settings/<identityProfile>/<config>` resolve to a real config file anywhere in
+ * the same up-tree search {@link findProjectConfigPath} walks? Returns the resolved profile config
+ * path (nearest dir, then format precedence) when the profile has its OWN config, `undefined`
+ * otherwise.
+ *
+ * Unlike {@link findProjectConfigPath}, it matches ONLY the profile-specific path — it NEVER falls
+ * through to a plain `<dir>/<config>` and NEVER falls back to the global config. That strictness is
+ * the whole point: it lets a caller distinguish "this named profile really exists" from "a bare
+ * config happens to be present / a global config exists," a distinction the loader's fall-through
+ * deliberately blurs.
+ *
+ * PURE PREDICATE — never throws, never calls `exit`, so it can be asked the question without
+ * committing to an outcome. {@link initConfig} uses it to enforce that an explicitly-named profile
+ * really exists (raising a catchable {@link ConfigDiscoveryError} when it does not), and callers
+ * that want to CLASSIFY rather than fail — BATCH-12's identity matrix checks every declared identity
+ * up front so one message can name them all — ask it directly. A blank/whitespace-only name counts
+ * as "no profile" → `undefined`.
+ *
+ * @param identityProfile The explicitly-requested identity profile name.
+ * @param options CFG-56 — `globalOnly` searches `~/.gsloth/.gsloth-settings/<name>/` INSTEAD of
+ * the up-tree project walk, for a `--global` run.
+ * @returns The resolved profile config path, or `undefined` when the profile has no config.
+ */
+export function resolveIdentityProfileConfigPath(identityProfile, options) {
+    const profile = identityProfile?.trim();
+    if (!profile) {
+        return undefined;
+    }
+    if (options?.globalOnly) {
+        const globalDir = getGlobalGslothDir();
+        const profileDir = resolve(globalDir, GSLOTH_SETTINGS_DIR, profile);
+        for (const filename of PROJECT_CONFIG_FORMATS) {
+            const candidate = resolve(profileDir, filename);
+            if (existsSync(candidate)) {
+                return candidate;
+            }
+        }
+        return undefined;
+    }
+    for (const dir of walkConfigSearchDirs()) {
+        const profileDir = resolve(dir, GSLOTH_DIR, GSLOTH_SETTINGS_DIR, profile);
+        for (const filename of PROJECT_CONFIG_FORMATS) {
+            const candidate = resolve(profileDir, filename);
+            if (existsSync(candidate)) {
+                return candidate;
+            }
         }
-        dir = parent;
     }
     return undefined;
 }
+/**
+ * CFG-36 — the ONE statement of "an explicitly-named identity profile that does not exist", shared
+ * by the run path ({@link initConfig}, which raises) and the read path ({@link validateConfig},
+ * which records a not-ok layer). Single-sourced deliberately: GS2-29's invariant is that
+ * `gth config validate` can never green-light a config a real run refuses, and two copies of this
+ * rule is exactly how that invariant rots.
+ *
+ * Returns the offending profile name, or `undefined` when there is nothing to complain about —
+ * no profile named (a blank/whitespace name counts as none, keeping the CFG-8 no-profile path
+ * untouched), an explicit `--config` path (which names the file to load and bypasses discovery),
+ * or a profile that resolves to its own config.
+ */
+function findUnresolvedExplicitProfile(commandLineConfigOverrides) {
+    const profile = commandLineConfigOverrides.identityProfile?.trim();
+    if (!profile || commandLineConfigOverrides.customConfigPath) {
+        return undefined;
+    }
+    return resolveIdentityProfileConfigPath(profile, {
+        globalOnly: commandLineConfigOverrides.global,
+    })
+        ? undefined
+        : profile;
+}
+/** The message both paths report for {@link findUnresolvedExplicitProfile}'s failure. */
+function identityProfileNotFoundMessage(profile, isGlobal = false) {
+    const base = isGlobal
+        ? globalProfileDirLabel(profile)
+        : `${GSLOTH_DIR}/${GSLOTH_SETTINGS_DIR}/${profile}/`;
+    return (`identity profile "${profile}" not found: no config file in ` +
+        `${base} ` +
+        `(checked ${PROJECT_CONFIG_FORMATS.join(', ')})`);
+}
 /**
  * Loads the global gsloth config (if present) from the global `~/.gsloth` folder.
  *
@@ -146,39 +342,63 @@ export function findProjectConfigPath(commandLineConfigOverrides) {
  * user-controlled layer (still above {@link DEFAULT_CONFIG}).
  *
  * Lookup order within the global folder, first match wins:
- *   `.gsloth.config.json` -> `.gsloth.config.js` -> `.gsloth.config.mjs`
+ *   `.gsloth.config.json` -> `.gsloth.config.jsonc` -> `.gsloth.config.js` -> `.gsloth.config.mjs`
  *
  * Absence of every variant is a no-op: returns `undefined` so behaviour is unchanged.
  *
  * NOTE: secrets (API keys) may live in this file; this function must never log its
  * contents. Only non-sensitive diagnostics (the resolved path / parse failure) are emitted.
  *
+ * @param options CFG-56 — `identityProfile` relocates the lookup to
+ * `~/.gsloth/.gsloth-settings/<name>/` and `globalOnly` scopes the profile names this layer refers
+ * to. Both are set ONLY for a `--global` run; see {@link globalLayerProfile}.
  * @returns The raw global config object, or `undefined` when no global config exists.
  */
-export async function loadGlobalRawConfig() {
-    // JSON first (the must-have format).
-    const jsonPath = getGlobalGslothConfigReadPath(USER_PROJECT_CONFIG_JSON);
-    if (existsSync(jsonPath)) {
-        try {
-            const parsed = parseJsonc(readFileSync(jsonPath, 'utf8'), `${USER_PROJECT_CONFIG_JSON} (global)`);
-            return validateRawConfigLayer(parsed, `${USER_PROJECT_CONFIG_JSON} (global)`);
-        }
-        catch (e) {
-            displayDebug(e instanceof Error ? e : String(e));
-            displayWarning(`Failed to read global config from ${jsonPath}, ignoring it.`);
-            return undefined;
+export async function loadGlobalRawConfig(options) {
+    const identityProfile = options?.identityProfile;
+    const scope = { globalOnly: options?.globalOnly };
+    // JSON/JSONC first (the must-have formats; `.json` wins when both exist — GS2-69).
+    for (const filename of JSON_CONFIG_FILENAMES) {
+        const jsonPath = getGlobalGslothConfigReadPath(filename, identityProfile);
+        if (existsSync(jsonPath)) {
+            const label = identityProfile
+                ? `${GSLOTH_SETTINGS_DIR}/${identityProfile}/${filename} (global)`
+                : `${filename} (global)`;
+            try {
+                const parsed = parseJsonc(readFileSync(jsonPath, 'utf8'), label);
+                return validateRawConfigLayer(parsed, label, scope);
+            }
+            catch (e) {
+                // CFG-36 — this catch exists to treat an UNREADABLE global as absent. A global that read
+                // fine and is MALFORMED is a hard configuration error (it used to `exit(1)` from inside
+                // the validator); swallowing it here would silently downgrade that to "ignoring it" and
+                // run under a different config — the exact false-green the throw was introduced to avoid.
+                if (isConfigDiscoveryError(e)) {
+                    throw e;
+                }
+                displayDebug(e instanceof Error ? e : String(e));
+                displayWarning(`Failed to read global config from ${jsonPath}, ignoring it.`);
+                return undefined;
+            }
         }
     }
     // Then JS / MJS variants (dynamic import of a `configure()` module).
     for (const filename of [USER_PROJECT_CONFIG_JS, USER_PROJECT_CONFIG_MJS]) {
-        const modulePath = getGlobalGslothConfigReadPath(filename);
+        const modulePath = getGlobalGslothConfigReadPath(filename, identityProfile);
         if (existsSync(modulePath)) {
+            const label = identityProfile
+                ? `${GSLOTH_SETTINGS_DIR}/${identityProfile}/${filename} (global)`
+                : `${filename} (global)`;
             try {
                 const imported = await importExternalFile(modulePath);
                 const configured = await imported.configure();
-                return validateRawConfigLayer(configured, `${filename} (global)`);
+                return validateRawConfigLayer(configured, label, scope);
             }
             catch (e) {
+                // CFG-36 — see the JSON branch above: a malformed global is a hard error, not an absent one.
+                if (isConfigDiscoveryError(e)) {
+                    throw e;
+                }
                 displayDebug(e instanceof Error ? e : String(e));
                 displayWarning(`Failed to read global config from ${modulePath}, ignoring it.`);
                 return undefined;
@@ -199,6 +419,155 @@ async function applyGlobalConfigBase(projectRawConfig) {
     }
     return deepMerge(globalRawConfig, projectRawConfig);
 }
+/**
+ * GS2-41 — hard cap on the `extends` chain length: a belt-and-suspenders backstop BEHIND the
+ * name-cycle guard. Even if a base name somehow failed to register in the visited chain, a chain
+ * this long is a misconfiguration and must fail fast rather than recurse without bound.
+ */
+const MAX_EXTENDS_CHAIN_DEPTH = 50;
+/**
+ * GS2-73 — the typed failure the `extends` traversal ({@link resolveExtendsChain}) raises on a
+ * cycle, a missing base, an over-deep chain, or an unreadable base. It carries the SAME clear,
+ * user-facing message the run path prints, so the two consumers can translate one shared failure
+ * into their own convention WITHOUT the traversal being forked or the checks duplicated:
+ *   - the run path ({@link resolveConfigExtends}) → re-raised as a {@link ConfigDiscoveryError}, so
+ *     the caller classifies it and chooses the exit code (CFG-36),
+ *   - the read path ({@link validateConfig}) → a `not-ok` layer with this message (collect, never
+ *     `exit`), so `gth config validate` mirrors what a real run would hit (GS2-29 invariant).
+ */
+class ConfigExtendsError extends Error {
+}
+/**
+ * GS2-41 — resolve a named profile's `extends` inheritance into a single composed raw config,
+ * riding the SAME GS2-1 deep-merge the config LAYERS use (NO second merge engine). When the given
+ * profile config declares `extends: "<base>"`, the base profile's config resolves FIRST
+ * (recursively — a base may itself extend another, so base-of-base resolves first), then this
+ * profile's own fields merge on top with last-wins semantics: the child overrides the base, nested
+ * objects merge, arrays REPLACE except the additive-array fields (`allowDirs`, `aiignore.patterns`
+ * and the three `approvals` rule lists, see {@link isAdditiveArrayField}) which accumulate
+ * base+child. The `extends` key itself is consumed and never leaks into the composed output.
+ *
+ * A config WITHOUT `extends` is returned UNCHANGED — every non-inheriting config (the vast
+ * majority) is untouched and behaves exactly as before.
+ *
+ * Composition is CONFINED to the profile-dir layer: it produces the single raw config that then
+ * acts as the project-file layer the global config underlays and CLI flags overlay, preserving
+ * GS2-33's outer precedence `CLI flags > profile (base+child composed) > global > defaults`. It is
+ * therefore invoked in {@link initConfig} on the loaded project/profile config BEFORE
+ * {@link applyGlobalConfigBase}.
+ *
+ * The base profile is discovered with {@link resolveIdentityProfileConfigPath} (the SAME strict
+ * up-tree profile walk `--profile` uses), so `extends` names a profile exactly as a user selects
+ * one; a name with no config dir is a hard, clearly-named error.
+ *
+ * CYCLE GUARD: the chain of profile NAMES is tracked (seeded with the selected profile's own name);
+ * because `extends` is single-valued the chain is linear, so a repeated name — `A extends B extends
+ * A`, or a self-extend — is an unambiguous cycle and fails fast with a clear error NAMING the cycle,
+ * never infinite-looping / stack-overflowing. A hard {@link MAX_EXTENDS_CHAIN_DEPTH} cap backstops
+ * it regardless of how the base path was derived.
+ *
+ * @param rawConfig   the just-loaded, schema-validated raw config that MAY declare `extends`.
+ * @param profileLabel the selected profile's own name (for cycle detection + messages); undefined
+ *                     for a plain (non-profile) project config.
+ */
+export async function resolveConfigExtends(rawConfig, profileLabel, options) {
+    try {
+        return await composeExtends(rawConfig, profileLabel, options);
+    }
+    catch (e) {
+        // GS2-73 — the traversal RAISES a {@link ConfigExtendsError} rather than exiting inline, so the
+        // read side ({@link validateConfig}) can report the same failure without terminating.
+        //
+        // CFG-36 — the RUN path re-raises it as a {@link ConfigDiscoveryError} instead of printing and
+        // calling `exit(1)`. A profile whose `extends` base is missing (or forms a cycle) is a bad
+        // profile exactly as a profile with no config at all is, and both must be classifiable by the
+        // caller: exiting here from inside a library collapses `gth eval`'s harness-error (exit 2) and
+        // product-failure (exit 1) contract onto the same code, which is the collapse this node exists
+        // to remove. The CLI's top-level guard prints the same message and exits 1, so what a person at
+        // a terminal sees is unchanged.
+        //
+        // The message already names the profile, the base and the cycle; the optional detail fields are
+        // deliberately left unset rather than guessed at. `identityProfile` means "the profile that did
+        // not resolve", which for a missing base referenced from another profile is the BASE, not the
+        // `profileLabel` in hand here — a wrong value would be worse than an absent one.
+        //
+        // CFG-47 — the original travels as `cause`. Re-raising by message alone made the
+        // {@link ConfigExtendsError} (and any stack under it) unrecoverable from the wrapper, so a
+        // consumer that wanted the underlying failure had only the rendered string. The in-repo sibling
+        // ({@link MissingProviderKeyError} in {@link tryJsonConfig}) already carries it.
+        if (e instanceof ConfigExtendsError) {
+            throw new ConfigDiscoveryError(e.message, {}, { cause: e });
+        }
+        throw e;
+    }
+}
+/**
+ * GS2-73 — seed the `extends` chain from the selected profile's own name and run the throwing
+ * traversal ({@link resolveExtendsChain}). Shared by BOTH consumers so the walk and its
+ * cycle/missing-base checks live in ONE place: the run-path {@link resolveConfigExtends} (which
+ * re-raises a {@link ConfigExtendsError} as a {@link ConfigDiscoveryError}) and the read-path
+ * {@link validateConfig} (which records it as a not-ok layer). Propagates the typed error to its
+ * caller; the caller owns the reporting convention.
+ */
+async function composeExtends(rawConfig, profileLabel, options) {
+    const seed = profileLabel?.trim();
+    return resolveExtendsChain(rawConfig, seed ? [seed] : [], options);
+}
+/**
+ * The recursive worker for {@link resolveConfigExtends}. `chain` is the ordered list of profile
+ * names already being resolved (the selected profile first, then each `extends` base as it is
+ * descended into) — used both for the name-based cycle guard and to render the cycle in the error.
+ *
+ * GS2-73 — on any hard failure (cycle, over-deep chain, missing base, unreadable base) it RAISES a
+ * {@link ConfigExtendsError} rather than printing + `exit`ing inline, so the same traversal serves
+ * both the run path and the read-side `validateConfig` (each translates the error its own way).
+ */
+async function resolveExtendsChain(rawConfig, chain, options) {
+    const baseName = typeof rawConfig.extends === 'string' ? rawConfig.extends.trim() : undefined;
+    if (!baseName) {
+        return rawConfig;
+    }
+    // Cycle guard (name-based): a base already present in the chain we are resolving loops back on
+    // itself. Fail fast, naming the cycle — never recurse without bound. GS2-73 — raise the shared
+    // {@link ConfigExtendsError}; the caller (run path vs. `validateConfig`) owns how it is surfaced.
+    if (chain.includes(baseName)) {
+        throw new ConfigExtendsError(`Profile inheritance cycle detected: ${[...chain, baseName].join(' -> ')}. ` +
+            `A profile's "extends" chain must not refer back to itself.`);
+    }
+    // Depth backstop behind the name guard — a chain this long can only be a misconfiguration.
+    if (chain.length >= MAX_EXTENDS_CHAIN_DEPTH) {
+        throw new ConfigExtendsError(`Profile inheritance chain exceeds the maximum depth of ${MAX_EXTENDS_CHAIN_DEPTH}: ` +
+            `${[...chain, baseName].join(' -> ')}. This is almost certainly a misconfiguration.`);
+    }
+    const basePath = resolveIdentityProfileConfigPath(baseName, options);
+    if (!basePath) {
+        const from = chain.length > 0 ? ` (referenced from "${chain[chain.length - 1]}")` : '';
+        const baseDir = options?.globalOnly
+            ? globalProfileDirLabel(baseName)
+            : `${GSLOTH_DIR}/${GSLOTH_SETTINGS_DIR}/${baseName}/`;
+        throw new ConfigExtendsError(`Profile "${baseName}" referenced by "extends"${from} was not found: no config file in ` +
+            `${baseDir} (checked ${PROJECT_CONFIG_FORMATS.join(', ')}).`);
+    }
+    let baseRaw;
+    try {
+        baseRaw = await readRawConfigAtPath(basePath);
+    }
+    catch (e) {
+        displayDebug(e instanceof Error ? e : String(e));
+        throw new ConfigExtendsError(`Failed to read base profile "${baseName}" from ${basePath}.`);
+    }
+    // Validate the base layer exactly as the project layer is validated (deprecated-shape reject,
+    // unknown-key warn, type-mismatch fail) so a broken base surfaces loudly rather than silently.
+    const validatedBase = validateRawConfigLayer(baseRaw, `${baseName} (extends base)`, options);
+    // Resolve the base's OWN extends first (base-of-base first), THEN merge this profile's delta on
+    // top via the existing GS2-1 deep-merge (child = source, so it wins; additive-array fields at the
+    // config root accumulate).
+    const resolvedBase = await resolveExtendsChain(validatedBase, [...chain, baseName], options);
+    // Consume `extends` so it never leaks into the composed output, then merge child over base.
+    const childDelta = { ...rawConfig };
+    delete childDelta.extends;
+    return deepMerge(resolvedBase, childDelta);
+}
 /**
  * ORDERING INVARIANT (GS2-11): detection ({@link hasProjectConfig}/{@link hasAnyConfig}) MUST run
  * before {@link initConfig} in a given process. Both resolve cwd-level candidates via
@@ -210,7 +579,7 @@ async function applyGlobalConfigBase(projectRawConfig) {
  * order is ever introduced, decouple discovery's cwd-branch from `getProjectDir()`.
  */
 /**
- * Returns true when a project-level config file (json/js/mjs) exists for the given
+ * Returns true when a project-level config file (json/jsonc/js/mjs) exists for the given
  * overrides. Honours `customConfigPath` and the active identity profile so the check
  * matches exactly what {@link initConfig} would attempt to load.
  *
@@ -222,7 +591,7 @@ export function hasProjectConfig(commandLineConfigOverrides) {
 }
 /**
  * CFG-10 — true when ANY usable configuration is present, either a project config file
- * (json/js/mjs) or a standalone global config (`~/.gsloth/.gsloth.config.*`). When this
+ * (json/jsonc/js/mjs) or a standalone global config (`~/.gsloth/.gsloth.config.*`). When this
  * returns false the caller should run the first-run dialog instead of erroring.
  *
  * Reuses CFG-8's project + global detection so the two paths can never disagree.
@@ -231,7 +600,81 @@ export async function hasAnyConfig(commandLineConfigOverrides) {
     if (hasProjectConfig(commandLineConfigOverrides)) {
         return true;
     }
-    return (await loadGlobalRawConfig()) !== undefined;
+    return ((await loadGlobalRawConfig({
+        identityProfile: globalLayerProfile(commandLineConfigOverrides),
+        globalOnly: commandLineConfigOverrides.global,
+    })) !== undefined);
+}
+/**
+ * CFG-37 — the layered value of the top-level `tui` config key, read BEFORE a session picks its
+ * surface. `chat`/`code` choose between the Ink TUI and the readline session in the app's
+ * `startSession` dispatcher, and each surface then loads its own config via {@link initConfig} — so
+ * at the moment of the choice there is no resolved {@link GthConfig} to consult, and this is the
+ * seam that supplies the one key the choice needs.
+ *
+ * Layering matches a run: the discovered PROJECT layer wins over the GLOBAL one, and a layer that
+ * does not set `tui` defers to the next rather than overriding it with `undefined`. A scalar needs
+ * no deep merge, so this reads the two layers and picks — it does not fork the merge engine.
+ *
+ * QUIET and fail-soft for the layers it reads ITSELF: it does not validate them and does not
+ * `exit` on a malformed one, because the caller runs moments before {@link initConfig}, which
+ * validates every layer and reports the very same problem — warning twice about one file is worse
+ * than not warning here. A failed read resolves to `undefined`, i.e. "nobody set it", and the
+ * surface auto-detects exactly as it does for a run with no config.
+ *
+ * ONE EXCEPTION, and it is deliberate: a `tui` may be INHERITED through a GS2-41 profile `extends`
+ * chain, so this walks that chain via the SHARED {@link resolveConfigExtends} rather than forking
+ * it — and that traversal owns its own reporting. It validates each base layer (so a base's own
+ * unknown-key warning can appear here as well as from `initConfig`) and hard-`exit`s on a cycle, a
+ * missing base or a malformed base. What the user sees is unchanged — `initConfig` exits on the
+ * same chain with the same message a moment later — but it now happens EARLIER, at surface
+ * selection rather than at config load. Forking the walk to silence it would mean a second
+ * inheritance engine; ignoring `extends` would mean silently dropping an inherited `tui`.
+ *
+ * Ordering: this is DETECTION, so per the GS2-11 invariant above it must run before any
+ * {@link initConfig} in the process — as it does, alongside {@link hasAnyConfig} in `startSession`.
+ */
+export async function loadConfiguredTui(commandLineConfigOverrides) {
+    const projectTui = await readProjectConfiguredTui(commandLineConfigOverrides);
+    if (projectTui !== undefined) {
+        return projectTui;
+    }
+    const globalRaw = await loadGlobalRawConfigUnvalidated(globalLayerProfile(commandLineConfigOverrides));
+    const globalTui = globalRaw?.raw.tui;
+    return typeof globalTui === 'boolean' ? globalTui : undefined;
+}
+/** The PROJECT layer's `tui`, or undefined when there is no project config or it does not set it. */
+async function readProjectConfiguredTui(commandLineConfigOverrides) {
+    const discovered = findProjectConfigPath(commandLineConfigOverrides);
+    if (!discovered) {
+        return undefined;
+    }
+    let raw;
+    try {
+        raw = await readRawConfigAtPath(discovered.path);
+    }
+    catch (e) {
+        // Quiet by design — see the note on loadConfiguredTui. initConfig reports this same file.
+        displayDebug(e instanceof Error ? e : String(e));
+        return undefined;
+    }
+    // GS2-41 — a named profile may inherit `tui` from the profile it extends, so compose the chain
+    // the way a run does, for EVERY config format. `initConfig` resolves `extends` on both of its
+    // branches (the JSON one below and {@link tryModuleConfig}), and `validateConfig` walks it with
+    // no format gate at all — so a format gate here would answer `undefined` for a `.js`/`.mjs`
+    // profile whose `tui` is inherited while the run composes it, which is precisely the
+    // reader-vs-run divergence this seam exists to prevent.
+    //
+    // Deliberately NOT inside the try above: a cycle, a missing base and a MALFORMED base all raise a
+    // {@link ConfigDiscoveryError} that must reach the top level to be reported. The try above exists
+    // to treat an unreadable config as "no configured tui"; extending it over these would swallow a
+    // hard configuration error and let the surface be selected from a config the run itself refuses
+    // to load. This reader runs BEFORE the TUI/readline choice, so the error surfaces here rather than
+    // through `createTuiSession` — either way it is reported once, by the CLI's top-level guard.
+    if (typeof raw.extends === 'string') {
+        raw = await resolveConfigExtends(raw, commandLineConfigOverrides.identityProfile);
+    }
+    return typeof raw.tui === 'boolean' ? raw.tui : undefined;
 }
 /**
  * Initialize configuration by loading from available config files
@@ -240,7 +683,13 @@ export async function hasAnyConfig(commandLineConfigOverrides) {
 export async function initConfig(commandLineConfigOverrides) {
     if (commandLineConfigOverrides.customConfigPath &&
         !existsSync(commandLineConfigOverrides.customConfigPath)) {
-        throw new Error(`Provided manual config "${commandLineConfigOverrides.customConfigPath}" does not exist`);
+        // CFG-47 — a {@link ConfigDiscoveryError}, not a plain `Error`. An explicitly named `-c` path
+        // that is not there is the same "this configuration cannot be used" failure as a named profile
+        // with no config, and it reaches the same two consumers: the CLI's top-level guard (prints the
+        // message, exits 1) and `gth eval` (harness error, exit 2). As a plain Error it was invisible to
+        // BOTH — it fell through the guard to the crash handler, so `gth -c <missing path> code` printed
+        // a false "TUI unavailable … falling back to the readline session" and then a crash snapshot.
+        throw new ConfigDiscoveryError(`Provided manual config "${commandLineConfigOverrides.customConfigPath}" does not exist`, { sourceLabel: commandLineConfigOverrides.customConfigPath });
     }
     // Clear the project root BEFORE discovery. Discovery and detection must resolve against cwd,
     // and the up-tree walk itself goes through getGslothConfigReadPath -> getProjectDir(); clearing
@@ -252,6 +701,26 @@ export async function initConfig(commandLineConfigOverrides) {
     // from cwd to the stop boundary (see findProjectConfigPath). Detection and loading share this
     // resolver, and the discovered dir becomes the base for the per-format cascade below.
     const discovered = findProjectConfigPath(commandLineConfigOverrides);
+    // GS2-62 / CFG-36 — an EXPLICITLY named identity profile (`-i <name>` / eval `--judge <name>`)
+    // must resolve to its OWN config; it must never silently run under some OTHER config. That is a
+    // false-green trap: `gth -i typo …` would run under the wrong model while appearing to use the
+    // named profile — in an authorization/eval context, hiding a real misconfiguration.
+    //
+    // Checked with the STRICT resolver, NOT with `discovered`. `findProjectConfigPath` deliberately
+    // falls back to a plain `<dir>/<config>` when the named profile has no config of its own (see its
+    // note, and the "Case C" spec in config.uptree.spec.ts), so gating on `!discovered` only catches
+    // the case where NO config exists anywhere — a project that has a plain config would sail past it
+    // and load that instead. `resolveIdentityProfileConfigPath` never falls through, which is what
+    // makes this check see the case the discovery gate cannot.
+    //
+    // The rule itself lives in findUnresolvedExplicitProfile, shared with `validateConfig` so the
+    // validator can never green-light a profile a run refuses (GS2-29).
+    const explicitProfile = findUnresolvedExplicitProfile(commandLineConfigOverrides);
+    if (explicitProfile) {
+        throw new ConfigDiscoveryError(identityProfileNotFoundMessage(explicitProfile, commandLineConfigOverrides.global), {
+            identityProfile: explicitProfile,
+        });
+    }
     const baseDir = discovered?.dir ?? getCurrentWorkDir();
     // Set the project root for post-config, project-relative artifact resolution (guidelines,
     // prompts, .gsloth-settings, outputs). up-tree and --config both set it here; a global-only /
@@ -259,51 +728,99 @@ export async function initConfig(commandLineConfigOverrides) {
     // Safe for the in-function load below: when discovered.dir === cwd getProjectDir() is unchanged,
     // and when it is an ancestor resolveConfigPath takes its explicit-dir branch (never getProjectDir).
     setProjectDir(discovered?.dir);
+    // GS2-69 — prefer the DISCOVERED path when it is a JSON-family file, so a discovered
+    // `.gsloth.config.jsonc` reaches the parseJsonc branch below (re-resolving only the `.json`
+    // name here would miss it). When discovery found a module config (or nothing), fall back to
+    // resolving the `.json` name — it won't exist, so the module fall-through below is unchanged.
+    const discoveredJsonConfigPath = discovered && isJsonConfigPath(discovered.path) ? discovered.path : undefined;
     const jsonConfigPath = commandLineConfigOverrides.customConfigPath ??
+        discoveredJsonConfigPath ??
         resolveConfigPath(baseDir, USER_PROJECT_CONFIG_JSON, commandLineConfigOverrides.identityProfile);
     // CFG-8 — when no project config file of any format exists (anywhere up-tree), fall back to a
     // standalone global config (loaded alone) before erroring. Project config still takes
     // precedence: this branch only runs when there is no project file to apply the global under.
     if (!discovered) {
-        const globalRawConfig = await loadGlobalRawConfig();
+        // The explicitly-named-profile guard that used to sit here now runs BEFORE discovery is
+        // consulted at all (see above), because gating it on `!discovered` missed the case where a
+        // plain project config exists. A run with no profile reaches the global fallback below exactly
+        // as before.
+        const globalRawConfig = await loadGlobalRawConfig({
+            identityProfile: globalLayerProfile(commandLineConfigOverrides),
+            globalOnly: commandLineConfigOverrides.global,
+        });
         if (globalRawConfig) {
-            if (globalRawConfig.llm &&
-                typeof globalRawConfig.llm === 'object' &&
-                'type' in globalRawConfig.llm) {
+            let resolvedRawConfig = globalRawConfig;
+            if (typeof resolvedRawConfig.extends === 'string') {
+                resolvedRawConfig = (await resolveConfigExtends(resolvedRawConfig, globalLayerProfile(commandLineConfigOverrides), { globalOnly: commandLineConfigOverrides.global }));
+            }
+            if (resolvedRawConfig.llm &&
+                typeof resolvedRawConfig.llm === 'object' &&
+                'type' in resolvedRawConfig.llm) {
                 // Route the global config through the same path the project JSON uses.
-                return await tryJsonConfig(globalRawConfig, commandLineConfigOverrides);
+                return await tryJsonConfig(resolvedRawConfig, commandLineConfigOverrides);
             }
-            displayError('Global configuration found but it is not in valid format. Should at least define llm.type');
-            exit(1);
-            // Unreachable past exit(1) in production; keeps TS happy and prevents test exit.
-            throw new Error('Unexpected error occurred.');
+            // CFG-47 — a global config that read fine and does not define `llm.type` is "config present
+            // and unusable", the same class CFG-36 converted: raise it, let the caller choose the exit
+            // code. The message is the one this branch has always printed, so the CLI's top-level guard
+            // reproduces the previous output exactly.
+            const globalProfile = globalLayerProfile(commandLineConfigOverrides);
+            const sourceLabel = globalProfile
+                ? `${GSLOTH_SETTINGS_DIR}/${globalProfile}/${USER_PROJECT_CONFIG_JSON} (global)`
+                : `${USER_PROJECT_CONFIG_JSON} (global)`;
+            throw new ConfigDiscoveryError('Global configuration found but it is not in valid format. Should at least define llm.type', { sourceLabel });
+        }
+        if (commandLineConfigOverrides.global) {
+            throw new ConfigDiscoveryError('No configuration file found. Please create one in ~/.gsloth.');
         }
     }
-    // Try loading the JSON config file first
-    if (jsonConfigPath.endsWith('.json') && existsSync(jsonConfigPath)) {
+    // Try loading the JSON/JSONC config file first (GS2-69 — an explicit `-c foo.jsonc` takes
+    // this branch too instead of falling into the `configure()`-module importer).
+    if (isJsonConfigPath(jsonConfigPath) && existsSync(jsonConfigPath)) {
+        const jsonConfigName = jsonConfigPath.endsWith('.jsonc')
+            ? USER_PROJECT_CONFIG_JSONC
+            : USER_PROJECT_CONFIG_JSON;
         try {
             // Validate the project config layer against the Zod schema (single source of
             // truth): pre-map deprecated names, warn on unknown top-level keys, and fail
             // with a friendly, path-scoped message on a genuine type mismatch.
-            const projectJsonConfig = validateRawConfigLayer(parseJsonc(readFileSync(jsonConfigPath, 'utf8'), USER_PROJECT_CONFIG_JSON), USER_PROJECT_CONFIG_JSON);
+            const projectJsonConfig = validateRawConfigLayer(parseJsonc(readFileSync(jsonConfigPath, 'utf8'), jsonConfigName), jsonConfigName);
+            // GS2-41 — compose profile inheritance (`extends`) WITHIN the profile-dir layer BEFORE the
+            // global base underlays it, so precedence stays CLI > profile(base+child) > global > defaults.
+            // No-op (returns the config unchanged) when there is no `extends`.
+            const composedProjectConfig = (await resolveConfigExtends(projectJsonConfig, commandLineConfigOverrides.identityProfile));
             // Apply global config as the base layer (project config wins on conflicts).
-            const jsonConfig = (await applyGlobalConfigBase(projectJsonConfig));
+            const jsonConfig = (await applyGlobalConfigBase(composedProjectConfig));
             // If the config has an LLM with a type, create the appropriate LLM instance
             if (jsonConfig.llm && typeof jsonConfig.llm === 'object' && 'type' in jsonConfig.llm) {
                 return await tryJsonConfig(jsonConfig, commandLineConfigOverrides);
             }
             else {
-                error(`${jsonConfigPath} is not in valid format. Should at least define llm.type`);
-                exit(1);
-                // noinspection ExceptionCaughtLocallyJS
-                // This throw is unreachable due to exit(1) above, but satisfies TS type analysis and prevents tests from exiting
+                // CFG-47 — same class, same treatment. Deliberately a ConfigDiscoveryError and not a plain
+                // one: the catch below re-raises this class and swallows everything else into the next
+                // FORMAT, so a plain throw here would silently fall through to the module loader and end in
+                // the terminal "No configuration file found" — hiding the real, clearly-worded problem.
                 // noinspection ExceptionCaughtLocallyJS
-                throw new Error('Unexpected error occurred.');
+                throw new ConfigDiscoveryError(`${jsonConfigPath} is not in valid format. Should at least define llm.type`, { sourceLabel: jsonConfigName });
             }
         }
         catch (e) {
+            // CFG-35 — the format fall-through must not swallow a resolvable-config-but-no-API-key
+            // failure. This catch exists to move on to the next config FORMAT when the JSON layer could
+            // not be read; a config that read fine and named a provider we have no key for is not a
+            // read failure, and falling through would end in the terminal "No configuration file found"
+            // failure — which blames a missing config for what is actually a missing key, burying the
+            // clearly-worded message this branch already has.
+            if (isMissingProviderKeyError(e)) {
+                throw e;
+            }
+            // CFG-36 — same reasoning for a MALFORMED config: the config read fine and is invalid, which
+            // is a hard error the user must see. Falling through to the next FORMAT would end in the
+            // terminal "No configuration file found" failure, hiding the real (clearly-worded) problem.
+            if (isConfigDiscoveryError(e)) {
+                throw e;
+            }
             displayDebug(e instanceof Error ? e : String(e));
-            displayError(`Failed to read config from ${USER_PROJECT_CONFIG_JSON}, will try other formats.`);
+            displayError(`Failed to read config from ${jsonConfigName}, will try other formats.`);
             // Continue to try other formats
             return await tryModuleConfig('js', commandLineConfigOverrides, baseDir);
         }
@@ -335,7 +852,8 @@ const MODULE_CONFIG_EXT = {
  * `tryJsConfig`/`tryMjsConfig` helpers into one format-parameterized loader.
  *
  * NOTE: the terminal "No configuration file found" message intentionally advertises only
- * json/js/mjs (the historical, asserted wording) — `.ts` is a quiet lowest-precedence fallback.
+ * json/js/mjs (the historical, asserted wording) — `.ts` is a quiet lowest-precedence fallback,
+ * and `.jsonc` (GS2-69) is a quiet spelling variant of the advertised `.json`.
  */
 async function tryModuleConfig(format, commandLineConfigOverrides, baseDir) {
     const filename = MODULE_CONFIG_FILENAME[format];
@@ -347,19 +865,31 @@ async function tryModuleConfig(format, commandLineConfigOverrides, baseDir) {
         try {
             const i = await importExternalFile(configPath);
             const customConfig = validateRawConfigLayer((await i.configure()), filename);
-            const mergedWithGlobal = await applyGlobalConfigBase(customConfig);
+            // GS2-41 — compose profile inheritance (`extends`) before the global base underlays it
+            // (parity with the JSON branch); no-op when there is no `extends`.
+            const composedConfig = await resolveConfigExtends(customConfig, commandLineConfigOverrides.identityProfile);
+            const mergedWithGlobal = await applyGlobalConfigBase(composedConfig);
             return await mergeConfig(mergedWithGlobal, commandLineConfigOverrides);
         }
         catch (e) {
+            // CFG-36 — a config that read fine and is MALFORMED (or names an unresolvable profile) is a
+            // hard error, not a reason to try the next format. Re-raise before the fall-through, exactly
+            // as the JSON branch in initConfig does.
+            if (isConfigDiscoveryError(e)) {
+                throw e;
+            }
             displayDebug(e instanceof Error ? e : String(e));
             if (nextFormat) {
                 displayError(`Failed to read config from ${filename}, will try other formats.`);
                 // Continue to try other formats
                 return await tryModuleConfig(nextFormat, commandLineConfigOverrides, baseDir);
             }
-            displayError(`Failed to read config from ${filename}.`);
-            displayError(`No valid configuration found. Please create a valid configuration file.`);
-            exit(1);
+            // CFG-47 — the last format in the chain failed to read. The config IS present and cannot be
+            // used, so this raises like the rest of the class. Both lines are kept in the one message:
+            // the first names the file that failed, the second is the advice, and the guard prints them
+            // together exactly as the two `displayError` calls did.
+            throw new ConfigDiscoveryError(`Failed to read config from ${filename}.\n` +
+                `No valid configuration found. Please create a valid configuration file.`, { sourceLabel: filename });
         }
     }
     else if (nextFormat) {
@@ -367,14 +897,19 @@ async function tryModuleConfig(format, commandLineConfigOverrides, baseDir) {
         return await tryModuleConfig(nextFormat, commandLineConfigOverrides, baseDir);
     }
     else {
-        // No config files found
-        displayError('No configuration file found. Please create one of: ' +
+        // No config files found.
+        //
+        // CFG-47 — the terminal "nothing to load" exit, raised rather than exited. It is the same class
+        // for the same reason as the rest: the caller must classify it. `gth eval` in particular needs
+        // "the harness has no config" to be a harness error (exit 2), not the exit 1 that means the SUT
+        // ran and failed. The CLI's top-level guard prints this message and exits 1, so a person at a
+        // terminal sees exactly what they saw before — and `startSession` still runs the first-run
+        // dialog ahead of this on an interactive TTY with no config anywhere (CFG-10), so the ordinary
+        // unconfigured path never reaches here.
+        throw new ConfigDiscoveryError('No configuration file found. Please create one of: ' +
             `${USER_PROJECT_CONFIG_JSON}, ${USER_PROJECT_CONFIG_JS}, or ${USER_PROJECT_CONFIG_MJS} ` +
             'in your project directory.');
-        exit(1);
     }
-    // This throw is unreachable due to exit(1) above, but satisfies TS type analysis and prevents tests from exiting
-    throw new Error('Unexpected error occurred.');
 }
 /**
  * Process JSON LLM config by creating the appropriate LLM instance
@@ -388,8 +923,12 @@ export async function tryJsonConfig(jsonConfig, commandLineConfigOverrides) {
             // Get the type of LLM (e.g. 'vertexai', 'anthropic') - this should exist
             const llmType = jsonConfig.llm.type;
             if (!llmType) {
-                displayError('LLM type not specified in config.');
-                exit(1);
+                // CFG-47 — same class, raised rather than exited. Note this throw is caught by THIS
+                // function's own catch below, which re-raises the class before its "Error processing LLM
+                // config" wrapper; without that re-raise the clear message here would be re-worded and then
+                // exited on anyway.
+                // noinspection ExceptionCaughtLocallyJS
+                throw new ConfigDiscoveryError('LLM type not specified in config.');
             }
             // Get the configuration for the specific LLM type
             const llmConfig = jsonConfig.llm;
@@ -397,6 +936,12 @@ export async function tryJsonConfig(jsonConfig, commandLineConfigOverrides) {
                 // Necessary to avoid https://github.com/langchain-ai/langchainjs/issues/8705
                 llmConfig.verbose = commandLineConfigOverrides.verbose;
             }
+            if (commandLineConfigOverrides.model) {
+                // BATCH-1 fix — see CommandLineConfigOverrides.model: retarget the raw LLM *spec* before
+                // the provider builds an instance from it, rather than cloning/mutating an already-built
+                // instance. `gth batch --models` is the only current caller.
+                llmConfig.model = commandLineConfigOverrides.model;
+            }
             // Import the appropriate config module
             const configModule = await import(`#src/providers/${llmType}.js`);
             if (configModule.processJsonConfig) {
@@ -410,26 +955,63 @@ export async function tryJsonConfig(jsonConfig, commandLineConfigOverrides) {
                 }
             }
             else {
-                displayWarning(`Config module for ${llmType} does not have processJsonConfig function.`);
-                exit(1);
+                // CFG-47 — the node called this site the one that is "genuinely a different case". Measured,
+                // it is not: `#src/providers/<type>.js` resolves against the SAME directory that holds five
+                // real modules with no `processJsonConfig` export (modelCatalog, modelDiscovery,
+                // geminiThinking, geminiSchemaSanitizer, configurationPassthrough), so `llm.type:
+                // "modelCatalog"` reaches here from an ordinary config file — verified by resolving that
+                // specifier at runtime. It is therefore user-reachable "config present and unusable" like
+                // the rest, and is converted with them. Kept on the warning wording it has always had.
+                // noinspection ExceptionCaughtLocallyJS
+                throw new ConfigDiscoveryError(`Config module for ${llmType} does not have processJsonConfig function.`);
             }
         }
         else {
-            displayError('No LLM configuration found in config.');
-            exit(1);
+            // noinspection ExceptionCaughtLocallyJS
+            throw new ConfigDiscoveryError('No LLM configuration found in config.');
         }
     }
     catch (e) {
+        // CFG-47 — the four sites above raise INTO this catch, so it must re-raise the class before its
+        // own wrapper reaches them. Without this, a clear "LLM type not specified in config." would be
+        // re-worded as "Error processing LLM config: …" and exited on anyway — the local catch would
+        // undo the conversion three lines after it happened. Same shape as the re-raises in
+        // `initConfig` and `tryModuleConfig`.
+        if (isConfigDiscoveryError(e)) {
+            throw e;
+        }
         if (e instanceof Error && e.message.includes('Cannot find module')) {
-            displayError(`LLM type '${jsonConfig.llm.type}' not supported.`);
+            // CFG-47 — a configured `llm.type` we have no provider module for is a config error, not a
+            // process exit. `{ cause: e }` keeps the resolver's own failure reachable.
+            throw new ConfigDiscoveryError(`LLM type '${jsonConfig.llm.type}' not supported.`, {}, { cause: e });
         }
         else {
-            displayError(`Error processing LLM config: ${e instanceof Error ? e.message : String(e)}`);
+            const message = `Error processing LLM config: ${e instanceof Error ? e.message : String(e)}`;
+            // CFG-35 — a provider that could not be built because NO API key is resolvable for it is a
+            // CATCHABLE error, not a process exit. Several provider SDKs validate the key in their
+            // constructor (groq, anthropic, xai, deepseek, openrouter) and two of our factories check it
+            // themselves (openrouter, huggingface); every one of those throws landed here and killed the
+            // process, so a multi-identity `gth eval` run — the case that is DESIGNED for partial
+            // secrets — lost every other identity's result and wrote no artifacts at all.
+            //
+            // Whether this is a missing key is decided from the environment, never from the SDK's
+            // wording (see findMissingProviderKey). Imported dynamically because it is an error-path
+            // question and a static import of the provider layer would put a cycle through the config
+            // barrel. The message is exactly the string this branch has always printed, so a caller that
+            // reports `error.message` produces the same output; the provider and variable names ride as
+            // FIELDS, which is what a report consumer needs to tell a missing key from an outage.
+            const { findMissingProviderKey } = await import('#src/providers/modelDiscovery.js');
+            const missingKey = findMissingProviderKey(jsonConfig.llm?.type, jsonConfig.llm);
+            if (missingKey) {
+                throw new MissingProviderKeyError(message, missingKey, { cause: e });
+            }
+            // CFG-47 — and when it is NOT a missing key, raise too. This site's immediate neighbour three
+            // lines up already threw, so the file disagreed with itself about whether a provider that
+            // could not be built terminates the process; it does not. The message is unchanged and
+            // `{ cause: e }` keeps the provider's own error reachable, as the missing-key branch does.
+            throw new ConfigDiscoveryError(message, {}, { cause: e });
         }
-        exit(1);
     }
-    // This throw is unreachable due to exit(1) above, but satisfies TS type analysis and prevents tests from exiting
-    throw new Error('Unexpected error occurred.');
 }
 /**
  * Config array fields whose values ADD UP across merge layers (global → project): the
@@ -441,33 +1023,96 @@ export async function tryJsonConfig(jsonConfig, commandLineConfigOverrides) {
  * REPLACE semantics, because those express "this is THE set" and silently unioning them across
  * global + project would surprise users.
  *
- * | array field          | policy   | rationale                                            |
- * | -------------------- | -------- | ---------------------------------------------------- |
- * | `allowDirs`          | ADDITIVE | extra sandbox roots accumulate across layers         |
- * | `aiignore.patterns`  | ADDITIVE | ignore patterns accumulate across layers             |
- * | `allowedTools`       | replace  | the explicit allow-list IS the set                   |
- * | `builtInTools`       | replace  | the explicit tool selection IS the set               |
- * | `tools`              | replace  | live tool instances; union would be surprising       |
- * | `middleware`         | replace  | ordered pipeline; union would reorder/duplicate      |
- * | `binaryFormats`      | replace  | the declared format policy IS the set                |
- * | (every other array)  | replace  | default; preserves historical behaviour              |
- *
- * NOTE: the additive fields only live at the config ROOT, so only the
- * `applyGlobalConfigBase(global, project)` merge can trigger them; the per-command
- * `deepMerge` calls start at command scope and never reach these paths.
+ * | array field                     | policy   | rationale                                     |
+ * | ------------------------------- | -------- | --------------------------------------------- |
+ * | `allowDirs`                     | ADDITIVE | extra sandbox roots accumulate across layers  |
+ * | `aiignore.patterns`             | ADDITIVE | ignore patterns accumulate across layers      |
+ * | `approvals.deny`/`escalate`     | ADDITIVE | see {@link isAdditiveArrayField}              |
+ * | `approvals.allow`               | replace  | a PERMISSIVE list; see the same doc           |
+ * | `allowedTools`                  | replace  | the explicit allow-list IS the set            |
+ * | `builtInTools`                  | replace  | the explicit tool selection IS the set        |
+ * | `tools`                         | replace  | live tool instances; union would be surprising|
+ * | `middleware`                    | replace  | ordered pipeline; union would reorder/duplicate|
+ * | `binaryFormats`                 | replace  | the declared format policy IS the set         |
+ * | (every other array)             | replace  | default; preserves historical behaviour       |
+ *
+ * NOTE: these keys only live at the config ROOT, so they are triggered only by the `deepMerge`
+ * calls that START at the config root (path === ''). There are TWO such sites: the
+ * `applyGlobalConfigBase(global, project)` merge, and — as of GS2-41 — the root-level `deepMerge`
+ * inside {@link resolveConfigExtends} that composes an `extends` base with its child profile. The
+ * per-command `deepMerge` calls start at command scope and never reach these paths.
  *
  * NAMESPACE CAVEAT: these keys are config-ROOT-relative, but the per-command
  * `deepMerge(DEFAULT_CONFIG.commands.X, …)` calls also start at `path === ''`. No command
  * default carries `allowDirs`/`aiignore`, so there is no collision today — but do NOT add a
- * key here that could also appear as a per-command field, or it would silently become additive
- * inside command merges too.
+ * key to THIS SET that could also appear as a per-command field, or it would silently become
+ * additive inside command merges too. The approvals RESTRICTIVE lists are the deliberate exception
+ * and are therefore matched by path SHAPE ({@link isAdditiveArrayField}) rather than listed here:
+ * for them, additive at every scope is the rule and not an accident.
  */
 const ADDITIVE_ARRAY_FIELDS = new Set(['allowDirs', 'aiignore.patterns']);
+/**
+ * §9.1/§11.1f — the approvals **restrictive** lists, wherever they appear. `deny` and `escalate`
+ * are PROHIBITIONS, and a prohibition another config layer can quietly delete is not a hardline:
+ * §3's "an appended entry can never perturb an existing outcome" has to hold across layers or it
+ * holds nowhere. So they add up rather than replace, and no layer can narrow another's.
+ *
+ * Matched by path SHAPE rather than by an exact root-relative path, because `approvals` is settable
+ * at the root AND per command — `commands.code.approvals.deny` has to add up across the global and
+ * project layers for exactly the same reason `approvals.deny` does, and listing only the root path
+ * would leave the identical silent loss one keystroke away.
+ *
+ * **`allow` is deliberately NOT here, and adding it would be a security regression.** It is the
+ * PERMISSIVE list, so it keeps the default REPLACE policy: a layer that states its own `allow`
+ * replaces the layer below, and one that says nothing inherits. §3.1's cost asymmetry is why the
+ * three lists do not share a policy — a missed allow entry escalates and a missed deny entry
+ * reaches the rater, but a too-broad allow entry runs, unrated and unprompted. Unioning the
+ * restrictive lists fails toward a prompt; unioning the permissive one fails toward an execution.
+ */
+const APPROVAL_RESTRICTIVE_LIST_PATH = /(^|\.)approvals\.(deny|escalate)$/;
+/** Whether the array at this dotted path accumulates across layers instead of being replaced. */
+function isAdditiveArrayField(fieldPath) {
+    return ADDITIVE_ARRAY_FIELDS.has(fieldPath) || APPROVAL_RESTRICTIVE_LIST_PATH.test(fieldPath);
+}
+/** The `approvals` block itself, at the root or on any command. */
+const APPROVALS_BLOCK_PATH = /(^|\.)approvals$/;
+/**
+ * §9.1 — the `approvals` value is a union, and **the scalar rung is exactly sugar for
+ * `{ mode: <rung> }`**. Expanded at merge time so a layer that spells its rung the friendly way
+ * still merges field-wise: left as a string, a project config's `"approvals": "bypass"` simply
+ * overwrites the global's object and discards that layer's rule lists — the same silent loss
+ * {@link APPROVAL_RESTRICTIVE_LIST_PATH} exists to prevent, reached by a different route. It
+ * matters for the permissive list too, in the other direction: without the expansion a bare rung
+ * would silently drop the lower layer's `allow` rather than inheriting it.
+ */
+function expandApprovalsScalar(value) {
+    return typeof value === 'string' ? { mode: value } : value;
+}
+/**
+ * Whether two layers' `approvals` values have to be merged FIELD-WISE rather than one replacing the
+ * other. True only when both layers set the key AND at least one of them is the object form — i.e.
+ * only when there is a field that replacement would lose.
+ *
+ * Deliberately narrow, because expanding the scalar changes the value's SHAPE: a config that is the
+ * only one to declare `approvals`, and two layers that both spell it as a bare rung, keep the exact
+ * value the user wrote, so `gth config print` and the `/config` panel do not churn for the
+ * overwhelmingly common cases.
+ */
+function approvalsNeedFieldWiseMerge(sourceValue, targetValue) {
+    if (sourceValue === undefined || targetValue === undefined)
+        return false;
+    return typeof sourceValue === 'object' || typeof targetValue === 'object';
+}
 /**
  * Deep merge two objects, with source overriding target properties.
  * Objects are merged recursively. Arrays REPLACE by default; arrays at an
- * {@link ADDITIVE_ARRAY_FIELDS} path are concatenated (target-first) then de-duplicated by
+ * {@link isAdditiveArrayField} path are concatenated (target-first) then de-duplicated by
  * value. Every other non-plain-object value is replaced by the source value.
+ *
+ * The de-duplication is by VALUE identity (a `Set`), so it removes repeated primitives and leaves
+ * structurally-equal objects — an approvals rule entry written in two layers — both in place. That
+ * is correct rather than merely tolerable: a duplicate entry cannot change a most-restrictive-wins
+ * outcome, and a deep-equality pass could.
  * @param target - The target object with default values (lower-precedence layer)
  * @param source - The source object with user overrides (higher-precedence layer)
  * @param path - Dotted path from the config root, used to look up the array merge policy.
@@ -479,9 +1124,13 @@ function deepMerge(target, source, path = '') {
         return source;
     const result = { ...target };
     for (const key in source) {
-        const sourceValue = source[key];
-        const targetValue = target[key];
         const fieldPath = path ? `${path}.${key}` : key;
+        // §9.1 — normalize the `approvals` scalar/object union to its object form when (and only when)
+        // a field would otherwise be lost, so the merge below is field-wise rather than a bare string
+        // clobbering a block that carries the user's rule lists.
+        const mergeApprovalsFieldWise = APPROVALS_BLOCK_PATH.test(fieldPath) && approvalsNeedFieldWiseMerge(source[key], target[key]);
+        const sourceValue = mergeApprovalsFieldWise ? expandApprovalsScalar(source[key]) : source[key];
+        const targetValue = mergeApprovalsFieldWise ? expandApprovalsScalar(target[key]) : target[key];
         if (sourceValue &&
             typeof sourceValue === 'object' &&
             !Array.isArray(sourceValue) &&
@@ -493,7 +1142,7 @@ function deepMerge(target, source, path = '') {
         }
         else if (Array.isArray(sourceValue) &&
             Array.isArray(targetValue) &&
-            ADDITIVE_ARRAY_FIELDS.has(fieldPath)) {
+            isAdditiveArrayField(fieldPath)) {
             // Additive list: concat both layers (target/lower-precedence first), de-dupe by value.
             result[key] = [...new Set([...targetValue, ...sourceValue])];
         }
@@ -504,16 +1153,80 @@ function deepMerge(target, source, path = '') {
     }
     return result;
 }
+/**
+ * Command-scoped fields whose effective value is picked by PRECEDENCE — one layer wins wholesale
+ * (a per-command value REPLACES rather than extends the top-level one; none is in
+ * {@link ADDITIVE_ARRAY_FIELDS}). {@link resolvePrecedencePickedField} bakes the correct value into
+ * every command inside {@link resolveConfig}, so `getEffectiveConfig`'s later per-command-vs-root
+ * ternary reads an already-resolved value.
+ *
+ * GS2-60 — historically these were resolved ONLY at agent-build time (`getEffectiveConfig`), across
+ * two layers (per-command value vs top-level value) AFTER `DEFAULT_CONFIG` had been merged in. That
+ * made an explicit top-level value lose to a per-command DEFAULT: once merged, a command's
+ * `filesystem` is always defined (from its `'read'`/`'all'` default), so the ternary always took it
+ * and never fell through to the user's explicit top-level `filesystem`. Resolving here against the
+ * RAW (pre-default) config — where "user set it" is still distinguishable from "it's a default" —
+ * is the single correct site. Only `filesystem` is actually affected today (the sole field with
+ * per-command defaults); the other three are baked in identically for principled future-proofing.
+ */
+const PRECEDENCE_PICKED_COMMAND_FIELDS = [
+    'filesystem',
+    'builtInTools',
+    'allowedTools',
+    'binaryFormats',
+];
+/**
+ * Resolve one {@link PRECEDENCE_PICKED_COMMAND_FIELDS} field for one command against the RAW
+ * (pre-{@link DEFAULT_CONFIG}) config, highest precedence first:
+ *
+ *   1. per-command explicit : `rawConfig.commands[command][field]`
+ *   2. top-level explicit    : `rawConfig[field]`
+ *   3. per-command default   : `DEFAULT_CONFIG.commands[command][field]`
+ *   4. top-level default     : `DEFAULT_CONFIG[field]`
+ *
+ * `!== undefined` at every layer so a falsy-but-EXPLICIT value (`'none'`, `[]`, `false`, `0`) is
+ * honoured and never mistaken for a "missing" layer. Returns `undefined` only when no layer sets
+ * the field (e.g. `allowedTools`/`binaryFormats` with neither a user value nor any default), in
+ * which case the caller leaves the command key absent — matching prior behaviour.
+ */
+function resolvePrecedencePickedField(rawConfig, command, field) {
+    const rawCommands = rawConfig.commands;
+    const perCommandExplicit = rawCommands?.[command]?.[field];
+    if (perCommandExplicit !== undefined)
+        return perCommandExplicit;
+    const topLevelExplicit = rawConfig[field];
+    if (topLevelExplicit !== undefined)
+        return topLevelExplicit;
+    const perCommandDefault = DEFAULT_CONFIG.commands[command]?.[field];
+    if (perCommandDefault !== undefined)
+        return perCommandDefault;
+    return DEFAULT_CONFIG[field];
+}
 /**
  * Resolve a fully-merged {@link GthConfig} from a partial config + CLI overrides WITHOUT
- * any global side effects (a pure transform). It deep-merges defaults, applies CLI overrides,
- * resolves the numeric `consoleLevel` (warning + defaulting to INFO on an invalid value), and
- * computes `canInterruptInferenceWithEsc`. The process-global setters (`setUseColour` /
+ * any global side effects. It deep-merges defaults, applies CLI overrides, resolves the numeric
+ * `consoleLevel` (warning + defaulting to INFO on an invalid value), and computes
+ * `canInterruptInferenceWithEsc` and `useColour`. The process-global setters (`setUseColour` /
  * `setConsoleLevel`) are applied separately by {@link mergeConfig}, so this function can be
  * reasoned about and reused without touching global state.
+ *
+ * It WRITES nothing globally, but it does READ the environment: `canInterruptInferenceWithEsc`
+ * consults stdin's TTY status, and (CFG-30) `useColour` consults `FORCE_COLOR`, `NO_COLOR` and
+ * stdout's TTY status. So it is deterministic for a given environment rather than a pure function
+ * of its arguments — a test that pins a resolved config should declare the terminal and the colour
+ * environment it expects in its setup. The ladder itself is a pure helper
+ * ({@link resolveUseColour}) so it can be tested rung by rung without process globals.
  */
 export function resolveConfig(partialConfig, commandLineConfigOverrides) {
     const config = partialConfig;
+    // CFG-30 — capture whether the user set `useColour` AT ALL, while the config is still raw.
+    // `DEFAULT_CONFIG.useColour` is merged in below, after which an explicit `true` and the default
+    // `true` are the same value and rung 3 can no longer be told from rung 4. Read it here or lose it.
+    const explicitUseColour = config?.useColour;
+    // TUI-C37 — the same pre-merge capture for `useMouse`, and for the same reason: once
+    // `DEFAULT_CONFIG.useMouse` is merged in, "the user asked for it" and "nobody said" are the same
+    // value and the ladder's config rung can no longer be distinguished from its default rung.
+    const explicitUseMouse = config?.useMouse;
     // Deep merge command configs while preserving defaults
     // Type complexity from DEFAULT_CONFIG.commands 'as const' requires any cast for deep merge result
     const mergedCommands = {
@@ -525,6 +1238,28 @@ export function resolveConfig(partialConfig, commandLineConfigOverrides) {
         chat: deepMerge(DEFAULT_CONFIG.commands.chat, config?.commands?.chat), // eslint-disable-line @typescript-eslint/no-explicit-any
         api: deepMerge(DEFAULT_CONFIG.commands.api, config?.commands?.api), // eslint-disable-line @typescript-eslint/no-explicit-any
     };
+    // GS2-60 — bake the correct 4-layer precedence for the precedence-picked fields
+    // (filesystem/builtInTools/allowedTools/binaryFormats) into each command, resolved against the
+    // RAW `config` (still pre-DEFAULT_CONFIG here). The per-command `deepMerge` above only ranks
+    // per-command explicit vs per-command DEFAULT and cannot see the user's explicit top-level value
+    // — so without this an explicit top-level `filesystem` was silently lost to a command's default.
+    // A fresh `{ ...base, ...overrides }` per command is REQUIRED: `deepMerge` returns the live
+    // `DEFAULT_CONFIG.commands[cmd]` reference verbatim when the user configured nothing for that
+    // command, so in-place mutation would corrupt the shared default across every subsequent call.
+    const commandsRecord = mergedCommands;
+    for (const command of Object.keys(commandsRecord)) {
+        const base = commandsRecord[command];
+        const overrides = {};
+        for (const field of PRECEDENCE_PICKED_COMMAND_FIELDS) {
+            const resolved = resolvePrecedencePickedField(config, command, field);
+            // Leave the key absent when no layer set it (preserves prior behaviour for e.g. a command
+            // with no allowedTools anywhere), rather than writing an explicit `undefined`.
+            if (resolved !== undefined) {
+                overrides[field] = resolved;
+            }
+        }
+        commandsRecord[command] = { ...base, ...overrides };
+    }
     const mergedConfig = {
         ...DEFAULT_CONFIG,
         ...config,
@@ -552,6 +1287,25 @@ export function resolveConfig(partialConfig, commandLineConfigOverrides) {
         }
     }
     mergedConfig.canInterruptInferenceWithEsc = mergedConfig.canInterruptInferenceWithEsc && isTTY();
+    // CFG-30 — resolve colour through the four-rung ladder (FORCE_COLOR > NO_COLOR > explicit config
+    // > stdout auto-detect). `useColour` is top-level only (it is not one of the
+    // PRECEDENCE_PICKED_COMMAND_FIELDS), so there is no per-command variant to reconcile.
+    mergedConfig.useColour = resolveUseColour({
+        forceColor: env.FORCE_COLOR,
+        noColor: env.NO_COLOR,
+        explicitUseColour,
+        stdoutIsTTY: isStdoutTTY(),
+    });
+    // TUI-C37 — resolve mouse through its own ladder (GTH_NO_MOUSE > explicit config > TERM >
+    // TTY auto-detect). Resolved here rather than in the TUI so the answer is one field on the
+    // config, the way `useColour` is, instead of a decision each surface re-takes.
+    mergedConfig.useMouse = resolveUseMouse({
+        noMouse: env.GTH_NO_MOUSE,
+        explicitUseMouse,
+        term: env.TERM,
+        stdoutIsTTY: isStdoutTTY(),
+        stdinIsTTY: isTTY(),
+    });
     return mergedConfig;
 }
 /**
@@ -610,54 +1364,210 @@ async function readRawConfigAtPath(path) {
 }
 /**
  * Global config read for the read-side {@link validateConfig}: mirrors
- * {@link loadGlobalRawConfig}'s lookup order (JSON → JS → MJS) but does NOT validate or
+ * {@link loadGlobalRawConfig}'s lookup order (JSON → JSONC → JS → MJS) but does NOT validate or
  * `exit` — it just returns the raw object + a source label so the validator owns the verdict.
+ *
+ * Ignore-on-error, exactly like {@link loadGlobalRawConfig}: a parse/module failure of the
+ * global file is treated as an ABSENT global (returns `undefined`), NOT a hard error — a real
+ * run does the same, so the diagnostic must too, else a clean project + an unparseable global
+ * would fail `gth config validate` while the run keeps going (the inverse of the GS2-29 bug).
+ *
+ * The failure is BOTH debug-logged AND surfaced as a user-facing `displayWarning` with the same
+ * message `loadGlobalRawConfig` emits (`Failed to read global config from <path>, ignoring it.`).
+ * A run warns the user while ignoring the broken global's VALUE; matching that message is what
+ * keeps `gth config validate` a faithful mirror of the run rather than staying silent about a
+ * problem the run flags.
  */
-async function loadGlobalRawConfigUnvalidated() {
-    const jsonPath = getGlobalGslothConfigReadPath(USER_PROJECT_CONFIG_JSON);
-    if (existsSync(jsonPath)) {
-        const label = `${USER_PROJECT_CONFIG_JSON} (global)`;
-        return {
-            raw: parseJsonc(readFileSync(jsonPath, 'utf8'), label),
-            label,
-        };
+async function loadGlobalRawConfigUnvalidated(identityProfile) {
+    for (const filename of JSON_CONFIG_FILENAMES) {
+        const jsonPath = getGlobalGslothConfigReadPath(filename, identityProfile);
+        if (existsSync(jsonPath)) {
+            const label = identityProfile
+                ? `${GSLOTH_SETTINGS_DIR}/${identityProfile}/${filename} (global)`
+                : `${filename} (global)`;
+            try {
+                return {
+                    raw: parseJsonc(readFileSync(jsonPath, 'utf8'), label),
+                    label,
+                };
+            }
+            catch (e) {
+                displayDebug(e instanceof Error ? e : String(e));
+                displayWarning(`Failed to read global config from ${jsonPath}, ignoring it.`);
+                return undefined;
+            }
+        }
     }
     for (const filename of [USER_PROJECT_CONFIG_JS, USER_PROJECT_CONFIG_MJS]) {
-        const modulePath = getGlobalGslothConfigReadPath(filename);
+        const modulePath = getGlobalGslothConfigReadPath(filename, identityProfile);
         if (existsSync(modulePath)) {
-            const imported = await importExternalFile(modulePath);
-            return {
-                raw: (await imported.configure()),
-                label: `${filename} (global)`,
-            };
+            const label = identityProfile
+                ? `${GSLOTH_SETTINGS_DIR}/${identityProfile}/${filename} (global)`
+                : `${filename} (global)`;
+            try {
+                const imported = await importExternalFile(modulePath);
+                return {
+                    raw: (await imported.configure()),
+                    label,
+                };
+            }
+            catch (e) {
+                displayDebug(e instanceof Error ? e : String(e));
+                displayWarning(`Failed to read global config from ${modulePath}, ignoring it.`);
+                return undefined;
+            }
         }
     }
     return undefined;
 }
 /**
  * Locate and validate the effective raw config against the schema WITHOUT building the LLM
- * or merging defaults (the read-side of GS2-1). Honours `--config`, up-tree discovery, and
- * the identity profile via {@link findProjectConfigPath}, falling back to a standalone global
- * config (CFG-8 order) when no project config exists. A JSONC/module parse failure is thrown
- * to the caller (surfaced as a clear "invalid config" error + non-zero exit).
+ * or merging defaults (the read-side of GS2-1). Honours `--config`, up-tree discovery, and the
+ * identity profile via {@link findProjectConfigPath}.
+ *
+ * GS2-29 — validates the SAME layer set a real run does: the discovered PROJECT layer (if any)
+ * AND the GLOBAL layer (if any), mirroring `initConfig`'s `validateRawConfigLayer(project)` +
+ * `applyGlobalConfigBase` → `loadGlobalRawConfig(global)`. Each present layer is validated
+ * independently ({@link validateRawGthConfig}) and its outcome recorded in {@link
+ * ConfigValidationReport.layers}, so a removed shape in EITHER file is reported (labelled with
+ * its source) rather than under-reported.
+ *
+ * A PROJECT-layer JSONC/module parse failure is thrown to the caller (surfaced as a clear
+ * "invalid config" error + non-zero exit). A GLOBAL-layer parse failure is treated as an absent
+ * global (no layer added) but is surfaced with a `displayWarning` — exactly as a run does (it
+ * warns the user while ignoring the broken global's value) — see {@link
+ * loadGlobalRawConfigUnvalidated}.
+ *
+ * GS2-73 — for the PROJECT layer it also walks the GS2-41 profile `extends` chain (via the SAME
+ * {@link composeExtends}/{@link resolveExtendsChain} the run path uses), so a cycle or a missing
+ * base — which fail a real run — is reported here as a not-ok layer instead of passing OK and only
+ * failing at run time. The GLOBAL layer is walked on exactly the branch a run walks it: when NO
+ * project layer was discovered, so the global config is what `initConfig` loads and resolves
+ * `extends` on. With a project layer present the run underlays the raw global config
+ * ({@link applyGlobalConfigBase}) and never resolves its `extends`, so neither does this.
  */
 export async function validateConfig(commandLineConfigOverrides) {
+    const layers = [];
+    // CFG-26 — the fs-backed `approvals.rater` hook, so this validator enforces the SAME existence
+    // rule the loader hard-fails on (`schema.ts` stays pure; the filesystem knowledge lives here).
+    // CFG-56 — built PER LAYER, because the run resolves a rater profile in the scope of the layer
+    // that named it: the project layer walks up-tree, and the global layer walks
+    // `~/.gsloth/.gsloth-settings/` only under `--global`. One shared hook would answer for the
+    // wrong scope on one of the two layers, which is precisely the validate-vs-run split this
+    // function exists to close.
+    const rawConfigValidationOptions = (scope) => ({
+        resolveProfile: (profile) => resolveIdentityProfileConfigPath(profile, scope) !== undefined,
+        describeProfileDir: (profile) => scope.globalOnly ? globalProfileDirLabel(profile) : undefined,
+    });
+    // CFG-36 — mirror the run's STRICT named-profile rule before anything is read. `initConfig`
+    // refuses outright when an explicitly-named profile has no config of its own, so a validator that
+    // walked on would report OK for a config the run rejects — and it would do so in the ordinary
+    // case, because discovery falls back to a plain project config for an unresolved profile. That is
+    // the GS2-29 divergence in its purest form: `gth config validate -i typo` green-lighting a run
+    // that cannot start. Reported as a not-ok layer rather than thrown, because the read side
+    // COLLECTS and never terminates; returned immediately because a run gets no further either.
+    const unresolvedProfile = findUnresolvedExplicitProfile(commandLineConfigOverrides);
+    if (unresolvedProfile) {
+        const sourceLabel = commandLineConfigOverrides.global
+            ? globalProfileDirLabel(unresolvedProfile)
+            : `${GSLOTH_DIR}/${GSLOTH_SETTINGS_DIR}/${unresolvedProfile}/`;
+        return {
+            // `found: true` so the caller renders THIS message. `found: false` means "nothing to
+            // validate, run `gth init`", which would both discard the real diagnosis and misdirect a user
+            // whose actual problem is a mistyped `-i`.
+            found: true,
+            ok: false,
+            layers: [
+                {
+                    sourceLabel,
+                    ok: false,
+                    warnings: [],
+                    errorMessage: identityProfileNotFoundMessage(unresolvedProfile, commandLineConfigOverrides.global),
+                },
+            ],
+        };
+    }
+    // Project layer first (run order): initConfig validates the discovered project config before
+    // applying the global base. A parse failure here propagates (surfaced by the caller).
     const discovered = findProjectConfigPath(commandLineConfigOverrides);
     if (discovered) {
         const raw = await readRawConfigAtPath(discovered.path);
-        return { found: true, sourceLabel: discovered.path, ...validateRawGthConfig(raw) };
+        const layer = {
+            sourceLabel: discovered.path,
+            ...validateRawGthConfig(raw, rawConfigValidationOptions({})),
+        };
+        // GS2-73 — mirror the run's `extends` resolution. GS2-41's `resolveConfigExtends` walks the
+        // profile inheritance chain and hard-fails a real run on a cycle or a missing base; the read
+        // side must surface the SAME failures, else a profile whose `extends` names a missing base (or
+        // forms a cycle) reports OK here yet dies at run time — the exact GS2-29 "validate mirrors the
+        // layer set a run loads" divergence. Reuse the SAME traversal (via {@link composeExtends}) —
+        // no forked walk — and record its typed failure as a not-ok layer instead of exiting. Gated on
+        // `layer.ok` and on a string `extends`, mirroring run order (a run validates the raw shape and
+        // only THEN resolves `extends`) and skipping the read + walk for the common no-`extends` config.
+        if (layer.ok && typeof raw.extends === 'string') {
+            try {
+                await composeExtends(raw, commandLineConfigOverrides.identityProfile);
+            }
+            catch (e) {
+                // CFG-36 — a MALFORMED base layer now raises a ConfigDiscoveryError from
+                // `validateRawConfigLayer` instead of exiting the process. Record it as a not-ok layer
+                // alongside the traversal's own failures: the read side collects, it never terminates, so
+                // `gth config validate` reports the broken base rather than dying on it.
+                if (e instanceof ConfigExtendsError || isConfigDiscoveryError(e)) {
+                    layer.ok = false;
+                    layer.errorMessage = e.message;
+                }
+                else {
+                    throw e;
+                }
+            }
+        }
+        layers.push(layer);
     }
-    const globalRaw = await loadGlobalRawConfigUnvalidated();
+    // Global layer next: a run ALWAYS applies it (applyGlobalConfigBase in the project path,
+    // loadGlobalRawConfig in the no-project path), so the diagnostic must validate it too — this is
+    // the layer the previous single-layer validateConfig skipped whenever a project config existed.
+    const globalRaw = await loadGlobalRawConfigUnvalidated(globalLayerProfile(commandLineConfigOverrides));
     if (globalRaw) {
-        return { found: true, sourceLabel: globalRaw.label, ...validateRawGthConfig(globalRaw.raw) };
+        const globalScope = { globalOnly: commandLineConfigOverrides.global };
+        const layer = {
+            sourceLabel: globalRaw.label,
+            ...validateRawGthConfig(globalRaw.raw, rawConfigValidationOptions(globalScope)),
+        };
+        // The global layer's `extends` is walked ONLY when there is no project layer, because that is
+        // the only case in which a run walks it: `initConfig`'s no-project branch resolves `extends` on
+        // the global config, while `applyGlobalConfigBase` (the branch taken whenever a project config
+        // exists) deep-merges the raw global config WITHOUT resolving it. Walking it unconditionally
+        // reported a missing base that the run it mirrors never looks for.
+        if (!discovered && layer.ok && typeof globalRaw.raw.extends === 'string') {
+            try {
+                await composeExtends(globalRaw.raw, globalLayerProfile(commandLineConfigOverrides), globalScope);
+            }
+            catch (e) {
+                if (e instanceof ConfigExtendsError || isConfigDiscoveryError(e)) {
+                    layer.ok = false;
+                    layer.errorMessage = e.message;
+                }
+                else {
+                    throw e;
+                }
+            }
+        }
+        layers.push(layer);
     }
-    return { found: false, ok: false, warnings: [] };
+    // Vacuous-truth guard: `every` is true on an empty array, so gate `ok` on a config existing.
+    return { found: layers.length > 0, ok: layers.length > 0 && layers.every((l) => l.ok), layers };
 }
 /**
  * Merge raw with default config
  */
 async function mergeRawConfig(config, llm, commandLineConfigOverrides) {
     const modelDisplayName = config.llm?.model;
-    return await mergeConfig({ ...config, llm, modelDisplayName }, commandLineConfigOverrides);
+    // GS2-53 — stash the raw provider `type` (openrouter/deepseek/xai/…) BEFORE the built `llm`
+    // replaces the raw `llm` spec below: it is the true configured provider and the only place the
+    // OpenAI-compatible shims' real identity survives (their `_llmType()` reports `openai`).
+    // `resolveModelIdentity` prefers it over `_llmType()`. INTERNAL field (not in the config schema).
+    const modelProviderType = config.llm?.type;
+    return await mergeConfig({ ...config, llm, modelDisplayName, modelProviderType }, commandLineConfigOverrides);
 }
 //# sourceMappingURL=loader.js.map