@opengsd/gsd-core 1.11.0 → 1.13.0

package/gsd-core/bin/lib/install-engine.cjs

@@ -32,6 +32,7 @@ const retiredArtifactCleanup = require("./retired-artifact-cleanup.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 const external_descriptor_trust_cjs_1 = require("./external-descriptor-trust.cjs");
 const commonjs_marker_cjs_1 = require("./commonjs-marker.cjs");
+const testHomeGuard = require("./real-home-guard.cjs");
 // #2874 (ADR-58 cleanup phase): the injectable fs seam for the
 // installRuntimeArtifacts call tree. `installFs()` resolves to real
 // `node:fs` unless a call is wrapped in `withInstallFs(deps.fs, ...)` —
@@ -54,6 +55,148 @@ const { processAttribution } = runtimeArtifactConversion;
 // resolveRuntimeArtifactLayout: accessed via module ref (not destructured) so
 // test stubs that monkeypatch the module's exports are seen at call time.
 const { getDirName } = runtimeNamePolicy;
+function withInstallerPackageSource(configDir, fn) {
+    // Reuse the existing compatibility-marker contract through the existing fs
+    // seam. The marker exists only in this synchronous call tree: no disk state,
+    // layout export, stage argument, or caller-settable authority flag is added.
+    const markerPath = node_path_1.default.resolve(configDir, '.gsd-source');
+    const packageCommandsRoot = runtimeArtifactLayout.findInstallSourceRoot();
+    const markerBytes = Buffer.from(packageCommandsRoot + '\n');
+    const base = installFs();
+    const overlay = {
+        ...base,
+        existsSync: (candidate) => node_path_1.default.resolve(candidate) === markerPath || base.existsSync(candidate),
+        lstatSync: (candidate) => node_path_1.default.resolve(candidate) === markerPath
+            ? { isFile: () => true, isDirectory: () => false, isSymbolicLink: () => false }
+            : base.lstatSync(candidate),
+        readFileSync: ((candidate, encoding) => {
+            if (node_path_1.default.resolve(candidate) !== markerPath) {
+                return encoding ? base.readFileSync(candidate, encoding) : base.readFileSync(candidate);
+            }
+            return encoding ? markerBytes.toString(encoding) : Buffer.from(markerBytes);
+        }),
+    };
+    return withInstallFs(overlay, fn);
+}
+function isRuntimeSurfaceSourceUnavailable(message) {
+    return message.startsWith('Runtime Surface source is unavailable or incomplete for ') &&
+        message.endsWith('install or upgrade gsd-core before materializing this surface.');
+}
+function assertCorpusTreeHasNoSymlinks(root) {
+    if (!installFs().existsSync(root))
+        return;
+    const stat = installFs().lstatSync(root);
+    if (stat.isSymbolicLink()) {
+        throw new Error(`Runtime Surface corpus path is a symlink: ${root}`);
+    }
+    if (!stat.isDirectory())
+        return;
+    for (const name of installFs().readdirSync(root)) {
+        assertCorpusTreeHasNoSymlinks(node_path_1.default.join(root, name));
+    }
+}
+function previousOwnedCorpusFiles(configDir, prefix) {
+    try {
+        const files = installerMigrations.readInstallManifest(configDir).files;
+        return Object.keys(files)
+            .filter((entry) => entry.startsWith(prefix))
+            .map((entry) => entry.slice(prefix.length))
+            .filter((entry) => entry !== '' && !node_path_1.default.posix.isAbsolute(entry) && !entry.split('/').some((part) => part === '' || part === '.' || part === '..'));
+    }
+    catch {
+        // An absent or unreadable prior manifest provides no ownership evidence.
+        // Preserve existing entries rather than guessing that they are stale.
+        return [];
+    }
+}
+function pruneEmptyCorpusParents(start, stop) {
+    let current = node_path_1.default.dirname(start);
+    while (current !== stop && current.startsWith(stop + node_path_1.default.sep)) {
+        if (installFs().readdirSync(current).length > 0)
+            return;
+        installFs().rmdirSync(current);
+        current = node_path_1.default.dirname(current);
+    }
+}
+function syncRuntimeSurfaceCorpus(source, destination, configDir, manifestPrefix) {
+    if (hasExistingSymlinkBetween(node_path_1.default.resolve(configDir), destination, { allowOptInFollow: isSymlinkedDestOptIn() })) {
+        throw new Error(`syncRuntimeSurfaceCorpus: destination "${destination}" contains a symlink the install root "${configDir}" does not trust — refusing to write.`);
+    }
+    assertCorpusTreeHasNoSymlinks(destination);
+    // Remove only paths the previous manifest proves GSD owned and which the
+    // executing package no longer ships. Unknown neighbouring files survive.
+    for (const relative of previousOwnedCorpusFiles(configDir, manifestPrefix)) {
+        const sourceEntry = node_path_1.default.join(source, ...relative.split('/'));
+        let sourceIsFile = false;
+        try {
+            sourceIsFile = installFs().lstatSync(sourceEntry).isFile();
+        }
+        catch {
+            sourceIsFile = false;
+        }
+        if (sourceIsFile)
+            continue;
+        const target = node_path_1.default.join(destination, ...relative.split('/'));
+        if (!installFs().existsSync(target))
+            continue;
+        const targetStat = installFs().lstatSync(target);
+        if (!targetStat.isFile()) {
+            throw new Error(`Runtime Surface corpus ownership conflict at ${target}`);
+        }
+        installFs().rmSync(target, { force: true });
+        pruneEmptyCorpusParents(target, destination);
+    }
+    installFs().mkdirSync(node_path_1.default.dirname(destination), { recursive: true });
+    installFs().cpSync(source, destination, { recursive: true });
+}
+/**
+ * Provision the raw, installation-owned input needed to re-materialize a
+ * global Runtime Surface after the executing package tree disappears.
+ *
+ * The corpus deliberately lives below the already-installed `gsd-core/`
+ * tree and is accepted only after its manifest ownership and hashes verify.
+ * The compatibility marker does not replace that installed-corpus authority.
+ */
+function provisionRuntimeSurfaceCorpus(layout, configDir, scope) {
+    const required = new Set();
+    if ((0, install_scope_cjs_1.isGlobalScope)(scope)) {
+        for (const kind of layout.kinds) {
+            if (kind.kind === 'commands' || kind.kind === 'skills')
+                required.add('commands');
+            if (kind.kind === 'agents' || kind.kind === 'kimi-agents')
+                required.add('agents');
+        }
+    }
+    if (required.size === 0)
+        return;
+    const corpusRoot = node_path_1.default.join(configDir, 'gsd-core');
+    if (required.has('commands')) {
+        const source = runtimeArtifactLayout.findInstallSourceRoot();
+        const destination = node_path_1.default.join(corpusRoot, 'commands', 'gsd');
+        syncRuntimeSurfaceCorpus(source, destination, configDir, 'gsd-core/commands/gsd/');
+    }
+    if (required.has('agents')) {
+        const source = node_path_1.default.join(executingPackageRoot(), 'agents');
+        const destination = node_path_1.default.join(corpusRoot, 'agents');
+        syncRuntimeSurfaceCorpus(source, destination, configDir, 'gsd-core/agents/');
+    }
+    const markerFile = _hostBehaviors(layout.runtime).sourceMarkerFile;
+    if (typeof markerFile === 'string' && markerFile !== '' && required.has('commands')) {
+        try {
+            const markerPath = runtimeArtifactInstallPlan.assertDestWithinConfigHome(configDir, markerFile);
+            if (hasExistingSymlinkBetween(node_path_1.default.resolve(configDir), markerPath, { allowOptInFollow: isSymlinkedDestOptIn() })) {
+                throw new Error(`compatibility marker "${markerPath}" contains an untrusted symlink`);
+            }
+            installFs().writeFileSync(markerPath, node_path_1.default.join(corpusRoot, 'commands', 'gsd') + '\n', 'utf8');
+        }
+        catch {
+            // The existing installer marker writer owns the user-facing warning and
+            // keeps marker failure non-fatal. The installed corpus remains usable
+            // without the compatibility marker.
+        }
+    }
+}
+function executingPackageRoot() { return node_path_1.default.dirname(node_path_1.default.dirname(runtimeArtifactLayout.findInstallSourceRoot())); }
 // ---------------------------------------------------------------------------
 // USER_OWNED_ARTIFACTS
 // ---------------------------------------------------------------------------
@@ -409,6 +552,15 @@ function _resolveDevPreferencesSkillTarget(targetDir, runtime, scope = 'global')
     // must confine against installRoot, not targetDir, or it would flag the
     // legitimate override destination as an escape.
     let installRoot = targetDir;
+    // Reported in Codex review of #3725: `installRoot !== targetDir` was used as the
+    // stand-in for "the skills kind declared a `home` override", and the two are NOT
+    // equivalent — a resolved `home` that happens to EQUAL targetDir (a configDir of
+    // `$HOME/.agents`, which is exactly where codex's override points) makes the
+    // inequality false while the override is very much declared, skipping the guard
+    // and writing SKILL.md into the real home. Report the declaration itself instead
+    // of inferring it from two paths, read off the SAME layout resolution the
+    // destination came from so the guard cannot vouch for a path this does not write.
+    let hasHomeOverride = false;
     if (runtime) {
         const layout = runtimeArtifactLayout.resolveRuntimeArtifactLayout(runtime, targetDir, scope);
         const skillsKindEntry = layout.kinds.find((k) => k.kind === 'skills');
@@ -420,6 +572,7 @@ function _resolveDevPreferencesSkillTarget(targetDir, runtime, scope = 'global')
         // -> $HOME/.agents) instead of always resolving against targetDir, so a
         // legacy dev-preferences migration lands in the SAME tree the installer
         // and surface-apply use. Runtimes with no `home` override are unaffected.
+        hasHomeOverride = skillsKindEntry.home != null;
         installRoot = skillsKindEntry.home ?? targetDir;
         skillDir = node_path_1.default.join(runtimeArtifactInstallPlan.assertDestWithinConfigHome(installRoot, skillsKindEntry.destSubpath), stemName);
     }
@@ -427,14 +580,42 @@ function _resolveDevPreferencesSkillTarget(targetDir, runtime, scope = 'global')
         // Legacy fallback for callers that have not yet been updated to pass runtime
         skillDir = node_path_1.default.join(runtimeArtifactInstallPlan.assertDestWithinConfigHome(targetDir, 'skills'), 'gsd-dev-preferences');
     }
-    return { skillFile: node_path_1.default.join(skillDir, 'SKILL.md'), installRoot };
+    return { skillFile: node_path_1.default.join(skillDir, 'SKILL.md'), installRoot, hasHomeOverride };
 }
-function migrateLegacyDevPreferencesToSkill(targetDir, saved, runtime, scope = 'global') {
+/**
+ * @param deps - #3712 test seam, mirroring the one on `installRuntimeArtifacts`
+ *   and `uninstallRuntimeArtifacts`. This is the SIXTH writer that resolves a
+ *   skills-kind `home`, and its guard's trigger condition — "HOME equals the
+ *   passwd home" — cannot be reproduced without pointing at the developer's real
+ *   home, so it is injected rather than simulated. Production callers pass
+ *   nothing and bind real `os`/`process.env`.
+ */
+function migrateLegacyDevPreferencesToSkill(targetDir, saved, runtime, scope = 'global', deps = {}) {
     if (!saved || !saved.has('dev-preferences.md'))
         return false;
     const target = _resolveDevPreferencesSkillTarget(targetDir, runtime, scope);
     if (!target)
         return false; // runtime has no skills layout at this scope (e.g. cline local)
+    // #3712 — the SIXTH writer that resolves a skills-kind `home` override.
+    // Exported and directly callable, and `_runLegacyInstallMigrations` runs it
+    // BEFORE installRuntimeArtifacts' own assertion, so a future runtime pairing a
+    // home override with this migration would write to the real home ahead of any
+    // guard. It creates rather than prunes, which is why it was missed.
+    //
+    // Guards the destination ALREADY RESOLVED above, never a second resolution of
+    // its own. An earlier revision re-ran resolveRuntimeArtifactLayout() here —
+    // and without `capabilityRegistry`, so a registry-dependent descriptor could
+    // make the two disagree and leave the guard vouching for a path the migration
+    // does not write. That is the generative-fix-divergence shape; reported in
+    // review of #3725. `target.hasHomeOverride` is that same resolution's own answer
+    // to "did the skills kind declare a `home`?" — not re-derived, and not inferred
+    // from `installRoot !== targetDir`, which is false whenever the override happens
+    // to resolve onto targetDir itself (Codex review of #3725).
+    if (runtime && target.hasHomeOverride) {
+        testHomeGuard.assertTestHomeSandboxed('migrateLegacyDevPreferencesToSkill', runtime, [
+            { kind: 'skills', home: node_path_1.default.dirname(target.skillFile) },
+        ], { os: deps.os, env: deps.env });
+    }
     const { skillFile, installRoot } = target;
     const skillDir = node_path_1.default.dirname(skillFile);
     // Security fix: `existsSync` FOLLOWS symlinks and reports `false` for a
@@ -938,6 +1119,7 @@ function _runLegacyUninstallCleanup(runtime, configDir, scope = 'global') {
  */
 function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, resolveAttribution = () => undefined, capabilityRegistry, deps = {}) {
     return withInstallFs(deps.fs, () => {
+        const layout = runtimeArtifactLayout.resolveRuntimeArtifactLayout(runtime, configDir, scope, capabilityRegistry);
         // A removed descriptor kind is no longer visited by the layout loop, so it
         // cannot prune its own previous output. Clean manifest-proven retired files
         // before materializing the current layout (#2644).
@@ -947,6 +1129,7 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
         // generic layout-driven loop below, mirroring the bespoke install path that
         // previously lived inline in bin/install.js.
         const behaviors = _hostBehaviors(runtime);
+        const projectDir = scope === 'global' ? process.cwd() : configDir;
         if (behaviors.combinedFamilyInstall) {
             // #2329: combined-family runtimes (OpenCode/Kilo) bypass
             // _runLegacyInstallMigrations below entirely (early return), so their
@@ -955,12 +1138,24 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
             // #2874 design row 2: this early return must ALSO return an executed
             // plan — installOpencodeFamilyArtifacts reports what it wrote, so a
             // whole runtime family returning undefined is no longer a hole.
-            return installOpencodeFamilyArtifacts(runtime, configDir, scope, resolvedProfile, resolveAttribution, behaviors, capabilityRegistry);
+            // An injected filesystem supplies its own hermetic corpus fixture. The
+            // real installer is the authority that refreshes package bytes into the
+            // durable installed corpus; attempting that cross-filesystem copy through
+            // an in-memory destination adapter would read from the wrong filesystem.
+            if (!deps.fs)
+                provisionRuntimeSurfaceCorpus(layout, configDir, scope);
+            return installOpencodeFamilyArtifacts(runtime, configDir, scope, resolvedProfile, resolveAttribution, behaviors, capabilityRegistry, deps.packageRoot, projectDir);
         }
         // Legacy cleanup before layout-driven writes
         _runLegacyInstallMigrations(runtime, configDir, scope);
-        const layout = runtimeArtifactLayout.resolveRuntimeArtifactLayout(runtime, configDir, scope, capabilityRegistry);
-        const planResult = runtimeArtifactInstallPlan.createRuntimeArtifactInstallPlan({
+        if (!deps.fs)
+            provisionRuntimeSurfaceCorpus(layout, configDir, scope);
+        // #3712: a global `home` override escapes the sandboxed configDir. Refuse to
+        // execute when a test run would land that escape in the developer's real home.
+        testHomeGuard.assertTestHomeSandboxed('installRuntimeArtifacts', runtime, layout?.kinds, {
+            os: deps.os, env: deps.env,
+        });
+        const createPlan = () => runtimeArtifactInstallPlan.createRuntimeArtifactInstallPlan({
             // `Layout` is structurally identical across the layout/install-plan .cjs
             // modules but nominally distinct to tsc (untyped .cjs boundary) — bridge it.
             layout: layout,
@@ -968,7 +1163,16 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
             homedir: () => node_os_1.default.homedir(),
             platform: process.platform,
             resolveAttribution,
+            projectDir,
         });
+        let planResult = createPlan();
+        if (scope === 'global' &&
+            !planResult.ok &&
+            planResult.kind === 'stage_failed' &&
+            planResult.cleanupDirs.length === 0 &&
+            isRuntimeSurfaceSourceUnavailable(planResult.message)) {
+            planResult = withInstallerPackageSource(configDir, createPlan);
+        }
         const cleanupDirs = planResult.ok ? planResult.plan.cleanupDirs : planResult.cleanupDirs;
         // #2874 row 1/4/5: per-kind executed-plan entries, appended only as the
         // loop below actually finishes writing each kind — a kind that throws
@@ -1132,8 +1336,10 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
         // is safe even when configDir has no .gsd-source marker (artifactLayout: []).
         let nativePluginInstalled = false;
         if (behaviors.nativePlugin) {
-            const commandsGsdDir = runtimeArtifactLayout.findInstallSourceRoot(configDir);
-            const src = node_path_1.default.dirname(node_path_1.default.dirname(commandsGsdDir));
+            // Native plugin sources live only in the executing package, never in the
+            // durable Runtime Surface corpus. Do not derive this package root from a
+            // config-scoped provider that may now correctly resolve installed input.
+            const src = deps.packageRoot ?? executingPackageRoot();
             _installNativePluginIfDeclared(runtime, configDir, behaviors, src);
             nativePluginInstalled = true;
         }
@@ -1183,6 +1389,13 @@ function installOpencodeFamilySkills(runtime, targetDir, rawCommandsDir, pathPre
     const skillsKindEntry = layout.kinds.find((k) => k.kind === 'skills');
     if (!skillsKindEntry)
         return 0;
+    // #3712: combined-family runtimes take installRuntimeArtifacts' early return
+    // BEFORE its guard runs, and this writer honors `skillsKindEntry.home` below and
+    // then prunes that destination. opencode/kilo declare no `home` today, so there
+    // is no live escape — but that makes this a bypass waiting on a descriptor
+    // change rather than a safe omission, so it is guarded at the writer instead.
+    // Scoped to the SKILLS kind alone, for the same reason as the agents writer.
+    testHomeGuard.assertTestHomeSandboxed('installOpencodeFamilySkills', runtime, [skillsKindEntry]);
     const rawDir = rawCommandsDir;
     if (!rawDir || !installFs().existsSync(rawDir))
         return 0;
@@ -1337,20 +1550,37 @@ function installOpencodeFamilySkills(runtime, targetDir, rawCommandsDir, pathPre
  * @param capabilityRegistry - #2362: optional composed capability registry, threaded
  *   straight through to resolveRuntimeArtifactLayout (unused by the agents kind today,
  *   but kept for signature parity with the skills/commands siblings on this call tree)
+ * @param projectDir - project/config discovery root, distinct from the artifact destination
  * @returns `{ sourceDir, destDir }` describing what was written, or `null` when the
  *   runtime's layout declares no `agents` kind.
  */
-function installAgentsKindStandalone(runtime, targetDir, scope, resolvedProfile, pathPrefix, resolveAttribution = () => undefined, capabilityRegistry) {
+function installAgentsKindStandalone(runtime, targetDir, scope, resolvedProfile, pathPrefix, resolveAttribution = () => undefined, capabilityRegistry, projectDir) {
     const layout = runtimeArtifactLayout.resolveRuntimeArtifactLayout(runtime, targetDir, scope, capabilityRegistry);
-    const agentsKindEntry = layout.kinds.find((k) => k.kind === 'agents');
+    const agentsKindEntry = layout.kinds.find((kind) => kind.kind === 'agents');
     if (!agentsKindEntry)
         return null;
+    // #3712: this writer selects `agentsKindEntry.home` over targetDir below and then
+    // prunes that destination via _removeGsdEntries, so it is a fifth route into the
+    // developer's real home. No agents kind declares a `home` override today, so like
+    // installOpencodeFamilySkills it is guarded against a descriptor change rather
+    // than a present escape. Scoped to the AGENTS kind alone: passing the whole
+    // layout made codex's unrelated skills-kind override trip a writer that never
+    // touches it, which is a false refusal, not a tighter guard.
+    testHomeGuard.assertTestHomeSandboxed('installAgentsKindStandalone', runtime, [agentsKindEntry]);
     // ADR-1235 §1: same agentCtx shape createRuntimeArtifactInstallPlan builds
     // for the generic layout-driven loop (runtime-artifact-install-plan.cts) —
     // targetDir IS the install root the inline agent loop called `targetDir`.
     const attribution = resolveAttribution ? resolveAttribution(runtime) : undefined;
-    const agentCtx = { runtime, pathPrefix, attribution, targetDir };
-    const stagedDir = agentsKindEntry.stage(resolvedProfile, agentCtx);
+    const agentCtx = { runtime, pathPrefix, attribution, targetDir, projectDir: projectDir ?? targetDir };
+    let stagedDir;
+    try {
+        stagedDir = agentsKindEntry.stage(resolvedProfile, agentCtx);
+    }
+    catch (err) {
+        if (scope !== 'global' || !isRuntimeSurfaceSourceUnavailable(err.message))
+            throw err;
+        stagedDir = withInstallerPackageSource(targetDir, () => agentsKindEntry.stage(resolvedProfile, agentCtx));
+    }
     const stagedAgentFiles = installFs().existsSync(stagedDir)
         ? installFs().readdirSync(stagedDir).filter((f) => f.endsWith('.md'))
         : [];
@@ -1611,12 +1841,13 @@ function _migrateLegacyOpencodeCommandDir(runtime, configDir, behaviors) {
  *   installOpencodeFamilySkills so an installed third-party capability skill
  *   materializes for this combined-family (OpenCode/Kilo) install path too.
  *   Absent -> no third-party skills staged (fail closed).
+ * @param projectDir - project/config discovery root, distinct from configDir for global installs
  * @returns #2874 design row 2: an executed-plan value, same top-level shape
  *   (`runtime`/`scope`/`kinds`/`cleanup`/`postSteps`) as the generic
  *   `installRuntimeArtifacts` branch — this was the one early return a
  *   `void`-shaped hole survived unnoticed in.
  */
-function installOpencodeFamilyArtifacts(runtime, configDir, scope, resolvedProfile, resolveAttribution = () => undefined, behaviors = {}, capabilityRegistry) {
+function installOpencodeFamilyArtifacts(runtime, configDir, scope, resolvedProfile, resolveAttribution = () => undefined, behaviors = {}, capabilityRegistry, packageRoot, projectDir) {
     // #2870: `scope` keeps its exported required `string` signature (no
     // signature change). It is always the `installRuntimeArtifacts`-forwarded
     // 'global' | 'local' literal produced by bin/install.js's scope-resolution
@@ -1629,7 +1860,7 @@ function installOpencodeFamilyArtifacts(runtime, configDir, scope, resolvedProfi
     // into stageSkillsForProfile/stageSkillsForRuntimeAsSkills. The repo/package
     // root (needed below for the native plugin source) is two levels up.
     const commandsGsdDir = runtimeArtifactLayout.findInstallSourceRoot(configDir);
-    const src = node_path_1.default.dirname(node_path_1.default.dirname(commandsGsdDir));
+    const src = packageRoot ?? executingPackageRoot();
     const rawCommandsDir = installProfiles.stageSkillsForProfile(commandsGsdDir, resolvedProfile);
     const pathPrefix = runtimeArtifactConversion._computePathPrefix({
         isGlobal,
@@ -1652,7 +1883,7 @@ function installOpencodeFamilyArtifacts(runtime, configDir, scope, resolvedProfi
     // generic layout-driven loop uses (see installAgentsKindStandalone's own
     // doc). A `null` result means this runtime's layout declares no `agents`
     // kind — nothing written, nothing reported (no #1879-F15 inert claim).
-    const agentsResult = installAgentsKindStandalone(runtime, configDir, scope, resolvedProfile, pathPrefix, resolveAttribution, capabilityRegistry);
+    const agentsResult = installAgentsKindStandalone(runtime, configDir, scope, resolvedProfile, pathPrefix, resolveAttribution, capabilityRegistry, projectDir);
     _installNativePluginIfDeclared(runtime, configDir, behaviors, src);
     // #2874 design row 2: report what this combined-family install wrote,
     // mirroring the generic branch's top-level shape. `cleanup` is `[]` — this
@@ -1683,7 +1914,7 @@ function installOpencodeFamilyArtifacts(runtime, configDir, scope, resolvedProfi
  * @param configDir           resolved runtime config directory
  * @param scope
  */
-function uninstallRuntimeArtifacts(runtime, configDir, scope) {
+function uninstallRuntimeArtifacts(runtime, configDir, scope, deps = {}) {
     // A retired descriptor kind is absent from the current uninstall plan, just
     // as it is absent from the install plan. Sweep manifest-proven output from
     // retired kinds before removing the current layout so a direct uninstall
@@ -1695,6 +1926,12 @@ function uninstallRuntimeArtifacts(runtime, configDir, scope) {
     // (the layout's gsd-* prefix pass would wipe a skill dir created here).
     const stagedLegacyArtifacts = _runLegacyUninstallCleanup(runtime, configDir, scope);
     const layout = runtimeArtifactLayout.resolveRuntimeArtifactLayout(runtime, configDir, scope);
+    // #3712: uninstall resolves the SAME `kind.home` override as install and then
+    // prunes it via _removeGsdEntries below, so it is a second escape route into
+    // the developer's real home, not a read-only path. Guard it identically.
+    testHomeGuard.assertTestHomeSandboxed('uninstallRuntimeArtifacts', runtime, layout?.kinds, {
+        os: deps.os, env: deps.env,
+    });
     const plan = runtimeArtifactInstallPlan.createRuntimeArtifactUninstallPlan(layout);
     const kindsByName = new Map(layout.kinds.map((kind) => [kind.kind, kind]));
     for (const item of plan.items) {

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

@@ -45,7 +45,7 @@ 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;
+const { resolveTierEntry: gsdResolveTierEntry, resolveModelPolicy: gsdResolveModelPolicy } = 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
@@ -114,6 +114,50 @@ function readGsdEffectiveModelOverrides(targetDir = null, options = {}) {
     // Per-project wins on conflict; preserve non-conflicting global keys.
     return { ...(global || {}), ...(projectOverrides || {}) };
 }
+function readGsdAgentTools(config) {
+    const raw = config?.agent_tools;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return null;
+    const result = {};
+    for (const [selector, value] of Object.entries(raw)) {
+        // An explicitly present selector always has a verdict. Invalid values are
+        // empty so a project config cannot accidentally restore a global grant.
+        result[selector] = Array.isArray(value)
+            ? value.filter((entry) => typeof entry === 'string')
+                .map((entry) => entry.trim())
+                .filter((entry) => entry.length > 0
+                && !entry.endsWith(':')
+                && !/[\s\u0000-\u001F\u007F-\u009F,#"'\u2028\u2029]/.test(entry))
+            : [];
+    }
+    return result;
+}
+/**
+ * Resolve valid install-time `agent_tools` grants from global defaults and
+ * the nearest project config. Project selectors replace only matching global
+ * selectors; malformed whole files remain harmless absence like the existing
+ * model override resolver.
+ */
+function readGsdEffectiveAgentTools(targetDir = null, options = {}) {
+    const home = options.homedir ? options.homedir() : node_os_1.default.homedir();
+    const globalConfig = _readGsdConfigFile(node_path_1.default.join(home, '.gsd', 'defaults.json'), 'global defaults');
+    let projectConfig = null;
+    if (targetDir) {
+        const candidate = _findAncestorGsdConfigPath(targetDir);
+        if (candidate) {
+            projectConfig = _readGsdConfigFile(candidate, 'project config');
+        }
+    }
+    const global = readGsdAgentTools(globalConfig);
+    const project = readGsdAgentTools(projectConfig);
+    if (projectConfig
+        && Object.prototype.hasOwnProperty.call(projectConfig, 'agent_tools')
+        && project === null)
+        return {};
+    if (!global && !project)
+        return null;
+    return { ...(global || {}), ...(project || {}) };
+}
 /**
  * Build a runtime-aware tier resolver for the install path (#2517).
  *
@@ -145,6 +189,10 @@ function readGsdRuntimeProfileResolver(targetDir = null) {
         model_profile_overrides: (projectConfig && projectConfig.model_profile_overrides) ||
             (homeDefaults && homeDefaults.model_profile_overrides) ||
             null,
+        // #3705: same project-wins-over-home precedence as every other key here.
+        model_policy: (projectConfig && projectConfig.model_policy) ||
+            (homeDefaults && homeDefaults.model_policy) ||
+            null,
     };
     if (!merged.runtime)
         return null;
@@ -164,6 +212,34 @@ function readGsdRuntimeProfileResolver(targetDir = null) {
             const tier = agentModels[profile] || agentModels.balanced;
             if (!tier)
                 return null;
+            // #3705: policy sits between the per-agent override and the tier table —
+            // the position dispatch uses. Measured against `query resolve-model` on the
+            // same config: policy-only -> the policy model; tier-overrides-only -> the
+            // override; BOTH -> the policy model. So policy outranks
+            // `model_profile_overrides`, and an explicit `model_overrides[agent]`
+            // (applied by resolveAgentModelOverride below) outranks policy.
+            //
+            // Calls the exported owner (#49) rather than re-deriving tier -> model here:
+            // a second implementation of that mapping is the very divergence this issue
+            // is, one layer down. A null from it (unknown provider, missing tier key, a
+            // `runtime_tiers` miss) falls through to the tier table — never to null,
+            // which would omit a frontmatter key that used to be written.
+            // The policy object must carry the effective runtime before it is resolved.
+            // `resolveModelPolicy`'s `runtime_tiers` branch reads `policy['runtime']`, but
+            // the documented config shape (docs/CONFIGURATION.md) puts `runtime` at the
+            // TOP level and keeps only `provider`/`runtime_tiers` inside `model_policy`.
+            // Dispatch injects it — `{ ...config.model_policy, runtime: effectiveRuntime }`
+            // (model-resolver.cts) — and passing the policy unmodified here silently
+            // skipped `runtime_tiers` entirely, falling through to the flat hi/med/lo keys
+            // or the catalog tier. That is the same "catalog Anthropic ID baked over a
+            // configured provider" defect this fix exists to close, so the injection is
+            // mirrored rather than assumed.
+            const policyForRuntime = merged.model_policy
+                ? { ...merged.model_policy, runtime }
+                : null;
+            const policyModel = gsdResolveModelPolicy(policyForRuntime, tier);
+            if (policyModel)
+                return { model: policyModel };
             return gsdResolveTierEntry({
                 runtime,
                 tier,
@@ -198,6 +274,7 @@ function resolveAgentModelOverride(agentName, modelOverrides, runtimeResolver) {
 module.exports = {
     readGsdGlobalModelOverrides,
     readGsdEffectiveModelOverrides,
+    readGsdEffectiveAgentTools,
     readGsdRuntimeProfileResolver,
     resolveAgentModelOverride,
 };