Merge main into phase 4 installer migrations

bin/install.js

@@ -7134,9 +7134,35 @@ function resolveInstallRelativePath(baseDir, relPath) {
   if (fullPath !== root && !fullPath.startsWith(root + path.sep)) {
     return null;
   }
+  if (hasExistingSymlinkBetween(root, fullPath)) {
+    return null;
+  }
   return { relPath: normalized, fullPath };
 }
 
+function hasExistingSymlinkBetween(root, fullPath) {
+  const resolvedRoot = path.resolve(root);
+  const resolvedFullPath = path.resolve(fullPath);
+  if (resolvedFullPath !== resolvedRoot && !resolvedFullPath.startsWith(resolvedRoot + path.sep)) {
+    return true;
+  }
+
+  let cursor = resolvedRoot;
+  if (fs.existsSync(cursor) && fs.lstatSync(cursor).isSymbolicLink()) {
+    return true;
+  }
+
+  const relative = path.relative(resolvedRoot, resolvedFullPath);
+  for (const segment of relative.split(path.sep)) {
+    if (!segment) continue;
+    cursor = path.join(cursor, segment);
+    if (!fs.existsSync(cursor)) return false;
+    if (fs.lstatSync(cursor).isSymbolicLink()) return true;
+  }
+
+  return false;
+}
+
 /**
  * Write file manifest after installation for future modification detection
  */
@@ -7554,6 +7580,13 @@ function install(isGlobal, runtime = 'claude', options = {}) {
 
   // Track installation failures
   const failures = [];
+  let installerMigrationResult = null;
+  const rollbackInstallerMigrations = () => {
+    if (!installerMigrationResult || typeof installerMigrationResult.rollback !== 'function') return;
+    const rollback = installerMigrationResult.rollback;
+    installerMigrationResult = null;
+    rollback();
+  };
 
   // Save any locally modified GSD files before they get wiped.
   // The pristine context lets saveLocalPatches populate gsd-pristine/ via
@@ -7566,6 +7599,9 @@ function install(isGlobal, runtime = 'claude', options = {}) {
     isGlobal,
   });
 
+  // Run manifest-backed cleanup migrations before package materialization.
+  installerMigrationResult = runInstallerMigrations({ configDir: targetDir });
+
   // #3245 — Codex idempotent rollback. Capture pre-install state of ALL
   // directories and files GSD will mutate so that any post-install validation
   // failure (config.toml schema check, write failure, etc.) can revert the
@@ -7596,13 +7632,6 @@ function install(isGlobal, runtime = 'claude', options = {}) {
   // Map<filename, Buffer> — content snapshot of each pre-existing gsd-* agent file.
   const codexPreInstallAgentContents = new Map();
   let codexPreInstallVersionBytes = null;
-  let installerMigrationResult = null;
-  const rollbackInstallerMigrations = () => {
-    if (!installerMigrationResult || typeof installerMigrationResult.rollback !== 'function') return;
-    const rollback = installerMigrationResult.rollback;
-    installerMigrationResult = null;
-    rollback();
-  };
   if (isCodex && !isMinimalMode(installMode)) {
     const _preSkillsDir = path.join(targetDir, 'skills');
     if (fs.existsSync(_preSkillsDir)) {
@@ -8388,6 +8417,7 @@ function install(isGlobal, runtime = 'claude', options = {}) {
     // #3245 CR finding 2 — any throw in the pre-config install operations (skills copy,
     // agents copy, VERSION write, manifest write, etc.) triggers the Codex pre-config
     // rollback so the caller is never left in a partially-installed state.
+    rollbackInstallerMigrations();
     if (_codexPreConfigRollback) {
       _codexPreConfigRollback();
     }

docs/installer-migrations.md

@@ -345,7 +345,7 @@ for the new shape before changing migration behavior.
 | Gemini CLI | TOML slash commands in `commands/gsd/*.toml`; agents in `agents/gsd-*.md`; `settings.json` feature flag, hooks, and statusline | Global `GEMINI_CONFIG_DIR` or `~/.gemini`; local `./.gemini` | GSD owns generated commands/agents/hooks and only GSD settings entries; local command copy may be skipped when global GSD commands already exist | [Custom commands](https://google-gemini.github.io/gemini-cli/docs/cli/custom-commands.html), [configuration](https://google-gemini.github.io/gemini-cli/docs/cli/configuration.html); docs checked 2026-05-11 |
 | Codex | Skills in `skills/gsd-*/SKILL.md`; agents as source markdown plus per-agent TOML in `agents/`; `[agents.gsd-*]` and hooks in `config.toml` | Global `CODEX_HOME` or `~/.codex`; local `./.codex` | GSD owns generated skills, generated agent TOML, `agents.gsd-*` config sections, `[features].codex_hooks` when added by GSD, and GSD hook entries | [Codex config schema](https://developers.openai.com/codex/config-schema.json), [Codex developer docs](https://developers.openai.com/codex/); docs not versioned, checked 2026-05-11; installer compatibility sentinel: Codex 0.124.0 agent table shape |
 | GitHub Copilot | Skills in `skills/gsd-*/SKILL.md`; agents as `.agent.md`; repository instructions in `copilot-instructions.md` | Global `COPILOT_CONFIG_DIR` or `~/.copilot`; local `./.github` | GSD owns generated skill/agent files and GSD-authored instruction files; no hook/statusline ownership | [Repository custom instructions](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions), [Copilot CLI custom instructions](https://docs.github.com/en/copilot/how-tos/copilot-cli/add-custom-instructions); GitHub Docs product docs, checked 2026-05-11 |
-| Antigravity | Skills in `skills/gsd-*/SKILL.md`; agents in `agents/`; Gemini-style `settings.json` hooks when installed by GSD | Global `ANTIGRAVITY_CONFIG_DIR` or `~/.gemini/antigravity`; local `./.agent` | GSD owns generated skills/agents/hooks and GSD settings entries only | Public Antigravity install/config docs for this file layout were not stable or complete on 2026-05-11; GSD uses the Gemini-compatible compatibility-shim settings contract |
+| Antigravity | Skills in `skills/gsd-*/SKILL.md`; agents in `agents/`; Gemini-style `settings.json` hooks when installed by GSD | Global `ANTIGRAVITY_CONFIG_DIR` or `~/.gemini/antigravity`; local `./.agent` | GSD owns generated skills/agents/hooks and GSD settings entries only | Checked 2026-05-11 against available Antigravity install/config material; this row records GSD's Gemini-compatible settings contract as the compatibility baseline for installer migrations. |
 | Cursor | Skills in `skills/gsd-*/SKILL.md`; agents in `agents/`; rule references under `rules/` | Global `CURSOR_CONFIG_DIR` or `~/.cursor`; local `./.cursor` | GSD owns generated skills/agents and GSD rule files or references; no hook/statusline ownership | [Cursor rules](https://docs.cursor.com/context/rules); docs not versioned, checked 2026-05-11 |
 | Windsurf | Skills in `skills/gsd-*/SKILL.md`; agents in `agents/`; rule references under `rules/` | Global `WINDSURF_CONFIG_DIR` or `~/.codeium/windsurf`; local `./.windsurf` | GSD owns generated skills/agents and GSD rule files or references; no hook/statusline ownership | Windsurf public rule docs were source-limited in search results as of 2026-05-11; installer targets the common workspace rules convention `./.windsurf/rules` and must be rechecked before migrations rewrite rules |
 | Augment Code | Skills in `skills/gsd-*/SKILL.md`; agents in `agents/` | Global `AUGMENT_CONFIG_DIR` or `~/.augment`; local `./.augment` | GSD owns generated skills/agents only; no hook/statusline ownership | [Augment Agent Skills](https://docs.augmentcode.com/cli/skills), [Augment IDE skills](https://docs.augmentcode.com/using-augment/skills); IDE skills public beta in VS Code 0.789.0+, checked 2026-05-11 |

tests/bug-2771-user-profile-manifest.test.cjs

@@ -22,6 +22,7 @@ const { describe, test, beforeEach, afterEach, before } = require('node:test');
 const assert = require('node:assert/strict');
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 const { execFileSync } = require('child_process');
 const { createTempDir, cleanup } = require('./helpers.cjs');
 
@@ -262,4 +263,44 @@ describe('manifest path safety', () => {
     assert.equal(fs.readFileSync(outside, 'utf8'), 'outside user data\n');
     assert.equal(fs.existsSync(path.join(tmpDir, PATCHES_DIR_NAME, '..', path.basename(outside))), false);
   });
+
+  test('saveLocalPatches does not follow symlinked patch directories outside the install root', () => {
+    const origMode = process.env.GSD_TEST_MODE;
+    process.env.GSD_TEST_MODE = '1';
+    let mod;
+    try {
+      delete require.cache[require.resolve(INSTALL_SCRIPT)];
+      mod = require(INSTALL_SCRIPT);
+    } finally {
+      if (origMode === undefined) delete process.env.GSD_TEST_MODE;
+      else process.env.GSD_TEST_MODE = origMode;
+    }
+
+    const hookPath = path.join(tmpDir, 'hooks', 'managed.js');
+    fs.mkdirSync(path.dirname(hookPath), { recursive: true });
+    fs.writeFileSync(hookPath, 'user edited hook\n', 'utf8');
+    fs.writeFileSync(
+      path.join(tmpDir, MANIFEST_NAME),
+      JSON.stringify({
+        version: 'legacy',
+        timestamp: '2026-05-11T00:00:00.000Z',
+        files: {
+          'hooks/managed.js': crypto.createHash('sha256').update('managed hook\n').digest('hex'),
+        },
+      }, null, 2),
+      'utf8'
+    );
+
+    fs.mkdirSync(outside, { recursive: true });
+    try {
+      fs.symlinkSync(outside, path.join(tmpDir, PATCHES_DIR_NAME), 'dir');
+    } catch {
+      return;
+    }
+
+    const modified = mod.saveLocalPatches(tmpDir);
+
+    assert.deepEqual(modified, []);
+    assert.equal(fs.existsSync(path.join(outside, 'hooks', 'managed.js')), false);
+  });
 });

tests/installer-migrations.test.cjs

@@ -665,6 +665,58 @@ test('reports lock release failures after migration work completes', (t) => {
   );
 });
 
+test('rollback handle restores files and install state after a successful apply', () => {
+  const configDir = createTempInstall();
+  try {
+    writeFile(configDir, 'hooks/old-hook.js', 'managed hook\n');
+    writeManifest(configDir, {
+      'hooks/old-hook.js': sha256('managed hook\n'),
+    });
+    writeInstallState(configDir, {
+      schemaVersion: 1,
+      appliedMigrations: [
+        {
+          id: 'already-applied',
+          appliedAt: '2026-05-10T00:00:00.000Z',
+          journal: 'gsd-migration-journal/prior.json',
+        },
+      ],
+    });
+
+    const plan = planInstallerMigrations({
+      configDir,
+      migrations: [
+        {
+          id: '2026-05-11-remove-old-hook',
+          description: 'Remove retired hook',
+          plan: () => [
+            {
+              type: 'remove-managed',
+              relPath: 'hooks/old-hook.js',
+              reason: 'retired hook',
+            },
+          ],
+        },
+      ],
+      now: () => '2026-05-11T00:00:00.000Z',
+    });
+
+    const result = applyInstallerMigrationPlan({
+      configDir,
+      plan,
+      now: () => '2026-05-11T00:00:01.000Z',
+    });
+
+    result.rollback();
+
+    assert.equal(fs.readFileSync(path.join(configDir, 'hooks/old-hook.js'), 'utf8'), 'managed hook\n');
+    assert.deepEqual(readInstallState(configDir).appliedMigrations.map((entry) => entry.id), ['already-applied']);
+    assert.equal(fs.existsSync(path.join(configDir, result.journalRelPath)), false);
+  } finally {
+    cleanup(configDir);
+  }
+});
+
 test('rolls back touched files and leaves state unchanged when apply fails', () => {
   const configDir = createTempInstall();
   try {