@opengsd/gsd-core 1.7.0-rc.6 → 1.8.0

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

@@ -14,6 +14,9 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+// #2322: reuse the existing pure path-containment seam (ADR-1239 Phase C-2)
+// instead of hand-rolling a new traversal check for capability skill stems.
+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;
@@ -438,7 +441,182 @@ function transformRouterBodyToNested(converted) {
     });
     return out.join('\n');
 }
-function stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converter, prefix, nested = false) {
+/**
+ * #2322 SECURITY: a third-party `capability.json`'s `skills[]` entries are only
+ * validated for being STRINGS and not one of the 3 reserved prototype-pollution
+ * names (capability-validator.cjs validateFeatureBody, ~line 503) — NOT for
+ * non-emptiness and NOT for a safe path-segment shape. `isSafeCapabilitySkillStem`
+ * is therefore the SOLE defense against an empty-string, `..`-escaping,
+ * separator-carrying, absolute, or NUL-carrying stem reaching a filesystem path
+ * as a literal component — not a second defense-in-depth layer on top of any
+ * validator-enforced non-emptiness (there is none). Once unioned into
+ * resolveSurface's `resolved.skills` (#2045), such a stem must never reach
+ * fs.readFileSync/writeFileSync as a literal path component, or it can escape
+ * the capabilities root on read (or stageDir on write). Reject anything but a
+ * single, ordinary path segment.
+ */
+function isSafeCapabilitySkillStem(stem) {
+    if (typeof stem !== 'string' || stem.length === 0)
+        return false;
+    if (stem.includes('\0'))
+        return false;
+    if (stem === '.' || stem === '..')
+        return false;
+    if (stem.includes('/') || stem.includes('\\'))
+        return false;
+    if (node_path_1.default.isAbsolute(stem))
+        return false;
+    return true;
+}
+/**
+ * Resolve which capability id DECLARES ownership of `stem`, per the registry's
+ * `capabilityClusters` view (capId -> [owned skill stems]) — the SAME
+ * authoritative binding `_capabilitySkillsForMode` (above) and `resolveSurface`
+ * (surface.cts) already trust to decide which stems a capability contributes.
+ * `capabilityClusters` is derived (gen-capability-registry.cjs
+ * deriveCapabilityClusters) straight from each ACCEPTED capability's OWN
+ * declared, non-empty `skills[]` array — an UNDECLARED directory a capability
+ * happens to ship on disk (an unlisted `skills/<stem>/` bundled by mistake, or
+ * by a malicious author trying to hijack another capability's stem) never
+ * appears here, so it can never resolve as an owner. Two capabilities can never
+ * both own the same stem: the registry loader (capability-loader.cts) rejects a
+ * candidate whose declared skill collides with an already-registered owner
+ * BEFORE it is ever composed into the registry — so this lookup is unambiguous
+ * by construction. Returns null for an unowned/unregistered stem or a
+ * malformed registry (never throws).
+ */
+function _owningCapabilityId(stem, clusters) {
+    const BANNED = ['__proto__', 'constructor', 'prototype'];
+    for (const capId of Object.keys(clusters)) {
+        if (BANNED.includes(capId))
+            continue;
+        const owned = clusters[capId];
+        if (!Array.isArray(owned))
+            continue;
+        if (owned.includes(stem))
+            return capId;
+    }
+    return null;
+}
+/**
+ * Union every stem ANY accepted capability declares across the WHOLE registry
+ * (unfiltered by mode/tier) — used only for the `'*'` (full profile) staging
+ * fill-in below, mirroring the SAME unconditional union `resolveSurface`
+ * (surface.cts) already performs when ITS OWN base profile resolves to `'*'`.
+ * Guards against a malformed/prototype-polluted registry; never throws.
+ */
+function capabilityClusterStems(registry) {
+    const result = new Set();
+    const clusters = registry?.capabilityClusters;
+    if (!clusters || typeof clusters !== 'object')
+        return result;
+    const BANNED = ['__proto__', 'constructor', 'prototype'];
+    for (const capId of Object.keys(clusters)) {
+        if (BANNED.includes(capId))
+            continue;
+        const stems = clusters[capId];
+        if (!Array.isArray(stems))
+            continue;
+        for (const s of stems) {
+            if (typeof s === 'string' && s.length > 0)
+                result.add(s);
+        }
+    }
+    return result;
+}
+/**
+ * #2322 HIGH-3: filesystem marker written into every staged THIRD-PARTY
+ * capability skill directory (alongside SKILL.md) so a later prune pass
+ * (surface.cts pruneSkillDirs) can identify the directory as GSD-capability-
+ * owned even after the owning capability has been uninstalled/unsurfaced and
+ * no longer appears in ANY registry view. Without a persisted marker, an
+ * orphaned capability skill directory has no first-party manifest entry (the
+ * skill manifest only ever knows gsd-core's own bundled stems) and
+ * pruneSkillDirs' conservative unknown-directory branch would preserve it
+ * FOREVER — uninstalling a malicious capability would never actually remove
+ * its already-staged instructions from the agent's context. A directory
+ * WITHOUT this marker is presumed genuinely user-created (data-loss
+ * protection is unchanged for that case).
+ */
+const CAPABILITY_SKILL_MARKER = '.gsd-capability-skill';
+/**
+ * Look up an installed third-party capability's already-authored SKILL.md for
+ * `stem`, bound to its DECLARING capability via the registry's
+ * `capabilityClusters` view (capId -> owned stems) — NEVER by scanning every
+ * installed capability directory and taking the first (sorted) match.
+ *
+ * #2322 BLOCKER 1: the prior implementation scanned every directory under the
+ * capabilities root for a `skills/<stem>/SKILL.md` file and returned the FIRST
+ * SORTED match, regardless of whether that capability actually DECLARED the
+ * stem in its `capability.json` `skills[]` and regardless of whether it was
+ * the (sole) REGISTERED owner. An attacker-controlled capability could ship an
+ * UNDECLARED `skills/<victim-stem>/SKILL.md` directory that sorted ahead of
+ * the legitimate, declaring capability and hijack its stem — the agent would
+ * load the attacker's instructions believing they came from the legitimate
+ * capability. Resolving `stem -> capId` via `capabilityClusters` FIRST (the
+ * same authoritative binding `resolveSurface`/`_capabilitySkillsForMode`
+ * trust) then reading ONLY that capability's own directory makes an
+ * undeclared/unregistered sibling directory unreachable by construction.
+ *
+ * The install-root path convention (`<capabilitiesRoot>/<capId>/skills/<stem>/
+ * SKILL.md` under `GSD_HOME || homedir()`) mirrors capability-loader.cts
+ * (global overlay root) and capability-source.cts's `stageValidated` finalDir.
+ *
+ * Total/non-throwing (#2322 requirement 5): no registry, an unowned stem, a
+ * missing capabilities root, an unreadable capability dir, or a missing/
+ * corrupt SKILL.md all degrade to `null` (skip that stem) rather than
+ * throwing — a partial/corrupt third-party install must never break
+ * first-party staging. No registry at all means NOTHING third-party is
+ * staged (fail closed — never a fallback scan).
+ *
+ * NOTE: the content returned here is staged AS-IS (no per-file `converter`
+ * runs on it — unlike gsd-core's flat command `.md`, an installed capability
+ * skill is already a complete SKILL.md), but it is NOT immune from the LATER
+ * runtime-targeted body rewrite pass `applySurface` runs over the ENTIRE
+ * staged directory (`rewriteStagedSkillBodies`, surface.cts): a `~/.claude/`
+ * (etc.) path reference in a third-party skill body IS rewritten exactly like
+ * a first-party one. "As-is" here refers only to this copy step, not to the
+ * final on-disk content after a full `applySurface` run.
+ */
+function readInstalledCapabilitySkill(stem, registry) {
+    if (!isSafeCapabilitySkillStem(stem))
+        return null;
+    if (!registry || !registry.capabilityClusters || typeof registry.capabilityClusters !== 'object')
+        return null;
+    const capId = _owningCapabilityId(stem, registry.capabilityClusters);
+    if (capId === null)
+        return null;
+    // Defense-in-depth: capId is a real accepted-capability directory name (a
+    // trusted fs.readdirSync entry at capability-loader.cts accept time), but
+    // re-validate its path-segment shape before using it as a literal path
+    // component in case a future registry composer ever stops guaranteeing that.
+    if (!isSafeCapabilitySkillStem(capId))
+        return null;
+    const home = process.env['GSD_HOME'] || node_os_1.default.homedir();
+    const capDir = node_path_1.default.join(home, '.gsd', 'capabilities', capId);
+    const relSkillPath = node_path_1.default.join('skills', stem, 'SKILL.md');
+    // Defense-in-depth: isSafeCapabilitySkillStem already rejects separators/
+    // '..'/absolute stems, but re-confirm the resolved read path stays under
+    // this capability's own directory before ever touching the filesystem.
+    if (!(0, external_descriptor_trust_cjs_1.isPathConfined)(relSkillPath, capDir))
+        return null;
+    const skillPath = node_path_1.default.join(capDir, relSkillPath);
+    try {
+        if (!node_fs_1.default.statSync(skillPath).isFile())
+            return null;
+        return { capId, content: node_fs_1.default.readFileSync(skillPath, 'utf8') };
+    }
+    catch {
+        return null; // missing / unreadable / corrupt entry -> skip
+    }
+}
+/**
+ * @param registry optional capability registry (capabilityClusters view) —
+ *   when present, third-party capability skills are unioned into the staged
+ *   output (bound to their declaring capId; see readInstalledCapabilitySkill).
+ *   When absent, NOTHING third-party is staged (fail closed).
+ */
+function stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converter, prefix, nested = false, registry) {
     if (!node_fs_1.default.existsSync(srcCommandsDir))
         return srcCommandsDir;
     // Nesting applies to the `full` install AND to any surface whose skill set
@@ -458,6 +636,10 @@ function stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converte
             doNest = [...bundles.routerStems].every((r) => present.has(r));
         }
     }
+    // #2322: stems actually staged from gsd-core's OWN bundled commands/gsd dir
+    // this call, so the third-party fill-in pass below can enforce "first-party
+    // ALWAYS wins on collision" without re-deriving membership.
+    const firstPartyStems = new Set();
     const stageDir = node_fs_1.default.mkdtempSync(node_path_1.default.join(node_os_1.default.tmpdir(), 'gsd-profile-runtime-skills-'));
     try {
         const entries = node_fs_1.default.readdirSync(srcCommandsDir, { withFileTypes: true });
@@ -469,6 +651,7 @@ function stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converte
             const stem = entry.name.slice(0, -3);
             if (resolvedProfile.skills !== '*' && !(resolvedProfile.skills).has(stem))
                 continue;
+            firstPartyStems.add(stem);
             const content = node_fs_1.default.readFileSync(node_path_1.default.join(srcCommandsDir, entry.name), 'utf8');
             const skillName = `${prefix}${stem}`;
             const converted = converter(content, skillName);
@@ -497,6 +680,55 @@ function stageSkillsForRuntimeAsSkills(srcCommandsDir, resolvedProfile, converte
             node_fs_1.default.mkdirSync(destDir, { recursive: true });
             node_fs_1.default.writeFileSync(node_path_1.default.join(destDir, 'SKILL.md'), converted);
         }
+        // #2322: materialize installed THIRD-PARTY capability skills, bound to
+        // their DECLARING capability via the registry's capabilityClusters view
+        // (see readInstalledCapabilitySkill — NEVER scan-and-first-match). The
+        // registry union (#2045) already puts every accepted-capability stem into
+        // a concrete resolvedProfile.skills Set, but srcCommandsDir only ever
+        // holds gsd-core's own bundled commands — so any stem with no first-party
+        // file here was silently dropped (registry says surfaced:true, nothing on
+        // disk) unless we fill it in from the capability's own install dir.
+        //
+        // BLOCKER 2 (#2322): `resolveProfile` short-circuits the `full` profile
+        // straight to the `'*'` sentinel BEFORE ever consulting a registry — the
+        // sentinel therefore carries no per-stem list of its own, and a bare
+        // `resolvedProfile.skills !== '*'` gate here skipped this ENTIRE fill-in
+        // pass for a `full` install regardless of what the registry declared
+        // (the issue's default-profile repro: `mode=full` staged zero third-party
+        // skills even when `mode=standard` on the SAME registry staged them
+        // correctly). When `resolvedProfile.skills === '*'`, the candidate stems
+        // are instead every stem the registry's `capabilityClusters` declares —
+        // mirroring the SAME unconditional union `resolveSurface` (surface.cts,
+        // "Issue #2045" block) already performs for its own `'*'` case. When
+        // `resolvedProfile.skills` is a concrete Set, the candidate stems are the
+        // ones `_capabilitySkillsForMode` already unioned into it (unchanged).
+        //
+        // No registry in scope at all -> stage NOTHING third-party (fail closed —
+        // never fall back to scanning). Nesting (#69) never applies to a
+        // capability skill — it was never a child of any ns-* router's
+        // `requires:` list — so it always lands flat at the top level, exactly
+        // like an unrouted first-party skill.
+        if (registry) {
+            const candidateStems = resolvedProfile.skills === '*' ? capabilityClusterStems(registry) : resolvedProfile.skills;
+            for (const stem of candidateStems) {
+                if (firstPartyStems.has(stem))
+                    continue; // first-party always wins
+                const found = readInstalledCapabilitySkill(stem, registry);
+                if (found === null)
+                    continue; // absent/malformed/unowned -> skip gracefully
+                const skillName = `${prefix}${stem}`;
+                if (!(0, external_descriptor_trust_cjs_1.isPathConfined)(skillName, stageDir))
+                    continue; // defense-in-depth
+                const destDir = node_path_1.default.join(stageDir, skillName);
+                node_fs_1.default.mkdirSync(destDir, { recursive: true });
+                node_fs_1.default.writeFileSync(node_path_1.default.join(destDir, 'SKILL.md'), found.content);
+                // #2322 HIGH-3: persist the capability-owned marker so a later prune
+                // pass (surface.cts pruneSkillDirs) can identify — and remove — this
+                // directory even once the owning capability is uninstalled/unsurfaced
+                // and no longer appears in any registry view.
+                node_fs_1.default.writeFileSync(node_path_1.default.join(destDir, CAPABILITY_SKILL_MARKER), found.capId + '\n', 'utf8');
+            }
+        }
     }
     catch (err) {
         try {
@@ -822,6 +1054,12 @@ module.exports = {
     parseRequires,
     parseCallsAgents,
     cleanupStagedSkills,
+    // #2322: capability-skill security seams — exported for direct unit-testing
+    // and for surface.cts's prune pass (CAPABILITY_SKILL_MARKER parity).
+    isSafeCapabilitySkillStem,
+    readInstalledCapabilitySkill,
+    capabilityClusterStems,
+    CAPABILITY_SKILL_MARKER,
     // Back-compat / deprecated
     MINIMAL_SKILL_ALLOWLIST,
     isMinimalMode,

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

@@ -14,6 +14,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateInstallerMigrationRecord = validateInstallerMigrationRecord;
 exports.validateInstallerMigrationActions = validateInstallerMigrationActions;
 const node_path_1 = __importDefault(require("node:path"));
+const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 function getStr(record, field) {
     const v = record[field];
     return typeof v === 'string' ? v : '';
@@ -56,7 +57,7 @@ function requireActionEvidence(action, field, migration) {
 }
 function validateSafeRelPath(relPath, migration, actionType) {
     const source = actionSource(migration, { relPath });
-    const normalized = relPath.replace(/\\/g, '/');
+    const normalized = (0, shell_command_projection_cjs_1.posixNormalize)(relPath);
     if (node_path_1.default.isAbsolute(normalized) || node_path_1.default.win32.isAbsolute(normalized)) {
         throw new Error(`migration action ${actionType} relPath must stay inside configDir: ${source}`);
     }

package/gsd-core/bin/lib/installer-migrations/005-opencode-baseline-commands-dir.cjs

@@ -0,0 +1,146 @@
+"use strict";
+/**
+ * Installer migration 005: baseline pre-existing OpenCode commands/ (plural)
+ * files during the first-time installer migration baseline scan (#2329
+ * follow-up).
+ *
+ * Background: #2329 moved OpenCode's slash-command install target from the
+ * legacy singular `command/` alias to the documented plural `commands/`
+ * convention. The first-time baseline scan migration
+ * (2026-05-11-first-time-baseline-scan, 000-first-time-baseline.cts) is a
+ * SHIPPED migration body — docs/installer-migrations.md#state-files requires
+ * shipped migration bodies stay immutable so an already-applied migration's
+ * checksum never drifts for a user who ran it before this fix (issue #670).
+ * Its RUNTIME_SURFACES.opencode list still only names the legacy `command`
+ * directory, so the baseline scan never classified pre-existing files under
+ * `commands/` before this fix.
+ *
+ * Consequence proven by probe (see tests/installer-migrations.test.cjs): a
+ * pre-existing, unmanifested file at `commands/gsd-<name>.md` that predates
+ * any GSD install is silently destroyed by ordinary OpenCode command
+ * materialization (which unconditionally removes every `gsd-*.md` file under
+ * its destination before writing the fresh set) with a clean exit code — no
+ * report, no backup, no prompt. The identical scenario under the
+ * already-covered legacy `command/` surface instead halts the install with a
+ * blocked `prompt-user` action, exactly as designed. This migration closes
+ * that gap for `commands/` without editing 000's shipped body.
+ *
+ * This is a NEW fix-forward migration id (per
+ * docs/installer-migrations.md#state-files) rather than an edit to 000: an
+ * already-applied migration never re-runs, so editing 000 would only protect
+ * fresh installs and leave every machine that already applied 000
+ * permanently unprotected for `commands/`. A new id runs for both
+ * populations (installs that never ran a baseline scan AND installs that
+ * already applied the original 000 scan) and drifts no checksum.
+ *
+ * Scope: OpenCode only. Kilo shares the same combined-family install path,
+ * but its command directory descriptor is still the singular `command/`
+ * (already covered by 000's RUNTIME_SURFACES.kilo), so this migration must
+ * never touch Kilo installs — enforced by the `runtimes: ['opencode']`
+ * scoping below.
+ *
+ * Classification mirrors 000-first-time-baseline.cts exactly (record-baseline
+ * for manifest-proven files, prompt-user for stale-GSD-looking unmanifested
+ * files, baseline-preserve-user for everything else) — this migration only
+ * widens the surface scanned, not the classification policy.
+ */
+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 SURFACE = 'commands';
+function normalizeRelPath(relPath) {
+    return relPath.replace(/\\/g, '/').replace(/^\/+/, '');
+}
+function walkFiles(root, relDir, files) {
+    const dir = node_path_1.default.join(root, relDir);
+    if (!node_fs_1.default.existsSync(dir))
+        return;
+    const entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const relPath = node_path_1.default.posix.join(relDir, entry.name);
+        if (entry.isDirectory()) {
+            walkFiles(root, relPath, files);
+        }
+        else if (entry.isFile()) {
+            files.add(normalizeRelPath(relPath));
+        }
+    }
+}
+function scanCommandsSurface(configDir) {
+    const relPaths = new Set();
+    const fullPath = node_path_1.default.join(configDir, SURFACE);
+    if (!node_fs_1.default.existsSync(fullPath))
+        return [];
+    const stat = node_fs_1.default.statSync(fullPath);
+    if (stat.isDirectory()) {
+        walkFiles(configDir, SURFACE, relPaths);
+    }
+    else if (stat.isFile()) {
+        relPaths.add(SURFACE);
+    }
+    return [...relPaths];
+}
+function isStaleGsdLookingPath(relPath) {
+    return /^gsd[-_]/.test(node_path_1.default.posix.basename(relPath));
+}
+function baselineActionRank(action) {
+    if (action.type === 'record-baseline')
+        return 0;
+    if (action.type === 'baseline-preserve-user')
+        return 1;
+    return 2;
+}
+const migration = {
+    id: '2026-07-17-opencode-baseline-commands-dir',
+    title: "Baseline OpenCode's commands/ directory in the first-time scan (#2329 follow-up)",
+    description: "Classify pre-existing files under OpenCode's commands/ (plural) directory during the first-time installer " +
+        'migration baseline scan. #2329 moved OpenCode command materialization from the legacy command/ alias to ' +
+        "commands/, but the shipped 000-first-time-baseline.cts RUNTIME_SURFACES.opencode list is immutable and still " +
+        'only names command/; this fix-forward migration widens the scanned surface without editing the shipped body.',
+    introducedIn: '1.7.0',
+    runtimes: ['opencode'],
+    scopes: ['global', 'local'],
+    destructive: false,
+    plan: ({ configDir, baselineScan, classifyArtifact }) => {
+        if (!baselineScan)
+            return [];
+        const actions = [];
+        for (const relPath of scanCommandsSurface(configDir)) {
+            const artifact = classifyArtifact(relPath);
+            if (artifact.classification === 'managed-pristine' || artifact.classification === 'managed-modified') {
+                actions.push({
+                    type: 'record-baseline',
+                    relPath,
+                    reason: 'existing manifest-managed OpenCode commands/ file included in first-time migration baseline',
+                });
+                continue;
+            }
+            const currentHash = artifact.currentHash ?? null;
+            if (isStaleGsdLookingPath(relPath)) {
+                actions.push({
+                    type: 'prompt-user',
+                    relPath,
+                    reason: 'GSD-looking file is not proven manifest-managed and needs explicit user choice',
+                    classification: 'stale-gsd-looking',
+                    originalHash: artifact.originalHash ?? null,
+                    currentHash,
+                    prompt: 'Choose whether to remove this stale-looking GSD artifact or keep it as user-owned.',
+                    choices: ['keep', 'remove'],
+                });
+                continue;
+            }
+            actions.push({
+                type: 'baseline-preserve-user',
+                relPath,
+                reason: 'unknown OpenCode commands/ file preserved by first-time migration baseline',
+                classification: artifact.classification,
+                originalHash: artifact.originalHash ?? null,
+                currentHash,
+            });
+        }
+        return actions.sort((left, right) => baselineActionRank(left) - baselineActionRank(right) || left.relPath.localeCompare(right.relPath));
+    },
+};
+module.exports = migration;

package/gsd-core/bin/lib/installer-migrations/006-pi-extension-cjs-to-js.cjs

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * Installer migration: retire pi's stale `extensions/gsd.cjs` after #2470
+ * renamed the installed native extension to `extensions/gsd.js`.
+ *
+ * What old artifact is being retired?
+ *   `extensions/gsd.cjs` — the pre-#2470 dest filename for pi's native
+ *   extension. pi auto-discovers extensions by scanning `<agentDir>/extensions/`
+ *   and keeping only names accepted by its own predicate
+ *   (`isExtensionFile()` in @earendil-works/pi-coding-agent:
+ *   `name.endsWith(".ts") || name.endsWith(".js")`). A `.cjs` file is skipped
+ *   SILENTLY — no `/gsd` command, no error, no log line. The file is therefore
+ *   permanently inert, not merely redundant.
+ *
+ * How do we prove it is GSD-owned?
+ *   The installer records the native plugin in the install manifest as
+ *   `<nativePlugin.dir>/<nativePlugin.file>` (bin/install.js, the
+ *   `_hostBehaviors(runtime).nativePlugin` manifest block), so a pre-#2470 pi
+ *   install carries `extensions/gsd.cjs` as a manifest-managed entry. Only a
+ *   manifest-managed classification produces an action here; an unmanifested
+ *   `gsd.cjs` is treated as a user's own file and preserved.
+ *
+ * What happens if the user modified it?
+ *   `backup-and-remove` instead of `remove-managed`, so a patched extension is
+ *   recoverable from the backup rather than silently destroyed.
+ *
+ * What happens if it is missing?
+ *   No actions — fresh (post-#2470) installs and already-migrated installs both
+ *   plan empty, so the migration is idempotent.
+ *
+ * What runtime and scope does it affect?
+ *   pi only, global and local. No other runtime ever installed this path:
+ *   OpenCode and Kilo — the only other runtimes declaring
+ *   `hostBehaviors.nativePlugin` — both ship `plugins/gsd-core.js`.
+ *
+ * Is the action safe in non-interactive install?
+ *   Yes. Both emitted action types are non-interactive and journaled; neither
+ *   requires a user choice, and unknown files never produce an action.
+ *
+ * Why not `move-managed`? The installer materializes the new `extensions/gsd.js`
+ * from the package payload in the same run, so moving the stale file onto that
+ * path would just be overwritten. Retiring the old path is the accurate
+ * description of the change.
+ *
+ * See docs/installer-migrations.md#shipped-migrations and the pi row of
+ * docs/installer-migrations.md#runtime-configuration-contract-registry.
+ */
+/** Pre-#2470 dest filename for pi's native extension. */
+const STALE_PI_EXTENSION = 'extensions/gsd.cjs';
+const OWNERSHIP_EVIDENCE = 'pre-#2470 pi installs record the native extension at extensions/gsd.cjs in ' +
+    'gsd-file-manifest.json (installer nativePlugin manifest entry)';
+const REASON = 'pi cannot auto-discover a .cjs extension (isExtensionFile accepts only .ts/.js), ' +
+    'so this file is inert; superseded by extensions/gsd.js (#2470)';
+const migration = {
+    id: '2026-07-20-pi-extension-cjs-to-js',
+    title: 'Retire pi\'s undiscoverable extensions/gsd.cjs',
+    description: 'Remove the stale extensions/gsd.cjs left by pre-#2470 pi installs, superseded by ' +
+        'extensions/gsd.js — the suffix pi\'s extension auto-discovery actually accepts.',
+    introducedIn: '1.7.1',
+    runtimes: ['pi'],
+    scopes: ['global', 'local'],
+    destructive: true,
+    plan: (ctx) => {
+        const artifact = ctx.classifyArtifact(STALE_PI_EXTENSION);
+        if (artifact.classification === 'managed-pristine') {
+            return [
+                {
+                    type: 'remove-managed',
+                    relPath: STALE_PI_EXTENSION,
+                    reason: REASON,
+                    ownershipEvidence: OWNERSHIP_EVIDENCE,
+                },
+            ];
+        }
+        if (artifact.classification === 'managed-modified') {
+            return [
+                {
+                    type: 'backup-and-remove',
+                    relPath: STALE_PI_EXTENSION,
+                    reason: REASON,
+                    ownershipEvidence: OWNERSHIP_EVIDENCE,
+                },
+            ];
+        }
+        // 'unknown' (never GSD-managed), 'missing', and 'managed-missing' all plan
+        // nothing: unknown files are preserved by policy, and an absent file needs
+        // no retirement.
+        return [];
+    },
+};
+module.exports = migration;

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

@@ -42,6 +42,37 @@ function sha256File(filePath) {
 function sha256Text(value) {
     return node_crypto_1.default.createHash('sha256').update(value).digest('hex');
 }
+/**
+ * Copy a managed path for the rollback snapshot or the user-facing backup,
+ * WITHOUT dereferencing a symlink.
+ *
+ * `fs.copyFileSync` follows symlinks, so a managed path that has been replaced
+ * by a link (tampering, or an unexpected user layout) would have had the
+ * LINK TARGET's bytes copied into `gsd-migration-journal/…-backups/` — e.g. a
+ * `gsd.cjs` symlinked at `~/.ssh/id_rsa` would land that key's contents in the
+ * backup tree. Nothing GSD installs is ever a symlink, so the faithful snapshot
+ * of a symlinked managed path is the link itself: recreating it preserves
+ * rollback fidelity (restore re-creates the same link) while never reading the
+ * referent. Deletion was already safe — `fs.rmSync` unlinks the link, never the
+ * target.
+ *
+ * Windows note: `fs.symlinkSync` can throw EPERM for unprivileged users. That
+ * surfaces as an apply failure and triggers the normal rollback path, which is
+ * the correct outcome — refusing to proceed beats silently copying referent
+ * bytes.
+ */
+function copyPreservingSymlink(srcPath, destPath) {
+    if (node_fs_1.default.lstatSync(srcPath).isSymbolicLink()) {
+        // symlinkSync fails with EEXIST on an occupied path, so clear it first.
+        // Scoped to this branch on purpose: the regular-file path below keeps
+        // copyFileSync's overwrite-in-place, so a mid-restore failure cannot leave
+        // the destination destroyed.
+        node_fs_1.default.rmSync(destPath, { force: true });
+        node_fs_1.default.symlinkSync(node_fs_1.default.readlinkSync(srcPath), destPath);
+        return;
+    }
+    node_fs_1.default.copyFileSync(srcPath, destPath);
+}
 function readJsonIfPresent(filePath, fallback) {
     if (!node_fs_1.default.existsSync(filePath))
         return fallback;
@@ -118,7 +149,7 @@ function normalizeRelPath(relPath) {
     if (typeof relPath !== 'string' || relPath.trim() === '') {
         throw new Error('migration action relPath must be a non-empty string');
     }
-    const normalized = relPath.replace(/\\/g, '/');
+    const normalized = (0, shell_command_projection_cjs_1.posixNormalize)(relPath);
     if (node_path_1.default.isAbsolute(normalized) || node_path_1.default.win32.isAbsolute(normalized)) {
         throw new Error(`migration action relPath must stay inside configDir: ${relPath}`);
     }
@@ -518,9 +549,12 @@ function rollbackAppliedMigrationResult({ configDir, journal, journalPath, rollb
         const rollbackPath = node_path_1.default.join(configDir, action.rollbackRelPath);
         const dest = node_path_1.default.join(configDir, action.relPath);
         try {
-            if (node_fs_1.default.existsSync(rollbackPath)) {
+            // lstat-based existence check: a snapshot of a symlinked managed path is
+            // itself a link, and existsSync() follows it — a link whose target is
+            // gone would read as "missing" and silently skip the restore.
+            if (node_fs_1.default.lstatSync(rollbackPath, { throwIfNoEntry: false })) {
                 node_fs_1.default.mkdirSync(node_path_1.default.dirname(dest), { recursive: true });
-                node_fs_1.default.copyFileSync(rollbackPath, dest);
+                copyPreservingSymlink(rollbackPath, dest);
             }
         }
         catch (error) {
@@ -623,7 +657,7 @@ function applyInstallerMigrationPlan({ configDir, plan, now = () => new Date().t
             }
             const rollbackPath = node_path_1.default.join(rollbackRoot, normalized);
             node_fs_1.default.mkdirSync(node_path_1.default.dirname(rollbackPath), { recursive: true });
-            node_fs_1.default.copyFileSync(fullPath, rollbackPath);
+            copyPreservingSymlink(fullPath, rollbackPath);
             rollback.push({ relPath: normalized, rollbackPath });
             if (action.type === 'rewrite-json') {
                 if (action.deleteIfEmpty && isStructurallyEmpty(action.value)) {
@@ -644,7 +678,7 @@ function applyInstallerMigrationPlan({ configDir, plan, now = () => new Date().t
                 const backupRelPath = action.backupRelPath || node_path_1.default.posix.join(backupRootRelPath, normalized);
                 const backupPath = node_path_1.default.join(configDir, backupRelPath);
                 node_fs_1.default.mkdirSync(node_path_1.default.dirname(backupPath), { recursive: true });
-                node_fs_1.default.copyFileSync(fullPath, backupPath);
+                copyPreservingSymlink(fullPath, backupPath);
                 journal.actions.push(journalAction(action, 'removed', {
                     backupRelPath,
                     rollbackRelPath: node_path_1.default.posix.join(rollbackRootRelPath, normalized),
@@ -695,7 +729,12 @@ function applyInstallerMigrationPlan({ configDir, plan, now = () => new Date().t
             const dest = node_path_1.default.join(configDir, entry.relPath);
             try {
                 node_fs_1.default.mkdirSync(node_path_1.default.dirname(dest), { recursive: true });
-                node_fs_1.default.copyFileSync(entry.rollbackPath, dest);
+                // Symlink-preserving, same as the forward path: `entry.rollbackPath` is
+                // itself a link whenever the managed path was one, so a raw copy here
+                // would dereference it and write the referent's bytes back to the LIVE
+                // install path — a worse leak than the journal-tree one, since it is
+                // user-visible and at a predictable location.
+                copyPreservingSymlink(entry.rollbackPath, dest);
             }
             catch (rollbackError) {
                 rollbackFailures.push({