@opengsd/gsd-core 1.11.0 → 1.12.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, ...)` —
@@ -409,6 +410,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 +430,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 +438,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
@@ -960,6 +999,11 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
         // Legacy cleanup before layout-driven writes
         _runLegacyInstallMigrations(runtime, configDir, scope);
         const layout = runtimeArtifactLayout.resolveRuntimeArtifactLayout(runtime, configDir, scope, capabilityRegistry);
+        // #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 planResult = runtimeArtifactInstallPlan.createRuntimeArtifactInstallPlan({
             // `Layout` is structurally identical across the layout/install-plan .cjs
             // modules but nominally distinct to tsc (untyped .cjs boundary) — bridge it.
@@ -1183,6 +1227,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;
@@ -1345,6 +1396,14 @@ function installAgentsKindStandalone(runtime, targetDir, scope, resolvedProfile,
     const agentsKindEntry = layout.kinds.find((k) => k.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`.
@@ -1683,7 +1742,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 +1754,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
@@ -145,6 +145,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 +168,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,

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

@@ -137,9 +137,79 @@ function parseCallsAgents(content) {
  * Also derives calls_agents for each skill by scanning the body text for
  * `gsd-*` agent name references. Agent stems are stored under the special
  * key `_calls_agents_<stem>` so they don't conflict with skill stems.
+ *
+ * #3798: command bodies are thin delegators — the actual `subagent_type=`
+ * spawns live in the workflow files each command references
+ * (`@…/workflows/<name>.md`). The agent derivation therefore ALSO reads every
+ * workflow file the command references (plus the workflow's steps/ fragments
+ * when it is split per the progressive-disclosure pattern) and unions their
+ * `gsd-*` tokens into the same `_calls_agents_<stem>` set. Without this,
+ * tiered profiles omitted agents their own installed skills spawn
+ * (gsd-verifier at execute-phase's verify_phase_goal was the filed repro).
+ * Over-inclusion fails safe: a tiered profile installing one extra agent
+ * costs bytes, never a broken spawn.
  */
 const DEFAULT_COMMANDS_DIR = node_path_1.default.resolve(__dirname, '..', '..', '..', 'commands', 'gsd');
-function loadSkillsManifest(commandsDir = DEFAULT_COMMANDS_DIR) {
+const DEFAULT_WORKFLOWS_DIR = node_path_1.default.resolve(__dirname, '..', '..', 'workflows');
+/**
+ * Collect the `gsd-*` agent tokens from every workflow file a command body
+ * references. References are the `workflows/<name>.md` path suffixes the
+ * delegating commands embed (`@…/gsd-core/workflows/<name>.md`). A
+ * split workflow (workflows/<name>/steps/*.md) contributes its fragments as
+ * well, because the parent dispatches into them and the spawns live there.
+ */
+function workflowAgentRefs(content, workflowsDir) {
+    const refs = content.match(/workflows\/([a-z0-9][a-z0-9-]*)\.md/g) || [];
+    const names = [...new Set(refs.map((r) => r.slice('workflows/'.length)))];
+    const tokens = new Set();
+    for (const name of names) {
+        const direct = node_path_1.default.join(workflowsDir, name);
+        let body = null;
+        try {
+            body = node_fs_1.default.readFileSync(direct, 'utf8');
+        }
+        catch {
+            body = null;
+        }
+        if (body === null)
+            continue;
+        for (const tok of parseCallsAgents(body))
+            tokens.add(tok);
+        // Split workflow: union EVERY fragment under the workflow's directory
+        // (steps/, modes/, templates/…) — the parent dispatches into these per
+        // the progressive-disclosure pattern, and spawns live in all of them
+        // (#3798 review: modes/ carried gsd-advisor-researcher's spawn while the
+        // parent only named it incidentally in prose).
+        const fragDir = node_path_1.default.join(workflowsDir, name.slice(0, -3));
+        const walk = (dir) => {
+            let frags;
+            try {
+                frags = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            for (const frag of frags) {
+                const full = node_path_1.default.join(dir, frag.name);
+                if (frag.isDirectory()) {
+                    walk(full);
+                    continue;
+                }
+                if (!frag.isFile() || !frag.name.endsWith('.md'))
+                    continue;
+                try {
+                    const fragBody = node_fs_1.default.readFileSync(full, 'utf8');
+                    for (const tok of parseCallsAgents(fragBody))
+                        tokens.add(tok);
+                }
+                catch { /* unreadable fragment — skip */ }
+            }
+        };
+        walk(fragDir);
+    }
+    return [...tokens];
+}
+function loadSkillsManifest(commandsDir = DEFAULT_COMMANDS_DIR, workflowsDir = DEFAULT_WORKFLOWS_DIR) {
     const manifest = new Map();
     if (!node_fs_1.default.existsSync(commandsDir))
         return manifest;
@@ -153,9 +223,12 @@ function loadSkillsManifest(commandsDir = DEFAULT_COMMANDS_DIR) {
         try {
             const content = node_fs_1.default.readFileSync(node_path_1.default.join(commandsDir, entry.name), 'utf8');
             manifest.set(stem, parseRequires(content));
-            // Derive agent references from body text
-            const agentRefs = parseCallsAgents(content);
-            manifest.set(`_calls_agents_${stem}`, agentRefs);
+            // Derive agent references from body text + the workflows it delegates to
+            const agentRefs = [
+                ...parseCallsAgents(content),
+                ...workflowAgentRefs(content, workflowsDir),
+            ];
+            manifest.set(`_calls_agents_${stem}`, [...new Set(agentRefs)]);
         }
         catch {
             manifest.set(stem, []);
@@ -1156,6 +1229,7 @@ module.exports = {
     // Shared internals
     parseRequires,
     parseCallsAgents,
+    workflowAgentRefs,
     cleanupStagedSkills,
     // #2322: capability-skill security seams — exported for direct unit-testing
     // and for surface.cts's prune pass (CAPABILITY_SKILL_MARKER parity).

package/gsd-core/bin/lib/installer-migration-report.cjs

@@ -48,6 +48,9 @@ exports.BUNDLED_GSD_HOOK_FILES = Object.freeze(new Set([
     'hooks/gsd-windsurf-pre-command.js',
     'hooks/gsd-ensure-canonical-path.js',
     'hooks/gsd-graphify-update.sh',
+    // #3662: portable node resolver staged into hooks/ (not itself a lifecycle
+    // hook — managed JS hook commands route through it under --portable-hooks).
+    'hooks/gsd-node-runner.sh',
     'hooks/gsd-phase-boundary.sh',
     'hooks/gsd-prompt-guard.js',
     'hooks/gsd-read-guard.js',

package/gsd-core/bin/lib/installer-migrations/010-antigravity-retire-confighome-artifacts.cjs

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * Installer migration: retire Antigravity's configHome skills/agents surfaces (#3738).
+ *
+ * Antigravity's machine-local discovery scans ~/.gemini/config/{skills,agents}
+ * (antigravity.google/docs/skills, /docs/subagents); the configHome
+ * (~/.gemini/antigravity{,-ide,-cli}) is not scanned for global artifacts, so
+ * skills installed there are silently ignored. Since #3738 the global layout
+ * declares a `home: ".gemini/config"` override for both kinds, and new
+ * installs land in the scanned dir. This migration converges an existing
+ * installation: manifest-managed files under the configHome's skills/ and
+ * agents/ subtrees are removed (modified ones backed up first), unmanifested
+ * files are preserved, and now-empty container directories are retired.
+ *
+ * Scope is GLOBAL only: the local workspace layout (.agents/skills,
+ * .agents/agents) is the documented, still-live surface and is never touched.
+ *
+ * Is the action safe in non-interactive install?
+ *   Yes. Every emitted action type (`remove-managed`, `backup-and-remove`,
+ *   `remove-empty-dir`) is non-interactive and journaled; none requires a
+ *   user choice, and unknown files never produce an action.
+ *
+ * See docs/installer-migrations.md#shipped-migrations and the antigravity row
+ * of docs/installer-migrations.md#runtime-configuration-contract-registry.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/** The two retired configHome-relative artifact subpaths. */
+const RETIRED_SUBPATHS = ['skills', 'agents'];
+/** Only GSD-owned top-level entries are retirement candidates. */
+const GSD_PREFIX = 'gsd-';
+const FILE_REASON = 'Antigravity scans ~/.gemini/config/{skills,agents} for global discovery and does not scan the ' +
+    'configHome, so these artifacts are invisible to the runtime (#3738); the same artifacts reinstall ' +
+    "under the global layout's .gemini/config home override";
+const FILE_OWNERSHIP_EVIDENCE = 'pre-#3738 antigravity installs record skills/gsd-*/** and agents/gsd-*.md keys in ' +
+    'gsd-file-manifest.json at the configHome root; the migration only walks gsd--prefixed entries ' +
+    'under the two retired subpaths';
+const DIR_REASON = 'the retired container directory is removed only once every GSD-owned entry inside it is gone; a ' +
+    'directory that still holds an unmanifested user file — or any file-level action that failed to ' +
+    'apply — is left in place by the emptiness re-check';
+const DIR_OWNERSHIP_EVIDENCE = 'skills/ and agents/ at the antigravity configHome root are GSD-installed container directories ' +
+    'from the pre-#3738 layout; removal is gated on emptiness by the shared remove-empty-dir action';
+/**
+ * Recursively collect files and directories under `root/relDir`, never
+ * following a symlink (whether it names a file or a directory) and never
+ * emitting a path that resolves outside `baseResolved`. Mirrors the traversal
+ * guard in migration 009 (`walkPiHooksTree`).
+ */
+function walkTree(root, relDir, baseResolved, files, dirs) {
+    const dir = node_path_1.default.join(root, relDir);
+    const entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        // Never follow a symlink into or through: it must not be traversed,
+        // hashed, or removed, regardless of what it points at.
+        if (entry.isSymbolicLink())
+            continue;
+        const relPath = node_path_1.default.posix.join(relDir, entry.name);
+        const resolved = node_path_1.default.resolve(root, relPath);
+        if (resolved !== baseResolved && !resolved.startsWith(baseResolved + node_path_1.default.sep))
+            continue;
+        if (entry.isDirectory()) {
+            dirs.push(relPath);
+            walkTree(root, relPath, baseResolved, files, dirs);
+        }
+        else if (entry.isFile()) {
+            files.push(relPath);
+        }
+    }
+}
+const migration = {
+    id: '2026-08-26-antigravity-retire-confighome-artifacts',
+    title: "Retire Antigravity's configHome skills/agents surfaces",
+    description: 'Remove manifest-managed skills/gsd-*/ and agents/gsd-*.md under the Antigravity configHome ' +
+        '(~/.gemini/antigravity{,-ide,-cli}) — a location Antigravity does not scan for global discovery — ' +
+        'and retire the now-empty container directories, now that the global layout installs both kinds ' +
+        'under the ~/.gemini/config home override (#3738). Global scope only; the local .agents workspace ' +
+        'surface is untouched.',
+    introducedIn: '1.11.0',
+    runtimes: ['antigravity'],
+    scopes: ['global'],
+    destructive: true,
+    plan: (ctx) => {
+        // Defense in depth ahead of the framework's own runtimes/scope filters:
+        // a claude/kimi/etc. skills/ or agents/ directory is a live install
+        // surface, never a retirement target, and so is antigravity's LOCAL
+        // .agents/skills layout.
+        if (ctx.runtime !== 'antigravity')
+            return [];
+        if (ctx.scope !== 'global')
+            return [];
+        const actions = [];
+        for (const subpath of RETIRED_SUBPATHS) {
+            const surfaceRoot = node_path_1.default.join(ctx.configDir, subpath);
+            let rootLstat;
+            try {
+                rootLstat = node_fs_1.default.lstatSync(surfaceRoot);
+            }
+            catch {
+                continue; // absent -> nothing to retire for this surface, idempotent
+            }
+            // Never follow a symlinked surface root: walking through it could plan
+            // actions against paths outside the config directory entirely.
+            if (rootLstat.isSymbolicLink() || !rootLstat.isDirectory())
+                continue;
+            const baseResolved = node_path_1.default.resolve(ctx.configDir);
+            const files = [];
+            const dirs = [];
+            try {
+                const entries = node_fs_1.default.readdirSync(surfaceRoot, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (entry.isSymbolicLink() || !entry.name.startsWith(GSD_PREFIX))
+                        continue;
+                    const relPath = node_path_1.default.posix.join(subpath, entry.name);
+                    if (entry.isDirectory()) {
+                        dirs.push(relPath);
+                        walkTree(ctx.configDir, relPath, baseResolved, files, dirs);
+                    }
+                    else if (entry.isFile()) {
+                        files.push(relPath);
+                    }
+                }
+            }
+            catch {
+                // Unreadable directory: nothing safe to plan for this surface.
+                continue;
+            }
+            for (const relPath of files) {
+                const { classification } = ctx.classifyArtifact(relPath);
+                if (classification === 'managed-pristine') {
+                    actions.push({ type: 'remove-managed', relPath, reason: FILE_REASON, ownershipEvidence: FILE_OWNERSHIP_EVIDENCE });
+                }
+                else if (classification === 'managed-modified') {
+                    actions.push({ type: 'backup-and-remove', relPath, reason: FILE_REASON, ownershipEvidence: FILE_OWNERSHIP_EVIDENCE });
+                }
+                // 'unknown' (user-added, not manifest-recorded): no action, preserved.
+                // 'missing' / 'managed-missing': impossible here — relPath was just
+                // discovered by walking the live filesystem, so it currently exists.
+            }
+            // Deepest directories first, so a child has already been evaluated
+            // (and possibly removed) before its parent's own emptiness is
+            // re-checked by the executor. The surface root itself is appended
+            // last, unconditionally: the executor's own emptiness re-check is what
+            // actually decides whether it goes, not this ordering.
+            const orderedDirs = [...dirs].sort((a, b) => b.split('/').length - a.split('/').length);
+            orderedDirs.push(subpath);
+            for (const relPath of orderedDirs) {
+                actions.push({
+                    type: 'remove-empty-dir',
+                    relPath,
+                    reason: DIR_REASON,
+                    ownershipEvidence: DIR_OWNERSHIP_EVIDENCE,
+                    // Declared, not derived: classifyArtifact() hashes file contents
+                    // via sha256File(), which throws EISDIR against a directory path.
+                    // These relPaths name directories, so classification is stated
+                    // directly (never 'unknown', so the planner's
+                    // unknown-classification block never fires for them).
+                    classification: 'managed-pristine',
+                    originalHash: null,
+                    currentHash: null,
+                });
+            }
+        }
+        return actions;
+    },
+};
+module.exports = migration;

package/gsd-core/bin/lib/installer-migrations.cjs

@@ -505,17 +505,20 @@ function acquireInstallMigrationLock(configDir, { timeoutMs = DEFAULT_LOCK_TIMEO
         let lockCreatedByUs = false;
         try {
             fd = node_fs_1.default.openSync(lockPath, 'wx');
-            // Close the open descriptor before writing so the file handle is
-            // released on Windows before the release closure unlinks it.
-            // Write payload via writeFileSync with the path (not the fd) so we
-            // don't hold an open fd across the lifetime of the lock.
-            node_fs_1.default.closeSync(fd);
-            fd = null;
             lockCreatedByUs = true; // we own the file; clean it up on any subsequent error
-            node_fs_1.default.writeFileSync(lockPath, JSON.stringify({
+            // Write the payload through the exclusively-created descriptor: a
+            // second open-by-path here would be a TOCTOU window (CWE-367) where a
+            // co-writer of the directory could symlink-swap the just-created empty
+            // lock file before the payload lands.
+            node_fs_1.default.writeFileSync(fd, JSON.stringify({
                 pid: process.pid,
                 acquiredAt: new Date().toISOString(),
             }) + '\n');
+            // Close before returning so no handle stays open across the lock's
+            // lifetime — Windows cannot unlink a file with an open handle when the
+            // release closure runs.
+            node_fs_1.default.closeSync(fd);
+            fd = null;
             lockCreatedByUs = false; // release closure owns cleanup from here
             return () => {
                 const failures = [];