@opengsd/gsd-core 1.17.0 → 1.19.0

package/bin/install.js

@@ -35,6 +35,7 @@ const {
   getGlobalSkillsBase,
   resolveKimiHooksTomlDir,
   isRegisteredRuntimeId,
+  resolveGsdHome,
 } = require('../gsd-core/bin/lib/runtime-homes.cjs');
 // #2870: the Install Scope Module — turns a bare 'global' | 'local' scope id
 // plus a runtime into one resolved value (configHome, settingsFile,
@@ -62,6 +63,8 @@ const { composeWorkflow } = require('../gsd-core/bin/lib/workflow-fragments.cjs'
 // #3072: THE shared composition-scope predicate (also consumed by the served
 // MCP catalog, src/mcp-catalog.cts) — see the comment at its call site below.
 const { shouldCompose } = require('../gsd-core/bin/lib/mcp-catalog.cjs');
+// #5637: per-install terminator for the typed-text capture heredoc.
+const { armArgsNonce, disarmArgsNonce, stampInstalledContent } =require('../gsd-core/bin/lib/args-terminator.cjs');
 const runtimeArtifactConversion = require('../gsd-core/bin/lib/runtime-artifact-conversion.cjs');
 const { escapeRegex: escapeRegExp } = require('../gsd-core/bin/lib/pattern.cjs');
 // #2873: cross-scope shadow detection — reports (never fails) when a
@@ -843,6 +846,9 @@ const {
   migrateLegacyDevPreferencesToSkill,
   USER_OWNED_ARTIFACTS,
   _snapshotDir,
+  createSkillDirOwnership,
+  _warnPreservedSkillDirs,
+  USER_OWNED_SKILL_DIRS,
 } = installEngine;
 
 // #2875 (epic #2866 Phase 6): durable on-disk staging for USER_OWNED_ARTIFACTS
@@ -1639,14 +1645,13 @@ const claudeToOpencodeTools = {
 const claudeToAntigravityTools = {
   // #4705: Antigravity-NATIVE tool names (see src/runtime-artifact-conversion.cts)
   Read: 'view_file',
-  Write: 'write_file',
+  Write: 'write_to_file',
   Edit: 'replace_file_content',
   Bash: 'run_command',
-  Glob: 'glob',
+  Glob: 'find_by_name',
   Grep: 'grep_search',
-  WebSearch: 'google_web_search',
-  WebFetch: 'web_fetch',
-  TodoWrite: 'write_todos',
+  WebSearch: 'search_web',
+  WebFetch: 'read_url_content',
 }
 
 // Tool name mapping from Claude/GSD agents to Kimi CLI module paths.
@@ -1715,13 +1720,16 @@ function convertAntigravityToolName(claudeTool) {
   // built-in tool; the lowercase fallback would emit an invalid
   // 'skill'/'slashcommand' name that fails frontmatter validation
   // (tools.N: Invalid tool name) and aborts the entire agent load (#1394).
+  // TodoWrite: exclude — agy 1.3.5 registers no todo tool, and an unknown name
+  // stops the agent from starting (#5447).
   if (
     claudeTool === 'Task' ||
     claudeTool === 'Agent' ||
     claudeTool === 'AskUserQuestion' ||
     claudeTool === 'ask_user' ||
     claudeTool === 'Skill' ||
-    claudeTool === 'SlashCommand'
+    claudeTool === 'SlashCommand' ||
+    claudeTool === 'TodoWrite'
   ) {
     return null;
   }
@@ -2155,43 +2163,11 @@ function parseKimiAgentSource(source) {
   };
 }
 
+// #5447: the tools list is read by the compiled module's parser (quoted entries,
+// `#` comments, inline and block lists), the one the runtime pipeline uses, so this
+// copy of the Antigravity and Kimi converters cannot diverge from it.
 function parseFrontmatterTools(frontmatter) {
-  if (!frontmatter) return [];
-  const lines = frontmatter.split(/\r?\n/);
-  const tools = [];
-  let collecting = false;
-
-  for (const line of lines) {
-    const trimmed = line.trim();
-    if (!trimmed) continue;
-
-    if (collecting) {
-      if (trimmed.startsWith('- ')) {
-        tools.push(trimmed.slice(2).trim());
-        continue;
-      }
-      collecting = false;
-    }
-
-    if (trimmed === 'tools:' || trimmed === 'allowed-tools:') {
-      collecting = true;
-      continue;
-    }
-
-    if (trimmed.startsWith('tools:') || trimmed.startsWith('allowed-tools:')) {
-      const value = trimmed.slice(trimmed.indexOf(':') + 1).trim();
-      if (value) {
-        for (const tool of value.split(',')) {
-          const name = tool.trim();
-          if (name) tools.push(name);
-        }
-      } else {
-        collecting = true;
-      }
-    }
-  }
-
-  return tools;
+  return runtimeArtifactConversion.parseFrontmatterTools(frontmatter);
 }
 
 function addKimiAgentDiagnostic(diagnostics, code, message, value, source = null) {
@@ -2499,10 +2475,11 @@ function convertClaudeAgentToAntigravityAgent(content, isGlobal = false) {
   const name = extractFrontmatterField(frontmatter, 'name') || 'unknown';
   const description = extractFrontmatterField(frontmatter, 'description') || '';
   const color = extractFrontmatterField(frontmatter, 'color');
-  const toolsRaw = extractFrontmatterField(frontmatter, 'tools') || '';
 
-  // Map tools to Antigravity equivalents (reuse existing convertAntigravityToolName)
-  const claudeTools = toolsRaw.split(',').map(t => t.trim()).filter(Boolean);
+  // Map tools to Antigravity equivalents (reuse existing convertAntigravityToolName).
+  // parseFrontmatterTools reads both the inline comma list and the YAML block
+  // list (e.g. agents/gsd-security-auditor.md) (#5447).
+  const claudeTools = parseFrontmatterTools(frontmatter);
   const mappedTools = claudeTools.map(t => convertAntigravityToolName(t)).filter(Boolean);
 
   // #2876: quote description for the same reason as the skill variant.
@@ -3274,6 +3251,12 @@ function _stripCallArgument(spanText, matchStart, matchEnd, { consumeLeadingComm
  */
 function _projectRoleArgument(spanText, matchStart, matchEnd, roleValueExpr, toolConfig, canOrchestrate) {
   const { namedRoleParam, promptContentParam, structuralRoleParam, leafRoleValue } = toolConfig;
+  // #5569: a primitive that resolves the role prompt itself (Pi `gsd_dispatch`)
+  // takes the role name alone — no prompt-content argument, no structural role.
+  // The argument's own separator is left in place.
+  if (toolConfig.rolePromptResolution === 'tool') {
+    return spanText.slice(0, matchStart) + `${namedRoleParam}=${roleValueExpr}` + spanText.slice(matchEnd);
+  }
   const lineStart = spanText.lastIndexOf('\n', matchStart - 1) + 1;
   const startsOwnLine = /^[ \t]*$/.test(spanText.slice(lineStart, matchStart));
 
@@ -3405,6 +3388,20 @@ function _normalizeDispatchCallSpan(spanText, hasBraceWrapper, dispatch, toolCon
     }
   }
 
+  // 1b. #5569: a tool-resolved primitive (`rolePromptResolution: 'tool'`) takes
+  //     `role` + `task` only. The task text arrives as `prompt`, so the key is
+  //     renamed; `description` has no counterpart and is dropped.
+  if (toolConfig.rolePromptResolution === 'tool') {
+    const pm = /\bprompt(\s*[=:])/.exec(_maskStringsAndComments(text));
+    if (pm) {
+      text = text.slice(0, pm.index) + toolConfig.taskParam + text.slice(pm.index + 'prompt'.length);
+    }
+    const dm = _callArgValueRe('description').exec(_maskStringsAndComments(text));
+    if (dm) {
+      text = _stripCallArgument(text, dm.index, dm.index + dm[0].length);
+    }
+  }
+
   // 2. Per-call model argument (model= / model:) — stripped entirely when the
   //    target has no per-call model-selection parameter (there is no
   //    `dispatch` axis for this — it is inherent tool vocabulary, like the
@@ -3636,6 +3633,15 @@ function projectNamedDispatchToStructuralDelegate(content, dispatch, toolConfig)
     if (namedDispatch) {
       return `The \`${toolName}\` tool IS available in a top-level ${sessionName} session. Always dispatch ${rosterFlat} as separate \`${toolName}()\` calls.`;
     }
+    if (toolConfig.rolePromptResolution === 'tool') {
+      return (
+        `The \`${toolName}\` tool IS available in a top-level ${sessionName} session. It takes a \`${toolConfig.namedRoleParam}\` ` +
+        `(the installed gsd-* role name) and a \`${toolConfig.taskParam}\`, resolves the role prompt from the install itself, and ` +
+        'runs the role in an isolated child session; the child cannot dispatch further. FAIL CLOSED — surface the ' +
+        `tool's error and stop — if it reports the role unresolved; never execute the role inline as a substitute. ` +
+        `Always dispatch ${rosterFlat} as separate \`${toolName}\` calls.`
+      );
+    }
     return (
       `${sessionName} has no \`Agent\` tool. It exposes \`${toolName}\`, which dispatches by structural role — ` +
       'it has no concept of a named subagent identity. GSD projects each named gsd-* role onto this primitive ' +
@@ -3793,6 +3799,31 @@ function convertClaudeToHermesMarkdown(content, ctx) {
 
 // ── End Hermes converters ────────────────────────────────────────────────────
 
+// #5569: Pi projects host-neutral `Agent(...)` calls onto its `gsd_dispatch`
+// tool (pi/gsd.cjs). The tool resolves and verifies the role prompt itself, so
+// the projection only renames the arguments (`rolePromptResolution: 'tool'`).
+const PI_DISPATCH_TOOL_CONFIG = Object.freeze({
+  toolName: 'gsd_dispatch',
+  namedRoleParam: 'role',
+  taskParam: 'task',
+  promptContentParam: 'task',
+  structuralRoleParam: 'role',
+  leafRoleValue: 'leaf',
+  backgroundParam: 'background',
+  supportsPerCallModel: false,
+  rolePromptResolution: 'tool',
+});
+
+function convertClaudeToPiMarkdown(content, ctx) {
+  const runtime = (ctx && ctx.runtime) || 'pi';
+  const dispatch = _hostIntegrationDispatch(runtime);
+  const toolConfig = Object.assign({}, PI_DISPATCH_TOOL_CONFIG, {
+    availableRoles: _resolveAvailableGsdRoles(),
+    runtime,
+  });
+  return projectNamedDispatchToStructuralDelegate(content, dispatch, toolConfig);
+}
+
 function convertSlashCommandsToCodexSkillMentions(content) {
   // Colon-style /gsd: never appears as a filesystem path segment, so no boundary guard is needed (unlike the hyphen-style below).
   let converted = content.replace(/\/gsd:([a-z0-9-]+)/gi, (_, commandName) => {
@@ -4284,8 +4315,8 @@ function generateCodexAgentToml(agentName, agentContent, modelOverrides = null,
  *   - Returns immediately if skillsDir does not exist (fails open).
  *   - Only touches directories whose names start with "gsd-".
  *   - Skips user-owned dirs (gsd-dev-preferences) — their agents/ content is
- *     never modified, mirroring the same USER_OWNED_SKILL_DIRS guard used by
- *     installOpencodeFamilySkills.
+ *     never modified, by the same USER_OWNED_SKILL_DIRS guard
+ *     installOpencodeFamilySkills uses.
  *   - For each managed gsd-* dir, if agents/openai.yaml exists, deletes it.
  *   - If agents/ is now empty, removes the directory; if it still contains
  *     other files (e.g. user-added content), leaves it in place.
@@ -4295,15 +4326,17 @@ function generateCodexAgentToml(agentName, agentContent, modelOverrides = null,
  *
  * @param {string} skillsDir - Path to the skills/ directory (e.g. ~/.codex/skills)
  */
-function cleanupCodexSkillMetadataSidecars(skillsDir) {
+function cleanupCodexSkillMetadataSidecars(skillsDir, owns) {
   if (!fs.existsSync(skillsDir)) return;
-  // Mirror the user-owned list from installOpencodeFamilySkills (#2973).
-  // We MUST skip these dirs — their contents are user-generated and must
-  // never be modified by GSD's install path.
-  const _userOwnedSkillDirs = new Set(['gsd-dev-preferences']);
+  // USER_OWNED_SKILL_DIRS (#2973) is the engine's one list. We MUST skip these
+  // dirs — their contents are user-generated and must never be modified by
+  // GSD's install path.
   for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
     if (!entry.isDirectory() || !entry.name.startsWith('gsd-')) continue;
-    if (_userOwnedSkillDirs.has(entry.name)) continue; // preserve user content
+    if (USER_OWNED_SKILL_DIRS.includes(entry.name)) continue; // preserve user content
+    // #5161: install keeps gsd-* dirs GSD does not own; their files are not
+    // GSD's sidecars to clean.
+    if (owns && !owns(entry.name)) continue;
     const agentsSubdir = path.join(skillsDir, entry.name, 'agents');
     const sidecarPath = path.join(agentsSubdir, 'openai.yaml');
     try {
@@ -4337,21 +4370,27 @@ function cleanupCodexSkillMetadataSidecars(skillsDir) {
  *   - non-gsd-* dirs under .devin/skills/ (user-authored skills)
  *   - gsd-dev-preferences/ (user-owned per #2973)
  *   - any files (not dirs) under .devin/skills/
+ *   - with `owns` (#5161), any gsd-* dir GSD does not own, which is named by path
  *
  * @param {string} workspaceDir - workspace root (process.cwd() for local installs)
+ * @param {(name: string) => boolean} [owns] ownership predicate (createSkillDirOwnership)
  * @returns {number} count of removed legacy gsd-* skill directories
  */
-function cleanupWindsurfLegacyDevinSkills(workspaceDir) {
+function cleanupWindsurfLegacyDevinSkills(workspaceDir, owns) {
   const legacySkillsDir = path.join(workspaceDir, '.devin', 'skills');
   if (!fs.existsSync(legacySkillsDir)) return 0;
 
-  // Mirror the user-owned list from cleanupCodexSkillMetadataSidecars (#2973).
-  const _userOwnedSkillDirs = new Set(['gsd-dev-preferences']);
   let removed = 0;
 
-  for (const entry of fs.readdirSync(legacySkillsDir, { withFileTypes: true })) {
-    if (!entry.isDirectory() || !entry.name.startsWith('gsd-')) continue;
-    if (_userOwnedSkillDirs.has(entry.name)) continue;
+  // Decide ownership once, BEFORE deleting: the capability-marker leg reads the
+  // dir itself, so asking after a removal would report the removed dir as kept.
+  // USER_OWNED_SKILL_DIRS (#2973) dirs are never candidates.
+  const candidates = fs.readdirSync(legacySkillsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && entry.name.startsWith('gsd-') && !USER_OWNED_SKILL_DIRS.includes(entry.name));
+  const notOwned = owns ? candidates.filter((entry) => !owns(entry.name)).map((entry) => entry.name) : [];
+
+  for (const entry of candidates) {
+    if (notOwned.includes(entry.name)) continue;
 
     const dirToRemove = path.join(legacySkillsDir, entry.name);
     try {
@@ -4366,6 +4405,7 @@ function cleanupWindsurfLegacyDevinSkills(workspaceDir) {
       // Fail open — a single bad dir must not block the install.
     }
   }
+  _warnPreservedSkillDirs(legacySkillsDir, notOwned);
 
   // If .devin/skills/ is now empty, prune it. If .devin/ itself is then empty,
   // prune that too — leaves the workspace clean for the new .windsurf/ layout.
@@ -4392,20 +4432,29 @@ function cleanupWindsurfLegacyDevinSkills(workspaceDir) {
  * relocating skills to ~/.agents/skills) orphans the pre-move dirs at
  * ~/.codex/skills. Only managed `<prefix>*` dirs are touched; user-owned content
  * (non-prefixed dirs, gsd-dev-preferences, symlinks) is preserved. Fail-open.
+ *
+ * #5161: with `owns`, a `<prefix>*` dir is removed only when GSD owns it; any
+ * other is kept and named by path. Install passes it. Uninstall does not: it
+ * removes every `gsd-*` skill dir, at either location.
  * @param {string} oldSkillsDir absolute path to the pre-move skills location
  * @param {string} prefix managed skill-dir prefix (e.g. 'gsd-')
+ * @param {(name: string) => boolean} [owns] ownership predicate (createSkillDirOwnership)
  * @returns {number} count of stale dirs removed
  */
-function cleanupMovedSkillsOldLocation(oldSkillsDir, prefix) {
+function cleanupMovedSkillsOldLocation(oldSkillsDir, prefix, owns) {
   if (!fs.existsSync(oldSkillsDir)) return 0;
 
-  // Mirror the user-owned list from cleanupCodexSkillMetadataSidecars (#2973).
-  const _userOwnedSkillDirs = new Set(['gsd-dev-preferences']);
   let removed = 0;
 
-  for (const entry of fs.readdirSync(oldSkillsDir, { withFileTypes: true })) {
-    if (!entry.isDirectory() || !entry.name.startsWith(prefix)) continue;
-    if (_userOwnedSkillDirs.has(entry.name)) continue;
+  // Decide ownership once, BEFORE deleting: the capability-marker leg reads the
+  // dir itself, so asking after a removal would report the removed dir as kept.
+  // USER_OWNED_SKILL_DIRS (#2973) dirs are never candidates.
+  const candidates = fs.readdirSync(oldSkillsDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && entry.name.startsWith(prefix) && !USER_OWNED_SKILL_DIRS.includes(entry.name));
+  const notOwned = owns ? candidates.filter((entry) => !owns(entry.name)).map((entry) => entry.name) : [];
+
+  for (const entry of candidates) {
+    if (notOwned.includes(entry.name)) continue;
 
     const dirToRemove = path.join(oldSkillsDir, entry.name);
     try {
@@ -4420,6 +4469,7 @@ function cleanupMovedSkillsOldLocation(oldSkillsDir, prefix) {
       // Fail open — a single bad dir must not block install/uninstall.
     }
   }
+  _warnPreservedSkillDirs(oldSkillsDir, notOwned);
 
   // Prune the old skills dir if now empty — leaves the configHome clean.
   // Never remove a non-empty container (user may keep other content there).
@@ -6477,7 +6527,28 @@ function splitTopLevelKeys(content) {
   return { topLevel: content.trim(), rest: '' };
 }
 
+/**
+ * #5301: the path a config write must target. atomicWriteFileSync ends in a
+ * rename(2) onto its destination, which REPLACES a symlink at that path rather than
+ * writing through it, so a dotfiles-managed `config.toml -> ~/dotfiles/codex.toml`
+ * became a plain file and the user's copy never saw the merge. With
+ * GSD_ALLOW_SYMLINKED_DEST the symlink is intentional: resolve it and write the
+ * file it points at, leaving the link itself alone. Without the opt-in the path is
+ * returned unchanged (the install-root symlink guard refuses such a layout before
+ * any write), and so does a dangling link (the guard cannot resolve it), so only a
+ * link whose target exists reaches the resolution below.
+ */
+function resolveSymlinkWriteTarget(filePath) {
+  if (!isSymlinkedDestOptIn()) return filePath;
+  let stat;
+  try { stat = fs.lstatSync(filePath); } catch (_) { return filePath; }
+  if (!stat.isSymbolicLink()) return filePath;
+  try { return fs.realpathSync(filePath); } catch (_) { return filePath; }
+}
+
 function mergeCodexConfig(configPath, gsdBlock) {
+  // #5301: both write sites below land on the symlink's target, never replace the link.
+  configPath = resolveSymlinkWriteTarget(configPath);
   // Case 1: No config.toml — create fresh
   if (!fs.existsSync(configPath)) {
     atomicWriteFileSync(configPath, gsdBlock + '\n');
@@ -7033,7 +7104,7 @@ function recordDefaultsProvenance(gsdDir, runtime, defaults, setNow) {
 /** @returns {boolean} true when it removed or reverted something */
 function revertNonClaudeDefaults(runtime) {
   if (hostBehaviorsFor(runtime).nativeModelAliases || process.env.GSD_TEST_MODE) return false;
-  const gsdDir = path.join(os.homedir(), '.gsd');
+  const gsdDir = path.join(resolveGsdHome(), '.gsd'); // #5017: GSD_HOME-aware, like the loader
   const provPath = path.join(gsdDir, DEFAULTS_PROVENANCE_NAME);
   if (!fs.existsSync(provPath)) return false;
   let releaseLock = null;
@@ -7086,7 +7157,7 @@ function revertNonClaudeDefaults(runtime) {
  */
 function writeNonClaudeDefaults(runtime) {
   if (hostBehaviorsFor(runtime).nativeModelAliases || process.env.GSD_TEST_MODE) return;
-  const gsdDir = path.join(os.homedir(), '.gsd');
+  const gsdDir = path.join(resolveGsdHome(), '.gsd'); // #5017: GSD_HOME-aware, like the loader
   const defaultsPath = path.join(gsdDir, 'defaults.json');
   let releaseLock = null;
   try {
@@ -7690,6 +7761,23 @@ function convertClaudeToKiloFrontmatter(content, { isAgent = false, modelOverrid
 // combinedFamilyInstall path (installOpencodeFamilyArtifacts) instead of the
 // bespoke inline block that used to call this function.
 
+/**
+ * Count the gsd-* skill dirs in `skillsDir` for "Installed N skills" and the
+ * non-empty check that detects a failed install (#5161): the dirs GSD owns,
+ * plus any USER_OWNED_SKILL_DIRS entry present (gsd-dev-preferences), which
+ * both counted before #5161. A gsd-* dir the prune kept because GSD does not
+ * own it is not counted, so it can neither inflate the line nor stand in for
+ * an install that wrote nothing.
+ */
+function _countOwnedSkillDirs(runtime, configDir, skillsDir) {
+  // A verification count fails closed: an unreadable install source must not
+  // let a user's gsd-* dir stand in for an install that wrote nothing.
+  const owns = createSkillDirOwnership(runtime, configDir, skillsDir, 'gsd-', { includeManifest: false, includeWritten: true });
+  return fs.readdirSync(skillsDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && e.name.startsWith('gsd-') && (owns(e.name) || USER_OWNED_SKILL_DIRS.includes(e.name)))
+    .length;
+}
+
 function listCodexSkillNames(skillsDir, prefix = 'gsd-') {
   if (!fs.existsSync(skillsDir)) return [];
   const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
@@ -7921,6 +8009,10 @@ const RUNTIME_CONTENT_DISPATCH = {
       return content;
     },
   },
+  pi: {
+    // #5569: `Agent(...)` -> `gsd_dispatch(role=..., task=...)`.
+    md: (content, ctx) => convertClaudeToPiMarkdown(content, ctx),
+  },
   hermes: {
     // #2284: brand-swap alone left the false "Agent tool IS available"
     // assertion + literal `Agent(...)` call syntax installed verbatim — see
@@ -8040,6 +8132,8 @@ function copyWithPathReplacement(srcDir, destDir, pathPrefix, runtime, isCommand
       if (shouldCompose(srcPath)) {
         content = composeWorkflow(content, { sourcePath: srcPath });
       }
+      // #5637: the typed-text capture heredoc ends at a terminator the typed text cannot know.
+      content = stampInstalledContent(content);
 
       content = filterRuntimeNotesForTarget(content, runtime);
 
@@ -10158,7 +10252,16 @@ function writeManifest(configDir, runtime = DEFAULT_RUNTIME, options = {}) {
   if (!hostBehaviorsFor(runtime).skipCodexSkillsManifest && fs.existsSync(codexSkillsDir)) {
     // All runtimes (including Hermes post-#947) use the canonical 'gsd-' prefix.
     const skillListPrefix = 'gsd-';
+    // #5161: record only skill dirs GSD owns. A user's gsd-* dir the prune
+    // preserved must not enter the manifest, or the next install reads it back
+    // as GSD-owned and deletes it. includeManifest:false keeps the previous
+    // manifest from vouching for itself; manifestIfSourceUnresolved keeps an
+    // unreadable install source from dropping every GSD skill from the manifest
+    // by carrying the previous manifest's entries forward instead of recording
+    // every gsd-* dir present.
+    const ownsSkillDir = createSkillDirOwnership(runtime, configDir, codexSkillsDir, skillListPrefix, { includeManifest: false, manifestIfSourceUnresolved: true, includeWritten: true });
     for (const skillName of listCodexSkillNames(codexSkillsDir, skillListPrefix)) {
+      if (!ownsSkillDir(skillName) && !USER_OWNED_SKILL_DIRS.includes(skillName)) continue;
       const skillRoot = path.join(codexSkillsDir, skillName);
       const skillHashes = generateManifest(skillRoot);
       for (const [rel, hash] of Object.entries(skillHashes)) {
@@ -10747,7 +10850,8 @@ function reportLocalPatches(configDir, runtime = DEFAULT_RUNTIME) {
   if (meta.files && meta.files.length > 0) {
     const reapplyCommand = hostBehaviorsFor(runtime).reapplyCommand || '/gsd-update --reapply';
     console.log('');
-    console.log('  ' + yellow + 'Local patches detected' + reset + ' (from v' + meta.from_version + '):');
+    const fromLabel = meta.from_version ? ' (from v' + meta.from_version + ')' : ' (from a first install)';
+    console.log('  ' + yellow + 'Local patches detected' + reset + fromLabel + ':');
     for (const f of meta.files) {
       console.log('     ' + cyan + f + reset);
     }
@@ -10760,6 +10864,114 @@ function reportLocalPatches(configDir, runtime = DEFAULT_RUNTIME) {
   return meta.files || [];
 }
 
+/**
+ * #5522: the first-time baseline reports a user's `skills/gsd-<stem>/SKILL.md` as preserved, but the
+ * skills writer owns a dir by its first-party name and replaces it. Before the writers run, set aside a copy of
+ * every baseline-preserved file in the shipped-name namespaces (bounded to BASELINE_SNAPSHOT_MAX_BYTES) in
+ * gsd-migration-backups/ — an installer-internal dir, so it can never collide with a user's existing
+ * gsd-local-patches/ content — so the user's content is on disk before anything can replace it.
+ * backUpReplacedBaselineFiles then moves the copies of replaced files into gsd-local-patches/.
+ * Returns Map<relPath, { fullPath, content, stagedPath }>.
+ */
+const BASELINE_SNAPSHOT_MAX_BYTES = 1024 * 1024;
+const BASELINE_SNAPSHOT_DIR = path.join('gsd-migration-backups', 'first-install-5522');
+const SHIPPED_NAME_NAMESPACE = /^(skills|commands?)\/gsd([-/]|$)/;
+function snapshotBaselinePreservedFiles(configDir, migrationResult) {
+  const snapshots = new Map();
+  const plan = migrationResult && migrationResult.plan;
+  const actions = plan && Array.isArray(plan.actions) ? plan.actions : [];
+  const stagingDir = path.join(configDir, BASELINE_SNAPSHOT_DIR);
+  for (const action of actions) {
+    if (!action || action.type !== 'baseline-preserve-user' || typeof action.relPath !== 'string') continue;
+    const ref = resolveInstallRelativePath(configDir, action.relPath);
+    if (!ref || !SHIPPED_NAME_NAMESPACE.test(ref.relPath)) continue;
+    try {
+      const st = fs.lstatSync(ref.fullPath);
+      if (!st.isFile()) continue;
+      if (st.size > BASELINE_SNAPSHOT_MAX_BYTES) {
+        console.warn(`  ${yellow}⚠${reset}  ${action.relPath} is larger than ${BASELINE_SNAPSHOT_MAX_BYTES} bytes, so it is not copied aside; if the install replaces it, the original is not kept`);
+        continue;
+      }
+      const content = fs.readFileSync(ref.fullPath);
+      const stagedRef = resolveInstallRelativePath(stagingDir, ref.relPath);
+      if (!stagedRef) continue;
+      fs.mkdirSync(path.dirname(stagedRef.fullPath), { recursive: true });
+      fs.writeFileSync(stagedRef.fullPath, content);
+      snapshots.set(ref.relPath, { fullPath: ref.fullPath, content, stagedPath: stagedRef.fullPath });
+    } catch (err) {
+      console.warn(`  ${yellow}⚠${reset}  Could not set aside ${action.relPath} before install (${err.message}); if the install replaces it, the original is not kept`);
+    }
+  }
+  return snapshots;
+}
+
+/**
+ * #5522: after the artifact writers ran, a snapshotted file that is gone or different was replaced. Its
+ * pre-install copy moves into gsd-local-patches/ (next to, never over, an existing backup) and is recorded in
+ * backup-meta.json, so the standard "Local patches detected" report names it as it does on the update path.
+ * The staging dir is always removed. Never throws: bookkeeping must not abort the install.
+ * Returns [{ relPath, backupRel }] for the files kept.
+ */
+function backUpReplacedBaselineFiles(configDir, snapshots) {
+  const replaced = [];
+  const patchesDir = path.join(configDir, PATCHES_DIR_NAME);
+  for (const [relPath, snap] of snapshots) {
+    let current = null;
+    try { current = fs.readFileSync(snap.fullPath); } catch { current = null; }
+    if (current !== null && current.equals(snap.content)) continue;
+    try {
+      let backupRel = relPath;
+      if (fs.existsSync(path.join(patchesDir, backupRel))) backupRel = `${relPath}.first-install`;
+      const backupRef = resolveInstallRelativePath(patchesDir, backupRel);
+      if (!backupRef) throw new Error('backup path escapes the config dir');
+      fs.mkdirSync(path.dirname(backupRef.fullPath), { recursive: true });
+      fs.writeFileSync(backupRef.fullPath, snap.content);
+      replaced.push({ relPath, backupRel });
+    } catch (err) {
+      console.warn(`  ${yellow}⚠${reset}  Could not back up ${relPath} to ${PATCHES_DIR_NAME}/ (${err.message}); the original is kept in ${BASELINE_SNAPSHOT_DIR}/`);
+      return replaced;
+    }
+  }
+  if (replaced.length > 0) {
+    try {
+      const metaPath = path.join(patchesDir, 'backup-meta.json');
+      let meta = {};
+      try { meta = JSON.parse(fs.readFileSync(metaPath, 'utf8')) || {}; } catch { meta = {}; }
+      const files = Array.from(new Set([...(Array.isArray(meta.files) ? meta.files : []), ...replaced.map((r) => r.backupRel)]));
+      fs.writeFileSync(metaPath, JSON.stringify({
+        ...meta,
+        backed_up_at: new Date().toISOString(),
+        from_version: meta.from_version ?? null,
+        files,
+        pristine_hashes: { ...(meta.pristine_hashes || {}) },
+      }, null, 2));
+    } catch (err) {
+      console.warn(`  ${yellow}⚠${reset}  Could not record ${PATCHES_DIR_NAME}/backup-meta.json (${err.message}); your copies are in ${PATCHES_DIR_NAME}/`);
+    }
+  }
+  try { fs.rmSync(path.join(configDir, BASELINE_SNAPSHOT_DIR), { recursive: true, force: true }); } catch { /* leftover is harmless */ }
+  return replaced;
+}
+
+/** relPaths in the snapshot whose name is a shipped skill/command the writers will lay down (#5522). */
+function predictShippedNameReplacements(snapshots, skillsManifest) {
+  const out = [];
+  for (const relPath of snapshots.keys()) {
+    const m = /^skills\/gsd-([^/]+)\//.exec(relPath) || /^commands?\/gsd\/([^/]+?)\.md$/.exec(relPath);
+    if (m && skillsManifest.has(m[1])) out.push(relPath);
+  }
+  return out;
+}
+
+/** A copy of the migration result without the baseline-preserve rows for paths the install replaced (#5522). */
+function withoutReplacedBaselineFiles(migrationResult, replaced) {
+  if (!replaced || replaced.length === 0 || !migrationResult || !migrationResult.plan) return migrationResult;
+  const norm = (p) => String(p).replace(/\\/g, '/').replace(/^\/+/, '');
+  const gone = new Set(replaced.map((r) => norm(r.relPath)));
+  const actions = (migrationResult.plan.actions || []).filter((a) => !(a && a.type === 'baseline-preserve-user' && gone.has(norm(a.relPath))));
+  return { ...migrationResult, plan: { ...migrationResult.plan, actions } };
+}
+
 function reportInstallerMigrationResult(result) {
   const summary = summarizeInstallerMigrationResult(result);
   if (!summary.hasReportableActions) return;
@@ -10893,6 +11105,20 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
       ? process.cwd()
       : path.join(process.cwd(), dirName);
 
+  // #5637: this install's typed-text heredoc terminator: the directory's existing nonce on a
+  // reinstall (so it changes nothing), a fresh one otherwise.
+  if (process.env.GSD_ARGS_NONCE_OFF !== '1') {
+    // Only a global install reuses its nonce; a project-local dir may be a committed clone.
+    armArgsNonce(targetDir, isGlobal);
+  } else {
+    disarmArgsNonce();
+    console.warn('  GSD_ARGS_NONCE_OFF=1: the typed-text heredoc terminator is NOT randomized in this install.');
+  }
+
+  // #5161: this install's record of the skill dirs it writes starts empty,
+  // whichever install path it takes.
+  installEngine.clearWrittenSkillDirs();
+
   // #3664: a --config-dir destination holding foreign agent files gets an
   // explicit install-time warning — never a silent Claude-shaped emit.
   if (isGlobal) {
@@ -10962,8 +11188,9 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
   const _isCoreProfileAlias = _activeProfileName === 'core';
   const _effectiveInstallMode = _isCoreProfileAlias ? 'minimal' : 'full';
   // Load the manifest and compute resolved profile for named profiles.
-  // For --minimal/core: use an empty manifest (core profile has no transitive
-  // deps) to produce a resolvedProfile with the core skill set.  For core/
+  // For --minimal/core: use an empty manifest for the SKILL closure (core profile has no
+  // transitive skill deps) to produce a resolvedProfile with the core skill set; agents
+  // come from the full manifest (#5503, see below).  For core/
   // standard profiles, resolveProfile's `registry` arg IS consulted (via
   // _capabilitySkillsForMode) so tier:core/tier:standard capability skills are
   // unioned in when registered. #2322 correction: for the DEFAULT `full`
@@ -10976,10 +11203,15 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
   // is passed so an INSTALLED third-party capability (not just a first-party
   // one) is honored on every profile, `full` included (#2322 blocker 2).
   const _commandsDir = path.join(src, 'commands', 'gsd');
-  const _skillsManifest = _isCoreProfileAlias ? new Map() : loadSkillsManifest(_commandsDir);
+  // #5503: the empty manifest only keeps core's SKILL set at the eight core skills (no
+  // `requires:` closure). The agents those skills spawn are still derived from the real
+  // manifest, so a core install can run /gsd-plan-phase and friends.
+  const _fullSkillsManifest = loadSkillsManifest(_commandsDir);
+  const _skillsManifest = _isCoreProfileAlias ? new Map() : _fullSkillsManifest;
   let _resolvedProfile = resolveProfile({
     modes: [_activeProfileName],
     manifest: _skillsManifest,
+    agentManifest: _fullSkillsManifest,
     registry: _installedCapabilityRegistry,
   });
   // Unified staging function: all profiles use stageSkillsForProfile with the
@@ -10988,9 +11220,13 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
     return stageSkillsForProfile(commandsGsdDir, _resolvedProfile);
   }
   function _stageAgents(agentsDir) {
-    if (_isCoreProfileAlias) return agentsDir;
+    // #5503: no core-alias shortcut — Codex gets the same profile-filtered agents as every runtime.
     return stageAgentsForProfile(agentsDir, _resolvedProfile);
   }
+  // #5503: Codex registers agent roles in config.toml. That used to be gated on "minimal mode"
+  // because minimal staged no agents; gate it on whether the resolved profile stages any.
+  const _codexAgentRolesEnabled = () =>
+    !isMinimalMode(_effectiveInstallMode) || (_resolvedProfile.agents instanceof Set && _resolvedProfile.agents.size > 0);
   const persistActiveProfileMarker = () => {
     try {
       writeActiveProfile(targetDir, _activeProfileName);
@@ -11365,7 +11601,7 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
   // The full restoreCodexSnapshot() (defined inside the config block) additionally
   // handles config.toml and the staged hooks/ tree, which are not yet touched
   // at this point in the pipeline.
-  const _codexPreConfigRollback = !hostBehaviorsFor(runtime).tomlConfigInstall || isMinimalMode(_effectiveInstallMode) ? null : () => {
+  const _codexPreConfigRollback = !hostBehaviorsFor(runtime).tomlConfigInstall || !_codexAgentRolesEnabled() ? null : () => {
     rollbackInstallerMigrations();
     // skills/gsd-* — pass 1: restore snapshot entries (may be absent if deleted mid-install).
     const _earlySkillsDir = _resolveSkillsRootDir(runtime, targetDir, _installScopeId);
@@ -11467,6 +11703,8 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
   // scope (outside the try block below) so it is accessible in the settings section later.
   // Absent VERSION = fresh install; present VERSION = upgrade/re-install.
   const priorInstallExisted = fs.existsSync(path.join(targetDir, 'gsd-core', 'VERSION'));
+  // #5522: files the first-time baseline reported as preserved, snapshotted before the artifact writers run.
+  let baselinePreservedSnapshots = new Map();
   try {
   installerMigrationResult = runInstallerMigrations({
     configDir: targetDir,
@@ -11520,8 +11758,18 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
       };
     }
   }
-  reportInstallerMigrationResult(installerMigrationResult);
+  if (Array.isArray(installerMigrationResult.blocked) && installerMigrationResult.blocked.length > 0) {
+    reportInstallerMigrationResult(installerMigrationResult); // show what blocked before the assertion throws
+  }
   assertInstallerMigrationsUnblocked(installerMigrationResult);
+  baselinePreservedSnapshots = snapshotBaselinePreservedFiles(targetDir, installerMigrationResult);
+  // #5522: the migration report stays ahead of materialization, but a baseline-preserved file the skills
+  // writer is about to replace (its name is a shipped skill's) is not listed as preserved; the
+  // replacement is reported once the writers have run.
+  reportInstallerMigrationResult(withoutReplacedBaselineFiles(
+    installerMigrationResult,
+    predictShippedNameReplacements(baselinePreservedSnapshots, _fullSkillsManifest).map((relPath) => ({ relPath }))
+  ));
 
   // Artifact install dispatcher — routes to layout-driven path for all
   // skills-based runtimes (both full and minimal/core profiles); keeps
@@ -11687,7 +11935,16 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
     // in autocomplete. Cleaning them up fixes the duplication; SKILL.md alone is
     // sufficient for Codex discovery. User-owned dirs are never touched.
     if (hostBehaviorsFor(runtime).cleanupSkillSidecars) {
-      cleanupCodexSkillMetadataSidecars(_skillsRootDir);
+      // #5161: no includeWritten here, unlike the count and writeManifest. The
+      // record would add only skills staged from a command (a capability skill
+      // carries the marker, which this predicate already owns). The writer prunes
+      // each of those except gsd-dev-preferences and writes it fresh as a lone
+      // SKILL.md, so it holds no sidecar for this cleanup to remove, and the
+      // cleanup skips gsd-dev-preferences by name (USER_OWNED_SKILL_DIRS).
+      cleanupCodexSkillMetadataSidecars(
+        _skillsRootDir,
+        createSkillDirOwnership(runtime, targetDir, _skillsRootDir, 'gsd-', { includeManifest: false }),
+      );
     }
 
     // ADR-1239 split-home migration: when a runtime's skills kind moved to an
@@ -11695,10 +11952,16 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
     // managed gsd-* skill dirs at the old configDir-rooted location
     // (~/.codex/skills). Reinstalling here writes the new location but would
     // otherwise orphan the old one — clean up the stale gsd-* dirs.
+    // #5161: only the ones GSD owns; any other gsd-* dir is kept and named.
+    // The manifest leg stays off: codex records its skills under `skills/`
+    // whichever root they sit in, so a name the manifest recorded for the new
+    // home would otherwise claim a same-named user dir at this old root that
+    // GSD never wrote.
     {
       const _movedOldSkillsDir = _resolveMovedSkillsOldDir(runtime, targetDir, scope);
       if (_movedOldSkillsDir) {
-        const migrated = cleanupMovedSkillsOldLocation(_movedOldSkillsDir, 'gsd-');
+        const migrated = cleanupMovedSkillsOldLocation(_movedOldSkillsDir, 'gsd-',
+          createSkillDirOwnership(runtime, targetDir, _movedOldSkillsDir, 'gsd-', { includeManifest: false }));
         if (migrated > 0) {
           console.log(`  ${green}✓${reset} Migrated ${migrated} skill dir(s) off the legacy ${_movedOldSkillsDir} location`);
         }
@@ -11712,8 +11975,13 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
     // Descriptor-driven (ADR-1239 / #2100): folded from `isWindsurf` into
     // hostBehaviors.legacyDevinSkillsCleanup (windsurf is the only runtime that
     // declares it, so this is byte-parity).
+    // #5161: only the gsd-* dirs GSD owns. The local manifest describes
+    // .windsurf/, never .devin/, so the manifest leg stays off here: a name it
+    // records under one root says nothing about a same-named dir under another.
     if (hostBehaviorsFor(runtime).legacyDevinSkillsCleanup && !isGlobal) {
-      const removedCount = cleanupWindsurfLegacyDevinSkills(process.cwd());
+      const _devinSkillsDir = path.join(process.cwd(), '.devin', 'skills');
+      const removedCount = cleanupWindsurfLegacyDevinSkills(process.cwd(),
+        createSkillDirOwnership(runtime, targetDir, _devinSkillsDir, 'gsd-', { includeManifest: false }));
       if (removedCount > 0) {
         console.log(`  ${green}✓${reset} Removed ${removedCount} legacy .devin/skills/gsd-* dir(s) (pre-#1615 Windsurf layout)`);
       }
@@ -11729,8 +11997,7 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
       const hermesSkillsDir = path.join(targetDir, 'skills', 'gsd');
       if (fs.existsSync(hermesSkillsDir)) {
         // Hermes layout uses prefix: 'gsd-' (#947) — skill dirs have gsd-<stem> names
-        const count = fs.readdirSync(hermesSkillsDir, { withFileTypes: true })
-          .filter(e => e.isDirectory() && e.name.startsWith('gsd-')).length;
+        const count = _countOwnedSkillDirs(runtime, targetDir, hermesSkillsDir);
         if (count > 0) {
           console.log(`  ${green}✓${reset} Installed ${count} skills to skills/gsd/`);
         } else {
@@ -11743,8 +12010,7 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
       const skillsDir = path.join(targetDir, 'skills');
       const rootAgentPath = path.join(targetDir, 'agents', 'gsd.yaml');
       if (fs.existsSync(skillsDir)) {
-        const count = fs.readdirSync(skillsDir, { withFileTypes: true })
-          .filter(e => e.isDirectory() && e.name.startsWith('gsd-')).length;
+        const count = _countOwnedSkillDirs(runtime, targetDir, skillsDir);
         if (count > 0) {
           console.log(`  ${green}✓${reset} Installed ${count} Kimi skills to skills/`);
         } else {
@@ -11783,8 +12049,7 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
     } else {
       const skillsDir = _skillsRootDir;
       if (fs.existsSync(skillsDir)) {
-        const count = fs.readdirSync(skillsDir, { withFileTypes: true })
-          .filter(e => e.isDirectory() && e.name.startsWith('gsd-')).length;
+        const count = _countOwnedSkillDirs(runtime, targetDir, skillsDir);
         if (count > 0) {
           console.log(`  ${green}✓${reset} Installed ${count} skills to skills/`);
         } else {
@@ -11844,6 +12109,9 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
     // command/ directories), so writing flat gsd-<cmd>.md files here would be
     // dead weight the extension never reads. Skip the flat-commands fallback
     // entirely for pluginOnlyInstall runtimes.
+    // NOTE (#5547): pi now declares a skills artifactLayout, so it takes the
+    // `_isSkillsRuntime` branch above; this branch is reached only if that layout
+    // is ever emptied again.
     console.log(`  ${green}✓${reset} pi: /gsd registered via native extension (no declarative command files)`);
   } else {
     // Claude Code local: flat gsd-<cmd>.md layout — Claude Code registers
@@ -11920,28 +12188,40 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
       }
     }
 
-    // Clean up any stale skills/ from a previous local install
+    // Clean up any stale skills/ from a previous local install. #5161: only
+    // dirs GSD owns — .claude/skills/ is also where a project keeps its own
+    // skills, so a user's gsd-* dir there is preserved and named instead.
     const staleSkillsDir = path.join(targetDir, 'skills');
     if (fs.existsSync(staleSkillsDir)) {
-      const staleGsd = fs.readdirSync(staleSkillsDir, { withFileTypes: true })
-        .filter(e => e.isDirectory() && e.name.startsWith('gsd-'));
+      // Decide ownership once, BEFORE deleting: the capability-marker leg reads
+      // the dir itself, so asking again afterwards reports a deleted dir as kept.
+      // A symlink is never removed here (as before) but is named when unowned.
+      const ownsSkillDir = createSkillDirOwnership(runtime, targetDir, staleSkillsDir, 'gsd-');
+      const prefixed = fs.readdirSync(staleSkillsDir, { withFileTypes: true })
+        .filter(e => (e.isDirectory() || e.isSymbolicLink()) && e.name.startsWith('gsd-'))
+        .map(e => ({ name: e.name, isDir: e.isDirectory(), owned: ownsSkillDir(e.name) }));
+      // gsd-dev-preferences is user content even when an old manifest records
+      // it, and nothing here restores it (#2973), so it is never removed.
+      const staleGsd = prefixed.filter(e => e.isDir && e.owned && !USER_OWNED_SKILL_DIRS.includes(e.name));
       for (const e of staleGsd) {
         fs.rmSync(path.join(staleSkillsDir, e.name), { recursive: true });
       }
       if (staleGsd.length > 0) {
         console.log(`  ${green}✓${reset} Removed ${staleGsd.length} stale GSD skill(s) from skills/`);
       }
+      _warnPreservedSkillDirs(staleSkillsDir, prefixed.filter(e => !e.owned).map(e => e.name));
     }
   }
 
   // Native-extension/plugin staging for runtimes OUTSIDE the layout-driven
-  // _isSkillsRuntime branch above (ADR-1239 / #2102 Stage 1: pi). OpenCode/Kilo
+  // _isSkillsRuntime branch above (ADR-1239 / #2102 Stage 1). OpenCode/Kilo
   // already get their nativePlugin file from installOpencodeFamilyArtifacts
   // (called inside the _isSkillsRuntime branch, since both declare a non-empty
   // artifactLayout) — guard on `!_isSkillsRuntime` so this standalone call never
-  // double-stages their plugin file. A runtime like pi, whose artifactLayout is
-  // intentionally empty for both scopes (`_isSkillsRuntime` is false), still
-  // needs its declared hostBehaviors.nativePlugin file copied into targetDir.
+  // double-stages their plugin file. pi (#5547) now declares a skills layout, so
+  // its extension is staged by installRuntimeArtifacts' own native-plugin
+  // post-step; this standalone call remains for any runtime that declares a
+  // nativePlugin with an intentionally empty artifactLayout.
   if (!_isSkillsRuntime && hostBehaviorsFor(runtime).nativePlugin) {
     _installNativePluginIfDeclared(runtime, targetDir, hostBehaviorsFor(runtime), src);
   }
@@ -12024,10 +12304,10 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
   // here explicitly to cover them (install-engine.cts's own doc comment
   // explains why; a regression here was caught by the install-tree golden
   // fixture, tests/fixtures/install-tree/claude-local.json). It is a no-op
-  // for pi: its capability.json declares an EMPTY artifactLayout for both
-  // scopes (programmatic dispatch, no named-dispatch subagent toolkit, no
-  // host-read markdown surface), so the resolved layout has no `agents` kind
-  // to stage and the function returns `null` without writing anything.
+  // for pi: its capability.json declares a skills-only artifactLayout for both
+  // scopes (#5547; programmatic dispatch, no named-dispatch subagent toolkit),
+  // so the resolved layout has no `agents` kind to stage and the function
+  // returns `null` without writing anything.
   if (hostBehaviorsFor(runtime).pluginOnlyInstall) {
     console.log(`  ${green}✓${reset} pi: no subagent files (programmatic dispatch, no named-dispatch toolkit)`);
   } else if (_isSkillsRuntime) {
@@ -12063,7 +12343,7 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
   // advertising the old full agent surface even though the descriptor-driven
   // write above already skipped writing the .md files for a minimal-tier
   // resolvedProfile. Reuse the same helper that powers `--uninstall`.
-  if (isMinimalMode(_effectiveInstallMode) && hostBehaviorsFor(runtime).tomlConfigInstall) {
+  if (!_codexAgentRolesEnabled() && hostBehaviorsFor(runtime).tomlConfigInstall) {
     const codexConfigPath = path.join(targetDir, 'config.toml');
     if (fs.existsSync(codexConfigPath)) {
       const existing = fs.readFileSync(codexConfigPath, 'utf8');
@@ -12472,6 +12752,13 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
     }
   }
 
+  // #5522: keep the user's copy of any baseline-preserved file the writers replaced (the update path's
+  // gsd-local-patches/ backup), then report the migrations with those paths no longer listed as preserved.
+  const replacedBaselineFiles = backUpReplacedBaselineFiles(targetDir, baselinePreservedSnapshots);
+  for (const { relPath, backupRel } of replacedBaselineFiles) {
+    console.log(`  ${yellow}i${reset}  ${relPath} was replaced by the install (it has the name of a shipped GSD file) — your copy is backed up to ${PATCHES_DIR_NAME}/${backupRel}`);
+  }
+
   if (failures.length > 0) {
     console.error(`\n  ${yellow}Installation incomplete!${reset} Failed: ${failures.join(', ')}`);
     process.exit(1);
@@ -12565,10 +12852,56 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
           }
         }
       }
+      // #5123: the Copilot and Antigravity converters write their DEFAULT home
+      // into `@` includes and Kimi's prompt converter leaves a prose "GSD core/"
+      // path, none of which exist when the payload lives somewhere else. Point
+      // them at the real install root (the same `$HOME/…` / absolute prefix the
+      // other runtimes use). Global installs only: a local install resolves
+      // against its project, which the converters already handle.
+      const includeRetarget = hostBehaviorsFor(runtime);
+      if (isGlobal && (includeRetarget.defaultHomeIncludeRoot || includeRetarget.retargetsGsdCoreProsePath === true)) {
+        const includePrefix = runtimeArtifactConversion._computePathPrefix({
+          isGlobal: true,
+          isOpencode: false,
+          resolvedTarget: targetDir,
+          homeDir: os.homedir(),
+        });
+        for (const relPath of manifestFiles) {
+          const fileName = path.basename(relPath);
+          if (!(fileName.endsWith('.md') || fileName.endsWith('.toml'))) continue;
+          if (fileName === 'CHANGELOG.md') continue;
+          const retargetPath = path.join(targetDir, relPath);
+          let retargetContent;
+          try {
+            retargetContent = fs.readFileSync(retargetPath, 'utf8');
+          } catch (_retargetReadErr) {
+            continue; // inaccessible or missing — never fail the install over this pass
+          }
+          const retargeted = runtimeArtifactConversion.retargetInstalledIncludes(retargetContent, includeRetarget, includePrefix);
+          if (retargeted !== retargetContent) {
+            try {
+              fs.writeFileSync(retargetPath, retargeted);
+            } catch (_retargetWriteErr) {
+              continue;
+            }
+          }
+        }
+      }
       for (const relPath of manifestFiles) {
         const fileName = path.basename(relPath);
         if (!(fileName.endsWith('.md') || fileName.endsWith('.toml'))) continue;
         if (fileName === 'CHANGELOG.md') continue;
+        // #5547: the Runtime Surface corpus is the package's canonical source
+        // bytes, kept byte-identical so a refresh can restore them
+        // (tests/install-runtime-artifacts.test.cjs); the converted artifacts
+        // are what the host reads. Counting the source form as a "leak" made
+        // every skills-runtime install print a warning about files nothing reads.
+        // Windsurf is the exception: its workflow wrappers delegate to the
+        // path-rewritten bodies at gsd-core/commands/gsd/ (#1629), so there they
+        // ARE host-read artifacts and stay in the scan.
+        const posixRelPath = relPath.replace(/\\/g, '/');
+        if (!hostBehaviorsFor(runtime).installsCommandBodiesForWorkflowDelegation
+          && (posixRelPath.startsWith('gsd-core/commands/') || posixRelPath.startsWith('gsd-core/agents/'))) continue;
         const fullPath = path.join(targetDir, relPath);
         let content;
         try {
@@ -12631,9 +12964,10 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
   // #2695: this branch runs for BOTH `core` (minimal) and `full` profiles.
   // Hooks are lightweight infrastructure (update-check + context monitor), not the
   // "full agent surface" that `core` deliberately omits. The config.toml / agent
-  // generation below is still gated by its own inner `!isMinimalMode` guard, so
-  // `core` enters the branch to receive the hook-file copy + hooks.json wiring but
-  // does NOT get agent roles generated. Before #2695 the outer `!isMinimalMode`
+  // generation below is gated by its own inner `_codexAgentRolesEnabled()` guard (#5503:
+  // it used to be `!isMinimalMode`, which kept `core` from registering the agents its
+  // skills spawn), so `core` enters the branch to receive the hook-file copy + hooks.json
+  // wiring AND the agent roles its own skills spawn. Before #2695 the outer `!isMinimalMode`
   // here skipped the whole branch for `core`, so the registered parent hook pointed
   // at a worker/registry the same installer never delivered.
   if (plan.installSurface === 'codex-toml') {
@@ -12804,7 +13138,7 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
     };
 
     let agentCount = 0;
-    if (!isMinimalMode(_effectiveInstallMode)) {
+    if (_codexAgentRolesEnabled()) {
       // #2834: write ~/.gsd/defaults.json (resolve_model_ids + runtime) BEFORE generating
       // agent TOMLs — installCodexConfig reads defaults.json at generation time, so on a
       // clean first install the runtime-aware model resolver must already know the runtime.
@@ -12823,7 +13157,7 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
       // not include agents/gsd-*.toml because those files did not yet exist.
       writeManifest(targetDir, runtime, { mode: _effectiveInstallMode, scope: _installScopeId });
     } else {
-      console.log(`  ${dim}↳${reset} Skipping Codex agent config generation (minimal install)`);
+      console.log(`  ${dim}↳${reset} Skipping Codex agent config generation (${_resolvedProfile.name} profile stages no agents)`);
     }
 
     // Copy only the hook files that Codex actually registers via its hook configuration (#2153).
@@ -13022,7 +13356,8 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
       // existing config; the snapshot restore below is a second line of
       // defense if even the rename fails.
       try {
-        atomicWriteFileSync(configPath, configContent, 'utf-8');
+        // #5301: write through an opted-in symlink instead of replacing it.
+        atomicWriteFileSync(resolveSymlinkWriteTarget(configPath), configContent, 'utf-8');
       } catch (writeErr) {
         // #2760 CR4 finding 1 — write failure must be loud and fatal. Wrap
         // with a `post-write` prefix the outer catch recognises so install
@@ -13628,10 +13963,7 @@ function install(isGlobal, runtime = DEFAULT_RUNTIME, options = {}) {
   // bare basename so an unrelated user command that merely mentions the same
   // filename can't false-positive into GSD's validated set.
   configuredEntrypoints.push(
-    ...settingsEntrypoints.filter(entry => {
-      const hooksSegment = '/hooks/' + path.basename(entry.scriptPath);
-      return registeredHookCommands.some(command => command.includes(hooksSegment));
-    }),
+    ...selectConfiguredEntrypointsForValidation(settingsEntrypoints, registeredHookCommands),
   );
   const statuslineEntrypoints = settingsEntrypoints.filter(entry => entry.command === statuslineCommand);
   const updateBannerEntrypoints = settingsEntrypoints.filter(entry => entry.command === updateBannerCommand);
@@ -13727,6 +14059,25 @@ function describeEntrypointConsequence(invalidRuntime) {
   return 'not persisted: this runtime writes its config after this check';
 }
 
+// #5100: select which tracked entrypoints reach the validation gate. A named
+// export (see module.exports) so tests can drive the fresh-vs-upgrade split
+// directly; the install() call site is covered by a child-process test that
+// runs the installer with win32 emulated.
+function selectConfiguredEntrypointsForValidation(settingsEntrypoints, registeredHookCommands) {
+  return (settingsEntrypoints || []).filter(entry => {
+    // A command-less entry never produced a registered command, so the
+    // segment match below can never keep it — but it is exactly the
+    // unresolved-bash entry the gate must see (buildHookCommand pushes it
+    // without a `command` when no Git Bash is found). Exempt it: without this
+    // a fresh install silently drops it (gate passes) while an upgrade keeps
+    // it via the persisted command (gate fails) — same host, opposite
+    // verdicts. Surface it in both cases and let the gate decide loudly.
+    if (entry.command === undefined) return true;
+    const hooksSegment = '/hooks/' + path.basename(entry.scriptPath);
+    return registeredHookCommands.some(command => command.includes(hooksSegment));
+  });
+}
+
 function assertConfiguredEntrypoints(entries) {
   // #4249: some writers push the same (configPath, scriptPath) pair more than
   // once (e.g. Kimi's context-monitor hook registered under several events,
@@ -14913,6 +15264,8 @@ module.exports = {
     install,
     installAllRuntimes,
     uninstall,
+    // #5100 — installer entrypoint-selection seam, exported for direct tests
+    selectConfiguredEntrypointsForValidation,
     // #3023 — shared hook bundle directory name, descriptor-driven
     SHARED_HOOKS_DIR_DEFAULT,
     resolveSharedHooksDirName,
@@ -14978,6 +15331,8 @@ module.exports = {
     convertClaudeAgentToClineAgent,
     // #2284 — Hermes named-dispatch → delegate_task projection
     convertClaudeToHermesMarkdown,
+    convertClaudeToPiMarkdown,
+    PI_DISPATCH_TOOL_CONFIG,
     projectNamedDispatchToStructuralDelegate,
     _hostIntegrationDispatch,
     _resolveAvailableGsdRoles,