@opengsd/gsd-core 1.10.0 → 1.11.0

package/gsd-core/bin/lib/install-fs-adapter.cjs

@@ -0,0 +1,262 @@
+'use strict';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+/**
+ * Install Fs Adapter — #2874 (epic #2866 Phase 5), governed by ADR-58.
+ *
+ * Narrow, enumerated fs seam for the install/staging call tree rooted at
+ * `installRuntimeArtifacts` (install-engine.cts): layout source-root
+ * resolution (runtime-artifact-layout.cts), profile staging
+ * (install-profiles.cts), content-rewrite passes
+ * (runtime-artifact-conversion.cts), the CommonJS module-type marker
+ * (commonjs-marker.cts), and the two installer-migrations entry points this
+ * call tree reaches — `readInstallManifest` / `classifyArtifact`
+ * (installer-migrations.cts). Extends the `deps` bag precedent already
+ * established by `createRuntimeArtifactInstallPlan`
+ * (runtime-artifact-install-plan.cts:155) — this is NOT a general-purpose
+ * `node:fs` wrapper (40-design.md "Rejected" #1): only the operations this
+ * call tree actually performs are enumerated below. installer-migrations.cts
+ * is ~1200 lines covering migration planning/apply/rollback/locking/journal
+ * machinery unrelated to `installRuntimeArtifacts` — only its two reachable
+ * entry points (and `sha256File`, their shared hashing helper — still raw-fd
+ * streaming via `openSync`/`readSync`/`closeSync`, now routed through this
+ * seam instead of calling `node:fs` directly, so large-file hashing never
+ * buffers a whole file through the injected adapter either) are routed; the
+ * rest of that file is untouched, deliberately, because it is off this call
+ * tree.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * DELIVERY MECHANISM — ambient, not threaded (read this before adding a call
+ * site that needs a different adapter mid-call)
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ * A single mutable "current adapter" (`current`, below) is swapped for the
+ * duration of one synchronous `installRuntimeArtifacts` call via
+ * `withInstallFs`, rather than a `deps` parameter threaded through every
+ * function on the call tree. The rejected alternative was threading: it
+ * would touch signatures across `install-profiles.cts` (5 staging
+ * functions), the 3000+-line `runtime-artifact-conversion.cts` (rewrite
+ * passes), `commonjs-marker.cts`, and `installer-migrations.cts` — a dozen+
+ * unrelated call sites — for no behavioral gain over an ambient swap, and
+ * `createRuntimeArtifactInstallPlan`'s own `deps` bag (the precedent this
+ * seam extends) does not reach that deep either. Every fs-touching site on
+ * the call tree reads the active adapter via `installFs()` instead of
+ * importing `node:fs` directly.
+ *
+ * SYNCHRONOUS-ONLY / RE-ENTRANCY ASSUMPTION (load-bearing, not incidental):
+ * every method on this seam is `*Sync`, and `installRuntimeArtifacts` never
+ * awaits mid-call — the whole call tree from the top-level `withInstallFs`
+ * wrap down to the last `fs` touch runs on one turn of the event loop with
+ * no interleaving. That is what makes a single ambient variable safe instead
+ * of a race: nothing else can observe or mutate `current` while it is set.
+ * This assumption BREAKS if `installRuntimeArtifacts` (or anything it calls)
+ * ever becomes `async`, or if two installs run concurrently in the same
+ * process (the second `withInstallFs` call would clobber the first's
+ * adapter mid-flight) — neither is true today, but a future change that
+ * introduces either must revisit this module before trusting it.
+ *
+ * DEFERRED CLEANUP ACROSS THE RESTORE (#2874 leak-fix): staged directories
+ * outlive one `withInstallFs` call — `install-profiles.cts`'s
+ * `cleanupStagedSkills` runs later, from a `process.on('exit'/'SIGINT'/…)`
+ * handler, by which time `withInstallFs`'s `finally` has already restored
+ * `current` back to whatever was active before (real fs, in the top-level
+ * case). A cleanup handler that resolved "which adapter do I use" via
+ * `installFs()` at CLEANUP time would therefore always see the real adapter,
+ * even for a directory that was staged entirely inside a fake-adapter call —
+ * performing real filesystem IO on a path that only ever existed in the
+ * fake's in-memory store. `install-profiles.cts` avoids this by capturing
+ * the adapter OBJECT `installFs()` returns at STAGING (registration) time,
+ * keyed by path, in its own `STAGED_DIR_ADAPTERS` map, and replaying that
+ * captured object — not the ambient `current` — at cleanup time. A real
+ * install's dirs were staged with the real adapter object, so their cleanup
+ * is byte-identical to before this fix.
+ *
+ * `withInstallFs` ALWAYS restores the previous adapter in a `finally`, even
+ * on throw — a failed install (or a test that intentionally throws to prove
+ * a guard) must never leak a fake adapter into whatever runs next in the
+ * same process (e.g. the next `node:test` in a shared worker).
+ *
+ * ⚠️ PARTIAL-ADAPTER TRAP (#2875 defect fix — CLOSED, not merely documented):
+ * `withInstallFs` used to merge the injected `partial` OVER the real adapter
+ * (`{ ...REAL_ADAPTER, ...partial }`), so any method the partial did not
+ * define silently resolved to REAL `node:fs`. An incomplete fake was not a
+ * smaller fake adapter; for the methods it omitted, it WAS the real
+ * filesystem — a genuine production hazard, not only a test-authoring
+ * footgun: `user-artifact-staging.cts`'s `stageUserArtifacts` calls
+ * `installFs().rmSync(entryDir)` unconditionally as its entryDir-clearing
+ * step, and a `deps.fs` that omits `rmSync` (an easy oversight — nothing in
+ * the type system catches a plain-JS test object missing a key at runtime)
+ * silently deleted the real `<configDir>/.gsd-staging/<key>` on disk instead
+ * of failing loudly or staying confined to the fake's own store.
+ *
+ * `withInstallFs` now builds a GUARDED adapter instead: every method the
+ * partial does not define — except `realpathSync`, the one method this
+ * module's own contract documents as intentionally degrading to real fs
+ * (see its own doc comment below) — throws immediately IF CALLED, naming the
+ * missing method, instead of silently delegating to real fs. This only
+ * changes behavior for the injected-partial path (`withInstallFs(partial,
+ * fn)` with a defined `partial`); the no-adapter-injected default (AC4)
+ * still resolves to `REAL_ADAPTER` untouched, and any partial fake that
+ * genuinely implements every method its code path touches — the documented,
+ * intended usage — is byte-identical to before. A test asserting "no real IO
+ * happened" against a partial fake can now rely on this guard directly
+ * instead of having to hand-poison real `fs` methods itself (see
+ * `tests/executed-plan.test.cjs`'s F2 test, which still poisons real `fs` as
+ * defense-in-depth belt-and-suspenders, not because this guard is
+ * insufficient on its own).
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * SECURITY NOTE (40-design.md rows 6/7, H1-H5)
+ * ─────────────────────────────────────────────────────────────────────────
+ * This module carries NO policy. `hasExistingSymlinkBetween` and
+ * `assertDestWithinConfigHome` keep their REFUSAL DECISIONS outside this
+ * seam — only their probe calls (existsSync/lstatSync/realpathSync) are
+ * routed through it. Injecting a fake adapter can only change what those
+ * probes observe for paths that were never real to begin with; it cannot
+ * flip the decision logic itself.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * DELIBERATELY NOT ROUTED (see the call sites themselves for the full
+ * reasoning — this is the index)
+ * ─────────────────────────────────────────────────────────────────────────
+ * `findInstallSourceRoot` / `findAgentsSourceRoot`'s walk-up-from-__dirname
+ * step (runtime-artifact-layout.cts) locates THIS PACKAGE'S OWN source tree
+ * (`commands/gsd/`, `agents/`) — not the install destination — so it uses
+ * `fs.statSync` directly, unrouted. A fake destination adapter's store
+ * starts empty and is never seeded with real repo paths; routing this walk
+ * through it would make every fake-adapter install throw
+ * "could not locate commands/gsd", not gracefully stage nothing. See the
+ * comment at each function's Step 2 for the full argument.
+ *
+ * RULE (40-design.md "Known limits"): this seam makes *destination* IO
+ * fake-able; package-source IO (this section) stays real by design — the F2
+ * test's poison list should be derived FROM that rule, not the reverse, or a
+ * future "complete the poison list" edit that adds `statSync` will break a
+ * correct `findInstallSourceRoot` for the wrong reason.
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const REAL_ADAPTER = {
+    existsSync: (p) => node_fs_1.default.existsSync(p),
+    mkdirSync: (p, opts) => node_fs_1.default.mkdirSync(p, opts),
+    rmSync: (p, opts) => node_fs_1.default.rmSync(p, opts),
+    readdirSync: ((p, opts) => (opts ? node_fs_1.default.readdirSync(p, opts) : node_fs_1.default.readdirSync(p))),
+    readFileSync: ((p, encoding) => (encoding ? node_fs_1.default.readFileSync(p, encoding) : node_fs_1.default.readFileSync(p))),
+    writeFileSync: (p, data, opts) => node_fs_1.default.writeFileSync(p, data, opts),
+    copyFileSync: (src, dest) => node_fs_1.default.copyFileSync(src, dest),
+    cpSync: (src, dest, opts) => node_fs_1.default.cpSync(src, dest, opts),
+    lstatSync: (p) => node_fs_1.default.lstatSync(p),
+    realpathSync: (p) => node_fs_1.default.realpathSync(p),
+    unlinkSync: (p) => node_fs_1.default.unlinkSync(p),
+    rmdirSync: (p) => node_fs_1.default.rmdirSync(p),
+    symlinkSync: (target, p) => node_fs_1.default.symlinkSync(target, p),
+    readlinkSync: (p) => node_fs_1.default.readlinkSync(p),
+    openSync: (p, flags) => node_fs_1.default.openSync(p, flags),
+    readSync: (fd, buffer, offset, length, position) => node_fs_1.default.readSync(fd, buffer, offset, length, position),
+    closeSync: (fd) => node_fs_1.default.closeSync(fd),
+};
+let current = REAL_ADAPTER;
+/**
+ * Returns the fs adapter active for the currently-running install call —
+ * the real adapter when no `deps.fs` was injected, or the injected partial
+ * adapter merged over the real one (any method it did not override still
+ * resolves to real fs — see the module doc's "PARTIAL-ADAPTER TRAP").
+ */
+function installFs() {
+    return current;
+}
+// Methods allowed to silently degrade to real fs when a partial injected
+// adapter omits them — see the module doc's "PARTIAL-ADAPTER TRAP". This is
+// deliberately a single, narrow, documented exception: `realpathSync`'s own
+// interface doc comment already promises graceful real-fs fallback (the
+// symlink guard treats a `realpathSync` failure as "fall back to the lexical
+// form" anyway, so an absent method degrading the same way changes nothing
+// observable). Every other method is REQUIRED by `InstallFsAdapter`'s own
+// type (no `?`) and now enforces that at runtime too.
+const OPTIONAL_ADAPTER_METHODS = new Set(['realpathSync']);
+/**
+ * Build a merged adapter for an injected `partial`: every method `partial`
+ * defines is used as-is; `realpathSync` (only) falls back to real fs when
+ * absent; every other omitted method becomes a stub that THROWS if actually
+ * called, naming the missing method — turning a silent real-fs fall-through
+ * into an immediate, diagnosable failure (module doc "PARTIAL-ADAPTER TRAP").
+ * A method never invoked by the exercised code path never throws, so this is
+ * safe for any existing partial fake that only implements what it touches.
+ */
+function buildGuardedAdapter(partial) {
+    const guarded = {};
+    for (const key of Object.keys(REAL_ADAPTER)) {
+        if (Object.prototype.hasOwnProperty.call(partial, key)) {
+            guarded[key] = partial[key];
+        }
+        else if (OPTIONAL_ADAPTER_METHODS.has(key)) {
+            guarded[key] = REAL_ADAPTER[key];
+        }
+        else {
+            guarded[key] = (..._args) => {
+                throw new Error(`installFs().${key}(...) was called but the injected partial adapter does not implement it. ` +
+                    `A fake adapter must implement every method its code path touches (install-fs-adapter.cts's ` +
+                    `PARTIAL-ADAPTER TRAP) — falling through to real fs is no longer allowed for this method.`);
+            };
+        }
+    }
+    return guarded;
+}
+/**
+ * Run `fn` with a GUARDED merge of `partial` over the real adapter as the
+ * active install-fs adapter, restoring the previous adapter afterward — even
+ * on throw (see the module doc's re-entrancy/synchronous-only assumption for
+ * why a bare module-level variable is safe here, and why it would not be
+ * under async interleaving or concurrent installs). `partial` undefined is
+ * a no-op: `fn` runs against whatever adapter was already active (real fs
+ * by default) — this is what keeps every existing `deps`-less call site
+ * (AC4) byte-identical. See `buildGuardedAdapter` for what "guarded" means.
+ */
+function withInstallFs(partial, fn) {
+    if (!partial)
+        return fn();
+    const previous = current;
+    current = buildGuardedAdapter(partial);
+    try {
+        return fn();
+    }
+    finally {
+        current = previous;
+    }
+}
+/**
+ * Create a fresh, uniquely-named temp directory.
+ *
+ * AC4 requires the no-adapter-injected path to stay byte-identical to the
+ * pre-#2874 code, which called real `fs.mkdtempSync` directly — several
+ * existing tests (e.g. tests/install-runtime-artifacts.test.cjs's "rmSync is
+ * called on the tempDir when readFileSync throws") monkeypatch real
+ * `fs.mkdtempSync` to capture the exact directory a call under test creates,
+ * and stop working if that real syscall is no longer made. So: when NO fake
+ * adapter is active (`current === REAL_ADAPTER`, the exact top-level-install
+ * default), this calls `nodeFs.mkdtempSync` directly — the same real call
+ * the old code made, still visible to a monkeypatch applied after import
+ * because it is a live property lookup on the `node:fs` module object, not a
+ * captured reference.
+ *
+ * When a fake adapter IS active (any `withInstallFs(partial, …)` call, even
+ * a partial one — see `current`'s assignment in `withInstallFs`, which
+ * always produces a NEW merged object, never `=== REAL_ADAPTER`), this falls
+ * back to synthesizing a unique name and creating it via
+ * `installFs().mkdirSync`, exactly as before: the injected adapter contract
+ * still does not require `mkdtempSync`, so a fake (which only needs to
+ * implement `mkdirSync`) can drive the full staging pipeline without ever
+ * touching real fs.
+ */
+function mkInstallTempDir(prefix) {
+    if (current === REAL_ADAPTER) {
+        return node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), prefix));
+    }
+    const dir = node_path_1.default.join(node_os_1.default.tmpdir(), `${prefix}${node_crypto_1.default.randomBytes(8).toString('hex')}`);
+    installFs().mkdirSync(dir, { recursive: true });
+    return dir;
+}
+module.exports = { installFs, withInstallFs, mkInstallTempDir };

package/gsd-core/bin/lib/install-model-override-resolver.cjs

@@ -0,0 +1,203 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+/**
+ * install-model-override-resolver — install-time per-agent model-override
+ * resolution (#2256 / #2794), extracted from the package-root `bin/install.js`
+ * (#2875 Part 2 / J8).
+ *
+ * bin/install.js's inline agent-staging loop duplicated this EXACT precedence
+ * chain across two runtime branches (OpenCode ~24 lines, Kilo ~24 lines) —
+ * `model_overrides[agent]` > `model_profile_overrides.<runtime>.<tier>` > omit.
+ * Extracted here — a `src/*.cts` module compiled into the shipped
+ * `gsd-core/bin/lib/` tree, mirroring `install-effort-resolver.cts`'s existing
+ * precedent (#2071) — so the descriptor-driven agents pipeline
+ * (`convertedAgentsKind` / `stageAgentsForRuntimeWithConverter`) and
+ * bin/install.js's own callers resolve through the SAME code. A single source
+ * of truth makes the two paths diverge only if this module changes, not
+ * silently across two hand-maintained copies (the Generative Fix Divergence
+ * class CLAUDE.md's "Known Defects" section warns about).
+ *
+ * `readGsdGlobalModelOverrides` / `readGsdEffectiveModelOverrides` /
+ * `readGsdRuntimeProfileResolver` are impure (config-file reads);
+ * `resolveAgentModelOverride` is pure given their pre-resolved outputs.
+ *
+ * #2875 defect fix: this module is on the `installRuntimeArtifacts` call tree
+ * (reached from `runtime-artifact-layout.cts`'s agents-kind `stage()` for the
+ * opencode/kilo converters) — every fs touch below routes through
+ * `installFs()` (install-fs-adapter.cts), matching `retired-artifact-cleanup.cts`
+ * / `user-artifact-staging.cts`'s existing precedent, instead of calling
+ * `node:fs` directly. A raw `fs` call here silently bypassed a fake adapter
+ * injected via `withInstallFs`/`installRuntimeArtifacts(..., { fs })`,
+ * exactly the class of bug those two modules were fixed for.
+ */
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- install-fs-adapter.cjs is an export= CommonJS module
+const installFsAdapter = require("./install-fs-adapter.cjs");
+const { installFs } = installFsAdapter;
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- install-effort-resolver.cjs is an export= CommonJS module
+const installEffortResolver = require("./install-effort-resolver.cjs");
+const { _readGsdConfigFile, _findAncestorGsdConfigPath } = installEffortResolver;
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- model-catalog.cjs is an export= CommonJS module
+const modelCatalog = require("./model-catalog.cjs");
+const { MODEL_PROFILES: GSD_MODEL_PROFILES } = modelCatalog;
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- model-resolver.cjs is an export= CommonJS module
+const modelResolverModule = require("./model-resolver.cjs");
+const { resolveTierEntry: gsdResolveTierEntry } = modelResolverModule;
+/**
+ * Read `model_overrides` from `~/.gsd/defaults.json` at install time.
+ * Returns an object mapping agent names to model IDs, or null if the file
+ * doesn't exist or has no `model_overrides` entry.
+ *
+ * Mirrors bin/install.js's prior local `readGsdGlobalModelOverrides` exactly
+ * (silent try/catch — no stderr warning on malformed JSON, unlike
+ * `_readGsdConfigFile`'s effort-config sibling — preserved for byte-parity).
+ */
+function readGsdGlobalModelOverrides(options = {}) {
+    try {
+        const home = options.homedir ? options.homedir() : node_os_1.default.homedir();
+        const defaultsPath = node_path_1.default.join(home, '.gsd', 'defaults.json');
+        if (!installFs().existsSync(defaultsPath))
+            return null;
+        const raw = installFs().readFileSync(defaultsPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        const overrides = parsed.model_overrides;
+        if (!overrides || typeof overrides !== 'object')
+            return null;
+        return overrides;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Effective per-agent `model_overrides` for the install path.
+ *
+ * Merges `~/.gsd/defaults.json` (global) with per-project
+ * `<project>/.planning/config.json`. Per-project keys win on conflict; keys
+ * present in only one source are preserved from that source (#2256).
+ *
+ * `targetDir` is the consuming runtime's install root (walks up to find
+ * `.planning/`). When `targetDir` is null/undefined only the global file is
+ * consulted.
+ *
+ * Returns a plain `{ agentName: modelId }` object, or `null` when neither
+ * source defines `model_overrides`.
+ */
+function readGsdEffectiveModelOverrides(targetDir = null, options = {}) {
+    const global = readGsdGlobalModelOverrides(options);
+    let projectOverrides = null;
+    if (targetDir) {
+        // #2875 defect fix (Generative Fix Divergence): the 8-deep upward walk to
+        // `.planning/config.json` is single-sourced in install-effort-resolver.cts
+        // (`_findAncestorGsdConfigPath`) — this module was itself extracted FROM
+        // that one to stop duplicating shared install-time config logic, so a
+        // second hand-rolled copy of the walk here defeated the point.
+        const candidate = _findAncestorGsdConfigPath(targetDir);
+        if (candidate) {
+            try {
+                const parsed = JSON.parse(installFs().readFileSync(candidate, 'utf-8'));
+                if (parsed && typeof parsed === 'object' && parsed.model_overrides && typeof parsed.model_overrides === 'object') {
+                    projectOverrides = parsed.model_overrides;
+                }
+            }
+            catch {
+                // Malformed config.json — fall back to global; readGsdRuntimeProfileResolver
+                // surfaces a parse warning via _readGsdConfigFile already.
+            }
+        }
+    }
+    if (!global && !projectOverrides)
+        return null;
+    // Per-project wins on conflict; preserve non-conflicting global keys.
+    return { ...(global || {}), ...(projectOverrides || {}) };
+}
+/**
+ * Build a runtime-aware tier resolver for the install path (#2517).
+ *
+ * Probes BOTH per-project `<targetDir>/.planning/config.json` AND
+ * `~/.gsd/defaults.json`, with per-project keys winning over global.
+ *
+ * Returns null if no `runtime` is configured, if `model_profile` is
+ * `inherit`, or if no project config is reachable AND `~/.gsd/defaults.json`
+ * declares no `model_profile` (#3543 — an unverifiable profile is never
+ * baked, letting the runtime's own default/session model govern).
+ */
+function readGsdRuntimeProfileResolver(targetDir = null) {
+    const homeDefaults = _readGsdConfigFile(node_path_1.default.join(node_os_1.default.homedir(), '.gsd', 'defaults.json'), '~/.gsd/defaults.json');
+    // #2875 defect fix (Generative Fix Divergence): same shared walk as
+    // readGsdEffectiveModelOverrides above — see that call site's comment.
+    let projectConfig = null;
+    if (targetDir) {
+        const candidate = _findAncestorGsdConfigPath(targetDir);
+        if (candidate)
+            projectConfig = _readGsdConfigFile(candidate, '.planning/config.json');
+    }
+    const merged = {
+        runtime: (projectConfig && projectConfig.runtime) ||
+            (homeDefaults && homeDefaults.runtime) ||
+            null,
+        model_profile: (projectConfig && projectConfig.model_profile) ||
+            (homeDefaults && homeDefaults.model_profile) ||
+            'balanced',
+        model_profile_overrides: (projectConfig && projectConfig.model_profile_overrides) ||
+            (homeDefaults && homeDefaults.model_profile_overrides) ||
+            null,
+    };
+    if (!merged.runtime)
+        return null;
+    if (!projectConfig && !(homeDefaults && homeDefaults.model_profile)) {
+        return null;
+    }
+    const profile = String(merged.model_profile).toLowerCase();
+    if (profile === 'inherit')
+        return null;
+    const runtime = merged.runtime;
+    return {
+        runtime,
+        resolve(agentName) {
+            const agentModels = GSD_MODEL_PROFILES[agentName];
+            if (!agentModels)
+                return null;
+            const tier = agentModels[profile] || agentModels.balanced;
+            if (!tier)
+                return null;
+            return gsdResolveTierEntry({
+                runtime,
+                tier,
+                overrides: merged.model_profile_overrides,
+            });
+        },
+    };
+}
+/**
+ * Resolve the effective model override for a single agent, given a
+ * pre-resolved `modelOverrides` map and `runtimeResolver` (both from the
+ * functions above). Pure — no filesystem access.
+ *
+ * Precedence (J8 — identical for kilo and opencode, resolved through this ONE
+ * shared function so the two runtimes can never diverge):
+ *   1. modelOverrides[agentName]         (#2256 — explicit per-agent override)
+ *   2. runtimeResolver.resolve(agentName)?.model
+ *      (#2794 — tier-based model_profile_overrides.<runtime>.<tier>)
+ *   3. null (omit — J7: the frontmatter key must not appear, not `null`/`""`)
+ */
+function resolveAgentModelOverride(agentName, modelOverrides, runtimeResolver) {
+    const explicit = modelOverrides ? modelOverrides[agentName] : undefined;
+    if (explicit)
+        return explicit;
+    if (runtimeResolver) {
+        const entry = runtimeResolver.resolve(agentName);
+        if (entry && entry.model)
+            return entry.model;
+    }
+    return null;
+}
+module.exports = {
+    readGsdGlobalModelOverrides,
+    readGsdEffectiveModelOverrides,
+    readGsdRuntimeProfileResolver,
+    resolveAgentModelOverride,
+};