fix(skills): rebind profiles across plugin upgrades

Author: jaromil

README.md

@@ -50,7 +50,10 @@ skill paths without starting the server. Without `--skills`, a workspace
 `gestalt-skills.yml` is used when present; otherwise Codex-native selection is
 preserved. Explicit profiles take precedence over project defaults, which take
 precedence over native configuration. Gestalt Mobile never rewrites Codex
-configuration or skill files.
+configuration or skill files. Exact skill paths remain authoritative, while
+paths inside Codex's versioned plugin cache are rebound to the currently
+discovered plugin version when their marketplace, plugin, and skill-relative
+path still match.
 
 ## Themes
 

src/server/features/skills/model/skill-profile.test.ts

@@ -128,6 +128,67 @@ describe('skill profile codec', () => {
     });
   });
 
+  it('rebinds a saved plugin skill across cache versions', () => {
+    const currentPath =
+      '/home/test/.codex/plugins/cache/dyne-gestalt-agents/gestalt/2.2.0/skills/development-testing/SKILL.md';
+    const result = compileSkillOverride({
+      discovered: [
+        { name: 'gestalt:development-testing', path: currentPath, enabled: false },
+        { ...alpha, enabled: true },
+      ],
+      explicit: createSkillSelection([
+        {
+          name: 'gestalt:development-testing',
+          path: '/home/test/.codex/plugins/cache/dyne-gestalt-agents/gestalt/2.1.0/skills/development-testing/SKILL.md',
+          enabled: true,
+        },
+      ]),
+    });
+
+    expect(result).toEqual({
+      source: 'explicit',
+      skillsConfig: [
+        { path: currentPath, enabled: true },
+        { path: '/skills/alpha/SKILL.md', enabled: false },
+      ],
+      warnings: [],
+    });
+  });
+
+  it('does not rebind a stale plugin skill to a different plugin or skill path', () => {
+    const stalePath =
+      '/home/test/.codex/plugins/cache/dyne-gestalt-agents/gestalt/2.1.0/skills/development-testing/SKILL.md';
+    const result = compileSkillOverride({
+      discovered: [
+        {
+          name: 'other:development-testing',
+          path: '/home/test/.codex/plugins/cache/other-marketplace/other-plugin/2.2.0/skills/development-testing/SKILL.md',
+          enabled: true,
+        },
+        {
+          name: 'gestalt:verification-before-completion',
+          path: '/home/test/.codex/plugins/cache/dyne-gestalt-agents/gestalt/2.2.0/skills/verification-before-completion/SKILL.md',
+          enabled: true,
+        },
+      ],
+      explicit: createSkillSelection([
+        { name: 'gestalt:development-testing', path: stalePath, enabled: true },
+      ]),
+    });
+
+    expect(result.skillsConfig).toEqual([
+      {
+        path: '/home/test/.codex/plugins/cache/dyne-gestalt-agents/gestalt/2.2.0/skills/verification-before-completion/SKILL.md',
+        enabled: false,
+      },
+      {
+        path: '/home/test/.codex/plugins/cache/other-marketplace/other-plugin/2.2.0/skills/development-testing/SKILL.md',
+        enabled: false,
+      },
+    ]);
+    expect(result.warnings).toEqual([`Saved skill path is no longer discovered: ${stalePath}`]);
+  });
+
   it('emits no override when neither explicit nor project selection exists', () => {
     expect(compileSkillOverride({ discovered: [alpha] })).toEqual({
       source: 'native',

src/server/features/skills/model/skill-profile.ts

@@ -116,6 +116,43 @@ function canonicalSkillPath(value: string): string {
   return value;
 }
 
+/**
+ * Return the durable identity of a skill inside Codex's versioned plugin cache.
+ * The concrete version directory is installation state, while marketplace,
+ * plugin, and skill-relative path remain stable across plugin upgrades.
+ */
+function versionNeutralPluginSkillPath(value: string): string | undefined {
+  const match = value.match(
+    /^(.*[\\/]plugins[\\/]cache[\\/][^\\/]+[\\/][^\\/]+)[\\/][^\\/]+([\\/]skills[\\/].+[\\/]SKILL\.md)$/,
+  );
+  return match ? `${match[1]}${match[2]}` : undefined;
+}
+
+function rebindVersionedPluginSkills(
+  discovered: readonly AvailableSkill[],
+  selection: SkillSelection,
+): SkillSelection {
+  const discoveredPaths = new Set(discovered.map((skill) => canonicalSkillPath(skill.path)));
+  const discoveredByDurablePath = new Map<string, AvailableSkill[]>();
+  for (const skill of discovered) {
+    const durablePath = versionNeutralPluginSkillPath(canonicalSkillPath(skill.path));
+    if (durablePath === undefined) continue;
+    const matches = discoveredByDurablePath.get(durablePath) ?? [];
+    matches.push(skill);
+    discoveredByDurablePath.set(durablePath, matches);
+  }
+
+  return createSkillSelection(
+    selection.map((entry) => {
+      if (discoveredPaths.has(entry.path)) return entry;
+      const durablePath = versionNeutralPluginSkillPath(entry.path);
+      if (durablePath === undefined) return entry;
+      const matches = discoveredByDurablePath.get(durablePath) ?? [];
+      return matches.length === 1 ? { ...entry, path: matches[0].path } : entry;
+    }),
+  );
+}
+
 /**
  * Validate a complete selection and return its canonical deterministic order.
  * This is lexical only: resolving symlinks is I/O and belongs to a platform
@@ -201,11 +238,12 @@ export function compileSkillOverride(input: {
   const effective = selectEffectiveSkillSelection(input);
   if (effective.selection === undefined)
     return { source: 'native', skillsConfig: undefined, warnings: [] };
+  const reboundSelection = rebindVersionedPluginSkills(input.discovered, effective.selection);
   const discoveredPaths = new Set(input.discovered.map((skill) => canonicalSkillPath(skill.path)));
-  const warnings = effective.selection
+  const warnings = reboundSelection
     .filter((entry) => !discoveredPaths.has(entry.path))
     .map((entry) => `Saved skill path is no longer discovered: ${entry.path}`);
-  const configured = applySkillSelectionSnapshot(input.discovered, effective.selection);
+  const configured = applySkillSelectionSnapshot(input.discovered, reboundSelection);
   return {
     source: effective.source,
     skillsConfig: configured