@opengsd/gsd-core 1.18.0 → 1.19.0

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

@@ -52,6 +52,7 @@ const userArtifactStaging = require("./user-artifact-staging.cjs");
 // module-level doc comment on `isGlobalScope` for why the projection is
 // centralized rather than eliminated).
 const install_scope_cjs_1 = require("./install-scope.cjs");
+const args_terminator_cjs_1 = require("./args-terminator.cjs");
 const { processAttribution } = runtimeArtifactConversion;
 // resolveRuntimeArtifactLayout: accessed via module ref (not destructured) so
 // test stubs that monkeypatch the module's exports are seen at call time.
@@ -233,7 +234,8 @@ function applyOpencodeFamilyPathPrefix(content, runtime, pathPrefix) {
     content = content.replace(/\.\/\.claude\//g, `./${getDirName(runtime)}/`);
     content = content.replace(/~\/\.opencode\//g, pathPrefix);
     content = content.replace(/~\/\.kilo\//g, pathPrefix);
-    return content;
+    // #5637: the typed-text capture heredoc ends at a terminator the typed text cannot know.
+    return (0, args_terminator_cjs_1.stampInstalledContent)(content);
 }
 /**
  * Convert a Claude command (.md) to an OpenCode skill (SKILL.md).
@@ -755,10 +757,17 @@ function _copyStaged(stagedDir, destDir, kind, configDir, runtime) {
  * For the prefix='' case: the destSubpath IS the namespace — remove the entire
  * destDir. (No current runtime uses prefix='' after #947 reversed Hermes; kept
  * as a defensive guard for future runtimes.)
+ *
+ * `owns` (#5161): when supplied, a prefix match is necessary but NOT
+ * sufficient — an entry is removed only when `owns(name)` is true, and every
+ * prefix-matching entry it rejects is returned so the caller can name it.
+ * Omitted (agents, commands, uninstall), every prefix match is removed as
+ * before and the return value is always empty.
  */
-function _removeGsdEntries(destDir, kind) {
+function _removeGsdEntries(destDir, kind, owns) {
+    const preserved = [];
     if (!installFs().existsSync(destDir))
-        return;
+        return preserved;
     if (kind.kind === 'kimi-agents') {
         for (const fileName of ['gsd.yaml', 'gsd.md']) {
             installFs().rmSync(node_path_1.default.join(destDir, fileName), { force: true });
@@ -775,19 +784,158 @@ function _removeGsdEntries(destDir, kind) {
                 installFs().rmSync(node_path_1.default.join(subagentsDir, entry.name), { force: true });
             }
         }
-        return;
+        return preserved;
     }
     if (kind.prefix === '') {
         // Whole-namespace removal (Hermes nested case — destSubpath is skills/gsd)
         // The directory itself is the GSD namespace, so remove it entirely.
         installFs().rmSync(destDir, { recursive: true, force: true });
-        return;
+        return preserved;
     }
     for (const entry of installFs().readdirSync(destDir, { withFileTypes: true })) {
         if (!entry.name.startsWith(kind.prefix))
             continue;
+        if (owns && !owns(entry.name)) {
+            preserved.push(entry.name);
+            continue;
+        }
         installFs().rmSync(node_path_1.default.join(destDir, entry.name), { recursive: true, force: true });
     }
+    return preserved;
+}
+// ---------------------------------------------------------------------------
+// Skill-dir ownership (#5161)
+// ---------------------------------------------------------------------------
+/**
+ * GSD-prefixed skill dirs the user owns and GSD never reinstalls from source
+ * (#2973). The skills writers snapshot them across the prune and restore them.
+ */
+const USER_OWNED_SKILL_DIRS = ['gsd-dev-preferences'];
+/** The skill dirs each writer wrote, keyed on the resolved skills dir (recordWrittenSkillDirs). */
+const writtenSkillDirs = new Map();
+/**
+ * Record the skill dirs a writer just wrote into `skillsDir`, replacing that
+ * dir's entry. Called only once the write has returned, so a writer that threw
+ * records nothing.
+ */
+function recordWrittenSkillDirs(skillsDir, names) {
+    writtenSkillDirs.set(node_path_1.default.resolve(skillsDir), new Set(names));
+}
+/** Start an install's record empty, so no earlier install's writes are read. */
+function clearWrittenSkillDirs() {
+    writtenSkillDirs.clear();
+}
+/**
+ * Build the predicate that decides whether a prefix-matching dir in
+ * `skillsDir` is GSD-owned (#5161). A prefix match is necessary but NOT
+ * sufficient — the rule surface.cts pruneSkillDirs already applies. A dir is
+ * GSD-owned when any of these hold:
+ *   - it is a first-party skill: `<prefix><stem>` for a commands/gsd/<stem>.md
+ *     in the install source;
+ *   - it carries the capability-skill marker (a third-party capability skill
+ *     GSD staged, install-profiles.cts CAPABILITY_SKILL_MARKER);
+ *   - `includeManifest` is not false and the previous install's
+ *     gsd-file-manifest.json records a file under it (a skill GSD installed
+ *     before that has since been retired or left the active profile).
+ * Anything else is user-owned or unknown. The first-time baseline migration
+ * may already have resolved it to `keep`, and the prune must honor that.
+ *
+ * writeManifest builds this with `includeManifest: false`: a preserved user
+ * dir recorded into the manifest would read back as GSD-owned on the next
+ * install and be deleted then.
+ *
+ * `manifestIfSourceUnresolved` is writeManifest's answer when the install
+ * source cannot be read, which leaves no first-party leg. It turns the manifest
+ * leg back on for that case only, so the dirs the previous install recorded
+ * stay recorded and the fallback adds no dir the previous manifest does not
+ * already record (beyond capability-marked ones). Owning every dir instead
+ * would record a user's kept dir, and the next install would read it back as
+ * GSD-owned and delete it: the #5161 failure, reached through a fallback. The
+ * cost is a skill first shipped by this release going unrecorded until the
+ * next install with a readable source. A prune never needs the flag: it keeps
+ * every dir it cannot otherwise prove, and its manifest leg is already on.
+ *
+ * `includeWritten` adds the skill dirs this install wrote into `skillsDir`
+ * (recordWrittenSkillDirs). The first-party lookups can miss the corpus a run
+ * staged: staging resolves its provider under the layout's requirement and the
+ * installed corpus's manifest, so it can take a corpus a `.gsd-source` marker
+ * names that neither lookup reaches, and its skills would then go uncounted
+ * and unrecorded. Only the skill counts and writeManifest pass the flag, since
+ * they must own what the install wrote. Every prune leaves it unset, so the
+ * record never widens what is deleted.
+ */
+function createSkillDirOwnership(runtime, configDir, skillsDir, prefix, opts = {}) {
+    // First-party stems come from BOTH the configDir-resolved source and the
+    // executing package's own source. Staging resolves its provider with the
+    // commands+agents requirement while a commands-only lookup can accept a
+    // different provider (a commands-only `.gsd-source` marker), so either root
+    // alone can miss the corpus the run staged. Both are GSD corpora, so the
+    // union only ever widens what GSD owns.
+    const firstParty = new Set();
+    let sourceResolved = false;
+    let lastError = null;
+    const roots = [
+        () => runtimeArtifactLayout.findInstallSourceRoot(configDir),
+        () => runtimeArtifactLayout.findInstallSourceRoot(undefined),
+    ];
+    for (const root of roots) {
+        try {
+            const commandsGsdDir = root();
+            // A regular `.md` file only — the filter every skills writer stages
+            // with. A source counts as resolved only once it yields a stem.
+            for (const entry of installFs().readdirSync(commandsGsdDir, { withFileTypes: true })) {
+                if (!entry.isFile() || !entry.name.endsWith('.md'))
+                    continue;
+                firstParty.add(prefix + entry.name.slice(0, -3));
+                sourceResolved = true;
+            }
+        }
+        catch (err) {
+            lastError = err;
+        }
+    }
+    if (!sourceResolved) {
+        console.warn(`  [gsd] could not read the install source to classify ${skillsDir} (${lastError?.message}) — ${opts.manifestIfSourceUnresolved ? 'treating as GSD-owned only the gsd- skill dirs the previous install manifest records or that carry the capability-skill marker' : 'keeping every gsd- skill dir GSD cannot otherwise prove it owns'}.`);
+    }
+    const manifestNames = new Set();
+    if (opts.includeManifest !== false || (!sourceResolved && opts.manifestIfSourceUnresolved === true)) {
+        // The prefix must describe the root being pruned: a manifest name under one
+        // root says nothing about a same-named dir under another (Hermes' flat
+        // pre-#2841 root vs its nested skills/gsd/ root).
+        const manifestPrefix = opts.manifestPrefix ?? (hostBehaviorsFor(runtime).skillsManifestPrefix || 'skills/');
+        for (const key of Object.keys(installerMigrations.readInstallManifest(configDir).files)) {
+            if (!key.startsWith(manifestPrefix))
+                continue;
+            const rest = key.slice(manifestPrefix.length);
+            const slash = rest.indexOf('/');
+            if (slash > 0)
+                manifestNames.add(rest.slice(0, slash));
+        }
+    }
+    const written = opts.includeWritten === true ? writtenSkillDirs.get(node_path_1.default.resolve(skillsDir)) : undefined;
+    return (name) => firstParty.has(name) ||
+        manifestNames.has(name) ||
+        written?.has(name) === true ||
+        installFs().existsSync(node_path_1.default.join(skillsDir, name, installProfiles.CAPABILITY_SKILL_MARKER));
+}
+/**
+ * Report each prefix-matching skill dir the prune preserved as not GSD-owned,
+ * by path (#5161). The deletion this replaces was silent.
+ *
+ * A USER_OWNED_SKILL_DIRS entry is never named: GSD special-cases it (the
+ * writers restore it and writeManifest records it), so "GSD does not own it,
+ * rename it" would be false. It reaches this list whenever no previous
+ * manifest records it yet, e.g. the first update after the user generates it.
+ *
+ * The message names no manifest: the legacy-location cleanups decide without
+ * one, so "not in the previous install manifest" would be false there.
+ */
+function _warnPreservedSkillDirs(skillsDir, names) {
+    for (const name of names) {
+        if (USER_OWNED_SKILL_DIRS.includes(name))
+            continue;
+        console.warn(`  [gsd] Preserved ${node_path_1.default.join(skillsDir, name)} — it matches the gsd- skill prefix but nothing shows GSD owns it here. Rename it if it should not share GSD's prefix.`);
+    }
 }
 // ---------------------------------------------------------------------------
 // _snapshotDir / _restoreDir
@@ -833,14 +981,17 @@ function _restoreDir(dir, snapshot) {
  *
  * @param nestedGsdDir  absolute path to skills/gsd/ category dir
  */
-function _removeHermesBareStemDirs(nestedGsdDir) {
+function _removeHermesBareStemDirs(nestedGsdDir, owns) {
     if (!installFs().existsSync(nestedGsdDir))
         return;
     const entries = installFs().readdirSync(nestedGsdDir, { withFileTypes: true });
     // Collect the set of stems that were installed as gsd-<stem>/ this run.
+    // #5161: the prune now keeps gsd-* dirs GSD does not own, so "present" no
+    // longer means "installed". With `owns`, only an owned gsd-<stem>/ counts,
+    // and a user's own <stem>/ beside their own gsd-<stem>/ is left alone.
     const installedStems = new Set();
     for (const entry of entries) {
-        if (entry.isDirectory() && entry.name.startsWith('gsd-')) {
+        if (entry.isDirectory() && entry.name.startsWith('gsd-') && (!owns || owns(entry.name))) {
             installedStems.add(entry.name.slice('gsd-'.length)); // e.g. 'quick', 'dev-preferences'
         }
     }
@@ -893,15 +1044,37 @@ function _runLegacyInstallMigrations(runtime, configDir, scope = 'global') {
         }
     }
     // Hermes: remove pre-#2841 flat skills/gsd-*/ entries that lived alongside
-    // the new skills/gsd/ nested layout. (#5169: `hostBehaviors.legacyFlatSkillsCleanup`.)
+    // the new skills/gsd/ nested layout (#5169: `hostBehaviors.legacyFlatSkillsCleanup`).
+    // #5161: skills/ is also Hermes' own skills root, so this runs on every
+    // install against dirs the user may own — remove only what GSD owns, keep
+    // and name the rest.
     if (hostBehaviorsFor(runtime).legacyFlatSkillsCleanup) {
         const flatSkillsDir = node_path_1.default.join(configDir, 'skills');
         if (installFs().existsSync(flatSkillsDir)) {
+            // The flat root's manifest entries were recorded as skills/gsd-<x>/…, not
+            // under Hermes' current nested prefix.
+            const ownsSkillDir = createSkillDirOwnership(runtime, configDir, flatSkillsDir, 'gsd-', { manifestPrefix: 'skills/' });
+            const kept = [];
             for (const entry of installFs().readdirSync(flatSkillsDir, { withFileTypes: true })) {
-                if (entry.isDirectory() && entry.name.startsWith('gsd-')) {
-                    installFs().rmSync(node_path_1.default.join(flatSkillsDir, entry.name), { recursive: true });
+                if (!entry.name.startsWith('gsd-'))
+                    continue;
+                // A symlink is never removed here (as before); name it when unowned.
+                if (entry.isSymbolicLink()) {
+                    if (!ownsSkillDir(entry.name))
+                        kept.push(entry.name);
+                    continue;
                 }
+                if (!entry.isDirectory())
+                    continue;
+                // gsd-dev-preferences is user content even when an old manifest records
+                // it, and nothing here restores it (#2973), so it is never removed.
+                if (!ownsSkillDir(entry.name) || USER_OWNED_SKILL_DIRS.includes(entry.name)) {
+                    kept.push(entry.name);
+                    continue;
+                }
+                installFs().rmSync(node_path_1.default.join(flatSkillsDir, entry.name), { recursive: true });
             }
+            _warnPreservedSkillDirs(flatSkillsDir, kept);
         }
         // Hermes: bare-stem skills/gsd/<stem>/ cleanup is deferred to AFTER the
         // layout-driven install loop in installRuntimeArtifacts, where the exact set
@@ -1117,6 +1290,8 @@ function _runLegacyUninstallCleanup(runtime, configDir, scope = 'global') {
  */
 function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, resolveAttribution = () => undefined, capabilityRegistry, deps = {}) {
     return withInstallFs(deps.fs, () => {
+        // #5161: this install's record of the skill dirs it writes starts empty.
+        clearWrittenSkillDirs();
         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
@@ -1253,7 +1428,9 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
                 }
                 installFs().mkdirSync(dest, { recursive: true });
                 const preserved = [];
-                if (kind.kind === 'skills' && installFs().existsSync(dest)) {
+                // #5161: keyed on the kind alone, so the non-skills branch below can
+                // never reach a skills dest with the prune that ignores ownership.
+                if (kind.kind === 'skills') {
                     // Pre-prune: snapshot user-owned content before _removeGsdEntries wipes it,
                     // then restore after. This preserves user dirs across a wipe-and-replace
                     // install (#2973 / #3664).
@@ -1264,24 +1441,37 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
                     // gsd-dev-preferences, which GSD does not reinstall from source but must
                     // survive the prune (#2973).
                     const toPreserve = new Map(); // dirName -> Map<relPath, Buffer>
-                    {
-                        // Preserve explicitly user-owned GSD-prefixed skill dirs.
-                        // gsd-dev-preferences is the sole user-customisable skill in this category.
-                        const USER_OWNED_SKILL_DIRS = ['gsd-dev-preferences'];
-                        for (const dirName of USER_OWNED_SKILL_DIRS) {
-                            const skillDir = node_path_1.default.join(dest, dirName);
-                            if (!installFs().existsSync(skillDir))
-                                continue;
-                            const snap = _snapshotDir(skillDir);
-                            if (snap.size > 0)
-                                toPreserve.set(dirName, snap);
-                        }
+                    for (const dirName of USER_OWNED_SKILL_DIRS) {
+                        const skillDir = node_path_1.default.join(dest, dirName);
+                        if (!installFs().existsSync(skillDir))
+                            continue;
+                        const snap = _snapshotDir(skillDir);
+                        if (snap.size > 0)
+                            toPreserve.set(dirName, snap);
                     }
-                    _removeGsdEntries(dest, kind);
+                    // #5161: prune only what GSD owns — a dir this run is about to write,
+                    // or one createSkillDirOwnership proves GSD's. Any other gsd-* dir is
+                    // user-owned or unknown: keep it and name it.
+                    const stagedNames = new Set(installFs().existsSync(item.sourceDir) ? installFs().readdirSync(item.sourceDir) : []);
+                    const ownsSkillDir = createSkillDirOwnership(runtime, configDir, dest, kind.prefix);
+                    // A USER_OWNED_SKILL_DIRS entry is never pruned, even when the manifest
+                    // leg owns it: the restore below skips symlinks, so a prune-then-restore
+                    // loses a symlinked SKILL.md. The restore remains for prune paths that
+                    // do not consult `owns`.
+                    const notOwned = _removeGsdEntries(dest, kind, (name) => !USER_OWNED_SKILL_DIRS.includes(name) && (stagedNames.has(name) || ownsSkillDir(name)));
+                    _warnPreservedSkillDirs(dest, notOwned);
                     _copyStaged(item.sourceDir, dest, kind, configDir, runtime);
-                    // Restore user-owned dirs after the prune+copy
+                    // The dirs _copyStaged just wrote: each directory child of the stage.
+                    recordWrittenSkillDirs(dest, installFs().existsSync(item.sourceDir)
+                        ? installFs().readdirSync(item.sourceDir, { withFileTypes: true })
+                            .filter((e) => e.isDirectory()).map((e) => e.name)
+                        : []);
+                    // Restore user-owned dirs after the prune+copy — only one a prune
+                    // branch that does not consult `owns` actually removed. Writing over
+                    // the kept dir would fail on a read-only file the user left there.
                     for (const [dirName, snap] of toPreserve) {
-                        _restoreDir(node_path_1.default.join(dest, dirName), snap);
+                        if (!installFs().existsSync(node_path_1.default.join(dest, dirName)))
+                            _restoreDir(node_path_1.default.join(dest, dirName), snap);
                         preserved.push(dirName);
                     }
                 }
@@ -1322,7 +1512,10 @@ function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, res
         let hermesBareStemCleanup = false;
         if (hostBehaviorsFor(runtime).bareStemSkillsCleanup) {
             const nestedGsdDirForCleanup = node_path_1.default.join(configDir, 'skills', 'gsd');
-            _removeHermesBareStemDirs(nestedGsdDirForCleanup);
+            // gsd-dev-preferences is restored rather than staged, and its legacy bare
+            // dev-preferences/ twin is one this cleanup exists for (#947).
+            const ownsNested = createSkillDirOwnership(runtime, configDir, nestedGsdDirForCleanup, 'gsd-', { includeManifest: false });
+            _removeHermesBareStemDirs(nestedGsdDirForCleanup, (name) => ownsNested(name) || USER_OWNED_SKILL_DIRS.includes(name));
             hermesBareStemCleanup = true;
         }
         // Generic-branch nativePlugin staging (ADR-1239 / #2102 Stage 1): runtimes
@@ -1427,7 +1620,6 @@ function installOpencodeFamilySkills(runtime, targetDir, rawCommandsDir, pathPre
     // and lives at <configDir>/skills/gsd-dev-preferences — _removeGsdEntries
     // would otherwise wipe it. Mirrors the preservation in installRuntimeArtifacts
     // (#2973).
-    const USER_OWNED_SKILL_DIRS = ['gsd-dev-preferences'];
     const toPreserve = new Map(); // dirName -> Map<relPath, Buffer>
     for (const dirName of USER_OWNED_SKILL_DIRS) {
         const skillDir = node_path_1.default.join(dest, dirName);
@@ -1437,8 +1629,20 @@ function installOpencodeFamilySkills(runtime, targetDir, rawCommandsDir, pathPre
         if (snap.size > 0)
             toPreserve.set(dirName, snap);
     }
-    _removeGsdEntries(dest, skillsKindEntry);
+    // #5161: same ownership gate as installRuntimeArtifacts' skills kind. The
+    // first-party set is rawDir's stems (exactly what this writer is about to
+    // write); third-party capability skills carry the marker.
+    // Same entry filter as the write loop below (a regular `.md` file), so a
+    // name is owned here only if this writer is about to rewrite it.
+    const rawStemNames = new Set(installFs().readdirSync(rawDir, { withFileTypes: true })
+        .filter((e) => e.isFile() && e.name.endsWith('.md'))
+        .map((e) => `${skillsKindEntry.prefix}${e.name.slice(0, -3)}`));
+    const ownsSkillDir = createSkillDirOwnership(runtime, targetDir, dest, skillsKindEntry.prefix);
+    _warnPreservedSkillDirs(dest, 
+    // Never pruned, as in installRuntimeArtifacts: the restore skips symlinks.
+    _removeGsdEntries(dest, skillsKindEntry, (name) => !USER_OWNED_SKILL_DIRS.includes(name) && (rawStemNames.has(name) || ownsSkillDir(name))));
     let count = 0;
+    const written = new Set();
     const firstPartyStems = new Set();
     for (const entry of installFs().readdirSync(rawDir, { withFileTypes: true })) {
         if (!entry.isFile() || !entry.name.endsWith('.md'))
@@ -1453,6 +1657,7 @@ function installOpencodeFamilySkills(runtime, targetDir, rawCommandsDir, pathPre
         const skillDir = node_path_1.default.join(dest, skillName);
         installFs().mkdirSync(skillDir, { recursive: true });
         installFs().writeFileSync(node_path_1.default.join(skillDir, 'SKILL.md'), content);
+        written.add(skillName);
         count++;
     }
     // #2362: materialize installed THIRD-PARTY capability skills, bound to their
@@ -1506,13 +1711,17 @@ function installOpencodeFamilySkills(runtime, targetDir, rawCommandsDir, pathPre
             // capability is uninstalled/unsurfaced and no longer appears in any
             // registry view.
             installFs().writeFileSync(node_path_1.default.join(skillDir, installProfiles.CAPABILITY_SKILL_MARKER), found.capId + '\n', 'utf8');
+            written.add(skillName);
             count++;
         }
     }
-    // Restore user-owned dirs after the prune+copy.
+    // Restore user-owned dirs after the prune+copy, only where a prune removed
+    // one; the kept dir is left untouched (it may hold read-only files).
     for (const [dirName, snap] of toPreserve) {
-        _restoreDir(node_path_1.default.join(dest, dirName), snap);
+        if (!installFs().existsSync(node_path_1.default.join(dest, dirName)))
+            _restoreDir(node_path_1.default.join(dest, dirName), snap);
     }
+    recordWrittenSkillDirs(dest, written);
     return count;
 }
 // ---------------------------------------------------------------------------
@@ -1544,7 +1753,7 @@ function installOpencodeFamilySkills(runtime, targetDir, rawCommandsDir, pathPre
  * (`layout.kinds` → `agentsKindEntry.stage(resolvedProfile, agentCtx)` →
  * `_copyStaged`), rather than forking a second agent-staging pipeline. A
  * runtime/scope whose resolved layout declares no `agents` kind at all
- * (e.g. pi, whose `artifactLayout` is empty for both scopes) is a no-op
+ * (e.g. pi, whose `artifactLayout` is skills-only for both scopes, #5547) is a no-op
  * (`null`) — mirrors `installOpencodeFamilySkills`'s own
  * `if (!skillsKindEntry) return 0` contract.
  *
@@ -2038,6 +2247,11 @@ module.exports = {
     _runLegacyInstallMigrations,
     _runLegacyUninstallCleanup,
     _removeGsdEntries,
+    createSkillDirOwnership,
+    recordWrittenSkillDirs,
+    clearWrittenSkillDirs,
+    _warnPreservedSkillDirs,
+    USER_OWNED_SKILL_DIRS,
     _snapshotDir,
     _restoreDir,
     _removeHermesBareStemDirs,

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

@@ -302,7 +302,7 @@ function _capabilitySkillsForMode(mode, registry) {
 /**
  * Resolve a profile (or composed profiles) to a typed result object.
  */
-function resolveProfile({ modes, manifest, _profilesOverride, registry } = {}) {
+function resolveProfile({ modes, manifest, _profilesOverride, registry, agentManifest } = {}) {
     const profiles = _profilesOverride || PROFILES;
     const activeModes = (modes && modes.length > 0) ? modes : ['full'];
     const normalizedModes = activeModes
@@ -337,10 +337,13 @@ function resolveProfile({ modes, manifest, _profilesOverride, registry } = {}) {
     }
     // Derive agents: union of all agent names referenced in the body text of
     // every skill in unionSkills. Agent names are stored in the manifest under
-    // _calls_agents_<stem> keys (populated by loadSkillsManifest).
+    // _calls_agents_<stem> keys (populated by loadSkillsManifest). #5503: read from
+    // `agentManifest` when given, so a profile that skips the skill closure still
+    // stages the agents its own skills spawn.
+    const agentMan = agentManifest || man;
     const unionAgents = new Set();
     for (const skillStem of unionSkills) {
-        const agentRefs = man.get(`_calls_agents_${skillStem}`) || [];
+        const agentRefs = agentMan.get(`_calls_agents_${skillStem}`) || [];
         for (const agentStem of agentRefs) {
             unionAgents.add(agentStem);
         }
@@ -940,7 +943,7 @@ function stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converte
  * @param isGlobal        install scope passed through to the converter
  * @param agentCtx        optional cross-cutting context (ADR-1235 §1)
  */
-function stageAgentsForRuntimeWithConverter(srcAgentsDir, resolvedProfile, converter, isGlobal = false, agentCtx) {
+function stageAgentsForRuntimeWithConverter(srcAgentsDir, resolvedProfile, converter, isGlobal = false, agentCtx, excludeSuffixes) {
     if (!installFs().existsSync(srcAgentsDir))
         return srcAgentsDir;
     const stageDir = mkInstallTempDir('gsd-profile-runtime-agents-');
@@ -976,6 +979,8 @@ function stageAgentsForRuntimeWithConverter(srcAgentsDir, resolvedProfile, conve
                 continue;
             if (!entry.name.endsWith('.md'))
                 continue;
+            if (excludeSuffixes && excludeSuffixes.some((s) => entry.name.endsWith(s)))
+                continue;
             // For tiered profiles, gate by agent stem (full filename without extension).
             if (resolvedProfile.skills !== '*') {
                 const stem = entry.name.slice(0, -3);

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

@@ -51,6 +51,8 @@ exports.BUNDLED_GSD_HOOK_FILES = Object.freeze(new Set([
     // #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',
+    // #5465: SessionStart PATH persistence through $CLAUDE_ENV_FILE.
+    'hooks/gsd-path-export.js',
     'hooks/gsd-phase-boundary.sh',
     'hooks/gsd-prompt-guard.js',
     'hooks/gsd-read-guard.js',

package/gsd-core/bin/lib/markdown-line-diff.cjs

@@ -0,0 +1,147 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_SCOPED_EDIT_DISTANCE = void 0;
+exports.matchLines = matchLines;
+exports.writeScope = writeScope;
+/**
+ * Line alignment for scoped Markdown normalization (#5165).
+ *
+ * `platformWriteSync` re-spaces a `.md` document on every write. Given the
+ * document the write replaces, only the line junctions the write itself made
+ * need that treatment; everything else is published byte-for-byte. This module
+ * is the pure half of that: it aligns the new lines against the prior lines and
+ * says which junctions the write left alone. It performs no I/O.
+ */
+/**
+ * Largest line-edit distance `matchLines` will search for. A write that changed
+ * more than this many lines is a rewrite, not an edit: it falls back to
+ * whole-document normalization (the pre-#5165 behavior), which also bounds the
+ * diff's time and memory.
+ */
+exports.MAX_SCOPED_EDIT_DISTANCE = 400;
+/**
+ * Align the lines of the document being written (`next`) against the document
+ * it replaces (`prev`). Returns, per `next` line, the index of its counterpart
+ * in `prev` (a longest-common-subsequence match, Myers' O(ND) greedy diff after
+ * trimming the common prefix and suffix), or -1 for a line the write added or
+ * changed. Null when the documents differ by more than MAX_SCOPED_EDIT_DISTANCE
+ * edits.
+ */
+function matchLines(prev, next) {
+    const match = new Int32Array(next.length).fill(-1);
+    const common = Math.min(prev.length, next.length);
+    let lo = 0;
+    while (lo < common && prev[lo] === next[lo]) {
+        match[lo] = lo;
+        lo++;
+    }
+    let prevEnd = prev.length;
+    let nextEnd = next.length;
+    while (prevEnd > lo && nextEnd > lo && prev[prevEnd - 1] === next[nextEnd - 1]) {
+        prevEnd--;
+        nextEnd--;
+        match[nextEnd] = prevEnd;
+    }
+    const a = prev.slice(lo, prevEnd);
+    const b = next.slice(lo, nextEnd);
+    const n = a.length;
+    const m = b.length;
+    if (n === 0 || m === 0)
+        return match;
+    const max = Math.min(n + m, exports.MAX_SCOPED_EDIT_DISTANCE);
+    const off = max + 1;
+    const v = new Int32Array(2 * max + 3);
+    const trace = [];
+    let found = -1;
+    for (let d = 0; d <= max && found < 0; d++) {
+        trace.push(v.slice()); // the furthest-reaching points after d-1 edits
+        for (let k = -d; k <= d; k += 2) {
+            let x = (k === -d || (k !== d && v[off + k - 1] < v[off + k + 1])) ? v[off + k + 1] : v[off + k - 1] + 1;
+            let y = x - k;
+            while (x < n && y < m && a[x] === b[y]) {
+                x++;
+                y++;
+            }
+            v[off + k] = x;
+            if (x >= n && y >= m) {
+                found = d;
+                break;
+            }
+        }
+    }
+    if (found < 0)
+        return null;
+    let x = n;
+    let y = m;
+    for (let d = found; d > 0; d--) {
+        const before = trace[d];
+        const k = x - y;
+        const prevK = (k === -d || (k !== d && before[off + k - 1] < before[off + k + 1])) ? k + 1 : k - 1;
+        const prevX = before[off + prevK];
+        const prevY = prevX - prevK;
+        while (x > prevX && y > prevY) {
+            x--;
+            y--;
+            match[lo + y] = lo + x;
+        }
+        x = prevX;
+        y = prevY;
+    }
+    while (x > 0 && y > 0) {
+        x--;
+        y--;
+        match[lo + y] = lo + x;
+    }
+    return match;
+}
+/**
+ * Derive a {@link WriteScope} from a line alignment. A junction is the write's
+ * own — and so is normalized — when it is wholly inside text the write added,
+ * or when a deletion between two kept lines made them newly adjacent. The
+ * boundary of an edit that replaced lines inherits the surrounding spacing:
+ * replacing a line in place must not add blank lines around it.
+ */
+function writeScope(match, prevLength) {
+    // For each unmatched line: how many prior lines its run of changed lines replaced.
+    const replaced = new Int32Array(match.length);
+    const priorIndex = new Int32Array(match.length).fill(-1);
+    for (let i = 0; i < match.length;) {
+        if (match[i] >= 0) {
+            i++;
+            continue;
+        }
+        let end = i;
+        while (end + 1 < match.length && match[end + 1] < 0)
+            end++;
+        const before = i > 0 ? match[i - 1] : -1;
+        const after = end + 1 < match.length ? match[end + 1] : prevLength;
+        const dropped = after - before - 1;
+        for (let j = i; j <= end; j++) {
+            replaced[j] = dropped;
+            if (j - i < dropped)
+                priorIndex[j] = before + 1 + (j - i);
+        }
+        i = end + 1;
+    }
+    return {
+        junctionKept(i) {
+            const left = match[i] >= 0;
+            const right = match[i + 1] >= 0;
+            // Two kept lines are one junction only if nothing sat between them in the
+            // prior document; a deletion made them adjacent, so the write owns it.
+            if (left && right)
+                return match[i + 1] - match[i] === 1;
+            if (left)
+                return replaced[i + 1] >= 1;
+            if (right)
+                return replaced[i] >= 1;
+            return false;
+        },
+        lineWritten(i) {
+            return match[i] < 0;
+        },
+        replacedPriorIndex(i) {
+            return priorIndex[i] ?? -1;
+        },
+    };
+}