@opengsd/gsd-core 1.9.0 → 1.10.0

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

@@ -28,8 +28,10 @@ const runtimeArtifactInstallPlan = require("./runtime-artifact-install-plan.cjs"
 const runtimeNamePolicy = require("./runtime-name-policy.cjs");
 const installProfiles = require("./install-profiles.cjs");
 const installerMigrations = require("./installer-migrations.cjs");
+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 { processAttribution } = runtimeArtifactConversion;
 // resolveRuntimeArtifactLayout: accessed via module ref (not destructured) so
 // test stubs that monkeypatch the module's exports are seen at call time.
@@ -315,13 +317,25 @@ function migrateLegacyDevPreferencesToSkill(targetDir, saved, runtime, scope = '
     if (!saved || !saved.has('dev-preferences.md'))
         return false;
     let skillDir;
+    // #2911: the actual install root the skill dir resolves under — defaults to
+    // targetDir, but a skills-kind `home` override (e.g. Codex -> $HOME/.agents)
+    // moves it entirely outside targetDir. Every confinement/guard check below
+    // must confine against installRoot, not targetDir, or it would flag the
+    // legitimate override destination as an escape.
+    let installRoot = targetDir;
     if (runtime) {
         const layout = runtimeArtifactLayout.resolveRuntimeArtifactLayout(runtime, targetDir, scope);
         const skillsKindEntry = layout.kinds.find((k) => k.kind === 'skills');
         if (!skillsKindEntry)
             return false; // runtime has no skills layout at this scope (e.g. cline local)
         const stemName = skillsKindEntry.prefix === '' ? 'dev-preferences' : 'gsd-dev-preferences';
-        skillDir = node_path_1.default.join(runtimeArtifactInstallPlan.assertDestWithinConfigHome(targetDir, skillsKindEntry.destSubpath), stemName);
+        // #2911: same destination-root defect as _copyStaged/applySurface — honor
+        // skillsKindEntry.home as a FALLBACK-preferred override (e.g. Codex skills
+        // -> $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.
+        installRoot = skillsKindEntry.home ?? targetDir;
+        skillDir = node_path_1.default.join(runtimeArtifactInstallPlan.assertDestWithinConfigHome(installRoot, skillsKindEntry.destSubpath), stemName);
     }
     else {
         // Legacy fallback for callers that have not yet been updated to pass runtime
@@ -330,11 +344,11 @@ function migrateLegacyDevPreferencesToSkill(targetDir, saved, runtime, scope = '
     const skillFile = node_path_1.default.join(skillDir, 'SKILL.md');
     if (node_fs_1.default.existsSync(skillFile))
         return false;
-    // Symlink-escape guard: reject if any path component between targetDir and
-    // skillDir is a symlink that would redirect writes outside the config root.
+    // Symlink-escape guard: reject if any path component between installRoot and
+    // skillDir is a symlink that would redirect writes outside the install root.
     // #2393: honor GSD_ALLOW_SYMLINKED_DEST for intentional user-owned symlink layouts.
-    if (hasExistingSymlinkBetween(node_path_1.default.resolve(targetDir), skillDir, { allowOptInFollow: isSymlinkedDestOptIn() })) {
-        throw new Error(`migrateLegacyDevPreferencesToSkill: skillDir "${skillDir}" contains a symlink the install root "${targetDir}" does not trust — refusing to write. If this is an intentional user-owned symlink layout, re-run with GSD_ALLOW_SYMLINKED_DEST=1.`);
+    if (hasExistingSymlinkBetween(node_path_1.default.resolve(installRoot), skillDir, { allowOptInFollow: isSymlinkedDestOptIn() })) {
+        throw new Error(`migrateLegacyDevPreferencesToSkill: skillDir "${skillDir}" contains a symlink the install root "${installRoot}" does not trust — refusing to write. If this is an intentional user-owned symlink layout, re-run with GSD_ALLOW_SYMLINKED_DEST=1.`);
     }
     try {
         node_fs_1.default.mkdirSync(skillDir, { recursive: true });
@@ -675,6 +689,10 @@ function _runLegacyUninstallCleanup(runtime, configDir, scope = 'global') {
  *   (fail closed), matching the layout resolver's own optional-registry contract.
  */
 function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, resolveAttribution = () => undefined, 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).
+    retiredArtifactCleanup.pruneRetiredRuntimeArtifacts(runtime, configDir);
     // Combined-family runtimes (OpenCode/Kilo, ADR-1239 / #2087): route through
     // the dedicated combined commands+skills+plugin orchestrator instead of the
     // generic layout-driven loop below, mirroring the bespoke install path that
@@ -849,12 +867,19 @@ function installOpencodeFamilySkills(runtime, targetDir, rawCommandsDir, pathPre
     if (!converter) {
         throw new TypeError(`installOpencodeFamilySkills: unknown skills converter '${String(converterName)}' for runtime '${runtime}'`);
     }
-    const dest = runtimeArtifactInstallPlan.assertDestWithinConfigHome(targetDir, skillsKindEntry.destSubpath);
-    // Symlink-escape guard: reject if any path component between targetDir and
-    // dest is a symlink that would redirect writes outside the config root.
+    // #2911: same destination-root defect as _copyStaged/migrateLegacyDevPreferencesToSkill
+    // — honor skillsKindEntry.home as a FALLBACK-preferred override (e.g. Codex skills
+    // -> $HOME/.agents) instead of always resolving against targetDir, so this bespoke
+    // OpenCode/Kilo writer lands in the SAME tree the installer and surface-apply use.
+    // Runtimes with no `home` override (opencode, kilo today) are unaffected. Must stay
+    // in lockstep with the sibling writers — the destination-parity test enforces it.
+    const installRoot = skillsKindEntry.home ?? targetDir;
+    const dest = runtimeArtifactInstallPlan.assertDestWithinConfigHome(installRoot, skillsKindEntry.destSubpath);
+    // Symlink-escape guard: reject if any path component between installRoot and
+    // dest is a symlink that would redirect writes outside the install root.
     // #2393: honor GSD_ALLOW_SYMLINKED_DEST for intentional user-owned symlink layouts.
-    if (hasExistingSymlinkBetween(node_path_1.default.resolve(targetDir), dest, { allowOptInFollow: isSymlinkedDestOptIn() })) {
-        throw new Error(`installOpencodeFamilySkills: destDir "${dest}" contains a symlink the install root "${targetDir}" does not trust — refusing to write. If this is an intentional user-owned symlink layout, re-run with GSD_ALLOW_SYMLINKED_DEST=1.`);
+    if (hasExistingSymlinkBetween(node_path_1.default.resolve(installRoot), dest, { allowOptInFollow: isSymlinkedDestOptIn() })) {
+        throw new Error(`installOpencodeFamilySkills: destDir "${dest}" contains a symlink the install root "${installRoot}" does not trust — refusing to write. If this is an intentional user-owned symlink layout, re-run with GSD_ALLOW_SYMLINKED_DEST=1.`);
     }
     node_fs_1.default.mkdirSync(dest, { recursive: true });
     // Preserve user-owned GSD-prefixed skill dirs across the gsd-* prune.
@@ -1037,6 +1062,30 @@ function _installNativePluginIfDeclared(runtime, configDir, behaviors, src) {
             const destPath = runtimeArtifactInstallPlan.assertDestWithinConfigHome(configDir, node_path_1.default.join(np.dir, np.file));
             node_fs_1.default.mkdirSync(node_path_1.default.dirname(destPath), { recursive: true });
             node_fs_1.default.copyFileSync(pluginSrc, destPath);
+            // #2544: the staged adapter is a `.js` file, so Node decides its module
+            // type by walking up for the nearest package.json. It used to find the
+            // marker the installer wrote at the config root — the write that
+            // clobbered user-authored files. Pin it from the plugin's own directory
+            // instead, leaving the config root alone. The marker cannot disturb
+            // plugin discovery: OpenCode auto-discovers `plugins/*.{ts,js}` and pi's
+            // isExtensionFile() accepts only `.ts`/`.js` (see installer-migration
+            // 006), so a package.json here is never treated as a plugin. Never
+            // written over a package.json GSD does not own — but when one is already
+            // there, say so: the adapter is CommonJS and will not load under a
+            // foreign `"type": "module"`, and a silent no-op would leave every guard
+            // the adapter spawns dead with no diagnostic (the #2305 failure shape).
+            const markerOutcome = (0, commonjs_marker_cjs_1.ensureCommonJsMarker)(node_path_1.default.dirname(destPath));
+            if (markerOutcome === 'preserved-foreign') {
+                console.warn(`  ⚠  ${np.dir}/package.json is not GSD's CommonJS marker — left untouched. `
+                    + `If it declares "type": "module", ${np.file} will not load.`);
+            }
+            else if (markerOutcome === 'failed') {
+                // Best-effort, never fatal: an unwritable plugin dir must not abort the
+                // install. Same warn-and-continue posture as the foreign-marker branch —
+                // the adapter is staged either way, it just may not resolve as CommonJS.
+                console.warn(`  ⚠  Could not write ${np.dir}/package.json (CommonJS marker) — install continued. `
+                    + `If the config root declares "type": "module", ${np.file} will not load.`);
+            }
         }
     }
 }
@@ -1180,6 +1229,11 @@ function installOpencodeFamilyArtifacts(runtime, configDir, scope, resolvedProfi
  * @param scope
  */
 function uninstallRuntimeArtifacts(runtime, configDir, scope) {
+    // 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
+    // cannot leave stale runtime surfaces behind (#2644).
+    retiredArtifactCleanup.pruneRetiredRuntimeArtifacts(runtime, configDir);
     // Legacy cleanup before layout-driven removal (scope-aware to avoid
     // removing Claude local commands/gsd/ which is the primary install dir).
     // Returns saved user artifacts so we can migrate AFTER layout removal

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

@@ -20,6 +20,13 @@ const external_descriptor_trust_cjs_1 = require("./external-descriptor-trust.cjs
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const conversionModule = require("./runtime-artifact-conversion.cjs");
 const { applyAgentPathRewrites: _applyAgentPathRewrites, processAttribution: _processAttribution, normalizeAgentBodyForRuntime: _normalizeAgentBodyForRuntime, readGsdCommandNames: _readGsdCommandNames, } = conversionModule;
+// #2995 (epic #1671 Phase 6.4): agent bodies join the fragment model. Markers are
+// stripped at emit BEFORE any path rewrite or converter runs, so a `.claude/` ->
+// `.windsurf/` regex can never reach inside a marker attribute and corrupt it —
+// the same ordering #2930 established for workflows.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const workflowFragmentsModule = require("./workflow-fragments.cjs");
+const { composeWorkflow: _composeWorkflow } = workflowFragmentsModule;
 // ---------------------------------------------------------------------------
 // Profile definitions
 // ---------------------------------------------------------------------------
@@ -329,6 +336,19 @@ function stageSkillsForProfile(srcDir, resolvedProfile) {
  * For tiered profiles, copies only agents whose full stem (e.g. 'gsd-planner')
  * is in resolvedProfile.agents — which is populated by resolveProfile() from
  * the _calls_agents_* entries in the manifest.
+ *
+ * ⚠️ RAW STAGER — ITS OUTPUT IS NOT EMISSION-READY (#2995). This stager performs a
+ * plain `fs.copyFileSync` and — under the default `full` profile — short-circuits
+ * and returns the real source directory unstaged. It does NOT strip `gsd:section`
+ * markers. It is still called, by `bin/install.js`'s `_stageAgents`, whose output
+ * feeds the inline agent loop and `installCodexConfig`; both of those compose the
+ * content themselves before writing, so the raw output never reaches disk. What
+ * changed in #2995 is that `agentsKind` and `kimiAgentsKind` no longer use it —
+ * they route through `stageAgentsForRuntimeWithConverter`, which composes.
+ *
+ * The invariant to preserve: anything that takes this function's output and WRITES
+ * it as a runtime artifact must call `composeWorkflow` on each file first, or it
+ * ships markers verbatim.
  */
 function stageAgentsForProfile(srcAgentsDir, resolvedProfile) {
     if (resolvedProfile.skills === '*')
@@ -796,7 +816,13 @@ function stageAgentsForRuntimeWithConverter(srcAgentsDir, resolvedProfile, conve
                     continue;
                 }
             }
-            let content = node_fs_1.default.readFileSync(node_path_1.default.join(srcAgentsDir, entry.name), 'utf8');
+            const agentSourcePath = node_path_1.default.join(srcAgentsDir, entry.name);
+            let content = node_fs_1.default.readFileSync(agentSourcePath, 'utf8');
+            // #2995: strip gsd:section markers FIRST — before path rewrites, attribution,
+            // and the per-runtime converter. Byte-identical (no-op) for an unmarked agent;
+            // throws loudly naming the file for a malformed marker, never emitting a
+            // half-composed agent.
+            content = _composeWorkflow(content, { sourcePath: agentSourcePath });
             if (agentCtx) {
                 // ADR-1235 §1: pre-converter cross-cutting (matches inline loop order exactly)
                 // Step 1: path rewrites (4 base ~/.claude/ regexes; skipped for copilot/antigravity)

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

@@ -109,7 +109,9 @@ function validateInstallerMigrationActions(actions, migration) {
         // Ownership and runtime-contract evidence are required by
         // docs/installer-migrations.md#action-types and
         // docs/adr/0008-installer-migration-module.md#runtime-contract-decision.
-        if (actType === 'remove-managed' || actType === 'rewrite-json') {
+        // `remove-empty-dir` carries the same evidence bar as `remove-managed`: it is
+        // still a destructive removal, just of a directory node instead of a file.
+        if (actType === 'remove-managed' || actType === 'rewrite-json' || actType === 'remove-empty-dir') {
             requireActionEvidence(act, 'ownershipEvidence', migration);
         }
         if (actType === 'rewrite-json') {

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

@@ -32,6 +32,7 @@ const VALID_CHOICES = ['keep', 'remove'];
 // on-disk `hooks/` directory in both directions: whitelist-but-missing
 // AND shipped-but-not-whitelisted both fail CI.
 exports.BUNDLED_GSD_HOOK_FILES = Object.freeze(new Set([
+    'hooks/gsd-agent-isolation-guard.js',
     'hooks/gsd-check-update-worker.js',
     'hooks/gsd-check-update.js',
     'hooks/gsd-config-reload.js',
@@ -57,6 +58,7 @@ exports.BUNDLED_GSD_HOOK_FILES = Object.freeze(new Set([
     'hooks/gsd-validate-commit.sh',
     'hooks/gsd-workflow-guard.js',
     'hooks/gsd-worktree-path-guard.js',
+    'hooks/gsd-write-guard.js',
 ]));
 // ── Internal helpers ──────────────────────────────────────────────────────────
 function installerMigrationActionLabel(action) {
@@ -74,6 +76,8 @@ function installerMigrationActionLabel(action) {
         return 'preserved';
     if (action.type === 'preserve-user')
         return 'preserved';
+    if (action.type === 'remove-empty-dir')
+        return 'removed';
     if (action.type === 'prompt-user')
         return 'blocked';
     return 'skipped';

package/gsd-core/bin/lib/installer-migrations/007-retire-config-root-commonjs-marker.cjs

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * Installer migration: retire the config-root `{"type":"commonjs"}` marker that
+ * pre-#2544 installs wrote over `<configRoot>/package.json`.
+ *
+ * What old artifact is being retired?
+ *   `package.json` at the runtime config root. Before #2544,
+ *   `installSharedHooksBundle(destRootDir)` wrote `{"type":"commonjs"}` there
+ *   unconditionally on every install and every re-install, to pin GSD's staged
+ *   `.js` hook scripts to CommonJS via Node's ancestor walk. #2544 moved that
+ *   marker into the directories GSD actually fills (`hooks/`, and the
+ *   `nativePlugin.dir` for runtimes declaring one) and stopped writing the
+ *   config root at all. Without this migration an upgrader keeps BOTH markers:
+ *   the new one under `hooks/` and the stale one at the root, so the config
+ *   root stays pinned to CommonJS and the PR's own claim — that GSD no longer
+ *   writes the shared config root — is false for every install made since the
+ *   marker was introduced, until the user uninstalls.
+ *
+ * How do we prove it is GSD-owned?
+ *   By exact content match, NOT by the manifest. The config-root marker was
+ *   never recorded in `gsd-file-manifest.json` — `writeManifest()` records
+ *   `hooks/`, `agents/`, `commands/`, `scripts/`, and the native plugin, and
+ *   has never had a `manifest.files['package.json']` entry — so
+ *   `classifyArtifact('package.json')` answers `unknown` and the planner's
+ *   own guard would downgrade a `remove-managed` to `preserve-user`.
+ *   This migration therefore supplies the "purpose-built detector for an old
+ *   GSD-owned shape" that `docs/installer-migrations.md#remove-managed`
+ *   sanctions, and declares the resulting classification on the action: the
+ *   file is removed only when its bytes are exactly the marker GSD writes
+ *   (`{"type":"commonjs"}`, trailing whitespace tolerated). That is the same
+ *   predicate `removeCommonJsMarker` has always used on the uninstall side, so
+ *   install, uninstall, and migration cannot drift apart.
+ *
+ * What happens if the user modified it?
+ *   Then it is not the marker, and this migration does not touch it. Any
+ *   `package.json` carrying a `name`, `dependencies`, `scripts`, or any key
+ *   beyond the single `type` — i.e. every file the #2544 defect destroyed —
+ *   fails the exact-content test and is left exactly as found. There is
+ *   deliberately no `backup-and-remove` branch: a modified file here is not a
+ *   patched GSD artifact, it is somebody else's file.
+ *
+ * What happens if it is missing?
+ *   No actions. Fresh post-#2544 installs never wrote it, already-migrated
+ *   installs no longer have it, and the executor additionally journals a
+ *   `missing` outcome if it disappears between plan and apply. Idempotent.
+ *
+ * What runtime and scope does it affect?
+ *   Every runtime whose config root received the marker — i.e. every runtime
+ *   not excluded from `installSharedHooksBundle(targetDir)` by
+ *   `hostBehaviors.skipSharedHooksInstall` and not Codex: antigravity,
+ *   augment, claude, claude-local, codebuddy, hermes, qwen, kilo, opencode,
+ *   and pi. The `runtimes` field is OMITTED — the framework's "all runtimes" —
+ *   rather than carrying that hand-list: a runtime that never received the
+ *   marker simply has no file to match, so enumerating them would add a second
+ *   place for the set to drift out of date without changing behavior. Note it
+ *   must be omitted and not `[]`; see the field's own comment below.
+ *
+ *   ONE DELIBERATE CARVE-OUT — kimi. Kimi's marker was written to its native
+ *   hook root (`~/.kimi`, `resolveKimiHooksTomlDir`), which is NOT under
+ *   kimi's `configDir` (its generic Agent-Skills root). Migration relPaths are
+ *   structurally confined to `configDir` (`validateSafeRelPath` /
+ *   `ensureInsideConfig`), so this framework cannot address that path at all.
+ *   Kimi's stale root marker is retired by the installer instead, at the same
+ *   call site that writes its replacement — see the `kimi-hooks-toml` branch
+ *   in `bin/install.js`. Named here so the gap is not mistaken for an
+ *   oversight.
+ *
+ * Is the action safe in non-interactive install?
+ *   Yes. `remove-managed` is non-interactive and journaled, the executor takes
+ *   a rollback snapshot before unlinking, and no branch of this migration can
+ *   emit `prompt-user`. A file that is not byte-identical to GSD's marker
+ *   produces no action at all.
+ *
+ * See docs/installer-migrations.md#shipped-migrations and #action-types.
+ */
+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"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
+/** The config-root path the pre-#2544 installer wrote, relative to configDir. */
+const STALE_ROOT_MARKER = 'package.json';
+/**
+ * The exact marker content GSD wrote. Duplicated as a literal rather than
+ * imported from `src/commonjs-marker.cts` on purpose: a migration record is a
+ * frozen historical statement about what a PAST version installed, and it must
+ * keep matching those bytes even if the live module's constant is ever changed.
+ * Importing would silently re-point this detector at a future value.
+ */
+const LEGACY_MARKER_CONTENT = '{"type":"commonjs"}';
+const OWNERSHIP_EVIDENCE = 'file content is byte-identical to the {"type":"commonjs"} marker pre-#2544 installs '
+    + 'wrote at the config root (installSharedHooksBundle); same exact-content predicate '
+    + 'removeCommonJsMarker uses on uninstall. Never manifest-recorded, so this is the '
+    + 'purpose-built detector permitted by docs/installer-migrations.md#remove-managed';
+const REASON = 'superseded by the hooks/ and plugin-dir markers (#2544); leaving it pins the shared '
+    + 'config root to CommonJS and keeps GSD occupying a file it no longer writes';
+const migration = {
+    id: '2026-07-28-retire-config-root-commonjs-marker',
+    title: 'Retire the pre-#2544 config-root CommonJS marker',
+    description: 'Remove <configRoot>/package.json when it is exactly the {"type":"commonjs"} marker '
+        + 'pre-#2544 installs wrote there, now superseded by markers scoped to the directories '
+        + 'GSD owns. A package.json with any other content is left untouched.',
+    introducedIn: '1.8.0',
+    scopes: ['global', 'local'],
+    destructive: true,
+    plan: (ctx) => {
+        const markerPath = node_path_1.default.join(ctx.configDir, STALE_ROOT_MARKER);
+        let stat;
+        try {
+            // lstat, not existsSync: existsSync follows symlinks and reports false for
+            // a dangling one. A symlink here is not something GSD wrote, and removing
+            // it is never ours to do — mirrors classifyMarker's fail-closed posture.
+            stat = node_fs_1.default.lstatSync(markerPath);
+        }
+        catch {
+            return [];
+        }
+        if (!stat.isFile())
+            return [];
+        let content;
+        try {
+            content = node_fs_1.default.readFileSync(markerPath, 'utf8');
+        }
+        catch {
+            // Present but unreadable never downgrades to the permissive answer.
+            return [];
+        }
+        if (content.trim() !== LEGACY_MARKER_CONTENT)
+            return [];
+        const hash = node_crypto_1.default.createHash('sha256').update(content).digest('hex');
+        return [
+            {
+                type: 'remove-managed',
+                relPath: STALE_ROOT_MARKER,
+                reason: REASON,
+                ownershipEvidence: OWNERSHIP_EVIDENCE,
+                // Declared, not derived: classifyArtifact answers 'unknown' for this
+                // never-manifested path, and the planner downgrades a remove-managed on
+                // an 'unknown' classification to preserve-user. The exact-content match
+                // above IS the ownership proof, so the classification is stated here.
+                classification: 'managed-pristine',
+                originalHash: hash,
+                currentHash: hash,
+            },
+        ];
+    },
+};
+module.exports = migration;

package/gsd-core/bin/lib/installer-migrations/008-cursor-retire-commands-surface.cjs

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * Installer migration: retire Cursor's duplicate commands/ surface (#2644).
+ *
+ * Cursor discovers GSD skills as slash-menu entries while also keeping them
+ * model-invocable. Older GSD releases installed the same workflows again as
+ * commands/gsd-*.md, so every action appeared twice. The skills remain the
+ * sole workflow surface; this migration removes only old command files proven
+ * managed by gsd-file-manifest.json. Modified files are backed up first and
+ * unmanifested files are preserved.
+ */
+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"));
+const COMMANDS_DIR = 'commands';
+const REASON = 'Cursor exposes skills directly in the slash menu; the parallel command file duplicated the same GSD action (#2644)';
+const OWNERSHIP_EVIDENCE = 'pre-#2644 Cursor installs record commands/gsd-*.md in gsd-file-manifest.json';
+const migration = {
+    id: '2026-07-29-cursor-retire-commands-surface',
+    title: 'Retire Cursor duplicate commands surface',
+    description: 'Remove manifest-managed Cursor commands/gsd-*.md files now that skills are the single slash-menu and model-invocation surface.',
+    introducedIn: '1.8.1',
+    runtimes: ['cursor'],
+    scopes: ['global', 'local'],
+    destructive: true,
+    plan: (ctx) => {
+        const commandsDir = node_path_1.default.join(ctx.configDir, COMMANDS_DIR);
+        let entries;
+        try {
+            if (!node_fs_1.default.existsSync(commandsDir) || node_fs_1.default.lstatSync(commandsDir).isSymbolicLink())
+                return [];
+            entries = node_fs_1.default.readdirSync(commandsDir, { withFileTypes: true });
+        }
+        catch {
+            return [];
+        }
+        const actions = [];
+        for (const entry of entries) {
+            if (!entry.isFile() || !entry.name.startsWith('gsd-') || !entry.name.endsWith('.md'))
+                continue;
+            const relPath = node_path_1.default.posix.join(COMMANDS_DIR, entry.name);
+            const artifact = ctx.classifyArtifact(relPath);
+            if (artifact.classification === 'managed-pristine') {
+                actions.push({ type: 'remove-managed', relPath, reason: REASON, ownershipEvidence: OWNERSHIP_EVIDENCE });
+            }
+            else if (artifact.classification === 'managed-modified') {
+                actions.push({ type: 'backup-and-remove', relPath, reason: REASON, ownershipEvidence: OWNERSHIP_EVIDENCE });
+            }
+        }
+        return actions;
+    },
+};
+module.exports = migration;

package/gsd-core/bin/lib/installer-migrations/009-pi-retire-reserved-hooks-dir.cjs

@@ -0,0 +1,199 @@
+"use strict";
+/**
+ * Installer migration: retire pi's legacy `<piConfigDir>/hooks/` directory
+ * after GSD's shared hook bundle moved to `<piConfigDir>/gsd-hooks/` (#3023).
+ *
+ * What old artifact is being retired?
+ *   `hooks/` (and its `hooks/lib/` subdirectory) at the pi config root. pi
+ *   reserves that exact name as its own deprecated extension directory and
+ *   warns on every startup whenever it exists — pi's
+ *   `checkDeprecatedExtensionDirs()` fires on mere PATH EXISTENCE, not on the
+ *   directory having contents (unlike the sibling `tools/` check, which does
+ *   `readdir` first). GSD used to install its shared hook bundle at exactly
+ *   that reserved path, so every pi install carried the warning permanently.
+ *   The fix moved the install target to `gsd-hooks/`
+ *   (`hostBehaviors.sharedHooksDirName`), but an EXISTING install that
+ *   upgrades still has the old `hooks/` tree sitting on disk — nothing
+ *   removes it on its own, so the warning would persist forever without this
+ *   migration.
+ *
+ * How do we prove it is GSD-owned?
+ *   Per file, by manifest membership — the same `classifyArtifact()` check
+ *   every other migration in this directory uses. Pre-#3023 pi installs
+ *   record the shared hook bundle under `hooks/…` keys in
+ *   `gsd-file-manifest.json`; the new install target writes `gsd-hooks/…`
+ *   keys instead, which this migration structurally never sees because it
+ *   only ever walks the `hooks/` subtree.
+ *
+ * What happens if the user modified it?
+ *   `backup-and-remove` instead of `remove-managed`, so a locally patched
+ *   hook script is recoverable from the backup rather than silently
+ *   destroyed — mirrors migration 006.
+ *
+ * What happens to files the manifest never recorded?
+ *   Nothing. An unmanifested file under `hooks/` (classification `unknown`)
+ *   is left exactly where it is, and — because its presence keeps the
+ *   directory non-empty — it also keeps the directory itself from being
+ *   retired. That is a deliberate consequence of directory removal being
+ *   gated on emptiness, not a special case.
+ *
+ * What happens to the directory itself?
+ *   `hooks/lib/` and then `hooks/` each get a `remove-empty-dir` action (see
+ *   `evaluateRemoveEmptyDir` in `../installer-migrations.cts`). That action
+ *   only ever calls `fs.rmdirSync` — never a recursive removal — and
+ *   re-checks emptiness immediately before doing so, so a directory that
+ *   still holds anything (an unmanifested file, or a file-level action that
+ *   failed to apply) is left in place rather than assumed empty. Actions are
+ *   emitted deepest-first (`hooks/lib` before `hooks`) so the parent has a
+ *   chance to become empty in the same pass.
+ *
+ * What happens if it is missing?
+ *   No actions. A fresh post-#3023 pi install never creates `hooks/` at all,
+ *   and an already-migrated install has nothing left to retire — both plan
+ *   empty, so the migration is idempotent.
+ *
+ * What runtime and scope does it affect?
+ *   pi only, global and local. No other runtime's install is affected:
+ *   `hostBehaviors.sharedHooksDirName` defaults to `'hooks'` for every other
+ *   runtime, and none of them reserve that name the way pi does, so a
+ *   claude/kimi/opencode/etc. `hooks/` directory is a live, in-use install
+ *   surface that must never be touched here. The runtime check is the FIRST
+ *   thing `plan()` does, ahead of even checking whether the directory exists,
+ *   as defense in depth beyond the `runtimes: ['pi']` record-level filter the
+ *   framework itself already enforces.
+ *
+ * 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, the pi row of
+ * docs/installer-migrations.md#runtime-configuration-contract-registry, and
+ * the 2026-08-07 amendment to docs/adr/0008-installer-migration-module.md.
+ */
+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"));
+/** pi's reserved (and, pre-#3023, GSD-populated) legacy hook directory name. */
+const HOOKS_DIR = 'hooks';
+const FILE_REASON = "pi's startup check warns whenever hooks/ exists (checkDeprecatedExtensionDirs), and GSD's shared " +
+    'hook bundle now installs at gsd-hooks/ instead (#3023), so the legacy files are superseded';
+const FILE_OWNERSHIP_EVIDENCE = 'pre-#3023 pi installs record the shared hook bundle under hooks/… keys in gsd-file-manifest.json; ' +
+    'the new install target is gsd-hooks/…, which this migration never touches because it only walks the ' +
+    'hooks/ subtree';
+const DIR_REASON = "pi's checkDeprecatedExtensionDirs() warns on hooks/'s mere existence, not its contents (#3023); the " +
+    'reserved container is retired once every GSD-owned entry inside it is gone';
+const DIR_OWNERSHIP_EVIDENCE = 'hooks/ and hooks/lib/ are GSD-installed container directories under the pi config root (the pre-#3023 ' +
+    'default of hostBehaviors.sharedHooksDirName); removal is gated on emptiness by the shared ' +
+    'remove-empty-dir action, so a directory that still holds an unmanifested user file — or any file-level ' +
+    'action that failed to apply — is left in place rather than assumed empty';
+/**
+ * Recursively collect files and directories under `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 003 (`walkLegacyFiles`).
+ */
+function walkPiHooksTree(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);
+            walkPiHooksTree(root, relPath, baseResolved, files, dirs);
+        }
+        else if (entry.isFile()) {
+            files.push(relPath);
+        }
+    }
+}
+const migration = {
+    id: '2026-08-07-pi-retire-reserved-hooks-dir',
+    title: "Retire pi's reserved hooks/ directory",
+    description: 'Remove manifest-managed files under <piConfigDir>/hooks/ and, once empty, the directory itself ' +
+        '(and its hooks/lib/ subdirectory), now that the shared hook bundle installs at gsd-hooks/ instead. pi ' +
+        'reserves hooks/ as its own deprecated extension directory and warns on every startup while it exists (#3023).',
+    introducedIn: '1.9.2',
+    runtimes: ['pi'],
+    scopes: ['global', 'local'],
+    destructive: true,
+    plan: (ctx) => {
+        // Defense in depth ahead of the framework's own runtimes filter: a
+        // claude/kimi/opencode/etc. hooks/ directory is a live install surface,
+        // never a retirement target.
+        if (ctx.runtime !== 'pi')
+            return [];
+        const hooksRoot = node_path_1.default.join(ctx.configDir, HOOKS_DIR);
+        let rootLstat;
+        try {
+            rootLstat = node_fs_1.default.lstatSync(hooksRoot);
+        }
+        catch {
+            return []; // absent -> nothing to retire, idempotent
+        }
+        // Never follow a symlinked hooks/ root: walking through it could plan
+        // actions against paths outside the pi config directory entirely.
+        if (rootLstat.isSymbolicLink())
+            return [];
+        if (!rootLstat.isDirectory())
+            return [];
+        const baseResolved = node_path_1.default.resolve(ctx.configDir);
+        const files = [];
+        const dirs = [];
+        try {
+            walkPiHooksTree(ctx.configDir, HOOKS_DIR, baseResolved, files, dirs);
+        }
+        catch {
+            // Unreadable directory: nothing safe to plan.
+            return [];
+        }
+        const actions = [];
+        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. `hooks/` itself is appended last, unconditionally: the
+        // executor's own emptiness re-check is what actually decides whether it
+        // goes, not this ordering — this ordering only gives it the chance to.
+        const orderedDirs = [...dirs].sort((a, b) => b.split('/').length - a.split('/').length);
+        orderedDirs.push(HOOKS_DIR);
+        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) rather than routed through the file
+                // classifier.
+                classification: 'managed-pristine',
+                originalHash: null,
+                currentHash: null,
+            });
+        }
+        return actions;
+    },
+};
+module.exports = migration;